@bookedsolid/rea 0.10.2 → 0.11.0

package/dist/hooks/review-gate/metadata.d.ts

@@ -1,98 +0,0 @@
-/**
- * OS / agent / repo identity collection for audit records.
- *
- * Closes defect M (0.9.4): the bash core's `jq --arg os_pid "$PID"` wrote
- * the pid as a JSON string; the audit consumer expected an integer, and the
- * schema had to tolerate both. The TS port emits pid/ppid as numbers from
- * day one (the JS runtime's `process.pid` is already a `number`), removing
- * the whole class of jq `--arg` vs `--argjson` confusion.
- *
- * ## Why capture this at all
- *
- * A skip-audit record (`REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`) is
- * the one place the gate is voluntarily weakened. The actor field (from
- * `git config user.email`) is mutable — a process with write access to
- * `.git/config` can stamp any email it likes. Supplementing that with
- * non-forgeable host-level identity (uid, hostname, pid, ppid, tty, CI
- * flag) gives a forensic investigator something to cross-reference when
- * a skip record turns out to have been unauthorized.
- *
- * ## Determinism + testability
- *
- * Every collector is a plain function over `process` / `os` / `node:child_process`
- * so tests can stub the collector's inputs cleanly. The public API takes no
- * arguments (production use) and the helpers are exported for tests.
- */
-export interface OsIdentity {
-    /** POSIX uid as a string (empty when not available — Windows). */
-    uid: string;
-    /** `whoami` output — username or empty string. */
-    whoami: string;
-    /** `hostname` output. */
-    hostname: string;
-    /** This process's pid — number, not string (defect M). */
-    pid: number;
-    /** Parent process's pid — number, not string (defect M). */
-    ppid: number;
-    /** `ps -o command= -p $PPID` output, capped at 512 bytes. */
-    ppid_cmd: string;
-    /** `tty` output or `"not-a-tty"`. */
-    tty: string;
-    /** `CI` env var value or empty string. */
-    ci: string;
-}
-/**
- * Collect current-process OS identity. Every individual collector degrades
- * to an empty-string fallback on any exception — matching the bash core's
- * `id -u || echo ""`, `whoami || echo ""`, `hostname || echo ""` pattern
- * (push-review-core.sh §420-422, 426). Codex pass-1 on phase 1 flagged
- * the earlier implementation that called `userInfo()` and `hostname()`
- * outside any try/catch and could therefore throw on hosts with broken
- * NSS/passwd lookups, which would silently block the skip-audit path.
- */
-export declare function collectOsIdentity(): OsIdentity;
-/**
- * Read POSIX uid + whoami. Each field is collected INDEPENDENTLY so a
- * partial-lookup-failure (e.g. LDAP/NSS returns the uid but no passwd
- * entry) still yields one field rather than dropping both. Bash-core
- * parity (push-review-core.sh §420-421): `id -u` and `whoami` are two
- * separate invocations, each with its own `|| echo ""` fallback.
- *
- * Codex pass-2 on phase 1 flagged the prior single-`userInfo()` version:
- * a broken NSS lookup zeroed out both fields at once, weakening forensic
- * metadata on shared hosts. We now prefer the POSIX primitives
- * (`os.userInfo()` internally reads the passwd entry) but isolate the
- * failures so uid and whoami cannot both disappear together when only
- * one of them is actually unavailable.
- */
-export declare function readUidAndWhoami(): {
-    uid: string;
-    whoami: string;
-};
-/**
- * Read `hostname` via `os.hostname`. Returns an empty string on any error.
- * Exported for unit tests.
- */
-export declare function readHostname(): string;
-/**
- * Read `ps -o command= -p <ppid>` safely. Returns the (truncated) command
- * or an empty string on any failure.
- *
- * Security: args are passed as an array, never interpolated into a shell
- * string. `ps` is the only executable spawned.
- */
-export declare function readPpidCommand(ppid: number): string;
-/**
- * Return the actual controlling tty path (e.g. `/dev/ttys001`) when one
- * exists, or the literal string `not-a-tty` otherwise. Bash-core parity
- * (push-review-core.sh §426): `tty 2>/dev/null || echo "not-a-tty"`.
- *
- * Codex pass-1 on phase 1 flagged the earlier `/dev/tty` literal as a
- * parity regression — the audit consumer expects the real device path so
- * forensic tooling can distinguish tty1 from tty2 on the same host.
- *
- * Implementation: we shell out to `tty(1)` exactly as bash does. On
- * systems without `tty` (distroless, minimal Alpine without coreutils-
- * full) we degrade to `not-a-tty`.
- */
-export declare function readTty(): string;

