kc-cli 0.4.0__py3-none-any.whl

kc/commands/init.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from contextlib import nullcontext
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from kc.atomic_write import atomic_write_text
+from kc.commands.common import run, validate_choice
+from kc.config import DEFAULT_CONFIG
+from kc.output import emit_success, warning
+from kc.paths import current_paths, repo_relative
+from kc.store.sqlite import init_db
+from kc.store.transaction import mutation_transaction
+
+ALLOWED_PROFILES = {"generic"}
+MANAGED_AGENT_SKILL_MARKER = "kc-managed-agent-skill:v1"
+AGENT_SKILL_DIRS = [
+    Path(".agents"),
+    Path(".agents") / "skills",
+    Path(".agents") / "skills" / "kc",
+    Path(".agents") / "skills" / "kc" / "agents",
+    Path(".agents") / "skills" / "kc" / "scripts",
+]
+AGENT_SKILL_TEMPLATE_FILES = [
+    (("SKILL.md",), Path(".agents") / "skills" / "kc" / "SKILL.md"),
+    (("agents", "openai.yaml"), Path(".agents") / "skills" / "kc" / "agents" / "openai.yaml"),
+    (
+        ("scripts", "resolve_query_citations.py"),
+        Path(".agents") / "skills" / "kc" / "scripts" / "resolve_query_citations.py",
+    ),
+]
+
+
+def _agent_skill_templates() -> dict[Path, str]:
+    template_root = files("kc").joinpath("templates", "agents", "skills", "kc")
+    return {
+        target: template_root.joinpath(*template_path).read_text(encoding="utf-8")
+        for template_path, target in AGENT_SKILL_TEMPLATE_FILES
+    }
+
+
+def _handle_managed_file(
+    path: Path,
+    content: str,
+    *,
+    effective_dry_run: bool,
+    created: list[str],
+    updated: list[str],
+    noop: list[str],
+    planned: list[str],
+    warnings: list[dict[str, Any]],
+) -> None:
+    rel = repo_relative(path)
+    if not path.exists():
+        if effective_dry_run:
+            planned.append(rel)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            atomic_write_text(path, content)
+            created.append(rel)
+        return
+
+    if not path.is_file():
+        noop.append(rel)
+        warnings.append(
+            warning(
+                "KC_INIT_AGENT_SKILL_CUSTOM",
+                "Existing agent skill path is not a managed file; preserved without overwrite.",
+                {"path": rel},
+            )
+        )
+        return
+
+    current = path.read_text(encoding="utf-8")
+    if current == content:
+        noop.append(rel)
+        return
+    if MANAGED_AGENT_SKILL_MARKER in current:
+        if effective_dry_run:
+            planned.append(rel)
+        else:
+            atomic_write_text(path, content)
+            updated.append(rel)
+        return
+
+    noop.append(rel)
+    warnings.append(
+        warning(
+            "KC_INIT_AGENT_SKILL_CUSTOM",
+            "Existing agent skill file is not kc-managed; preserved without overwrite.",
+            {"path": rel},
+        )
+    )
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("init", help="Create the repo-local kc layout, config, JSONL stores, and SQLite state.")
+    def init_command(
+        profile: Annotated[
+            str, typer.Option("--profile", help="Initialization profile: generic.")
+        ] = "generic",
+        dry_run: Annotated[
+            bool, typer.Option("--dry-run", help="Preview without writing.")
+        ] = False,
+        yes: Annotated[bool, typer.Option("--yes", help="Create files.")] = False,
+    ) -> None:
+        def _run() -> None:
+            validate_choice(profile, option="--profile", supported=ALLOWED_PROFILES)
+            paths = current_paths()
+            effective_dry_run = dry_run or not yes
+            dirs = [
+                paths.data_dir,
+                paths.data_dir / "raw",
+                paths.wiki_dir,
+                paths.data_dir / "artifacts",
+                paths.data_dir / "schemas",
+                paths.data_dir / "evals",
+                paths.data_dir / "exports",
+                *[paths.root / path for path in AGENT_SKILL_DIRS],
+                paths.state_dir,
+                paths.locks_dir,
+                paths.snapshots_dir,
+                paths.plans_dir,
+                paths.tasks_dir,
+                paths.context_dir,
+                paths.operations_dir,
+                paths.state_dir / "cache",
+                paths.state_dir / "logs",
+            ]
+            files: dict[Path, str] = {
+                paths.config_path: DEFAULT_CONFIG,
+                paths.sources_jsonl: "",
+                paths.source_revisions_jsonl: "",
+                paths.ranges_jsonl: "",
+                paths.artifacts_jsonl: "",
+                paths.citation_edges_jsonl: "",
+                paths.wiki_dir / "index.md": "# Knowledge Index\n\n",
+                paths.log_path: "# Knowledge Log\n\n",
+            }
+            created: list[str] = []
+            noop: list[str] = []
+            planned: list[str] = []
+            updated: list[str] = []
+            warnings: list[dict[str, Any]] = []
+            transaction = (
+                nullcontext()
+                if effective_dry_run
+                else mutation_transaction(paths, "init", [paths.root])
+            )
+            with transaction as tx:
+                for d in dirs:
+                    rel = repo_relative(d)
+                    if d.exists():
+                        noop.append(rel)
+                    elif effective_dry_run:
+                        planned.append(rel)
+                    else:
+                        d.mkdir(parents=True, exist_ok=True)
+                        created.append(rel)
+                for path, content in files.items():
+                    rel = repo_relative(path)
+                    if path.exists():
+                        noop.append(rel)
+                    elif effective_dry_run:
+                        planned.append(rel)
+                    else:
+                        path.parent.mkdir(parents=True, exist_ok=True)
+                        atomic_write_text(path, content)
+                        created.append(rel)
+                for rel_path, content in _agent_skill_templates().items():
+                    _handle_managed_file(
+                        paths.root / rel_path,
+                        content,
+                        effective_dry_run=effective_dry_run,
+                        created=created,
+                        updated=updated,
+                        noop=noop,
+                        planned=planned,
+                        warnings=warnings,
+                    )
+                sqlite_rel = repo_relative(paths.sqlite_path)
+                if paths.sqlite_path.exists():
+                    noop.append(sqlite_rel)
+                elif effective_dry_run:
+                    planned.append(sqlite_rel)
+                else:
+                    init_db(paths.sqlite_path)
+                    created.append(sqlite_rel)
+                if tx is not None:
+                    tx.commit({"created": created, "updated": updated})
+            emit_success(
+                "init",
+                {
+                    "dry_run": effective_dry_run,
+                    "profile": profile,
+                    "created": created,
+                    "updated": updated,
+                    "planned": planned,
+                    "noop": sorted(set(noop)),
+                },
+                warnings=warnings,
+            )
+
+        run("init", _run)

