@reticlehq/server 2.12.0 → 2.13.1

package/dist/init/mcp.js

@@ -55,7 +55,7 @@ const WINDOWS_SHELL_C = '/c';
  *
  * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
  * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
- * shape is now repaired on re-run rather than reported "already registered" (see cursor.ts).
+ * shape is now repaired on re-run rather than reported "already registered" (see mcp-clients.ts).
  */
 export function npxServerArgs() {
     return [RETICLE_PACKAGE, MCP_SUBCOMMAND];

package/dist/init/node-io.js

@@ -3,7 +3,7 @@
  * `runInit` stays testable with an in-memory IO. Prints to stdout — `init` is a one-shot CLI
  * command, not the MCP stdio transport.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, } from 'node:fs';
 import { NodePlatform } from '../platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
@@ -95,6 +95,16 @@ export function buildNodeIo(cwd) {
             const result = spawnSync(command, shellSafe(args), { cwd, stdio: 'inherit', ...shellOpt() });
             return 0 === result.status;
         },
+        /** One access check, rather than discovering it as an EACCES stack four phases later. */
+        canWrite() {
+            try {
+                accessSync(cwd, constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
         probe(command, args) {
             // Quiet yes/no check (CLI availability, existing registration). Never throws.
             const result = spawnSync(command, shellSafe(args), { cwd, stdio: 'ignore', ...shellOpt() });

package/dist/init/plan-framework.js

@@ -6,13 +6,14 @@
 import { bridgeWsUrl } from '@reticlehq/core';
 import { patchViteConfig, VitePatchKind } from './vite-config.js';
 import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js';
-import { patchAstroConfig, patchAstroLayout } from './astro-patch.js';
-import { CRA_DEV_MODULE_IMPORT, CRA_DEV_MODULE_PATH, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craEnvPatch, craImportPatch, } from './cra.js';
+import { ASTRO_ENV_DTS_PATH, patchAstroConfig, patchAstroEnvDts, patchAstroLayout, } from './astro-patch.js';
+import { CRA_DEV_MODULE_IMPORT, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craDevModulePath, craEnvPatch, craImportPatch, } from './cra.js';
 import { PatchKind } from './patch-kind.js';
 import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, nuxtManual, NUXT_PLUGIN_PATH, } from './snippets.js';
-import { RETICLE_CONFIG_FILE, StepStatus } from './plan.js';
+import { StepStatus } from './plan.js';
 import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { CSP_STEP_TITLE, cspPlanProblem } from './csp-check.js';
+import { CSP_STEP_TITLE } from './csp-check.js';
+import { diagnoseWebCsp } from './csp-doctor.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. */
@@ -41,20 +42,13 @@ const CAPABILITIES_TITLE = 'Capabilities + store';
  */
 const CAPABILITIES_TODO_TITLE = 'AGENT: finish the capabilities file';
 function capabilitiesTodo(path, stores) {
-    const store = stores.length > 0
-        ? `This app depends on a state library init cannot wire on its own (it needs an argument only ` +
-            `reading the code can supply). Uncomment the suggested line in that file and complete it: ` +
-            `${stores.join('; ')}.`
-        : `No state library was detected. If the app holds state somewhere init cannot see, register ` +
-            `it — see node_modules/@reticlehq/server/docs/usage.md.`;
-    return (`${path} was written but registers nothing, so \`hasCapabilities\` stays false and reticle_state ` +
-        `has nothing to read.\n` +
+    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. ${store}\n` +
-        `  2. Open the app's main flow and add \`testids\` for the elements it touches (or add ` +
-        `data-testid attributes where there are none).\n` +
-        `  3. Prove it: drive one flow and check reticle_state returns your keys. An empty state read ` +
-        `means this file is still not doing anything, whatever else went green.`);
+        `  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`.
@@ -64,20 +58,26 @@ function capabilitiesTodo(path, stores) {
  * only when absent, because it is the one generated file a user is expected to EDIT.
  */
 /**
- * Does the generated dev module actually REGISTER anything?
+ * Is there state left that ONLY the app can hand over?
  *
- * Shared by the Vite and Next paths because it is one question about one generated call, and the
- * two answered it differently for as long as only Vite asked: `capabilitiesStep` was called from
- * `viteSteps` and nowhere else, so a Next app whose store can only be SUGGESTED wrote
- * `registerCapabilities({ testids: [], stores: [] })`, registered nothing, and said nothing.
- * Measured on a real Next + mobx app: five steps, every one a checkmark, no capabilities line.
+ * 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".
  */
-function registersNothing(testids, wired) {
-    return 0 === testids.length && 0 === wired.length;
+function needsManualStore(hints, wired) {
+    return hints.length > 0 && 0 === wired.length;
 }
 function capabilitiesStep(input) {
     if (true === input.viteDevModuleExists) {
@@ -93,13 +93,15 @@ function capabilitiesStep(input) {
     const testids = input.testids ?? [];
     const stores = input.storeHints ?? [];
     const wired = input.foundStores ?? [];
-    const found = testids.length > 0
-        ? `${String(testids.length)} data-testid values`
-        : 'no data-testid values yet';
-    // A store we found and WIRED is a registration, so the "registers nothing" 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".
+    // 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
@@ -107,10 +109,10 @@ function capabilitiesStep(input) {
     // false, `reticle_state` was empty forever, and the install gate reported "connected: 1,
     // manual ⚠: none". Every check green, state observability zero.
     //
-    // This is the common case rather than an edge one: a library whose registration needs an argument
-    // only reading the source supplies — jotai atoms, an XState actor, a TanStack queryClient — is
-    // exactly what init leaves commented.
-    const nothingToRegister = registersNothing(testids, wired);
+    // 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,
@@ -165,7 +167,7 @@ function viteConfigSteps(input, detail) {
             },
         ];
     }
-    const patch = patchViteConfig(cfg.source, port);
+    const patch = patchViteConfig(cfg.source, port, true === input.captureBodies);
     if (patch.kind === VitePatchKind.ALREADY) {
         return [
             {
@@ -294,7 +296,7 @@ export function nextSteps(input) {
     // The same question the Vite path asks. Skipped when the module already exists: its contents are
     // the user's, and re-nagging about a file we did not write is noise.
     const nextTodo = true !== input.nextReticleDevExists &&
-        registersNothing(input.testids ?? [], input.nextFoundStores ?? [])
+        needsManualStore(input.storeHints ?? [], input.nextFoundStores ?? [])
         ? [
             {
                 title: CAPABILITIES_TODO_TITLE,
@@ -327,15 +329,19 @@ export function nextSteps(input) {
  */
 export function craSteps(input) {
     const entry = input.craEntry ?? null;
+    // Match the project language the same way Next does (#675): a JS CRA app cannot resolve `.ts`.
+    const modulePath = craDevModulePath(input.detection.typescript);
     const steps = [
         {
             title: 'Reticle connect module',
-            target: CRA_DEV_MODULE_PATH,
+            target: modulePath,
             status: StepStatus.APPLY,
             detail: 'create the dev-only connect (CRA cannot inject through public/index.html)',
             write: {
-                path: CRA_DEV_MODULE_PATH,
-                content: craDevModuleFile(input.options.port, input.options.projectId),
+                path: modulePath,
+                content: craDevModuleFile(input.options.port, input.options.projectId, {
+                    typescript: input.detection.typescript,
+                }),
             },
             dependsOnInstall: true,
         },
@@ -500,9 +506,14 @@ export function astroSteps(input) {
             },
         ];
     }
+    const envPatch = patchAstroEnvDts(input.astroEnvDts ?? null);
     return [
         patchStep('Astro config (token + build target)', config.path, configPatch, 'inline the pairing token and raise build.target to es2022', manualWithLayout),
         patchStep('Connect snippet (Astro)', layout.path, layoutPatch, 'add the dev-only connect <script> before </body>', manualWithLayout),
+        // Declares the Vite define names so `astro check` (create-astro's default build) can see them
+        // (#677). Independent of the two halves above: even an ALREADY config/layout still needs this
+        // when the env file was never written.
+        patchStep('Astro env types (Vite defines)', ASTRO_ENV_DTS_PATH, envPatch, 'declare __RETICLE_TOKEN__ / __RETICLE_ROOT__ for astro check', manualWithLayout),
     ];
 }
 /**
@@ -515,15 +526,40 @@ export function astroSteps(input) {
  * warning and a fix.
  */
 export function cspStep(input) {
-    const problem = cspPlanProblem([input.nextConfigSource, input.nextLayout?.source], input.options.port ?? RETICLE_DEFAULT_PORT);
-    if (problem === undefined)
+    // Reads the SAME list `reticle doctor` reads. It used to read a hand-written pair —
+    // `[nextConfigSource, nextLayout?.source]` — while csp-doctor.ts already carried the full set
+    // including `index.html`, which is where every Vite and Electron app declares its policy. So the
+    // command you run BEFORE anything works checked less than the one you run after it has failed.
+    //
+    // Measured on MarkText, a production Electron editor: its renderer sets `default-src 'self'` with
+    // no `connect-src`, the browser blocked the bridge WebSocket, and `init` printed a clean plan. The
+    // daemon cannot see a dial that never left the page, so nothing anywhere said why — and the check
+    // that would have said it was sitting one import away.
+    // The pre-read Next sources are folded in ON TOP of the shared list, not replaced by it: init
+    // resolves `nextConfigFile` across more spellings than CSP_FILES names (`.mts`, for one), and a
+    // layout is found by search rather than by a fixed path. Two sources of the same truth is the
+    // problem being fixed here — one of them being a SUPERSET is not.
+    const extra = {
+        ...(input.nextConfigFile !== null && input.nextConfigFile !== undefined
+            ? { [input.nextConfigFile]: input.nextConfigSource ?? undefined }
+            : {}),
+        ...(input.nextLayout ? { [input.nextLayout.path]: input.nextLayout.source } : {}),
+    };
+    const read = (file) => extra[file] ?? input.cspSources?.[file];
+    const findings = diagnoseWebCsp(read, input.options.port ?? RETICLE_DEFAULT_PORT, [
+        ...Object.keys(extra),
+    ]);
+    const first = findings[0];
+    if (first === undefined)
         return [];
     return [
         {
             title: CSP_STEP_TITLE,
-            target: input.nextConfigFile ?? RETICLE_CONFIG_FILE,
+            target: first.file,
             status: StepStatus.NOTICE,
-            detail: problem,
+            // `problem` already ends with the text to paste; `fix` is the same sentence for callers that
+            // want it on its own (doctor renders them separately). Printing both said it twice.
+            detail: first.problem,
         },
     ];
 }

package/dist/init/plan.d.ts

@@ -5,7 +5,7 @@
  */
 import { Framework, UiLibrary, type Detection } from './detect.js';
 import type { FoundStore } from './capabilities.js';
-import { type McpClient } from './mcp-clients.js';
+import { McpClient } from './mcp-clients.js';
 /**
  * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
  *
@@ -85,20 +85,28 @@ export interface Plan {
 }
 export interface PlanInput {
     detection: Detection;
+    /**
+     * Write `captureNetworkBodies: true` into the app's config. Off unless the caller asked (#705).
+     *
+     * Optional so every existing caller and test keeps the safe default without naming it — the one
+     * direction a default about somebody else's data should be wrong in.
+     */
+    captureBodies?: boolean | undefined;
+    /**
+     * The CSP-bearing files this project actually has, keyed by path — read once in `gatherPlanInput`.
+     *
+     * Pre-read rather than given a reader, because `PlanInput` is the pure input to a pure planner and
+     * handing it an io would let any later step reach the disk from inside `buildPlan`.
+     */
+    cspSources?: Readonly<Record<string, string | undefined>> | undefined;
     /** Whether the `claude` CLI is installed (so we can register the MCP server globally). */
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     mcpExists: boolean;
-    /** Whether Cursor is installed for this user (its global config dir exists). */
-    cursorPresent: boolean;
     /** `process.platform`. Injected so this module stays pure. Windows is the only branch. */
     platform?: string;
     /** Whether THIS project has a .cursor/ directory — the signal that Cursor works on this repo. */
     cursorProjectPresent?: boolean | undefined;
-    /** Current ~/.cursor/mcp.json content, or null if absent. */
-    cursorConfig: string | null;
-    /** Absolute path of ~/.cursor/mcp.json (the write target). */
-    cursorConfigPath: string;
     /**
      * Every OTHER MCP client detected on this machine, with its config path and current content.
      *
@@ -131,6 +139,11 @@ export interface PlanInput {
         path: string;
         source: string;
     } | null | undefined;
+    /**
+     * Existing `src/env.d.ts` content, when present — where the Vite-define ambient declarations go
+     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677).
+     */
+    astroEnvDts?: string | null | undefined;
     /** Discovered Next config filename (e.g. 'next.config.mjs'), or null. */
     nextConfigFile: string | null;
     /** Source of that Next config, so the export can be wrapped in withReticle. */

package/dist/init/plan.js

@@ -4,16 +4,16 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, PackageManager, UiLibrary, installCommand, installCommandParts, } from './detect.js';
+import { installFailureHint } from './install-hint.js';
 import { claudeAddCommand, mcpManual, mcpWindowsNote } from './mcp.js';
 import { NodePlatform } from '../platform.js';
-import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
-import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
+import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, McpClient, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
 import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
 import { viteSteps, nextSteps, craSteps, svelteKitSteps, nuxtSteps, astroSteps, cspStep, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
 import { join } from 'node:path';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
-import { declaredInstallSource } from '../telemetry/install-source.js';
+import { configWithInstallSource, declaredInstallSource } from '../telemetry/install-source.js';
 import { devServerPortWarning, isLikelyDevServerPort } from '../cli/cli-port.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
@@ -122,7 +122,6 @@ function agentFile(input, relPath) {
     return root === undefined || 0 === root.length ? relPath : join(root, relPath);
 }
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
-const CURSOR_MCP_TITLE = 'MCP server (Cursor, global)';
 function claudeMcpStep(input) {
     if (!input.claudeCli)
         return null;
@@ -143,34 +142,6 @@ function claudeMcpStep(input) {
         exec: { command: cmd.command, args: cmd.args, fallback: cmd.display },
     };
 }
-function cursorMcpStep(input) {
-    if (!input.cursorPresent)
-        return null;
-    const r = mergeCursorConfig(input.cursorConfig);
-    if (r.status === CursorMergeStatus.ALREADY) {
-        return {
-            title: CURSOR_MCP_TITLE,
-            target: input.cursorConfigPath,
-            status: StepStatus.ALREADY,
-            detail: 'reticle already in Cursor global config',
-        };
-    }
-    if (r.status === CursorMergeStatus.MANUAL) {
-        return {
-            title: CURSOR_MCP_TITLE,
-            target: input.cursorConfigPath,
-            status: StepStatus.MANUAL,
-            detail: `couldn't parse ${input.cursorConfigPath} — add this server by hand:\n  "reticle": ${JSON.stringify(cursorServerEntry())}`,
-        };
-    }
-    return {
-        title: CURSOR_MCP_TITLE,
-        target: input.cursorConfigPath,
-        status: StepStatus.APPLY,
-        detail: 'register reticle in Cursor global config',
-        write: { path: input.cursorConfigPath, content: r.content },
-    };
-}
 /**
  * One step per OTHER detected client.
  *
@@ -304,7 +275,8 @@ function claudeCommandStep(input) {
     return commandStepFor(agentFile(input, CLAUDE_COMMAND_PATH), input.claudeCli, input.claudeCommandContent);
 }
 function cursorCommandStep(input) {
-    const present = true === input.cursorProjectPresent || (input.cursorPresent && !input.claudeCli);
+    const cursorGlobal = (input.detectedClients ?? []).some((c) => c.id === McpClient.CURSOR);
+    const present = true === input.cursorProjectPresent || (cursorGlobal && !input.claudeCli);
     return commandStepFor(agentFile(input, CURSOR_COMMAND_PATH), present, input.cursorCommandContent);
 }
 const AGENT_RULE_TITLE = 'Agent verification rule';
@@ -339,7 +311,8 @@ function claudeRuleStep(input) {
  * committed into their repo. (Global MCP registration is different: it is global, and stays.)
  */
 function cursorRuleStep(input) {
-    if (!input.cursorPresent)
+    const cursorGlobal = (input.detectedClients ?? []).some((c) => c.id === McpClient.CURSOR);
+    if (!cursorGlobal && true !== input.cursorProjectPresent)
         return null;
     if (input.cursorProjectPresent !== true && input.claudeCli)
         return null;
@@ -389,14 +362,13 @@ const AGENT_INTEGRATIONS = [
     },
     {
         id: AgentId.CURSOR,
-        mcpStep: cursorMcpStep,
         ruleStep: cursorRuleStep,
         commandStep: cursorCommandStep,
     },
 ];
 /** The steps one surface contributes across every known agent, in registry order. */
 function stepsForAgents(input, surface) {
-    return AGENT_INTEGRATIONS.map((a) => surface(a)(input)).filter((s) => s !== null);
+    return AGENT_INTEGRATIONS.map((a) => surface(a)?.(input) ?? null).filter((s) => s !== null);
 }
 /** The `/reticle` command file for every agent that has a command surface and is present here. */
 function slashCommandSteps(input) {
@@ -503,15 +475,6 @@ function unpinnedRetryNote(version, pm) {
         `installed instead. That may not match the daemon — if the agent reports protocol errors, check ` +
         `\`versionSkew\` in reticle_sessions.${remedy}`);
 }
-function installFailureHint(pm) {
-    if (pm !== PackageManager.PNPM)
-        return 'If the version was refused, install the SDK yourself.';
-    return ('If pnpm reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, its minimumReleaseAge setting is holding ' +
-        'this release back. Either wait out the window, or allow these packages explicitly:\n' +
-        '  pnpm config set minimumReleaseAgeExclude "@reticlehq/*"\n' +
-        'Do NOT drop the version pin — unpinned, pnpm installs an older SDK against a newer daemon, and ' +
-        'that mismatch surfaces as a -32000 with nothing naming a version.');
-}
 function installStep(input) {
     const pm = input.detection.packageManager;
     const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
@@ -629,6 +592,18 @@ function reticleConfigStep(input, content) {
                 detail: problem,
             };
         }
+        // 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, declaredInstallSource());
+        if (backfilled !== undefined) {
+            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 },
+            };
+        }
         return {
             title: RETICLE_CONFIG_TITLE,
             target: RETICLE_CONFIG_FILE,

package/dist/init/preflight.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/** The parts of the environment preflight reads, so the rules are testable without a filesystem. */
+export interface PreflightIo {
+    /** Absolute path of the directory init is running in. */
+    cwd(): string;
+    /** Can this process write into the project root. */
+    canWrite(): boolean;
+    /** Runs a command quietly for a yes/no check; true on exit code 0. */
+    probe(command: string, args: readonly string[]): boolean;
+}
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `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
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * 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): string | undefined;

package/dist/init/preflight.js

@@ -0,0 +1,38 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/**
+ * npm ships with node, so refusing for its absence would refuse on a machine that is fine.
+ */
+const ALWAYS_PRESENT = 'npm';
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `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
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * 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) {
+    // 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.');
+    }
+    // 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.
+    if (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;
+}

package/dist/init/run.d.ts

@@ -18,6 +18,8 @@ import type { InitOutcome } from '@reticlehq/core';
  */
 export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;
 export interface InitOptions {
+    /** `--capture-bodies`: write `captureNetworkBodies: true` into the app's config. Off by default (#705). */
+    captureBodies?: boolean | undefined;
     cwd: string;
     port: number | undefined;
     mcp: boolean;
@@ -47,6 +49,13 @@ export interface InitOptions {
      * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
      */
     deferOutcome?: boolean;
+    /**
+     * Whether the caller carries on into booting the app and driving it.
+     *
+     * Only affects the closing hint, which otherwise tells the reader to restart their dev server and
+     * drive a flow by hand — three lines before this command does both.
+     */
+    continuesToRuntime?: boolean;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -70,25 +79,39 @@ export interface InitIo {
     exec(command: string, args: readonly string[]): boolean;
     /** Runs a subprocess quietly (no stdio) for a yes/no check; returns true on exit code 0. */
     probe(command: string, args: readonly string[]): boolean;
+    /** Can this process write into the project root — see preflight.ts. */
+    canWrite(): boolean;
     print(line: string): void;
 }
+/**
+ * What a run established, for a caller that means to continue where init stopped.
+ *
+ * Everything here was already computed and then thrown away. That was fine while init only wrote
+ * files: nobody downstream existed. A caller that goes on to boot the app needs the same answers,
+ * and re-deriving them is how two parts of one command end up disagreeing about which directory
+ * they are in — which is not hypothetical, because a monorepo redirect re-enters `runInit` with a
+ * different cwd and the outer caller never learns that it happened.
+ */
+export interface InitContext {
+    /** The directory actually wired, AFTER any monorepo redirect. */
+    readonly appDir: string;
+    readonly framework: string;
+    readonly packageManager: string;
+    /** The project's own dev command, when its scripts name one. Never composed. */
+    readonly devCommand?: string | undefined;
+    /** Set when init redirected into a workspace app, naming the one it chose. */
+    readonly redirectedTo?: string | undefined;
+}
 export interface InitResult {
     ok: boolean;
     applied: number;
     manual: number;
+    /** What this run established. Absent only where init exits before establishing anything. */
+    context?: InitContext;
     /**
      * The event body this run would report, handed to the caller instead of emitted, when
      * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
      */
     outcome?: InitOutcome;
 }
-/**
- * App directories under a workspace root.
- *
- * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
- * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
- * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
- * it knows it is in a workspace; this is the matching walk DOWN.
- */
-export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;