package/dist/hooks/review-gate/metadata.js

@@ -1,158 +0,0 @@
-/**
- * OS / agent / repo identity collection for audit records.
- *
- * Closes defect M (0.9.4): the bash core's `jq --arg os_pid "$PID"` wrote
- * the pid as a JSON string; the audit consumer expected an integer, and the
- * schema had to tolerate both. The TS port emits pid/ppid as numbers from
- * day one (the JS runtime's `process.pid` is already a `number`), removing
- * the whole class of jq `--arg` vs `--argjson` confusion.
- *
- * ## Why capture this at all
- *
- * A skip-audit record (`REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`) is
- * the one place the gate is voluntarily weakened. The actor field (from
- * `git config user.email`) is mutable — a process with write access to
- * `.git/config` can stamp any email it likes. Supplementing that with
- * non-forgeable host-level identity (uid, hostname, pid, ppid, tty, CI
- * flag) gives a forensic investigator something to cross-reference when
- * a skip record turns out to have been unauthorized.
- *
- * ## Determinism + testability
- *
- * Every collector is a plain function over `process` / `os` / `node:child_process`
- * so tests can stub the collector's inputs cleanly. The public API takes no
- * arguments (production use) and the helpers are exported for tests.
- */
-import { hostname, userInfo } from 'node:os';
-import { spawnSync } from 'node:child_process';
-/**
- * Collect current-process OS identity. Every individual collector degrades
- * to an empty-string fallback on any exception — matching the bash core's
- * `id -u || echo ""`, `whoami || echo ""`, `hostname || echo ""` pattern
- * (push-review-core.sh §420-422, 426). Codex pass-1 on phase 1 flagged
- * the earlier implementation that called `userInfo()` and `hostname()`
- * outside any try/catch and could therefore throw on hosts with broken
- * NSS/passwd lookups, which would silently block the skip-audit path.
- */
-export function collectOsIdentity() {
-    const { uid, whoami } = readUidAndWhoami();
-    const host = readHostname();
-    const pid = process.pid;
-    const ppid = process.ppid;
-    const ppid_cmd = readPpidCommand(ppid);
-    const tty = readTty();
-    const ci = process.env['CI'] ?? '';
-    return { uid, whoami, hostname: host, pid, ppid, ppid_cmd, tty, ci };
-}
-/**
- * Read POSIX uid + whoami. Each field is collected INDEPENDENTLY so a
- * partial-lookup-failure (e.g. LDAP/NSS returns the uid but no passwd
- * entry) still yields one field rather than dropping both. Bash-core
- * parity (push-review-core.sh §420-421): `id -u` and `whoami` are two
- * separate invocations, each with its own `|| echo ""` fallback.
- *
- * Codex pass-2 on phase 1 flagged the prior single-`userInfo()` version:
- * a broken NSS lookup zeroed out both fields at once, weakening forensic
- * metadata on shared hosts. We now prefer the POSIX primitives
- * (`os.userInfo()` internally reads the passwd entry) but isolate the
- * failures so uid and whoami cannot both disappear together when only
- * one of them is actually unavailable.
- */
-export function readUidAndWhoami() {
-    let uid = '';
-    let whoami = '';
-    try {
-        // Node exposes the raw numeric uid via process.getuid() on POSIX —
-        // this goes through the kernel, not through passwd. If it throws
-        // (Windows), the fallback is '' and we still try whoami below.
-        const getuid = process.getuid;
-        if (typeof getuid === 'function') {
-            const raw = getuid.call(process);
-            if (typeof raw === 'number' && raw >= 0)
-                uid = String(raw);
-        }
-    }
-    catch {
-        // swallow — uid stays ''
-    }
-    try {
-        const info = userInfo({ encoding: 'utf8' });
-        whoami = info.username ?? '';
-        // If the kernel-uid probe above failed but userInfo() succeeded, use
-        // its uid as a secondary source.
-        if (uid.length === 0 && typeof info.uid === 'number' && info.uid >= 0) {
-            uid = String(info.uid);
-        }
-    }
-    catch {
-        // swallow — whoami stays ''
-    }
-    return { uid, whoami };
-}
-/**
- * Read `hostname` via `os.hostname`. Returns an empty string on any error.
- * Exported for unit tests.
- */
-export function readHostname() {
-    try {
-        return hostname();
-    }
-    catch {
-        return '';
-    }
-}
-/**
- * Read `ps -o command= -p <ppid>` safely. Returns the (truncated) command
- * or an empty string on any failure.
- *
- * Security: args are passed as an array, never interpolated into a shell
- * string. `ps` is the only executable spawned.
- */
-export function readPpidCommand(ppid) {
-    if (!Number.isFinite(ppid) || ppid <= 0)
-        return '';
-    try {
-        const result = spawnSync('ps', ['-o', 'command=', '-p', String(ppid)], {
-            encoding: 'utf8',
-            timeout: 2_000,
-        });
-        if (result.status !== 0)
-            return '';
-        const out = (result.stdout ?? '').replace(/\n+$/, '');
-        return out.slice(0, 512);
-    }
-    catch {
-        return '';
-    }
-}
-/**
- * Return the actual controlling tty path (e.g. `/dev/ttys001`) when one
- * exists, or the literal string `not-a-tty` otherwise. Bash-core parity
- * (push-review-core.sh §426): `tty 2>/dev/null || echo "not-a-tty"`.
- *
- * Codex pass-1 on phase 1 flagged the earlier `/dev/tty` literal as a
- * parity regression — the audit consumer expects the real device path so
- * forensic tooling can distinguish tty1 from tty2 on the same host.
- *
- * Implementation: we shell out to `tty(1)` exactly as bash does. On
- * systems without `tty` (distroless, minimal Alpine without coreutils-
- * full) we degrade to `not-a-tty`.
- */
-export function readTty() {
-    try {
-        const result = spawnSync('tty', [], {
-            encoding: 'utf8',
-            timeout: 2_000,
-            stdio: ['inherit', 'pipe', 'pipe'],
-        });
-        if (result.status === 0) {
-            const out = (result.stdout ?? '').replace(/\n+$/, '');
-            if (out.length > 0)
-                return out;
-        }
-    }
-    catch {
-        // fall through to the not-a-tty fallback
-    }
-    return 'not-a-tty';
-}

