@bookedsolid/rea 0.32.0 → 0.34.0

package/dist/hooks/architecture-review-gate/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Node-binary port of `hooks/architecture-review-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #4 — the SIMPLEST tier-1 port.
+ *
+ * PostToolUse Write/Edit advisory. Reads `policy.architecture_review.
+ * patterns` and prints an advisory banner to stderr when the just-
+ * written file path begins with one of the configured prefixes.
+ * ALWAYS exits 0 — this is a nudge, not a gate.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner. (Even though the
+ *      gate is advisory, HALT short-circuits ALL hooks.)
+ *   2. `policy.architecture_advisory: false` short-circuit → exit 0
+ *      silently. The bash hook reads the policy file with a grep
+ *      `architecture_advisory: false`; we mirror via the canonical
+ *      YAML loader.
+ *   3. Read stdin → `tool_input.file_path` (the bash hook uses
+ *      `notebook_path` too via fall-through, but the original
+ *      `jq -r '.tool_input.file_path // empty'` expression does NOT
+ *      fall through to notebook_path. We preserve that exactly).
+ *   4. Empty file_path → exit 0.
+ *   5. Path normalization mirrors `_lib/path-normalize.sh::normalize_path`:
+ *        - Convert backslashes to forward slashes (Windows / Git Bash).
+ *        - URL-decode `%xx` sequences.
+ *        - Strip a leading `<REA_ROOT>/` prefix if present so
+ *          `policy.architecture_review.patterns` can use repo-relative
+ *          patterns.
+ *   6. Read `policy.architecture_review.patterns`. Empty / unset →
+ *      silent no-op (exit 0). The bst-internal profile pins rea-
+ *      source patterns; consumer projects opt in by populating their
+ *      own list.
+ *   7. First prefix match wins. Emit the advisory banner to stderr;
+ *      exit 0.
+ *
+ * Distinct from the other 0.33.0 ports: this gate is POSTToolUse
+ * (fires AFTER the write, advisory only). The shim that invokes it
+ * should NOT fail-closed on missing CLI — the pre-0.33.0 bash hook
+ * was already a silent no-op when the policy was unset.
+ */
+import type { Buffer } from 'node:buffer';
+export interface ArchitectureReviewGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface ArchitectureReviewGateResult {
+    exitCode: number;
+    stderr: string;
+    /** Test seam — the matched pattern (or `null`). */
+    matched: string | null;
+}
+export declare function runArchitectureReviewGate(options?: ArchitectureReviewGateOptions): Promise<ArchitectureReviewGateResult>;
+/**
+ * CLI entry — `rea hook architecture-review-gate`.
+ */
+export declare function runHookArchitectureReviewGate(options?: ArchitectureReviewGateOptions): Promise<void>;

package/dist/hooks/architecture-review-gate/index.js

@@ -0,0 +1,250 @@
+/**
+ * Node-binary port of `hooks/architecture-review-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #4 — the SIMPLEST tier-1 port.
+ *
+ * PostToolUse Write/Edit advisory. Reads `policy.architecture_review.
+ * patterns` and prints an advisory banner to stderr when the just-
+ * written file path begins with one of the configured prefixes.
+ * ALWAYS exits 0 — this is a nudge, not a gate.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner. (Even though the
+ *      gate is advisory, HALT short-circuits ALL hooks.)
+ *   2. `policy.architecture_advisory: false` short-circuit → exit 0
+ *      silently. The bash hook reads the policy file with a grep
+ *      `architecture_advisory: false`; we mirror via the canonical
+ *      YAML loader.
+ *   3. Read stdin → `tool_input.file_path` (the bash hook uses
+ *      `notebook_path` too via fall-through, but the original
+ *      `jq -r '.tool_input.file_path // empty'` expression does NOT
+ *      fall through to notebook_path. We preserve that exactly).
+ *   4. Empty file_path → exit 0.
+ *   5. Path normalization mirrors `_lib/path-normalize.sh::normalize_path`:
+ *        - Convert backslashes to forward slashes (Windows / Git Bash).
+ *        - URL-decode `%xx` sequences.
+ *        - Strip a leading `<REA_ROOT>/` prefix if present so
+ *          `policy.architecture_review.patterns` can use repo-relative
+ *          patterns.
+ *   6. Read `policy.architecture_review.patterns`. Empty / unset →
+ *      silent no-op (exit 0). The bst-internal profile pins rea-
+ *      source patterns; consumer projects opt in by populating their
+ *      own list.
+ *   7. First prefix match wins. Emit the advisory banner to stderr;
+ *      exit 0.
+ *
+ * Distinct from the other 0.33.0 ports: this gate is POSTToolUse
+ * (fires AFTER the write, advisory only). The shim that invokes it
+ * should NOT fail-closed on missing CLI — the pre-0.33.0 bash hook
+ * was already a silent no-op when the policy was unset.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseWriteHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+/**
+ * Normalize the incoming file path. Mirrors
+ * `hooks/_lib/path-normalize.sh::normalize_path`:
+ *   - backslashes → forward slashes
+ *   - URL-decoded
+ *   - leading `<REA_ROOT>/` stripped (when applicable)
+ *
+ * Pre-0.16.0 the bash hook ONLY stripped the REA_ROOT prefix, which
+ * meant Windows / Git Bash backslash paths bypassed advisory.
+ */
+function normalizePath(rawPath, reaRoot) {
+    let p = rawPath.replace(/\\/g, '/');
+    try {
+        p = decodeURIComponent(p);
+    }
+    catch {
+        // Malformed % escape — leave the string unchanged. The bash
+        // helper's `printf '%b'` behavior is similar (passes through).
+    }
+    // Strip leading <REA_ROOT>/. Compare normalized forms.
+    const normRoot = reaRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normRoot.length > 0) {
+        if (p === normRoot)
+            return '';
+        const withSep = normRoot + '/';
+        if (p.startsWith(withSep)) {
+            p = p.slice(withSep.length);
+        }
+    }
+    // 2026-05-15 codex round-1 P3 fix: strip chains of leading `./`
+    // segments. Mirrors `_lib/path-normalize.sh::path_canonical_form`.
+    // Pre-fix `./src/gateway/foo.ts` did NOT match the `src/gateway/`
+    // pattern because the leading `./` was preserved. Bash's
+    // path_canonical_form collapses `./` chains, so `./src/...`,
+    // `././src/...`, etc. all reduce to `src/...`.
+    while (p.startsWith('./')) {
+        p = p.slice(2);
+    }
+    return p;
+}
+function buildAdvisoryBanner(filePath, matched) {
+    return [
+        'ARCHITECTURE ADVISORY: Sensitive path modified\n',
+        '\n',
+        `  File: ${filePath}\n`,
+        `  Category: ${matched}\n`,
+        '\n',
+        '  This file is in an architecture-sensitive directory.\n',
+        '  Consider: Does this change maintain backward compatibility?\n',
+        '  Consider: Should this be reviewed by the principal-engineer agent?\n',
+    ].join('');
+}
+/**
+ * Read `policy.architecture_review.patterns`. Returns `[]` on:
+ *   - policy file missing
+ *   - YAML unparseable
+ *   - architecture_review unset
+ *   - architecture_review.patterns unset/empty/non-list
+ *
+ * 2026-05-15 codex round-1 P3 fix: do NOT use `loadPolicy()` here.
+ * The strict zod schema throws on legacy keys / extra fields, which
+ * caused the catch to swallow patterns silently — a legacy policy.yaml
+ * with one unknown key would disable the advisory entirely, with no
+ * indication to the user.
+ *
+ * The bash original used `policy_list` (a non-strict reader). To match
+ * that behavior we read the YAML directly via the same permissive
+ * parser that `rea hook policy-get` uses (`yaml` package's `parse`),
+ * then pull `architecture_review.patterns` as a list of strings. Any
+ * non-string entry is filtered out. Unknown keys ELSEWHERE in the
+ * policy are tolerated — only the patterns subset matters for this
+ * advisory.
+ */
+function loadArchitecturePatterns(reaRoot, onWarning) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        // File missing — bash hook treats this as "advisory disabled".
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        // Unparseable YAML — log to stderr (NOT silent) and return [].
+        // The advisory still short-circuits to exit 0 since this is an
+        // advisory tier, but the user sees a one-line warning instead of
+        // mysterious silence.
+        onWarning('architecture-review-gate: policy.yaml is unparseable; advisory disabled\n');
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const ar = parsed['architecture_review'];
+    if (ar === undefined || ar === null || typeof ar !== 'object' || Array.isArray(ar)) {
+        return [];
+    }
+    const patterns = ar['patterns'];
+    if (!Array.isArray(patterns))
+        return [];
+    const out = [];
+    for (const entry of patterns) {
+        if (typeof entry === 'string' && entry.length > 0) {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Quick policy-disable probe. The bash hook reads
+ * `architecture_advisory: false` (legacy key — pre-0.20.1 toggle)
+ * directly from policy.yaml via grep. The canonical loader doesn't
+ * surface this key (it's not in the strict schema), so we re-read
+ * the raw YAML text. Returns true when the key is present and
+ * literally `false` (no other value disables the hook in the bash
+ * implementation).
+ */
+function isAdvisoryDisabled(reaRoot) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return /^architecture_advisory:\s*false\b/m.test(raw);
+}
+export async function runArchitectureReviewGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr, matched: null };
+    }
+    // 2. Disabled?
+    if (isAdvisoryDisabled(reaRoot)) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    // 3. Stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let filePath = '';
+    try {
+        const payload = parseWriteHookPayload(stdinRaw);
+        filePath = payload.filePath;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            // Advisory tier: silently exit 0 on malformed payload. The bash
+            // hook used `jq -r '.tool_input.file_path // empty'` which
+            // coerces malformed JSON to empty stdout, then exits 0. Mirror
+            // that — never refuse on a parse error in the advisory path.
+            return { exitCode: 0, stderr, matched: null };
+        }
+        throw err;
+    }
+    if (filePath.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    const normalized = normalizePath(filePath, reaRoot);
+    if (normalized.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    const patterns = loadArchitecturePatterns(reaRoot, writeStderr);
+    if (patterns.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    let matched = null;
+    for (const pattern of patterns) {
+        if (normalized.startsWith(pattern)) {
+            matched = pattern;
+            break;
+        }
+    }
+    if (matched === null) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    writeStderr(buildAdvisoryBanner(normalized, matched));
+    return { exitCode: 0, stderr, matched };
+}
+/**
+ * CLI entry — `rea hook architecture-review-gate`.
+ */
+export async function runHookArchitectureReviewGate(options = {}) {
+    const result = await runArchitectureReviewGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}

package/dist/hooks/changeset-security-gate/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Node-binary port of `hooks/changeset-security-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #3.
+ *
+ * Guards `.changeset/*.md` files against two failure modes:
+ *
+ *   1. SECURITY DISCLOSURE LEAK — a GHSA or CVE identifier in a
+ *      changeset file becomes public via CHANGELOG.md when the
+ *      release ships. Block the write.
+ *   2. MISSING OR MALFORMED FRONTMATTER — a changeset without a
+ *      proper frontmatter block is silently ignored by the
+ *      changesets tool, wasting the release entry. Block the write.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Tool filter: only `Write`, `Edit`, `MultiEdit`, `NotebookEdit`.
+ *      Any other tool exits 0.
+ *   3. File-path filter: only `.changeset/*.md` files. The
+ *      `.changeset/README.md` companion is excluded (it's metadata
+ *      for the changesets tool itself).
+ *   4. Security disclosure scan on the resolved content. The
+ *      ordered pattern list is reproduced verbatim. First match wins;
+ *      emit the `MATCHED_PATTERN` placeholder.
+ *   5. MultiEdit short-circuit for frontmatter: MultiEdit's
+ *      `edits[].new_string` is a list of replacement FRAGMENTS, not
+ *      a full file. Running frontmatter validation against the
+ *      concatenated fragments would reject every legitimate edit.
+ *      The bash hook added this exemption in 0.15.0; we mirror it.
+ *      The disclosure scan still runs on the fragments because
+ *      GHSA/CVE patterns match per-fragment without structural
+ *      assumption.
+ *   6. Frontmatter validation:
+ *        a. Must start with `---`.
+ *        b. Must contain at least one `<pkg>: (patch|minor|major)`
+ *           entry inside the first `---`/`---` block. Accepts
+ *           single-quoted, double-quoted, and unquoted package
+ *           names — same explicit alternation form as the bash hook
+ *           (0.15.0 codex round-1 P2-1 fix).
+ *        c. Must have a non-empty description after the closing
+ *           `---`.
+ *
+ * Block emissions use the Claude Code PreToolUse JSON-on-stdout
+ * protocol via `emitJsonBlock`, mirroring `_lib/common.sh::json_output`
+ * — JSON on stdout AND the human reason on stderr, exit 2.
+ */
+import type { Buffer } from 'node:buffer';
+export interface ChangesetSecurityGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+    stdoutWrite?: (s: string) => void;
+}
+export interface ChangesetSecurityGateResult {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}
+export declare function runChangesetSecurityGate(options?: ChangesetSecurityGateOptions): Promise<ChangesetSecurityGateResult>;
+/**
+ * CLI entry — `rea hook changeset-security-gate`.
+ */
+export declare function runHookChangesetSecurityGate(options?: ChangesetSecurityGateOptions): Promise<void>;
+export declare const __INTERNAL_DISCLOSURE_PATTERNS_FOR_TESTS: readonly string[];
+export declare const __INTERNAL_FRONTMATTER_PATTERN_FOR_TESTS: RegExp;
+export declare const __INTERNAL_BANNERS_FOR_TESTS: {
+    MISSING_FRONTMATTER_BANNER: string;
+    INVALID_FRONTMATTER_BANNER: string;
+    MISSING_DESCRIPTION_BANNER: string;
+};