formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/guard/quality-gate

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""The gate, wired to the end of a turn. The rule that actually blocks.
+
+    quality-gate --format claude-code    < hook payload on stdin
+    quality-gate --run                   run the aggregate and report it.
+                                         No budget, no counter, no state
+
+Exit status:
+    0   allowed to finish — green, or the budget is spent and you were told
+    2   refused. The aggregate is red and the turn cannot conclude
+
+WHAT THIS DOES
+--------------
+When the agent tries to finish a turn, this runs the aggregate — by name, the
+whole thing, never a hand-picked subset — and refuses to let the turn end while
+it is red.
+
+Naming the aggregate rather than listing its parts means a check added later is
+covered without anybody remembering to update this file.
+
+THE BUDGET, AND WHY IT IS NOT A DETAIL
+--------------------------------------
+It refuses a bounded number of times per session, then stands aside and tells
+the human.
+
+Both extremes fail, and one of them fails silently:
+
+  * **Refuse once.** A guard that gives up after a single refusal was defeated
+    under test: an agent broke a check, met one refusal, then altered working
+    code until the broken check agreed with it, and declared itself finished.
+    Nobody had run the aggregate a second time. The safeguard produced a
+    successful-looking result the first time it met a real agent.
+  * **Refuse for ever.** The work strands, and the human finds out by noticing
+    that nothing is happening.
+
+Bounded refusal with escalation is the only version that survives contact.
+
+WHAT A GREEN RESULT HERE DOES NOT MEAN
+--------------------------------------
+Named, because an unqualified pass reads as total coverage.
+
+  * Work done in another checkout this session is not seen.
+  * Changes made outside the agent's tool calls are not seen.
+  * Anything needing real hardware, a live model, or real money is not run by
+    the aggregate, so it is not run here either.
+
+Python 3, standard library only, no dependencies.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+ALLOW, REFUSE = 0, 2
+STRENGTHS = ("block", "warn", "off")
+
+DEFAULT_BUDGET = 3
+
+
+def _timeout():
+    """A malformed timeout must not crash the hook that blocks the turn."""
+    raw = os.environ.get("FORMWORK_GATE_TIMEOUT", "300")
+    try:
+        v = int(raw)
+    except (TypeError, ValueError):
+        return 300
+    if v <= 0:
+        return 300
+    return min(v, 86400)
+
+
+GATE_TIMEOUT = _timeout()
+STATE = os.environ.get("FORMWORK_STATE_DIR", os.path.expanduser("~/.formwork"))
+FORMATS = ("claude-code", "codex", "cursor", "gemini-cli")
+
+
+def project_root():
+    env = os.environ.get("CLAUDE_PROJECT_DIR")
+    if env and os.path.isdir(env):
+        return env
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.dirname(os.path.dirname(here))
+
+
+def setting(root, key, allowed, default):
+    config = os.path.join(root, ".formwork.toml")
+    if not os.path.exists(config):
+        return default
+    try:
+        text = open(config, encoding="utf-8", errors="ignore").read()
+    except OSError:
+        return default
+    m = re.search(r'^\s*%s\s*=\s*["\']?([A-Za-z0-9_]+)["\']?' % key, text, re.M)
+    if not m:
+        return default
+    v = m.group(1).strip().lower()
+    return v if (allowed is None or v in allowed) else default
+
+
+def budget(root):
+    env = os.environ.get("FORMWORK_GATE_BUDGET")
+    if env and env.isdigit():
+        return int(env)
+    v = setting(root, "gate_budget", None, str(DEFAULT_BUDGET))
+    return int(v) if str(v).isdigit() else DEFAULT_BUDGET
+
+
+def counter_path(session):
+    """Where this session's refusal count lives.
+
+    A payload without a session identifier used to get no counter at all,
+    which meant the escalation never happened and the gate refused for ever —
+    the exact failure this file's own docstring says it avoids. Three of the
+    four runtimes have never been run, so a missing identifier is likely
+    rather than exotic. Fall back to the project, which bounds the refusals
+    even when it cannot tell two sessions apart.
+    """
+    if not session:
+        session = "no-session-id-%s" % re.sub(
+            r"[^A-Za-z0-9_.-]", "_", os.path.basename(project_root()))
+    safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session)
+    return os.path.join(STATE, "sessions", "%s.refusals" % safe)
+
+
+def refusals_so_far(path):
+    if not path:
+        return 0
+    try:
+        return int(open(path).read().strip())
+    except (OSError, ValueError):
+        return 0
+
+
+def record(path, n):
+    if not path:
+        return
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        open(path, "w").write(str(n))
+    except OSError:
+        pass
+
+
+def nothing_changed(root):
+    """True when version control reports a clean tree. Cheap, and read-only."""
+    try:
+        p = subprocess.run(["git", "-C", root, "status", "--porcelain"],
+                           capture_output=True, text=True, timeout=20)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return p.returncode == 0 and not p.stdout.strip()
+
+
+def run_aggregate(root):
+    """(exit_code, output). exit_code is None when it could not run at all."""
+    gate = os.path.join(root, "formwork", "check", "run")
+    if not os.path.isfile(gate):
+        return None, "there is no aggregate at %s" % gate
+    try:
+        p = subprocess.run([gate], capture_output=True, text=True,
+                           cwd=root, timeout=GATE_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        return None, ("the aggregate took longer than %ds and was stopped"
+                      % GATE_TIMEOUT)
+    except OSError as e:
+        return None, "the aggregate could not be started: %s" % e
+    return p.returncode, (p.stdout + p.stderr).strip()
+
+
+def main(argv):
+    root = project_root()
+    direct = "--run" in argv
+    fmt = None
+    for i, a in enumerate(argv):
+        if a == "--format" and i + 1 < len(argv):
+            fmt = argv[i + 1]
+
+    session = ""
+    if not direct:
+        if fmt is None:
+            print("ERROR: give --run, or --format with a payload on stdin",
+                  file=sys.stderr)
+            return REFUSE
+        if fmt not in FORMATS:
+            print("ERROR: unknown runtime format: %s" % fmt, file=sys.stderr)
+            print("       Refusing rather than guessing.", file=sys.stderr)
+            return REFUSE
+        raw = sys.stdin.read()
+        if raw.strip():
+            try:
+                session = (json.loads(raw) or {}).get("session_id", "") or ""
+            except ValueError:
+                session = ""
+
+    level = os.environ.get("FORMWORK_GATE", "").strip().lower()
+    if level not in STRENGTHS:
+        level = setting(root, "aggregate_gate", STRENGTHS, "block")
+    if level == "off":
+        return ALLOW
+
+    if not direct and nothing_changed(root):
+        return ALLOW
+
+    code, out = run_aggregate(root)
+
+    if code is None:
+        if level == "warn":
+            # Saying REFUSED and then allowing it made the message and the
+            # exit code disagree.
+            print("WARNING: %s. A gate that did not run is not a green gate, "
+                  "and this gate is set to warn, so the turn finished anyway."
+                  % out, file=sys.stderr)
+            return ALLOW
+        print("REFUSED: %s." % out, file=sys.stderr)
+        print("A gate that did not run is not a green gate.", file=sys.stderr)
+        return REFUSE
+
+    if code == 0:
+        return ALLOW
+
+    if direct:
+        # --run is for a person or a script asking "is it green?". Reporting
+        # ALLOW on a red aggregate because a counter somewhere had reached
+        # three would be a false answer to a direct question — and the counter
+        # never reset, so it stayed false for ever.
+        print(out, file=sys.stderr)
+        return REFUSE
+
+    if level == "warn":
+        print("The aggregate is red. This gate is set to warn, so the turn "
+              "finished anyway.", file=sys.stderr)
+        print(out, file=sys.stderr)
+        return ALLOW
+
+    path = counter_path(session)
+    used = refusals_so_far(path)
+    allowance = budget(root)
+
+    if used >= allowance:
+        print("THE AGGREGATE IS STILL RED, and this gate has already refused "
+              "%d times in this session." % used, file=sys.stderr)
+        print("It is standing aside so the work is not stranded. NOTHING BELOW "
+              "HAS BEEN FIXED.", file=sys.stderr)
+        print(out, file=sys.stderr)
+        return ALLOW
+
+    record(path, used + 1)
+    print("REFUSED: the aggregate is red, so this turn cannot conclude.",
+          file=sys.stderr)
+    print(out, file=sys.stderr)
+    print("", file=sys.stderr)
+    print("Refusal %d of %d this session. Fix the cause. Do not change the "
+          "check that just failed you." % (used + 1, allowance),
+          file=sys.stderr)
+    return REFUSE
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/guard/test_boundary.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Prove the boundary refuses, and prove it lets reading through.
+
+Three things are tested, and the third is the unusual one:
+
+    REFUSED   commands that change the repository
+    ALLOWED   commands that only read it, because the report needs them
+    KNOWN MISS  evasions this guard does not catch
+
+The third group is asserted deliberately. A blind spot that is tested is a
+blind spot somebody has to delete a test to pretend away. An unqualified pass
+would read as total coverage, and this is not that.
+
+Python 3, standard library only, no dependencies.
+"""
+import json
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+GUARD = os.path.join(HERE, "git-boundary")
+ALLOW, WARN, REFUSE = 0, 1, 2
+results = []
+
+
+def run(command=None, fmt=None, payload=None, level=None):
+    env = dict(os.environ)
+    # Each case states its own strength, so a stray setting in the shell this
+    # runs from cannot quietly change the result.
+    env["FORMWORK_GIT_BOUNDARY"] = level or "block"
+    args = [sys.executable, GUARD]
+    if command is not None:
+        args += ["--command", command]
+    if fmt is not None:
+        args += ["--format", fmt]
+    p = subprocess.run(args, capture_output=True, text=True, env=env,
+                       input=json.dumps(payload) if payload is not None else "")
+    return p.returncode, (p.stdout + p.stderr).strip()
+
+
+def expect(label, command, want):
+    got, out = run(command=command)
+    ok = got == want
+    results.append(ok)
+    names = {ALLOW: "allow", WARN: "warn", REFUSE: "REFUSE"}
+    print("  [%s] %-44s %s" % ("pass" if ok else "FAIL", command, names[want]))
+    if not ok:
+        print("        got %s: %s" % (names.get(got, got), out.split("\n")[0]))
+
+
+def main():
+    print("REFUSED — changes the repository")
+    for c in [
+        "git commit -m 'x'",
+        "git add .",
+        "git push origin main",
+        "git merge feature",
+        "git rebase -i HEAD~3",
+        "git reset --hard",
+        "git stash",
+        "git tag -a v1 -m x",
+        "git branch -D old",
+        "git config user.name --add",
+        "git remote add origin git@example.com:a/b.git",
+        "git worktree add ../wt",
+        "git checkout -b new-branch",
+        "git switch -c new-branch",
+        "gh pr create --fill",
+        "gh pr merge 12",
+        "glab mr create",
+        # wrappers and compound commands
+        "sudo git commit -m x",
+        "FOO=1 git commit -m x",
+        "cd subdir && git commit -m x",
+        "git status && git commit -m x",
+        "git -C /elsewhere commit -m x",
+        "git -c user.name=x commit -m y",
+        "echo hi; git push",
+        # A subcommand held in a variable cannot be read, so it is not on the
+        # read-only list, so it is refused. Caution is the default.
+        "C=commit; git $C -m x",
+    ]:
+        expect("refuse", c, REFUSE)
+
+    print()
+    print("ALLOWED — reading only, and the report depends on it")
+    for c in [
+        "git status",
+        "git status --short",
+        "git diff",
+        "git diff --cached --name-only",
+        "git log --oneline -20",
+        "git show HEAD",
+        "git ls-files",
+        "git rev-parse HEAD",
+        "git branch",
+        "git branch --list",
+        "git tag",
+        "git remote -v",
+        "git worktree list",
+        "git config --get user.name",
+        "git blame README.md",
+        "git describe --tags",
+        "ls -la",
+        "python3 tools/privacy_scan.py",
+        "grep -rn TODO .",
+        "git diff && git status",
+    ]:
+        expect("allow", c, ALLOW)
+
+    print()
+    print("KNOWN MISS — asserted, so nobody mistakes these for covered")
+    for c in [
+        # the whole command is assembled at run time, so the word "git"
+        # never appears for the guard to find
+        "eval $(echo git commit -m x)",
+        # a script on disk commits; this reads the command, not the script
+        "./scripts/release.sh",
+        "make release",
+    ]:
+        expect("known miss", c, ALLOW)
+
+    print()
+    print("PAYLOADS — the four runtimes, and a refusal to guess")
+    for fmt in ("claude-code", "codex", "cursor", "gemini-cli"):
+        code, _ = run(fmt=fmt, payload={"tool_input": {"command": "git push"}})
+        ok = code == REFUSE
+        results.append(ok)
+        print("  [%s] %-44s REFUSE" % ("pass" if ok else "FAIL", fmt))
+
+    code, _ = run(fmt="claude-code", payload={"tool_input": {"command": "git log"}})
+    ok = code == ALLOW
+    results.append(ok)
+    print("  [%s] %-44s allow" % ("pass" if ok else "FAIL", "claude-code, a read"))
+
+    # Fails closed. A guard that cannot decide refuses, because a boundary
+    # that fails open is a boundary nobody notices has gone.
+    code, out = run(fmt="some-other-tool", payload={})
+    ok = code == REFUSE
+    results.append(ok)
+    print("  [%s] %-44s REFUSE, not allow"
+          % ("pass" if ok else "FAIL", "an unknown runtime"))
+
+    code, out = run(fmt="claude-code", payload=None)
+    ok = code == REFUSE
+    results.append(ok)
+    print("  [%s] %-44s REFUSE, not allow"
+          % ("pass" if ok else "FAIL", "no payload at all"))
+
+    print()
+    print("STRENGTH — the same command, three settings")
+    for level, want, label in (("block", REFUSE, "block: refuses"),
+                               ("warn", WARN, "warn: runs, and says so"),
+                               ("off", ALLOW, "off: runs, silently")):
+        code, _ = run(command="git commit -m x", level=level)
+        ok = code == want
+        results.append(ok)
+        print("  [%s] %-44s %s"
+              % ("pass" if ok else "FAIL", label,
+                 {ALLOW: "allow", WARN: "warn", REFUSE: "REFUSE"}[want]))
+
+    # A read is allowed whatever the strength; the report depends on it.
+    for level in ("block", "warn", "off"):
+        code, _ = run(command="git status", level=level)
+        ok = code == ALLOW
+        results.append(ok)
+        print("  [%s] %-44s allow"
+              % ("pass" if ok else "FAIL", "reads pass at strength=%s" % level))
+
+    # Everything below is a hole an audit walked through. Each one was
+    # allowed before the fix that follows it in git history.
+    print("WRAPPERS — a write hidden behind something else")
+    for c in ['bash -c "git commit -m x"',
+              'sh -c "git push"',
+              'eval "git push"',
+              'nice -n 5 git push',
+              'timeout 60 git push',
+              'env -u FOO git push',
+              'sudo -u somebody git push',
+              'echo $(git commit -m x)']:
+        expect(c, c, REFUSE)
+
+    print("WRAPPERS — and the same wrappers around innocent work")
+    for c in ['bash -c "echo hello"', 'nice -n 5 ls', 'timeout 60 git status']:
+        expect(c, c, ALLOW)
+
+    print("WRITES WITH NO OPTION AT ALL")
+    expect("git config core.hooksPath /dev/null",
+           "git config core.hooksPath /dev/null", REFUSE)
+    expect("git checkout somefile.py", "git checkout somefile.py", REFUSE)
+
+    print("READS ONCE WRONGLY REFUSED")
+    for c in ['git stash list', 'git stash show', 'git notes list',
+              'git cherry -v', 'git config --get user.name']:
+        expect(c, c, ALLOW)
+    expect("git stash", "git stash", REFUSE)
+
+    print("FAILS CLOSED — a payload it cannot read")
+    for bad in ("[]", "null", '{"tool_input":{"command":5}}'):
+        code, out = run(fmt="claude-code", payload=bad)
+        ok = code == REFUSE
+        results.append(ok)
+        print("  [%s] %-44s %s"
+              % ("pass" if ok else "FAIL", "unreadable payload %s" % bad[:20],
+                 "REFUSE"))
+
+    print("SECOND AUDIT — grouping, loops, aliases, heredocs into a shell")
+    for c in ['(git push)', '{ git push; }',
+              'for f in x; do git push; done',
+              'while true; do git commit -m x; done',
+              'if true; then git push; fi',
+              '\\git commit',
+              'git submodule foreach git push',
+              'gh -R owner/repo pr create',
+              'gh --repo a/b pr create',
+              'gh api -X POST /repos/a/b/pulls',
+              'git config core.hooksPath /dev/null']:
+        expect(c, c, REFUSE)
+    code, out = run(command="bash <<'EOF'\ngit push\nEOF\n")
+    ok = code == REFUSE
+    results.append(ok)
+    print("  [%s] %-44s %s" % ("pass" if ok else "FAIL",
+                               "heredoc fed to a shell", "REFUSE"))
+
+    print("THIRD AUDIT — wrappers that swallowed the command")
+    for c in ['sudo -n git push', 'env -i git push', 'sudo -s git push',
+              'timeout -k 1 30 git push',
+              'git symbolic-ref HEAD refs/heads/evil']:
+        expect(c, c, REFUSE)
+    for pre in ('bash', 'sudo -n bash', 'nice -n 5 bash', 'timeout 60 bash',
+                'env FOO=1 bash'):
+        code, out = run(command="%s <<'EOF'\ngit push\nEOF\n" % pre)
+        ok = code == REFUSE
+        results.append(ok)
+        print("  [%s] %-44s %s" % ("pass" if ok else "FAIL",
+                                   "heredoc into: " + pre, "REFUSE"))
+
+    print("THIRD AUDIT — reads and branch moves wrongly refused")
+    for c in ['git stash show -p', 'git checkout main', 'git checkout v1.2.0',
+              'git symbolic-ref --short HEAD',
+              'git config --local user.email 2>/dev/null']:
+        expect(c, c, ALLOW)
+    for name in ('retrieval.md', 'node-setup.md', 'ruby-guide.md'):
+        code, out = run(command="cat > docs/%s <<'EOF'\ngit push\nEOF\n" % name)
+        ok = code == ALLOW
+        results.append(ok)
+        print("  [%s] %-44s %s" % ("pass" if ok else "FAIL",
+                                   "heredoc written to " + name, "allow"))
+
+    print("SECOND AUDIT — reads that were wrongly refused")
+    for c in ['git symbolic-ref --short HEAD',
+              'git config --global --get user.name',
+              'git config --list --global',
+              'git apply --check patch.diff',
+              'git fetch origin',
+              'for f in x; do echo $f; done',
+              'bash -c "echo hello"',
+              'gh pr list', 'gh api /repos/a/b']:
+        expect(c, c, ALLOW)
+    code, out = run(command="cat > notes.md <<'EOF'\ngit commit -m x\nEOF\n")
+    ok = code == ALLOW
+    results.append(ok)
+    print("  [%s] %-44s %s" % ("pass" if ok else "FAIL",
+                               "heredoc written to a file", "allow"))
+
+    print()
+    print("%d of %d behaved as specified." % (sum(results), len(results)))
+    return 0 if all(results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())