kctl-agent 0.2.0__tar.gz

kctl_agent-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Agent memory (claude-mem regenerates AGENTS.md locally; not a committed guide)
+AGENTS.md
+
+# kctl-agent container render output (derived from agents.toml)
+out/

kctl_agent-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: kctl-agent
+Version: 0.2.0
+Summary: Manifest, registry and reconciler for every agent asset in the Kodemeio workspace
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.14.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: eval
+Requires-Dist: anthropic>=0.40; extra == 'eval'

kctl_agent-0.2.0/README.md

@@ -0,0 +1,121 @@
+# kctl-agent
+
+The manifest, registry and reconciler for **every agent asset** in this workspace —
+skills, slash commands, subagents, hooks, MCP servers, rules and knowledge — first-party
+and third-party alike.
+
+`kctl-agent` succeeds `kctl-claude`, which promised to "manage local and remote Claude Code
+environments" but delegated `env`, `sync`, `setup`, `backup` and `verify` to five shell
+scripts in a repository that no longer exists. Those ten call sites are replaced here with
+real implementations, and the scope widens from one runtime to every runtime this workspace
+targets.
+
+See the design: [`docs/superpowers/specs/2026-09-05-agent-platform-design.md`](../../docs/superpowers/specs/2026-09-05-agent-platform-design.md).
+
+## The idea
+
+Your machine's agent state should be **derived**, not hand-maintained. `agents.toml`
+declares intent; `kctl-agent apply` makes `~/.claude`, `~/.agents` and a container render
+tree match it. A new laptop, a CI runner and a chat agent on a server all reconcile from
+the same file.
+
+First-party assets are **discovered** from the declared roots, never enumerated — a
+directory walk already knows the tree, and restating it would create a second source of
+truth that drifts. Only external assets are declared, because the tree cannot see them.
+
+## Install / run
+
+```bash
+uv sync --all-extras --all-packages
+uv run kctl-agent --help
+```
+
+Like `kctl-conform` and `kctl-skill`, this is a `kind = "meta"` developer tool: no service
+to talk to, no kctl config profile. Its `-p/--profile` names a **manifest** profile — which
+assets a given environment gets.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kctl-agent import [--write]` | Snapshot this machine into `agents.toml` + `agents.lock`. Dry-run by default. |
+| `kctl-agent registry [--kind K]` | Every asset this repo governs: first-party, vendored, external. |
+| `kctl-agent lock [--write]` | Resolve declared external assets and refresh `agents.lock`. |
+| `kctl-agent -p P plan [--prune]` | What `apply` would change. Always read-only. |
+| `kctl-agent -p P apply [--explain\|--adopt\|--force]` | Reconcile every target this profile names. |
+| `kctl-agent -p P diff` | Report drift. Exits 1 when anything differs. |
+| `kctl-agent doctor [--skip-network]` | Asset counts, MCP reachability, lock coverage, drift. |
+| `kctl-agent doctor ai-summary` | One-call JSON health summary for agents. |
+| `kctl-agent knowledge list\|search\|show` | The agent-facing knowledge layer. |
+
+## Getting started
+
+```bash
+kctl-agent import                 # see what is on this machine — writes nothing
+kctl-agent import --write         # create agents.toml and agents.lock
+kctl-agent registry               # what the repo now governs
+kctl-agent -p laptop plan         # what reconciling would change
+kctl-agent -p laptop apply        # make it so
+```
+
+## Safety
+
+Reconciliation is a **three-way merge**, never an overwrite. `~/.claude/.kctl-agent-state.json`
+records the hash of everything `kctl-agent` last wrote, and every apply compares
+*last-written · current-on-disk · desired*:
+
+| Situation | Outcome |
+|---|---|
+| absent | `create` |
+| matches the manifest | `ok` |
+| matches what we last wrote, manifest changed | `update` |
+| differs from what we last wrote | **`conflict` — apply stops** |
+| present but never written by us | **`conflict` — apply stops** |
+| adopted | `unmanaged` — the machine's version is kept |
+
+Two escape hatches, with different meanings:
+
+- `--adopt` keeps the machine's version and stops flagging it. Adoptions are recorded
+  distinctly from managed writes, so a later apply will not quietly overwrite them.
+  Adoption does **not** copy values back into the manifest; `import` does that, with review.
+- `--force` clears adoptions and overwrites. This is the only path on which `kctl-agent`
+  destroys local data, and it still takes the pre-apply backup first.
+
+Other invariants:
+
+- Nothing unmanaged is ever touched. A symlink resolving outside the repo is reported,
+  never removed.
+- `plan` and `--explain` never write.
+- The first apply tars every file it will touch into `~/.claude/backups/`.
+- `--prune` removes only links `kctl-agent` created.
+
+## Targets
+
+| Target | Renderer | Notes |
+|---|---|---|
+| `claude-code` | symlink + json-merge + plugin | `~/.claude/{skills,commands,agents}`, `settings.json`, `~/.claude.json#mcpServers` |
+| `codex` | symlink | `~/.agents/skills` — the cross-runtime convention |
+| `container` | copy | a real tree; Docker `COPY` cannot follow symlinks out of build context |
+
+## Hooks describe themselves
+
+A hook is a script that carries its own wiring, so the logic and the matcher cannot drift
+apart:
+
+```bash
+#!/usr/bin/env bash
+# kctl-agent:event = PreToolUse
+# kctl-agent:matcher = Edit|Write
+# kctl-agent:description = Ask before editing a sensitive file
+```
+
+`kctl-agent` merges these into `settings.json` as entries it owns, tagged so that foreign
+entries keep their position and are never dropped.
+
+## Testing
+
+```bash
+uv run pytest packages/kctl-agent/tests/ -v
+```
+
+Every test runs against a `tmp_path` home. Nothing touches the real `~/.claude`.