package/dist/hooks/review-gate/policy.d.ts

@@ -1,55 +0,0 @@
-/**
- * Policy accessors for the review-gate modules.
- *
- * The bash core resolves `review.codex_required` via `node dist/scripts/read-
- * policy-field.js` and evaluates `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`
- * directly from env vars. The TS port composes the same behavior over the
- * already-TS `loadPolicy` helper, removing the fork/exec hop and the
- * exit-code-parsing that came with it.
- *
- * Fail-closed: when the policy file is malformed or unreadable, the
- * returned `codex_required` is `true`. This matches the bash core's
- * "treating as true" path (design §2, security carry-forward).
- */
-import type { Policy } from '../../policy/types.js';
-export interface ResolvedPolicy {
-    /** Resolved `review.codex_required`; true when malformed/absent. */
-    codex_required: boolean;
-    /** Resolved `review.allow_skip_in_ci`; false when absent. */
-    allow_skip_in_ci: boolean;
-    /** Full policy (undefined when load failed — caller emits a WARN). */
-    policy: Policy | null;
-    /** Warning text from the loader, if any — surfaced to stderr by the caller. */
-    warning: string | null;
-}
-/**
- * Resolve review-related policy fields. Never throws — any error path
- * returns `codex_required: true` with a `warning` populated so the caller
- * can decide whether to echo it.
- */
-export declare function resolveReviewPolicy(baseDir: string): ResolvedPolicy;
-/**
- * Skip-env evaluation. The bash core reads `REA_SKIP_PUSH_REVIEW` +
- * `REA_SKIP_CODEX_REVIEW` with simple non-empty semantics. We preserve
- * that exactly: any non-empty value triggers the skip path, and the
- * VALUE is used as the skip reason. Empty or unset = no skip.
- */
-export interface SkipEnv {
-    /** `REA_SKIP_PUSH_REVIEW` value or null. */
-    push_review_reason: string | null;
-    /** `REA_SKIP_CODEX_REVIEW` value or null. */
-    codex_review_reason: string | null;
-}
-export declare function readSkipEnv(env?: NodeJS.ProcessEnv): SkipEnv;
-/**
- * True iff `CI` env is set to a non-empty value. The bash core checks
- * `[[ -n "${CI:-}" ]]` — we match that.
- */
-export declare function isCiContext(env?: NodeJS.ProcessEnv): boolean;
-/**
- * Legacy-bash kill switch (design §11.2). When `REA_LEGACY_PUSH_REVIEW=1`,
- * the CLI entry point delegates to the preserved bash core for one
- * release window. Advertised in `rea doctor`; sunset after 90 days of
- * clean 0.11.x running on canaries.
- */
-export declare function isLegacyBashKillSwitchOn(env?: NodeJS.ProcessEnv): boolean;

