@bookedsolid/rea 0.26.1 → 0.28.0

package/dist/cli/preflight.js

@@ -124,10 +124,20 @@ export async function computePreflight(baseDir, options, env = process.env) {
     if (!reviewCheckSkipped) {
         const lookup = findRecentLocalReview(baseDir, headSha, maxAgeSeconds, new Date(), contentToken);
         if (!lookup.found) {
+            // 0.28.0 round-29 P3: when the most recent path-matching audit
+            // entry was blocking/error, the operator HAS reviewed — they
+            // just need to address the findings. The original message ("no
+            // recent local-review audit entry covers HEAD") makes them
+            // think they forgot to review. Distinguish the two cases.
+            const reason = lookup.last_blocking_verdict === 'blocking'
+                ? 'your last local review was blocking — address findings or override'
+                : lookup.last_blocking_verdict === 'error'
+                    ? 'your last local review errored — re-run `rea review` and address findings'
+                    : 'no recent local-review audit entry covers HEAD';
             return {
                 outcome: {
                     status: 'refuse',
-                    reason: 'no recent local-review audit entry covers HEAD',
+                    reason,
                     exitCode: 2,
                     details: {
                         head_sha: headSha,
@@ -135,6 +145,12 @@ export async function computePreflight(baseDir, options, env = process.env) {
                         max_age_seconds: maxAgeSeconds,
                         bypass_env_var: bypassEnvVar,
                         policy_off_switch: 'policy.review.local_review.mode: off',
+                        ...(lookup.last_blocking_verdict !== undefined
+                            ? {
+                                last_blocking_verdict: lookup.last_blocking_verdict,
+                                last_blocking_timestamp: lookup.last_blocking_timestamp,
+                            }
+                            : {}),
                     },
                 },
                 policy,
@@ -292,6 +308,21 @@ function resolveCommitCountBase(baseDir) {
         if (resolveRef(baseDir, ref).length > 0)
             return ref;
     }
+    // 0.28.0 round-29 P3: develop-branch repos sometimes omit
+    // `origin/HEAD` entirely (the symbolic ref is unset until a fresh
+    // `git remote set-head origin -a`), and `origin/main` /
+    // `origin/master` may not exist when the trunk is `origin/develop`.
+    // Pre-fix the resolver silently fell through to `null`, disabling
+    // the auto-narrow check without telling the operator. Emit a single
+    // advisory line on stderr so the failure mode is visible — but do
+    // not fail; this path is best-effort and a missing trunk is a
+    // recoverable misconfiguration.
+    if (resolveRef(baseDir, 'origin/develop').length > 0) {
+        process.stderr.write(`rea: preflight commit-count base falling through to origin/develop ` +
+            `(origin/HEAD/main/master not resolvable). ` +
+            `Consider: \`git remote set-head origin -a\` to seed origin/HEAD.\n`);
+        return 'origin/develop';
+    }
     // `@{upstream}` LAST. We additionally probe what it resolves to —
     // if it's a remote feature-branch ref under `refs/remotes/origin/`
     // (not a primary trunk ref we already tried), the candidate is
@@ -365,6 +396,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
     }
     const lines = raw.split(/\r?\n/);
     const cutoffMs = now.getTime() - maxAgeSeconds * 1000;
+    // 0.28.0 round-29 P3: track the most recent blocking/error entry that
+    // path-matched HEAD even though it didn't qualify as coverage. The
+    // not-found return path consumes this so the operator-facing message
+    // distinguishes "you haven't reviewed" from "your review found
+    // problems".
+    let lastBlockingVerdict;
+    let lastBlockingTimestamp;
     // Walk in reverse — most recent first.
     for (let i = lines.length - 1; i >= 0; i--) {
         const line = lines[i];
@@ -421,8 +459,19 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
         if (matchKind === null)
             continue;
         const verdict = typeof metadata.verdict === 'string' ? metadata.verdict : '';
-        if (verdict === 'error' || verdict === 'blocking')
+        if (verdict === 'error' || verdict === 'blocking') {
+            // 0.28.0 round-29 P3 — capture the FIRST (i.e., most-recent in
+            // reverse walk) blocking/error entry that path-matched HEAD so
+            // the not-found path can render a better message. Don't
+            // overwrite a later catch — we want the most-recent one.
+            if (lastBlockingVerdict === undefined) {
+                lastBlockingVerdict = verdict;
+                const ts = typeof record.timestamp === 'string' ? record.timestamp : '';
+                if (ts.length > 0)
+                    lastBlockingTimestamp = ts;
+            }
             continue;
+        }
         const timestamp = typeof record.timestamp === 'string' ? record.timestamp : '';
         if (timestamp.length > 0) {
             const ts = Date.parse(timestamp);
@@ -430,7 +479,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
                 // Older than max_age_seconds — keep walking; a more recent valid
                 // record may exist further back? No: we walk newest-to-oldest so
                 // anything older from here on is also stale. Stop early.
-                return { found: false };
+                return {
+                    found: false,
+                    ...(lastBlockingVerdict !== undefined ? { last_blocking_verdict: lastBlockingVerdict } : {}),
+                    ...(lastBlockingTimestamp !== undefined
+                        ? { last_blocking_timestamp: lastBlockingTimestamp }
+                        : {}),
+                };
             }
         }
         return {
@@ -441,7 +496,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
             match_kind: matchKind,
         };
     }
-    return { found: false };
+    return {
+        found: false,
+        ...(lastBlockingVerdict !== undefined ? { last_blocking_verdict: lastBlockingVerdict } : {}),
+        ...(lastBlockingTimestamp !== undefined
+            ? { last_blocking_timestamp: lastBlockingTimestamp }
+            : {}),
+    };
 }
 async function safeAudit(baseDir, toolName, status, metadata, policy) {
     try {

package/dist/cli/status.d.ts

@@ -75,6 +75,12 @@ export interface LiveDownstreamSnapshot {
     circuit_state: 'closed' | 'open' | 'half-open';
     retry_at: string | null;
     last_error: string | null;
+    /**
+     * 0.28.0 helix-025 F1 — `'never' | 'ok' | 'errored'` tri-state.
+     * `null` for snapshots written by pre-0.28.0 gateways that did not
+     * include the field (back-compat).
+     */
+    connection_state: 'never' | 'ok' | 'errored' | null;
     tools_count: number | null;
     open_transitions: number;
     session_blocker_emitted: boolean;

package/dist/cli/status.js

@@ -129,6 +129,12 @@ function parseDownstreamEntry(raw) {
     const circuit = r.circuit_state === 'open' || r.circuit_state === 'half-open' || r.circuit_state === 'closed'
         ? r.circuit_state
         : 'closed';
+    // 0.28.0 helix-025 F1: tri-state. `null` when the snapshot was written
+    // by a pre-0.28.0 gateway (back-compat) — the pretty-printer renders
+    // that as "—" rather than fabricating a value.
+    const connectionState = r.connection_state === 'never' || r.connection_state === 'ok' || r.connection_state === 'errored'
+        ? r.connection_state
+        : null;
     return {
         name: r.name,
         connected: typeof r.connected === 'boolean' ? r.connected : false,
@@ -136,6 +142,7 @@ function parseDownstreamEntry(raw) {
         circuit_state: circuit,
         retry_at: typeof r.retry_at === 'string' ? r.retry_at : null,
         last_error: typeof r.last_error === 'string' ? r.last_error : null,
+        connection_state: connectionState,
         tools_count: typeof r.tools_count === 'number' && Number.isInteger(r.tools_count) ? r.tools_count : null,
         open_transitions: typeof r.open_transitions === 'number' && Number.isInteger(r.open_transitions)
             ? r.open_transitions

package/dist/cli/verify-claim.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `rea verify-claim <claim-id>` — replay a recorded security-claim PoC
+ * battery against the currently-installed (or in-tree dogfood) rea CLI.
+ *
+ * The centerpiece of 0.28.0 (4th structural pivot — claims as
+ * machine-verifiable artifacts rather than prose-only release notes).
+ *
+ * Each claim lives at `data/claims/<id>.json` and lists 1..N PoCs.
+ * Every PoC has a `type` that names the executor:
+ *
+ *   - `scan-bash` (primary): pipes `input` into
+ *     `dist/cli/index.js hook scan-bash --mode <protected|blocked>` and
+ *     compares the resulting verdict to `expected_verdict`.
+ *   - `shellcheck` (helix-031 case): runs shellcheck on `target` and
+ *     asserts the run is clean (no SC<code> warnings).
+ *
+ * Resolution order for the rea CLI under test:
+ *
+ *   - `--installed` → resolves to `<cwd>/node_modules/@bookedsolid/rea/dist/cli/index.js`.
+ *     This is the canonical "verify against MY pinned rea" mode for
+ *     consumers — tells them whether the version they actually have
+ *     installed still rejects the PoCs the claim targets.
+ *   - default → uses the same `dist/cli/index.js` that ships with the
+ *     CLI itself (i.e. the rea repo's own dogfood). Resolved relative
+ *     to the running script.
+ *
+ * Exit codes:
+ *
+ *   - 0 — every PoC matched the recorded `expected_verdict`.
+ *   - 1 — at least one PoC mismatched (regression — investigate).
+ *   - 2 — claim id is unknown / no JSON file at `data/claims/<id>.json`.
+ */
+import { type SpawnSyncReturns } from 'node:child_process';
+import type { Command } from 'commander';
+export interface ScanBashPoC {
+    id: string;
+    type: 'scan-bash';
+    input: string;
+    mode: 'protected' | 'blocked';
+    expected_verdict: 'allow' | 'block';
+}
+export interface ShellcheckPoC {
+    id: string;
+    type: 'shellcheck';
+    target: string;
+    expected_verdict: 'clean';
+}
+export type ClaimPoC = ScanBashPoC | ShellcheckPoC;
+export interface Claim {
+    id: string;
+    title: string;
+    introduced_in: string;
+    closed_in: string;
+    summary?: string;
+    pocs: ClaimPoC[];
+}
+export interface VerifyClaimOptions {
+    /** Resolve the CLI to `<cwd>/node_modules/@bookedsolid/rea/dist/cli/index.js`. */
+    installed?: boolean;
+    /** Emit a single JSON document on stdout. */
+    json?: boolean;
+    /**
+     * Override the claim-file root. Production resolves this internally
+     * (ships at `data/claims/` next to the package). Tests pass an
+     * absolute path so they can stage fixtures.
+     */
+    claimsDir?: string;
+    /**
+     * Override the rea CLI under test. Wins over `installed`. Used by
+     * tests to point at a stub binary. Production callers leave this
+     * unset.
+     */
+    cliOverride?: string;
+    /**
+     * Override the working directory the `--installed` resolver uses.
+     * Defaults to `process.cwd()`; tests pass a tmp dir.
+     */
+    cwd?: string;
+}
+export interface PoCResult {
+    poc_id: string;
+    type: ClaimPoC['type'];
+    expected: string;
+    actual: string;
+    match: boolean;
+    /** Empty on match; populated on mismatch with a one-line diagnostic. */
+    detail: string;
+}
+export interface VerifyClaimResult {
+    claim_id: string;
+    cli: string;
+    total: number;
+    matched: number;
+    mismatched: number;
+    results: PoCResult[];
+    exit_code: 0 | 1 | 2;
+}
+/**
+ * Resolve the directory holding the bundled claim JSON files. Walks up
+ * from the running script (or from this file at dev time) looking for
+ * a `data/claims/` sibling. Returns null when the directory cannot be
+ * located — the caller falls back to whatever `claimsDir` override was
+ * passed.
+ */
+export declare function resolveDefaultClaimsDir(): string | null;
+/**
+ * Load and validate a claim file. Throws on malformed JSON or shape
+ * mismatch — `runVerifyClaim` translates the throw into exit-code 2 +
+ * a stderr message.
+ */
+export declare function loadClaim(claimsDir: string, claimId: string): Claim;
+/**
+ * Resolve the rea CLI to invoke for `scan-bash` PoCs.
+ *
+ * Precedence: cliOverride > --installed > sibling dogfood dist/cli/index.js.
+ *
+ * Returns a pair `[command, args]` so the caller can do
+ * `spawnSync(cmd, [...args, 'hook', 'scan-bash', ...])`. The shape
+ * keeps node-vs-direct-binary differences localized to this resolver.
+ */
+export declare function resolveCli(opts: VerifyClaimOptions): {
+    cmd: string;
+    args: string[];
+    path: string;
+};
+interface SpawnImpl {
+    (cmd: string, args: string[], options: {
+        input?: string;
+        encoding: 'utf8';
+        timeout: number;
+    }): SpawnSyncReturns<string>;
+}
+/**
+ * Run a single PoC against the resolved CLI. Pure function — no global
+ * state, all dependencies threaded through `cliCmd` / `cliArgs` / `spawn`.
+ * Tests substitute `spawn` with a fake.
+ */
+export declare function runPoC(poc: ClaimPoC, cliCmd: string, cliArgs: string[], spawn?: SpawnImpl, cwd?: string): PoCResult;
+/**
+ * Run all PoCs in a claim. Pure — exposed so tests can drive without
+ * spawning processes if they substitute `spawn`.
+ */
+export declare function runVerifyClaimSync(claim: Claim, cliCmd: string, cliArgs: string[], cliPath: string, spawn?: SpawnImpl, cwd?: string): VerifyClaimResult;
+export declare function runVerifyClaim(claimId: string, opts: VerifyClaimOptions): Promise<void>;
+/**
+ * Attach `rea verify-claim <claim-id>` to the commander program.
+ */
+export declare function registerVerifyClaimCommand(program: Command): void;
+export {};