@bookedsolid/rea 0.48.0 → 0.49.0

package/dist/cli/upgrade.js

@@ -48,6 +48,7 @@ import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, pruneH
 import { validateSettings } from '../config/settings-schema.js';
 import { ensureReaGitignore } from './install/gitignore.js';
 import { installPrepareCommitMsgHook } from './install/prepare-commit-msg.js';
+import { checkUpgradeBlockingPin, selfPinRea } from './install/self-pin.js';
 import { manifestExists, readManifest, writeManifestAtomic } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { err, getPkgVersion, log, warn } from './utils.js';
@@ -499,6 +500,65 @@ export async function runUpgrade(options = {}) {
                 `unchanged. zod errors: ${validation.errors.join('; ')}`);
         }
     }
+    // R9-P1 (codex round 9 / 0.49.0): blocking-pin pre-flight.
+    //
+    // When package.json pins @bookedsolid/rea to a version that does
+    // NOT admit the installed CLI version (workspace:*, file:.., git
+    // URLs, dist-tags, exact older pins, cross-major caret), writing
+    // 0.49 hooks + policy artifacts on top creates a hook/CLI skew:
+    // the bash gates resolve the older CLI from node_modules and that
+    // CLI's strict policy loader rejects the new `bootstrap_allowlist:`
+    // top-level key, breaking every Bash payload until the operator
+    // reconciles the pin.
+    //
+    // The check is READ-ONLY (single package.json read) and runs
+    // BEFORE every artifact-writing step:
+    //   - migrateReviewPolicyFor0110 (rewrites .rea/policy.yaml)
+    //   - the canonical file-write loop (hooks, agents, commands)
+    //   - the dedicated selfPinRea call further below
+    //   - .gitignore + prepare-commit-msg + manifest writes
+    //
+    // In dry-run we DESCRIBE the abort condition without exiting
+    // non-zero — operators using `rea upgrade --check` get to see the
+    // would-block diagnostic, then the dry-run completes normally.
+    // In live mode we abort with exit 1 and the operator-facing
+    // reconciliation steps.
+    {
+        const pinCheck = await checkUpgradeBlockingPin({
+            cwd: resolvedRoot,
+            cliVersion: getPkgVersion(),
+            mode: 'upgrade',
+        });
+        if (pinCheck.kind === 'block' || pinCheck.kind === 'block-symlink') {
+            // R10-P2 (codex round 10): block-symlink is the new variant —
+            // package.json is a symlink and writing through it would
+            // mutate a file outside the requested project tree. Handle
+            // it identically to the R9-P1 block case (throw with the
+            // operator-actionable reason; dry-run describes without
+            // throwing).
+            const dryRunHeadline = pinCheck.kind === 'block'
+                ? `dry-run: rea upgrade WOULD refuse — pin ${JSON.stringify(pinCheck.existingRange)} ` +
+                    `in ${path.relative(resolvedRoot, pinCheck.packageJsonPath)} does not admit ` +
+                    `CLI ${pinCheck.newCliVersion}.`
+                : `dry-run: rea upgrade WOULD refuse — ${path.relative(resolvedRoot, pinCheck.packageJsonPath)} ` +
+                    `is a symlink and rea must not mutate files outside the requested project tree.`;
+            if (dryRun) {
+                console.log('');
+                warn(dryRunHeadline);
+                for (const line of pinCheck.reason.split('\n')) {
+                    console.log(`    ${line}`);
+                }
+                console.log('');
+            }
+            else {
+                // R9-P1: throw (don't process.exit) so the CLI wrapper can
+                // surface the message via its standard error path AND tests
+                // can assert on the thrown reason. Matches the settings
+                // pre-flight (line ~588) which also throws.
+                throw new Error(pinCheck.reason);
+            }
+        }
+    }
     // 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
@@ -681,6 +741,80 @@ export async function runUpgrade(options = {}) {
         for (const w of pcmResult.warnings)
             warn(w);
     }
