kctl-agent 0.2.0__py3-none-any.whl

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/__main__.py

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

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/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/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",
+            ],
+        }
+    )

kctl_agent/commands/eval_cmd.py

@@ -0,0 +1,116 @@
+"""`kctl-agent eval` — inspect and validate eval scenarios.
+
+Deliberately model-free. Running a routing eval needs a model; *validating* that
+scenarios are well-formed, assert something, and reference commands that actually
+exist does not — and that is the part CI can enforce on every push.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import Annotated
+
+import typer
+
+from ..evals import MIN_SCENARIOS, cli_of, load_scenarios, referenced_commands, results_are_stale
+from ..model import AssetKind
+from ..registry import discover
+from ._shared import _note, _ok, _warn, context, manifest_of
+
+app = typer.Typer(help="Inspect and validate eval scenarios.", no_args_is_help=True)
+
+
+def _skills(actx):  # type: ignore[no-untyped-def]
+    manifest = manifest_of(actx)
+    assert actx.root is not None
+    return [
+        a
+        for a in discover(actx.root, manifest, include_external=False)
+        if a.kind == AssetKind.SKILLS and a.path.is_dir()
+    ]
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    """Eval coverage per skill."""
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+
+    rows = []
+    for asset in _skills(actx):
+        scenarios = load_scenarios(asset.path)
+        stale = results_are_stale(actx.root, asset.name, asset.path)
+        rows.append(
+            {
+                "skill": asset.name,
+                "scenarios": len(scenarios),
+                "meets_minimum": len(scenarios) >= MIN_SCENARIOS,
+                "results": "stale" if stale else ("recorded" if stale is False else "none"),
+            }
+        )
+
+    if actx.json_mode:
+        out.raw_json(rows)
+        return
+
+    columns = [("skill", "cyan"), ("scenarios", "white"), ("min met", "dim"), ("results", "dim")]
+    out.table(
+        "Eval coverage",
+        columns,
+        [[r["skill"], str(r["scenarios"]), "yes" if r["meets_minimum"] else "no", r["results"]] for r in rows],
+    )
+    covered = sum(1 for r in rows if r["meets_minimum"])
+    _note(actx, f"{covered} of {len(rows)} skill(s) meet the {MIN_SCENARIOS}-scenario minimum")
+
+
+@app.command("validate")
+def validate_cmd(
+    ctx: typer.Context,
+    names: Annotated[list[str] | None, typer.Argument(help="Skill names. Omit for all.")] = None,
+) -> None:
+    """Check scenarios are well-formed and reference commands that exist.
+
+    Exits 1 on a broken scenario. This is the half of eval that needs no model, so
+    it is the half CI can run.
+    """
+    actx = context(ctx)
+    out = actx.output
+    wanted = set(names) if names else None
+    problems: list[dict[str, str]] = []
+    checked = 0
+
+    for asset in _skills(actx):
+        if wanted is not None and asset.name not in wanted:
+            continue
+        for scenario in load_scenarios(asset.path):
+            checked += 1
+            label = f"{asset.name}/{scenario.path.name}"
+            if scenario.error:
+                problems.append({"scenario": label, "problem": scenario.error})
+                continue
+            if not scenario.prompt.strip():
+                problems.append({"scenario": label, "problem": "no prompt"})
+            if not scenario.has_expectation:
+                problems.append({"scenario": label, "problem": "asserts nothing"})
+            if scenario.expect_skill and scenario.expect_skill != asset.name:
+                problems.append(
+                    {"scenario": label, "problem": f"expect_skill {scenario.expect_skill!r} is not this skill"}
+                )
+            for command in referenced_commands(scenario):
+                binary = cli_of(command)
+                if binary and shutil.which(binary) is None:
+                    problems.append({"scenario": label, "problem": f"expects {binary!r}, which is not installed"})
+
+    if actx.json_mode:
+        out.raw_json({"checked": checked, "problems": problems})
+    else:
+        for problem in problems:
+            _warn(actx, f"{problem['scenario']}: {problem['problem']}")
+        if problems:
+            _note(actx, f"\n{len(problems)} problem(s) across {checked} scenario(s)")
+        else:
+            _ok(actx, f"{checked} scenario(s) valid")
+
+    if problems:
+        raise typer.Exit(code=1)

kctl_agent/commands/knowledge_cmd.py

@@ -0,0 +1,93 @@
+"""`kctl-agent knowledge` — discover cross-cutting facts in one call."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ..knowledge import DEFAULT_MAX_AGE_DAYS, load_all, search
+from ..model import AssetKind
+from ._shared import _note, _warn, context, manifest_of, rel
+
+app = typer.Typer(help="Search and audit the knowledge layer.", no_args_is_help=True)
+
+
+def _base(actx):  # type: ignore[no-untyped-def]
+    manifest = manifest_of(actx)
+    assert actx.root is not None
+    return actx.root / manifest.root_for(AssetKind.KNOWLEDGE)
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    """List every knowledge entry with its freshness."""
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+    entries = load_all(_base(actx))
+
+    if actx.json_mode:
+        out.raw_json(
+            [
+                {
+                    "name": e.name,
+                    "title": e.title,
+                    "updated": e.updated,
+                    "source": e.source,
+                    "age_days": e.age_days(),
+                    "stale": e.stale(),
+                    "path": str(e.path),
+                }
+                for e in entries
+            ]
+        )
+        return
+
+    columns = [("name", "cyan"), ("title", "white"), ("updated", "dim"), ("age", "dim"), ("source", "dim")]
+    rows = [
+        [e.name, e.title, e.updated or "-", str(e.age_days() if e.age_days() is not None else "-"), e.source or "-"]
+        for e in entries
+    ]
+    out.table("Knowledge", columns, rows)
+    stale = [e for e in entries if e.stale()]
+    if stale:
+        _warn(actx, f"{len(stale)} entry/entries older than {DEFAULT_MAX_AGE_DAYS} days")
+    _note(actx, f"{len(entries)} entry/entries")
+
+
+@app.command("search")
+def search_cmd(
+    ctx: typer.Context,
+    query: Annotated[str, typer.Argument(help="Substring to look for.")],
+    limit: Annotated[int, typer.Option("--limit", help="Maximum hits.")] = 10,
+) -> None:
+    """Find the entry that answers a question, without reading the whole tree."""
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+    hits = search(load_all(_base(actx)), query, limit=limit)
+
+    if actx.json_mode:
+        out.raw_json([{"name": e.name, "path": str(e.path), "context": ctxline} for e, ctxline in hits])
+        return
+
+    for entry, line in hits:
+        _note(actx, f"{entry.name:<28} {rel(entry.path, actx.root)}")
+        _note(actx, f"    {line}")
+    _note(actx, f"\n{len(hits)} hit(s)")
+
+
+@app.command("show")
+def show_cmd(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Entry name (filename without .md).")],
+) -> None:
+    """Print one knowledge entry."""
+    actx = context(ctx)
+    out = actx.output
+    entry = next((e for e in load_all(_base(actx)) if e.name == name), None)
+    if entry is None:
+        out.error(f"no knowledge entry named {name!r}")
+        raise typer.Exit(code=1)
+    typer.echo(entry.path.read_text(encoding="utf-8"))