kctl_agent-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-agent"
+version = "0.2.0"
+description = "Manifest, registry and reconciler for every agent asset in the Kodemeio workspace"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.14.0",
+    "typer>=0.9.0",
+    "rich>=13.0",
+    "tomli-w>=1.0",
+]
+
+[project.optional-dependencies]
+eval = ["anthropic>=0.40"]
+
+[project.scripts]
+kctl-agent = "kctl_agent.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_agent"]
+
+[tool.kctl-conform]
+kind = "meta"
+# Rules genuinely N/A for a local reconciler with no external service:
+#   AFFORD-001 = --profile here selects a MANIFEST profile, not a kctl config
+#                profile, so the shared global-option check does not apply.
+#   AFFORD-004 = `doctor` reports local state; there is no service to probe.
+#   LAYOUT-006 = no core/client.py; the filesystem is the substrate.
+exempt = [
+    "AFFORD-001",
+    "AFFORD-004",
+    "LAYOUT-006",
+]

kctl_agent-0.2.0/src/kctl_agent/__init__.py

@@ -0,0 +1,5 @@
+"""kctl-agent — the manifest, registry and reconciler for agent assets."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

kctl_agent-0.2.0/src/kctl_agent/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

kctl_agent-0.2.0/src/kctl_agent/cli.py

@@ -0,0 +1,95 @@
+"""kctl-agent — the manifest, registry and reconciler for every agent asset."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from . import __version__
+from .commands import (
+    doctor_cmd,
+    eval_cmd,
+    knowledge_cmd,
+    lint_cmd,
+    manifest_cmd,
+    reconcile_cmd,
+    vendor_cmd,
+)
+from .core.callbacks import AppContext
+
+PROFILE_ENV = "KCTL_AGENT_PROFILE"
+HOME_ENV = "KCTL_AGENT_HOME"
+
+app = typer.Typer(
+    name="kctl-agent",
+    help="Declare, govern and reconcile every agent asset in this workspace.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-agent {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    profile: Annotated[
+        str,
+        typer.Option("--profile", "-p", help="Manifest profile: which assets this environment gets."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress non-essential output.")] = False,
+    output_format: Annotated[str, typer.Option("--format", "-f", help="pretty | json | csv | yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit table headers.")] = False,
+    home: Annotated[str, typer.Option("--home", help="Override the home directory (testing, containers).")] = "",
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = False,
+) -> None:
+    """Root callback: build the app context every command reads."""
+    home_raw = home or os.environ.get(HOME_ENV, "")
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        format="json" if json_output else output_format,
+        no_header=no_header,
+        profile=profile or os.environ.get(PROFILE_ENV, ""),
+        home=Path(home_raw).expanduser() if home_raw else Path.home(),
+    )
+
+
+app.add_typer(manifest_cmd.app, name="manifest")
+app.add_typer(reconcile_cmd.app, name="reconcile")
+app.add_typer(knowledge_cmd.app, name="knowledge")
+app.add_typer(doctor_cmd.app, name="doctor")
+app.add_typer(lint_cmd.app, name="lint")
+app.add_typer(vendor_cmd.app, name="vendor")
+app.add_typer(eval_cmd.app, name="eval")
+
+# The three verbs used constantly are also top-level, because
+# `kctl-agent plan` reads better than `kctl-agent reconcile plan`.
+app.command("plan")(reconcile_cmd.plan_cmd)
+app.command("apply")(reconcile_cmd.apply_cmd)
+app.command("diff")(reconcile_cmd.diff_cmd)
+app.command("import")(manifest_cmd.import_cmd)
+app.command("lock")(manifest_cmd.lock_cmd)
+app.command("registry")(manifest_cmd.registry_cmd)
+app.command("hoist")(manifest_cmd.hoist_cmd)
+
+# register_introspection_commands and cli_entrypoint must remain the last two
+# statements: introspection needs every command registered first, and
+# cli_entrypoint wraps the fully-assembled app for error handling.
+register_introspection_commands(app)
+app = cli_entrypoint(app)
+
+
+def _run() -> None:
+    app()

