@bookedsolid/rea 0.41.0 → 0.43.0

package/dist/cli/upgrade-check.js

@@ -65,6 +65,7 @@ import { manifestExists, readManifest } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { diffUnified, DIFF_TOO_LARGE_NOTICE } from './install/unified-diff.js';
 import { loadPolicy } from '../policy/loader.js';
+import { validateSettings } from '../config/settings-schema.js';
 import { err, getPkgVersion, log } from './utils.js';
 /** Hard cap on the diff input size. Mirrors `DIFF_SIZE_CAP_BYTES` in
  *  upgrade.ts so the two preview surfaces agree on the "too big to
@@ -288,6 +289,11 @@ async function classifyClaudeMd(resolvedRoot, includeDiffs) {
  * upgrade flow, we prune known-stale hook tokens BEFORE merging the
  * default-desired hook set — the order matters so the merge sees a
  * clean baseline.
+ *
+ * 0.42.0 — also returns the merged object so the caller can run the
+ * same `validateSettings` check the real `runUpgrade` runs. We hand
+ * back the merged shape directly (not the file rendering) so the
+ * caller can decide whether to thread it into the schema check.
  */
 async function classifySettings(resolvedRoot, includeDiffs) {
     const desired = defaultDesiredHooks();
@@ -344,7 +350,7 @@ async function classifySettings(resolvedRoot, includeDiffs) {
             Object.assign(file, safeDiff(oldText, newText, file.path));
         }
     }
