@giamme/forge 0.0.0-stage → 0.8.0

package/scripts/forge-fail-first.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Fail-first evidence: do the tests a change adds or edits fail without the change?
+
+    forge-fail-first.py run --repo <review snapshot> --base <commit> --reviewed <commit>
+                        --command '<test command with {files}>' --out <failfirst.json>
+                        [--deps-from <dir>] [--timeout S]
+
+Opt-in (`--fail-first` on forge-solo.sh and `plan`) and advisory. A test that passes on the
+code it is meant to protect, before that code changed, proves nothing about the change. For
+every test file the diff adds or edits, this runs the project's own per-file test command
+(`.forge/verify-subset`, which must contain `{files}`) twice, each in a throwaway export:
+
+  - with the change: the reviewed tree;
+  - without it: the base tree plus the change's test-path files only (test files, fixtures
+    and helpers under test directories), so the new tests meet the old code.
+
+Each file ends up `proven` (passes with, fails without), `passes_without_change` (passes both
+ways: it does not prove the change), `inconclusive` (fails even with the change: a broken test
+or a missing dependency, no evidence either way) or `error` (could not export or timed out).
+
+The result goes to the JSON file, and the reviewer's prompt section goes to stdout; the QA
+prompt asks the reviewer to report every `passes_without_change` file as a P2 finding. Forge
+never changes a status or verdict on its own from this. The review snapshot is only read:
+exports use a private index, so no fingerprint can change. Always exits 0 except on usage
+errors (2).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+
+# The same two conditions as forge_jev/subset.py: a test path, and for the files that are run,
+# a source suffix (README.md and JSON fixtures under tests/ are carried over, never run).
+TEST_PATH = re.compile(r'(^|/)(tests?|spec|specs|__tests__)/'
+                       r'|(^|/)test_[^/]*$|_test\.[^/]+$|\.(test|spec)\.[^/]+$')
+CODE_SUFFIXES = ('.py', '.go', '.js', '.jsx', '.ts', '.tsx', '.rb', '.rs', '.java',
+                 '.kt', '.php', '.sh', '.mjs', '.cjs')
+DEP_DIRS = ('node_modules', '.venv', 'venv', 'vendor')
+MAX_FILES = 20
+TAIL = 2000
+
+
+def _git(repo, *args, env=None, data=None):
+    return subprocess.run(['git', '-C', str(repo), *args], input=data, capture_output=True,
+                          env=env, timeout=120, check=True).stdout
+
+
+def changed_paths(repo, base, reviewed):
+    """[(status, path)] of the change, renames split into a delete and an add."""
+    out = _git(repo, 'diff', '--name-status', '-z', '--no-renames', base, reviewed, '--', '.', ':(exclude).forge')
+    parts = out.decode('utf-8', 'surrogateescape').split('\0')
+    return [(parts[i], parts[i + 1]) for i in range(0, len(parts) - 1, 2)]
+
+
+def export(repo, tree, dest, overlay_from=None, overlay=(), deps_from=None):
+    """Check `tree` out into `dest` through a private index; `overlay` paths come from `overlay_from`."""
+    handle, index = tempfile.mkstemp(prefix='forge-failfirst-index.')
+    os.close(handle); os.unlink(index)
+    env = dict(os.environ, GIT_INDEX_FILE=index)
+    try:
+        _git(repo, 'read-tree', tree, env=env)
+        for path in overlay:
+            entry = _git(repo, 'ls-tree', '-z', overlay_from, '--', path).decode('utf-8', 'surrogateescape')
+            if entry:
+                _git(repo, 'update-index', '-z', '--index-info', env=env, data=entry.encode('utf-8', 'surrogateescape'))
+            else:
+                _git(repo, 'update-index', '--force-remove', '--', path, env=env)
+        _git(repo, 'checkout-index', '--all', '--force', '--prefix=' + str(dest) + '/', env=env)
+    finally:
+        if os.path.exists(index):
+            os.unlink(index)
+    for name in DEP_DIRS:  # dependencies are not in the tree; link them so the export can run
+        source = Path(deps_from) / name if deps_from else None
+        if source and source.is_dir() and not (Path(dest) / name).exists():
+            try:
+                os.symlink(source, Path(dest) / name)
+            except OSError:
+                pass
+
+
+def run_one(command, cwd, timeout):
+    started = time.time()
+    try:
+        done = subprocess.run(command, shell=True, cwd=str(cwd), capture_output=True, text=True,
+                              stdin=subprocess.DEVNULL, timeout=timeout, errors='replace')
+    except subprocess.TimeoutExpired:
+        return dict(rc=None, seconds=round(time.time() - started, 3), tail='timed out')
+    except OSError as error:
+        return dict(rc=None, seconds=round(time.time() - started, 3), tail=str(error))
+    tail = ((done.stdout or '') + (done.stderr or ''))[-TAIL:]
+    return dict(rc=done.returncode, seconds=round(time.time() - started, 3), tail=tail)
+
+
+def classify(with_change, without):
+    if with_change['rc'] is None or without['rc'] is None:
+        return 'error'
+    if with_change['rc'] != 0:
+        return 'inconclusive'
+    return 'proven' if without['rc'] != 0 else 'passes_without_change'
+
+
+def evaluate(repo, base, reviewed, command, timeout, deps_from=None):
+    result = dict(version=1, status='ran', command=command, base=base, reviewed=reviewed, tests=[],
+                  skipped=[], started=time.time())
+    if '{files}' not in (command or ''):
+        result.update(status='skipped', reason='no per-file test command: put one with {files} in .forge/verify-subset')
+        return result
+    changes = changed_paths(repo, base, reviewed)
+    support = [path for _status, path in changes if TEST_PATH.search(path)]
+    tests = [path for status, path in changes
+             if status != 'D' and TEST_PATH.search(path) and path.endswith(CODE_SUFFIXES)]
+    if not tests:
+        result.update(status='skipped', reason='the change adds or edits no test files')
+        return result
+    result['skipped'] = tests[MAX_FILES:]
+    work = Path(tempfile.mkdtemp(prefix='forge-failfirst-'))
+    try:
+        with_dir, without_dir = work / 'with', work / 'without'
+        export(repo, reviewed, with_dir, deps_from=deps_from)
+        export(repo, base, without_dir, overlay_from=reviewed, overlay=support, deps_from=deps_from)
+        for path in tests[:MAX_FILES]:
+            line = command.replace('{files}', shlex.quote(path))
+            with_change = run_one(line, with_dir, timeout)
+            without = run_one(line, without_dir, timeout)
+            result['tests'].append(dict(path=path, result=classify(with_change, without),
+                                        with_change=with_change, without_change=without))
+    except (OSError, subprocess.SubprocessError) as error:
+        result.update(status='error', reason=f'could not export the change: {error}'[:500])
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    result['ended'] = time.time()
+    return result
+
+
+def prompt_section(result):
+    """What the reviewer reads; empty when there is nothing to say."""
+    if result.get('status') != 'ran' or not result.get('tests'):
+        return ''
+    words = dict(proven='fails without the change and passes with it',
+                 passes_without_change='PASSES WITHOUT THE CHANGE: it does not prove the change',
+                 inconclusive='fails even with the change (a broken test or the environment): no evidence either way',
+                 error='could not be run (timeout or error): no evidence either way')
+    lines = ['Fail-first evidence (observed by forge, not claimed by the implementer): each test file this',
+             'change adds or edits was run with the change and against the code WITHOUT its non-test changes.',
+             'Command: ' + result['command']]
+    lines += [f'  - {item["path"]}: {words[item["result"]]}' for item in result['tests']]
+    if result.get('skipped'):
+        lines.append(f'  ({len(result["skipped"])} more test files were not run)')
+    if any(item['result'] == 'passes_without_change' for item in result['tests']):
+        lines += ['Report each test file that passes without the change as a [P2][CONFIRMED] finding at that file:',
+                  'a test that cannot fail does not protect this change. If the test is not meant to catch it',
+                  '(a refactor kept green, a pure rename), say why instead.']
+    return '\n'.join(lines) + '\n'
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='forge-fail-first.py')
+    sub = parser.add_subparsers(dest='cmd', required=True)
+    run = sub.add_parser('run')
+    run.add_argument('--repo', required=True)
+    run.add_argument('--base', required=True)
+    run.add_argument('--reviewed', required=True)
+    run.add_argument('--command', default='')
+    run.add_argument('--out', required=True)
+    run.add_argument('--deps-from')
+    run.add_argument('--timeout', type=float, default=float(os.environ.get('FORGE_FAIL_FIRST_TIMEOUT') or 600))
+    args = parser.parse_args(argv)
+    try:
+        result = evaluate(args.repo, args.base, args.reviewed, args.command.strip(), max(1.0, args.timeout),
+                          deps_from=args.deps_from)
+    except Exception as error:  # advisory: never break the run
+        result = dict(version=1, status='error', reason=str(error)[:500], command=args.command, tests=[])
+    counts = {}
+    for item in result.get('tests', []):
+        counts[item['result']] = counts.get(item['result'], 0) + 1
+    result['counts'] = counts
+    try:
+        Path(args.out).write_text(json.dumps(result, indent=1) + '\n', encoding='utf-8')
+    except OSError:
+        pass
+    sys.stdout.write(prompt_section(result))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/forge-fractal-dispatch.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$ROOT/forge-fractal.py" _dispatch "$@"

