@reticlehq/init 3.2.0 → 3.4.0

package/dist/plan/plan.js

@@ -3,23 +3,25 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { Framework, UiLibrary, installCommand, installCommandParts, } from '../detect/detect.js';
+import { Framework, UiLibrary, installCommand, installCommandParts } from '../detect/detect.js';
 import { installFailureHint } from '../diagnose/install-hint.js';
 import { installRetries } from '../diagnose/install-retries.js';
-import { claudeAddCommand, mcpManual } from '../register/mcp.js';
-import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, McpClient, } from '../register/mcp-clients.js';
+import { claudeAddCommand, claudeProjectMcpJson, mcpManual } from '../register/mcp.js';
+import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, CLAUDE_PROJECT_CONFIG, CLAUDE_PROJECT_SPEC, McpClient, } from '../register/mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from '../register/slash-command.js';
 import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, markedBlock, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from '../project/agent-rules.js';
-import { cspStep } from './plan-framework.js';
+import { cspStep } from '../diagnose/csp-step.js';
 import { frameworkSteps } from './framework-adapter.js';
 import { FRAMEWORK_ADAPTERS, RETICLE_BROWSER_SDK, RETICLE_REACT_KIT } from './framework-adapter.js';
-import { MCP_TARGET, StepStatus, } from './plan-types.js';
+import { MCP_TARGET, StepStatus } from './plan-types.js';
 export { DEPS_TARGET, MCP_TARGET, StepStatus, } from './plan-types.js';
 import { join } from 'node:path';
-import { reticleConfigContent } from '../patch/snippets.js';
+import { reticleConfigContent, usesReactKit } from '../patch/snippets.js';
 import { configWithInstallSource } from '../project/install-source-config.js';
-import { containerisedStep, uiLibraryStep, webGlCanvasStep, windowsMcpNoteStep } from './notices.js';
-import { existingConfigProblem, projectIdOf, RETICLE_CONFIG_FILE } from '../detect/existing-config.js';
+import { portMoveDetail, retargetConfigPort } from './port-steps.js';
+import { containerisedStep, uiLibraryStep, webGlCanvasStep, windowsMcpNoteStep, } from './notices.js';
+import { existingConfigProblem, projectIdOf, RETICLE_CONFIG_FILE, } from '../detect/existing-config.js';
+import { CLAUDE_SETTINGS_PATH, stopHookStep } from './stop-hook-step.js';
 // Re-exported: it moved to the module that reads it, and every existing importer says `plan.js`.
 export { RETICLE_CONFIG_FILE };
 /**
@@ -36,20 +38,6 @@ function pinnedPackages(packages, version) {
         return packages;
     return packages.map((p) => `${p}@${version}`);
 }
-/**
- * Does this codebase want the React kit, or the framework-neutral sensor?
- *
- * The kit is what adds component identity — component names and stacks — and it is worth having
- * wherever React or Preact is rendering (the adapter reaches Preact through `preact/compat`).
- * Everywhere else it is a package named `@reticlehq/react`, carrying `react` in its peer
- * dependencies, being installed into a codebase that has no React in it.
- *
- * UNKNOWN keeps the kit deliberately. Absence of evidence is not evidence of Vue, and guessing
- * "sensor" on no information silently drops component identity from apps that should have it.
- */
-function wantsReactKit(ui) {
-    return ui !== UiLibrary.VUE && ui !== UiLibrary.SVELTE;
-}
 /**
  * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
  *
@@ -59,7 +47,7 @@ function wantsReactKit(ui) {
  * right after `init` had detected the real UI library and said so on screen.
  */
 export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
