@bookedsolid/rea 0.40.0 → 0.41.0

package/dist/cli/audit-summary.js

@@ -0,0 +1,479 @@
+/**
+ * `rea audit summary` — high-level audit-log overview (0.41.0).
+ *
+ * The audit log is rich and `rea audit specialists` already exists for
+ * one narrow event-class. `rea audit summary` complements it with a
+ * broad rollup: total events, counts by `tool_name`, by tier, by
+ * session, by status, the time window covered, and a sample-verified
+ * chain-integrity check.
+ *
+ * # Filtering
+ *
+ * `--since <duration>` accepts a compact duration string
+ * (`s`/`m`/`h`/`d`/`w`) and filters records by `timestamp >= now -
+ * duration`. Examples: `24h`, `7d`, `90m`, `2w`. This is DIFFERENT
+ * from `rea audit verify --since <file>` / `rea audit specialists
+ * --since <file>` which take a rotated-file ANCHOR, not a duration —
+ * the two `--since` semantics serve different needs (anchor for chain
+ * walks, duration for summarization) and we accept the surface area
+ * cost. The duration form is what consumers reach for when asking
+ * "what happened in the last day?".
+ *
+ * # Chain integrity
+ *
+ * `rea audit verify` does the rigorous per-record re-hash. `summary`
+ * samples up to `CHAIN_SAMPLE_SIZE` records, evenly spaced through
+ * the filtered window, and reports `ok` / `tampered` / `unsampled`
+ * (window empty). Operators who suspect tampering should still run
+ * `rea audit verify` for an authoritative answer.
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "window_seconds": 86400,
+ *       "window_start": "2026-05-15T13:42:00Z",
+ *       "window_end":   "2026-05-16T13:42:00Z",
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"],
+ *       "total_events": 1247,
+ *       "by_tool_name": { "Bash": 612, "Edit": 289, … },
+ *       "by_tier":      { "read": 683, "write": 416, "destructive": 148 },
+ *       "by_status":    { "allowed": 1242, "denied": 5, "error": 0 },
+ *       "by_session":   { "session-abc…": 312, "session-def…": 935 },
+ *       "session_count": 8,
+ *       "earliest_timestamp": "2026-05-15T13:43:01.103Z",
+ *       "latest_timestamp":   "2026-05-16T13:41:57.842Z",
+ *       "chain_integrity": "ok",
+ *       "chain_samples_verified": 12
+ *     }
+ *
+ * # Walk scope
+ *
+ * v1 walks the current `.rea/audit.jsonl` plus EVERY rotated file
+ * whose latest record falls within the window. Older rotated files
+ * are skipped — they cannot contain in-window records. When `--since`
+ * is omitted, no time filter is applied and the walk covers the
+ * current `audit.jsonl` only (operators wanting historical depth
+ * should pass `--since <DUR>`).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { computeHash, GENESIS_HASH } from '../audit/fs.js';
+import { listRotatedAuditFiles } from './audit-specialists.js';
+import { AUDIT_FILE, REA_DIR, err, log } from './utils.js';
+export const AUDIT_SUMMARY_SCHEMA_VERSION = 1;
+/** Hard cap on chain-integrity samples. Keeps `rea audit summary`
+ *  fast even on large logs while still surfacing obvious tampering. */
+export const CHAIN_SAMPLE_SIZE = 12;
+/**
+ * Thrown by `computeAuditSummary` when `--since` cannot be parsed.
+ * The commander wrapper exits 1.
+ */
+export class AuditSummarySinceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditSummarySinceError';
+    }
+}
+/**
+ * Parse a compact duration string into seconds. Accepts:
+ *
+ *   - `<N>s` — seconds
+ *   - `<N>m` — minutes
+ *   - `<N>h` — hours
+ *   - `<N>d` — days
+ *   - `<N>w` — weeks (7 days)
+ *
+ * `N` must be a positive integer with no whitespace. Returns the
+ * number of seconds; throws `AuditSummarySinceError` on parse failure.
+ *
+ * We deliberately do not accept bare numbers (would be ambiguous) or
+ * fractional units (no real use case; complicates rendering).
+ */
+export function parseDurationSeconds(raw) {
+    const m = /^(\d+)(s|m|h|d|w)$/i.exec(raw.trim());
+    if (m === null) {
+        throw new AuditSummarySinceError(`--since: cannot parse ${JSON.stringify(raw)}. ` +
+            `Expected <N><unit> where unit is s|m|h|d|w (e.g. 24h, 7d, 90m).`);
+    }
+    const n = Number.parseInt(m[1], 10);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new AuditSummarySinceError(`--since: duration must be a positive integer; got ${JSON.stringify(raw)}.`);
+    }
+    const unit = m[2].toLowerCase();
+    const factor = {
+        s: 1,
+        m: 60,
+        h: 60 * 60,
+        d: 60 * 60 * 24,
+        w: 60 * 60 * 24 * 7,
+    };
+    return n * factor[unit];
+}
+/**
+ * Resolve the audit files to walk. Always includes the current
+ * `audit.jsonl` (when it exists).
+ *
+ *   - `windowStart === null` (no `--since`): walk EVERY rotated file
+ *     PLUS the current `audit.jsonl`. Round-1 P2: the prior shape
+ *     dropped rotated history silently while the header still
+ *     advertised "all time", undercounting long-lived repos.
+ *   - `windowStart` set: walk every rotated file whose basename
+ *     timestamp >= the cutoff, PLUS one rotated file immediately
+ *     before the cutoff (the in-flight file at cutoff time may
+ *     contain in-window records).
+ *
+ * Sort order is timestamp-ascending; the current `audit.jsonl` is
+ * always appended last (it is the newest segment of the chain).
+ */
+async function resolveSummaryFileWalk(baseDir, windowStart) {
+    const reaDir = path.join(baseDir, REA_DIR);
+    const currentAudit = path.join(reaDir, AUDIT_FILE);
+    const files = [];
+    const rotated = await listRotatedAuditFiles(reaDir);
+    if (windowStart === null) {
+        // Walk every rotated segment. The "all time" header would be a
+        // lie otherwise.
+        for (const name of rotated)
+            files.push(path.join(reaDir, name));
+    }
+    else {
+        // Rotated filenames are `audit-YYYYMMDD-HHMMSS(-N).jsonl` in UTC.
+        // We treat each filename as "rotated at this instant" and include
+        // every file rotated >= windowStart, plus one file immediately
+        // before windowStart (the in-flight file at cutoff time may
+        // contain in-window records).
+        const stampToDate = (name) => {
+            const m = /^audit-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/.exec(name);
+            if (m === null)
+                return null;
+            const iso = `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`;
+            const d = new Date(iso);
+            return Number.isNaN(d.getTime()) ? null : d;
+        };
+        const cutoffIdx = rotated.findIndex((n) => {
+            const d = stampToDate(n);
+            return d !== null && d >= windowStart;
+        });
+        const startIdx = cutoffIdx === -1 ? Math.max(0, rotated.length - 1) : Math.max(0, cutoffIdx - 1);
+        for (const name of rotated.slice(startIdx)) {
+            files.push(path.join(reaDir, name));
+        }
+    }
+    try {
+        const stat = await fs.stat(currentAudit);
+        if (stat.isFile())
+            files.push(currentAudit);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    return files;
+}
+/** Map a rea Tier value (or unknown) to a stable bucket key for the
+ *  by_tier table. Unknown values bucket to `'unknown'` so the rollup
+ *  surfaces them rather than silently dropping.
+ */
+function tierBucket(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return 'unknown';
+    return value;
+}
+function statusBucket(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return 'unknown';
+    return value;
+}
+/**
+ * Parse an ISO-8601 timestamp into a Date. Returns `null` on failure.
+ */
+function parseTimestamp(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * Sample-verify per-record hash integrity across the IN-WINDOW
+ * records only. Returns `ok`, `tampered`, or `unsampled` (no
+ * records in window).
+ *
+ * Sampling: take indices at offsets 0, n/k, 2n/k, …, (k-1)n/k where
+ * n is the in-window count and k is `CHAIN_SAMPLE_SIZE`. Always
+ * sample the first and last record.
+ *
+ * Codex round-2 P1: we do NOT verify `prev_hash` linkage between
+ * adjacent records in the filtered list. `appendAuditRecord` accepts
+ * caller-supplied timestamps, so a valid chain can look like
+ * `in-window → out-of-window → in-window`; in that case the second
+ * in-window record's `prev_hash` points to the filtered-out entry,
+ * not the previous survivor in our filtered view, and a linkage
+ * check would false-positive `tampered` on a healthy log. The
+ * authoritative chain walk lives in `rea audit verify`; summary
+ * stays advisory.
+ */
+function sampleChainIntegrity(records) {
+    if (records.length === 0)
+        return { result: 'unsampled', samplesVerified: 0 };
+    const sampleIndices = new Set();
+    const k = Math.min(CHAIN_SAMPLE_SIZE, records.length);
+    for (let i = 0; i < k; i += 1) {
+        const idx = Math.floor((i * records.length) / k);
+        sampleIndices.add(idx);
+    }
+    sampleIndices.add(records.length - 1);
+    let samplesVerified = 0;
+    for (const i of sampleIndices) {
+        const r = records[i];
+        const { hash, ...rest } = r;
+        const recomputed = computeHash(rest);
+        if (recomputed !== hash) {
+            return { result: 'tampered', samplesVerified };
+        }
+        samplesVerified += 1;
+    }
+    return { result: 'ok', samplesVerified };
+}
+/**
+ * Compute the summary. Pure (read-only). Throws
+ * `AuditSummarySinceError` on bad `--since`; everything else is
+ * surfaced via the result.
+ */
+export async function computeAuditSummary(options = {}) {
+    const baseDir = options.baseDir ?? process.cwd();
+    const now = options.now ?? new Date();
+    let windowSeconds = null;
+    let windowStart = null;
+    let windowEnd = null;
+    if (options.since !== undefined && options.since.length > 0) {
+        windowSeconds = parseDurationSeconds(options.since);
+        windowEnd = now;
+        windowStart = new Date(now.getTime() - windowSeconds * 1000);
+    }
+    const files = await resolveSummaryFileWalk(baseDir, windowStart);
+    const byToolName = {};
+    const byTier = {};
+    const byStatus = {};
+    const bySession = {};
+    let totalEvents = 0;
+    let earliest = null;
+    let latest = null;
+    // We only feed in-window records to the chain-sample check.
+    const inWindowRecords = [];
+    for (const filePath of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                continue;
+            throw e;
+        }
+        for (const line of raw.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Malformed line — `rea audit verify` is the tool for that.
+                // Summary just skips and moves on.
+                continue;
+            }
+            const ts = parseTimestamp(parsed.timestamp);
+            if (windowStart !== null && (ts === null || ts < windowStart))
+                continue;
+            // upper bound is `now`; future-dated records (skew, replay) are
+            // still counted — they're real records that landed in the file.
+            totalEvents += 1;
+            const toolName = typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+                ? parsed.tool_name
+                : '(unknown)';
+            byToolName[toolName] = (byToolName[toolName] ?? 0) + 1;
+            const tier = tierBucket(parsed.tier);
+            byTier[tier] = (byTier[tier] ?? 0) + 1;
+            const status = statusBucket(parsed.status);
+            byStatus[status] = (byStatus[status] ?? 0) + 1;
+            const session = typeof parsed.session_id === 'string' && parsed.session_id.length > 0
+                ? parsed.session_id
+                : '(unknown)';
+            bySession[session] = (bySession[session] ?? 0) + 1;
+            const tsRaw = typeof parsed.timestamp === 'string' ? parsed.timestamp : null;
+            if (tsRaw !== null) {
+                if (earliest === null || tsRaw < earliest)
+                    earliest = tsRaw;
+                if (latest === null || tsRaw > latest)
+                    latest = tsRaw;
+            }
+            inWindowRecords.push(parsed);
+        }
+    }
+    const { result: chainIntegrity, samplesVerified } = sampleChainIntegrity(inWindowRecords);
+    // Suppress unused-variable warning for genesis hash by referencing
+    // it: the chain-sample check uses it implicitly via the relaxed
+    // first-record rule. Kept as an import-time anchor for the linkage
+    // contract documented in `sampleChainIntegrity`.
+    void GENESIS_HASH;
+    return {
+        schema_version: AUDIT_SUMMARY_SCHEMA_VERSION,
+        window_seconds: windowSeconds,
+        window_start: windowStart !== null ? windowStart.toISOString() : null,
+        window_end: windowEnd !== null ? windowEnd.toISOString() : null,
+        files_scanned: files,
+        total_events: totalEvents,
+        by_tool_name: byToolName,
+        by_tier: byTier,
+        by_status: byStatus,
+        by_session: bySession,
+        session_count: Object.keys(bySession).length,
+        earliest_timestamp: earliest,
+        latest_timestamp: latest,
+        chain_integrity: chainIntegrity,
+        chain_samples_verified: samplesVerified,
+    };
+}
+function sortBucket(bucket) {
+    return Object.entries(bucket).sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1];
+        return a[0].localeCompare(b[0]);
+    });
+}
+function renderBucket(d, total) {
+    const lines = [];
+    lines.push(`${d.title}:`);
+    const visible = d.limit !== undefined ? d.entries.slice(0, d.limit) : d.entries;
+    const overflow = d.limit !== undefined ? d.entries.slice(d.limit) : [];
+    const maxNameLen = visible.reduce((m, [n]) => Math.max(m, n.length), 0);
+    for (const [name, count] of visible) {
+        const pad = ' '.repeat(maxNameLen - name.length + 2);
+        const pct = total > 0 ? ` (${((count * 100) / total).toFixed(1)}%)` : '';
+        lines.push(`  ${name}${pad}${String(count).padStart(6)}${pct}`);
+    }
+    if (overflow.length > 0) {
+        const overflowSum = overflow.reduce((s, [, n]) => s + n, 0);
+        const pad = ' '.repeat(Math.max(0, maxNameLen - 7) + 2);
+        const pct = total > 0 ? ` (${((overflowSum * 100) / total).toFixed(1)}%)` : '';
+        lines.push(`  (other)${pad}${String(overflowSum).padStart(6)}${pct}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Render the result as a human-readable terminal block. Designed for
+ * the default `rea audit summary` invocation; `--json` callers bypass
+ * this entirely.
+ */
+export function renderAuditSummary(result) {
+    const lines = [];
+    const windowLabel = result.window_seconds !== null ? formatDurationShort(result.window_seconds) : 'all time';
+    lines.push(`rea audit summary (${windowLabel})`);
+    lines.push('─'.repeat(40));
+    lines.push(`total events:       ${String(result.total_events).padStart(6)}`);
+    lines.push(`sessions:           ${String(result.session_count).padStart(6)}`);
+    if (result.session_count > 0) {
+        const avg = result.total_events / result.session_count;
+        lines.push(`events/session avg: ${avg.toFixed(1).padStart(6)}`);
+    }
+    lines.push('');
+    if (result.total_events === 0) {
+        lines.push(result.window_seconds !== null
+            ? 'No events in the requested window.'
+            : 'No events in the audit log.');
+        lines.push('');
+        if (result.files_scanned.length === 0) {
+            lines.push('(no audit files found — has `rea serve` ever run?)');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    const total = result.total_events;
+    lines.push(renderBucket({ title: 'by tool_name', entries: sortBucket(result.by_tool_name), limit: 12 }, total));
+    lines.push('');
+    lines.push(renderBucket({ title: 'by tier', entries: sortBucket(result.by_tier) }, total));
+    lines.push('');
+    lines.push(renderBucket({ title: 'by status', entries: sortBucket(result.by_status) }, total));
+    lines.push('');
+    // Sessions can balloon — limit to 5 by default.
+    lines.push(renderBucket({ title: 'top sessions', entries: sortBucket(result.by_session), limit: 5 }, total));
+    lines.push('');
+    if (result.earliest_timestamp !== null && result.latest_timestamp !== null) {
+        lines.push(`window: ${result.earliest_timestamp} → ${result.latest_timestamp}`);
+    }
+    const chainLabel = result.chain_integrity === 'ok'
+        ? `ok (${String(result.chain_samples_verified)} sample${result.chain_samples_verified === 1 ? '' : 's'} verified)`
+        : result.chain_integrity === 'tampered'
+            ? 'TAMPERED — run `rea audit verify` for the exact break'
+            : 'unsampled (no records in window)';
+    lines.push(`chain integrity: ${chainLabel}`);
+    lines.push(`files scanned:   ${String(result.files_scanned.length)}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Compact human duration label for the header. `86400` → `last 24h`,
+ * `604800` → `last 7d`, etc. We pick the coarsest single unit that
+ * yields an integer; otherwise fall back to seconds.
+ */
+function formatDurationShort(seconds) {
+    const units = [
+        ['w', 60 * 60 * 24 * 7],
+        ['d', 60 * 60 * 24],
+        ['h', 60 * 60],
+        ['m', 60],
+        ['s', 1],
+    ];
+    for (const [unit, factor] of units) {
+        if (seconds % factor === 0) {
+            return `last ${String(seconds / factor)}${unit}`;
+        }
+    }
+    return `last ${String(seconds)}s`;
+}
+/** Commander entrypoint. */
+export async function runAuditSummary(options) {
+    let result;
+    try {
+        result = await computeAuditSummary({
+            ...(options.since !== undefined ? { since: options.since } : {}),
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof AuditSummarySinceError) {
+            err(`rea audit summary: ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(renderAuditSummary(result));
+    if (result.chain_integrity === 'tampered') {
+        // Non-zero exit gives CI users a single signal for "something is
+        // off"; the JSON path stays exit 0 so machine consumers can react
+        // to the integrity field directly.
+        log('summary complete with tampered chain — see message above.');
+        process.exit(1);
+    }
+}
+/**
+ * Register `rea audit summary` under the `audit` command group.
+ */
+export function registerAuditSummaryCommand(auditCommand) {
+    auditCommand
+        .command('summary')
+        .description('High-level audit-log summary — counts by tool_name, tier, session, status; window timestamps; sample-verified chain integrity. Read-only.')
+        .option('--since <duration>', 'Filter to records within the last <duration>. Compact form: <N><unit> where unit is s|m|h|d|w (e.g. 24h, 7d). Distinct from `rea audit verify --since <file>` which anchors on a rotated file.')
+        .option('--json', 'emit a JSON document instead of the human-readable table')
+        .action(async (opts) => {
+        await runAuditSummary({
+            ...(opts.since !== undefined ? { since: opts.since } : {}),
+            ...(opts.json === true ? { json: true } : {}),
+        });
+    });
+}

package/dist/cli/index.js

@@ -13,6 +13,8 @@ import { runServe } from './serve.js';
 import { runStatus } from './status.js';
 import { runTofuAccept, runTofuList } from './tofu.js';
 import { runUpgrade } from './upgrade.js';
+import { runUpgradeCheck } from './upgrade-check.js';
+import { registerAuditSummaryCommand } from './audit-summary.js';
 import { registerVerifyClaimCommand } from './verify-claim.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -51,7 +53,34 @@ async function main() {
         .option('--dry-run', 'show what would change; write nothing')
         .option('-y, --yes', 'non-interactive — keep drifted files, skip removed-upstream')
         .option('--force', 'non-interactive — overwrite drift, delete removed-upstream')
+        // 0.41.0 — `--check` is a non-interactive, structured preview that
+        // emits unified diffs per modified file and exits 0 regardless of
+        // what would change. Distinct from `--dry-run`, which rehearses the
+        // FULL interactive flow with writes suppressed. Use `--check` in CI
+        // to surface the changes a `rea upgrade` PR would produce; use
+        // `--dry-run` locally to walk through the same prompts you'd see
+        // during a real upgrade.
+        .option('--check', '0.41.0 — preview-only mode: classify files, emit unified diffs, exit 0')
+        .option('--json', '(with --check) emit a single JSON document instead of the text summary')
+        .option('--no-diff', '(with --check) omit unified-diff bodies (counts + paths only)')
         .action(async (opts) => {
+        if (opts.check === true) {
+            await runUpgradeCheck({
+                json: opts.json === true,
+                noDiff: opts.diff === false,
+            });
+            return;
+        }
+        // Codex round-2 P1: `--json` / `--no-diff` are preview-only.
+        // Before this PR they were unknown flags and commander rejected
+        // them; now they exist on the command. Refuse them without
+        // `--check` rather than silently performing a real upgrade —
+        // a CI typo (`rea upgrade --json` without `--check`) must not
+        // rewrite `.claude/` / `.husky/` / managed fragments.
+        if (opts.json === true || opts.diff === false) {
+            err('`--json` / `--no-diff` are preview-only flags; pass `--check` to use them.');
+            process.exit(2);
+        }
         await runUpgrade({
             dryRun: opts.dryRun,
             yes: opts.yes,
@@ -111,6 +140,10 @@ async function main() {
     // records. Read-only; honors $CLAUDE_SESSION_ID for current-session
     // filtering. v1 omits --since / --session (deferred to 0.29.1).
     registerAuditSpecialistsSubcommand(audit);
+    // 0.41.0 — `rea audit summary [--since=DUR] [--json]` high-level
+    // overview reader. Counts events by tool_name, tier, session,
+    // status; samples chain integrity. Tier-Read; never mutates.
+    registerAuditSummaryCommand(audit);
     // Register `rea hook push-gate` — the stateless pre-push Codex gate
     // called by `.husky/pre-push` and `.git/hooks/pre-push`.
     registerHookCommand(program);

package/dist/cli/install/gitignore.d.ts

@@ -102,6 +102,28 @@ export interface EnsureGitignoreResult {
     addedEntries: string[];
     /** Non-fatal operator-facing messages (e.g. symlink refused, duplicate blocks). */
     warnings: string[];
+    /**
+     * 0.41.0 — when computed under `dryRun: true`, the full would-be
+     * on-disk content. Omitted in real-write mode (the file IS the
+     * authoritative copy). Callers like `rea upgrade --check` use this
+     * to render a unified diff against the current on-disk content.
+     */
+    previewContent?: string;
+    /**
+     * 0.41.0 — current on-disk content at planning time. `null` when
+     * the file does not exist. Omitted in real-write mode.
+     */
+    previousContent?: string | null;
+}
+export interface EnsureGitignoreOptions {
+    /**
+     * When `true`, compute the action + would-be content without
+     * writing. Returns `previewContent` and `previousContent`. Default
+     * `false` (write-on).
+     */
+    dryRun?: boolean;
+    /** Override the canonical entry list. Tests use this. */
+    entries?: readonly string[];
 }
 /**
  * Main entry point. Idempotent: calling twice in a row produces `unchanged`
@@ -111,4 +133,4 @@ export interface EnsureGitignoreResult {
  * init` and `rea upgrade` pass the default. Tests override to verify
  * reconciliation.
  */
-export declare function ensureReaGitignore(targetDir: string, entries?: readonly string[]): Promise<EnsureGitignoreResult>;
+export declare function ensureReaGitignore(targetDir: string, optionsOrEntries?: EnsureGitignoreOptions | readonly string[]): Promise<EnsureGitignoreResult>;

package/dist/cli/install/gitignore.js

@@ -271,7 +271,15 @@ async function writeAtomic(absPath, content) {
  * init` and `rea upgrade` pass the default. Tests override to verify
  * reconciliation.
  */
-export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTRIES) {
+export async function ensureReaGitignore(targetDir, optionsOrEntries = {}) {
+    // Back-compat: pre-0.41.0 callers passed `entries` as the second
+    // positional argument. Detect the legacy shape and forward to the
+    // options form so we don't break existing call sites.
+    const options = Array.isArray(optionsOrEntries)
+        ? { entries: optionsOrEntries }
+        : optionsOrEntries;
+    const entries = options.entries ?? REA_GITIGNORE_ENTRIES;
+    const dryRun = options.dryRun === true;
     const absPath = path.resolve(targetDir, GITIGNORE);
     const warnings = [];
     let existing;
@@ -280,18 +288,26 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     }
     catch (err) {
         warnings.push(err.message);
-        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+        return {
+            path: absPath,
+            action: 'unchanged',
+            addedEntries: [],
+            warnings,
+            ...(dryRun ? { previousContent: null, previewContent: '' } : {}),
+        };
     }
     // Detect EOL so a CRLF repo stays CRLF and doesn't get torn. Codex F3.
     const eol = existing !== null && existing.includes('\r\n') ? '\r\n' : '\n';
     if (existing === null) {
         const content = buildManagedBlock(entries, '\n') + '\n';
-        await writeAtomic(absPath, content);
+        if (!dryRun)
+            await writeAtomic(absPath, content);
         return {
             path: absPath,
             action: 'created',
             addedEntries: [...entries],
             warnings,
+            ...(dryRun ? { previousContent: null, previewContent: content } : {}),
         };
     }
     const lines = existing.split(/\r?\n/);
@@ -300,7 +316,13 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     if (block === 'duplicate') {
         warnings.push(`${absPath} contains multiple '# === rea managed' blocks — refusing to modify. ` +
             `Consolidate the managed blocks manually and rerun.`);
-        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+        return {
+            path: absPath,
+            action: 'unchanged',
+            addedEntries: [],
+            warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: existing } : {}),
+        };
     }
     if (block === null) {
         // No managed block. Append one after a blank-line separator (unless the
@@ -315,12 +337,14 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
         const separator = bodyLines.length === 0 ? [] : [''];
         const newLines = [...bodyLines, ...separator, buildManagedBlock(entries, eol)];
         const content = newLines.join(eol) + eol;
-        await writeAtomic(absPath, content);
+        if (!dryRun)
+            await writeAtomic(absPath, content);
         return {
             path: absPath,
             action: 'updated',
             addedEntries: [...entries],
             warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: content } : {}),
         };
     }
     // Managed block exists — reconcile body lines.
@@ -332,6 +356,7 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
             action: 'unchanged',
             addedEntries: [],
             warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: existing } : {}),
         };
     }
     const newLines = [
@@ -342,11 +367,13 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     let content = newLines.join(eol);
     if (hadTrailingNewline && !content.endsWith(eol))
         content += eol;
-    await writeAtomic(absPath, content);
+    if (!dryRun)
+        await writeAtomic(absPath, content);
     return {
         path: absPath,
         action: 'updated',
         addedEntries: added,
         warnings,
+        ...(dryRun ? { previousContent: existing, previewContent: content } : {}),
     };
 }