# TKfA

Outils de *timekeeping* pour les agents : ils notent leur temps de travail
dans les tickets Gitea. Ce dépôt ne porte que l'outil : quand saisir, et sur
quel ticket, relève des consignes de chaque équipe.

## Récupérer l'outil

Le dépôt est public : un seul fichier, sans authentification. La dernière
version est sur `main` ; une version figée, sur son tag (`v1.0.0`…).

```
curl -fsSL -o temps-session.py \
  https://gitea.raggaroth-factory.fr/public/TKfA/raw/branch/main/outils/temps-session.py
# version figée : …/raw/tag/v1.0.0/outils/temps-session.py
python3 -I temps-session.py --version
```

Les évolutions de chaque version sont dans `CHANGELOG.md`.

## `outils/temps-session.py`

Calcule le temps actif d'une session Claude Code sur un ticket, prêt à saisir
sur Gitea. Il lit le transcript de la session (`~/.claude/projects/*/<session>.jsonl`
et ses sous-agents) et ne compte que le temps où l'agent travaille : l'attente
d'une réponse de l'humain n'est jamais comptée. Il retire ce qui est déjà
saisi sur le ticket : le relancer ne double rien.

Python 3.11 ou plus, sans dépendance. Il ne lit que le transcript et l'API
Gitea (GET). **Il n'écrit ni n'envoie rien** : il affiche une ligne JSON par
séance restant à saisir.

```
python3 -I outils/temps-session.py \
  --depot <organisation>/<dépôt> --ticket <n> --depuis <heure> [--jusqua <heure>]
```

- `--depuis` : l'heure où l'on a commencé le ticket (`date -Iseconds`).
- `--jusqua` : l'heure où l'on est passé à un autre ticket sans saisir ; sans
  elle, le travail fait sur l'autre serait compté sur celui-ci.
- L'instance Gitea et son jeton viennent de la configuration (voir
  *Configuration*) : **sans elle, l'outil n'interroge rien.**
- La session est `CLAUDE_CODE_SESSION_ID`. Hors de Claude Code (un humain),
  passer `--session <id>` : le nom du `.jsonl` de la session.

L'outil termine en affichant sur stderr l'adresse où saisir.

Options fines : `--pause` (trou non compté au sein d'un tour, 1800 s),
`--seance` (écart qui sépare deux séances, 3600 s). Voir `--help`.

## Configuration

Sans configuration, l'outil n'interroge aucune instance et s'arrête. Les
instances Gitea se décrivent dans un fichier TOML (modèle commenté :
`tkfa.exemple.toml`) :

```toml
defaut = "principale"

[instances.principale]
api = "https://gitea.example.org/api/v1"
jeton = "~/.config/tkfa/principale.jeton"   # chemin du fichier, jamais le jeton

[instances.agents]
api = "https://gitea.example.com/api/v1"
jeton_env = "GITEA_TOKEN_FILE"   # variable qui contient le chemin du fichier
```

- Le fichier : `--config <fichier>`, sinon `TKFA_CONFIG`, sinon
  `~/.config/tkfa/config.toml` s'il existe (`XDG_CONFIG_HOME` respecté).
- L'instance : `--instance <nom>`, sinon la clé `defaut`.
- Le jeton : `--jeton <fichier>`, sinon la clé `jeton` de l'instance (un
  chemin relatif se lit depuis le dossier du fichier), sinon le fichier que
  nomme la variable de sa clé `jeton_env`. Une variable ne sert que
  l'instance qui la nomme : le jeton d'une instance ne part pas vers une
  autre. Préférer `jeton` ou `jeton_env` à `--jeton` : le chemin d'un jeton
  en argument est refusé par certains garde-fous.
- L'`api` doit être en `https://`.

## Saisir

Chaque ligne affichée se saisit par un appel séparé, en-têtes passés par
stdin — **jamais le jeton dans la ligne de commande**, lisible par tous les
comptes de la machine (`/proc/<pid>/cmdline`) :

```
printf 'Authorization: token %s\nContent-Type: application/json\n' "$(cat <fichier du jeton>)" \
  | curl -s -X POST -H @- -d '<ligne>' <adresse affichée par l'outil>
```

Le jeton est celui de l'instance que l'outil a interrogée.

Si l'outil échoue, on le signale : on ne saisit jamais une durée estimée à
la main.

## Tests

Hors ligne (transcript fabriqué, Gitea simulé, configurations jetables) :

```
python3 -I tests/test-temps-session.py
```

## Licence

GPL v3, voir `LICENSE`.