-    const kit = wantsReactKit(uiLibrary) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
+    const kit = usesReactKit(uiLibrary, framework) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
     return FRAMEWORK_ADAPTERS[framework].packages(kit);
 }
 /**
@@ -104,40 +92,49 @@ function claudeMcpStep(input) {
  * parse is reported with a paste-able block rather than overwritten, and everything else is written.
  */
 function otherClientSteps(input) {
-    const steps = [];
-    for (const detected of input.detectedClients ?? []) {
-        const spec = clientSpec(detected.id);
-        const merged = mergeClientConfig(spec, detected.existing);
-        const title = `MCP server (${spec.label})`;
-        if (merged.status === ClientMergeStatus.ALREADY) {
-            steps.push({
-                title,
-                target: detected.configPath,
-                status: StepStatus.ALREADY,
-                detail: `reticle already registered with ${spec.label}`,
-            });
-            continue;
-        }
-        if (merged.status === ClientMergeStatus.MANUAL) {
-            // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
-            // end the same way: say so, and hand over the exact block.
-            steps.push({
-                title,
-                target: detected.configPath,
-                status: StepStatus.MANUAL,
-                detail: `add this to ${detected.configPath} by hand:\n${clientSnippet(spec)}`,
-            });
-            continue;
-        }
-        steps.push({
+    return (input.detectedClients ?? []).map((detected) => clientStep(clientSpec(detected.id), detected.configPath, detected.existing));
+}
+/** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
+function clientStep(spec, configPath, existing) {
+    const merged = mergeClientConfig(spec, existing);
+    const title = `MCP server (${spec.label})`;
+    if (merged.status === ClientMergeStatus.ALREADY) {
+        return {
             title,
-            target: detected.configPath,
-            status: StepStatus.APPLY,
-            detail: `register reticle with ${spec.label}`,
-            write: { path: detected.configPath, content: merged.content },
-        });
+            target: configPath,
+            status: StepStatus.ALREADY,
+            detail: `reticle already registered with ${spec.label}`,
+        };
     }
-    return steps;
+    if (merged.status === ClientMergeStatus.MANUAL) {
+        // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
+        // end the same way: say so, and hand over the exact block.
+        return {
+            title,
+            target: configPath,
+            status: StepStatus.MANUAL,
+            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec)}`,
+        };
+    }
+    return {
+        title,
+        target: configPath,
+        status: StepStatus.APPLY,
+        detail: `register reticle with ${spec.label}`,
+        write: { path: configPath, content: merged.content },
+    };
+}
+/**
+ * Claude Code's project `.mcp.json`, written only when `init` runs inside Claude Code with no CLI on
+ * PATH (a VS Code extension session). There the reporter had to write this file by hand (#1071,
+ * #1078); anywhere else a `.mcp.json` is a file in somebody's repo for a client they may not use, so
+ * they get the notice instead.
+ */
+function claudeProjectStep(input) {
+    if (input.claudeCli || true !== input.insideClaudeCode)
+        return null;
+    const path = agentFile(input, CLAUDE_PROJECT_CONFIG);
+    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null);
 }
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
@@ -157,7 +154,12 @@ function mcpSteps(input) {
     // Claude and Cursor first (they have their own registration paths), then every other detected
     // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
     // how a user ends up with Reticle in the editor they were not using.
-    const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
+    const claudeProject = claudeProjectStep(input);
+    const steps = [
+        ...stepsForAgents(input, (a) => a.mcpStep),
+        ...(null === claudeProject ? [] : [claudeProject]),
+        ...otherClientSteps(input),
+    ];
     if (0 === steps.length) {
         // No agent detected. mcpManual already carries the Windows cmd fallback — do not append it again.
         return [
@@ -169,6 +171,32 @@ function mcpSteps(input) {
             },
         ];
     }
+    /*
+     * Claude Code never leaves the plan without a word (#1071).
+     *
+     * It is the only client detected by CLI-on-PATH rather than by its config, so inside a Claude Code
+     * VS Code extension session — where `claude` is not on PATH — it reads as absent while the user is
+     * sitting in it. `claudeMcpStep` then returned null, and the manual fallback below only fires when
+     * NO agent at all was found. With Gemini and Codex present, Claude Code vanished from the plan
+     * entirely and nothing said so. A step that disappears is exactly what the install gate's baseline
+     * diff exists to catch, and the plan is the one artifact a person reads to learn what init did.
+     *
+     * Only when something else WAS found. With nothing found, the generic note below already says how
+     * to register, so nothing has silently vanished — and leaving that path untouched keeps every
+     * pristine scaffold in the install baseline reading exactly as it did.
+     */
+    if (!input.claudeCli && null === claudeProject && steps.length > 0) {
+        steps.push({
+            title: CLAUDE_MCP_TITLE,
+            target: MCP_TARGET,
+            // NOTICE, not MANUAL. Nothing here FAILED and the reader may not use Claude Code at all, so
+            // this is something to know rather than work owed — and the install gate asserts zero `⚠`,
+            // which would turn an informational line into a gate failure on any machine that happens to
+            // have another agent's config. A notice prints in full exactly like a manual step.
+            status: StepStatus.NOTICE,
+            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson()}`,
+        });
+    }
     const windowsNote = windowsMcpNoteStep(input);
     if (windowsNote !== null)
         steps.push(windowsNote);
@@ -415,10 +443,51 @@ function agentRuleSteps(input) {
  * with nothing naming a version. Pinning turns that into this loud failure, which is the better
  * trade — but only if the message says what to do about it.
  */
+/**
+ * Is this package already declared at the version we would pin?
+ *
+ * The caret is the point. `npm i -D pkg@3.2.0` WRITES `^3.2.0`, so on every later run the pinned
+ * `3.2.0` failed a string comparison against the range npm had just created, and init re-installed
+ * for ever. Only the two forms a package manager writes by itself are read - an exact version, and
+ * `^`/`~` over that same version.
+ *
+ * Everything else installs. A false "already" leaves somebody with no SDK and an install that
+ * claims to have run; a redundant install only costs time, so the unreadable cases go the safe way.
+ */
+function alreadyDeclared(declared, pinned) {
+    if (declared === undefined)
+        return false;
+    if (pinned === undefined || 0 === pinned.length)
+        return true;
+    return declared === pinned || `^${pinned}` === declared || `~${pinned}` === declared;
+}
 function installStep(input) {
     const pm = input.detection.packageManager;
+    // `Detection.packageManagerCommand` (see `preflight.ts`, #1149). Falling back to `pm` covers every
+    // caller that never went through preflight (tests, and any future one).
+    const pmCommand = input.detection.packageManagerCommand ?? pm;
     const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
-    const command = installCommand(pm, packages);
+    const command = installCommand(pm, packages, pmCommand);
+    /*
+     * A re-run over an already-wired project does NO dependency work.
+     *
+     * Reported from the field: `init` on an instrumented npm-workspaces project ran a pnpm dependency
+     * migration, which moved the existing `node_modules` aside and broke the dev server. Whatever
+     * manager gets chosen, the redundant install is the step that touches the tree — so the fix that
+     * matters is not running one that nothing needs. `init` is documented as idempotent; this is the
+     * step that was not.
+     */
+    const declared = input.detection.dependencies ?? {};
+    const version = input.options.sdkVersion;
+    const names = frameworkPackages(input.detection.framework, input.detection.uiLibrary);
+    if (names.length > 0 && names.every((n) => alreadyDeclared(declared[n], version))) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.ALREADY,
+            detail: `${names.join(', ')} already declared${version === undefined || 0 === version.length ? '' : ` at ${version}`}`,
+        };
+    }
     if (!input.options.install) {
         return {
             title: 'Install dependencies',
@@ -427,7 +496,7 @@ function installStep(input) {
             detail: command,
         };
     }
-    const parts = installCommandParts(pm, packages);
+    const parts = installCommandParts(pm, packages, [], pmCommand);
     return {
         title: 'Install dependencies',
         target: 'package.json',
@@ -436,9 +505,9 @@ function installStep(input) {
         exec: {
             command: parts.command,
             args: parts.args,
-            fallback: `${command}\n\n${installFailureHint(pm)}`,
+            fallback: `${command}\n\n${installFailureHint(pm, pmCommand)}`,
         },
-        retries: installRetries(pm, packages, frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion),
+        retries: installRetries(pm, packages, frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion, pmCommand),
     };
 }
 const RETICLE_CONFIG_TITLE = 'Reticle config';
@@ -513,9 +582,9 @@ function agentRootConfigStep(input, content) {
         },
     ];
 }
-function reticleConfigStep(input, content) {
+function reticleConfigStep(input, content, onDisk, movedFrom) {
     if (true === input.reticleConfigExists) {
-        const problem = existingConfigProblem(input.reticleConfigSource);
+        const problem = existingConfigProblem(onDisk);
         if (problem !== undefined) {
             // `ℹ`, not `·`: the step is done and something about the result still stops things working,
             // which is the one mark that says "there is something here to read".
@@ -528,14 +597,17 @@ function reticleConfigStep(input, content) {
         }
         // The one thing a re-run can still learn: which channel the user actually arrived through.
         // See configWithInstallSource — it only ever ADDS a field that is absent.
-        const backfilled = configWithInstallSource(input.reticleConfigSource, input.installSource);
-        if (backfilled !== undefined) {
+        const backfilled = configWithInstallSource(onDisk, input.installSource);
+        if (backfilled !== undefined || movedFrom !== undefined) {
+            const port = input.options.port;
             return {
                 title: RETICLE_CONFIG_TITLE,
                 target: RETICLE_CONFIG_FILE,
                 status: StepStatus.APPLY,
-                detail: 'record which install route this project came through',
-                write: { path: RETICLE_CONFIG_FILE, content: backfilled },
+                detail: movedFrom !== undefined && port !== undefined
+                    ? portMoveDetail(movedFrom, port)
+                    : 'record which install route this project came through',
+                write: { path: RETICLE_CONFIG_FILE, content: backfilled ?? onDisk ?? content },
             };
         }
         return {
@@ -557,16 +629,27 @@ function reticleConfigStep(input, content) {
  * The project config, in every directory that has to read it: the app's, and — after a redirect —
  * the one the agent runs from. One content string for both, so they cannot disagree; an existing
  * app-side config wins over a freshly derived one, or a re-run would copy a DIFFERENT identity up.
+ *
+ * Except its port, when a re-run asked for a different one: the daemon is about to start on the
+ * requested port, and a config still naming the old one is half of a split brain (see
+ * port-steps.ts). Only the port moves; the identity stays the one already on disk.
  */
 function reticleConfigSteps(input) {
     const existing = input.reticleConfigSource;
-    const content = true === input.reticleConfigExists && null !== existing && existing !== undefined
+    const onDisk = true === input.reticleConfigExists && null !== existing && existing !== undefined
         ? existing
-        : reticleConfigContent(input.detection.framework, input.options.port, input.options.projectId, 
+        : undefined;
+    const moved = onDisk === undefined ? null : retargetConfigPort(onDisk, input.options.port);
+    const content = moved?.code ??
+        onDisk ??
+        reticleConfigContent(input.detection.framework, input.options.port, input.options.projectId, 
         // Only when it is actually known. Writing `unknown` would be indistinguishable from a
         // config written before this field existed, and the two mean different things.
         input.installSource);
-    return [reticleConfigStep(input, content), ...agentRootConfigStep(input, content)];
+    return [
+        reticleConfigStep(input, content, moved?.code ?? existing, moved?.from),
+        ...agentRootConfigStep(input, content),
+    ];
 }
 export function buildPlan(input) {
     const steps = [
@@ -574,6 +657,9 @@ export function buildPlan(input) {
         ...mcpSteps(input),
         ...agentRuleSteps(input),
         ...slashCommandSteps(input),
+        ...(true === input.hooks
+            ? [stopHookStep(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent)]
+            : []),
         ...uiLibraryStep(input),
         ...webGlCanvasStep(input),
         installStep(input),

package/dist/plan/port-steps.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Moving a project that `init` already wired onto a different bridge port.
+ *
+ * Re-running `init --port 4689` over a project wired at 4688 used to be a silent no-op that
+ * reported success: every step read "already", nothing was rewritten, setup started the daemon on
+ * 4689, and the page kept dialling 4688 — "never dialled the bridge", with every file green. Each
+ * of those files had an "exists → done" check that never looked at the port inside it.
+ *
+ * So the port is compared wherever `init` wrote one, and rewritten IN PLACE: the rest of each file
+ * is the user's (registered stores, their own plugins), so only the number moves. With no `--port`
+ * on the re-run there is nothing requested to converge on, and every file is left exactly as it is —
+ * a re-run without the flag must not quietly reset a project to the default port.
+ */
+import { type Step } from './plan-types.js';
+/** A rewritten source, and the port it was moved off (for the "port A → B" line). */
+export interface Retargeted {
+    code: string;
+    from: number;
+}
+/** The one line both rewrites print, so every file reports a move the same way. */
+export declare function portMoveDetail(from: number, to: number): string;
+/**
+ * Rewrite every port `init` baked into a generated source file, or null when none differs.
+ *
+ * Covers the two shapes `init` writes: the bridge URL literal (Next's component, the SvelteKit hook,
+ * the Nuxt plugin) and the plugin option (`reticle({ port })` in a Vite config). A Vite config with
+ * a bare `reticle()` is null: the plugin reads the port from `.reticle.json`, which moves with it.
+ */
+export declare function retargetPort(source: string, to: number | undefined): Retargeted | null;
+/**
+ * The same, for `.reticle.json`: the `port` field set to the requested one, every other field kept.
+ *
+ * An absent `port` means the default, so moving onto the default REMOVES the field rather than
+ * writing `4400` — the same shape a fresh install writes (see `reticleConfigContent`). Unreadable
+ * JSON is null: `existingConfigProblem` already reports it, and rewriting a file we cannot parse
+ * would drop whatever the user meant by it.
+ */
+export declare function retargetConfigPort(source: string, to: number | undefined): Retargeted | null;
+/**
+ * The step for a file `init` already wrote, once a re-run's `--port` has been compared with it.
+ *
+ * Every "file exists" branch used to return ALREADY without reading the port inside the file; this is
+ * the one place that turns the rewrite above into a step.
+ */
+export declare function alreadyOrMovedPort(already: Step, source: string | null | undefined, port: number | undefined): Step;

package/dist/plan/port-steps.js

@@ -0,0 +1,119 @@
+/**
+ * Moving a project that `init` already wired onto a different bridge port.
+ *
+ * Re-running `init --port 4689` over a project wired at 4688 used to be a silent no-op that
+ * reported success: every step read "already", nothing was rewritten, setup started the daemon on
+ * 4689, and the page kept dialling 4688 — "never dialled the bridge", with every file green. Each
+ * of those files had an "exists → done" check that never looked at the port inside it.
+ *
+ * So the port is compared wherever `init` wrote one, and rewritten IN PLACE: the rest of each file
+ * is the user's (registered stores, their own plugins), so only the number moves. With no `--port`
+ * on the re-run there is nothing requested to converge on, and every file is left exactly as it is —
+ * a re-run without the flag must not quietly reset a project to the default port.
+ */
+import { RETICLE_CLIENT_HOST, RETICLE_DEFAULT_PORT, RETICLE_WS_PATH, bridgeWsUrl, } from '@reticlehq/core';
+import { StepStatus } from './plan-types.js';
+/** The bridge URL every generated connect bakes (`bridgeWsUrl`), with its port captured. */
+const BRIDGE_URL = new RegExp(`(ws://${RETICLE_CLIENT_HOST}:)(\\d+)(${RETICLE_WS_PATH})\\b`, 'g');
+/** The opening of the connect call every generated connect file makes. */
+const CONNECT_CALL = 'reticle.connect({';
+/** `port: <n>` inside the options object of a `reticle({ … })` plugin call. */
+const PLUGIN_PORT = /(\breticle\(\s*\{[^}]*?\bport\s*:\s*)(\d+)/g;
+/** The one line both rewrites print, so every file reports a move the same way. */
+export function portMoveDetail(from, to) {
+    return `port ${String(from)} → ${String(to)}`;
+}
+/**
+ * Rewrite every port `init` baked into a generated source file, or null when none differs.
+ *
+ * Covers the two shapes `init` writes: the bridge URL literal (Next's component, the SvelteKit hook,
+ * the Nuxt plugin) and the plugin option (`reticle({ port })` in a Vite config). A Vite config with
+ * a bare `reticle()` is null: the plugin reads the port from `.reticle.json`, which moves with it.
+ */
+export function retargetPort(source, to) {
+    if (to === undefined)
+        return null;
+    let from;
+    let baked = false;
+    /** True when this literal is the one to move; remembers the first port moved off. */
+    const moves = (port) => {
+        baked = true;
+        const current = Number(port);
+        if (current === to)
+            return false;
+        from ??= current;
+        return true;
+    };
+    const target = String(to);
+    const code = source
+        .replace(BRIDGE_URL, (match, head, port, tail) => moves(port) ? `${head}${target}${tail}` : match)
+        .replace(PLUGIN_PORT, (match, head, port) => moves(port) ? `${head}${target}` : match);
+    if (from !== undefined)
+        return { code, from };
+    // A port was baked and it is already the requested one: nothing to do. Falling through here used
+    // to insert a SECOND `url:` beside the one already there on every same-port re-run —
+    // `TS1117: An object literal cannot have multiple properties with the same name`, and the app's
+    // build failed.
+    if (baked)
+        return null;
+    // A default-port install bakes no URL at all — the SDK's default IS 4400 — so there is nothing to
+    // rewrite, and the page would go on dialling 4400. Give the connect call the URL it now needs.
+    if (RETICLE_DEFAULT_PORT === to || !source.includes(CONNECT_CALL))
+        return null;
+    return {
+        code: source.replace(CONNECT_CALL, `${CONNECT_CALL} url: '${bridgeWsUrl(to)}',`),
+        from: RETICLE_DEFAULT_PORT,
+    };
+}
+/**
+ * The same, for `.reticle.json`: the `port` field set to the requested one, every other field kept.
+ *
+ * An absent `port` means the default, so moving onto the default REMOVES the field rather than
+ * writing `4400` — the same shape a fresh install writes (see `reticleConfigContent`). Unreadable
+ * JSON is null: `existingConfigProblem` already reports it, and rewriting a file we cannot parse
+ * would drop whatever the user meant by it.
+ */
+export function retargetConfigPort(source, to) {
+    if (to === undefined)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+        return null;
+    const fields = { ...parsed };
+    const declared = fields['port'];
+    const from = 'number' === typeof declared ? declared : RETICLE_DEFAULT_PORT;
+    if (from === to)
+        return null;
+    if (RETICLE_DEFAULT_PORT === to)
+        delete fields['port'];
+    else
+        fields['port'] = to;
+    return { code: `${JSON.stringify(fields, null, 2)}\n`, from };
+}
+/**
+ * The step for a file `init` already wrote, once a re-run's `--port` has been compared with it.
+ *
+ * Every "file exists" branch used to return ALREADY without reading the port inside the file; this is
+ * the one place that turns the rewrite above into a step.
+ */
+export function alreadyOrMovedPort(already, source, port) {
+    if (StepStatus.ALREADY !== already.status)
+        return already;
+    if ('string' !== typeof source || port === undefined)
+        return already;
+    const moved = retargetPort(source, port);
+    if (null === moved)
+        return already;
+    return {
+        ...already,
+        status: StepStatus.APPLY,
+        detail: portMoveDetail(moved.from, port),
+        write: { path: already.target, content: moved.code },
+    };
+}

package/dist/plan/preflight.d.ts

@@ -16,8 +16,22 @@ export interface PreflightIo {
     /** Runs a command quietly for a yes/no check; true on exit code 0. */
     probe(command: string, args: readonly string[]): boolean;
 }
+/** What `preflight` decided: run through `command`, or refuse with this message. */
+export type PreflightResult = {
+    refusal: string;
+    command?: undefined;
+} | {
+    refusal?: undefined;
+    command: string;
+};
 /**
- * The refusal to print, or undefined when this machine can run the install.
+ * The one place this run decides whether — and how — it can invoke the package manager.
+ *
+ * Resolves the invocation ONCE: earlier, `preflightRefusal` probed the machine to decide whether to
+ * refuse, and callers that got past it probed AGAIN, separately, to learn what the resolved command
+ * actually was — two subprocesses (the bare binary, then corepack) doing the same test twice on every
+ * ordinary run. This is the single call site: it returns either the command every later step should
+ * invoke, or the refusal to print, never both and never neither.
  *
  * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
  * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
@@ -25,6 +39,6 @@ export interface PreflightIo {
  * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
  * with no pnpm, which the install gate proves must succeed.
  */
-export declare function preflightRefusal(io: PreflightIo, packageManager: string, options?: {
+export declare function preflight(io: PreflightIo, packageManager: string, options?: {
     alreadyServed?: boolean;
-}): string | undefined;
+}): PreflightResult;

package/dist/plan/preflight.js

@@ -11,8 +11,38 @@
  * npm ships with node, so refusing for its absence would refuse on a machine that is fine.
  */
 const ALWAYS_PRESENT = 'npm';
+/** The one program allowed to run a package manager it cannot find on PATH itself. */
+const COREPACK = 'corepack';
 /**
- * The refusal to print, or undefined when this machine can run the install.
+ * The prefix this run can actually invoke `packageManager` through, or undefined when neither the
+ * bare binary nor corepack can.
+ *
+ * Reported from the field (#1149): a Windows machine with a corepack-managed pnpm — no `pnpm` on
+ * PATH, only `corepack`, which resolves it from the project's `packageManager` field — failed the
+ * bare `pnpm --version` probe and refused, even though `corepack pnpm --version` succeeds and every
+ * later step could have run through it. `corepack <pm>` is not a fallback guess: corepack shipped
+ * with node and does exactly what the bare binary would have, so a machine that can only reach it
+ * that way is not missing the tool, only the shim. Every other place in this codebase that needs to
+ * talk about a corepack-only machine (`Detection.packageManagerCommand` and its readers) points back
+ * here rather than re-explaining it.
+ */
+function resolvedPmCommand(io, packageManager) {
+    if (ALWAYS_PRESENT === packageManager)
+        return packageManager;
+    if (io.probe(packageManager, ['--version']))
+        return packageManager;
+    if (io.probe(COREPACK, [packageManager, '--version']))
+        return `${COREPACK} ${packageManager}`;
+    return undefined;
+}
+/**
+ * The one place this run decides whether — and how — it can invoke the package manager.
+ *
+ * Resolves the invocation ONCE: earlier, `preflightRefusal` probed the machine to decide whether to
+ * refuse, and callers that got past it probed AGAIN, separately, to learn what the resolved command
+ * actually was — two subprocesses (the bare binary, then corepack) doing the same test twice on every
+ * ordinary run. This is the single call site: it returns either the command every later step should
+ * invoke, or the refusal to print, never both and never neither.
  *
  * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
  * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
@@ -20,33 +50,33 @@ const ALWAYS_PRESENT = 'npm';
  * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
  * with no pnpm, which the install gate proves must succeed.
  */
-export function preflightRefusal(io, packageManager, options = {}) {
+export function preflight(io, packageManager, options = {}) {
     // First: on a read-only checkout nothing else matters, and one access check is cheaper and
     // quieter than spawning a subprocess to discover the same thing.
     if (!io.canWrite()) {
-        return (`${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
-            'a capabilities file). Fix the permissions, or run init from a checkout you own.');
+        return {
+            refusal: `${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
+                'a capabilities file). Fix the permissions, or run init from a checkout you own.',
+        };
     }
+    const resolved = resolvedPmCommand(io, packageManager);
+    if (resolved !== undefined)
+        return { command: resolved };
     // What the project resolves to says nothing about what the machine HAS, and a project committed to
     // pnpm on an npm-only box is an ordinary Monday.
     //
-    // `alreadyServed` is `--url`, and skipping the check for it is the message keeping its own promise.
-    // This guard exists for the DEV SERVER — to stop `spawn pnpm ENOENT` surfacing inside "the dev
-    // server exited" — and `--url` says the app is already up, so init starts nothing and the failure
-    // it protects against cannot happen. Reported from the field as a circle: the refusal named `--url`
-    // as the way past it while `--url` was being passed, because the flag was parsed and then never
-    // handed to init at all.
-    //
-    // The dependency install can still fail without the package manager. That is one step reporting ⚠,
-    // which is what a step that cannot complete is for, and is a better outcome than writing nothing:
-    // the config, the connect module and `.reticle.json` all land, and the user is told the one thing
-    // left to do rather than being sent to install a package manager they were trying to avoid.
-    if (true !== options.alreadyServed &&
-        ALWAYS_PRESENT !== packageManager &&
-        !io.probe(packageManager, ['--version'])) {
-        return (`this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
-            `installed on this machine. Install it (npm i -g ${packageManager}, or corepack enable), or ` +
-            'pass --url with the address the app already serves.');
-    }
-    return undefined;
+    // `alreadyServed` is `--url`. This guard exists for the DEV SERVER — to stop `spawn pnpm ENOENT`
+    // surfacing inside "the dev server exited" — and `--url` says the app is already up, so init starts
+    // nothing and the failure it protects against cannot happen. The dependency install can still fail
+    // without the package manager (one step reporting ⚠, a better outcome than writing nothing), so a
+    // command is still returned here — the bare name, since neither probe above found one — rather than
+    // refusing a run that `--url` already made safe.
+    if (true === options.alreadyServed)
+        return { command: packageManager };
+    return {
+        refusal: `this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
+            `installed on this machine — and corepack ${packageManager} could not run it either. Install ` +
+            `it (npm i -g ${packageManager}), or enable corepack for it (corepack enable — on Windows this ` +
+            'needs an elevated shell), or pass --url with the address the app already serves.',
+    };
 }

package/dist/plan/stop-hook-step.d.ts

@@ -0,0 +1,4 @@
+import { type Step } from './plan-types.js';
+export declare const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+export declare const STOP_HOOK_COMMAND = "npx @reticlehq/server report --hook";
+export declare function stopHookStep(path: string, existing: string | null | undefined): Step;