kata-cli 0.9.2__tar.gz → 0.11.0__tar.gz

{kata_cli-0.9.2 → kata_cli-0.11.0}/.github/workflows/publish.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Build and publish each distribution to TestPyPI
         run: |
           set -euo pipefail
-          for pkg in antoine-cli kata-cli code-lens-cli; do
+          for pkg in antoine-cli kata-cli; do
             echo "::group::TestPyPI publish $pkg"
             # Run the per-package steps in a subshell so set -e failures
             # don't skip the ::endgroup:: marker — keeps Actions logs
@@ -81,7 +81,7 @@ jobs:
       - name: Print install commands
         if: always()
         run: |
-          for pkg in antoine-cli kata-cli code-lens-cli; do
+          for pkg in antoine-cli kata-cli; do
             echo "::notice::Test with: uv tool install --index-url https://test.pypi.org/simple/ --index-strategy unsafe-best-match $pkg==${DEV_VERSION}"
           done
 
@@ -105,7 +105,7 @@ jobs:
       - name: Build and publish each distribution
         run: |
           set -euo pipefail
-          for pkg in antoine-cli kata-cli code-lens-cli; do
+          for pkg in antoine-cli kata-cli; do
             echo "::group::Publishing $pkg"
             # Run the per-package steps in a subshell so set -e failures
             # don't skip the ::endgroup:: marker — keeps Actions logs

{kata_cli-0.9.2 → kata_cli-0.11.0}/.gitignore