kc/commands/lint.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import re
+from typing import Annotated
+
+import typer
+
+from kc.commands.artifact import validate_artifact_file
+from kc.commands.common import (
+    load_artifacts,
+    load_citation_edges,
+    load_ranges,
+    load_sources,
+    parse_checks,
+    run,
+)
+from kc.errors import EXIT_VALIDATION, KcError
+from kc.fingerprints import raw_fingerprint
+from kc.output import emit, emit_success, envelope
+from kc.paths import current_paths, resolve_repo_path
+from kc.store.sqlite import index_status
+
+LOG_REF_RE = re.compile(r"\b(?P<kind>plan|task)_[A-Z0-9]+\b")
+DEFAULT_CHECKS = {"citations", "stale", "orphans"}
+ALLOWED_CHECKS = {"citations", "stale", "orphans", "duplicates", "index", "log"}
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("lint", help="Run repository integrity checks for citations, stale sources, and orphaned artifacts.")
+    def lint(
+        checks: Annotated[
+            str,
+            typer.Option("--checks", help="Comma-separated checks: citations,stale,orphans."),
+        ] = "citations,stale,orphans",
+    ) -> None:
+        def _run() -> None:
+            enabled = parse_checks(checks, allowed=ALLOWED_CHECKS, all_checks=ALLOWED_CHECKS)
+            issues: list[dict] = []
+            paths = current_paths()
+            sources = load_sources()
+            ranges = load_ranges()
+            artifacts = load_artifacts()
+            citation_edges = load_citation_edges()
+            source_ids = [source.source_id for source in sources]
+            range_ids = [source_range.range_id for source_range in ranges]
+            artifact_ids = [artifact.artifact_id for artifact in artifacts]
+            artifact_paths = {artifact.path for artifact in artifacts}
+
+            if "duplicates" in enabled:
+                issues.extend(_duplicate_issues("source_id", source_ids, "KC_CONFIG_INVALID"))
+                issues.extend(_duplicate_issues("range_id", range_ids, "KC_CONFIG_INVALID"))
+                issues.extend(
+                    _duplicate_issues("artifact_id", artifact_ids, "KC_ARTIFACT_SCHEMA_INVALID")
+                )
+
+            if "stale" in enabled:
+                for source in sources:
+                    original = source.metadata.get("original_path")
+                    if not isinstance(original, str):
+                        continue
+                    path = resolve_repo_path(original, paths.root)
+                    if not path.exists():
+                        issues.append(
+                            {
+                                "code": "KC_SOURCE_STALE",
+                                "message": f"Source file is missing: {source.uri}",
+                                "source_id": source.source_id,
+                            }
+                        )
+                    elif raw_fingerprint(path) != source.fingerprint:
+                        issues.append(
+                            {
+                                "code": "KC_SOURCE_STALE",
+                                "message": f"Source fingerprint changed: {source.uri}",
+                                "source_id": source.source_id,
+                            }
+                        )
+
+            if "orphans" in enabled:
+                source_id_set = set(source_ids)
+                range_id_set = set(range_ids)
+                for source_range in ranges:
+                    if source_range.source_id not in source_id_set:
+                        issues.append(
+                            {
+                                "code": "KC_SOURCE_NOT_FOUND",
+                                "message": f"Source range has no registered source: {source_range.range_id}",
+                                "range_id": source_range.range_id,
+                                "source_id": source_range.source_id,
+                            }
+                        )
+                for edge in citation_edges:
+                    if edge.artifact_path not in artifact_paths:
+                        issues.append(
+                            {
+                                "code": "KC_ARTIFACT_NOT_FOUND",
+                                "message": f"Citation edge has no registered artifact: {edge.artifact_path}",
+                                "edge_id": edge.edge_id,
+                                "artifact_path": edge.artifact_path,
+                            }
+                        )
+                    if edge.source_id not in source_id_set:
+                        issues.append(
+                            {
+                                "code": "KC_CITATION_SOURCE_MISSING",
+                                "message": f"Citation edge source is missing: {edge.source_id}",
+                                "edge_id": edge.edge_id,
+                                "source_id": edge.source_id,
+                            }
+                        )
+                    if edge.range_id and edge.range_id not in range_id_set:
+                        issues.append(
+                            {
+                                "code": "KC_CITATION_RANGE_MISSING",
+                                "message": f"Citation edge range is missing: {edge.range_id}",
+                                "edge_id": edge.edge_id,
+                                "range_id": edge.range_id,
+                            }
+                        )
+
+            for artifact in artifacts:
+                artifact_path = resolve_repo_path(artifact.path, paths.root)
+                if "orphans" in enabled and not artifact_path.exists():
+                    issues.append(
+                        {
+                            "code": "KC_ARTIFACT_NOT_FOUND",
+                            "message": f"Registered artifact file is missing: {artifact.path}",
+                            "artifact_id": artifact.artifact_id,
+                        }
+                    )
+                    continue
+                if "citations" in enabled and artifact_path.exists():
+                    result = validate_artifact_file(artifact_path)
+                    if not result["valid"]:
+                        for error in result["errors"]:
+                            issues.append(error | {"artifact_path": artifact.path})
+
+            if "index" in enabled:
+                status = index_status(paths.sqlite_path, sources, ranges)
+                if status["stale"]:
+                    issues.append(
+                        {
+                            "code": "KC_INDEX_BUILD_FAILED",
+                            "message": "SQLite search index is missing or stale.",
+                            "index": status,
+                        }
+                    )
+
+            if "log" in enabled and paths.log_path.exists():
+                plan_dir = paths.plans_dir
+                task_dir = paths.tasks_dir
+                for match in LOG_REF_RE.finditer(paths.log_path.read_text(encoding="utf-8")):
+                    ref = match.group(0)
+                    if ref.startswith("plan_") and not (plan_dir / f"{ref}.json").exists():
+                        issues.append(
+                            {
+                                "code": "KC_ARTIFACT_SCHEMA_INVALID",
+                                "message": f"Knowledge log references unknown plan: {ref}",
+                                "reference": ref,
+                            }
+                        )
+                    if ref.startswith("task_") and not (task_dir / f"{ref}.json").exists():
+                        issues.append(
+                            {
+                                "code": "KC_ARTIFACT_SCHEMA_INVALID",
+                                "message": f"Knowledge log references unknown task: {ref}",
+                                "reference": ref,
+                            }
+                        )
+            result = {
+                "valid": not issues,
+                "checks": sorted(enabled),
+                "sources": len(sources),
+                "artifacts": len(artifacts),
+                "issues": issues,
+                "next_commands": _next_commands(issues),
+            }
+            if issues:
+                errors = [
+                    KcError(
+                        code=str(issue.get("code", "KC_ARTIFACT_SCHEMA_INVALID")),
+                        message=str(issue.get("message", "Lint issue.")),
+                        details=issue,
+                        suggested_action="fix lint issue",
+                    ).to_message()
+                    for issue in issues
+                ]
+                emit(
+                    envelope(
+                        "lint",
+                        None,
+                        ok=False,
+                        errors=errors,
+                    ),
+                    exit_code=max(int(error["exit_code"]) for error in errors)
+                    if errors
+                    else EXIT_VALIDATION,
+                )
+            emit_success("lint", result)
+
+        run("lint", _run)
+
+
+def _duplicate_issues(field: str, values: list[str], code: str) -> list[dict]:
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for value in values:
+        if value in seen:
+            duplicates.add(value)
+        seen.add(value)
+    return [
+        {
+            "code": code,
+            "message": f"Duplicate {field}: {value}",
+            "field": field,
+            "value": value,
+        }
+        for value in sorted(duplicates)
+    ]
+
+
+def _next_commands(issues: list[dict]) -> list[str]:
+    commands: set[str] = set()
+    for issue in issues:
+        code = issue.get("code")
+        if code == "KC_SOURCE_STALE" and issue.get("source_id"):
+            commands.add(f"kc source refresh {issue['source_id']} --dry-run")
+        elif code == "KC_INDEX_BUILD_FAILED":
+            commands.add("kc index build")
+        elif code in {"KC_CITATION_RANGE_MISSING", "KC_CITATION_STALE_SOURCE"}:
+            artifact_path = issue.get("artifact_path")
+            if artifact_path:
+                commands.add(f"kc citation repair --file {artifact_path} --dry-run")
+        elif code in {"KC_ARTIFACT_SCHEMA_INVALID", "KC_VALIDATION_MISSING_CITATION"}:
+            artifact_path = issue.get("artifact_path")
+            if artifact_path:
+                commands.add(f"kc artifact validate --file {artifact_path}")
+    return sorted(commands)