-    return file;
+    return { file, merged: mergeResult.merged };
 }
 /**
  * Build a `removed_upstream` entry from a manifest record that has no
@@ -480,14 +486,37 @@ export async function computeUpgradeCheck(options = {}) {
         }
     }
     // Synthetic entries.
-    const settingsFile = await classifySettings(resolvedRoot, includeDiffs);
-    files.push(settingsFile);
+    const settingsClassification = await classifySettings(resolvedRoot, includeDiffs);
+    files.push(settingsClassification.file);
     const claudeMd = await classifyClaudeMd(resolvedRoot, includeDiffs);
     if (claudeMd !== null)
         files.push(claudeMd);
     const gitignoreFile = await classifyGitignore(resolvedRoot, includeDiffs);
     if (gitignoreFile !== null)
         files.push(gitignoreFile);
+    // 0.42.0 charter item 2 — schema-validate the merged settings the
+    // real `runUpgrade` would write. `runUpgrade` calls `validateSettings`
+    // (non-strict, matching the upgrade flow's posture) and throws when
+    // the merged result fails — refusing the write. Pre-0.42.0 the
+    // preview never ran this check, so the planner could promise a write
+    // that the real upgrade would refuse. Reproduce the exact validation
+    // shape here so the JSON `settings_validation` field is byte-for-byte
+    // what `runUpgrade` would see.
+    const validation = validateSettings(settingsClassification.merged, { strict: false });
+    const settingsValidation = {
+        parsed: validation.parsed,
+        errors: validation.errors,
+    };
+    // If validation failed, annotate the settings file row so the
+    // human-readable rendering surfaces the refusal alongside the count
+    // table (operators reading the table without scrolling to the
+    // footer still see the warning). Note appends rather than overwrites
+    // so the existing merge / prune annotations remain visible.
+    if (!validation.parsed) {
+        const refusalNote = `WOULD REFUSE: schema validation failed — ${validation.errors.join('; ')}`;
+        const f = settingsClassification.file;
+        f.note = f.note !== undefined ? `${f.note}; ${refusalNote}` : refusalNote;
+    }
     // Stable sort: action priority (modified → created → removed_upstream
     // → unchanged) then path. Operators reviewing the table want to see
     // the changed entries first.
@@ -513,6 +542,13 @@ export async function computeUpgradeCheck(options = {}) {
         bootstrap: isBootstrap,
         counts,
         files,
+        settings_validation: settingsValidation,
+        // Codex round 3 P2 (2026-05-16): mirror runUpgrade's pre-flight
+        // gate. `would_apply` is true when the real upgrade would actually
+        // start mutating disk — currently the only gate is settings-schema
+        // validation, but more pre-flight checks may land in future
+        // releases (in which case they get ANDed in here).
+        would_apply: settingsValidation.parsed,
     };
 }
 /**
@@ -528,8 +564,20 @@ export function renderUpgradeCheck(plan) {
         lines.push(`  bootstrap mode: no install-manifest found yet`);
     }
     lines.push('');
+    // Codex round 3 P2 (2026-05-16): when a pre-flight gate would
+    // refuse the upgrade, the counts/files below describe what WOULD
+    // happen if the gate passed — but `rea upgrade` will actually
+    // write nothing in the current state. Lead with that banner so
+    // operators don't read the summary table as a promise of action.
+    if (!plan.would_apply) {
+        lines.push('BLOCKED — `rea upgrade` would refuse to apply this plan in its current state. ' +
+            'The summary below describes the would-be plan IF the refusal were fixed first; ' +
+            'the real upgrade writes nothing until the refusal clears.');
+        lines.push('');
+    }
     const totalChanges = plan.counts.created + plan.counts.modified + plan.counts.removed_upstream;
-    lines.push(`Summary — ${String(totalChanges)} planned change(s):`);
+    const summaryLabel = plan.would_apply ? 'planned change(s)' : 'change(s) blocked by refusal';
+    lines.push(`Summary — ${String(totalChanges)} ${summaryLabel}:`);
     lines.push(`  created:          ${String(plan.counts.created)}`);
     lines.push(`  modified:         ${String(plan.counts.modified)}`);
     lines.push(`  removed-upstream: ${String(plan.counts.removed_upstream)}`);
@@ -538,6 +586,17 @@ export function renderUpgradeCheck(plan) {
     if (totalChanges === 0) {
         lines.push('No changes — your install is already in sync with this rea version.');
         lines.push('');
+        // 0.42.0 — even with zero planned changes, surface a validation
+        // failure here so an operator doesn't see "in sync" and miss the
+        // settings refusal.
+        if (plan.settings_validation !== null && !plan.settings_validation.parsed) {
+            lines.push('WARNING: `rea upgrade` would REFUSE to run — the merged ' +
+                '.claude/settings.json would fail schema validation:');
+            for (const e of plan.settings_validation.errors) {
+                lines.push(`  - ${e}`);
+            }
+            lines.push('');
+        }
         return lines.join('\n');
     }
     // Per-file detail — skip `unchanged` entries.
@@ -545,7 +604,12 @@ export function renderUpgradeCheck(plan) {
         if (file.action === 'unchanged')
             continue;
         const marker = file.action === 'created' ? '+' : file.action === 'removed_upstream' ? '-' : '~';
-        const label = file.action === 'removed_upstream' ? 'removed-upstream' : file.action;
+        const baseLabel = file.action === 'removed_upstream' ? 'removed-upstream' : file.action;
+        // Codex round 3 P2 (2026-05-16): when a refusal is active, every
+        // would-be-mutated file row gets a BLOCKED suffix so a quick scroll
+        // through the per-file detail cannot miss the fact that no write
+        // will happen until the refusal clears.
+        const label = plan.would_apply ? baseLabel : `${baseLabel} (BLOCKED — refusal active)`;
         const syntheticTag = file.synthetic !== undefined ? ` [${file.synthetic}]` : '';
         lines.push(`${marker} ${file.path}${syntheticTag} — ${label}`);
         if (file.note !== undefined)
@@ -572,8 +636,30 @@ export function renderUpgradeCheck(plan) {
         }
         lines.push('');
     }
-    lines.push('No changes were written. Run `rea upgrade` (without --check) to apply.');
-    lines.push('');
+    // 0.42.0 — surface settings-schema validation outcome alongside the
+    // footer. When the merged settings would fail validation, `rea
+    // upgrade` would refuse to start at all (codex round 2 P2 moved the
+    // validation to a pre-flight check BEFORE any file writes); we
+    // report that here so consumers can fix policy + settings before
+    // invoking the real upgrade.
+    if (plan.settings_validation !== null && !plan.settings_validation.parsed) {
+        lines.push('');
+        lines.push('WARNING: `rea upgrade` would REFUSE to run — the merged ' +
+            '.claude/settings.json would fail schema validation:');
+        for (const e of plan.settings_validation.errors) {
+            lines.push(`  - ${e}`);
+        }
+        lines.push('No files will be written by `rea upgrade` while this is true — the ' +
+            'pre-flight check runs before any canonical hook or agent file is ' +
+            'installed AND before the 0.11.0 .rea/policy.yaml migration, so your ' +
+            'existing install stays untouched. Fix the settings entries flagged ' +
+            'above and re-run `rea upgrade --check`.');
+        lines.push('');
+    }
+    else {
+        lines.push('No changes were written. Run `rea upgrade` (without --check) to apply.');
+        lines.push('');
+    }
     return lines.join('\n');
 }
 /**

package/dist/cli/upgrade.js

@@ -460,10 +460,52 @@ export async function runUpgrade(options = {}) {
     if (options.force === true && !dryRun) {
         warn('--force: overwriting locally-modified files and deleting removed-upstream entries without prompt.');
     }
+    // 0.42.0 codex round 2 P2 (2026-05-16): pre-flight the merged
+    // settings validation BEFORE any file writes happen. Pre-correction,
+    // `upgradeSettings` ran AFTER the canonical-file write loop and only
+    // then validated the merged result; throwing here meant canonical
+    // hook + agent files had already been written to disk, breaking
+    // `rea upgrade --check`'s implicit "preview = real" contract (the
+    // check footer correctly claimed validation would refuse, but did
+    // not warn that hook files would still be written first).
+    //
+    // Codex round 2 P2 (2026-05-16, follow-up): this MUST run before
+    // `migrateReviewPolicyFor0110` as well — the 0.11.0 policy migration
+    // rewrites `.rea/policy.yaml` and creates a `policy.yaml.bak-*`
+    // sibling. If the pre-flight runs after that migration, the
+    // "no files have been written" claim in the refusal message
+    // becomes false for pre-0.11 consumers with malformed settings.
+    // Ordering: pre-flight FIRST, then migration, then canonical
+    // enumeration + write loop.
+    //
+    // The pre-flight reuses the same helpers as `upgradeSettings` —
+    // `readSettings` / `pruneHookCommands` / `mergeSettings` /
+    // `validateSettings` are all pure functions over existing on-disk
+    // state and `defaultDesiredHooks()`, so running them twice is
+    // cheap (microseconds — single JSON parse + small object merge)
+    // and the second run inside `upgradeSettings` re-derives the same
+    // result before writing. Atomicity guarantee: if validation fails,
+    // `runUpgrade` aborts here with ZERO mutations to disk.
+    {
+        const desired = defaultDesiredHooks();
+        const { settings: existingSettings } = readSettings(resolvedRoot);
+        const pruned = pruneHookCommands(existingSettings, STALE_HOOK_COMMAND_TOKENS);
+        const mergeResult = mergeSettings(pruned.merged, desired);
+        const validation = validateSettings(mergeResult.merged);
+        if (!validation.parsed) {
+            throw new Error(`rea upgrade: refusing to start because the merged .claude/settings.json would ` +
+                `fail schema validation. This is a safety guardrail — no files have been written ` +
+                `(including no .rea/policy.yaml 0.11.0 migration). Your existing install is ` +
+                `unchanged. zod errors: ${validation.errors.join('; ')}`);
+        }
+    }
     // 0.11.0 migration — strip removed review.* fields and backfill the new
     // concerns_blocks default. Runs before canonical file reconciliation so a
     // policy that fails strict schema load (which happens on upgrade from
     // 0.10.x the moment we re-read `.rea/policy.yaml`) is cleaned up first.
+    // 0.42.0 round 2 P2 follow-up: ordered AFTER the pre-flight validation
+    // above so a settings-validation refusal does not leave a half-migrated
+    // .rea/policy.yaml + backup behind.
     await migrateReviewPolicyFor0110(resolvedRoot, { dryRun });
     const canonicalFiles = await enumerateCanonicalFiles();
     if (canonicalFiles.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",