package/scripts/forge-fractal-options.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Source in runners. Arrays and syntax remain compatible with macOS Bash 3.2.
+FRACTAL_CHOICE=""; FRACTAL_ARGS=()
+forge_fractal_help() {
+  cat <<'HELP'
+Optional Fractal execution (solo or parallel run):
+  --fractal | --no-fractal   Explicit choice; unattended defaults off
+  --fractal-auto-decompose  Enable Fractal with automatic split-or-atomic planning
+  --fractal-planner SPEC    Decision model (top-level planner, then task root model)
+  --fractal-depth N         Nested levels below implementation (2)
+  --fractal-children N      Unsettled direct children per node (3)
+  --fractal-nodes N         Lifetime nodes per task (12)
+  --fractal-iterations N    Iterations per node per attempt (6)
+  --fractal-concurrency N   Model slots across the run, including QA (3)
+  --fractal-deadline N      Task attempt seconds excluding pauses (2700)
+  --fractal-max-cost N      Unsupported: costs are observational
+Run choice, planners, limits and pools persist for resume/retry. Installation never activates it.
+Solo child routing: --dwarf-low, --dwarf-medium, --dwarf-high (comma pools).
+Decomposed routing is configured by the plan command.
+Use ./forge fractal --help for installation, inspection, controls and HTML reports.
+HELP
+}
+forge_fractal_flag() {
+  local choice="$1"
+  [ -z "$FRACTAL_CHOICE" ] || [ "$FRACTAL_CHOICE" = "$choice" ] || { echo '--fractal and --no-fractal are mutually exclusive' >&2; return 2; }
+  FRACTAL_CHOICE="$choice"
+}
+forge_fractal_select() {
+  local run="$1" repo="$2" mode="$3" dry="$4" selected
+  shift 4
+  local args=(select --run-dir "$run" --repo "$repo" --mode "$mode" --choice "$FRACTAL_CHOICE")
+  [ "$dry" != 1 ] || args+=(--dry-run)
+  selected="$(python3 "$SKILL_DIR/scripts/forge-fractal.py" "${args[@]}" ${FRACTAL_ARGS[@]+"${FRACTAL_ARGS[@]}"} "$@")" || return $?
+  if [ "$selected" != off ] && [ "$selected" != dry-fractal ]; then
+    export FORGE_FRACTAL_RUN="$selected"
+    DISPATCH="$SKILL_DIR/scripts/forge-fractal-dispatch.sh"
+  elif [ "$selected" = dry-fractal ]; then
+    unset FORGE_FRACTAL_RUN
+    echo 'backend: fractal (dry run)' >&2
+  else
+    unset FORGE_FRACTAL_RUN
+  fi
+}
+
+forge_fractal_parallel_run() {
+  local plan="$1" repo="$2" dry="$3"; shift 3
+  local flags=()
+  [ ! -f "$plan/yolo_dwarf" ] || flags+=(--yolo-dwarf)
+  [ ! -f "$plan/yolo_qa" ] || flags+=(--yolo-qa)
+  forge_fractal_select "$plan" "$repo" parallel "$dry" ${flags[@]+"${flags[@]}"} || return $?
+  if [ -n "${FORGE_FRACTAL_RUN:-}" ]; then
+    python3 "$SKILL_DIR/scripts/forge-fractal.py" _remember "$SELF" run "$plan" "$@" || return $?
+  fi
+}

