cuff-cli 0.1.0__py3-none-any.whl

cuff/__init__.py

@@ -0,0 +1,4 @@
+"""Cuff's host-neutral claim and evidence gate."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

cuff/__main__.py

@@ -0,0 +1,4 @@
+from cuff.cli import main
+
+
+raise SystemExit(main())

cuff/cli.py

@@ -0,0 +1,230 @@
+"""Cuff's intentionally small command line surface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .errors import CuffError
+from .gate import check
+from .ledger import append, create_claim, seal, verify
+from .subject import declared_subject, filesystem_subject
+from .workspace import find_workspace, initialize_workspace
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cuff")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    initialize = commands.add_parser("init", help="initialize a Cuff workspace")
+    initialize.add_argument("--workspace", type=Path)
+    initialize.add_argument("--json", action="store_true")
+
+    claim = commands.add_parser("claim", help="record a completion claim")
+    claim.add_argument("--workspace", type=Path)
+    claim.add_argument("--work-item", required=True)
+    claim.add_argument("--summary", required=True)
+    _add_subject_arguments(claim)
+    claim.add_argument("--actor")
+    claim.add_argument("--json", action="store_true")
+
+    verification = commands.add_parser("verify", help="run a command and record its result")
+    verification.add_argument("--workspace", type=Path)
+    verification.add_argument("--work-item", required=True)
+    verification.add_argument("--claim", required=True)
+    verification.add_argument("--timeout", type=float, default=300)
+    verification.add_argument("--actor")
+    verification.add_argument("--json", action="store_true")
+    verification.add_argument("verification_command", nargs=argparse.REMAINDER)
+
+    sealing = commands.add_parser("seal", help="atomically record a claim and executed evidence")
+    sealing.add_argument("--workspace", type=Path)
+    sealing.add_argument("--work-item", required=True)
+    sealing.add_argument("--summary", required=True)
+    _add_subject_arguments(sealing)
+    sealing.add_argument("--timeout", type=float, default=300)
+    sealing.add_argument("--actor")
+    sealing.add_argument("--json", action="store_true")
+    sealing.add_argument("verification_command", nargs=argparse.REMAINDER)
+
+    readiness = commands.add_parser("check", help="require fresh evidence for the latest claim")
+    readiness.add_argument("--workspace", type=Path)
+    readiness.add_argument("--work-item", required=True)
+    readiness.add_argument("--base")
+    readiness.add_argument("--head")
+    readiness.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    try:
+        if args.command == "init":
+            data = initialize_workspace(args.workspace)
+            return _finish(args, data, f"Cuff project: {data['status']}")
+
+        root = find_workspace(args.workspace)
+        if args.command == "claim":
+            subject = _subject(root, args)
+            record = create_claim(root, args.work_item, args.summary, subject, args.actor)
+            path, line = append(root, record)
+            return _finish(
+                args,
+                {"ok": True, "record": record, "path": str(path), "line": line},
+                f"Claim {record['id']} recorded for {record['work_item']}",
+            )
+        if args.command == "verify":
+            observed = verify(
+                root,
+                args.work_item,
+                args.claim,
+                _verification_command(args.verification_command),
+                timeout=args.timeout,
+                actor=args.actor,
+            )
+            data = {
+                "ok": observed.record["exit_code"] == 0,
+                "record": observed.record,
+                "path": str(observed.path),
+                "line": observed.line,
+                "timed_out": observed.timed_out,
+            }
+            return _finish_observation(
+                args,
+                data,
+                observed.stdout,
+                observed.stderr,
+                f"Evidence {observed.record['id']} recorded: exit {observed.record['exit_code']}",
+            )
+        if args.command == "seal":
+            sealed = seal(
+                root,
+                args.work_item,
+                args.summary,
+                _subject(root, args),
+                _verification_command(args.verification_command),
+                timeout=args.timeout,
+                actor=args.actor,
+            )
+            data = {
+                "ok": sealed.evidence["exit_code"] == 0,
+                "claim": sealed.claim,
+                "evidence": sealed.evidence,
+                "path": str(sealed.path),
+                "lines": sealed.lines,
+                "timed_out": sealed.timed_out,
+            }
+            return _finish_observation(
+                args,
+                data,
+                sealed.stdout,
+                sealed.stderr,
+                f"Claim {sealed.claim['id']} and evidence {sealed.evidence['id']} recorded: "
+                f"exit {sealed.evidence['exit_code']}",
+            )
+        if args.command == "check":
+            data = check(root, args.work_item, base=args.base, head=args.head)
+            return _finish_result(args, data, "Cuff readiness")
+        parser.error("unknown command")
+    except CuffError as exc:
+        return _finish_error(args, exc)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        if getattr(args, "json", False):
+            print(json.dumps({
+                "ok": False,
+                "errors": [{"code": "CUFF_UNEXPECTED", "message": f"{type(exc).__name__}: {exc}"}],
+            }, sort_keys=True, indent=2))
+        else:
+            print(f"CUFF_UNEXPECTED: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 3
+    return 2
+
+
+def _add_subject_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--subject-kind")
+    parser.add_argument("--subject-ref")
+    parser.add_argument("--subject-digest")
+    parser.add_argument("--subject-path", type=Path)
+
+
+def _subject(root: Path, args: argparse.Namespace) -> dict[str, str]:
+    declared = (args.subject_kind, args.subject_ref, args.subject_digest)
+    if args.subject_path is not None:
+        if any(value is not None for value in declared):
+            raise CuffError(
+                "CUFF_SUBJECT_INVALID",
+                "Choose either --subject-path or all declared subject arguments",
+            )
+        return filesystem_subject(root, args.subject_path)
+    if any(value is None for value in declared):
+        raise CuffError(
+            "CUFF_SUBJECT_REQUIRED",
+            "Pass --subject-path or --subject-kind, --subject-ref, and --subject-digest",
+        )
+    return declared_subject(*declared)
+
+
+def _verification_command(command: list[str]) -> list[str]:
+    return command[1:] if command[:1] == ["--"] else command
+
+
+def _finish(args: argparse.Namespace, data: dict[str, Any], message: str) -> int:
+    if args.json:
+        print(json.dumps(data, sort_keys=True, indent=2))
+    else:
+        print(message)
+    return 0
+
+
+def _finish_observation(
+    args: argparse.Namespace,
+    data: dict[str, Any],
+    stdout: bytes,
+    stderr: bytes,
+    message: str,
+) -> int:
+    if args.json:
+        print(json.dumps(data, sort_keys=True, indent=2))
+    else:
+        _replay(stdout, sys.stdout)
+        _replay(stderr, sys.stderr)
+        print(message)
+    return 0 if data["ok"] else 1
+
+
+def _finish_result(args: argparse.Namespace, data: dict[str, Any], label: str) -> int:
+    if args.json:
+        print(json.dumps(data, sort_keys=True, indent=2))
+    else:
+        print(f"{label}: {'PASS' if data['ok'] else 'FAIL'}")
+        for error in data["errors"]:
+            print(f"ERROR {error['code']}: {error['message']}")
+    return 0 if data["ok"] else 1
+
+
+def _finish_error(args: argparse.Namespace, error: CuffError) -> int:
+    data = {"ok": False, "errors": [error.to_dict()]}
+    if getattr(args, "json", False):
+        print(json.dumps(data, sort_keys=True, indent=2))
+    else:
+        print(str(error), file=sys.stderr)
+    return 1
+
+
+def _replay(content: bytes, stream: Any) -> None:
+    if content:
+        stream.write(content.decode(errors="replace"))
+        if not content.endswith(b"\n"):
+            stream.write("\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cuff/errors.py

@@ -0,0 +1,19 @@
+"""Small, stable failure shapes shared by the CLI and gate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CuffError(Exception):
+    code: str
+    message: str
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message, **self.context}

cuff/gate.py

@@ -0,0 +1,206 @@
+"""The single latest-claim readiness decision."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .errors import CuffError
+from .ledger import RECORDS_DIR, normalize_work_item, read, read_all
+from .subject import current_subject
+
+
+def check(
+    root: Path,
+    work_item: str,
+    *,
+    base: str | None = None,
+    head: str | None = None,
+) -> dict[str, Any]:
+    normalized = normalize_work_item(work_item)
+    result: dict[str, Any] = {
+        "ok": False,
+        "errors": [],
+        "work_item": normalized,
+        "latest_claim": None,
+        "selected_evidence": None,
+        "record_count": 0,
+    }
+    try:
+        read_all(root)
+        records = read(root, normalized)
+    except CuffError as exc:
+        result["errors"].append(exc.to_dict())
+        return result
+
+    result["record_count"] = len(records)
+    claims = [record for record in records if record["type"] == "claim"]
+    claim = claims[-1] if claims else None
+    result["latest_claim"] = claim
+
+    git_context = _check_git_workspace(root, base, head, result["errors"])
+    if claim is None:
+        _fail(result["errors"], "CUFF_CLAIM_MISSING", "No completion claim exists", work_item=normalized)
+        return result
+
+    passing = [
+        record
+        for record in records
+        if record["type"] == "evidence"
+        and record["claim"] == claim["id"]
+        and record["exit_code"] == 0
+    ]
+    for evidence in reversed(passing):
+        if not _subject_fresh(root, claim):
+            break
+        if git_context is None or not _evidence_fresh(root, evidence, head, git_context):
+            continue
+        result["selected_evidence"] = evidence
+        result["ok"] = not result["errors"]
+        return result
+
+    _fail(
+        result["errors"],
+        "CUFF_EVIDENCE_MISSING",
+        "Latest claim has no fresh passing evidence",
+        work_item=normalized,
+        record_id=claim["id"],
+    )
+    return result
+
+
+def _subject_fresh(root: Path, claim: dict[str, Any]) -> bool:
+    try:
+        return current_subject(root, claim["subject"]) == claim["subject"]
+    except CuffError:
+        return False
+
+
+def _check_git_workspace(
+    root: Path,
+    base: str | None,
+    head: str | None,
+    errors: list[dict[str, Any]],
+) -> tuple[Path, str] | None:
+    from . import git
+
+    try:
+        workspace = root.resolve()
+        repository = git.repo_root(workspace)
+        if repository != workspace:
+            raise CuffError(
+                "CUFF_WORKSPACE_NOT_ROOT",
+                "Cuff workspace must be the Git worktree root",
+                {"workspace": str(workspace), "repository": str(repository)},
+            )
+        dirty = [
+            path for path in git.dirty_paths(repository)
+            if not _is_record_path(repository, workspace, path)
+        ]
+        if dirty:
+            _fail(
+                errors,
+                "CUFF_REPOSITORY_DIRTY",
+                "Git readiness cannot evaluate uncommitted non-ledger changes",
+                paths=dirty,
+            )
+
+        proposed_ref = head or "HEAD"
+        proposed = git.head(repository, proposed_ref)
+        comparison_base = _comparison_base(repository, base, proposed_ref)
+        if comparison_base is not None:
+            if not git.is_ancestor(comparison_base, proposed, repository):
+                _fail(
+                    errors,
+                    "CUFF_GIT_ANCESTRY",
+                    "The comparison base is not an ancestor of the selected head",
+                    base=comparison_base,
+                    head=proposed,
+                )
+            _check_append_only(repository, workspace, comparison_base, head, errors)
+        return repository, proposed
+    except CuffError as exc:
+        errors.append(exc.to_dict())
+        return None
+
+
+def _comparison_base(repository: Path, base: str | None, proposed_ref: str) -> str | None:
+    from . import git
+
+    if base is not None:
+        return git.head(repository, base)
+    return git.default_base(repository, proposed_ref)
+
+
+def _check_append_only(
+    repository: Path,
+    root: Path,
+    base: str,
+    head: str | None,
+    errors: list[dict[str, Any]],
+) -> None:
+    from . import git
+
+    pathspec = _record_prefix(repository, root)
+    for status, path in git.diff_status(repository, base, head, pathspec):
+        target = (
+            git.show_file(repository, head, path)
+            if head is not None
+            else (repository / path).read_bytes()
+            if (repository / path).exists()
+            else None
+        )
+        if status == "A" and target is not None and target.endswith(b"\n"):
+            continue
+        if status == "M":
+            original = git.show_file(repository, base, path)
+            if (
+                original is not None
+                and target is not None
+                and target.startswith(original)
+                and target.endswith(b"\n")
+            ):
+                continue
+        _fail(
+            errors,
+            "CUFF_LEDGER_REWRITE",
+            "Ledger changes must only append complete lines",
+            path=path,
+            status=status,
+        )
+
+
+def _evidence_fresh(
+    root: Path,
+    evidence: dict[str, Any],
+    head: str | None,
+    git_context: tuple[Path, str],
+) -> bool:
+    from . import git
+
+    repository, proposed = git_context
+    try:
+        evidence_commit = git.head(repository, evidence["provenance"]["commit"])
+        if not git.is_ancestor(evidence_commit, proposed, repository):
+            return False
+        changed = git.changed_files(repository, evidence_commit, proposed if head is not None else None)
+        return not any(not _is_record_path(repository, root, path) for path in changed)
+    except CuffError:
+        return False
+
+
+def _record_prefix(repository: Path, root: Path) -> str:
+    try:
+        return (root / RECORDS_DIR).resolve().relative_to(repository.resolve()).as_posix()
+    except ValueError as exc:
+        raise CuffError("CUFF_NOT_A_REPOSITORY", "Cuff workspace is outside the selected repository") from exc
+
+
+def _is_record_path(repository: Path, root: Path, path: str) -> bool:
+    prefix = _record_prefix(repository, root)
+    normalized = path.replace("\\", "/")
+    return normalized == prefix or normalized.startswith(prefix + "/")
+
+
+def _fail(errors: list[dict[str, Any]], code: str, message: str, **context: Any) -> None:
+    errors.append({"code": code, "message": message, **context})

cuff/git.py

@@ -0,0 +1,113 @@
+"""The few Git operations required for provenance and freshness."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .errors import CuffError
+
+
+def _run(args: list[str], *, root: Path | str | None = None, check: bool = True) -> str:
+    try:
+        process = subprocess.run(
+            ["git", *args],
+            cwd=root,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=15,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CuffError("CUFF_GIT_FAILED", f"Git command could not complete: {exc}") from exc
+    if check and process.returncode != 0:
+        raise CuffError(
+            "CUFF_GIT_FAILED",
+            process.stderr.strip() or "Git command failed",
+            {"command": ["git", *args]},
+        )
+    return process.stdout
+
+
+def repo_root(cwd: Path | str | None = None) -> Path:
+    value = _run(["rev-parse", "--show-toplevel"], root=cwd, check=False).strip()
+    if not value:
+        raise CuffError("CUFF_NOT_A_REPOSITORY", "Cuff must run inside a Git repository")
+    return Path(value).resolve()
+
+
+def head(root: Path, ref: str = "HEAD") -> str:
+    value = _run(["rev-parse", "--verify", f"{ref}^{{commit}}"], root=root, check=False).strip()
+    if not value:
+        raise CuffError("CUFF_GIT_REF_INVALID", f"Git ref cannot be resolved: {ref}")
+    return value
+
+
+def is_ancestor(ancestor: str, descendant: str, root: Path) -> bool:
+    try:
+        process = subprocess.run(
+            ["git", "merge-base", "--is-ancestor", ancestor, descendant],
+            cwd=root,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            timeout=15,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CuffError("CUFF_GIT_FAILED", f"Git ancestry check could not complete: {exc}") from exc
+    if process.returncode in (0, 1):
+        return process.returncode == 0
+    raise CuffError("CUFF_GIT_FAILED", process.stderr.decode().strip() or "Git ancestry check failed")
+
+
+def default_base(root: Path, proposed_head: str = "HEAD") -> str | None:
+    parent = _run(["rev-parse", "--verify", f"{proposed_head}^"], root=root, check=False).strip()
+    return parent or None
+
+
+def changed_files(root: Path, start: str, end: str | None = None) -> list[str]:
+    args = ["-c", "core.quotePath=false", "diff", "--name-only", start]
+    if end is not None:
+        args.append(end)
+    return [line for line in _run(args, root=root).splitlines() if line]
+
+
+def dirty_paths(root: Path) -> list[str]:
+    tracked = _run(
+        ["-c", "core.quotePath=false", "diff", "--name-only", "HEAD"],
+        root=root,
+    ).splitlines()
+    untracked = _run(
+        ["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard"],
+        root=root,
+    ).splitlines()
+    return sorted({path for path in (*tracked, *untracked) if path})
+
+
+def diff_status(root: Path, base: str, head_ref: str | None, pathspec: str) -> list[tuple[str, str]]:
+    args = ["-c", "core.quotePath=false", "diff", "--name-status", "--no-renames", base]
+    if head_ref is not None:
+        args.append(head_ref)
+    args.extend(["--", pathspec])
+    rows: list[tuple[str, str]] = []
+    for line in _run(args, root=root).splitlines():
+        status, separator, path = line.partition("\t")
+        if separator:
+            rows.append((status, path))
+    return rows
+
+
+def show_file(root: Path, ref: str, path: str) -> bytes | None:
+    try:
+        process = subprocess.run(
+            ["git", "show", f"{ref}:{path}"],
+            cwd=root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=15,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CuffError("CUFF_GIT_FAILED", f"Historical ledger could not be read: {exc}") from exc
+    return process.stdout if process.returncode == 0 else None