@@ -232,3 +232,8 @@ experiments/scripts_eval/results/*
 
 # Claude Code per-machine scheduler lock
 .claude/scheduled_tasks.lock
+
+# kata-cli local store — everything under .antoine/ is local-only,
+# EXCEPT katas.toml which is the committed audit ledger.
+.antoine/*
+!.antoine/katas.toml

{kata_cli-0.9.2 → kata_cli-0.11.0}/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-05-17
+
+### Removed
+
+- `antoine.lookup` engine + `kata classify` / `kata grep` / `kata recent`
+  verbs — migrated to `code-lens-cli` v0.10.0.
+- `antoine.repo` engine + `python -m antoine.repo {profile,connections,graph}`
+  surface — migrated to `code-lens-cli` v0.10.0.
+- `.claude/skills/code-lookup/` and `.claude/skills/repo-map/` — re-homed
+  under `agentculture/code-lens-cli/.claude/skills/`.
+- 16 tests for the migrated surface (`test_ast_scope`, `test_classify*`,
+  `test_grep*`, `test_recent*`, `test_repo_*`).
+
+### Changed
+
+- `docs/skill-sources.md`: `code-lookup` and `repo-map` rows now point
+  at `code-lens-cli` as the upstream supplier; added "graduation"
+  precedent bullet to the vendoring policy.
+- `CLAUDE.md` "Dispatching subagents" table now names `code-lens`
+  verbs (soft dep — install with `uv tool install code-lens-cli`);
+  preserved as **evidence** of the first catalog this loop produced
+  rather than as a prescription antoine pushes downstream.
+- `README.md`: new "Results of this loop" section pointing at
+  `code-lens-cli`; corrected the alt-publish bullet to drop
+  `code-lens-cli` (which left the dual-publish loop in 0.10.0).
+
+### Migration
+
+- `kata classify .` → `code-lens classify .`
+- `kata grep <pattern> .` → `code-lens grep <pattern> .`
+- `kata recent .` → `code-lens recent .`
+- `python -m antoine.repo profile .` → `code-lens profile .`
+
+antoine continues to ship the capture/reduce/assess loop
+(`kata log {tail, gc, grep}` plus the forthcoming cells 2–8); the
+inspection verbs were extracted because they are the loop's *result*,
+not its mechanism. See <https://github.com/agentculture/code-lens-cli/issues/2>
+for handover history.
+
+## [0.10.0] - 2026-05-17
+
+### Added
+
+- `kata log {tail, gc, grep}` verbs for inspecting the local capture log
+  under `.antoine/log/`.
+- `antoine.kata.log` engine subpackage: `LogEntry` schema, daily-sharded
+  `LogStore`, `ArgsSidecar`, TTL `gc` with privacy invariant (args files
+  deleted first).
+- `.gitignore` rule: everything under `.antoine/` is local-only except
+  `katas.toml` (the future committed ledger; introduced in cell 4).
+- `docs/kata/log-schema.md` documenting the JSONL row format.
+
+This is **Cell 1** of the kata-cli capture/reduce/assess loop. See
+`docs/superpowers/specs/2026-05-17-kata-loop-design.md` for the full
+8-cell scope.
+
 ## [0.9.2] - 2026-05-17
 
 ### Changed

{kata_cli-0.9.2 → kata_cli-0.11.0}/CLAUDE.md

@@ -112,45 +112,31 @@ The harness gates the planned redesign of the `learn` / `explain` /
 brainstorm** — fed by the eval results, not by the harness's
 existence.
 
-## Dispatching subagents — inject code-lookup / repo-map directives
-
-This table applies in two places for **the conversational agent that loads
-this CLAUDE.md at session start** (i.e. you, the parent reading this now —
-not subagents you dispatch):
-
-1. **When you delegate** a task to a subagent (Explore, general-purpose,
-   Plan, etc.) whose task shape matches a row below: include the matching
-   directive **verbatim** in the subagent's prompt.
-2. **When you answer first-person** a task shape that matches a row below
-   without delegating: invoke the named verb yourself rather than
-   ad-hoc combinations of `ls` / `cat` / `grep` / `git` calls. The table
-   is one application of a broader rule: prefer a small purpose-built
-   script that returns structured high-value data in one call.
-
-| Task shape | Directive (verbatim if delegating; otherwise the verb to invoke yourself) |
+## Dispatching subagents — code-lens verbs (first catalog this loop produced)
+
+The four task shapes below have 1-call verbs in
+[`code-lens-cli`](https://github.com/agentculture/code-lens-cli) —
+the first published results catalog of running kata's
+capture/reduce/assess loop on a real codebase (this one). Install with
+`uv tool install code-lens-cli`. If installed, prefer the verb; if not,
+the loop will eventually re-surface the N-call pattern and the next
+catalog release will offer a replacement.
+
+This is the **evidence** view of code-lens-cli: it is what running the
+loop produces, not a dependency antoine prescribes downstream. The
+verbs lived under `antoine/lookup/` + `antoine/repo/` through 0.10.0;
+0.11.0 migrated them out (see [code-lens-cli#2](https://github.com/agentculture/code-lens-cli/issues/2)).
+
+| Task shape | Verb |
 |---|---|
-| "what changed in the last N commits / which functions or classes changed across commits" | `Use the code-lookup skill's recent verb (.claude/skills/code-lookup/scripts/recent.sh) for the commit + symbol-diff data. Do not call git log / git diff / git show directly for this question.` |
-| "where is `<pattern>` referenced / find usages with enclosing scope" | `Use the code-lookup skill's grep verb (.claude/skills/code-lookup/scripts/grep.sh <pattern>) for match + scope. Do not use raw rg / grep for this question.` |
-| "what kind of project is this — CLI? library? PyPI-published? dockerized?" | `Use the code-lookup skill's classify verb (.claude/skills/code-lookup/scripts/classify.sh).` |
-| "profile this repo / build-test story / repo overview / what fields does pyproject expose" | `Use the repo-map skill's profile verb (.claude/skills/repo-map/scripts/profile.sh).` |
-
-**Why this lives in CLAUDE.md and not in the skill descriptions:** round-2
-of the PR #18 organic-adoption smokes showed that **subagents construct
-their plan from the prompt body before consulting the skills catalog** —
-so a description-shape change on the skill itself does not move adoption
-(0 of 2 models picked up `antoine recent` for a question perfectly tuned for
-it). Round-3 confirmed the parent-agent path: a fresh session loading the
-table delegated *and the subagent invoked the verb directly via the
-injected directive*.
-
-**Scope of this rule — empirical:** the table directly governs the parent
-agent's behavior at delegation time and first-person execution time. It
-does **not** reliably propagate to subagents through CLAUDE.md alone —
-round-4 of the smokes (PR #18 commit `171980f`) showed a fresh subagent
-receiving the broadened table as ambient context still defaulted to `git
-log` via Bash (7 calls, no skill use) for a perfectly-shaped question.
-The lever for subagent adoption stays the prompt-body directive injection
-in row 1 above — the table does not change that.
+| "what changed in the last N commits / which functions or classes changed" | `code-lens recent .` |
+| "where is `<pattern>` referenced / find usages with enclosing scope" | `code-lens grep <pattern> .` |
+| "what kind of project is this — CLI? library? PyPI-published? dockerized?" | `code-lens classify .` |
+| "profile this repo / build-test story / repo overview" | `code-lens profile .` |
+
+Empirical adoption notes for this table (PR #18 round-2/3/4 smokes —
+why CLAUDE.md is the lever, not skill descriptions) moved with the
+verbs to code-lens-cli's CLAUDE.md.
 
 ## Workspace Context
 

{kata_cli-0.9.2 → kata_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kata-cli
-Version: 0.9.2
+Version: 0.11.0
 Summary: antoine — codebase lookup and indexing for agent skills (greenfield AgentCulture sibling).
 Project-URL: Homepage, https://github.com/agentculture/antoine
 Project-URL: Issues, https://github.com/agentculture/antoine/issues
@@ -41,16 +41,19 @@ actually worth the bet, and the recorded results from past rounds.
   placeholder stubs. See [`CLAUDE.md`](./CLAUDE.md) for build / test /
   architecture details.
 
-- **`kata-cli` (and `code-lens-cli`) — alt-published PyPI distributions**
-  carrying the same wheel content as `antoine-cli`. Installing any of the
-  three exposes the same pair of console scripts — `antoine` and `kata`
-  (see [`pyproject.toml`](./pyproject.toml)). The dispatching directives
-  baked into [`CLAUDE.md`](./CLAUDE.md) refer to **verbs** invoked via the
-  `kata` / `antoine` commands; `kata-cli` is the distribution label users
-  `pip install`, not a command they run. The dual-publish loop is defined
-  in [`.github/workflows/`](./.github/workflows/); see
+- **`kata-cli` — alt-published PyPI distribution** carrying the same
+  wheel content as `antoine-cli`. Installing either exposes the same
+  pair of console scripts — `antoine` and `kata`
+  (see [`pyproject.toml`](./pyproject.toml)). `kata-cli` is the
+  distribution label users `pip install`, not a command they run. The
+  dual-publish loop is defined in
+  [`.github/workflows/`](./.github/workflows/); see
   [`CHANGELOG.md`](./CHANGELOG.md) entries for v0.7.0 / v0.7.1 for the
-  history of how the three distribution names were wired up.
+  history of how the distribution names were wired up. (A third name,
+  `code-lens-cli`, was published from this repo through v0.9.2; from
+  v0.10.0 onward it lives in [its own
+  repo](https://github.com/agentculture/code-lens-cli) — see "Results
+  of this loop" below.)
 
 - **`experiments/scripts_eval/`** — the A/B-test harness for the
   `repo-map` skill (env-var-gated hooks, three-layer scoring, 5-repo
@@ -69,3 +72,18 @@ actually worth the bet, and the recorded results from past rounds.
   *before* consulting the skills catalog, which is why the dispatching
   table lives in the parent agent's instructions rather than in skill
   descriptions.
+
+## Results of this loop
+
+antoine ships the *tool*. The first published *catalog of results* from
+running its capture/reduce/assess loop is
+[`code-lens-cli`](https://github.com/agentculture/code-lens-cli) —
+four 1-call verbs (`classify` / `recent` / `grep` / `profile`) that
+antoine maintainers identified as recurring N-call patterns and
+packaged into a sibling distribution. Install with
+`uv tool install code-lens-cli`. Most agents will install both.
+
+The migration history (antoine 0.10.0 → code-lens-cli 0.10.0,
+2026-05-17) is the first concrete proof that the loop produces shippable
+artifacts. Future cells (2–8) of the loop are designed to make catalogs
+like this one routine rather than artisanal.

{kata_cli-0.9.2 → kata_cli-0.11.0}/README.md

@@ -23,16 +23,19 @@ actually worth the bet, and the recorded results from past rounds.
   placeholder stubs. See [`CLAUDE.md`](./CLAUDE.md) for build / test /
   architecture details.
 
-- **`kata-cli` (and `code-lens-cli`) — alt-published PyPI distributions**
-  carrying the same wheel content as `antoine-cli`. Installing any of the
-  three exposes the same pair of console scripts — `antoine` and `kata`
-  (see [`pyproject.toml`](./pyproject.toml)). The dispatching directives
-  baked into [`CLAUDE.md`](./CLAUDE.md) refer to **verbs** invoked via the
-  `kata` / `antoine` commands; `kata-cli` is the distribution label users
-  `pip install`, not a command they run. The dual-publish loop is defined
-  in [`.github/workflows/`](./.github/workflows/); see
+- **`kata-cli` — alt-published PyPI distribution** carrying the same
+  wheel content as `antoine-cli`. Installing either exposes the same
+  pair of console scripts — `antoine` and `kata`
+  (see [`pyproject.toml`](./pyproject.toml)). `kata-cli` is the
+  distribution label users `pip install`, not a command they run. The
+  dual-publish loop is defined in
+  [`.github/workflows/`](./.github/workflows/); see
   [`CHANGELOG.md`](./CHANGELOG.md) entries for v0.7.0 / v0.7.1 for the
-  history of how the three distribution names were wired up.
+  history of how the distribution names were wired up. (A third name,
+  `code-lens-cli`, was published from this repo through v0.9.2; from
+  v0.10.0 onward it lives in [its own
+  repo](https://github.com/agentculture/code-lens-cli) — see "Results
+  of this loop" below.)
 
 - **`experiments/scripts_eval/`** — the A/B-test harness for the
   `repo-map` skill (env-var-gated hooks, three-layer scoring, 5-repo
@@ -51,3 +54,18 @@ actually worth the bet, and the recorded results from past rounds.
   *before* consulting the skills catalog, which is why the dispatching
   table lives in the parent agent's instructions rather than in skill
   descriptions.
+
+## Results of this loop
+
+antoine ships the *tool*. The first published *catalog of results* from
+running its capture/reduce/assess loop is
+[`code-lens-cli`](https://github.com/agentculture/code-lens-cli) —
+four 1-call verbs (`classify` / `recent` / `grep` / `profile`) that
+antoine maintainers identified as recurring N-call patterns and
+packaged into a sibling distribution. Install with
+`uv tool install code-lens-cli`. Most agents will install both.
+
+The migration history (antoine 0.10.0 → code-lens-cli 0.10.0,
+2026-05-17) is the first concrete proof that the loop produces shippable
+artifacts. Future cells (2–8) of the loop are designed to make catalogs
+like this one routine rather than artisanal.

{kata_cli-0.9.2 → kata_cli-0.11.0}/antoine/cli/__init__.py

@@ -12,7 +12,7 @@ the raw argv (:func:`main` sets ``_AntoineArgumentParser._json_hint`` before
 ``parse_args``).
 """
 
-# pylint: disable=duplicate-code  # _dispatch mirrors antoine.repo.__main__ by design
+# pylint: disable=duplicate-code  # _dispatch keeps a deliberate pattern shared with sibling CLIs
 
 from __future__ import annotations
 
@@ -57,11 +57,9 @@ def _build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", parser_class=_AntoineArgumentParser)
 
     # pylint: disable=import-outside-toplevel
-    from antoine.cli._commands import classify as _classify_cmd
     from antoine.cli._commands import explain as _explain_cmd
-    from antoine.cli._commands import grep as _grep_cmd
     from antoine.cli._commands import learn as _learn_cmd
-    from antoine.cli._commands import recent as _recent_cmd
+    from antoine.cli._commands import log as _log_cmd
     from antoine.cli._commands import whoami as _whoami_cmd
 
     # pylint: enable=import-outside-toplevel
@@ -69,9 +67,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _learn_cmd.register(sub)
     _explain_cmd.register(sub)
     _whoami_cmd.register(sub)
-    _classify_cmd.register(sub)
-    _grep_cmd.register(sub)
-    _recent_cmd.register(sub)
+    _log_cmd.register(sub)
 
     return parser
 

kata_cli-0.11.0/antoine/cli/_commands/log.py

@@ -0,0 +1,129 @@
+"""`kata log` verb: parent + tail/gc/grep subcommands."""
+
+from __future__ import annotations
+
+import argparse
+from collections import deque
+
+from antoine.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, AntoineError
+from antoine.cli._output import emit_result
+from antoine.kata.log._gc import gc as _gc_run
+from antoine.kata.log._store import LogStore
+
+
+def _no_subcommand(args: argparse.Namespace) -> int:
+    args._parent_parser.print_help()
+    return 0
+
+
+def _handle_grep(args: argparse.Namespace) -> int:
+    store = LogStore()
+    if not store.root.exists() or not any(store.root.glob("*.jsonl")):
+        raise AntoineError(
+            code=EXIT_ENV_ERROR,
+            message="No capture data found in .antoine/log/. antoine has nothing to grep.",
+            remediation=(
+                "Run `kata learn` to see how to instrument your agent, "
+                "then start a session before grepping the log."
+            ),
+        )
+
+    needle = args.pattern
+    for entry in store.read_all():
+        haystack = " ".join(
+            v for v in (entry.tool, entry.bash_argv0 or "", entry.agent, entry.session) if v
+        )
+        if needle in haystack:
+            emit_result(entry.to_json_line().rstrip("\n"), json_mode=False)
+    return 0
+
+
+def _handle_tail(args: argparse.Namespace) -> int:
+    store = LogStore()
+    if not store.root.exists() or not any(store.root.glob("*.jsonl")):
+        raise AntoineError(
+            code=EXIT_ENV_ERROR,
+            message=(
+                "No capture data found in .antoine/log/. "
+                "antoine has no observed tool calls to display."
+            ),
+            remediation=(
+                "Run `kata learn` to see how to instrument your agent, "
+                "then start a session and try `kata log tail` again."
+            ),
+        )
+
+    n = max(1, int(args.n))
+    last = deque(store.read_all(), maxlen=n)
+    for entry in last:
+        emit_result(entry.to_json_line().rstrip("\n"), json_mode=False)
+    return 0
+
+
+def _handle_gc(args: argparse.Namespace) -> int:
+    if args.ttl_days < 0:
+        raise AntoineError(
+            code=EXIT_USER_ERROR,
+            message=(
+                f"--ttl-days must be >= 0 (got {args.ttl_days}). "
+                "A negative TTL would classify every log file as stale and "
+                "delete the entire log."
+            ),
+            remediation="Re-run with a non-negative value, e.g. `kata log gc --ttl-days 7`.",
+        )
+
+    store = LogStore()
+    if not store.root.exists():
+        message = "deleted 0 shape files, 0 args files (no log present)"
+    else:
+        try:
+            result = _gc_run(root=store.root, ttl_days=args.ttl_days)
+        except PermissionError as exc:
+            raise AntoineError(
+                code=EXIT_ENV_ERROR,
+                message=(
+                    f"GC could not delete files past TTL: {exc}. "
+                    "The privacy invariant requires expired data to be removed."
+                ),
+                remediation=(
+                    "Check filesystem permissions on .antoine/log/ "
+                    "(needs delete access for the user running antoine), then retry."
+                ),
+            ) from exc
+        message = (
+            f"deleted {len(result.deleted_shape)} shape files, "
+            f"{len(result.deleted_args)} args files"
+        )
+
+    emit_result(message, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "log",
+        help="raw access to the local capture log",
+        description="Inspect, prune, or search the local kata capture log under ./.antoine/log/.",
+    )
+    parser.set_defaults(func=_no_subcommand, _parent_parser=parser)
+    # Nested parsers MUST share the structured-error wrapper used by the top
+    # level — otherwise `kata log tail --bogus` exits 2 via default argparse,
+    # bypassing the "antoine never crashes" contract. (Qodo #25 bug 1.)
+    subsub = parser.add_subparsers(dest="log_command", parser_class=type(parser))
+
+    tail = subsub.add_parser("tail", help="print the last N captured entries")
+    tail.add_argument("-n", default=10, type=int, help="number of entries (default: 10)")
+    tail.set_defaults(func=_handle_tail)
+
+    gc_p = subsub.add_parser("gc", help="delete capture entries past TTL")
+    gc_p.add_argument(
+        "--ttl-days",
+        type=int,
+        default=7,
+        help="retention window in days (default: 7)",
+    )
+    gc_p.set_defaults(func=_handle_gc)
+
+    grep_p = subsub.add_parser("grep", help="filter log entries by substring")
+    grep_p.add_argument("pattern", help="substring matched against tool/bash_argv0/agent/session")
+    grep_p.set_defaults(func=_handle_grep)

kata_cli-0.11.0/antoine/kata/__init__.py

@@ -0,0 +1,5 @@
+"""antoine.kata — the capture/reduce/assess loop engine.
+
+See `docs/superpowers/specs/2026-05-17-kata-loop-design.md` for the design.
+This package is purely the engine; CLI verbs live in `antoine.cli._commands`.
+"""

kata_cli-0.11.0/antoine/kata/log/__init__.py

@@ -0,0 +1,11 @@
+"""Log subsystem: JSONL schema, on-disk store, TTL gc.
+
+Layout (under the current working directory):
+
+  .antoine/log/<YYYY-MM-DD>.jsonl    shape index, one line per tool call
+  .antoine/log/args/<session>.jsonl  raw args sidecar, keyed by row index
+
+The shape index is what `suggest`/`assess` read. The args sidecar holds
+raw, privacy-sensitive data and is the first thing the 7-day TTL pass
+deletes.
+"""

kata_cli-0.11.0/antoine/kata/log/_args.py

@@ -0,0 +1,63 @@
+"""ArgsSidecar — raw args kept separately from the shape index.
+
+This is the privacy-sensitive half of the log. TTL gc deletes this
+directory first; the shape index can be retained longer if the user wants
+aggregate stats without raw content.
+
+Files live at <root>/args/<session>.jsonl, one JSON object per line.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+# Whitelist: alphanumeric, dot, underscore, hyphen. No path separators,
+# no `..`, no whitespace. Keeps args/<session>.jsonl strictly flat so
+# `kata log gc`'s non-recursive `*.jsonl` scan can't miss a file (the
+# privacy invariant requires expired args to be deleted on schedule).
+# (Qodo #25 bug 2.)
+_SAFE_SESSION_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def _validate_session(session: str) -> str:
+    # `.` and `..` pass the char-class regex but are path-traversal refs.
+    if session in {".", ".."} or not _SAFE_SESSION_RE.fullmatch(session):
+        raise ValueError(
+            f"unsafe session id {session!r}: must match [A-Za-z0-9._-]+ "
+            "and cannot be '.' or '..' (the args sidecar stays flat under "
+            "args/<session>.jsonl)"
+        )
+    return session
+
+
+class ArgsSidecar:
+    """Per-session JSONL store for raw tool args."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.args_dir = root / "args"
+
+    def _file_for(self, session: str) -> Path:
+        safe = _validate_session(session)
+        return self.args_dir / f"{safe}.jsonl"
+
+    def append(self, session: str, args: dict[str, Any]) -> None:
+        self.args_dir.mkdir(parents=True, exist_ok=True)
+        path = self._file_for(session)
+        with path.open("a", encoding="utf-8") as fp:
+            fp.write(json.dumps(args, ensure_ascii=False, separators=(",", ":")) + "\n")
+
+    def read(self, session: str) -> Iterator[dict[str, Any]]:
+        path = self._file_for(session)
+        if not path.exists():
+            return
+        with path.open("r", encoding="utf-8") as fp:
+            for raw in fp:
+                stripped = raw.strip()
+                if not stripped:
+                    continue
+                yield json.loads(stripped)

kata_cli-0.11.0/antoine/kata/log/_gc.py

@@ -0,0 +1,55 @@
+"""TTL gc — privacy invariant: if files past TTL exist, they MUST be deleted.
+
+The order is intentional: raw args first (privacy-sensitive), then the
+shape index. If any unlink raises ``PermissionError``, propagate it
+unchanged so the caller (the ``kata log gc`` verb handler) can translate
+it into an ``AntoineError`` with an actionable Fix line.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class GCResult:
+    deleted_shape: list[Path] = field(default_factory=list)
+    deleted_args: list[Path] = field(default_factory=list)
+
+
+def _stale_files(directory: Path, ttl_seconds: float, now: float) -> list[Path]:
+    if not directory.exists():
+        return []
+    out: list[Path] = []
+    for p in sorted(directory.glob("*.jsonl")):
+        if (now - p.stat().st_mtime) > ttl_seconds:
+            out.append(p)
+    return out
+
+
+def gc(*, root: Path, ttl_days: int) -> GCResult:
+    """Delete files older than ``ttl_days`` from ``root`` and ``root/args``.
+
+    Raises ``ValueError`` on negative ``ttl_days`` — a negative TTL would
+    classify every file as stale and wipe the whole log from a single typo,
+    which we treat as a programming error, not silently allowed input.
+    Raises ``PermissionError`` if any unlink fails — privacy invariant.
+    """
+    if ttl_days < 0:
+        raise ValueError(f"ttl_days must be >= 0 (got {ttl_days})")
+    now = time.time()
+    ttl_seconds = ttl_days * 86400.0
+
+    args_dir = root / "args"
+    stale_args = _stale_files(args_dir, ttl_seconds, now)
+    stale_shape = _stale_files(root, ttl_seconds, now)
+
+    # Args first — they hold the raw, privacy-sensitive data.
+    for path in stale_args:
+        path.unlink()
+    for path in stale_shape:
+        path.unlink()
+
+    return GCResult(deleted_shape=stale_shape, deleted_args=stale_args)

kata_cli-0.11.0/antoine/kata/log/_schema.py

@@ -0,0 +1,62 @@
+"""LogEntry — the JSONL row written by an adapter per captured tool call.
+
+The schema is documented in:
+  docs/kata/log-schema.md  (added in a later task in this plan)
+
+This module is pure data + serialization; it owns no IO.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, fields
+from typing import Any
+
+_REQUIRED = ("ts", "session", "agent", "tool", "args_digest")
+
+
+@dataclass(frozen=True)
+class LogEntry:
+    """One captured tool call.
+
+    Required fields (always present): ts, session, agent, tool, args_digest.
+    Optional fields (None if the adapter could not provide them):
+    bash_argv0, tokens_in, tokens_out, duration_ms.
+    """
+
+    ts: str
+    session: str
+    agent: str
+    tool: str
+    args_digest: str
+    bash_argv0: str | None = None
+    tokens_in: int | None = None
+    tokens_out: int | None = None
+    duration_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.args_digest.startswith("sha256:"):
+            raise ValueError(
+                "args_digest must start with 'sha256:' " f"(got: {self.args_digest!r})"
+            )
+
+    def to_json_line(self) -> str:
+        """Return a single newline-terminated JSON object."""
+        payload = asdict(self)
+        return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+
+    @classmethod
+    def from_json_line(cls, line: str) -> "LogEntry":
+        """Parse one JSONL row. Raises ValueError on missing required fields.
+
+        Unknown fields in ``payload`` are silently dropped — adapters may emit
+        future-evolved schemas, and tolerating that keeps log ingestion working
+        instead of TypeError-ing through ``cls(**payload)``. Forward-compat is
+        part of the "antoine never crashes" contract.
+        """
+        payload: dict[str, Any] = json.loads(line)
+        for field_name in _REQUIRED:
+            if field_name not in payload:
+                raise ValueError(f"missing required field: {field_name!r}")
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in payload.items() if k in known})