+    // 0.49.0 — self-heal legacy installs that pre-date `rea init`'s
+    // self-pin step. Bricks-on-fresh-clone is a 0.48.x-and-earlier
+    // problem; `rea upgrade` rolls forward to a healthy state by
+    // re-running the same self-pin module.
+    //
+    // P1-1 (codex round 2): `mode: 'upgrade'` opts the upgrade path
+    // into auto-bumping a managed-caret pin when the existing range
+    // does not admit the new CLI minor. `^0.49.0` does NOT admit
+    // `0.50.0` (npm pre-1.0 caret = tilde semantics) — without auto-
+    // bump, `rea upgrade 0.50.0` would copy newer hooks against the
+    // older CLI pin and recreate the hook/CLI skew this feature
+    // exists to prevent. Auto-bump fires ONLY when the existing
+    // range is a strict managed-caret shape (something we wrote);
+    // workspace:*, file:.., git URLs, tags, exact pins, tildes, and
+    // cross-major bumps all hands-off and warn+skip. See
+    // src/cli/install/self-pin.ts::shouldBumpManagedCaret for the
+    // gate.
+    //
+    // R3-P2 (codex round 3): dry-run must surface the SAME action the
+    // live run would take — operators ran `rea upgrade --dry-run`,
+    // saw zero pin-related output, and were surprised when the live
+    // run mutated `package.json`. We now invoke `selfPinRea` in BOTH
+    // dry-run and live mode; the helper's `dryRun: true` opt computes
+    // the action discriminant without writing. Dry-run console output
+    // uses "would" verbs so the planned vs done distinction is
+    // unambiguous.
+    {
+        const selfPinResult = await selfPinRea({
+            cwd: resolvedRoot,
+            cliVersion: getPkgVersion(),
+            mode: 'upgrade',
+            dryRun,
+        });
+        const rel = selfPinResult.packageJsonPath !== null
+            ? path.relative(resolvedRoot, selfPinResult.packageJsonPath)
+            : null;
+        if (selfPinResult.action === 'wrote' && rel !== null) {
+            console.log(dryRun
+                ? `  ~ ${rel} (would self-pin: write devDependencies["@bookedsolid/rea"] = ${selfPinResult.pinnedRange})`
+                : `  ~ ${rel} (self-pin: @bookedsolid/rea@${selfPinResult.pinnedRange})`);
+        }
+        else if (selfPinResult.action === 'bumped' && rel !== null) {
+            // P1-1: surface the bump explicitly so the upgrade log shows
+            // exactly what changed about the pin (vs the silent same-bytes
+            // case which uses the dot marker).
+            console.log(dryRun
+                ? `  ~ ${rel} (would self-pin: bump @bookedsolid/rea from ${selfPinResult.existingRange ?? '?'} to ${selfPinResult.pinnedRange})`
+                : `  ✓ ${rel} (self-pin: bumped @bookedsolid/rea from ${selfPinResult.existingRange ?? '?'} to ${selfPinResult.pinnedRange})`);
+        }
+        else if (selfPinResult.action === 'skipped-same' && rel !== null) {
+            console.log(`  · ${rel} (self-pin: already declared)`);
+        }
+        else if (selfPinResult.action === 'skipped-different') {
+            // Same warn-and-skip path for both dry-run and live — the
+            // operator-owned-pin posture doesn't change between modes.
+            // The message itself describes the existing pin and the
+            // hands-off rationale.
+            warn(selfPinResult.message);
+        }
+        else if (selfPinResult.action === 'skipped-no-package-json') {
+            warn('self-pin skipped — no package.json found upward from target; bash gates may refuse without it');
+        }
+        else if (selfPinResult.action === 'skipped-malformed-package-json') {
+            warn(selfPinResult.message);
+        }
+        else if (selfPinResult.action === 'skipped-symlink-package-json') {
+            // R10-P2 (codex round 10): dry-run path only. Live mode throws
+            // at the symlink check; reaching this branch means the
+            // pre-flight already described the block-symlink condition to
+            // the operator earlier in this `rea upgrade --dry-run`
+            // invocation. No additional output needed beyond the
+            // already-printed pre-flight diagnostic.
+        }
+    }
     // BUG-010 — ensure `.gitignore` carries every runtime artifact entry. This
     // backfills older installs that predate the scaffolding in `rea init`. A
     // consumer who upgraded from 0.3.x/0.4.0 was previously seeing

package/dist/policy/loader.d.ts

@@ -308,6 +308,13 @@ declare const PolicySchema: z.ZodObject<{
     }, {
         enabled?: boolean | undefined;
     }>>;
