cuff-cli 0.1.0__py3-none-any.whl

cuff/subject.py

@@ -0,0 +1,180 @@
+"""Closed subject identities and deterministic filesystem manifests."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from pathlib import Path
+from typing import Any
+
+from .errors import CuffError
+
+
+SUBJECT_FIELDS = {"kind", "ref", "digest"}
+SUBJECT_KIND_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,119}$")
+SHA256_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+FILESYSTEM_KINDS = {"file", "tree"}
+MAX_REF_BYTES = 2048
+MAX_FILES = 10_000
+MAX_BYTES = 256 * 1024 * 1024
+MAX_DEPTH = 64
+MAX_NAME_BYTES = 255
+
+
+def declared_subject(kind: str, ref: str, digest: str) -> dict[str, str]:
+    subject = {"kind": kind, "ref": ref, "digest": digest}
+    validate_subject(subject)
+    if kind in FILESYSTEM_KINDS:
+        raise CuffError(
+            "CUFF_SUBJECT_INVALID",
+            "The file and tree subject kinds are reserved for --subject-path",
+        )
+    return subject
+
+
+def validate_subject(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict) or set(value) != SUBJECT_FIELDS:
+        raise CuffError("CUFF_SUBJECT_INVALID", "Subject fields are invalid")
+    kind = value.get("kind")
+    ref = value.get("ref")
+    digest = value.get("digest")
+    if not isinstance(kind, str) or SUBJECT_KIND_RE.fullmatch(kind) is None:
+        raise CuffError("CUFF_SUBJECT_INVALID", "Subject kind must be a bounded lowercase token")
+    if (
+        not isinstance(ref, str)
+        or not ref
+        or len(ref.encode("utf-8")) > MAX_REF_BYTES
+        or any(ord(character) < 32 or ord(character) == 127 for character in ref)
+    ):
+        raise CuffError("CUFF_SUBJECT_INVALID", "Subject ref must be bounded text without controls")
+    if not isinstance(digest, str) or SHA256_RE.fullmatch(digest) is None:
+        raise CuffError("CUFF_SUBJECT_INVALID", "Subject digest must be lowercase SHA-256")
+    return {"kind": kind, "ref": ref, "digest": digest}
+
+
+def filesystem_subject(root: Path, path: Path) -> dict[str, str]:
+    workspace = root.resolve()
+    target, reference = _bounded_target(workspace, path)
+    target_stat = target.stat(follow_symlinks=False)
+    if stat.S_ISREG(target_stat.st_mode):
+        entries = [_file_entry(target, reference, target_stat)]
+        kind = "file"
+    elif stat.S_ISDIR(target_stat.st_mode):
+        entries = _tree_entries(workspace, target)
+        kind = "tree"
+    else:
+        raise CuffError(
+            "CUFF_SUBJECT_PATH_INVALID",
+            "Filesystem subjects must be regular files or directories",
+            {"path": str(path)},
+        )
+    total_bytes = sum(entry["bytes"] for entry in entries)
+    if len(entries) > MAX_FILES or total_bytes > MAX_BYTES:
+        raise CuffError(
+            "CUFF_SUBJECT_BOUNDS",
+            "Filesystem subject exceeds the file or byte bound",
+            {"files": len(entries), "bytes": total_bytes},
+        )
+    manifest = {"format": "cuff-manifest-1", "entries": entries}
+    encoded = json.dumps(
+        manifest,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode()
+    return {"kind": kind, "ref": reference, "digest": "sha256:" + hashlib.sha256(encoded).hexdigest()}
+
+
+def current_subject(root: Path, subject: dict[str, str]) -> dict[str, str]:
+    validated = validate_subject(subject)
+    if validated["kind"] not in FILESYSTEM_KINDS:
+        return validated
+    current = filesystem_subject(root, Path(validated["ref"]))
+    if current["kind"] != validated["kind"]:
+        raise CuffError("CUFF_SUBJECT_CHANGED", "Filesystem subject kind changed")
+    return current
+
+
+def _bounded_target(workspace: Path, path: Path) -> tuple[Path, str]:
+    raw = path.expanduser()
+    candidate = raw if raw.is_absolute() else workspace / raw
+    lexical = Path(os.path.abspath(candidate))
+    try:
+        relative = lexical.relative_to(workspace)
+    except ValueError as exc:
+        raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Subject path escapes the workspace") from exc
+    if relative.parts[:1] == (".cuff",):
+        raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Cuff controller state cannot be a subject")
+    current = workspace
+    for part in relative.parts:
+        if len(os.fsencode(part)) > MAX_NAME_BYTES:
+            raise CuffError("CUFF_SUBJECT_BOUNDS", "Filesystem subject name exceeds the bound")
+        current /= part
+        if current.is_symlink():
+            raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Filesystem subjects must not contain symlinks")
+    if not lexical.exists():
+        raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Filesystem subject does not exist")
+    resolved = lexical.resolve()
+    try:
+        resolved.relative_to(workspace)
+    except ValueError as exc:
+        raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Subject path escapes the workspace") from exc
+    reference = relative.as_posix() if relative.parts else "."
+    return resolved, reference
+
+
+def _tree_entries(workspace: Path, target: Path) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    total_bytes = 0
+    for directory, names, filenames in os.walk(target, topdown=True, followlinks=False):
+        directory_path = Path(directory)
+        relative_directory = directory_path.relative_to(target)
+        if len(relative_directory.parts) > MAX_DEPTH:
+            raise CuffError("CUFF_SUBJECT_BOUNDS", "Filesystem subject exceeds the depth bound")
+        for name in [*names, *filenames]:
+            if len(os.fsencode(name)) > MAX_NAME_BYTES:
+                raise CuffError("CUFF_SUBJECT_BOUNDS", "Filesystem subject name exceeds the bound")
+
+        kept_names: list[str] = []
+        for name in names:
+            candidate = directory_path / name
+            workspace_relative = candidate.relative_to(workspace)
+            if workspace_relative.parts[:1] == (".cuff",):
+                continue
+            directory_mode = candidate.stat(follow_symlinks=False).st_mode
+            if stat.S_ISLNK(directory_mode):
+                raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Filesystem subjects must not contain symlinks")
+            if not stat.S_ISDIR(directory_mode):
+                raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Filesystem subjects contain a special entry")
+            kept_names.append(name)
+        names[:] = sorted(kept_names, key=os.fsencode)
+
+        for name in sorted(filenames, key=os.fsencode):
+            candidate = directory_path / name
+            metadata = candidate.stat(follow_symlinks=False)
+            if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
+                raise CuffError("CUFF_SUBJECT_PATH_INVALID", "Filesystem subjects contain a special entry")
+            relative = candidate.relative_to(workspace).as_posix()
+            entries.append(_file_entry(candidate, relative, metadata))
+            total_bytes += metadata.st_size
+            if len(entries) > MAX_FILES or total_bytes > MAX_BYTES:
+                raise CuffError("CUFF_SUBJECT_BOUNDS", "Filesystem subject exceeds the file or byte bound")
+    entries.sort(key=lambda entry: os.fsencode(entry["path"]))
+    return entries
+
+
+def _file_entry(path: Path, reference: str, metadata: os.stat_result) -> dict[str, Any]:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return {
+        "path": reference,
+        "mode": stat.S_IMODE(metadata.st_mode),
+        "bytes": metadata.st_size,
+        "digest": "sha256:" + digest.hexdigest(),
+    }

cuff/workspace.py

@@ -0,0 +1,204 @@
+"""Safe selection and initialization of one Git-root Cuff workspace."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from . import git
+from .errors import CuffError
+from .ledger import RECORDS_DIR, init as init_records
+
+
+MAX_PARENT_WALK = 64
+PROJECT_PATH = Path(".cuff/project.json")
+PROJECT_MARKER = {"schema": 1}
+PROJECT_MARKER_BYTES = b'{"schema":1}\n'
+
+
+def initialize_workspace(
+    explicit: Path | None = None,
+    *,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    """Initialize only the caller-selected directory or current directory."""
+    start = (cwd or Path.cwd()).resolve()
+    root = _existing_directory(explicit or start, start)
+    _require_git_root(root)
+    state = root / ".cuff"
+    marker = root / PROJECT_PATH
+    _require_safe_state_paths(state, marker)
+    _require_safe_records_path(root / RECORDS_DIR)
+
+    existed = marker.exists()
+    if existed:
+        _read_marker(marker)
+    else:
+        state.mkdir(mode=0o755, exist_ok=True)
+    init_records(root)
+    if not existed:
+        _create_marker(marker)
+    return {
+        "ok": True,
+        "status": "already_initialized" if existed else "initialized",
+        "workspace": str(root),
+        "marker": dict(PROJECT_MARKER),
+    }
+
+
+def find_workspace(
+    explicit: Path | None = None,
+    *,
+    cwd: Path | None = None,
+) -> Path:
+    """Find and validate the explicit or nearest parent Cuff workspace."""
+    start = (cwd or Path.cwd()).resolve()
+    if explicit is not None:
+        root = _existing_directory(explicit, start)
+        _validate_project(root)
+        return root
+
+    current = start
+    for _ in range(MAX_PARENT_WALK):
+        state = current / ".cuff"
+        marker = current / PROJECT_PATH
+        if state.is_symlink() or (state.exists() and not state.is_dir()):
+            raise CuffError(
+                "CUFF_PATH_INVALID",
+                "Cuff state path in workspace discovery is unsafe",
+                {"path": str(state)},
+            )
+        if marker.exists() or marker.is_symlink():
+            _validate_project(current)
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    raise _not_initialized(start)
+
+
+def _validate_project(root: Path) -> None:
+    state = root / ".cuff"
+    marker = root / PROJECT_PATH
+    if not marker.exists() and not marker.is_symlink():
+        raise _not_initialized(root)
+    _require_safe_state_paths(state, marker)
+    _read_marker(marker)
+    _require_git_root(root)
+    records = root / RECORDS_DIR
+    _require_safe_records_path(records)
+    if not records.is_dir():
+        raise CuffError(
+            "CUFF_PROJECT_INVALID",
+            "Cuff records directory is missing or unsafe; rerun cuff init",
+            {"path": str(records)},
+        )
+
+
+def _require_git_root(root: Path) -> None:
+    repository = git.repo_root(root)
+    if repository != root.resolve():
+        raise CuffError(
+            "CUFF_WORKSPACE_NOT_ROOT",
+            "Cuff workspace must be the Git worktree root",
+            {"workspace": str(root.resolve()), "repository": str(repository)},
+        )
+
+
+def _existing_directory(path: Path, start: Path) -> Path:
+    candidate = path.expanduser()
+    if not candidate.is_absolute():
+        candidate = start / candidate
+    if candidate.is_symlink() or not candidate.is_dir():
+        raise CuffError(
+            "CUFF_WORKSPACE_INVALID",
+            "Workspace must be one existing non-symlink directory",
+            {"path": str(candidate)},
+        )
+    return candidate.resolve()
+
+
+def _require_safe_state_paths(state: Path, marker: Path) -> None:
+    if state.is_symlink() or (state.exists() and not state.is_dir()):
+        raise CuffError(
+            "CUFF_PATH_INVALID",
+            "Cuff state directory must be a non-symlink directory",
+            {"path": str(state)},
+        )
+    if marker.is_symlink() or (marker.exists() and not marker.is_file()):
+        raise CuffError(
+            "CUFF_PATH_INVALID",
+            "Cuff project marker must be a regular non-symlink file",
+            {"path": str(marker)},
+        )
+
+
+def _require_safe_records_path(records: Path) -> None:
+    if records.is_symlink() or (records.exists() and not records.is_dir()):
+        raise CuffError(
+            "CUFF_PATH_INVALID",
+            "Cuff records path must be a non-symlink directory",
+            {"path": str(records)},
+        )
+
+
+def _read_marker(path: Path) -> dict[str, int]:
+    try:
+        content = path.read_bytes()
+        data = json.loads(content, object_pairs_hook=_no_duplicate_keys)
+    except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as exc:
+        raise CuffError(
+            "CUFF_PROJECT_INCOMPATIBLE",
+            "Cuff project marker is incompatible; archive or remove only the marker and rerun cuff init",
+            {"path": str(path)},
+        ) from exc
+    if data != PROJECT_MARKER or content != PROJECT_MARKER_BYTES:
+        raise CuffError(
+            "CUFF_PROJECT_INCOMPATIBLE",
+            "Cuff project marker is incompatible; archive or remove only the marker and rerun cuff init",
+            {"path": str(path)},
+        )
+    return data
+
+
+def _create_marker(path: Path) -> None:
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile("wb", dir=path.parent, prefix=".project.", delete=False) as handle:
+            temporary = Path(handle.name)
+            handle.write(PROJECT_MARKER_BYTES)
+            handle.flush()
+            os.fsync(handle.fileno())
+        try:
+            os.link(temporary, path)
+        except FileExistsError:
+            _read_marker(path)
+        descriptor = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    finally:
+        if temporary is not None and temporary.exists():
+            temporary.unlink()
+
+
+def _no_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in data:
+            raise ValueError(f"duplicate JSON key: {key}")
+        data[key] = value
+    return data
+
+
+def _not_initialized(path: Path) -> CuffError:
+    return CuffError(
+        "CUFF_PROJECT_NOT_INITIALIZED",
+        "No Cuff project was found; run cuff init or pass --workspace",
+        {"path": str(path)},
+    )

cuff_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: cuff-cli
+Version: 0.1.0
+Summary: Cuff subject-bound claim, evidence, and verification gate.
+Author: Fab7
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="Cuff check flow: bind the subject, observe the verifier, require fresh evidence" width="100%" />
+</p>
+
+# Cuff
+
+**Make claims checkable. Reject evidence when stale.**
+
+Cuff ties one completion claim to one exact subject, runs the verifier you
+choose, and checks whether the latest passing evidence still matches the
+current Git state.
+
+It turns a completion statement into a durable, checkable record without
+deciding what should prove the work or what action should follow.
+
+## Requirements
+
+- Python 3.11 or newer;
+- `uv` on `PATH` (`0.11.32` is the tested recommendation); and
+- an existing Git worktree. Its root is the only valid Cuff workspace.
+
+Git is mandatory. Cuff never initializes a repository, selects another
+worktree, or stages, commits, fetches, pushes, releases, or deploys anything.
+
+## Install
+
+Install a released version as a standard uv-managed tool:
+
+```bash
+uv tool install cuff-cli==0.1.0
+cuff --version
+```
+
+For local development, install the checkout explicitly:
+
+```bash
+uv tool install --editable .
+```
+
+Cuff has no runtime dependencies. It is distributed as a standard wheel and
+source distribution; it contains no bundled Python or native executable.
+
+## Five-command quickstart
+
+Run initialization at the exact Git worktree root:
+
+```bash
+cuff init --json
+git add .cuff/project.json
+git commit -m "Initialize Cuff"
+```
+
+The marker is exactly `{"schema":1}` and records live under
+`.cuff/records/`. An incompatible marker is never rewritten or migrated.
+
+The preferred path atomically appends a claim and its observed evidence:
+
+```bash
+cuff seal \
+  --work-item task-1 \
+  --summary "Implementation complete" \
+  --subject-path src \
+  --json \
+  -- python -m pytest
+
+cuff check --work-item task-1 --json
+```
+
+The split path is available when the claim must exist before verification:
+
+```bash
+cuff claim \
+  --work-item task-1 \
+  --summary "Implementation complete" \
+  --subject-path src \
+  --json
+
+cuff verify \
+  --work-item task-1 \
+  --claim rec_REPLACE_ME \
+  --json \
+  -- python -m pytest
+```
+
+The public surface is exactly:
+
+```text
+cuff init
+cuff claim
+cuff verify
+cuff seal
+cuff check
+```
+
+Every claim, verification, seal, and check names its work item explicitly.
+Declared subjects use the complete `{kind, ref, digest}` identity; file and
+tree subjects use `--subject-path` and a Cuff-computed manifest digest.
+
+## Proof boundary
+
+- Claims and evidence are closed generation-1 JSONL records.
+- Every evidence record contains the `HEAD` commit observed before execution.
+- Verifier argv is executed literally without a shell.
+- Non-ledger dirtiness before or after verification records no evidence.
+- `seal` appends its linked pair in one locked atomic replacement.
+- `check` enforces subject freshness, commit ancestry, changed paths,
+  non-ledger cleanliness, and append-only ledger changes.
+
+Cuff treats verifier argv as opaque. It does not select the command, import an
+extension, interpret domain output, or grant merge, release, deployment,
+spend, or residual-risk authority.
+
+## Static host integrations
+
+Small native assets live in [`plugins/claude/cuff`](plugins/claude/cuff) and
+[`plugins/codex/cuff`](plugins/codex/cuff). The corresponding host plugin
+manager owns their installation and removal. These assets require only the
+uv-managed `cuff` executable on `PATH`; Cuff itself does not install plugins.
+
+```bash
+# Codex
+codex plugin marketplace add fab7hq/cuff --ref v0.1.0
+codex plugin add cuff@fab7hq
+
+# Claude Code
+claude plugin marketplace add fab7hq/cuff@v0.1.0
+claude plugin install cuff@fab7hq --scope user
+```
+
+See [RUNBOOK.md](RUNBOOK.md) for operations, [the architecture overview](docs/architecture/overview.md)
+for ownership, and [the ledger contract](docs/architecture/ledger.md) for the
+record and gate invariants.
+
+## Development
+
+```bash
+uv sync --locked
+uv run --locked python -m pytest
+uv run --locked python -m compileall -q core/cuff
+uv build
+git diff --check
+```
+
+## Community and support
+
+- Use [Cuff Discussions](https://github.com/fab7hq/cuff/discussions) for usage questions and design proposals.
+- Report reproducible defects through [GitHub Issues](https://github.com/fab7hq/cuff/issues/new/choose).
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change.
+- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+Cuff is licensed under the [Apache License 2.0](LICENSE).

cuff_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+cuff/__init__.py,sha256=j7VeQDzYOCfi6j72wCBo99g9xUmJxyVZRsyBqFvd-iM,100
+cuff/__main__.py,sha256=8F2QDwc1Aevh_MqyENACDK1freyN9sNexmi7IKlbfGU,53
+cuff/cli.py,sha256=wM3jJQi5c_ozBrXDGggjjohNnSkCwES9W3J5d7jesAg,8514
+cuff/errors.py,sha256=Hl_g101k6efJNKIwVnAbG0_7kstCT3ZU_ix1CtEp85E,489
+cuff/gate.py,sha256=t4LUXx1ON4hf6u1eftstyJXRtqNXhtA0MsOaootSUp0,6493
+cuff/git.py,sha256=bM-x67Q_vD29dENvm8bgl5dFWDFtUig1RRYN8fl8B68,4029
+cuff/ledger.py,sha256=Us73NcbxDSDFOXmLRHBDamt9x7OE1PoUL_FaujgOn8I,22763
+cuff/subject.py,sha256=0S2e0dz1UOM8WQoBO21WjAW3XNJS8zyRUn8t-UEdqNY,7576
+cuff/workspace.py,sha256=9ANo_L01GFzD3GURlWDDXS_q5iST2dFfzIWAEazT6NI,6465
+cuff_cli-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cuff_cli-0.1.0.dist-info/METADATA,sha256=OXbJ992OkxEGR0nw2kC_2I9734jGTRpN6ElIS1GY3Do,4725
+cuff_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cuff_cli-0.1.0.dist-info/entry_points.txt,sha256=xDe9VI-R88K9P5llkgU6MOH44Ui0_7SeYr7mLQkS1_U,39
+cuff_cli-0.1.0.dist-info/top_level.txt,sha256=zOwA6w7ZmmamL--uv26Xgrfp9rFSbBIt-69kDEPjK-k,5
+cuff_cli-0.1.0.dist-info/RECORD,,

cuff_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cuff_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cuff = cuff.cli:main