claude-company 0.1.0

package/.claude/hooks/_common.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Shared helpers for the claude-company enforcement hooks.
+
+Python 3 stdlib only. Everything here fails open: on any internal error the
+callers should treat the result as "allow" rather than bricking the session.
+The one deliberate exception is git-tracked uncertainty in the immutability
+checks, which fail safe (treat as tracked) per the frozen-surface contract.
+"""
+
+import datetime
+import hashlib
+import json
+import os
+import subprocess
+import sys
+
+# Documented anti-accident salt (not anti-adversary). Bump the suffix only on a
+# real stamp-format change.
+CHECKSUM_SALT = "claude-company.gates.v1"
+
+
+def read_stdin_json():
+    """Parse the hook JSON payload from stdin. None on any failure."""
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return None
+
+
+def project_root(payload):
+    """Resolve the project root: CLAUDE_PROJECT_DIR, else stdin cwd, else cwd."""
+    root = os.environ.get("CLAUDE_PROJECT_DIR")
+    if root:
+        return root
+    if isinstance(payload, dict):
+        cwd = payload.get("cwd")
+        if cwd:
+            return cwd
+    return os.getcwd()
+
+
+def iso_now():
+    return datetime.datetime.now(datetime.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+
+def adherence_log(root, hook_name, action, target, reason):
+    """Append one line to company/state/adherence.log. Never raises."""
+    try:
+        state_dir = os.path.join(root, "company", "state")
+        os.makedirs(state_dir, exist_ok=True)
+        target = (target or "").replace("\n", " ")
+        reason = (reason or "").replace("\n", " ")
+        line = "{} | {} | {} | {} | {}\n".format(
+            iso_now(), hook_name, action, target, reason
+        )
+        with open(os.path.join(state_dir, "adherence.log"), "a") as f:
+            f.write(line)
+    except Exception:
+        pass
+
+
+def block(root, hook_name, target, short_reason, message):
+    """Log a BLOCK line, print the human message to stderr, exit 2."""
+    adherence_log(root, hook_name, "BLOCK", target, short_reason)
+    print(message, file=sys.stderr)
+    sys.exit(2)
+
+
+def log_bypass(root, hook_name, target, short_reason):
+    adherence_log(root, hook_name, "BYPASS", target, short_reason)
+
+
+def read_json_file(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def active_task(root):
+    return read_json_file(
+        os.path.join(root, "company", "state", "active-task.json")
+    )
+
+
+def gates_config(root):
+    return read_json_file(os.path.join(root, "company", "gates.config"))
+
+
+def rel_path(root, file_path):
+    """Project-relative, forward-slash path for file_path under root.
+
+    Falls back to the input (minus a leading slash) when file_path is outside
+    the project tree.
+    """
+    if not file_path:
+        return ""
+    norm = file_path.replace("\\", "/")
+    try:
+        root_norm = os.path.abspath(root).replace("\\", "/").rstrip("/")
+        if norm.startswith("/"):
+            candidate = norm
+        else:
+            candidate = root_norm + "/" + norm
+        candidate = os.path.normpath(candidate).replace("\\", "/")
+        if candidate == root_norm:
+            return ""
+        if candidate.startswith(root_norm + "/"):
+            return candidate[len(root_norm) + 1:]
+    except Exception:
+        pass
+    return norm.lstrip("/")
+
+
+def _git(root, args):
+    try:
+        result = subprocess.run(
+            ["git", "-C", root] + args, capture_output=True, timeout=5
+        )
+    except Exception:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.decode("utf-8", "replace")
+
+
+def current_branch(root):
+    """Current branch name, or None on git uncertainty."""
+    out = _git(root, ["symbolic-ref", "--short", "HEAD"])
+    if out is None:
+        return None
+    return out.strip() or None
+
+
+def is_git_tracked(file_path):
+    """True if committed/staged in git (shipped, immutable).
+
+    Returns True on any uncertainty (git missing, not a repo) so immutability
+    checks fail safe. Returncode 1 is a real untracked file inside a repo,
+    which is the freshly generated artifact we want to leave editable.
+    """
+    directory = os.path.dirname(file_path) or "."
+    try:
+        result = subprocess.run(
+            ["git", "-C", directory, "ls-files", "--error-unmatch", file_path],
+            capture_output=True,
+            timeout=5,
+        )
+    except Exception:
+        return True
+    return result.returncode != 1
+
+
+def work_hash(root):
+    """Fingerprint the working tree. Fail-open to 'no-git'.
+
+    company/state/ is excluded from the fingerprint: the stamp and adherence
+    log live there and would otherwise self-invalidate the hash the moment they
+    are written.
+    """
+    exclude = ["--", ".", ":(exclude)company/state"]
+    head = _git(root, ["rev-parse", "HEAD"])
+    status = _git(root, ["status", "--porcelain"] + exclude)
+    diff = _git(root, ["diff"] + exclude)
+    cached = _git(root, ["diff", "--cached"] + exclude)
+    if head is None and status is None and diff is None and cached is None:
+        return "no-git"
+    digest = hashlib.sha256()
+    for part in (head, status, diff, cached):
+        digest.update((part or "").encode("utf-8", "replace"))
+        digest.update(b"\x00")
+    return digest.hexdigest()
+
+
+def stamp_checksum(payload_without_checksum):
+    """sha256 of canonical stamp payload plus the salt."""
+    canonical = json.dumps(
+        payload_without_checksum, sort_keys=True, separators=(",", ":")
+    )
+    return hashlib.sha256(
+        (canonical + CHECKSUM_SALT).encode("utf-8")
+    ).hexdigest()
+
+
+def read_stamp(root):
+    return read_json_file(
+        os.path.join(root, "company", "state", "gates.status")
+    )
+
+
+def check_stamp(root):
+    """Return (ok, reason). ok iff the stamp is green, fresh, and valid."""
+    stamp = read_stamp(root)
+    if stamp is None:
+        return False, "no gates.status stamp (gates have not been run)"
+    if not isinstance(stamp, dict):
+        return False, "gates.status is malformed"
+    stored = stamp.get("checksum")
+    payload = {k: v for k, v in stamp.items() if k != "checksum"}
+    if stored != stamp_checksum(payload):
+        return False, "gates.status checksum invalid (stamp edited by hand)"
+    if stamp.get("status") != "green":
+        return False, "gates are red (last run had failing gates)"
+    if stamp.get("work_hash") != work_hash(root):
+        return False, "gates.status is stale (work changed since gates ran)"
+    return True, "green"

package/.claude/hooks/gate_stamp.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Gate stamp CLI (NOT a hook). Called by the gate runner.
+
+  python3 gate_stamp.py --results '{"gates":[{"name":"tests","ok":true}]}'
+      Compute overall status (green iff every gate ok), the work hash, and a
+      checksum, then write company/state/gates.status.
+
+  python3 gate_stamp.py --check
+      Exit 0 if the stamp is green + fresh + valid, else exit 1 with a reason.
+
+Project root comes from CLAUDE_PROJECT_DIR, falling back to the cwd.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _common as c  # noqa: E402
+
+
+def resolve_root():
+    return os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+
+
+def write_stamp(root, results_json):
+    data = json.loads(results_json)
+    gates = data.get("gates", []) or []
+    all_ok = all(bool(g.get("ok")) for g in gates)
+    status = "green" if all_ok else "red"
+    payload = {
+        "status": status,
+        "ran_at": c.iso_now(),
+        "work_hash": c.work_hash(root),
+        "gates": gates,
+    }
+    payload["checksum"] = c.stamp_checksum(
+        {k: v for k, v in payload.items() if k != "checksum"}
+    )
+    state_dir = os.path.join(root, "company", "state")
+    os.makedirs(state_dir, exist_ok=True)
+    with open(os.path.join(state_dir, "gates.status"), "w") as f:
+        json.dump(payload, f, indent=2)
+        f.write("\n")
+    return status
+
+
+def main():
+    ap = argparse.ArgumentParser(description="claude-company gate stamp")
+    ap.add_argument("--results", help="JSON gate results")
+    ap.add_argument("--check", action="store_true", help="verify stamp")
+    args = ap.parse_args()
+
+    root = resolve_root()
+
+    if args.check:
+        ok, reason = c.check_stamp(root)
+        print(reason)
+        sys.exit(0 if ok else 1)
+
+    if args.results:
+        try:
+            status = write_stamp(root, args.results)
+        except Exception as exc:
+            print("gate_stamp: failed to write stamp: {}".format(exc),
+                  file=sys.stderr)
+            sys.exit(1)
+        print("wrote gates.status: {}".format(status))
+        sys.exit(0)
+
+    ap.print_help()
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/gates_detect.py

@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+"""gates_detect.py - sniff a project and propose real mechanical gates.
+
+CLI (not a hook): `python3 .claude/hooks/gates_detect.py [--write]`.
+
+Detects the project stack (JS/TS, Python, Go, Rust, Makefile) and proposes
+concrete gate commands ordered cheap-to-expensive (lint, typecheck, tests,
+build). Only commands whose tool is actually invocable (shutil.which on the
+binary) are proposed; the rest are reported as "detected_but_missing_tool" and
+skipped on --write.
+
+Without --write: prints a human table plus a machine-readable JSON line
+(prefixed `GATES_JSON: `) and leaves company/gates.config untouched.
+
+With --write: writes company/gates.config in the existing
+`{"gates": [{"name", "command", "blocking": true}]}` shape, UNLESS the existing
+config already holds a non-placeholder gate (a gate whose command contains
+"CONFIGURE ME" is a placeholder and may be replaced). If no stack is detected
+the config is left untouched either way.
+
+Stdlib only. Exits 0 in the normal case.
+"""
+
+import json
+import os
+import re
+import shutil
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _common as c  # noqa: E402
+
+# cheap-to-expensive ordering buckets
+ORDER = {"lint": 0, "typecheck": 1, "tests": 2, "build": 3, "other": 4}
+
+PLACEHOLDER_MARK = "configure me"
+
+
+def project_dir():
+    root = os.environ.get("CLAUDE_PROJECT_DIR")
+    if root:
+        return root
+    return os.getcwd()
+
+
+def read_text(path):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+def exists(root, name):
+    return os.path.exists(os.path.join(root, name))
+
+
+def gate(name, command, binary, kind):
+    """Build a proposed-gate record."""
+    return {
+        "name": name,
+        "command": command,
+        "binary": binary,
+        "kind": kind,
+        "order": ORDER.get(kind, ORDER["other"]),
+    }
+
+
+def detect_node(root, gates, stacks):
+    pkg_path = os.path.join(root, "package.json")
+    if not os.path.exists(pkg_path):
+        return None
+    try:
+        pkg = json.loads(read_text(pkg_path))
+    except Exception:
+        pkg = {}
+    if not isinstance(pkg, dict):
+        pkg = {}
+    stacks.append("package.json")
+
+    # package manager from lockfiles
+    if exists(root, "pnpm-lock.yaml"):
+        pm = "pnpm"
+    elif exists(root, "yarn.lock"):
+        pm = "yarn"
+    else:
+        pm = "npm"
+
+    scripts = pkg.get("scripts") or {}
+    if not isinstance(scripts, dict):
+        scripts = {}
+
+    def run_cmd(script):
+        # `npm test` is idiomatic; other scripts go through `run`.
+        if script == "test":
+            return "{} test".format(pm)
+        return "{} run {}".format(pm, script)
+
+    if scripts.get("lint"):
+        gates.append(gate("lint", run_cmd("lint"), pm, "lint"))
+    if scripts.get("typecheck"):
+        gates.append(gate("typecheck", run_cmd("typecheck"), pm, "typecheck"))
+    else:
+        deps = {}
+        for key in ("dependencies", "devDependencies"):
+            d = pkg.get(key)
+            if isinstance(d, dict):
+                deps.update(d)
+        if "typescript" in deps:
+            gates.append(
+                gate("typecheck", "tsc --noEmit", "tsc", "typecheck")
+            )
+    if scripts.get("test"):
+        gates.append(gate("tests", run_cmd("test"), pm, "tests"))
+    if scripts.get("build"):
+        gates.append(gate("build", run_cmd("build"), pm, "build"))
+    return pm
+
+
+def detect_python(root, gates, stacks):
+    pyproject = os.path.join(root, "pyproject.toml")
+    pyproject_txt = read_text(pyproject) if os.path.exists(pyproject) else ""
+    setup_cfg_txt = (
+        read_text(os.path.join(root, "setup.cfg"))
+        if exists(root, "setup.cfg")
+        else ""
+    )
+    tox_txt = (
+        read_text(os.path.join(root, "tox.ini"))
+        if exists(root, "tox.ini")
+        else ""
+    )
+
+    test_signals = any(
+        exists(root, f)
+        for f in ("pyproject.toml", "setup.cfg", "pytest.ini", "conftest.py")
+    )
+    if not test_signals:
+        return
+    stacks.append("python")
+
+    # lint: ruff, then flake8
+    ruff_cfg = (
+        "[tool.ruff" in pyproject_txt
+        or exists(root, "ruff.toml")
+        or exists(root, ".ruff.toml")
+    )
+    flake8_cfg = (
+        exists(root, ".flake8")
+        or "[flake8]" in setup_cfg_txt
+        or "[flake8]" in tox_txt
+    )
+    if ruff_cfg:
+        gates.append(gate("lint", "ruff check .", "ruff", "lint"))
+    elif flake8_cfg:
+        gates.append(gate("lint", "flake8", "flake8", "lint"))
+
+    # typecheck: mypy
+    mypy_cfg = (
+        "[tool.mypy" in pyproject_txt
+        or exists(root, "mypy.ini")
+        or exists(root, ".mypy.ini")
+        or "[mypy]" in setup_cfg_txt
+    )
+    if mypy_cfg:
+        gates.append(gate("typecheck", "mypy .", "mypy", "typecheck"))
+
+    # tests: pytest
+    gates.append(gate("tests", "python3 -m pytest", "python3", "tests"))
+
+
+def detect_go(root, gates, stacks):
+    if not exists(root, "go.mod"):
+        return
+    stacks.append("go.mod")
+    gates.append(gate("vet", "go vet ./...", "go", "lint"))
+    gates.append(gate("tests", "go test ./...", "go", "tests"))
+
+
+def detect_rust(root, gates, stacks):
+    if not exists(root, "Cargo.toml"):
+        return
+    stacks.append("Cargo.toml")
+    gates.append(
+        gate("clippy", "cargo clippy -- -D warnings", "cargo", "lint")
+    )
+    gates.append(gate("tests", "cargo test", "cargo", "tests"))
+
+
+def detect_make(root, gates, stacks):
+    if not exists(root, "Makefile"):
+        return
+    txt = read_text(os.path.join(root, "Makefile"))
+    targets = set()
+    for line in txt.splitlines():
+        m = re.match(r"^([A-Za-z0-9_-]+)\s*:", line)
+        if m:
+            targets.add(m.group(1))
+    wanted = [("lint", "lint"), ("gates", "other"), ("test", "tests")]
+    found = False
+    for target, kind in wanted:
+        if target in targets:
+            found = True
+            name = "tests" if target == "test" else target
+            gates.append(
+                gate(name, "make {}".format(target), "make", kind)
+            )
+    if found:
+        stacks.append("Makefile")
+
+
+def dedupe_and_order(gates):
+    """Sort cheap-to-expensive, drop duplicate commands, unique-ify names."""
+    ordered = sorted(
+        enumerate(gates), key=lambda pair: (pair[1]["order"], pair[0])
+    )
+    seen_cmd = set()
+    seen_name = {}
+    out = []
+    for _, g in ordered:
+        cmd = g["command"]
+        if cmd in seen_cmd:
+            continue
+        seen_cmd.add(cmd)
+        name = g["name"]
+        if name in seen_name:
+            seen_name[name] += 1
+            name = "{}-{}".format(name, seen_name[name])
+        else:
+            seen_name[name] = 1
+        entry = dict(g)
+        entry["name"] = name
+        out.append(entry)
+    return out
+
+
+def split_invocable(gates):
+    proposed, skipped = [], []
+    for g in gates:
+        if shutil.which(g["binary"]):
+            proposed.append(g)
+        else:
+            skipped.append(g)
+    return proposed, skipped
+
+
+def config_has_real_gates(cfg):
+    if not isinstance(cfg, dict):
+        return False
+    for g in cfg.get("gates") or []:
+        if not isinstance(g, dict):
+            continue
+        cmd = str(g.get("command", ""))
+        if cmd and PLACEHOLDER_MARK not in cmd.lower():
+            return True
+    return False
+
+
+def to_config_gates(gates):
+    return [
+        {"name": g["name"], "command": g["command"], "blocking": True}
+        for g in gates
+    ]
+
+
+def write_config(root, config_gates):
+    path = os.path.join(root, "company", "gates.config")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    body = {
+        "$comment": (
+            "Auto-generated by gates_detect.py. Every gate is blocking; "
+            "edit freely. See company/GATES.md."
+        ),
+        "gates": config_gates,
+    }
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(json.dumps(body, indent=2))
+        f.write("\n")
+    return path
+
+
+def print_table(proposed, skipped, pm, stacks):
+    if stacks:
+        print("Detected stack: {}".format(", ".join(stacks)))
+    if pm:
+        print("Package manager: {}".format(pm))
+    print("")
+    header = "{:<12} {:<10} {}".format("GATE", "STATUS", "COMMAND")
+    print(header)
+    print("-" * len(header))
+    for g in proposed:
+        print("{:<12} {:<10} {}".format(g["name"], "ready", g["command"]))
+    for g in skipped:
+        print(
+            "{:<12} {:<10} {}  (missing: {})".format(
+                g["name"], "no-tool", g["command"], g["binary"]
+            )
+        )
+    if not proposed and not skipped:
+        print("(no gate candidates)")
+    print("")
+
+
+def emit_json(obj):
+    print("GATES_JSON: " + json.dumps(obj, sort_keys=True))
+
+
+def main(argv):
+    write = "--write" in argv[1:]
+    root = project_dir()
+
+    gates = []
+    stacks = []
+    pm = detect_node(root, gates, stacks)
+    detect_python(root, gates, stacks)
+    detect_go(root, gates, stacks)
+    detect_rust(root, gates, stacks)
+    detect_make(root, gates, stacks)
+
+    gates = dedupe_and_order(gates)
+    proposed, skipped = split_invocable(gates)
+
+    proposed_json = to_config_gates(proposed)
+    skipped_json = [
+        {
+            "name": g["name"],
+            "command": g["command"],
+            "binary": g["binary"],
+            "reason": "detected_but_missing_tool",
+        }
+        for g in skipped
+    ]
+
+    # No stack at all: leave config untouched, report, exit 0.
+    if not stacks:
+        print("no stack detected - leaving company/gates.config untouched")
+        emit_json(
+            {
+                "stacks": [],
+                "package_manager": pm,
+                "proposed": [],
+                "skipped": [],
+                "wrote": False,
+                "status": "no_stack",
+            }
+        )
+        return 0
+
+    print_table(proposed, skipped, pm, stacks)
+
+    status = "proposed"
+    wrote = False
+    if write:
+        existing = c.gates_config(root)
+        if config_has_real_gates(existing):
+            status = "preserved_existing"
+            print(
+                "company/gates.config already has real gates - preserved, "
+                "not overwritten."
+            )
+        elif not proposed:
+            status = "nothing_invocable"
+            print(
+                "no invocable gate commands on this machine - config left "
+                "untouched."
+            )
+        else:
+            path = write_config(root, proposed_json)
+            wrote = True
+            status = "wrote"
+            print("wrote {} gate(s) to {}".format(len(proposed_json), path))
+
+    emit_json(
+        {
+            "stacks": stacks,
+            "package_manager": pm,
+            "proposed": proposed_json,
+            "skipped": skipped_json,
+            "wrote": wrote,
+            "status": status,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))