package/dist/hooks/review-gate/policy.js

@@ -1,71 +0,0 @@
-/**
- * Policy accessors for the review-gate modules.
- *
- * The bash core resolves `review.codex_required` via `node dist/scripts/read-
- * policy-field.js` and evaluates `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`
- * directly from env vars. The TS port composes the same behavior over the
- * already-TS `loadPolicy` helper, removing the fork/exec hop and the
- * exit-code-parsing that came with it.
- *
- * Fail-closed: when the policy file is malformed or unreadable, the
- * returned `codex_required` is `true`. This matches the bash core's
- * "treating as true" path (design §2, security carry-forward).
- */
-import { loadPolicy } from '../../policy/loader.js';
-/**
- * Resolve review-related policy fields. Never throws — any error path
- * returns `codex_required: true` with a `warning` populated so the caller
- * can decide whether to echo it.
- */
-export function resolveReviewPolicy(baseDir) {
-    try {
-        const policy = loadPolicy(baseDir);
-        const review = policy.review;
-        const codex_required = review?.codex_required === false ? false : true;
-        const allow_skip_in_ci = review?.allow_skip_in_ci === true;
-        return {
-            codex_required,
-            allow_skip_in_ci,
-            policy,
-            warning: null,
-        };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        // Policy-file-not-found is a first-run condition for consumers running
-        // the gate before `rea init`; treat codex_required as true and surface
-        // the warning so the operator knows what state the gate is in.
-        return {
-            codex_required: true,
-            allow_skip_in_ci: false,
-            policy: null,
-            warning: `review-gate: could not load .rea/policy.yaml — ${msg}. Treating codex_required=true (fail-closed).`,
-        };
-    }
-}
-export function readSkipEnv(env = process.env) {
-    const pr = env['REA_SKIP_PUSH_REVIEW'];
-    const cr = env['REA_SKIP_CODEX_REVIEW'];
-    return {
-        push_review_reason: typeof pr === 'string' && pr.length > 0 ? pr : null,
-        codex_review_reason: typeof cr === 'string' && cr.length > 0 ? cr : null,
-    };
-}
-/**
- * True iff `CI` env is set to a non-empty value. The bash core checks
- * `[[ -n "${CI:-}" ]]` — we match that.
- */
-export function isCiContext(env = process.env) {
-    const v = env['CI'];
-    return typeof v === 'string' && v.length > 0;
-}
-/**
- * Legacy-bash kill switch (design §11.2). When `REA_LEGACY_PUSH_REVIEW=1`,
- * the CLI entry point delegates to the preserved bash core for one
- * release window. Advertised in `rea doctor`; sunset after 90 days of
- * clean 0.11.x running on canaries.
- */
-export function isLegacyBashKillSwitchOn(env = process.env) {
-    const v = env['REA_LEGACY_PUSH_REVIEW'];
-    return typeof v === 'string' && v.length > 0 && v !== '0';
-}

package/dist/hooks/review-gate/protected-paths.d.ts

