kc-cli 0.4.0__py3-none-any.whl

kc/__init__.py

@@ -0,0 +1,5 @@
+"""kc — deterministic knowledge compiler harness."""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"

kc/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from kc.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

kc/artifacts/__init__.py

@@ -0,0 +1 @@
+"""Artifact parsing, validation, and diff helpers."""

kc/artifacts/diff.py

@@ -0,0 +1,76 @@
+"""Structured artifact diff planning."""
+
+from __future__ import annotations
+
+import difflib
+from datetime import UTC, datetime
+from pathlib import Path
+
+from kc.fingerprints import raw_fingerprint
+from kc.ids import new_id
+from kc.models.plan import PlanCondition, PlanOperation, PlanRecord
+
+
+def build_artifact_plan(
+    path: Path,
+    *,
+    registered_fingerprint: str | None,
+    baseline_path: Path | None = None,
+    mode: str = "dry_run",
+    idempotency_key: str | None = None,
+) -> tuple[PlanRecord, str, dict[str, str | None]]:
+    after = raw_fingerprint(path) if path.exists() else None
+    before = registered_fingerprint
+    baseline: dict[str, str | None] = {"kind": "unavailable", "path": None, "fingerprint": before}
+    old_lines: list[str] = []
+    if baseline_path is not None and baseline_path.exists():
+        old_lines = baseline_path.read_text(encoding="utf-8-sig").splitlines(keepends=True)
+        baseline = {
+            "kind": "last_applied_snapshot",
+            "path": baseline_path.as_posix(),
+            "fingerprint": raw_fingerprint(baseline_path),
+        }
+    new_lines = (
+        path.read_text(encoding="utf-8-sig").splitlines(keepends=True) if path.exists() else []
+    )
+    if before is None:
+        risk_flags = ["new_artifact"]
+        old_label = "/dev/null"
+    else:
+        risk_flags = ["updates_existing_artifact"] if before != after else []
+        old_label = baseline_path.as_posix() if baseline_path is not None and baseline_path.exists() else f"{path.as_posix()}@registry"
+    diff_text = "".join(
+        difflib.unified_diff(
+            old_lines,
+            new_lines,
+            fromfile=old_label,
+            tofile=path.as_posix(),
+        )
+    )
+    risk = "medium" if risk_flags else "low"
+    plan = PlanRecord(
+        plan_id=new_id("plan"),
+        created_at=datetime.now(UTC).isoformat(),
+        command="artifact.apply",
+        mode=mode,  # type: ignore[arg-type]
+        idempotency_key=idempotency_key,
+        operations=[
+            PlanOperation(
+                op_id="op_01",
+                kind="register_artifact",
+                path=path.as_posix(),
+                before_fingerprint=before,
+                after_fingerprint=after,
+                risk=risk,  # type: ignore[arg-type]
+                requires_yes=True,
+            )
+        ],
+        preconditions=[
+            PlanCondition(kind="file_exists", path=path.as_posix(), expected="true"),
+        ],
+        postconditions=[
+            PlanCondition(kind="artifact_validates", path=path.as_posix()),
+        ],
+        risk_flags=risk_flags,
+    )
+    return plan, diff_text, baseline

kc/artifacts/frontmatter.py

