@reticlehq/server 2.12.0 → 2.13.0

package/dist/init/astro-patch.js

@@ -270,3 +270,31 @@ export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.
         code: `${source.slice(0, at)}${astroConnectScript(port, projectId, uiLibrary)}${source.slice(at)}`,
     };
 }
+/** Where Astro keeps ambient types — `create-astro` ships this file. */
+export const ASTRO_ENV_DTS_PATH = 'src/env.d.ts';
+/**
+ * The declarations `astro check` needs for the Vite `define` names (#677).
+ *
+ * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
+ * absent when the pairing token file is missing.
+ */
+export const ASTRO_ENV_DTS_DECLARES = 'declare const __RETICLE_TOKEN__: string | undefined;\n' +
+    'declare const __RETICLE_ROOT__: string | undefined;\n';
+/** Present once either declare is in the file — both are written together. */
+const ENV_DTS_MARKER = '__RETICLE_TOKEN__';
+/**
+ * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ *
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
+ * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ */
+export function patchAstroEnvDts(existing) {
+    if (null !== existing && existing.includes(ENV_DTS_MARKER)) {
+        return { kind: PatchKind.ALREADY };
+    }
+    if (null === existing || '' === existing.trim()) {
+        return { kind: PatchKind.APPLY, code: ASTRO_ENV_DTS_DECLARES };
+    }
+    const base = existing.endsWith('\n') ? existing : `${existing}\n`;
+    return { kind: PatchKind.APPLY, code: `${base}${ASTRO_ENV_DTS_DECLARES}` };
+}

package/dist/init/capabilities.d.ts

@@ -13,7 +13,10 @@
 export declare const MAX_TESTIDS = 60;
 /** Every distinct `data-testid` literal in the given sources, in first-seen order. */
 export declare function scanTestids(sources: readonly string[]): string[];
-/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+/**
+ * The store libraries this app depends on AND the running app cannot reveal on its own, as
+ * ready-to-uncomment registration lines.
+ */
 export declare function storeHints(deps: ReadonlySet<string>): string[];
 /** A store instance we found in the app's own source, with everything needed to import and register it. */
 export interface FoundStore {

package/dist/init/capabilities.js

@@ -49,9 +49,29 @@ const STORE_LIBRARIES = [
     ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
     ['svelte', "registerStore('cart', svelteStore(cartStore))"],
 ];
-/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+/**
+ * Libraries that hand their store to React through a context provider, and therefore need no hint.
+ *
+ * `<Provider store>` and `<QueryClientProvider client>` put the store instance in the fiber tree as
+ * a prop, so the React adapter finds and registers it on the first commit — see `auto-stores.ts` in
+ * `@reticlehq/react`. Offering a commented `registerStore` line for these was asking someone to do
+ * by hand, and be nagged about, work that is already done by the time they read the report.
+ *
+ * Everything absent from this set is module-scope (Zustand, Valtio, a MobX singleton) or needs an
+ * argument only the source supplies (Jotai atoms, an XState actor). Nothing in the running app
+ * points at those, so they still need the app to hand them over, and the hint still earns its place.
+ */
+const AUTO_DISCOVERED_DEPS = new Set([
+    '@tanstack/react-query',
+    '@reduxjs/toolkit',
+    'redux',
+]);
+/**
+ * The store libraries this app depends on AND the running app cannot reveal on its own, as
+ * ready-to-uncomment registration lines.
+ */
 export function storeHints(deps) {
-    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep)).map(([, hint]) => hint);
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep) && !AUTO_DISCOVERED_DEPS.has(dep)).map(([, hint]) => hint);
 }
 /**
  * Store factories whose EXPORTED result is the store instance itself — the form `registerStore`

package/dist/init/confirm.d.ts

@@ -19,17 +19,29 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
- *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
- *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
- *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
- *    the ONE command that is outstanding and the one that proves it worked.
+ *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
+ *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
+ *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
+ *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
+ *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
+ *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
+ *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
+ *    it worked.
  */
 import { InitConfirmation } from '@reticlehq/core';