@@ -1,46 +0,0 @@
-/**
- * Protected-path detection. Given a `git diff --name-status` output blob,
- * return true iff any change touches one of the prefixes in
- * `PROTECTED_PATH_PREFIXES`.
- *
- * ## Why this is a dedicated module
- *
- * The bash core uses `awk -v re='^(src/gateway/...)' '{...}'` inline in
- * the main gate loop (push-review-core.sh:904-923). That regex is
- * duplicated in `.husky/pre-push` (the native-git shim) and in at least
- * two places in THREAT_MODEL.md. A single TS helper with a grep-able
- * constant in `constants.ts` removes the drift risk.
- *
- * ## Input shape
- *
- * `git diff --name-status <merge_base>..<local_sha>` output. Each line is:
- *   <STATUS>\t<path1>[\t<path2>]
- * STATUS is one letter, possibly followed by a similarity score for
- * rename/copy (`R100`, `C95`). STATUS letters we care about: A, C, D, M,
- * R, T, U — the bash core's `status !~ /^[ACDMRTU]/` filter. We match
- * that exactly.
- */
-/**
- * Parse a single `git diff --name-status` line and extract the paths that
- * matter for protected-path detection. Rename (`R`) and copy (`C`) lines
- * carry two paths separated by tabs; both are checked against the
- * protected-path set.
- *
- * Returns an empty array for irrelevant status letters or malformed lines.
- */
-export declare function extractPathsFromStatusLine(line: string): string[];
-/**
- * True iff `path` starts with one of the protected-path prefixes. Exported
- * for unit tests; callers should usually use `diffTouchesProtectedPaths`.
- */
-export declare function isProtectedPath(filePath: string): boolean;
-/**
- * True iff the given `git diff --name-status` output contains at least
- * one protected-path hit. Returns the set of hit paths (deduped) for
- * audit-record metadata.
- */
-export interface ProtectedPathScanResult {
-    hit: boolean;
-    paths: string[];
-}
-export declare function scanNameStatusForProtectedPaths(nameStatusOutput: string): ProtectedPathScanResult;

package/dist/hooks/review-gate/protected-paths.js

@@ -1,76 +0,0 @@
-/**
- * Protected-path detection. Given a `git diff --name-status` output blob,
- * return true iff any change touches one of the prefixes in
- * `PROTECTED_PATH_PREFIXES`.
- *
- * ## Why this is a dedicated module
- *
- * The bash core uses `awk -v re='^(src/gateway/...)' '{...}'` inline in
- * the main gate loop (push-review-core.sh:904-923). That regex is
- * duplicated in `.husky/pre-push` (the native-git shim) and in at least
- * two places in THREAT_MODEL.md. A single TS helper with a grep-able
- * constant in `constants.ts` removes the drift risk.
- *
- * ## Input shape
- *
- * `git diff --name-status <merge_base>..<local_sha>` output. Each line is:
- *   <STATUS>\t<path1>[\t<path2>]
- * STATUS is one letter, possibly followed by a similarity score for
- * rename/copy (`R100`, `C95`). STATUS letters we care about: A, C, D, M,
- * R, T, U — the bash core's `status !~ /^[ACDMRTU]/` filter. We match
- * that exactly.
- */
-import { PROTECTED_PATH_PREFIXES } from './constants.js';
-/** Set of single-letter status codes the gate cares about. */
-const RELEVANT_STATUS = new Set(['A', 'C', 'D', 'M', 'R', 'T', 'U']);
-/**
- * Parse a single `git diff --name-status` line and extract the paths that
- * matter for protected-path detection. Rename (`R`) and copy (`C`) lines
- * carry two paths separated by tabs; both are checked against the
- * protected-path set.
- *
- * Returns an empty array for irrelevant status letters or malformed lines.
- */
-export function extractPathsFromStatusLine(line) {
-    if (line.length === 0)
-        return [];
-    const parts = line.split('\t');
-    if (parts.length < 2)
-        return [];
-    const status = parts[0] ?? '';
-    if (status.length === 0)
-        return [];
-    const statusLetter = status[0];
-    if (statusLetter === undefined || !RELEVANT_STATUS.has(statusLetter)) {
-        return [];
-    }
-    return parts.slice(1).filter((p) => p.length > 0);
-}
-/**
- * True iff `path` starts with one of the protected-path prefixes. Exported
- * for unit tests; callers should usually use `diffTouchesProtectedPaths`.
- */
-export function isProtectedPath(filePath) {
-    for (const prefix of PROTECTED_PATH_PREFIXES) {
-        if (filePath.startsWith(prefix))
-            return true;
-        // A bare `.rea` or `hooks` path (no trailing slash) is a directory
-        // boundary match — `.rea/audit.jsonl` passes, `my-rea.config` does
-        // not. startsWith on the prefix-with-slash enforces that naturally.
-    }
-    return false;
-}
-export function scanNameStatusForProtectedPaths(nameStatusOutput) {
-    if (nameStatusOutput.length === 0) {
-        return { hit: false, paths: [] };
-    }
-    const hits = new Set();
-    for (const line of nameStatusOutput.split('\n')) {
-        const paths = extractPathsFromStatusLine(line);
-        for (const p of paths) {
-            if (isProtectedPath(p))
-                hits.add(p);
-        }
-    }
-    return { hit: hits.size > 0, paths: Array.from(hits).sort() };
-}