package/scripts/forge-fractal.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+"""Repository-local entry point for Forge's optional Fractal integration."""
+from forge_fractal.cli import main
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/scripts/forge-guard.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Implementer-side guards for forge-dispatch.sh. Stdlib only, offline.
+
+  forge-guard.py ping
+      prints `ok`; lets the dispatcher prove the helper can start before relying on it.
+
+  forge-guard.py session -- CMD [ARGS...]
+      os.setsid(), then exec CMD. The pid does not change, so the dispatcher's $! is
+      still the harness pid, and that pid is now also the process-group id: everything
+      the harness spawns (a dwarf's `npm test &`, a dev server) shares the group and can
+      be signalled or reaped as a unit. macOS has no `setsid` binary; this is why the
+      helper exists.
+
+  forge-guard.py reap <pgid> <orphans-file>
+      After the harness exited: anything still alive in its process group is an orphan
+      the implementer abandoned. List it (only when something is found), TERM, wait a
+      bounded ~2s, KILL, print how many were found. Never exits nonzero for an ordinary
+      outcome, and never touches its own or its caller's group.
+
+  forge-guard.py promises <file> [--tail-bytes N]
+      Scan the tail of an implementer's final message for promises of later work ("it is
+      still running in the background", "I'll check back"). One `pattern<TAB>excerpt`
+      line per hit; nothing when clean.
+"""
+from __future__ import annotations
+
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+
+PS_CANDIDATES = ('/bin/ps', '/usr/bin/ps')
+TERM_WAIT_S = 2.0
+KILL_WAIT_S = 1.0
+
+
+# --- session ------------------------------------------------------------------
+def session(argv: list[str]) -> int:
+    if not argv:
+        print('forge-guard: session needs a command', file=sys.stderr)
+        return 2
+    try:
+        os.setsid()
+    except OSError:
+        # Already a group leader (job control on): pgid == pid already, which is all
+        # the reaper needs.
+        pass
+    try:
+        os.execvp(argv[0], argv)
+    except FileNotFoundError:
+        print('forge-guard: cannot execute %s: not found' % argv[0], file=sys.stderr)
+        return 127
+    except OSError as error:
+        print('forge-guard: cannot execute %s: %s' % (argv[0], error), file=sys.stderr)
+        return 126
+    return 126  # unreachable
+
+
+# --- reap ---------------------------------------------------------------------
+def group_exists(pgid: int) -> bool:
+    try:
+        os.killpg(pgid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def list_group(pgid: int):
+    """[(pid, command)] of live members, or None when ps is unavailable.
+
+    Zombies are skipped: they are already dead and only wait for their parent.
+    """
+    for ps in PS_CANDIDATES:
+        if not os.access(ps, os.X_OK):
+            continue
+        try:
+            out = subprocess.run([ps, '-axo', 'pid=,pgid=,stat=,command='],
+                                 stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                                 timeout=5).stdout.decode(errors='replace')
+        except (OSError, subprocess.SubprocessError):
+            continue
+        members = []
+        for line in out.splitlines():
+            parts = line.split(None, 3)
+            if len(parts) < 3:
+                continue
+            try:
+                pid, group = int(parts[0]), int(parts[1])
+            except ValueError:
+                continue
+            if group != pgid or pid == os.getpid() or parts[2].startswith('Z'):
+                continue
+            members.append((pid, parts[3].strip() if len(parts) > 3 else ''))
+        return members
+    return None
+
+
+def wait_gone(pgid: int, seconds: float) -> bool:
+    deadline = time.monotonic() + seconds
+    while time.monotonic() < deadline:
+        members = list_group(pgid)
+        if members is None:
+            if not group_exists(pgid):
+                return True
+        elif not members:
+            return True
+        time.sleep(0.05)
+    members = list_group(pgid)
+    return (not members) if members is not None else not group_exists(pgid)
+
+
+def reap(pgid: int, orphans_file: str) -> int:
+    # Never signal ourselves, the dispatcher that called us, or init.
+    forbidden = {0, 1, os.getpgrp()}
+    try:
+        forbidden.add(os.getpgid(os.getppid()))
+    except OSError:
+        pass
+    if pgid in forbidden or pgid < 0:
+        print(0)
+        return 0
+    if not group_exists(pgid):
+        print(0)
+        return 0
+    members = list_group(pgid)
+    if members is not None and not members:
+        # Only zombies (or nothing visible) left; nothing worth reporting or killing.
+        print(0)
+        return 0
+    found = members if members is not None else [(0, '(unknown: ps unavailable; process group %d still has live members)' % pgid)]
+    try:
+        with open(orphans_file, 'w') as handle:
+            for pid, command in found:
+                handle.write('%s\t%s\n' % (pid or '?', ' '.join(command.split()) or '?'))
+    except OSError:
+        pass
+    for sig, wait in ((signal.SIGTERM, TERM_WAIT_S), (signal.SIGKILL, KILL_WAIT_S)):
+        try:
+            os.killpg(pgid, sig)
+        except (ProcessLookupError, PermissionError, OSError):
+            break
+        if wait_gone(pgid, wait):
+            break
+    print(len(found))
+    return 0
+
+
+# --- promises -----------------------------------------------------------------
+# A promise of later work in a FINAL message is a bug: the dispatch ends when the message
+# does, so whatever was "still running" is abandoned and whatever "I'll check" never
+# happens. Patterns are deliberately tight; a false positive costs a warning line, a false
+# negative costs a silent half-finished change, but a noisy scan gets ignored.
+DONE_WORDS = re.compile(
+    r"\b(?:finished|completed|done|exited|passed|failed|succeeded|terminated|killed|stopped|ended|returned|"
+    r"was\s+running|were\s+running|had\s+(?:finished|completed))\b", re.I)
+Q = r"['’]"
+PROMISES = (
+    # (name, regex, past_tense_tolerated)
+    # "in the background job scheduler" describes code, not a process left running.
+    ('background', re.compile(
+        r"\bin\s+(?:the\s+)?background\b(?!\s+(?:jobs?|tasks?|workers?|threads?|queues?|refresh|sync|polling|fetch|process(?:es)?\b))", re.I), True),
+    ('still_running', re.compile(r"\bstill\s+(?:running|executing|in\s+progress|working|going)\b", re.I), True),
+    ('report_back', re.compile(r"\b(?:will|I%s?ll|I\s+will|going\s+to)\s+(?:report|come|get|circle|check)\s+back\b" % Q, re.I), False),
+    ('once_it_finishes', re.compile(
+        r"\bonce\s+(?:it|they|that|this|the\s+[\w-]+(?:\s+[\w-]+)?)\s+(?:finish(?:es)?|completes?|is\s+done|are\s+done|ends|exits)\b", re.I), False),
+    ('ill_do', re.compile(
+        r"\bI(?:%s|\s+wi)ll\s+(?:check|report|continue|follow\s+up|run|measure|verify)\b" % Q, re.I), False),
+    ('next_ill', re.compile(r"\bnext,?\s+I(?:%s|\s+wi)ll\b" % Q, re.I), False),
+    ('will_continue', re.compile(
+        r"\b(?:I|we)\s+will\s+(?:continue|finish)\b|\bwill\s+(?:continue|finish)\s+(?:running|in\s+the|once|after|shortly|later)\b", re.I), False),
+    ('to_be_continued', re.compile(r"\bto\s+be\s+continued\b", re.I), False),
+    ('waiting_for', re.compile(r"\b(?:am|I%sm|still|now|currently)\s+waiting\s+(?:for|on)\b" % Q, re.I), False),
+)
+_SENTENCE_BREAK = re.compile(r"[.!?\n]")
+
+
+def _sentence(text: str, start: int, end: int) -> str:
+    left = start
+    while left > 0 and not _SENTENCE_BREAK.match(text[left - 1]):
+        left -= 1
+    right = end
+    while right < len(text) and not _SENTENCE_BREAK.match(text[right]):
+        right += 1
+    return ' '.join(text[left:right].split())
+
+
+def scan_promises(text: str) -> list[tuple[str, str]]:
+    hits: list[tuple[str, str]] = []
+    for name, pattern, tolerate_past in PROMISES:
+        for match in pattern.finditer(text):
+            sentence = _sentence(text, match.start(), match.end())
+            if tolerate_past and DONE_WORDS.search(sentence):
+                continue
+            hit = (name, sentence[:200])
+            if hit not in hits:
+                hits.append(hit)
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if lines and lines[-1].endswith(':') and not lines[-1].endswith('::'):
+        hits.append(('trailing_colon', lines[-1][-200:]))
+    return hits
+
+
+def promises(path: str, tail_bytes: int = 3000) -> int:
+    try:
+        with open(path, 'rb') as handle:
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+            handle.seek(max(0, size - tail_bytes))
+            data = handle.read()
+    except OSError:
+        return 0
+    text = data.decode('utf-8', errors='replace')
+    if size > tail_bytes:
+        # The cut usually lands mid-sentence; a fragment would only produce noise.
+        newline = text.find('\n')
+        text = text[newline + 1:] if 0 <= newline < len(text) - 1 else text
+    for name, excerpt in scan_promises(text):
+        print('%s\t%s' % (name, excerpt.replace('\t', ' ')))
+    return 0
+
+
+# --- cli ----------------------------------------------------------------------
+def main(argv: list[str]) -> int:
+    if not argv:
+        print('usage: forge-guard.py ping | session -- CMD... | reap <pgid> <orphans-file> | '
+              'promises <file> [--tail-bytes N]', file=sys.stderr)
+        return 2
+    command, rest = argv[0], argv[1:]
+    try:
+        if command == 'ping':
+            print('ok')
+            return 0
+        if command == 'session':
+            if rest and rest[0] == '--':
+                rest = rest[1:]
+            return session(rest)
+        if command == 'reap':
+            if len(rest) != 2:
+                print('usage: forge-guard.py reap <pgid> <orphans-file>', file=sys.stderr)
+                return 2
+            return reap(int(rest[0]), rest[1])
+        if command == 'promises':
+            tail = 3000
+            if '--tail-bytes' in rest:
+                index = rest.index('--tail-bytes')
+                tail = int(rest[index + 1])
+                rest = rest[:index] + rest[index + 2:]
+            if len(rest) != 1:
+                print('usage: forge-guard.py promises <file> [--tail-bytes N]', file=sys.stderr)
+                return 2
+            return promises(rest[0], max(1, tail))
+    except (ValueError, IndexError) as error:
+        print('forge-guard: ' + str(error), file=sys.stderr)
+        return 2
+    print('forge-guard: unknown command: ' + command, file=sys.stderr)
+    return 2
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))

package/scripts/forge-install-fractal.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$ROOT/forge-fractal.py" install "$@"

package/scripts/forge-install-ripwire.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Optional pinned upstream installer. No network activity before consent.
+set -uo pipefail
+YES=0; DRY=0
+for arg in "$@"; do
+  case "$arg" in
+    --yes) YES=1 ;;
+    --dry-run) DRY=1 ;;
+    *) echo "forge: unknown installation option: $arg" >&2; exit 2 ;;
+  esac
+done
+[ "${FORGE_RIPWIRE:-}" != off ] || exit 0
+DEST="$HOME/.local/bin/ripwire"
+if command -v ripwire >/dev/null 2>&1 || [ -e "$DEST" ] || [ -L "$DEST" ]; then
+  echo 'forge: preserving existing Ripwire installation' >&2
+  exit 0
+fi
+printf 'forge: Ripwire v0.4.0 -> %s\n' "$DEST" >&2
+[ "$DRY" = 0 ] || exit 0
+if [ "$YES" = 0 ]; then
+  # Open the controlling terminal, never task stdin (which may be a pipe/FIFO).
+  if { exec 3<> /dev/tty; } 2>/dev/null && [ -t 3 ]; then
+    printf 'Ripwire is missing. Install it now? [Y/n] ' >&3
+    reply=''
+    if ! IFS= read -r reply <&3; then exec 3>&-; exit 0; fi
+    exec 3>&-
+    case "$reply" in ''|y|Y|yes|YES) ;; *) exit 0 ;; esac
+  else
+    printf 'forge: optional install: bash %q --yes\n' "${BASH_SOURCE[0]}" >&2
+    exit 0
+  fi
+fi
+work="$(mktemp -d "${TMPDIR:-/tmp}/forge-install-ripwire.XXXXXX")" || exit 1
+trap 'rm -rf "$work"' EXIT
+curl -fLSs --connect-timeout 10 --max-time 60 \
+  https://raw.githubusercontent.com/redhat-et/ripwire/v0.4.0/scripts/install.sh \
+  -o "$work/install.sh" || { echo 'forge: Ripwire installer download failed' >&2; exit 1; }
+# Pin the installer bytes as well as the release; never execute a changed tag.
+python3 - "$work/install.sh" <<'PYHASH'
+import hashlib, pathlib, sys
+expected = '7290f90775d333798ec9d7f1193c5950516dd0f1fea6ce5faea3923b1f60ff01'
+if hashlib.sha256(pathlib.Path(sys.argv[1]).read_bytes()).hexdigest() != expected:
+    sys.exit('forge: Ripwire installer checksum mismatch')
+PYHASH
+[ "$?" = 0 ] || exit 1
+# The upstream installer verifies archive checksums and the binary version.
+RIPWIRE_REPO=redhat-et/ripwire RIPWIRE_VERSION=v0.4.0 \
+RIPWIRE_INSTALL_PREFIX="$HOME/.local" RIPWIRE_INSTALL_YES=1 RIPWIRE_NO_ACTIVATE=1 \
+  /bin/bash "$work/install.sh"
+rc=$?
+[ "$rc" = 0 ] || echo "forge: Ripwire installation failed (exit $rc); Forge can continue" >&2
+exit "$rc"