kc-cli 0.4.0__py3-none-any.whl

kc/errors.py

@@ -0,0 +1,141 @@
+"""Typed errors and exit-code contract for kc."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_VALIDATION = 10
+EXIT_NOT_FOUND = 11
+EXIT_ALREADY_EXISTS = 12
+EXIT_CONFLICT = 13
+EXIT_PROVENANCE = 20
+EXIT_INDEX = 30
+EXIT_RETRIEVAL_MODEL = 31
+EXIT_WAITING = 40
+EXIT_IO = 50
+EXIT_LOCK = 60
+EXIT_PERSISTENCE = 70
+EXIT_UNSUPPORTED = 80
+EXIT_INTERNAL = 90
+
+
+ERROR_EXIT_MAP: dict[str, int] = {
+    "KC_USAGE_ERROR": EXIT_USAGE,
+    "KC_CONFIG_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_CONFIG_INVALID": EXIT_VALIDATION,
+    "KC_SOURCE_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_SOURCE_ALREADY_REGISTERED": EXIT_ALREADY_EXISTS,
+    "KC_SOURCE_STALE": EXIT_PROVENANCE,
+    "KC_SOURCE_UNSUPPORTED_MEDIA_TYPE": EXIT_UNSUPPORTED,
+    "KC_RANGE_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_ARTIFACT_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_ARTIFACT_SCHEMA_INVALID": EXIT_VALIDATION,
+    "KC_ARTIFACT_STATUS_INVALID": EXIT_VALIDATION,
+    "KC_CITATION_INVALID_TOKEN": EXIT_PROVENANCE,
+    "KC_CITATION_SOURCE_MISSING": EXIT_PROVENANCE,
+    "KC_CITATION_RANGE_MISSING": EXIT_PROVENANCE,
+    "KC_CITATION_STALE_SOURCE": EXIT_PROVENANCE,
+    "KC_VALIDATION_MISSING_CITATION": EXIT_VALIDATION,
+    "KC_VALIDATION_TODO_IN_ACTIVE_ARTIFACT": EXIT_VALIDATION,
+    "KC_VALIDATION_INVALID_ARGUMENT": EXIT_VALIDATION,
+    "KC_PLAN_PRECONDITION_FAILED": EXIT_CONFLICT,
+    "KC_CONFORMANCE_FAILED": EXIT_VALIDATION,
+    "KC_APPLY_REQUIRES_YES": EXIT_VALIDATION,
+    "KC_APPLY_NOT_VALIDATED": EXIT_VALIDATION,
+    "KC_LOCK_HELD": EXIT_LOCK,
+    "KC_INDEX_BUILD_FAILED": EXIT_INDEX,
+    "KC_RETRIEVAL_MODEL_UNAVAILABLE": EXIT_RETRIEVAL_MODEL,
+    "KC_UNSUPPORTED_FEATURE": EXIT_UNSUPPORTED,
+    "KC_PATH_OUTSIDE_REPO": EXIT_VALIDATION,
+    "KC_FILE_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_FILE_EXISTS": EXIT_ALREADY_EXISTS,
+    "KC_JSON_INVALID": EXIT_VALIDATION,
+    "KC_TASK_NOT_FOUND": EXIT_NOT_FOUND,
+    "KC_TASK_NOT_WAITING": EXIT_CONFLICT,
+    "KC_EVENT_INVALID": EXIT_VALIDATION,
+    "KC_INTERNAL_ERROR": EXIT_INTERNAL,
+}
+
+
+ERROR_CATEGORIES: dict[str, str] = {
+    "CONFIG": "configuration",
+    "USAGE": "usage",
+    "SOURCE": "source",
+    "RANGE": "source_range",
+    "ARTIFACT": "artifact",
+    "CITATION": "provenance",
+    "VALIDATION": "validation",
+    "PLAN": "plan",
+    "CONFORMANCE": "validation",
+    "APPLY": "apply",
+    "LOCK": "concurrency",
+    "INDEX": "index",
+    "RETRIEVAL": "retrieval",
+    "PATH": "validation",
+    "FILE": "io",
+    "JSON": "validation",
+    "TASK": "task",
+    "EVENT": "task",
+    "UNSUPPORTED": "unsupported",
+    "INTERNAL": "internal",
+}
+
+
+def exit_code_for(code: str) -> int:
+    return ERROR_EXIT_MAP.get(code, EXIT_INTERNAL)
+
+
+def category_for(code: str) -> str:
+    parts = code.split("_")
+    if len(parts) >= 2:
+        return ERROR_CATEGORIES.get(parts[1], "internal")
+    return "internal"
+
+
+@dataclass
+class KcError(Exception):
+    """Domain error surfaced through the kc.result.v1 envelope."""
+
+    code: str
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+    category: str | None = None
+    exit_code: int | None = None
+    retryable: bool = False
+    suggested_action: str | None = None
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+        if self.category is None:
+            self.category = category_for(self.code)
+        if self.exit_code is None:
+            self.exit_code = exit_code_for(self.code)
+        if self.suggested_action is None:
+            if self.retryable:
+                self.suggested_action = "retry"
+            elif self.exit_code in {EXIT_USAGE, EXIT_VALIDATION, EXIT_NOT_FOUND, EXIT_ALREADY_EXISTS}:
+                self.suggested_action = "fix_input"
+            elif self.exit_code == EXIT_LOCK:
+                self.suggested_action = "inspect lock with kc doctor locks or retry later"
+            else:
+                self.suggested_action = "escalate"
+
+    def to_message(self) -> dict[str, Any]:
+        return {
+            "code": self.code,
+            "category": self.category,
+            "message": self.message,
+            "exit_code": self.exit_code,
+            "retryable": self.retryable,
+            "suggested_action": self.suggested_action,
+            "details": self.details,
+        }
+
+
+def validation_error(
+    message: str, *, code: str = "KC_ARTIFACT_SCHEMA_INVALID", **details: Any
+) -> KcError:
+    return KcError(code=code, message=message, details=details)

kc/fingerprints.py

@@ -0,0 +1,35 @@
+"""File and text fingerprint helpers."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def sha256_bytes(data: bytes) -> str:
+    return f"sha256:{hashlib.sha256(data).hexdigest()}"
+
+
+def normalize_text(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def raw_fingerprint(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return f"sha256:{h.hexdigest()}"
+
+
+def normalized_fingerprint(path: Path) -> str:
+    text = normalize_text(path.read_text(encoding="utf-8-sig"))
+    return sha256_bytes(text.encode("utf-8"))
+
+
+def text_hash(text: str) -> str:
+    return sha256_bytes(normalize_text(text).encode("utf-8"))
+
+
+def fingerprint_text(text: str) -> str:
+    return text_hash(text)

kc/ids.py

@@ -0,0 +1,23 @@
+"""Deterministic-looking public IDs with kc prefixes."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+
+try:
+    from ulid import ULID
+except Exception:  # pragma: no cover - fallback for unusual environments
+    ULID = None  # type: ignore[assignment]
+
+
+def new_id(prefix: str) -> str:
+    if ULID is not None:
+        return f"{prefix}_{ULID()}"
+    return f"{prefix}_{uuid.uuid4().hex}"
+
+
+def stable_id(prefix: str, *parts: str) -> str:
+    material = "\x1f".join(parts)
+    digest = hashlib.sha256(material.encode("utf-8")).hexdigest()[:26].upper()
+    return f"{prefix}_{digest}"

kc/locks.py

@@ -0,0 +1,65 @@
+"""Simple visible lock files for write commands."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from kc.errors import KcError
+from kc.ids import new_id
+from kc.output import state
+
+
+@dataclass
+class FileLock:
+    locks_dir: Path
+    name: str
+    command: str
+    target: str
+
+    def __post_init__(self) -> None:
+        self.locks_dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.locks_dir / f"{self.name}.lock"
+        self.acquired = False
+
+    def __enter__(self) -> FileLock:
+        metadata = {
+            "schema_version": "kc.lock.v1",
+            "lock_id": new_id("lock"),
+            "created_at": datetime.now(UTC).isoformat(),
+            "pid": os.getpid(),
+            "hostname": socket.gethostname(),
+            "command": self.command,
+            "request_id": state.request_id,
+            "target": self.target,
+        }
+        try:
+            fd = os.open(str(self.path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError as exc:
+            holder: dict[str, Any] = {}
+            try:
+                holder = json.loads(self.path.read_text(encoding="utf-8"))
+            except Exception:
+                holder = {"lock_file": str(self.path)}
+            raise KcError(
+                code="KC_LOCK_HELD",
+                message=f"Lock is held: {self.path}",
+                details={"lock_file": str(self.path), "holder": holder},
+                retryable=True,
+            ) from exc
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2)
+            f.write("\n")
+        self.acquired = True
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        if self.acquired:
+            with suppress(FileNotFoundError):
+                self.path.unlink()

kc/models/__init__.py

@@ -0,0 +1,17 @@
+from kc.models.artifact import ArtifactRecord
+from kc.models.citation import CitationEdgeRecord
+from kc.models.plan import PlanRecord
+from kc.models.source import Authority, SourceRecord
+from kc.models.source_range import Locator, SourceRangeRecord
+from kc.models.task import TaskRecord
+
+__all__ = [
+    "ArtifactRecord",
+    "Authority",
+    "CitationEdgeRecord",
+    "Locator",
+    "PlanRecord",
+    "SourceRangeRecord",
+    "SourceRecord",
+    "TaskRecord",
+]

kc/models/artifact.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SourceRef(BaseModel):
+    source_id: str
+    range_ids: list[str] = Field(default_factory=list)
+
+
+class ArtifactRecord(BaseModel):
+    schema_version: Literal["kc.artifact.v1"] = "kc.artifact.v1"
+    artifact_id: str
+    path: str
+    artifact_type: Literal[
+        "knowledge_page",
+        "glossary",
+        "decision_note",
+        "source_index",
+        "log_entry",
+        "eval_pack",
+    ] = "knowledge_page"
+    title: str
+    status: Literal["draft", "active", "deprecated", "superseded"] = "draft"
+    domain: list[str] = Field(default_factory=list)
+    fingerprint: str
+    created_at: str
+    updated_at: str
+    last_validated_at: str | None = None
+    validation_status: Literal["passed", "failed", "unknown"] = "unknown"
+    source_refs: list[SourceRef] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)

kc/models/citation.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from kc.models.source_range import Locator
+
+
+class ArtifactLocator(BaseModel):
+    kind: Literal["line_range"] = "line_range"
+    start_line: int
+    end_line: int
+
+
+class CitationEdgeRecord(BaseModel):
+    schema_version: Literal["kc.citation_edge.v1"] = "kc.citation_edge.v1"
+    edge_id: str
+    artifact_id: str | None = None
+    artifact_path: str
+    artifact_locator: ArtifactLocator
+    citation_token: str
+    source_id: str
+    range_id: str | None = None
+    source_fingerprint_at_validation: str | None = None
+    validated_at: str
+    status: Literal[
+        "valid",
+        "missing_source",
+        "missing_range",
+        "stale_source",
+        "locator_mismatch",
+        "invalid_token",
+    ] = "valid"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ParsedCitation(BaseModel):
+    token: str
+    source_id: str
+    range_id: str | None = None
+    token_version: Literal["v1", "v2"] = "v1"
+    kind: Literal["line_range", "json_pointer", "csv_row_range"]
+    line: int
+    start_line: int | None = None
+    end_line: int | None = None
+    pointer: str | None = None
+    start_row: int | None = None
+    end_row: int | None = None
+
+    @property
+    def locator(self) -> Locator:
+        return Locator(
+            kind=self.kind,
+            start_line=self.start_line,
+            end_line=self.end_line,
+            pointer=self.pointer,
+            start_row=self.start_row,
+            end_row=self.end_row,
+        )

kc/models/context.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ContextPackRecord(BaseModel):
+    schema_version: Literal["kc.context_pack.v1"] = "kc.context_pack.v1"
+    context_id: str
+    created_at: str
+    ask: str
+    shape: str = "knowledge_page"
+    target: str | None = None
+    grounding_policy: str = "required"
+    workspace: dict[str, Any] = Field(default_factory=dict)
+    candidate_ranges: list[dict[str, Any]] = Field(default_factory=list)
+    existing_artifacts: list[dict[str, Any]] = Field(default_factory=list)
+    citation_policy: dict[str, Any] = Field(default_factory=dict)
+    artifact_policy: dict[str, Any] = Field(default_factory=dict)
+    agent_instructions: list[str] = Field(default_factory=list)
+    next_commands: list[str] = Field(default_factory=list)
+    validation: dict[str, Any] = Field(default_factory=dict)

kc/models/eval.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class EvalCase(BaseModel):
+    id: str
+    query: str
+    domain: str | None = None
+    limit: int = 10
+    expected_source_ids: list[str] = Field(default_factory=list)
+    expected_range_ids: list[str] = Field(default_factory=list)
+    must_include_citation_tokens: list[str] = Field(default_factory=list)
+    min_recall_at_k: float = 1.0
+
+
+class EvalPack(BaseModel):
+    schema_version: Literal["kc.eval_pack.v1"] = "kc.eval_pack.v1"
+    cases: list[EvalCase] = Field(default_factory=list)

kc/models/plan.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class PlanOperation(BaseModel):
+    op_id: str
+    kind: str
+    path: str
+    before_fingerprint: str | None = None
+    after_fingerprint: str | None = None
+    risk: Literal["low", "medium", "high"] = "medium"
+    diff_path: str | None = None
+    requires_yes: bool = True
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlanCondition(BaseModel):
+    kind: str
+    path: str | None = None
+    expected: str | None = None
+
+
+class PlanRecord(BaseModel):
+    schema_version: Literal["kc.plan.v1"] = "kc.plan.v1"
+    plan_id: str
+    created_at: str
+    command: str
+    mode: Literal["dry_run", "apply"] = "dry_run"
+    idempotency_key: str | None = None
+    operations: list[PlanOperation] = Field(default_factory=list)
+    preconditions: list[PlanCondition] = Field(default_factory=list)
+    postconditions: list[PlanCondition] = Field(default_factory=list)
+    risk_flags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)

kc/models/source.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class Authority(BaseModel):
+    level: Literal["unknown", "informal", "team-approved", "enterprise-approved", "regulatory"] = (
+        "unknown"
+    )
+    owner: str | None = None
+    review_date: str | None = None
+    notes: str = "Do not infer authority from file location."
+
+
+class SourceRecord(BaseModel):
+    schema_version: Literal["kc.source.v1"] = "kc.source.v1"
+    source_id: str
+    uri: str
+    display_name: str
+    media_type: str = "text/plain"
+    fingerprint: str
+    raw_fingerprint: str | None = None
+    normalized_fingerprint: str | None = None
+    fingerprint_algorithm: str = "sha256-normalized-v1"
+    registered_at: str
+    registered_by: str = "agent-or-human"
+    status: Literal["active", "stale", "superseded", "missing", "excluded"] = "active"
+    immutability: Literal["fingerprinted", "external", "copied"] = "fingerprinted"
+    domain: list[str] = Field(default_factory=list)
+    authority: Authority = Field(default_factory=Authority)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    canonical_source_key: str | None = None
+    current_revision_id: str | None = None
+    first_registered_at: str | None = None
+    last_refreshed_at: str | None = None

kc/models/source_range.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class Locator(BaseModel):
+    kind: Literal["line_range", "json_pointer", "csv_row_range", "page_text_range"] = "line_range"
+    start_line: int | None = None
+    end_line: int | None = None
+    pointer: str | None = None
+    start_row: int | None = None
+    end_row: int | None = None
+
+
+class SourceRangeRecord(BaseModel):
+    schema_version: Literal["kc.source_range.v1"] = "kc.source_range.v1"
+    range_id: str
+    source_id: str
+    revision_id: str | None = None
+    source_fingerprint: str
+    locator: Locator
+    text_hash: str
+    excerpt: str
+    tokens_estimate: int = 0
+    extracted_at: str
+    status: Literal["active", "superseded"] = "active"
+    metadata: dict[str, Any] = Field(default_factory=dict)

kc/models/source_revision.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SourceRevisionRecord(BaseModel):
+    schema_version: Literal["kc.source_revision.v1"] = "kc.source_revision.v1"
+    revision_id: str
+    source_id: str
+    uri: str
+    raw_fingerprint: str
+    normalized_fingerprint: str
+    media_type: str
+    extracted_at: str
+    status: Literal["active", "superseded"] = "active"
+    previous_revision_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)

kc/models/task.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class TaskRecord(BaseModel):
+    schema_version: Literal["kc.task.v1"] = "kc.task.v1"
+    task_id: str
+    goal: str
+    status: Literal[
+        "created",
+        "awaiting_agent",
+        "awaiting_validation",
+        "awaiting_apply",
+        "completed",
+        "blocked",
+        "cancelled",
+        "failed",
+    ] = "awaiting_agent"
+    context_pack_id: str | None = None
+    context_pack_path: str | None = None
+    created_at: str
+    updated_at: str
+    shape: str = "knowledge_page"
+    domain: list[str] = Field(default_factory=list)
+    candidate_sources: list[str] = Field(default_factory=list)
+    candidate_ranges: list[str] = Field(default_factory=list)
+    target_artifacts: list[str] = Field(default_factory=list)
+    agent_instructions: list[str] = Field(default_factory=list)
+    next_commands: list[str] = Field(default_factory=list)
+    expected_event_name: str | None = None
+    expected_event_schema: dict[str, Any] | None = None
+    events: list[dict[str, Any]] = Field(default_factory=list)