kctl_agent-0.2.0/src/kctl_agent/commands/_shared.py

@@ -0,0 +1,122 @@
+"""Helpers shared by the command groups: context access and consistent output."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+
+from ..core.callbacks import AppContext
+from ..core.config import find_repo_root
+from ..manifest import load_manifest
+from ..model import ACTION_CONFLICT, ACTION_OK, Manifest, Plan
+from ..reconcile import ReconcileRequest, resolve_profile
+
+PROFILE_ENV = "KCTL_AGENT_PROFILE"
+
+#: Console glyphs per action, so a plan reads at a glance.
+_GLYPH = {
+    "create": "+",
+    "update": "~",
+    "remove": "-",
+    "ok": "=",
+    "conflict": "!",
+    "unmanaged": "?",
+}
+
+
+def context(ctx: typer.Context) -> AppContext:
+    actx: AppContext = ctx.obj
+    if actx.root is None:
+        actx.root = find_repo_root()
+    return actx
+
+
+def manifest_of(actx: AppContext) -> Manifest:
+    assert actx.root is not None
+    return load_manifest(actx.root)
+
+
+def request(actx: AppContext, manifest: Manifest, prune: bool = False) -> ReconcileRequest:
+    assert actx.root is not None
+    name = actx.profile or os.environ.get(PROFILE_ENV, "")
+    return ReconcileRequest(
+        root=actx.root,
+        home=actx.home,
+        manifest=manifest,
+        profile=resolve_profile(manifest, name),
+        prune=prune,
+    )
+
+
+def note(actx: AppContext, message: str, level: str = "info") -> None:
+    """Human-readable line, suppressed under --json.
+
+    kctl_lib.Output.info/success/warn print to stdout regardless of json_mode, so
+    an unguarded call corrupts the JSON document a caller is trying to parse.
+    """
+    if actx.json_mode:
+        return
+    getattr(actx.output, level)(message)
+
+
+def print_plan(actx: AppContext, plan: Plan, show_ok: bool = False) -> None:
+    """Render a plan. Unchanged items are hidden unless asked for -- the signal is what moves."""
+    if actx.json_mode:
+        return
+    out = actx.output
+    rows = [a for a in plan.actions if show_ok or a.action != ACTION_OK]
+    for action in rows:
+        glyph = _GLYPH.get(action.action, " ")
+        out.info(f"{glyph} {action.action:<9} {action.target:<12} {action.path}")
+        out.info(f"             {action.detail}")
+    if not rows:
+        out.success("nothing to do — every target already matches the manifest")
+
+
+def plan_payload(plan: Plan) -> dict[str, object]:
+    return {
+        "counts": plan.counts(),
+        "actions": [
+            {
+                "action": a.action,
+                "target": a.target,
+                "renderer": a.renderer,
+                "path": str(a.path),
+                "detail": a.detail,
+                "state_key": a.state_key,
+            }
+            for a in plan.actions
+        ],
+    }
+
+
+def conflict_hint(plan: Plan) -> str | None:
+    count = sum(1 for a in plan.actions if a.action == ACTION_CONFLICT)
+    if not count:
+        return None
+    return (
+        f"{count} conflict(s): items changed outside kctl-agent. "
+        "Run `kctl-agent apply --adopt` to keep the machine's version, "
+        "or `--force` to overwrite."
+    )
+
+
+def rel(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _note(actx: AppContext, message: str) -> None:
+    note(actx, message, "info")
+
+
+def _ok(actx: AppContext, message: str) -> None:
+    note(actx, message, "success")
+
+
+def _warn(actx: AppContext, message: str) -> None:
+    note(actx, message, "warn")

kctl_agent-0.2.0/src/kctl_agent/commands/doctor_cmd.py

@@ -0,0 +1,146 @@
+"""`kctl-agent doctor` — is this workspace's agent tooling actually working?"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ..health import check_all, machine_env, missing_env
+from ..lockfile import load_lock
+from ..model import ACTION_CONFLICT, ACTION_OK, AssetKind
+from ..reconcile import build_plan
+from ..registry import discover
+from ._shared import _note, _ok, _warn, context, manifest_of, request
+
+app = typer.Typer(help="Diagnose the agent platform.", no_args_is_help=False, invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(
+    ctx: typer.Context,
+    timeout: Annotated[float, typer.Option("--timeout", help="Per-server health timeout, seconds.")] = 5.0,
+    skip_network: Annotated[bool, typer.Option("--skip-network", help="Do not probe MCP servers.")] = False,
+    deep: Annotated[
+        bool,
+        typer.Option("--deep", help="Launch each stdio server and complete an MCP handshake."),
+    ] = False,
+) -> None:
+    """Report asset counts, MCP reachability, lock coverage, and drift.
+
+    Without --deep a stdio server is only checked for a resolvable command, which
+    says nothing about whether it answers. --deep spawns each one, so it is opt-in.
+    """
+    if ctx.invoked_subcommand:
+        return
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+
+    manifest = manifest_of(actx)
+    assets = discover(actx.root, manifest)
+    lock = load_lock(actx.root)
+
+    counts: dict[str, int] = {}
+    for asset in assets:
+        counts[asset.kind.value] = counts.get(asset.kind.value, 0) + 1
+
+    health = (
+        []
+        if skip_network
+        else check_all(manifest.mcp, timeout=timeout, deep=deep, env_by_server=machine_env(actx.home))
+    )
+    failing = [h for h in health if h.failing]
+    warning = [h for h in health if h.warning]
+
+    absent_env = missing_env(manifest.mcp)
+    declared = len(manifest.marketplaces) + len(manifest.plugins) + len(manifest.skills) + len(manifest.mcp)
+    unlocked = max(declared - len(lock.entries), 0)
+
+    drift = 0
+    conflicts = 0
+    if actx.profile:
+        plan = build_plan(request(actx, manifest))
+        drift = sum(1 for a in plan.actions if a.action != ACTION_OK)
+        conflicts = sum(1 for a in plan.actions if a.action == ACTION_CONFLICT)
+
+    if actx.json_mode:
+        out.raw_json(
+            {
+                "assets": counts,
+                "assets_total": len(assets),
+                "external_declared": declared,
+                "lock_entries": len(lock.entries),
+                "unlocked": unlocked,
+                "mcp": [{"name": h.name, "status": h.status, "health": h.health, "detail": h.detail} for h in health],
+                "mcp_failing": len(failing),
+                "mcp_warning": len(warning),
+                "mcp_missing_env": absent_env,
+                "drift": drift,
+                "conflicts": conflicts,
+                "ok": not failing,
+            }
+        )
+    else:
+        columns = [("kind", "cyan"), ("count", "white")]
+        rows = [[kind.value, str(counts.get(kind.value, 0))] for kind in AssetKind]
+        out.table("Assets", columns, rows)
+
+        if health:
+            hcols = [("server", "cyan"), ("status", "white"), ("class", "dim"), ("detail", "dim")]
+            hrows = [[h.name, h.status, h.health, h.detail] for h in health]
+            out.table("MCP servers", hcols, hrows)
+
+        _note(actx, f"external declared: {declared}   lock entries: {len(lock.entries)}   unlocked: {unlocked}")
+        if actx.profile:
+            _note(actx, f"profile {actx.profile}: {drift} item(s) drifted, {conflicts} conflict(s)")
+        else:
+            _note(actx, "pass -p/--profile to include drift in this report")
+
+        for name, keys in sorted(absent_env.items()):
+            _warn(actx, f"MCP {name}: env not set — {', '.join(keys)}")
+        if failing:
+            out.error(f"{len(failing)} required MCP server(s) unreachable")
+        if warning:
+            _warn(actx, f"{len(warning)} optional MCP server(s) unreachable")
+        if not failing and not warning:
+            _ok(actx, "all declared MCP servers reachable")
+
+    if failing:
+        raise typer.Exit(code=1)
+
+
+@app.command("ai-summary")
+def ai_summary(ctx: typer.Context) -> None:
+    """One-call machine-readable health summary for agents."""
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+
+    manifest = manifest_of(actx)
+    assets = discover(actx.root, manifest)
+    health = check_all(manifest.mcp)
+    failing = [h.name for h in health if h.failing]
+    warning = [h.name for h in health if h.warning]
+
+    counts: dict[str, int] = {}
+    for asset in assets:
+        counts[asset.kind.value] = counts.get(asset.kind.value, 0) + 1
+
+    out.raw_json(
+        {
+            "workspace": manifest.workspace,
+            "assets": counts,
+            "assets_total": len(assets),
+            "profiles": sorted(manifest.profiles),
+            "targets": sorted(manifest.targets),
+            "mcp_failing": failing,
+            "mcp_warning": warning,
+            "healthy": not failing,
+            "next_commands": [
+                "kctl-agent registry --kind skills",
+                "kctl-agent -p laptop plan",
+                "kctl-agent doctor",
+            ],
+        }
+    )