-import type { InitOutcome } from '@reticlehq/core';
+import type { DevServerEntry, InitOutcome } from '@reticlehq/core';
 export interface ConfirmDeps {
     /** Session ids connected right now, or null when nothing is listening on the bridge port. */
     listSessionIds: () => Promise<readonly string[] | null>;
+    /**
+     * The dev servers that have announced themselves, read at the END of the wait rather than the
+     * start: a dev server booting alongside `init` is the common case, and asking before it has
+     * finished listening would report the state we are trying to move away from.
+     *
+     * Optional so every existing construction of these deps — and any embedder's — keeps working and
+     * simply gets today's less specific message.
+     */
+    listDevServers?: () => readonly DevServerEntry[];
     now: () => number;
     sleep: (ms: number) => Promise<void>;
     windowMs?: number;
@@ -68,7 +80,19 @@ export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConf
  * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
  * up when the agent loads the tools — so it is a notice.
  */
-export declare function confirmationMessage(confirmation: InitConfirmation, port: number): string;
+/**
+ * Narrow "no app connected" using what the dev servers themselves announced.
+ *
+ * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
+ * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
+ * opened. An announced entry is proof the plugin is loaded in the process that is actually running
+ * — which means the config is right and it has already been restarted.
+ *
+ * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
+ * different fact; neither becomes more true because a dev server is up.
+ */
+export declare function sharpenWithDevServers(confirmation: InitConfirmation, running: readonly DevServerEntry[]): InitConfirmation;
+export declare function confirmationMessage(confirmation: InitConfirmation, port: number, running?: readonly DevServerEntry[]): string;
 /**
  * Finish `init` on evidence rather than on a write.
  *

package/dist/init/confirm.js

@@ -19,14 +19,21 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
- *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
- *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
- *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
- *    the ONE command that is outstanding and the one that proves it worked.
+ *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
+ *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
+ *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
+ *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
+ *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
+ *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
+ *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
+ *    it worked.
  */
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
+import { readDevServers } from '../daemon/dev-servers.js';
+import { devServersForProject } from '@reticlehq/core';
+import { readProjectId } from '../cli/cli-port.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 import { reportInitOutcome } from '../telemetry/init-telemetry.js';
 /**
  * How long a human is asked to wait.
@@ -78,7 +85,23 @@ const PROVE_COMMAND = '`npx @reticlehq/server status`';
  * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
  * up when the agent loads the tools — so it is a notice.
  */
-export function confirmationMessage(confirmation, port) {
+/**
+ * Narrow "no app connected" using what the dev servers themselves announced.
+ *
+ * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
+ * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
+ * opened. An announced entry is proof the plugin is loaded in the process that is actually running
+ * — which means the config is right and it has already been restarted.
+ *
+ * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
+ * different fact; neither becomes more true because a dev server is up.
+ */
+export function sharpenWithDevServers(confirmation, running) {
+    if (confirmation !== InitConfirmation.NO_SESSION)
+        return confirmation;
+    return 0 === running.length ? InitConfirmation.NO_SESSION : InitConfirmation.NO_PAGE;
+}
+export function confirmationMessage(confirmation, port, running = []) {
     if (confirmation === InitConfirmation.CONNECTED) {
         return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
             '      Ask your agent to drive a flow.');
@@ -89,6 +112,15 @@ export function confirmationMessage(confirmation, port) {
             '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
             `${PROVE_COMMAND} confirms the app.`);
     }
+    if (confirmation === InitConfirmation.NO_PAGE) {
+        // Deliberately never says "restart". The announcement is proof they already did — telling them
+        // again is how a correct instruction reads as the tool not knowing what is going on.
+        const where = running.map((s) => `        ${s.url}`).join('\n');
+        return ('  [⚠] your dev server has Reticle loaded, and no page has connected yet — so the only step ' +
+            'left is opening the app.\n' +
+            `      Open it in a browser:\n${where}\n` +
+            `      ${PROVE_COMMAND} then confirms it.`);
+    }
     return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
         'done.\n' +
         '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
@@ -142,13 +174,21 @@ export async function confirmInstall(result, io, deps, report = reportInitOutcom
     }
     io.print('');
     io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
-    const confirmation = await confirmAppConnected(deps);
-    io.print(confirmationMessage(confirmation, deps.port));
+    const observed = await confirmAppConnected(deps);
+    const running = deps.listDevServers?.() ?? [];
+    const confirmation = sharpenWithDevServers(observed, running);
+    io.print(confirmationMessage(confirmation, deps.port, running));
     report({ ...outcome, confirmation });
 }
 /** The real deps: the daemon's own status endpoint, and whether a human is watching. */
 export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
     return {
+        // Scoped to the project being set up. The registry is machine-wide, so unscoped it reported a
+        // sibling app's dev server as this one's — see devServersForProject.
+        listDevServers: () => devServersForProject(readDevServers(reticleStateHome()), {
+            projectId: readProjectId(process.cwd()),
+            root: process.cwd(),
+        }),
         listSessionIds: async () => {
             const payload = await fetchStatus(port);
             // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"

package/dist/init/cra.d.ts

@@ -12,9 +12,17 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
-/** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
 export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
-export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export declare function craDevModulePath(typescript: boolean): string;
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export declare const CRA_DEV_MODULE_PATH: string;
 export declare const CRA_ENV_PATH = ".env.development.local";
 export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
 /**
@@ -59,5 +67,13 @@ export declare const CRA_TOKEN_PER_MACHINE_NOTICE: string;
 export declare function craImportPatch(source: string): string | null;
 /** Set the token variable, or null when nothing needs to change. */
 export declare function craEnvPatch(existing: string | null, token: string, url?: string): string | null;
-/** The dev-only connect module imported from `src/index.tsx`. */
-export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;
+/** Options for the CRA connect module. */
+export interface CraDevModuleOptions {
+    /**
+     * When false, emit a `.js`-shaped body (no `export {}`). Default true for callers that predate
+     * the language branch.
+     */
+    typescript?: boolean;
+}
+/** The dev-only connect module imported from the app entry. */
+export declare function craDevModuleFile(port: number | undefined, projectId?: string, options?: CraDevModuleOptions): string;

package/dist/init/cra.js

@@ -14,9 +14,19 @@
  */
 import { bridgeWsUrl } from '@reticlehq/core';
 import { CLI } from './agent-rules.js';
-/** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
-export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export function craDevModulePath(typescript) {
+    return typescript ? 'src/reticle-dev.ts' : 'src/reticle-dev.js';
+}
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export const CRA_DEV_MODULE_PATH = craDevModulePath(true);
 export const CRA_ENV_PATH = '.env.development.local';
 export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
 /**
@@ -101,8 +111,9 @@ export function craEnvPatch(existing, token, url) {
     }
     return next === (existing ?? '') ? null : next;
 }
-/** The dev-only connect module imported from `src/index.tsx`. */
-export function craDevModuleFile(port, projectId) {
+/** The dev-only connect module imported from the app entry. */
+export function craDevModuleFile(port, projectId, options = {}) {
+    const typescript = false !== options.typescript;
     const fields = [];
     // `bridgeWsUrl`, not a hand-written string. This was the only client URL in the product spelling
     // the host as `127.0.0.1` while every other generator said `localhost` — same endpoint, but a
@@ -112,27 +123,56 @@ export function craDevModuleFile(port, projectId) {
         fields.push(`url: '${bridgeWsUrl(port)}'`);
     if (projectId !== undefined && projectId.length > 0)
         fields.push(`projectId: '${projectId}'`);
-    const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
+    // Multiline on purpose (#684): a single-line connect + console.error fails CRA boilerplate
+    // Prettier (printWidth 80) and the project's own lint blocks a clean install.
+    const connectFields = [
+        ...fields.map((f) => `      ${f},`),
+        '      ...(url.length > 0 ? { url } : {}),',
+        '      ...(token.length > 0 ? { token } : {}),',
+    ].join('\n');
+    // Split so every emitted line stays under a CRA boilerplate printWidth of 80 (#684). A single
+    // JSON.stringify of the whole note is ~290 characters and fails prettier-as-eslint on install.
+    // Chunks are joined with `+` in the emitted file; together they equal `[reticle] ${CRA_TOKEN_MISSING_NOTE}`.
+    const missingChunks = [
+        `[reticle] ${TOKEN_VAR} is not set, so Reticle `,
+        'cannot pair with the daemon. The pairing token is ',
+        `per-machine and ${CRA_ENV_PATH} is gitignored by `,
+        "CRA's template, so it does not survive a clone. Run ",
+        `\`${CLI} init\` in this project to write it for this `,
+        'machine.',
+    ].map((c) => JSON.stringify(c));
+    // Eight spaces match the indent inside `console.error(` below.
+    const missingExpr = missingChunks.join(' +\n        ');
+    // `export {}` is a TypeScript empty-module marker. A `.js` file with it is fine under Babel, but
+    // the workaround reporters used was to drop it when renaming to `.js` — keep the JS emit clean.
+    const trailer = typescript ? '\nexport {};\n' : '\n';
     return `// Dev-only: connect Reticle. Imported for its side effect from src/index.tsx.
 //
-// CRA's public/index.html is a static template the bundler never processes for modules, so the
-// connect cannot live there. The pairing token arrives through REACT_APP_RETICLE_TOKEN because
-// REACT_APP_* is the only thing CRA inlines into browser code.
+// CRA's public/index.html is a static template the bundler never processes for
+// modules, so the connect cannot live there. The pairing token arrives through
+// REACT_APP_RETICLE_TOKEN because REACT_APP_* is the only thing CRA inlines
+// into browser code.
 if (process.env.NODE_ENV === 'development') {
   void import('@reticlehq/react').then(({ reticle, install }) => {
     install();
     const token = process.env.${TOKEN_VAR} ?? '';
-    // Written by \`reticle init\` from the daemon that was live when it ran, and refreshed by
-    // re-running it. CRA gives us no hook to resolve this at dev-server start, so if the daemon
-    // moves, re-run \`reticle init\` rather than editing the url below.
+    // Written by \`reticle init\` from the daemon that was live when it ran, and
+    // refreshed by re-running it. CRA gives us no hook to resolve this at
+    // dev-server start, so if the daemon moves, re-run \`reticle init\` rather
+    // than editing the url below.
     const url = process.env.${URL_VAR} ?? '';
-    // Loud on purpose: without this the only symptom is the bridge's generic auth failure.
-    if (token.length === 0) console.error(${JSON.stringify(`[reticle] ${CRA_TOKEN_MISSING_NOTE}`)});
+    // Loud on purpose: without this the only symptom is the bridge's generic
+    // auth failure.
+    if (token.length === 0) {
+      console.error(
+        ${missingExpr},
+      );
+    }
     // Still attempt it — a bridge running without a token pairs fine.
-    reticle.connect({ ${inline}...(url.length > 0 ? { url } : {}), ...(token.length > 0 ? { token } : {}) });
+    reticle.connect({
+${connectFields}
+    });
   });
 }
-
-export {};
-`;
+${trailer}`;
 }

package/dist/init/csp-check.js

@@ -30,10 +30,10 @@ function bridgeOrigins(port) {
  * Matches to the end of the directive (`;`) or the end of the enclosing quoted string, which is how
  * these are written in both a Next `headers()` value and a `<meta content="...">`.
  */
-function connectSrcSources(text) {
+function directiveSources(text, directive) {
     // Stops at the directive separator or the closing double quote of the enclosing string. Single
     // quotes are NOT terminators: `'self'` is a source, not the end of the list.
-    const match = /connect-src([^;"]*)/i.exec(text);
+    const match = new RegExp(`${directive}([^;"]*)`, 'i').exec(text);
     const list = match?.[1];
     if (list === undefined)
         return undefined;
@@ -42,6 +42,21 @@ function connectSrcSources(text) {
         .map((source) => source.trim())
         .filter((source) => source.length > 0);
 }
+/**
+ * What this policy allows a WebSocket to reach — `connect-src`, or `default-src` when it is absent.
+ *
+ * The fallback is the CSP spec's, and leaving it out made the check blind to the commonest strict
+ * policy there is. MarkText, a production Electron editor, declares
+ * `default-src 'self'; script-src 'self'; …` with NO `connect-src`: its WebSockets are restricted to
+ * 'self', the bridge is blocked, and this returned "no problem" because it was looking for a
+ * directive that was not written. Every fetch-directive falls back to `default-src`; that is what
+ * `default` means, and it is why an author does not repeat themselves.
+ *
+ * Still undefined when NEITHER is present — a policy that constrains neither is not blocking us.
+ */
+function connectSrcSources(text) {
+    return directiveSources(text, 'connect-src') ?? directiveSources(text, 'default-src');
+}
 /**
  * The problem with this app's `connect-src`, or undefined if there is not one.
  *

package/dist/init/csp-doctor.d.ts

@@ -21,5 +21,12 @@ export interface CspDiagnosis {
     /** Exactly what to add — copy-pasteable, with the port actually in use. */
     fix: string;
 }
-export declare function diagnoseWebCsp(read: ReadFile, port: number): CspDiagnosis[];
+/**
+ * The places a Content-Security-Policy gets written in a JS app.
+ *
+ * Next config and middleware cover `headers()` and the edge-middleware style; the layouts and the
+ * plain `index.html` cover the `<meta http-equiv>` style. Both reported cases were in this list.
+ */
+export declare const CSP_FILES: readonly string[];
+export declare function diagnoseWebCsp(read: ReadFile, port: number, alsoCheck?: readonly string[]): CspDiagnosis[];
 export {};

package/dist/init/csp-doctor.js

@@ -18,7 +18,7 @@ import { cspConnectSrcProblem, devCspAddition } from './csp-check.js';
  * Next config and middleware cover `headers()` and the edge-middleware style; the layouts and the
  * plain `index.html` cover the `<meta http-equiv>` style. Both reported cases were in this list.
  */
-const CSP_FILES = [
+export const CSP_FILES = [
     'next.config.js',
     'next.config.mjs',
     'next.config.ts',
@@ -31,12 +31,17 @@ const CSP_FILES = [
     'pages/_document.js',
     'index.html',
     'public/index.html',
+    // Vite puts the entry HTML at the project root; electron-vite and Tauri put the RENDERER's one
+    // under src/. MarkText declares its policy in `src/renderer/index.html`, and a desktop app is the
+    // likeliest place to meet a strict CSP at all — Electron's own security guidance asks for one.
+    'src/index.html',
+    'src/renderer/index.html',
     'vercel.json',
     'netlify.toml',
 ];
-export function diagnoseWebCsp(read, port) {
+export function diagnoseWebCsp(read, port, alsoCheck = []) {
     const findings = [];
-    for (const file of CSP_FILES) {
+    for (const file of [...alsoCheck, ...CSP_FILES]) {
         const source = read(file);
         if (source === undefined)
             continue;

package/dist/init/dev-script.d.ts

@@ -14,6 +14,8 @@
  * which script, and whether to touch anything at all — and that is what wants testing. Spawning a
  * process is not.
  */
+/** Script names a JS project uses to run itself, in the order we would pick them. */
+export declare const DEV_SCRIPT_NAMES: readonly ["dev", "start", "serve"];
 export declare const DevScriptChoice: {
     /** Something already answers on the port. Use it; never replace a server the user is running. */
     readonly ALREADY_SERVING: "already-serving";
@@ -45,4 +47,4 @@ export declare function planDevScript(scripts: Readonly<Record<string, string>>,
  * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
  * read: this phrasing decides nothing, so it must never be able to break an install.
  */
-export declare function devCommandFrom(pkgRaw: string, packageManager: string): string | undefined;
+export declare function devCommandFrom(pkg: unknown, packageManager: string): string | undefined;

package/dist/init/dev-script.js

@@ -15,7 +15,8 @@
  * process is not.
  */
 /** Script names a JS project uses to run itself, in the order we would pick them. */
-const CANDIDATES = ['dev', 'start', 'serve'];
+export const DEV_SCRIPT_NAMES = ['dev', 'start', 'serve'];
+const CANDIDATES = DEV_SCRIPT_NAMES;
 export const DevScriptChoice = {
     /** Something already answers on the port. Use it; never replace a server the user is running. */
     ALREADY_SERVING: 'already-serving',
@@ -49,11 +50,13 @@ export function planDevScript(scripts, packageManager, serving) {
  * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
  * read: this phrasing decides nothing, so it must never be able to break an install.
  */
-export function devCommandFrom(pkgRaw, packageManager) {
+export function devCommandFrom(pkg, packageManager) {
     try {
-        const parsed = JSON.parse(pkgRaw);
-        const scripts = 'object' === typeof parsed && null !== parsed
-            ? (parsed.scripts ?? {})
+        // Takes the PARSED manifest. It used to take the raw string and parse it a fourth time — the
+        // caller now reads the file once, through a guard, so there is one place a malformed manifest
+        // can be noticed and it is not this one.
+        const scripts = 'object' === typeof pkg && null !== pkg
+            ? (pkg.scripts ?? {})
             : {};
         return planDevScript(scripts, packageManager, false).command;
     }

package/dist/init/format-generated.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Format a file `init` is about to write, using the project's own Prettier when it is installed.
+ *
+ * Reported from the field (#684): a clean CRA install failed the project's own lint because
+ * `src/reticle-dev.ts` was emitted as one long line. The project already had Prettier; init never
+ * asked it. Best-effort: resolve Prettier from the app (not from ours — we do not ship it), apply
+ * its config, and on any failure return the original content so init never fails because of a
+ * formatter. Sync only — `applyEffects` is sync, and Prettier 3's async `format` cannot join here.
+ */
+/** True when this write is a connect/dev module lint will treat as project source. */
+export declare function isGeneratedSourcePath(relPath: string): boolean;
+/**
+ * Format `content` for `relPath` under `projectRoot`, or return it unchanged.
+ *
+ * Only the sync Prettier API is used. Prettier 3's async `format` is skipped (returns the original)
+ * rather than holding init open on a promise `applyEffects` cannot await.
+ */
+export declare function formatGeneratedSource(content: string, relPath: string, projectRoot: string): string;

package/dist/init/format-generated.js

@@ -0,0 +1,39 @@
+/**
+ * Format a file `init` is about to write, using the project's own Prettier when it is installed.
+ *
+ * Reported from the field (#684): a clean CRA install failed the project's own lint because
+ * `src/reticle-dev.ts` was emitted as one long line. The project already had Prettier; init never
+ * asked it. Best-effort: resolve Prettier from the app (not from ours — we do not ship it), apply
+ * its config, and on any failure return the original content so init never fails because of a
+ * formatter. Sync only — `applyEffects` is sync, and Prettier 3's async `format` cannot join here.
+ */
+import { createRequire } from 'node:module';
+import { basename, join } from 'node:path';
+/** Basenames of full-file generators that a project's lint will see. */
+const GENERATED_SOURCE_NAMES = new Set(['reticle-dev.ts', 'reticle-dev.tsx', 'hooks.client.ts']);
+/** True when this write is a connect/dev module lint will treat as project source. */
+export function isGeneratedSourcePath(relPath) {
+    return GENERATED_SOURCE_NAMES.has(basename(relPath));
+}
+/**
+ * Format `content` for `relPath` under `projectRoot`, or return it unchanged.
+ *
+ * Only the sync Prettier API is used. Prettier 3's async `format` is skipped (returns the original)
+ * rather than holding init open on a promise `applyEffects` cannot await.
+ */
+export function formatGeneratedSource(content, relPath, projectRoot) {
+    if (!isGeneratedSourcePath(relPath))
+        return content;
+    try {
+        const require = createRequire(join(projectRoot, 'package.json'));
+        const prettier = require('prettier');
+        const filePath = join(projectRoot, relPath);
+        const resolved = prettier.resolveConfig.sync?.(filePath) ?? {};
+        const formatted = prettier.format(content, { ...resolved, filepath: filePath });
+        // Prettier 2 returns a string; Prettier 3 returns a Promise we cannot join from sync code.
+        return 'string' === typeof formatted ? formatted : content;
+    }
+    catch {
+        return content;
+    }
+}

package/dist/init/install-hint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What to say when the dependency install fails.
+ *
+ * Split out of plan.ts, which was at the 1000-line backstop. A cohesive unit rather than an
+ * arbitrary cut: it is prose about one step's failure modes, and the only thing it needs is which
+ * package manager was used.
+ */
+import { PackageManager } from './detect.js';
+export declare function installFailureHint(pm: PackageManager): string;

package/dist/init/install-hint.js

@@ -0,0 +1,29 @@
+/**
+ * What to say when the dependency install fails.
+ *
+ * Split out of plan.ts, which was at the 1000-line backstop. A cohesive unit rather than an
+ * arbitrary cut: it is prose about one step's failure modes, and the only thing it needs is which
+ * package manager was used.
+ */
+import { PackageManager } from './detect.js';
+/**
+ * Every package manager fetches, so every one of them can fail for a reason that is nothing to do
+ * with the project: offline, a proxy that blocks npmjs, a corporate mirror that is down.
+ *
+ * The hint used to name only version pinning and pnpm's maturity window. Both are real causes, and
+ * neither is that one — so a blocked registry sent the reader through their own dependency versions
+ * looking for a problem that was entirely about reachability.
+ */
+const REGISTRY_HINT = 'If it could not reach the registry at all (offline, a proxy, a mirror that is down), that is ' +
+    'about reachability and not about this project: check `npm config get registry` and whether this ' +
+    'machine can reach it.';
+export function installFailureHint(pm) {
+    if (pm !== PackageManager.PNPM) {
+        return `If the version was refused, install the SDK yourself. ${REGISTRY_HINT}`;
+    }
+    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.\n${REGISTRY_HINT}`);
+}

package/dist/init/mcp-clients.d.ts

@@ -78,5 +78,12 @@ export declare function clientSnippet(spec: ClientSpec): string;
  * because a fresh Cursor profile has not written `~/.cursor` yet.
  */
 export declare function clientMarkerRelPath(spec: ClientSpec): string;
+/**
+ * Project-relative directory whose presence signals Cursor is in use for this repo.
+ *
+ * A fresh Cursor profile has not written `~/.cursor` yet, so the home marker alone misses real
+ * users. A project-level `.cursor/` is unambiguous evidence somebody uses Cursor here.
+ */
+export declare const CURSOR_PROJECT_MARKER = ".cursor";
 /** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
 export declare function fileBackedClients(): readonly ClientSpec[];

package/dist/init/mcp-clients.js

@@ -286,6 +286,13 @@ export function clientMarkerRelPath(spec) {
     const parts = spec.relPath.split('/');
     return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
 }
+/**
+ * Project-relative directory whose presence signals Cursor is in use for this repo.
+ *
+ * A fresh Cursor profile has not written `~/.cursor` yet, so the home marker alone misses real
+ * users. A project-level `.cursor/` is unambiguous evidence somebody uses Cursor here.
+ */
+export const CURSOR_PROJECT_MARKER = '.cursor';
 /** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
 export function fileBackedClients() {
     return MCP_CLIENTS.filter((spec) => spec.scope !== ConfigScope.CLI);

package/dist/init/mcp.d.ts

@@ -43,7 +43,7 @@ export declare const NPX = "npx";
  *
  * 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 declare function npxServerArgs(): string[];
 /**