@reticlehq/init 3.3.0 → 3.4.0

package/dist/plan/plan-vite.js

@@ -0,0 +1,256 @@
+/**
+ * The Vite half of the plan: the `reticle()` plugin in a Vite config, and the dev module that
+ * carries `registerCapabilities` / `registerStore`.
+ *
+ * Split out of `plan-framework.ts`, which had grown to the edge of the line cap. It is its own
+ * module because every Vite-based stack (plain Vite, SvelteKit, React Router, Remix, TanStack
+ * Start, the Electron renderers) composes these steps, while the rest of `plan-framework.ts` is one
+ * builder per framework that has its own files to write.
+ */
+import { newViteConfig, patchViteConfig, VitePatchKind, VITE_IMPORT } from '../patch/vite-config.js';
+import { viteManual, viteDevModuleFile, VITE_DEV_MODULE_PATH } from '../patch/snippets.js';
+import { hasOptOut, OPT_OUT_MARKER } from '../detect/declared/init-opt-out.js';
+import { Framework } from '../detect/detect.js';
+import { StepStatus } from './plan-types.js';
+import { StepTitle } from './connect-steps.js';
+import { alreadyOrMovedPort } from './port-steps.js';
+/** What adding `reticle()` to a Vite config buys, which differs by framework. */
+export const VITE_PLUGIN_DETAIL = {
+    /** A plain Vite app gets both halves from the plugin. */
+    VITE: 'add reticle() to plugins (also injects connect())',
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    SVELTEKIT: 'add reticle({ inject: false }) to plugins (stamps data-reticle-source in .svelte components; the client hook connects)',
+    /**
+     * React Router framework mode renders through its own request handler, so the plugin's HTML
+     * injection never fires and connect() comes from the client entry instead. The plugin is still
+     * required for the same reason it is under SvelteKit: without it every verdict on the app comes
+     * back with no file:line at all.
+     */
+    REACT_ROUTER: 'add reticle() to plugins (stamps data-reticle-source in .tsx components)',
+    /**
+     * TanStack Start SSRs its own HTML, so the plugin's HTML injection never fires and connect()
+     * comes from a client effect instead. `inject: false` is load-bearing honesty: leaving the
+     * default would keep reporting "also injects connect()" for a transform that never runs.
+     * The plugin is still required for the same reason it is under SvelteKit: without it every
+     * verdict on the app comes back with no file:line at all.
+     */
+    TANSTACK_START: 'add reticle({ inject: false }) to plugins (stamps data-reticle-source; Start SSRs its own HTML so connect() cannot come from the plugin)',
+};
+const CAPABILITIES_TITLE = StepTitle.CAPABILITIES;
+/**
+ * The one step `init` genuinely cannot finish, addressed to the AGENT reading this report.
+ *
+ * It used to read "Capabilities are empty until you edit that file" and describe the consequence to
+ * a human — homework, in a report a human mostly does not read, naming no file to open and no thing
+ * to look for. The agent that ran `init` is right there, has the codebase, and can finish this in
+ * the same minute; what it needed was the specific instruction, not the rationale.
+ *
+ * What is left is exactly what could not be PROVEN from source: which atoms/actor/queryClient an
+ * adapter-wrapped store should be built from, and which elements matter enough to name. `init`
+ * emits nothing it cannot prove, because a wrong import here throws on every dev page load — worse
+ * than an empty file.
+ */
+const CAPABILITIES_TODO_TITLE = StepTitle.CAPABILITIES_TODO;
+export function capabilitiesTodo(path, stores) {
+    return (`This app's state lives in a library nothing in the running app points at, so it is the one ` +
+        `thing Reticle cannot find for itself — reticle_state will not see it until you say where it ` +
+        `is.\n` +
+        `Do this now, before driving anything:\n` +
+        `  1. In ${path}, uncomment the suggested line and complete it: ${stores.join('; ')}.\n` +
+        `  2. Prove it: drive one flow and check reticle_state returns your key. An empty state read ` +
+        `means the line is still not doing anything, whatever else went green.`);
+}
+/**
+ * The dev module carrying `registerCapabilities` / `registerStore`.
+ *
+ * Without it every app came up `hasCapabilities: false` with a `reticle_state` holding nothing but
+ * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
+ * only when absent, because it is the one generated file a user is expected to EDIT.
+ */
+/**
+ * Is there state left that ONLY the app can hand over?
+ *
+ * This used to ask a much bigger question — "does the generated file register anything at all?" —
+ * and fired on almost every install, because almost every install generated a file whose testids
+ * and stores were both empty. The answer was homework: go read the source, uncomment a line, add
+ * data-testid attributes, then drive to prove it. Several turns, on every onboarding.
+ *
+ * Two of those three are no longer anyone's homework. Testids are read from the live DOM, and a
+ * store passed through a React context provider (Redux, TanStack Query) is discovered and
+ * registered on the first commit. What is left is the genuinely unreachable case: a module-scope
+ * store, or one needing an argument only the source supplies — Zustand, Jotai atoms, an XState
+ * actor. Nothing in the running app points at those, so the notice still has to fire, and it now
+ * fires ONLY there.
+ *
+ * `wired` are stores init resolved and wrote a live `registerStore` call for. Hints are not
+ * registrations: they land in the file as a commented line, and counting one as a registration
+ * silences the notice whose whole purpose is to say "act on the hint".
+ */
+export function needsManualStore(hints, wired) {
+    return hints.length > 0 && 0 === wired.length;
+}
+export function capabilitiesStep(input, path = VITE_DEV_MODULE_PATH) {
+    if (true === input.viteDevModuleExists) {
+        return [
+            {
+                title: CAPABILITIES_TITLE,
+                target: path,
+                status: StepStatus.ALREADY,
+                detail: 'file exists, left alone, it is yours to edit',
+            },
+        ];
+    }
+    const testids = input.testids ?? [];
+    const stores = input.storeHints ?? [];
+    const wired = input.foundStores ?? [];
+    // Testids no longer need counting here. They are read from the live DOM at announce time, so a
+    // number printed at install time would be a stale claim about a codebase that is about to change —
+    // which is exactly what "no data-testid values yet" used to be on an app whose testids arrive with
+    // a lazy route.
+    const found = 'testids read from the live DOM';
+    // A store we found and WIRED is a registration, so the notice must not fire. A store HINT is not:
+    // `stores` holds suggestions, written into the file as a commented line of the form
+    // `// import your store, then: registerStore(...)`. Counting a suggestion as a registration let
+    // the hint silence the notice whose entire job is to say "act on the hint".
+    //
+    // Measured against a real product UI (rowy — 70+ deps, jotai, a whole src/atoms tree): init
+    // detected jotai, offered one commented line, emitted NO notice, and wrote
+    // `registerCapabilities({ testids: [], signals: [], stores: [] })`. So `hasCapabilities` stayed
+    // false, `reticle_state` was empty forever, and the install gate reported "connected: 1,
+    // manual ⚠: none". Every check green, state observability zero.
+    //
+    // jotai is still exactly that case. A Redux or TanStack app is not, any more: its store rides a
+    // context provider and the React adapter registers it on the first commit, so `storeHints` no
+    // longer names either one and this notice no longer fires for them.
+    const nothingToRegister = needsManualStore(stores, wired);
+    return [
+        {
+            title: CAPABILITIES_TITLE,
+            target: path,
+            status: StepStatus.APPLY,
+            detail: `${found}; ${wired.length > 0
+                ? `registered ${wired.map((s) => `'${s.key}'`).join(', ')} from your source`
+                : stores.length > 0
+                    ? `store: uncomment the ${String(stores.length)} suggested line(s)`
+                    : 'no state library detected'}`,
+            write: {
+                path,
+                content: viteDevModuleFile(testids, stores, wired, input.detection.uiLibrary, input.detection.framework),
+            },
+            dependsOnInstall: true,
+        },
+        // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
+        // stores: [] })` registers nothing, so `hasCapabilities` stays false — correctly — and the ✓
+        // above reads as if the feature is on. Reported as exactly that confusion: "hasCapabilities false
+        // on every session while init said ✓ Capabilities + store".
+        //
+        // Beside the write rather than replacing it, for two reasons: only APPLY steps are written
+        // (run.ts), and SKILL.md tells the reader to skip ✓ lines — so a caveat carried on the ✓ is a
+        // caveat nobody reads.
+        ...(nothingToRegister
+            ? [
+                {
+                    title: CAPABILITIES_TODO_TITLE,
+                    target: path,
+                    status: StepStatus.NOTICE,
+                    detail: capabilitiesTodo(path, stores),
+                },
+            ]
+            : []),
+    ];
+}
+export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE, inject = true) {
+    // Capabilities are independent of whether the config needed patching. Attaching them to the APPLY
+    // branch meant a re-run on an already-wired app silently never created the module.
+    return [...viteConfigSteps(input, detail, inject), ...capabilitiesStep(input)];
+}
+function viteConfigSteps(input, detail, inject = true) {
+    const cfg = input.viteConfig;
+    const port = input.options.port;
+    // Stamp `data-reticle-source` unless this app renders through a non-DOM React reconciler, where a
+    // lowercase JSX tag is not an element and the stamp crashes the app at commit time. See
+    // `Detection.customReconciler`.
+    const stampSource = true !== input.detection?.customReconciler;
+    // An explicit "not here" is not an invitation. `init` runs unattended in a repo it has just met,
+    // and it was reported adding the plugin to an app whose config said Reticle was deliberately
+    // excluded. A NOTICE rather than a ⚠: opting out is a decision, not something to go and fix.
+    if (cfg !== null && hasOptOut(cfg.source)) {
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.NOTICE,
+                detail: `left alone: this config carries ${OPT_OUT_MARKER}. Remove that marker to instrument this app.`,
+            },
+        ];
+    }
+    // Plain Vite runs happily with no config file (`npm create vite`'s vanilla template has none), so
+    // make one. Only there: a Vite-based framework's missing config also lost the framework's own
+    // plugin, and a file carrying ours alone would not boot the app.
+    const plainVite = Framework.VITE === input.detection.framework;
+    if (null === cfg) {
+        if (!plainVite) {
+            return [
+                {
+                    title: StepTitle.VITE_PLUGIN,
+                    target: 'vite.config',
+                    status: StepStatus.MANUAL,
+                    detail: viteManual(port, input.detection.uiLibrary, inject, stampSource),
+                },
+            ];
+        }
+        const path = input.detection.typescript ? 'vite.config.ts' : 'vite.config.mjs';
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: path,
+                status: StepStatus.APPLY,
+                detail,
+                write: {
+                    path,
+                    content: newViteConfig(port, true === input.captureBodies, inject, stampSource),
+                    expect: [VITE_IMPORT, 'reticle('],
+                },
+                dependsOnInstall: true,
+            },
+        ];
+    }
+    const patch = patchViteConfig(cfg.source, port, true === input.captureBodies, inject, stampSource);
+    if (patch.kind === VitePatchKind.ALREADY) {
+        return [
+            alreadyOrMovedPort({
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.ALREADY,
+                detail: 'reticle() already in plugins',
+            }, cfg.source, port),
+        ];
+    }
+    if (patch.kind === VitePatchKind.MANUAL) {
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.MANUAL,
+                detail: `${patch.reason}\n\n${viteManual(port, input.detection.uiLibrary, inject, stampSource)}`,
+            },
+        ];
+    }
+    return [
+        {
+            title: StepTitle.VITE_PLUGIN,
+            target: cfg.path,
+            status: StepStatus.APPLY,
+            detail,
+            // Both halves, because either alone is a config that does not wire: the import without the
+            // call leaves `plugins` untouched, and the call without the import does not build.
+            write: { path: cfg.path, content: patch.code, expect: [VITE_IMPORT, 'reticle('] },
+            dependsOnInstall: true,
+        },
+    ];
+}

package/dist/plan/plan.js

@@ -3,23 +3,24 @@
  * 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, 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 };
@@ -37,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.
  *
@@ -60,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);
 }
 /**
@@ -476,8 +463,11 @@ function alreadyDeclared(declared, pinned) {
 }
 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.
      *
@@ -506,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',
@@ -515,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';
@@ -592,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".
@@ -607,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 {
@@ -636,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 = [

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;