@bookedsolid/rea 0.48.1 → 0.49.0

package/dist/cli/install/self-pin.d.ts

@@ -0,0 +1,440 @@
+/**
+ * `rea init` self-pin (0.49.0).
+ *
+ * # Problem
+ *
+ * `rea init` writes hook shims under `.claude/hooks/` that depend on the
+ * `@bookedsolid/rea` CLI being resolvable from `node_modules/`. The
+ * pre-0.49.0 init flow did NOT add the dep to the consumer's
+ * `package.json`, so any fresh clone + `pnpm install` produced a repo
+ * where the shims found no CLI and (correctly) refused every Bash
+ * call — including the very `pnpm add -D @bookedsolid/rea` that would
+ * recover the install. The bash-gate bootstrap allowlist (Fix B) is the
+ * paired safety net; this module is the structural fix.
+ *
+ * # Contract
+ *
+ * - Caret-pinned (`^<current-CLI-version>`) entry in `devDependencies`.
+ * - Lands in workspace ROOT `package.json`. Walks up from `targetDir`
+ *   until a `package.json` is found; refuses to mutate a parent that
+ *   the operator did not explicitly target (we only mutate when the
+ *   FIRST `package.json` we find IS the target).
+ * - Existing different version: warn + skip (do NOT mutate). The
+ *   operator owns their pin.
+ * - Idempotent: re-runs are byte-identical when the pin already
+ *   matches. Detects and preserves indent / EOL / trailing-newline so
+ *   no spurious diff churn lands in the consumer's repo.
+ * - Dogfood short-circuit: when the consumer's `pkg.name` is
+ *   `@bookedsolid/rea` itself, skip silently — the dogfood install
+ *   pins the version via the build, not via the manifest.
+ *
+ * # Why caret
+ *
+ * A caret pin (`^0.49.0` → satisfies 0.49.x AND 0.50.0+) gives
+ * consumers automatic minor-version uptake without breaking when the
+ * shim ABI bumps. Major bumps remain a deliberate operator action.
+ *
+ * # Why warn-and-skip on existing different version
+ *
+ * Three scenarios where this matters:
+ *
+ *   1. Operator explicitly pinned an exact version (`"0.48.1"`) for
+ *      reproducibility — `rea init` overwriting that to caret would
+ *      silently widen their pin.
+ *   2. Operator is running an OLDER `rea init` against a `package.json`
+ *      that has a NEWER `rea` pin. Downgrading the pin would brick the
+ *      install once the operator's lockfile resolves against it.
+ *   3. Operator deliberately pinned a workspace-relative path (`"workspace:^"`,
+ *      `"file:../rea"`). Replacing that with a registry pin breaks the
+ *      monorepo wiring.
+ *
+ * Warn-and-skip preserves operator intent in all three cases.
+ */
+/** Package name we self-pin. */
+export declare const REA_PACKAGE_NAME = "@bookedsolid/rea";
+export interface SelfPinResult {
+    /**
+     * Outcome of the operation. Single value so the caller can format a
+     * one-line console message uniformly.
+     *
+     *   - `'wrote'`     — package.json was mutated (new dep added OR an
+     *                      existing matching pin re-serialized identically).
+     *   - `'bumped'`    — `mode: 'upgrade'` only. Existing pin was a
+     *                     managed-caret form on the SAME major as the new
+     *                     CLI but did not admit the new minor (e.g.
+     *                     `^0.49.0` + new CLI `0.50.0` — `^0.49.0` rejects
+     *                     `0.50.0` because pre-1.0 caret behaves like
+     *                     tilde). We re-write the pin to the new caret
+     *                     form. Operator-facing message includes the
+     *                     "bumped from X to Y" delta so the change is
+     *                     visible in the upgrade log.
+     *   - `'skipped-same'` — the existing pin already matches what we
+     *                        would write (idempotent re-run, byte-identical).
+     *   - `'skipped-different'` — the existing pin differs from ours and
+     *                              we refuse to mutate (operator owns the pin).
+     *   - `'skipped-dogfood'` — `pkg.name === '@bookedsolid/rea'`, the
+     *                            self-host case; we never self-pin.
+     *   - `'skipped-no-package-json'` — no `package.json` in the explicit
+     *                                    target directory. P2-4: we never
+     *                                    walk upward — invocation from a
+     *                                    pkg-less subdir refuses rather
+     *                                    than silently mutating the parent.
+     *   - `'skipped-malformed-package-json'` — `package.json` exists but
+     *                                           is not valid JSON or not an
+     *                                           object; we refuse to mutate
+     *                                           a file we do not understand.
+     *   - `'skipped-symlink-package-json'` — R10-P2 (codex round 10):
+     *                                          `package.json` is a symlink.
+     *                                          DRY-RUN only — live mode
+     *                                          THROWS rather than returning
+     *                                          this. The skip-shape exists
+     *                                          so `rea upgrade --dry-run`
+     *                                          / `--check` can complete a
+     *                                          preview even when the
+     *                                          symlink would block the
+     *                                          live run.
+     */
+    action: 'wrote' | 'bumped' | 'skipped-same' | 'skipped-different' | 'skipped-dogfood' | 'skipped-no-package-json' | 'skipped-malformed-package-json' | 'skipped-symlink-package-json';
+    /** Absolute path to the package.json we resolved (or null when none found). */
+    packageJsonPath: string | null;
+    /** Caret-pinned version range we wrote (e.g. `^0.49.0`). Empty when no write happened. */
+    pinnedRange: string;
+    /** Existing range when the action was `skipped-different`. */
+    existingRange?: string;
+    /** Operator-facing message (one line, no newline). */
+    message: string;
+}
+export interface SelfPinOptions {
+    /**
+     * Starting directory for the upward `package.json` walk. The walk
+     * stops at the first `package.json` found OR at the filesystem root.
+     */
+    cwd: string;
+    /**
+     * The currently-running `@bookedsolid/rea` CLI version (e.g.
+     * `'0.49.0'`). The written pin is `^<version>`.
+     */
+    cliVersion: string;
+    /**
+     * When true, never log to stderr — the caller will surface the result
+     * structurally. Used by `rea upgrade` which composes its own output.
+     */
+    silent?: boolean;
+    /**
+     * R3-P2 (codex round 3): when true, perform the read + decision
+     * logic but skip the on-disk write. The returned `action`
+     * discriminant is the SAME as the live run would produce
+     * (`'wrote'`, `'bumped'`, `'skipped-same'`, `'skipped-different'`,
+     * etc.) so the caller can preview exactly what the live run will
+     * do. `message` carries a `would-` prefix on the actions that
+     * would have mutated the file (`wrote` / `bumped`) so the caller's
+     * console output is unambiguous.
+     *
+     * Pre-fix, `rea upgrade --dry-run` short-circuited around the entire
+     * `selfPinRea` call, hiding the planned self-pin action from the
+     * dry-run preview. Operators ran dry-run, saw zero pin-related
+     * lines, then ran the live upgrade and got a surprise mutation of
+     * their package.json.
+     *
+     * Default: `false` (write path active — preserves existing behavior
+     * for every caller that does not opt in).
+     */
+    dryRun?: boolean;
+    /**
+     * Call-site discriminator (P1-1 / codex round 2).
+     *
+     *   - `'init'` (default) — `rea init` semantics: warn-and-skip on every
+     *      existing-different-version pin. Respects whatever pin the
+     *      operator already chose; we never overwrite on a fresh install.
+     *
+     *   - `'upgrade'` — `rea upgrade` semantics: when the existing pin is
+     *      a managed-caret form (a caret pin we previously wrote, with no
+     *      operator-authored shape laundering) AND the new CLI is on the
+     *      SAME major as the existing pin AND the existing caret does NOT
+     *      admit the new CLI version, BUMP the pin to the new caret. This
+     *      closes the pre-1.0 caret tightness trap: `^0.49.0` does NOT
+     *      admit `0.50.0` (pre-1.0 caret is npm-spec'd to behave like
+     *      tilde), so without auto-bump a 0.49.x → 0.50.x upgrade would
+     *      copy the newer hooks but leave the old CLI pinned, recreating
+     *      the hook/CLI skew this whole feature exists to prevent.
+     *
+     *      Auto-bump shape gate: existing range matches a strict managed-
+     *      caret regex (`^\^\d+\.\d+(\.\d+)?(-prerelease)?$`). Anything
+     *      else (`workspace:*`, `file:..`, git URLs, `next`, exact pins,
+     *      tildes, complex ranges) is operator-authored and we hands-off.
+     *      Cross-major bumps (`^0.x` → `1.x` or `^1.x` → `0.x`) are
+     *      ALSO operator-authored decisions and we hands-off — major
+     *      changes are meaningful and should not be silent.
+     *
+     * Default: `'init'`. R13-P1 (codex round 13) update: BOTH the
+     * `rea init` and `rea upgrade` call sites now pass `mode:
+     * 'upgrade'` explicitly. The R11-P1 preflight (init) +
+     * R9-P1 preflight (upgrade) filter out non-managed-caret cases
+     * BEFORE `selfPinRea` runs, so the only thing that reaches the
+     * write path is either a fresh write OR a managed-caret bump —
+     * and `mode: 'upgrade'` is the correct semantics for both.
+     *
+     * The `'init'` default is preserved for backwards-compat with any
+     * external caller of this exported function. New rea-internal
+     * call sites should pass `mode: 'upgrade'` explicitly.
+     */
+    mode?: 'init' | 'upgrade';
+}
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF / EF BB BF) from a string, returning the
+ * rest. No-op when no BOM is present.
+ *
+ * Some Windows operators commit `package.json` with a leading BOM; `JSON.parse`
+ * rejects it (the spec says JSON.parse must error on a leading BOM). We
+ * silently strip it before parse — npm and pnpm both tolerate either form
+ * when writing back, so dropping the BOM on save is the simpler, more
+ * invariant choice. The alternative (detect-and-preserve) would need an
+ * extra field on `FileShape` plus a re-prepend in `serialize`, and the cost
+ * (one operator who deliberately wanted a BOM no longer has one) is much
+ * lower than the cost of an unrecoverable false-positive
+ * `skipped-malformed-package-json` on every BOM-bearing manifest.
+ *
+ * P3-1 (codex round 1): extracted into a shared helper so the same canonical
+ * BOM-strip applies to BOTH `readPackageJson` (the write path used by
+ * `selfPinRea`) AND `checkSelfPinDeclaredSync` (the doctor brick-state
+ * detector). Pre-extraction, only the write path stripped — doctor would
+ * report `fail-malformed` for a BOM-prefixed manifest that self-pin
+ * tolerated fine, which is the asymmetric-fix class we explicitly want
+ * to defend against.
+ */
+export declare function stripUtf8Bom(input: string): string;
+/**
+ * Decide whether `rea upgrade` should auto-bump an existing pin to the
+ * newly-written caret. Returns `true` only when:
+ *
+ *   1. `existing` matches the managed-caret shape (we wrote it; it
+ *      isn't a workspace/file/git/tag/exact pin).
+ *   2. `newRange` ALSO matches the managed-caret shape (sanity — the
+ *      function should never be called with a non-caret target, but
+ *      the predicate stays self-contained).
+ *   3. Both ranges share the same major version. Cross-major bumps
+ *      are intentional operator decisions and we hands-off.
+ *   4. The existing caret does NOT already admit the version the new
+ *      range would resolve to. We extract the floor version from
+ *      `newRange` (strip the leading `^`) and ask
+ *      `semver.satisfies(floor, existing)`:
+ *
+ *        - `^0.49.0` + `^0.49.5` → 0.49.5 satisfies ^0.49.0 → NO bump
+ *        - `^0.49.0` + `^0.50.0` → 0.50.0 does NOT satisfy → BUMP
+ *        - `^0.49.0` + `^0.49.1-beta.0` → prerelease does NOT satisfy
+ *          a non-prerelease range (npm spec) → BUMP (R4-P2)
+ *        - `^1.0.0` + `^1.5.0` → 1.5.0 satisfies ^1.0.0 → NO bump
+ *        - `^1.0.0` + `^1.1.0-beta.0` → prerelease does NOT satisfy
+ *          → BUMP (R4-P2)
+ *
+ * The pre-fix predicate compared major/minor by hand, which
+ * mis-classified prerelease bumps as already-covered. Switching to
+ * `semver.satisfies` gives us npm-spec-correct semver behavior in
+ * one place.
+ */
+export declare function shouldBumpManagedCaret(existing: string, newRange: string): boolean;
+/**
+ * R9-P1 (codex round 9 / 0.49.0) — `rea upgrade` blocking-pin check.
+ *
+ * # Why this exists
+ *
+ * `rea init` and `rea upgrade` write the consumer's `.rea/policy.yaml`
+ * with the new `bootstrap_allowlist:` top-level key (added in 0.49.0).
+ * `src/policy/loader.ts::PolicySchema` is `.strict()` — older CLIs
+ * (≤ 0.48.x) cannot parse a policy file with that key and throw on
+ * load. So if `rea upgrade` writes 0.49 hooks + policy artifacts on
+ * top of a `package.json` that still pins an OLD `@bookedsolid/rea`
+ * version, the hooks resolve the OLD CLI from `node_modules/` on the
+ * next fire and that CLI refuses every payload (policy.yaml strict
+ * parse fails). The seemingly-successful upgrade leaves the consumer
+ * with non-functional gates.
+ *
+ * R2-P1-1 closed the managed-caret-bump case (we write the new pin in
+ * place). R9-P1 closes the gap for EVERY other shape: workspace:*,
+ * file:.., git URLs, dist-tags like `next`, exact pins like `0.48.0`,
+ * and managed-caret-cross-major. The fix: abort the upgrade BEFORE
+ * any artifacts hit disk when the existing pin would not admit the
+ * new CLI version.
+ *
+ * # Contract
+ *
+ * Returns a discriminated result:
+ *
+ *   - `kind: 'ok'`              — proceed with upgrade. Either:
+ *       * no existing pin (will write fresh), OR
+ *       * existing pin admits the new CLI version (semver.satisfies), OR
+ *       * existing pin is a managed-caret that bumps cleanly (R2-P1-1).
+ *   - `kind: 'no-pkg-json'`     — no package.json in cwd; proceed.
+ *       `selfPinRea` will return `skipped-no-package-json` later.
+ *   - `kind: 'malformed-pkg-json'` — same; `selfPinRea` will return
+ *       `skipped-malformed-package-json` later.
+ *   - `kind: 'dogfood'`         — pkg.name === '@bookedsolid/rea';
+ *       proceed (dogfood install never mutates the manifest).
+ *   - `kind: 'block'`           — existing pin won't admit the new
+ *       CLI; the caller MUST abort before writing artifacts.
+ *       Carries the operator-facing reason string.
+ *
+ * # Why a separate function?
+ *
+ * `selfPinRea` is the WRITE-path helper. `checkUpgradeBlockingPin` is
+ * a READ-only preflight that gives the caller a yes/no answer before
+ * any disk mutation. We do NOT fold the abort logic into `selfPinRea`
+ * because:
+ *   1. Other callers of `selfPinRea` (rea init) want the warn-and-skip
+ *      posture, not abort.
+ *   2. The upgrade entry needs to run this check BEFORE the canonical
+ *      file-write loop, well upstream of the existing `selfPinRea`
+ *      invocation.
+ *   3. Keeping the check stateless and read-only makes it testable in
+ *      isolation without filesystem side effects beyond reading
+ *      package.json (and even those are bounded — single read).
+ */
+export type UpgradeBlockingPinCheckResult = {
+    kind: 'ok';
+    packageJsonPath: string | null;
+    existingRange?: string | undefined;
+} | {
+    kind: 'no-pkg-json';
+} | {
+    kind: 'malformed-pkg-json';
+    packageJsonPath: string;
+} | {
+    kind: 'dogfood';
+    packageJsonPath: string;
+} | {
+    kind: 'block';
+    packageJsonPath: string;
+    existingRange: string;
+    newCliVersion: string;
+    newPinnedRange: string;
+    reason: string;
+} | {
+    kind: 'block-symlink';
+    packageJsonPath: string;
+    newCliVersion: string;
+    newPinnedRange: string;
+    reason: string;
+};
+export interface UpgradeBlockingPinCheckOptions {
+    cwd: string;
+    cliVersion: string;
+    /**
+     * R11-P1 (codex round 11): which call site is invoking the
+     * pre-flight. The check logic is identical for both modes — what
+     * changes is the operator-facing message prefix:
+     *
+     *   - `'upgrade'` (default) → `rea upgrade refusing: ...`
+     *   - `'init'`              → `rea init refusing: ...`
+     *
+     * Both `runInit` and `runUpgrade` write the same 0.49 hooks +
+     * policy artifacts, so the skew-creation risk is identical and
+     * the pre-flight needs to fire on both surfaces. Pre-R11 the
+     * pre-flight was upgrade-only; `rea init` on an existing-install
+     * scenario could still leave the bash gates non-functional.
+     */
+    mode?: 'init' | 'upgrade';
+}
+/**
+ * Determine whether the existing `@bookedsolid/rea` pin would block
+ * `rea init` / `rea upgrade` from writing 0.49 artifacts safely.
+ * See type doc.
+ *
+ * R11-P1 (codex round 11): the check applies to BOTH `rea init` and
+ * `rea upgrade`. The implementation is unchanged; only the
+ * operator-facing message prefix varies with `mode`.
+ */
+export declare function checkUpgradeBlockingPin(options: UpgradeBlockingPinCheckOptions): Promise<UpgradeBlockingPinCheckResult>;
+/**
+ * Idempotent self-pin step. See module header for the full contract.
+ */
+export declare function selfPinRea(options: SelfPinOptions): Promise<SelfPinResult>;
+/**
+ * `rea doctor` check: FAIL when hook shims are present but no self-pin
+ * is declared. This is the "brick state" detector — a fresh clone of a
+ * consumer repo whose `.claude/hooks/` exists but whose `package.json`
+ * declares no `@bookedsolid/rea` dep is exactly the scenario the bash
+ * allowlist (Fix B) recovers from. Doctor surfaces it loudly so the
+ * operator knows to run `rea upgrade` (which re-runs the self-pin
+ * step) instead of fighting the gates.
+ *
+ * Returns a discriminated result:
+ *   - `kind: 'pass'`           — hooks + self-pin both present.
+ *   - `kind: 'pass-no-hooks'`  — no `.claude/hooks/` directory; the
+ *                                check is N/A (caller emits an `info`
+ *                                row instead of a check row).
+ *   - `kind: 'pass-no-pkg'`    — no `package.json` in the doctor's
+ *                                target directory (P2-4: no upward
+ *                                walk — doctor reports the absence
+ *                                rather than scanning the parent
+ *                                chain). Doctor treats this as a
+ *                                `warn` not a `fail` because the
+ *                                bootstrap allowlist refuses pkg-less
+ *                                projects anyway.
+ *   - `kind: 'pass-dogfood'`   — `pkg.name === '@bookedsolid/rea'`.
+ *   - `kind: 'fail'`           — hooks present, package.json present,
+ *                                no self-pin declared. Caller emits
+ *                                a `fail` row with the recovery
+ *                                instruction.
+ *   - `kind: 'fail-malformed'` — package.json exists but is malformed
+ *                                or not an object. Caller emits a
+ *                                `fail` row naming the file.
+ *   - `kind: 'fail-symlink'`   — R10-P2 (codex round 10):
+ *                                package.json is a symlink. Doctor
+ *                                emits a `fail` row mirroring the
+ *                                write path's refusal so operators
+ *                                discover the misconfiguration before
+ *                                running `rea upgrade`.
+ */
+export type SelfPinCheckResult = {
+    kind: 'pass';
+    packageJsonPath: string;
+    declaredRange: string;
+    declaredIn: 'dependencies' | 'devDependencies';
+} | {
+    kind: 'pass-no-hooks';
+} | {
+    kind: 'pass-no-pkg';
+    hooksDir: string;
+} | {
+    kind: 'pass-dogfood';
+    packageJsonPath: string;
+} | {
+    kind: 'fail';
+    packageJsonPath: string;
+    hooksDir: string;
+} | {
+    kind: 'fail-malformed';
+    packageJsonPath: string;
+} | {
+    kind: 'fail-symlink';
+    packageJsonPath: string;
+    reason: string;
+} | {
+    kind: 'fail-incompatible';
+    packageJsonPath: string;
+    declaredRange: string;
+    declaredIn: 'dependencies' | 'devDependencies';
+    currentCliVersion: string;
+    reason: string;
+} | {
+    kind: 'fail-non-semver';
+    packageJsonPath: string;
+    declaredRange: string;
+    declaredIn: 'dependencies' | 'devDependencies';
+    reason: string;
+};
+export declare function checkSelfPinDeclared(baseDir: string, cliVersion?: string): Promise<SelfPinCheckResult>;
+/**
+ * Synchronous variant of {@link checkSelfPinDeclared}. `rea doctor`
+ * runs all checks sync; the read+parse cost here is microseconds so
+ * the sync form is acceptable.
+ *
+ * R11-P3 (codex round 11): when `cliVersion` is provided, this check
+ * also verifies that the declared range admits the running CLI
+ * version (semver.satisfies). Without `cliVersion` the check
+ * reverts to presence-only behavior (backwards-compat for callers
+ * that don't yet pass the version). The doctor wrapper
+ * (`checkSelfPinDeclaredCheck`) passes `getPkgVersion()` so the
+ * skew detection always runs in the doctor surface.
+ */
+export declare function checkSelfPinDeclaredSync(baseDir: string, cliVersion?: string): SelfPinCheckResult;