kctl_agent/commands/lint_cmd.py

@@ -0,0 +1,77 @@
+"""`kctl-agent lint` — evaluate every asset rule family."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ..lint import has_errors, lint_all
+from ..rules.registry import SEVERITY_ERROR, all_rules
+from ._shared import _note, _ok, context, manifest_of
+
+app = typer.Typer(
+    help="Lint agent assets against the rule families.", no_args_is_help=False, invoke_without_command=True
+)
+
+
+@app.callback(invoke_without_command=True)
+def lint(
+    ctx: typer.Context,
+    names: Annotated[list[str] | None, typer.Argument(help="Asset names to lint. Omit for all.")] = None,
+    warnings_as_errors: Annotated[bool, typer.Option("--warnings-as-errors", help="Exit 1 on warnings too.")] = False,
+) -> None:
+    """Lint every asset. Exits 1 when any error-severity rule fires."""
+    if ctx.invoked_subcommand:
+        return
+    actx = context(ctx)
+    out = actx.output
+    assert actx.root is not None
+
+    findings = lint_all(actx.root, manifest_of(actx), names=list(names) if names else None)
+
+    if actx.json_mode:
+        out.raw_json(
+            [{"rule": f.rule_id, "location": f.location, "detail": f.detail, "severity": f.severity} for f in findings]
+        )
+    else:
+        for finding in findings:
+            line = f"{finding.severity:<5} {finding.rule_id:<10} {finding.location} — {finding.detail}"
+            _note(actx, line)
+        errors = sum(1 for f in findings if f.severity == SEVERITY_ERROR)
+        warns = len(findings) - errors
+        if findings:
+            _note(actx, f"\n{errors} error(s), {warns} warning(s)")
+        else:
+            _ok(actx, "no findings")
+
+    if has_errors(findings) or (warnings_as_errors and findings):
+        raise typer.Exit(code=1)
+
+
+@app.command("rules")
+def rules_cmd(ctx: typer.Context) -> None:
+    """List every registered rule."""
+    actx = context(ctx)
+    out = actx.output
+    registered = all_rules()
+
+    if actx.json_mode:
+        out.raw_json(
+            [
+                {
+                    "id": r.id,
+                    "severity": r.severity,
+                    "title": r.title,
+                    "rationale": r.rationale,
+                    "kinds": sorted(k.value for k in r.kinds) or ["repo"],
+                }
+                for r in registered
+            ]
+        )
+        return
+
+    columns = [("rule", "cyan"), ("sev", "white"), ("applies to", "dim"), ("title", "white")]
+    rows = [[r.id, r.severity, ", ".join(sorted(k.value for k in r.kinds)) or "repo", r.title] for r in registered]
+    out.table("Asset rules", columns, rows)
+    _note(actx, f"{len(registered)} rule(s)")