openplanr 1.22.0 → 1.24.0

package/dist/services/upgrade-offer-service.js

@@ -0,0 +1,256 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { display, logger } from '../utils/logger.js';
+import { saveConfig } from './config-service.js';
+import { isNonInteractive } from './interactive-state.js';
+import { promptSelect } from './prompt-service.js';
+import { runtimeRoot } from './runtime-manager-service.js';
+import { executeCliHalfUpgrade, planCliUpgrade, reconcileInstalledTuple, } from './upgrade-service.js';
+const DEFAULT_SNOOZE_STATE = {
+    neverAsk: false,
+    snoozeUntil: null,
+    snoozeStage: 0,
+};
+/**
+ * FR5 escalating backoff, keyed by the stage the user is snoozing *at*. The
+ * first "not now" (stage 0) waits a day; the next (stage 1) two days; every one
+ * after that (stage 2) a full week — so a prompt that was dismissed never
+ * reappears frequently enough to train a reflexive dismissal.
+ */
+const BACKOFF_MS = {
+    0: 24 * 60 * 60 * 1000,
+    1: 48 * 60 * 60 * 1000,
+    2: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * FR6's "exact re-enable command" — stated verbatim both when the user chooses
+ * "never ask again" in the offer and when they set it via
+ * `planr config set-upgrade-policy --never-ask`, so a permanent opt-out is never
+ * a trap the user cannot find how to undo.
+ */
+export const UPGRADE_REENABLE_COMMAND = 'planr config set-upgrade-policy --ask-again';
+/** Where the machine-local snooze/never-ask state lives (reuses T-002's root). */
+export function upgradeStatePath() {
+    return path.join(runtimeRoot(), 'upgrade-state.json');
+}
+/**
+ * Read the snooze state, failing open on *any* problem. A missing file is the
+ * common first-run case; a corrupt file is the crash-mid-write case the task's
+ * atomicity note calls out — both resolve to "no snooze recorded" so a bad local
+ * preference file can never throw out of every subsequent `preAction` hook.
+ */
+export function readSnoozeState() {
+    const statePath = upgradeStatePath();
+    if (!existsSync(statePath))
+        return { ...DEFAULT_SNOOZE_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+        const stage = parsed.snoozeStage;
+        return {
+            neverAsk: parsed.neverAsk === true,
+            snoozeUntil: typeof parsed.snoozeUntil === 'string' ? parsed.snoozeUntil : null,
+            snoozeStage: stage === 1 || stage === 2 ? stage : 0,
+        };
+    }
+    catch {
+        return { ...DEFAULT_SNOOZE_STATE };
+    }
+}
+/** Persist the snooze state. Proportionate to a non-critical local file: a plain write. */
+export async function writeSnoozeState(state) {
+    const statePath = upgradeStatePath();
+    await mkdir(path.dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/**
+ * A test seam of the same shape as T-002's `OPENPLANR_ECOSYSTEM_SOURCE` and
+ * T-003's `OPENPLANR_NPM_BIN`: unset in production, it lets a hermetic
+ * subprocess integration test drive the offer path — which has no TTY — with a
+ * pre-selected choice instead of a live prompt.
+ */
+export function injectedOfferChoice() {
+    const raw = process.env.OPENPLANR_UPGRADE_OFFER_CHOICE?.trim();
+    if (raw === 'upgrade-now' || raw === 'always' || raw === 'not-now' || raw === 'never')
+        return raw;
+    return null;
+}
+/**
+ * Whether the offer can be surfaced from `preAction`. In production this reduces
+ * exactly to `!isNonInteractive()` — the offer is shown only where a human can
+ * answer it. The injected-choice seam additionally makes the path reachable from
+ * a TTY-less test subprocess.
+ */
+export function upgradeOfferReachable() {
+    return !isNonInteractive() || injectedOfferChoice() !== null;
+}
+/** Optional injected clock (ms since epoch), for a deterministic subprocess test. */
+function injectedNow() {
+    const raw = process.env.OPENPLANR_UPGRADE_NOW?.trim();
+    if (!raw)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+const OFFER_CHOICES = [
+    { name: '[u] Upgrade now', value: 'upgrade-now' },
+    { name: '[a] Always keep me current (upgrade automatically from now on)', value: 'always' },
+    { name: '[n] Not now (ask again later)', value: 'not-now' },
+    { name: '[x] Never ask again', value: 'never' },
+];
+/**
+ * The default prompter: the injected-choice seam wins (test subprocess),
+ * otherwise the existing `promptSelect` helper renders the four-way menu with
+ * "not now" as the safe default.
+ */
+async function defaultChooseAction(targetVersion) {
+    const injected = injectedOfferChoice();
+    if (injected !== null)
+        return injected;
+    return promptSelect(`OpenPlanr ${targetVersion} is available — how would you like to proceed?`, OFFER_CHOICES, 'not-now');
+}
+/** Human phrase for the backoff about to be applied at a given stage. */
+function describeBackoff(stage) {
+    return stage === 0 ? 'in 24 hours' : stage === 1 ? 'in 48 hours' : 'in a week';
+}
+/**
+ * The entry point wired into `src/cli/index.ts`'s `preAction` hook. Fail-open at
+ * the top level: nothing about an upgrade offer may ever break the command the
+ * user actually ran, so every path below is wrapped and a thrown error degrades
+ * to "did not surface" rather than propagating out of the hook.
+ */
+export async function maybeOfferUpgrade(projectDir, config, deps = {}) {
+    try {
+        return await runOffer(projectDir, config ?? null, deps);
+    }
+    catch {
+        return { surfaced: false, choice: null, reason: 'error' };
+    }
+}
+async function runOffer(projectDir, config, deps) {
+    const now = deps.now ?? injectedNow() ?? Date.now();
+    const reconcile = deps.reconcile ?? reconcileInstalledTuple;
+    const runUpgrade = deps.executeUpgrade ?? executeCliHalfUpgrade;
+    const chooseAction = deps.chooseAction ?? defaultChooseAction;
+    const state = readSnoozeState();
+    // (1) Permanent opt-out — honoured before anything else. Zero reconcile.
+    if (state.neverAsk)
+        return { surfaced: false, choice: null, reason: 'never-ask' };
+    // (2) Active snooze — the whole point of the backoff. This is the no-delay
+    //     guarantee: a still-snoozed command touches no network and no reconcile.
+    if (state.snoozeUntil && now < Date.parse(state.snoozeUntil)) {
+        return { surfaced: false, choice: null, reason: 'snoozed' };
+    }
+    // (3) Team opt-out of the check itself — `update_check: false` skips reconcile
+    //     entirely: no network, no prompt.
+    if (config?.upgrade?.updateCheck === false) {
+        return { surfaced: false, choice: null, reason: 'update-check-disabled' };
+    }
+    // Only now do we consult reconcile — bounded, cache-first, and offline-safe by
+    // T-002's construction. `unknown`/`aligned`/`incompatible` never offer here.
+    const reconciliation = await reconcile(projectDir, { now });
+    if (reconciliation.status !== 'upgrade-available') {
+        return { surfaced: false, choice: null, reason: 'not-upgrade-available' };
+    }
+    const plan = planCliUpgrade(reconciliation);
+    const targetVersion = plan.targetCliVersion ?? reconciliation.published?.cli.version ?? 'a newer version';
+    // (4) `auto_upgrade: true` — the team asked us to skip the prompt entirely.
+    if (config?.upgrade?.autoUpgrade === true) {
+        await performUpgrade(projectDir, plan, runUpgrade);
+        await writeSnoozeState({ ...DEFAULT_SNOOZE_STATE });
+        return { surfaced: false, choice: null, reason: 'auto-upgraded' };
+    }
+    // (5) The four-way offer.
+    logger.info(`An OpenPlanr upgrade is available (${reconciliation.installed.cli} → ${targetVersion}).`);
+    const choice = await chooseAction(targetVersion);
+    await applyChoice({ choice, projectDir, config, plan, now, state, runUpgrade });
+    return { surfaced: true, choice, reason: 'offered' };
+}
+async function applyChoice(input) {
+    const { choice, projectDir, config, plan, now, state, runUpgrade } = input;
+    switch (choice) {
+        case 'upgrade-now':
+            await performUpgrade(projectDir, plan, runUpgrade);
+            // A satisfied upgrade clears any prior snooze so future drift starts fresh.
+            await writeSnoozeState({ ...DEFAULT_SNOOZE_STATE });
+            return;
+        case 'always':
+            await enableAutoUpgrade(projectDir, config);
+            await performUpgrade(projectDir, plan, runUpgrade);
+            await writeSnoozeState({ ...DEFAULT_SNOOZE_STATE });
+            return;
+        case 'not-now':
+            await recordSnooze(state, now);
+            return;
+        case 'never':
+            await recordNeverAsk(state);
+            return;
+    }
+}
+/** FR5 escalating snooze: wait `BACKOFF_MS[stage]`, then advance the stage (capped at 2). */
+async function recordSnooze(state, now) {
+    const stage = state.snoozeStage;
+    const snoozeUntil = new Date(now + BACKOFF_MS[stage]).toISOString();
+    const nextStage = stage < 2 ? (stage + 1) : 2;
+    await writeSnoozeState({ neverAsk: false, snoozeUntil, snoozeStage: nextStage });
+    logger.info(`Snoozed — I'll check for an upgrade again ${describeBackoff(stage)}.`);
+}
+/** FR6 permanent, reversible opt-out. States the exact re-enable command. */
+async function recordNeverAsk(state) {
+    await writeSnoozeState({ ...state, neverAsk: true, snoozeUntil: null });
+    logger.info('You will not be asked about upgrades again on this machine.');
+    logger.info(`To re-enable the reminder, run: ${UPGRADE_REENABLE_COMMAND}`);
+}
+/** Persist the team-shared `auto_upgrade` preference into `config.json`. */
+async function enableAutoUpgrade(projectDir, config) {
+    if (!config) {
+        logger.warn('No project config found, so auto-upgrade could not be saved for the team — upgrading now.');
+        return;
+    }
+    const updated = {
+        ...config,
+        upgrade: { ...config.upgrade, autoUpgrade: true },
+    };
+    await saveConfig(projectDir, updated);
+    logger.success('Auto-upgrade enabled — future upgrades will run without asking.');
+}
+/**
+ * Delegate the CLI-owned half to T-003's executor and render its result. This
+ * re-uses `executeCliHalfUpgrade` verbatim: the offer never re-implements the
+ * npm install, the verify-after-write, or the plugin-half prescription.
+ */
+async function performUpgrade(projectDir, plan, runUpgrade) {
+    if (!plan.proceed || !plan.targetCliVersion) {
+        logger.warn(plan.reason);
+        return;
+    }
+    logger.info(`Upgrading the OpenPlanr CLI to ${plan.targetCliVersion}…`);
+    const result = await runUpgrade({ projectDir, targetCliVersion: plan.targetCliVersion });
+    renderUpgradeResult(result);
+}
+/** Mirror `planr upgrade apply`'s rendering so the inline offer reads identically. */
+function renderUpgradeResult(result) {
+    if (result.ok) {
+        logger.success(`CLI upgraded to ${result.installedVersion}.`);
+        if (result.changelogBullets.length > 0) {
+            display.blank();
+            display.heading("What's new");
+            for (const bullet of result.changelogBullets)
+                display.bullet(bullet);
+        }
+        if (result.pluginHalfCommands.length > 0) {
+            display.blank();
+            display.heading('Plugin half — the CLI cannot install host plugins');
+            logger.info('Run these yourself, in order (the first refreshes the marketplace):');
+            result.pluginHalfCommands.forEach((command, index) => {
+                display.numbered(index + 1, command);
+            });
+        }
+    }
+    else {
+        logger.error(result.failure?.message ?? 'The upgrade did not complete.');
+        if (result.restoredTo)
+            logger.info(`Restored the previous version ${result.restoredTo}.`);
+    }
+}
+//# sourceMappingURL=upgrade-offer-service.js.map

package/dist/services/upgrade-offer-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-offer-service.js","sourceRoot":"","sources":["../../src/services/upgrade-offer-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAGL,qBAAqB,EACrB,cAAc,EAEd,uBAAuB,GAExB,MAAM,sBAAsB,CAAC;AAkC9B,MAAM,oBAAoB,GAAuB;IAC/C,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,IAAI;IACjB,WAAW,EAAE,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,GAA8B;IAC5C,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACtB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACtB,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,6CAA6C,CAAC;AAEtF,kFAAkF;AAClF,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,oBAAoB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,GAAG,oBAAoB,EAAE,CAAC;IAC/D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAgC,CAAC;QAC1F,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC;QACjC,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,IAAI;YAClC,WAAW,EAAE,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI;YAC/E,WAAW,EAAE,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACpD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,oBAAoB,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAyB;IAC9D,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,EAAE,IAAI,EAAE,CAAC;IAC/D,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IAClG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,CAAC,gBAAgB,EAAE,IAAI,mBAAmB,EAAE,KAAK,IAAI,CAAC;AAC/D,CAAC;AAED,qFAAqF;AACrF,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,CAAC;IACtD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,MAAM,aAAa,GAAuD;IACxE,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa,EAAE;IACjD,EAAE,IAAI,EAAE,gEAAgE,EAAE,KAAK,EAAE,QAAQ,EAAE;IAC3F,EAAE,IAAI,EAAE,+BAA+B,EAAE,KAAK,EAAE,SAAS,EAAE;IAC3D,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE;CAChD,CAAC;AAEF;;;;GAIG;AACH,KAAK,UAAU,mBAAmB,CAAC,aAAqB;IACtD,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,YAAY,CACjB,aAAa,aAAa,gDAAgD,EAC1E,aAAa,EACb,SAAS,CACV,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,SAAS,eAAe,CAAC,KAAgB;IACvC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC;AACjF,CAAC;AA8BD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,UAAkB,EAClB,MAA0C,EAC1C,OAA8B,EAAE;IAEhC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,UAAkB,EAClB,MAA8B,EAC9B,IAA2B;IAE3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,uBAAuB,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC;IAChE,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,mBAAmB,CAAC;IAE9D,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAEhC,yEAAyE;IACzE,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAElF,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,KAAK,CAAC,WAAW,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC9D,CAAC;IAED,+EAA+E;IAC/E,uCAAuC;IACvC,IAAI,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,KAAK,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC5E,CAAC;IAED,+EAA+E;IAC/E,6EAA6E;IAC7E,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5D,IAAI,cAAc,CAAC,MAAM,KAAK,mBAAmB,EAAE,CAAC;QAClD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC5E,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,aAAa,GACjB,IAAI,CAAC,gBAAgB,IAAI,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,IAAI,iBAAiB,CAAC;IAEtF,4EAA4E;IAC5E,IAAI,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACnD,MAAM,gBAAgB,CAAC,EAAE,GAAG,oBAAoB,EAAE,CAAC,CAAC;QACpD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACpE,CAAC;IAED,0BAA0B;IAC1B,MAAM,CAAC,IAAI,CACT,sCAAsC,cAAc,CAAC,SAAS,CAAC,GAAG,MAAM,aAAa,IAAI,CAC1F,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,aAAa,CAAC,CAAC;IACjD,MAAM,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAChF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvD,CAAC;AAYD,KAAK,UAAU,WAAW,CAAC,KAAuB;IAChD,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAC3E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,aAAa;YAChB,MAAM,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACnD,4EAA4E;YAC5E,MAAM,gBAAgB,CAAC,EAAE,GAAG,oBAAoB,EAAE,CAAC,CAAC;YACpD,OAAO;QACT,KAAK,QAAQ;YACX,MAAM,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC5C,MAAM,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACnD,MAAM,gBAAgB,CAAC,EAAE,GAAG,oBAAoB,EAAE,CAAC,CAAC;YACpD,OAAO;QACT,KAAK,SAAS;YACZ,MAAM,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC/B,OAAO;QACT,KAAK,OAAO;YACV,MAAM,cAAc,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO;IACX,CAAC;AACH,CAAC;AAED,6FAA6F;AAC7F,KAAK,UAAU,YAAY,CAAC,KAAyB,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC;IAChC,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACpE,MAAM,SAAS,GAAc,KAAK,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,GAAG,CAAC,CAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,gBAAgB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;IACjF,MAAM,CAAC,IAAI,CAAC,6CAA6C,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACtF,CAAC;AAED,6EAA6E;AAC7E,KAAK,UAAU,cAAc,CAAC,KAAyB;IACrD,MAAM,gBAAgB,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACxE,MAAM,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;IAC3E,MAAM,CAAC,IAAI,CAAC,mCAAmC,wBAAwB,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,4EAA4E;AAC5E,KAAK,UAAU,iBAAiB,CAC9B,UAAkB,EAClB,MAA8B;IAE9B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,IAAI,CACT,2FAA2F,CAC5F,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAoB;QAC/B,GAAG,MAAM;QACT,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE;KAClD,CAAC;IACF,MAAM,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,OAAO,CAAC,iEAAiE,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAC3B,UAAkB,EAClB,IAAuC,EACvC,UAAuF;IAEvF,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,kCAAkC,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACzF,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,sFAAsF;AACtF,SAAS,mBAAmB,CAAC,MAAmC;IAC9D,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,CAAC,OAAO,CAAC,mBAAmB,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC9B,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,gBAAgB;gBAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,OAAO,CAAC,mDAAmD,CAAC,CAAC;YACrE,MAAM,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;YACnF,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;gBACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;YACvC,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,+BAA+B,CAAC,CAAC;QACzE,IAAI,MAAM,CAAC,UAAU;YAAE,MAAM,CAAC,IAAI,CAAC,iCAAiC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC"}

package/dist/services/upgrade-service.d.ts

@@ -0,0 +1,156 @@
+import { type ClaudeCommandRunner, type ClaudePluginOperation } from './claude-plugin-service.js';
+/**
+ * One component of the published compatibility manifest (`ecosystem.json`'s
+ * `components.*`). Each artifact carries its own version plus the mutual
+ * compatibility range it requires of its sibling.
+ */
+export interface EcosystemComponent {
+    version: string;
+    cliRange?: string;
+    pipelineRange?: string;
+}
+export interface EcosystemComponents {
+    cli: EcosystemComponent;
+    pipeline: EcosystemComponent;
+    skills: EcosystemComponent;
+    marketplace?: EcosystemComponent;
+}
+/**
+ * Where the compatibility manifest came from for this reconciliation.
+ *
+ * - `network`  — freshly fetched and cached this run.
+ * - `cache`    — a still-fresh cache (within the TTL); no network was touched.
+ * - `stale-cache` — the fetch failed, so a past cache was reused.
+ * - `unavailable` — neither a fetch nor any cache; the tuple cannot be judged.
+ */
+export type EcosystemSource = 'network' | 'cache' | 'stale-cache' | 'unavailable';
+export interface UpgradeReconciliation {
+    status: 'aligned' | 'upgrade-available' | 'incompatible' | 'unknown';
+    installed: {
+        cli: string;
+        skills: string | null;
+        pipeline: string | null;
+    };
+    published: EcosystemComponents | null;
+    ecosystemSource: EcosystemSource;
+}
+export interface ReconcileOptions {
+    /** Injectable `claude` runner; defaults to the real host command. */
+    claudeCommandRunner?: ClaudeCommandRunner;
+    /** Injectable fetch, for hermetic offline/hung-network tests. */
+    fetchImpl?: typeof fetch;
+    /** Clock override (ms since epoch), for deterministic TTL tests. */
+    now?: number;
+    /** Hard fetch timeout in ms; a hung network must never exceed this. */
+    timeoutMs?: number;
+}
+/**
+ * FR3: read the published compatibility manifest, compare it against the real
+ * installed tuple (this CLI's version, plus both host-plugin versions), and
+ * report whether the tuple is aligned, has an upgrade available, or is
+ * genuinely incompatible. The warn-vs-fail call is delegated to
+ * `classifyComponentDrift` so it is doctor's exact distinction, not a re-derivation.
+ */
+export declare function reconcileInstalledTuple(_projectDir: string, options?: ReconcileOptions): Promise<UpgradeReconciliation>;
+export interface NpmCommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type NpmCommandRunner = (args: string[]) => NpmCommandResult;
+export interface UpgradePlan {
+    proceed: boolean;
+    targetCliVersion: string | null;
+    reason: string;
+}
+/**
+ * FR4 ownership split, decided once so the CLI command stays thin: the npm half
+ * is executed only when the CLI itself can move forward — `upgrade-available`,
+ * or `incompatible` with the CLI genuinely behind the published version. An
+ * `incompatible` tuple whose CLI is not behind cannot be fixed by upgrading the
+ * CLI (the plugin half must move); apply prints the prescription instead of
+ * mutating. `aligned`/`unknown` never mutate.
+ */
+export declare function planCliUpgrade(reconciliation: UpgradeReconciliation): UpgradePlan;
+/**
+ * FR8 — "what's new, honestly." Return the changelog bullets between two
+ * `## <version>` headers: everything after `## <newVersion>` and before
+ * `## <oldVersion>` (the changelog is newest-first, so the new version sits
+ * above the old one). Only real list items in that window are returned, each
+ * verbatim from the file. When the window or its entries are missing — an
+ * unreleased target, a CHANGELOG the package does not ship, a shifted file, no
+ * bullets — the result is empty, and the caller says so rather than inventing a
+ * summary. If the old header is absent, the window is bounded at the next
+ * version header so a summary can never reach back past the target's section.
+ */
+export declare function summarizeChangelogBetween(oldVersion: string, newVersion: string): string[];
+/**
+ * FR4's manifest-refresh guarantee: the marketplace add/refresh command is
+ * printed FIRST — "without which the installer reinstalls the stale version." A
+ * stable sort keeps every other operation in the order
+ * `inspectClaudePluginIntegration` produced, and each is rendered by
+ * `formatClaudePluginOperationCommand` (the same argv an apply would run), so
+ * the prescription can never drift from what would actually execute. This is a
+ * pure formatter — it prints the plugin half, it never runs it.
+ */
+export declare function prescribePluginHalfCommands(operations: ClaudePluginOperation[]): string[];
+/** One migration's outcome as the injected registry runner reports it (T-006). */
+export interface MigrationRunResult {
+    id: string;
+    applied: boolean;
+    alreadyApplied: boolean;
+    failure?: string;
+}
+/**
+ * FR7's migration registry, injected rather than imported so this service owns
+ * only the call site and result field (the registry lives in
+ * `migration-registry.ts`). Called with the pre-upgrade and verified
+ * post-upgrade versions so a migration runs only when the upgrade crosses its
+ * version. `runPendingMigrations` satisfies this shape structurally.
+ */
+export type MigrationRunner = (fromVersion: string, toVersion: string, ctx: {
+    projectDir: string;
+}) => Promise<MigrationRunResult[]>;
+export interface ExecuteCliHalfUpgradeInput {
+    projectDir: string;
+    targetCliVersion: string;
+    /** Injectable npm runner; defaults to the real (or `OPENPLANR_NPM_BIN`) npm. */
+    npmCommandRunner?: NpmCommandRunner;
+    /** Injectable `claude` runner for the prescription's inspection (hermetic tests). */
+    claudeCommandRunner?: ClaudeCommandRunner;
+    /**
+     * FR7 migration runner, run after the CLI half verifies. Omitted (no runner)
+     * means no migrations are attempted; the `apply` command injects the real
+     * registry's `runPendingMigrations`.
+     */
+    migrationRunner?: MigrationRunner;
+}
+export interface ExecuteCliHalfUpgradeResult {
+    ok: boolean;
+    cliUpgraded: boolean;
+    installedVersion: string;
+    restoredTo?: string;
+    changelogBullets: string[];
+    pluginHalfCommands: string[];
+    /** Per-migration results for every registered migration this upgrade crossed. */
+    migrations: MigrationRunResult[];
+    failure?: {
+        step: 'npm-install' | 'verify' | 'changelog' | 'migration';
+        message: string;
+    };
+}
+/**
+ * FR4/FR8/FR9. Execute the one half the CLI owns — a global npm install — and
+ * prescribe (never execute) the plugin half.
+ *
+ * FR9's atomicity is enforced by verify-after-write: the previously installed
+ * version is captured *before* any mutation as the restorable backup, and after
+ * a zero-exit install the on-disk version is re-read. A clean exit that did not
+ * land the target is the decisive case the spec names — it triggers an automatic
+ * reinstall of the captured previous version and reports exactly what was
+ * restored, so a partially-upgraded install can never report success. `ok` is
+ * `false` whenever an owned step fails, even when npm itself exited zero.
+ */
+export declare function executeCliHalfUpgrade(input: ExecuteCliHalfUpgradeInput): Promise<ExecuteCliHalfUpgradeResult>;
+//# sourceMappingURL=upgrade-service.d.ts.map

package/dist/services/upgrade-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-service.d.ts","sourceRoot":"","sources":["../../src/services/upgrade-service.ts"],"names":[],"mappings":"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"}