+    bootstrap_allowlist: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -389,6 +396,9 @@ declare const PolicySchema: z.ZodObject<{
     shim_cache?: {
         enabled: boolean;
     } | undefined;
+    bootstrap_allowlist?: {
+        enabled: boolean;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -470,6 +480,9 @@ declare const PolicySchema: z.ZodObject<{
     shim_cache?: {
         enabled?: boolean | undefined;
     } | undefined;
+    bootstrap_allowlist?: {
+        enabled?: boolean | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -354,6 +354,32 @@ const ShimCachePolicySchema = z
     enabled: z.boolean().default(true),
 })
     .strict();
+/**
+ * 0.49.0 — bootstrap allowlist policy. Drives the narrow CLI-missing
+ * pass-through in `hooks/_lib/bootstrap-allowlist.sh` that the
+ * `blocked-paths-bash-gate.sh` and `protected-paths-bash-gate.sh`
+ * shims consult when the rea CLI is unreachable. See the helper
+ * header for the full security contract.
+ *
+ * The block is optional — vanilla installs with no
+ * `bootstrap_allowlist:` block get the default behavior (enabled).
+ * To disable: `bootstrap_allowlist: { enabled: false }`.
+ *
+ * Strict mode rejects unknown keys so a typo (`enabld`, `enable`)
+ * fails loudly at policy load.
+ *
+ * The bash-tier helper does a narrow YAML grep for the field via
+ * inline node (engines.node >=22 guarantees availability) BEFORE the
+ * canonical 4-tier policy reader is available (the allowlist runs
+ * precisely BECAUSE the CLI is missing). This zod schema validates
+ * the field at CLI load time so wrong types / typos are caught at the
+ * load boundary.
+ */
+const BootstrapAllowlistPolicySchema = z
+    .object({
+    enabled: z.boolean().default(true),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -423,6 +449,16 @@ const PolicySchema = z
     // in env overrides this to `false` for the current invocation
     // regardless of policy.
     shim_cache: ShimCachePolicySchema.optional(),
+    // 0.49.0 — bootstrap allowlist. Narrow CLI-missing pass-through
+    // for the `pnpm install` / `npm ci` / `yarn` / `corepack enable`
+    // class of recovery commands. ALWAYS-ON by default; opt-out via
+    // `bootstrap_allowlist: { enabled: false }`. The bash-tier
+    // gate consults the field via inline node BEFORE the canonical
+    // 4-tier policy reader is reachable, since the whole reason it
+    // runs is that the CLI is unbuilt. See
+    // `hooks/_lib/bootstrap-allowlist.sh` and
+    // `THREAT_MODEL.md §5.X`.
+    bootstrap_allowlist: BootstrapAllowlistPolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/profiles.d.ts

@@ -121,6 +121,13 @@ export declare const ProfileSchema: z.ZodObject<{
         threshold?: number | undefined;
         exempt_subagents?: string[] | undefined;
     }>>;
+    bootstrap_allowlist: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -160,6 +167,9 @@ export declare const ProfileSchema: z.ZodObject<{
         threshold?: number | undefined;
         exempt_subagents?: string[] | undefined;
     } | undefined;
+    bootstrap_allowlist?: {
+        enabled?: boolean | undefined;
+    } | undefined;
 }, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -199,6 +209,9 @@ export declare const ProfileSchema: z.ZodObject<{
         threshold?: number | undefined;
         exempt_subagents?: string[] | undefined;
     } | undefined;
+    bootstrap_allowlist?: {
+        enabled?: boolean | undefined;
+    } | undefined;
 }>;
 export type Profile = z.infer<typeof ProfileSchema>;
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/profiles.js

@@ -116,6 +116,18 @@ export const ProfileSchema = z
     })
         .strict()
         .optional(),
+    // 0.49.0+ bootstrap allowlist (P3-1) — narrow CLI-missing pass-through
+    // in `hooks/_lib/bootstrap-allowlist.sh`. The `bst-internal` profile
+    // pins `enabled: true` for parity with `.rea/policy.yaml`; every other
+    // shipped profile inherits the schema default (also `true`). The
+    // profile-layer schema mirrors the policy-loader's
+    // `BootstrapAllowlistPolicySchema`; strict mode catches typos at init.
+    bootstrap_allowlist: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/types.d.ts

@@ -557,6 +557,44 @@ export interface Policy {
      * methodology note.
      */
     shim_cache?: ShimCachePolicy;
+    /**
+     * Bootstrap allowlist (0.49.0+).
+     *
+     * Drives the narrow CLI-missing pass-through in
+     * `hooks/_lib/bootstrap-allowlist.sh`. When the bash-tier
+     * `blocked-paths-bash-gate.sh` / `protected-paths-bash-gate.sh`
+     * shims would refuse a Bash payload because the rea CLI is
+     * unreachable, the allowlist consults this block + the
+     * consumer's `package.json` to decide whether the payload is a
+     * legitimate recovery command (pnpm install / npm ci / yarn /
+     * corepack enable / etc.) that should pass through.
+     *
+     * Always-on by default. Set `enabled: false` to disable.
+     * Opt-out is the only knob — the allowlist itself does not
+     * accept env-var participation in the decision (security
+     * architect locked).
+     */
+    bootstrap_allowlist?: BootstrapAllowlistPolicy;
+}
+/**
+ * Bootstrap allowlist policy (0.49.0+).
+ *
+ * See `hooks/_lib/bootstrap-allowlist.sh` for the full contract and
+ * `THREAT_MODEL.md §5.X` for the threat-model analysis. The single
+ * knob is `enabled` — there is no list of allowed shapes in policy;
+ * the shape set is hardcoded in the helper because the threat model
+ * depends on it being fixed (a consumer-mutable shape list would let
+ * an attacker who can edit `policy.yaml` widen the pass-through).
+ *
+ * `policy.yaml` is itself a `blocked_paths` entry in the
+ * `bst-internal` profile (so a consumer who is dogfooding rea's
+ * own profile cannot turn the allowlist off via a Bash payload
+ * without first earning a separate Write-tier audit event), but
+ * the field is intentionally simple so external profiles can drop
+ * it back to consumer-editable.
+ */
+export interface BootstrapAllowlistPolicy {
+    enabled?: boolean;
 }
 /**
  * Per-session shim cache policy (0.48.0+).