kc-cli 0.4.0__py3-none-any.whl

kc/commands/conformance.py

@@ -0,0 +1,293 @@
+"""Read-only V1 CLI contract conformance checks."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import typer
+
+from kc.commands.common import run
+from kc.commands.guide import build_guide
+from kc.errors import ERROR_EXIT_MAP, KcError
+from kc.output import HUMAN_RENDERERS, emit_success, envelope
+
+PUBLIC_COMMAND_IDS = frozenset(
+    {
+        "guide",
+        "init",
+        "status",
+        "source.add",
+        "source.inspect",
+        "source.refresh",
+        "source.search",
+        "index.build",
+        "context.prepare",
+        "artifact.new",
+        "artifact.validate",
+        "artifact.diff",
+        "artifact.apply",
+        "citation.check",
+        "citation.rewrite",
+        "citation.repair",
+        "lint",
+        "task.start",
+        "task.status",
+        "task.inspect",
+        "task.next",
+        "task.resume",
+        "eval.run",
+        "export",
+        "doctor",
+        "doctor.locks",
+        "conformance",
+    }
+)
+
+REQUIRED_GUIDE_SECTIONS = frozenset(
+    {
+        "name",
+        "version",
+        "description",
+        "schema_version",
+        "compatibility",
+        "capabilities",
+        "bootstrap",
+        "global_options",
+        "output_formats",
+        "environment",
+        "commands",
+        "schemas",
+        "citation_syntax",
+        "workflows",
+        "anti_patterns",
+        "quality_rubric",
+        "concurrency",
+        "error_codes",
+        "exit_codes",
+        "errors",
+        "examples",
+    }
+)
+
+REQUIRED_COMMAND_FIELDS = frozenset(
+    {
+        "command_id",
+        "mutates",
+        "confirmation",
+        "syntax",
+        "important_options",
+        "result_summary",
+        "examples",
+        "common_errors",
+        "exit_codes",
+    }
+)
+
+REQUIRED_ERROR_FIELDS = frozenset(
+    {
+        "code",
+        "category",
+        "message",
+        "exit_code",
+        "retryable",
+        "suggested_action",
+        "details",
+    }
+)
+
+REQUIRED_ENVELOPE_FIELDS = frozenset(
+    {
+        "schema_version",
+        "request_id",
+        "ok",
+        "command",
+        "target",
+        "result",
+        "warnings",
+        "errors",
+        "metrics",
+    }
+)
+
+
+def _row(check_id: str, passed: bool, message: str, details: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    return {
+        "check_id": check_id,
+        "passed": passed,
+        "message": message,
+        "details": dict(details or {}),
+    }
+
+
+def _summarize(rows: list[dict[str, Any]]) -> dict[str, int]:
+    passed = sum(1 for row in rows if row["passed"])
+    return {"total": len(rows), "passed": passed, "failed": len(rows) - passed}
+
+
+def _guide_commands(guide: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    commands = guide.get("commands", {})
+    if not isinstance(commands, dict):
+        return {}
+    return {str(command_id): command for command_id, command in commands.items() if isinstance(command, Mapping)}
+
+
+def _check_guide_sections(guide: Mapping[str, Any]) -> dict[str, Any]:
+    missing = sorted(REQUIRED_GUIDE_SECTIONS - set(guide))
+    return _row(
+        "guide.required_sections",
+        not missing,
+        "Guide exposes all required V1 sections.",
+        {"missing": missing} if missing else {},
+    )
+
+
+def _check_command_fields(commands: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
+    failures = []
+    for command_id, command in sorted(commands.items()):
+        missing = sorted(REQUIRED_COMMAND_FIELDS - set(command))
+        command_id_mismatch = command.get("command_id") != command_id
+        if missing or command_id_mismatch:
+            failures.append(
+                {
+                    "command_id": command_id,
+                    "missing": missing,
+                    "command_id_mismatch": command_id_mismatch,
+                }
+            )
+    return _row(
+        "guide.command_fields",
+        not failures,
+        "Every guide command has the required manifest fields.",
+        {"failures": failures} if failures else {},
+    )
+
+
+def _check_public_commands(commands: Mapping[str, Mapping[str, Any]], public_command_ids: set[str]) -> dict[str, Any]:
+    guide_command_ids = set(commands)
+    missing = sorted(public_command_ids - guide_command_ids)
+    extra = sorted(guide_command_ids - public_command_ids)
+    return _row(
+        "guide.public_commands",
+        not missing and not extra,
+        "Guide command IDs match the public command set.",
+        {"missing": missing, "extra": extra} if missing or extra else {},
+    )
+
+
+def _check_renderer_coverage(commands: Mapping[str, Mapping[str, Any]], human_renderers: Mapping[str, Any]) -> dict[str, Any]:
+    guide_command_ids = set(commands)
+    renderer_ids = set(human_renderers)
+    missing = sorted(guide_command_ids - renderer_ids)
+    extra = sorted(renderer_ids - guide_command_ids)
+    return _row(
+        "renderers.coverage",
+        not missing and not extra,
+        "Human renderer coverage matches guide commands.",
+        {"missing": missing, "extra": extra} if missing or extra else {},
+    )
+
+
+def _check_error_contract(guide: Mapping[str, Any], commands: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
+    guide_error_codes = guide.get("error_codes", {})
+    if not isinstance(guide_error_codes, Mapping):
+        guide_error_codes = {}
+
+    unknown_guide_errors = sorted(set(guide_error_codes) - set(ERROR_EXIT_MAP))
+    missing_guide_errors = sorted(set(ERROR_EXIT_MAP) - set(guide_error_codes))
+    exit_mismatches = []
+    for code, metadata in guide_error_codes.items():
+        if code not in ERROR_EXIT_MAP or not isinstance(metadata, Mapping):
+            continue
+        if metadata.get("exit_code") != ERROR_EXIT_MAP[code]:
+            exit_mismatches.append({"code": code, "guide_exit": metadata.get("exit_code"), "mapped_exit": ERROR_EXIT_MAP[code]})
+
+    unknown_common_errors = []
+    for command_id, command in sorted(commands.items()):
+        common_errors = command.get("common_errors", [])
+        if not isinstance(common_errors, list):
+            unknown_common_errors.append({"command_id": command_id, "error": "<common_errors-not-list>"})
+            continue
+        for code in common_errors:
+            if code not in ERROR_EXIT_MAP:
+                unknown_common_errors.append({"command_id": command_id, "error": code})
+
+    shape_keys = set(KcError(code="KC_CONFORMANCE_FAILED", message="shape probe").to_message())
+    shape_missing = sorted(REQUIRED_ERROR_FIELDS - shape_keys)
+
+    failures = {
+        "unknown_guide_errors": unknown_guide_errors,
+        "missing_guide_errors": missing_guide_errors,
+        "exit_mismatches": exit_mismatches,
+        "unknown_common_errors": unknown_common_errors,
+        "shape_missing": shape_missing,
+    }
+    failed = any(failures.values())
+    return _row(
+        "errors.contract",
+        not failed,
+        "Guide errors and common errors resolve to the stable KcError contract.",
+        failures if failed else {},
+    )
+
+
+def _check_envelope_shape() -> dict[str, Any]:
+    payload = envelope("conformance.shape", {"valid": True})
+    missing = sorted(REQUIRED_ENVELOPE_FIELDS - set(payload))
+    metrics = payload.get("metrics", {})
+    missing_metrics = [] if isinstance(metrics, Mapping) and "duration_ms" in metrics else ["duration_ms"]
+    return _row(
+        "envelope.shape",
+        not missing and not missing_metrics,
+        "JSON envelope exposes the locked V1 fields.",
+        {"missing": missing, "missing_metrics": missing_metrics} if missing or missing_metrics else {},
+    )
+
+
+def build_conformance_report(
+    *,
+    guide: Mapping[str, Any] | None = None,
+    human_renderers: Mapping[str, Any] | None = None,
+    public_command_ids: set[str] | None = None,
+) -> dict[str, Any]:
+    guide = build_guide() if guide is None else guide
+    human_renderers = HUMAN_RENDERERS if human_renderers is None else human_renderers
+    public_command_ids = set(PUBLIC_COMMAND_IDS if public_command_ids is None else public_command_ids)
+    commands = _guide_commands(guide)
+
+    rows = [
+        _check_guide_sections(guide),
+        _check_command_fields(commands),
+        _check_public_commands(commands, public_command_ids),
+        _check_renderer_coverage(commands, human_renderers),
+        _check_error_contract(guide, commands),
+        _check_envelope_shape(),
+    ]
+    summary = _summarize(rows)
+    return {
+        "profile": "v1",
+        "valid": summary["failed"] == 0,
+        "summary": summary,
+        "checks": rows,
+    }
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("conformance", help="Run read-only CLI contract conformance checks.")
+    def conformance() -> None:
+        def _run() -> None:
+            result = build_conformance_report()
+            if not result["valid"]:
+                failed_checks = [check for check in result["checks"] if not check["passed"]]
+                raise KcError(
+                    code="KC_CONFORMANCE_FAILED",
+                    message="V1 conformance checks failed.",
+                    details={
+                        "profile": result["profile"],
+                        "summary": result["summary"],
+                        "failed_checks": failed_checks,
+                    },
+                )
+            emit_success("conformance", result)
+
+        run("conformance", _run)

kc/commands/context.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from kc.atomic_write import atomic_write_text
+from kc.commands.common import (
+    json_dumps,
+    load_artifacts,
+    load_ranges,
+    load_sources,
+    now,
+    parse_named_ints,
+    run,
+    stale_source_warnings,
+    validate_choice,
+)
+from kc.config import load_config
+from kc.ids import new_id
+from kc.models.context import ContextPackRecord
+from kc.output import emit_success, warning
+from kc.paths import current_paths, repo_relative, resolve_repo_path
+from kc.search.fts import ensure_index, search_ranges
+from kc.store.transaction import mutation_transaction
+
+app = typer.Typer(help="Prepare grounded source context for an external agent.")
+ALLOWED_GROUNDING = {"required", "optional"}
+
+
+def _parse_budget(raw: str | None) -> dict[str, int]:
+    return parse_named_ints(raw, option="--budget", defaults={"max_sources": 12, "max_ranges": 40})
+
+
+@app.command("prepare", help="Search sources and emit evidence, policies, and next commands without answering.")
+def prepare(
+    ask: Annotated[str, typer.Option("--ask", help="Knowledge task or question.")],
+    shape: Annotated[
+        str, typer.Option("--shape", help="Output shape requested from agent.")
+    ] = "knowledge_page",
+    domain: Annotated[str | None, typer.Option("--domain", help="Domain filter.")] = None,
+    target: Annotated[str | None, typer.Option("--target", help="Target artifact path.")] = None,
+    grounding: Annotated[
+        str, typer.Option("--grounding", help="Grounding policy: required or optional.")
+    ] = "required",
+    budget: Annotated[
+        str | None, typer.Option("--budget", help="max_sources=N,max_ranges=N")
+    ] = None,
+    out: Annotated[Path | None, typer.Option("--out", help="Write a durable context pack JSON file.")] = None,
+    context_id: Annotated[str | None, typer.Option("--id", help="Context pack ID override.")] = None,
+) -> None:
+    def _run() -> None:
+        paths = current_paths()
+        validate_choice(grounding, option="--grounding", supported=ALLOWED_GROUNDING)
+        limits = _parse_budget(budget)
+        ensure_index(paths.sqlite_path, paths.sources_jsonl, paths.ranges_jsonl)
+        sources = load_sources()
+        retrieval_metadata: dict[str, str | None] = {}
+        candidate_ranges = search_ranges(
+            paths.sqlite_path,
+            ask,
+            domain=domain,
+            limit=limits["max_ranges"],
+            rrf_k=load_config(paths.root).rrf_k,
+            ranges=load_ranges(),
+            metadata=retrieval_metadata,
+        )
+        seen_sources: set[str] = set()
+        filtered = []
+        for item in candidate_ranges:
+            if item["source_id"] not in seen_sources and len(seen_sources) >= limits["max_sources"]:
+                continue
+            seen_sources.add(item["source_id"])
+            filtered.append(item)
+        artifacts = load_artifacts()
+        existing = [
+            {
+                "artifact_id": artifact.artifact_id,
+                "path": artifact.path,
+                "status": artifact.status,
+                "validation_status": artifact.validation_status,
+                "title": artifact.title,
+            }
+            for artifact in artifacts
+            if (target and artifact.path == target)
+            or (domain and domain in artifact.domain)
+            or (not target and not domain)
+        ]
+        warnings = []
+        if not filtered:
+            warnings.append(
+                warning(
+                    "KC_NO_CONTEXT_RANGES",
+                    "No source ranges matched the request; register or index sources first.",
+                    {"ask": ask, "domain": domain},
+                )
+            )
+        if retrieval_metadata.get("mode") == "fts_fallback":
+            warnings.append(
+                warning(
+                    "KC_RETRIEVAL_SEMANTIC_UNAVAILABLE",
+                    "Semantic ranking is unavailable; results use SQLite FTS fallback.",
+                    {"reason": retrieval_metadata.get("semantic_unavailable_reason")},
+                )
+            )
+        citation_policy = {
+            "material_claims_require_citations": grounding == "required",
+            "citation_token_formats": [
+                "[kc:src_<id>:rng_<id>]",
+                "[kc:src_<id>:rng_<id>:L<start>-L<end>]",
+                "[kc:src_<id>:rng_<id>:JP:<percent-encoded-json-pointer>]",
+                "[kc:src_<id>:rng_<id>:CSV:R<start>-R<end>]",
+            ],
+            "legacy_citation_token_formats": [
+                "[kc:src_<id>:L<start>-L<end>]",
+                "[kc:src_<id>:JP:<percent-encoded-json-pointer>]",
+                "[kc:src_<id>:CSV:R<start>-R<end>]",
+            ],
+        }
+        agent_instructions = [
+            "Use the returned source ranges for factual claims.",
+            "Prefer v2 citation_token values with range IDs.",
+            "If no candidate range supports a claim, mark it [kc:todo] or leave it out.",
+            "Do not invent owner, authority, review date, or lifecycle status.",
+            "If sources conflict, report the conflict instead of silently resolving it.",
+            "kc does not answer the question; you must write the answer or artifact.",
+        ]
+        next_commands = [
+            f"kc artifact validate --file {target or '<artifact>'}",
+            f"kc artifact diff --file {target or '<artifact>'}",
+            f"kc artifact apply --file {target or '<artifact>'} --dry-run",
+            f"kc artifact apply --file {target or '<artifact>'} --yes",
+        ]
+        result = {
+                "search_query": ask,
+                "mode": retrieval_metadata.get("mode") or "hybrid",
+                "budget": limits,
+                "candidate_ranges": filtered,
+                "existing_artifacts": existing,
+                "required_output_shape": shape,
+                "grounding_policy": grounding,
+                "citation_policy": citation_policy,
+                "agent_instructions": agent_instructions,
+                "validation_commands": [
+                    "kc citation check --file <artifact-or-answer>",
+                    "kc artifact validate --file <artifact>",
+                ],
+                "next_commands": next_commands,
+            }
+        if out is not None:
+            pack = ContextPackRecord(
+                context_id=context_id or new_id("ctx"),
+                created_at=now(),
+                ask=ask,
+                shape=shape,
+                target=target,
+                grounding_policy=grounding,
+                workspace={"root": paths.root.as_posix(), "project_id": load_config(paths.root).project_id},
+                candidate_ranges=filtered,
+                existing_artifacts=existing,
+                citation_policy=citation_policy,
+                artifact_policy={"requires_validation_before_apply": True},
+                agent_instructions=agent_instructions,
+                next_commands=next_commands,
+                validation={
+                    "commands": [
+                        f"kc artifact validate --file {target or '<artifact>'}",
+                        f"kc citation check --file {target or '<artifact>'}",
+                    ],
+                    "expected_exit_codes": {"success": 0, "validation": 10, "provenance": 20},
+                },
+            )
+            out_path = resolve_repo_path(out)
+            with mutation_transaction(paths, "context.prepare", [out_path]) as tx:
+                atomic_write_text(out_path, json_dumps(pack.model_dump(mode="json")) + "\n")
+                tx.commit({"context_id": pack.context_id})
+            result["context_pack"] = {
+                "context_id": pack.context_id,
+                "path": repo_relative(out_path),
+                "schema_version": pack.schema_version,
+            }
+        emit_success(
+            "context.prepare",
+            result,
+            target={"ask": ask, "shape": shape, "target": target, "mode": retrieval_metadata.get("mode") or "hybrid", "budget": limits},
+            warnings=[*warnings, *stale_source_warnings(filtered, sources)],
+        )
+
+    run("context.prepare", _run)

kc/commands/doctor.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from kc.commands.common import load_ranges, load_sources, run
+from kc.output import emit_success
+from kc.paths import current_paths, current_workspace
+from kc.search.semantic import semantic_index_status
+from kc.store.sqlite import index_status
+
+app = typer.Typer(help="Inspect repository health, locks, and semantic index state.")
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    def _run() -> None:
+        workspace = current_workspace()
+        paths = workspace.paths
+        ranges = load_ranges() if paths.ranges_jsonl.exists() else []
+        sources = load_sources() if paths.sources_jsonl.exists() else []
+        emit_success(
+            "doctor",
+            {
+                "workspace_resolution": {
+                    "root": workspace.root.as_posix(),
+                    "source": workspace.source,
+                    "project_id": workspace.config.project_id,
+                    "data_dir": paths.data_dir.as_posix(),
+                    "state_dir": paths.state_dir.as_posix(),
+                },
+                "config_exists": paths.config_path.exists(),
+                "data_dir_exists": paths.data_dir.exists(),
+                "state_dir_exists": paths.state_dir.exists(),
+                "sqlite_exists": paths.sqlite_path.exists(),
+                "locks": len(list(paths.locks_dir.glob("*.lock")))
+                if paths.locks_dir.exists()
+                else 0,
+                "index": index_status(paths.sqlite_path, sources, ranges),
+                "semantic": semantic_index_status(paths.sqlite_path, ranges),
+            },
+        )
+
+    run("doctor", _run)
+
+
+@app.command("locks", help="List lock files and optionally clear them after confirmation.")
+def locks(
+    clear_stale: Annotated[bool, typer.Option("--clear-stale", help="Clear lock files.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm clearing lock files.")] = False,
+) -> None:
+    def _run() -> None:
+        paths = current_paths()
+        paths.locks_dir.mkdir(parents=True, exist_ok=True)
+        lock_infos = []
+        cleared = []
+        for path in sorted(paths.locks_dir.glob("*.lock")):
+            try:
+                metadata = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:
+                metadata = {"lock_file": str(path)}
+            lock_infos.append({"path": str(path), "metadata": metadata})
+            if clear_stale and yes:
+                path.unlink(missing_ok=True)
+                cleared.append(str(path))
+        emit_success(
+            "doctor.locks",
+            {
+                "locks": lock_infos,
+                "clear_stale": clear_stale,
+                "cleared": cleared,
+                "dry_run": clear_stale and not yes,
+            },
+        )
+
+    run("doctor.locks", _run)