@@ -0,0 +1,26 @@
+"""Markdown frontmatter parsing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    if not text.startswith("---\n") and not text.startswith("---\r\n"):
+        return {}, text
+    normalized = text.replace("\r\n", "\n")
+    parts = normalized.split("---\n", 2)
+    if len(parts) < 3:
+        return {}, text
+    raw = parts[1]
+    body = parts[2]
+    data = yaml.safe_load(raw) or {}
+    if not isinstance(data, dict):
+        data = {}
+    return data, body
+
+
+def dump_frontmatter(data: dict[str, Any], body: str) -> str:
+    return "---\n" + yaml.safe_dump(data, sort_keys=False) + "---\n" + body.lstrip("\n")

kc/artifacts/markdown.py

@@ -0,0 +1,116 @@
+"""Markdown artifact helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from kc.artifacts.frontmatter import parse_frontmatter
+from kc.provenance.citations import has_citation_or_marker
+
+
+def read_markdown_artifact(path: Path) -> tuple[dict[str, Any], str, str]:
+    text = path.read_text(encoding="utf-8-sig")
+    frontmatter, body = parse_frontmatter(text)
+    return frontmatter, body, text
+
+
+def markdown_body_line_offset(text: str) -> int:
+    normalized = text.replace("\r\n", "\n")
+    if not normalized.startswith("---\n"):
+        return 0
+    parts = normalized.split("---\n", 2)
+    if len(parts) < 3:
+        return 0
+    return ("---\n" + parts[1] + "---\n").count("\n")
+
+
+def required_section_names(body: str) -> set[str]:
+    headings = set()
+    for line in body.splitlines():
+        if line.startswith("## "):
+            headings.add(line[3:].strip().lower())
+    return headings
+
+
+def citation_coverage_issues(
+    body: str,
+    *,
+    status: str,
+    requires_citations: bool,
+    allow_uncited: bool,
+    line_offset: int = 0,
+) -> list[dict[str, Any]]:
+    issues: list[dict[str, Any]] = []
+    if not requires_citations:
+        return issues
+
+    in_code = False
+    paragraph: list[tuple[int, str]] = []
+
+    def flush() -> None:
+        nonlocal paragraph
+        if not paragraph:
+            return
+        text = " ".join(line for _line_no, line in paragraph).strip()
+        first_line = paragraph[0][0]
+        paragraph = []
+        if not text:
+            return
+        if text.startswith("#"):
+            return
+        if text.startswith("|") and text.endswith("|"):
+            return
+        if has_citation_or_marker(text):
+            if "[kc:uncited]" in text and not allow_uncited:
+                issues.append(
+                    {
+                        "code": "KC_VALIDATION_MISSING_CITATION",
+                        "message": "[kc:uncited] is not allowed without --allow-uncited.",
+                        "line": first_line,
+                    }
+                )
+            if "[kc:todo]" in text and status != "draft":
+                issues.append(
+                    {
+                        "code": "KC_VALIDATION_TODO_IN_ACTIVE_ARTIFACT",
+                        "message": "[kc:todo] is allowed only for draft artifacts.",
+                        "line": first_line,
+                    }
+                )
+            return
+        issues.append(
+            {
+                "code": "KC_VALIDATION_MISSING_CITATION",
+                "message": "Paragraph requires at least one citation token or explicit kc marker.",
+                "line": first_line,
+            }
+        )
+
+    for line_no, raw_line in enumerate(body.splitlines(), start=1 + line_offset):
+        line = raw_line.strip()
+        if line.startswith("```"):
+            flush()
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+        if not line:
+            flush()
+            continue
+        if line.startswith("#"):
+            flush()
+            continue
+        paragraph.append((line_no, line))
+    flush()
+    return issues
+
+
+def markdown_title(frontmatter: dict[str, Any], body: str, fallback: str) -> str:
+    title = frontmatter.get("title")
+    if isinstance(title, str) and title.strip():
+        return title.strip()
+    for line in body.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return fallback

kc/atomic_write.py

@@ -0,0 +1,33 @@
+"""Atomic file writing helpers."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_bytes(target: Path, data: bytes) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=target.parent, prefix=".kc_tmp_", suffix=target.suffix)
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, target)
+    except Exception:
+        if tmp_path.exists():
+            tmp_path.unlink()
+        raise
+
+
+def atomic_write_text(target: Path, text: str) -> None:
+    atomic_write_bytes(target, text.encode("utf-8"))
+
+
+def copy_snapshot(src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)

kc/cli.py

@@ -0,0 +1,284 @@
+"""Typer CLI application for kc."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Any
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from kc.errors import KcError
+from kc.output import emit_error, init_request, is_interactive, is_llm_mode, state
+
+
+def _value_after(args: list[str], option: str) -> str | None:
+    for idx, item in enumerate(args):
+        if item == option and idx + 1 < len(args):
+            return args[idx + 1]
+        if item.startswith(f"{option}="):
+            return item.split("=", 1)[1]
+    return None
+
+
+def _initialize_error_state(args: list[str]) -> None:
+    if not state.request_id:
+        init_request(_value_after(args, "--request-id"))
+    requested_format = _value_after(args, "--format") or _value_after(args, "-f")
+    state.format = requested_format if requested_format in {"json", "table", "markdown"} else "json"
+    if is_llm_mode():
+        state.format = "json"
+    state.root_override = _value_after(args, "--root")
+    state.data_dir = _value_after(args, "--data-dir")
+    state.state_dir = _value_after(args, "--state-dir")
+    state.quiet = True
+
+
+def _command_id_from_args(args: list[str]) -> str:
+    value_opts = {"--format", "-f", "--root", "--data-dir", "--state-dir", "--request-id"}
+    top_level = {
+        "guide",
+        "conformance",
+        "init",
+        "status",
+        "lint",
+        "export",
+        "source",
+        "index",
+        "context",
+        "artifact",
+        "citation",
+        "task",
+        "eval",
+        "doctor",
+    }
+    tokens: list[str] = []
+    index = 0
+    while index < len(args):
+        item = args[index]
+        if item in value_opts:
+            index += 2
+            continue
+        if any(item.startswith(f"{opt}=") for opt in value_opts):
+            index += 1
+            continue
+        if item.startswith("-"):
+            index += 1
+            continue
+        tokens.append(item)
+        if len(tokens) == 2:
+            break
+        index += 1
+    if not tokens or tokens[0] not in top_level:
+        return "kc"
+    if tokens[0] in {"source", "index", "context", "artifact", "citation", "task", "eval"} and len(tokens) > 1:
+        return f"{tokens[0]}.{tokens[1]}"
+    if tokens[0] == "doctor" and len(tokens) > 1:
+        return f"doctor.{tokens[1]}"
+    return tokens[0]
+
+
+class FlexibleGroup(TyperGroup):
+    """Allow root global options before or after the first subcommand."""
+
+    _VALUE_OPTS = frozenset(("--format", "-f", "--root", "--data-dir", "--state-dir", "--request-id"))
+    _FLAG_OPTS = frozenset(("--quiet", "-q", "--no-input", "--version", "-V"))
+    _VALUE_PREFIXES = ("--format=", "--root=", "--data-dir=", "--state-dir=", "--request-id=")
+
+    def main(
+        self,
+        args: list[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        **extra: Any,
+    ) -> object:
+        raw_args = list(sys.argv[1:] if args is None else args)
+        try:
+            result = super().main(
+                args=raw_args,
+                prog_name=prog_name,
+                complete_var=complete_var,
+                standalone_mode=False,
+                **extra,
+            )
+            if standalone_mode:
+                raise SystemExit(result if isinstance(result, int) else 0)
+            return result
+        except click.UsageError as exc:
+            if not standalone_mode:
+                raise
+            _initialize_error_state(raw_args)
+            emit_error(
+                _command_id_from_args(raw_args),
+                KcError(
+                    code="KC_USAGE_ERROR",
+                    message=exc.format_message(),
+                    details={"usage": exc.format_message()},
+                ),
+            )
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        cmd_idx: int | None = None
+        i = 0
+        while i < len(args):
+            item = args[i]
+            if not item.startswith("-"):
+                cmd_idx = i
+                break
+            if item in self._VALUE_OPTS:
+                i += 2
+                continue
+            if item.startswith(self._VALUE_PREFIXES):
+                i += 1
+                continue
+            i += 1
+        if cmd_idx is None:
+            return super().parse_args(ctx, args)
+        before = list(args[:cmd_idx])
+        cmd_and_after = list(args[cmd_idx:])
+        cmd_name = cmd_and_after[0]
+        sub_cmd = self.commands.get(cmd_name) if self.commands else None
+        sub_opts: set[str] = set()
+        if sub_cmd:
+            for param in sub_cmd.params:
+                sub_opts.update(param.opts)
+                sub_opts.update(getattr(param, "secondary_opts", []))
+        moved: list[str] = []
+        kept: list[str] = [cmd_name]
+        i = 1
+        end_of_opts = False
+        while i < len(cmd_and_after):
+            item = cmd_and_after[i]
+            if item == "--":
+                end_of_opts = True
+                kept.append(item)
+                i += 1
+                continue
+            if not end_of_opts and item in self._VALUE_OPTS and item not in sub_opts:
+                moved.append(item)
+                if i + 1 < len(cmd_and_after):
+                    i += 1
+                    moved.append(cmd_and_after[i])
+                i += 1
+                continue
+            if not end_of_opts and item in self._FLAG_OPTS and item not in sub_opts:
+                moved.append(item)
+                i += 1
+                continue
+            if (
+                not end_of_opts
+                and item.startswith(self._VALUE_PREFIXES)
+                and not any(item.startswith(f"{opt}=") for opt in sub_opts)
+            ):
+                moved.append(item)
+                i += 1
+                continue
+            kept.append(item)
+            i += 1
+        return super().parse_args(ctx, before + moved + kept)
+
+
+app = typer.Typer(
+    name="kc",
+    cls=FlexibleGroup,
+    help=(
+        "kc — deterministic knowledge compiler harness.\n\n"
+        "Agents provide the intelligence. kc provides source registration, search, "
+        "context preparation, citation validation, safe apply, and task state."
+    ),
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from kc import __version__
+
+        typer.echo(f"kc {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format: json, table, or markdown."),
+    ] = "json",
+    root: Annotated[
+        str | None, typer.Option("--root", help="Workspace root override.")
+    ] = None,
+    data_dir: Annotated[
+        str | None, typer.Option("--data-dir", help="Knowledge data directory override.")
+    ] = None,
+    state_dir: Annotated[str | None, typer.Option("--state-dir", help="kc state directory override.")] = None,
+    quiet: Annotated[
+        bool, typer.Option("--quiet", "-q", help="Suppress stderr diagnostics.")
+    ] = False,
+    request_id: Annotated[
+        str | None, typer.Option("--request-id", help="Trace request ID.")
+    ] = None,
+    no_input: Annotated[
+        bool, typer.Option("--no-input", help="Fail instead of prompting.")
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    del version
+    init_request(request_id)
+    state.root_override = root
+    state.data_dir = data_dir
+    state.state_dir = state_dir
+    state.workspace_root = None
+    state.workspace_resolution_source = None
+    state.no_input = no_input or is_llm_mode()
+    if format not in {"json", "table", "markdown"}:
+        from kc.errors import KcError
+        from kc.output import emit_error
+
+        state.format = "json"
+        emit_error(
+            "kc",
+            KcError(
+                code="KC_VALIDATION_INVALID_ARGUMENT",
+                message=f"Unknown output format: {format}",
+                details={"requested": format, "supported": ["json", "table", "markdown"]},
+            ),
+        )
+    state.format = "json" if is_llm_mode() else format
+    state.quiet = quiet or is_llm_mode() or not is_interactive()
+
+
+from kc.commands import artifact, citation, context, doctor, eval, index, source, task  # noqa: E402
+from kc.commands import conformance as conformance_command  # noqa: E402
+from kc.commands import export as export_command  # noqa: E402
+from kc.commands import guide as guide_command  # noqa: E402
+from kc.commands import init as init_command  # noqa: E402
+from kc.commands import lint as lint_command  # noqa: E402
+from kc.commands import status as status_command  # noqa: E402
+
+guide_command.register(app)
+conformance_command.register(app)
+init_command.register(app)
+status_command.register(app)
+lint_command.register(app)
+export_command.register(app)
+app.add_typer(source.app, name="source")
+app.add_typer(index.app, name="index")
+app.add_typer(context.app, name="context")
+app.add_typer(artifact.app, name="artifact")
+app.add_typer(citation.app, name="citation")
+app.add_typer(task.app, name="task")
+app.add_typer(eval.app, name="eval")
+app.add_typer(doctor.app, name="doctor")

kc/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""