@reticlehq/server 2.12.0 → 2.13.0

package/dist/init/run.js

@@ -4,21 +4,23 @@
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
 import { dirname, join } from 'node:path';
+import { CSP_FILES } from './csp-doctor.js';
+import { preflightRefusal } from './preflight.js';
 import { noPackageJsonMessage } from './non-js-project.js';
 import { devCommandFrom } from './dev-script.js';
 import { restartHint, FEEDBACK_HINT } from './closing-hint.js';
 import { spanSync } from '../trace.js';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { projectIdOf, rememberProjectOnDisk } from '../project/remember-project.js';
 import { detect, Framework, namesAPackageManager, UiLibrary } from './detect.js';
 import { wasMcpRegistered } from './mcp-registered.js';
 import { pickAstroHost } from './astro-host.js';
-import { workspaceParents } from './workspace-apps.js';
+import { findWorkspaceApps, NEXT_CONFIG_CANDIDATES, PACKAGE_JSON, VITE_CONFIG_CANDIDATES, } from './workspace-apps.js';
 import { chooseWorkspaceApp } from './app-choice.js';
 import { isConnectStep } from './connect-steps.js';
 import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
 import { CRA_ENV_PATH } from './cra.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync } from '../bridge/pairing-token.js';
+import { formatGeneratedSource } from './format-generated.js';
 /** CRA's bundled entry, in the order create-react-app itself generates them. */
 const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
 function craEntryOf(io) {
@@ -30,26 +32,20 @@ function craEntryOf(io) {
     return null;
 }
 /**
- * The daemon's pairing token, for the one stack that cannot read it at build time.
+ * The daemon's pairing token, minted here if nothing has written it yet.
  *
- * Every other framework's snippet reads this file in Node when the dev server starts, so the token
- * is never written into the project. CRA bundles browser code and inlines only REACT_APP_*, so it
- * has to be materialised into .env.development.local — which CRA's own template gitignores.
+ * `init` used to READ the file and return empty when the daemon had never started. The CDN snippet
+ * inlined that empty value permanently, and regenerating the token made the pasted literal stale.
+ * Same mint as the daemon (`readOrCreatePairingToken`), honours `RETICLE_PAIRING_TOKEN_DIR`.
  */
 function readPairingToken() {
-    try {
-        return readFileSync(join(homedir(), '.reticle', 'pairing-token'), 'utf8').trim();
-    }
-    catch {
-        return '';
-    }
+    return readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
 }
 import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { reticleDevLocation } from './next-patch.js';
 import { scanTestids, storeHints, scanStores } from './capabilities.js';
-import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
-import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient } from './mcp-clients.js';
+import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient, CURSOR_PROJECT_MARKER, } from './mcp-clients.js';
 import { deriveProjectId, packageName } from './project-id.js';
 import { VITE_DEV_MODULE_PATH, connectArgWithToken, staticPageSnippet } from './snippets.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
@@ -96,7 +92,6 @@ export function resolveLockfiles(rootFiles, cwd, io, nodeModulesMarkers = new Se
     }
     return set;
 }
-const PACKAGE_JSON = 'package.json';
 const NODE_MODULES_DIR = 'node_modules';
 /**
  * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
@@ -200,12 +195,6 @@ function dependencyNames(pkg) {
         ...Object.keys(p['devDependencies'] ?? {}),
     ]);
 }
-const VITE_CONFIG_CANDIDATES = [
-    'vite.config.ts',
-    'vite.config.js',
-    'vite.config.mjs',
-    'vite.config.mts',
-];
 const ASTRO_CONFIG_CANDIDATES = [
     'astro.config.mjs',
     'astro.config.js',
@@ -216,12 +205,6 @@ const ASTRO_CONFIG_CANDIDATES = [
 const ASTRO_LAYOUTS_DIR = 'src/layouts';
 /** Also searched: an app with no layouts directory renders the document straight from a page. */
 const ASTRO_PAGES_DIR = 'src/pages';
-const NEXT_CONFIG_CANDIDATES = [
-    'next.config.mjs',
-    'next.config.js',
-    'next.config.ts',
-    'next.config.cjs',
-];
 /**
  * `⚠` means WORK LEFT TO DO and nothing else — it is what an agent (and the release gate) counts to
  * decide whether the install finished. A notice gets its own mark so "steps remaining" can reach zero
@@ -266,8 +249,7 @@ function agentRootOf(options) {
     const root = options.agentRoot;
     return root === undefined || root === options.cwd ? undefined : root;
 }
-function gatherPlanInput(options, io, pkgRaw) {
-    const pkg = JSON.parse(pkgRaw);
+function gatherPlanInput(options, io, pkg) {
     // Stable identity derived from the app's package.json name + root, so it survives port changes.
     const projectId = deriveProjectId(packageName(pkg), options.cwd);
     const rootFiles = new Set(io.rootFiles());
@@ -291,32 +273,25 @@ function gatherPlanInput(options, io, pkgRaw) {
     const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
     const existsProbe = claudeExistsProbe();
     const mcpExists = claudeCli ? io.probe(existsProbe.command, existsProbe.args) : false;
-    // join(), not a literal '/': this path is checked and WRITTEN on the user's machine, and a
-    // backslash platform silently misses the config it is meant to find.
-    const cursorDir = join(io.homeDir(), CURSOR_DIR_RELPATH);
-    const cursorConfigPath = join(io.homeDir(), CURSOR_MCP_RELPATH);
-    // Cursor is "present" if its global config directory exists OR the project carries a `.cursor/`.
-    // The directory alone missed a real case: Cursor installed with a FRESH profile has not written
-    // ~/.cursor yet, so a user who had it open got no Cursor step and no message about one. A
-    // project-level .cursor/ is unambiguous evidence somebody uses it here.
-    const cursorPresent = options.mcp && (io.exists(cursorDir) || io.exists(CURSOR_DIR_RELPATH));
-    const cursorConfig = cursorPresent ? io.readFile(cursorConfigPath) : null;
-    // Every OTHER MCP client this machine shows evidence of. Conservative and one-directional: we
-    // write into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody
-    // who does not use them. Cursor and Claude are handled above by their own steps.
+    // Every MCP client this machine shows evidence of. Conservative and one-directional: we write
+    // into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody who
+    // does not use them.
     const detectedClients = options.mcp
         ? fileBackedClients()
-            .filter((spec) => spec.id !== McpClient.CURSOR)
             .map((spec) => {
             const marker = clientMarkerRelPath(spec);
             const absolute = spec.scope === ConfigScope.HOME ? join(io.homeDir(), spec.relPath) : spec.relPath;
             const markerPath = spec.scope === ConfigScope.HOME ? join(io.homeDir(), marker) : marker;
-            if (!io.exists(markerPath))
+            // A fresh Cursor profile has not written ~/.cursor yet; the project-level .cursor/ is the
+            // fallback that kept that real case working. Same signal, project scope.
+            const projectFallback = spec.id === McpClient.CURSOR && !io.exists(markerPath)
+                ? io.exists(CURSOR_PROJECT_MARKER)
+                : false;
+            if (!io.exists(markerPath) && !projectFallback)
                 return null;
             return {
                 id: spec.id,
                 configPath: absolute,
-                // io.readFile passes absolute paths through unchanged, so one call covers both scopes.
                 existing: io.readFile(absolute),
             };
         })
@@ -349,21 +324,27 @@ function gatherPlanInput(options, io, pkgRaw) {
     const sourceFiles = readSourceFiles(io);
     const agentRoot = agentRootOf(options);
     const agentFile = (relPath) => agentRoot === undefined ? relPath : join(agentRoot, relPath);
+    const cspSources = {};
+    for (const file of CSP_FILES) {
+        const source = io.readFile(file);
+        if (null !== source)
+            cspSources[file] = source;
+    }
     return {
         detection,
+        captureBodies: options.captureBodies,
+        cspSources,
         claudeCli,
         mcpExists,
-        cursorPresent,
         platform: process.platform,
         detectedClients,
-        cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
-        cursorConfig,
-        cursorConfigPath,
+        cursorProjectPresent: io.exists(CURSOR_PROJECT_MARKER),
         viteConfig,
         astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
         astroLayout: layoutRelPath !== null && astroLayoutSource !== null
             ? { path: layoutRelPath, source: astroLayoutSource }
             : null,
+        astroEnvDts: io.readFile('src/env.d.ts'),
         nextConfigFile,
         nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
         nextLayout: layoutPath !== null && layoutSource !== null
@@ -414,69 +395,19 @@ function gatherPlanInput(options, io, pkgRaw) {
 }
 /** Where workspace tooling conventionally puts packages. */
 /** pnpm's workspace declaration, read when present — it is authoritative about where packages live. */
-const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
-/** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
-const APP_DEPS = ['next', 'vite'];
-function looksLikeApp(dir, io) {
-    const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
-    if (null === pkgRaw)
-        return false;
-    const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
-    if (configs.some((c) => io.exists(`${dir}/${c}`)))
-        return true;
-    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
-    return APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`));
-}
-/**
- * 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 function findWorkspaceApps(io) {
-    const found = [];
-    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
-    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
-    // root and reported ✓ for a file Next never compiles. See workspace-apps.
-    const pkgRaw = io.readFile(PACKAGE_JSON);
-    let pkgWorkspaces;
-    try {
-        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
-        pkgWorkspaces =
-            'object' === typeof parsed && parsed !== null
-                ? parsed.workspaces
-                : undefined;
-    }
-    catch {
-        pkgWorkspaces = undefined;
-    }
-    const parents = workspaceParents({
-        ...(null === io.readFile(PNPM_WORKSPACE)
-            ? {}
-            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
-        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
-        topLevelDirs: io.listDirs('.'),
-    });
-    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
-    // its children rather than assuming one level of nesting.
-    for (const parent of parents) {
-        if (looksLikeApp(parent, io))
-            found.push(parent);
-        for (const name of io.listDirs(parent)) {
-            const dir = `${parent}/${name}`;
-            if (looksLikeApp(dir, io))
-                found.push(dir);
-        }
-    }
-    return [...new Set(found)];
-}
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
 function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRoot, 
 /** The project's own dev command, so the closing line names what a human would type. */
-devCommand) {
+devCommand, 
+/**
+ * Whether this run continues into the phases that boot the app and drive it.
+ *
+ * The closing hint tells the reader to restart their dev server and then drive a flow. When those
+ * are the very next things this command does, printing them is worse than noise: it is an
+ * instruction to do by hand what is about to happen automatically, three lines before it happens.
+ */
+continuesToRuntime = false) {
     io.print(dryRun ? 'reticle init (dry run, no files written)' : 'reticle init');
     // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
     // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
@@ -536,7 +467,9 @@ devCommand) {
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
+    if (!continuesToRuntime) {
+        io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
+    }
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -588,7 +521,10 @@ function applyEffects(plan, io) {
             // is decoration, and this one is the first thing a new user reads. Same shape as #139.
             const wrote = spanSync('init.write', { target: s.target, path: write.path }, () => {
                 try {
-                    io.writeFile(write.path, write.content);
+                    // Format connect modules with the project's Prettier when present (#684) — a clean
+                    // install must not fail the project's own lint on a file we just wrote.
+                    const content = formatGeneratedSource(write.content, write.path, io.cwd());
+                    io.writeFile(write.path, content);
                 }
                 catch {
                     return false; // a throw is the loud version of the same failure
@@ -663,16 +599,36 @@ const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle
  * guessing which app someone meant is worse than one line of output.
  * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
  */
-function redirectToWorkspaceApp(options, io, pkgRaw) {
+function redirectToWorkspaceApp(options, io, pkg) {
     if (true === options.redirected)
         return null;
-    const pkg = JSON.parse(pkgRaw);
     const rootFiles = new Set(io.rootFiles());
     const here = detect({
         pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
         lockfiles: new Set(),
     });
+    // `--app` is an INSTRUCTION, and it is read before the guess below. The guess answers "where is
+    // the app?" for somebody who did not say; when somebody said, there is nothing left to infer.
+    //
+    // It used to be read after, and the check underneath returns early for any directory that looks
+    // like an app — which a JS monorepo ROOT does, because shared tooling puts `vite` in its
+    // devDependencies. So on a real pnpm+turbo monorepo (measured on nuclear, a Tauri v2 app at
+    // product scale) `reticle init --app packages/player` silently ignored the flag, installed the
+    // SDK into the root's package.json, wrote `.reticle.json` and a whole `src/reticle-dev.ts` into a
+    // repository root that has no `src/`, left `packages/player` untouched — and reported three ✓ and
+    // one ⚠. The one flag documented for this shape wired the wrong directory and said it worked.
+    //
+    // Existence is the test, not membership of the discovered list: discovery scans conventional
+    // directories, and somebody who names a path knows their own layout better than the scan does.
+    const named = options.app === undefined || '' === options.app ? undefined : options.app;
+    if (named !== undefined) {
+        const wanted = named.replace(/\/+$/, '');
+        if (io.exists(`${wanted}/${PACKAGE_JSON}`))
+            return enterApp(options, io, wanted, 'Wiring');
+        io.print(`--app ${named} does not name a directory with a package.json in it.`);
+        return { ok: false, applied: 0, manual: 1 };
+    }
     if (here.framework !== Framework.HTML)
         return null; // this directory IS the app
     const apps = findWorkspaceApps(io);
@@ -695,7 +651,18 @@ function redirectToWorkspaceApp(options, io, pkgRaw) {
         io.print(`Or name one without changing directory:  reticle init --app ${apps[0] ?? '<dir>'}`);
         return { ok: false, applied: 0, manual: apps.length };
     }
-    io.print(`No app in this directory — wiring ${target} instead.`);
+    return enterApp(options, io, target, 'No app in this directory — wiring');
+}
+/**
+ * Re-enter `init` scoped to one directory of a workspace.
+ *
+ * One implementation for both routes in — the app somebody NAMED and the app discovery found when
+ * nobody did. They differ only in the sentence printed; scoping the io, moving the cwd and keeping
+ * the agent root has to be identical for both, and was worth having twice for exactly as long as it
+ * took to get one of them wrong.
+ */
+function enterApp(options, io, target, lead) {
+    io.print(`${lead} ${target}.`);
     io.print('');
     return runInit({
         ...options,
@@ -721,8 +688,42 @@ export function runInit(options, io) {
     }
     return result;
 }
+/**
+ * The manifest, parsed once, or the reason it could not be.
+ *
+ * It used to be parsed in three places from the same raw string, and two of them were unguarded —
+ * so `reticle init` on a `package.json` with a trailing comma died with a raw `SyntaxError` and a
+ * stack through `redirectToWorkspaceApp`. A stack trace in front of a user is a bug whatever caused
+ * it, and this one lands on the very first thing the command does, before it has said anything.
+ *
+ * `setup/reticle.mjs` has always got this right ("… is not valid JSON (…). Fix it and re-run"). The
+ * shipped CLI did not, which is the shape of every divergence between the two: the prototype refuses
+ * politely, `init` throws. Parsing once at the single point the file enters means no later caller
+ * CAN reintroduce it — a guard per call site would have been three guards and a fourth one waiting.
+ */
+function readManifest(io) {
+    const raw = io.readFile(PACKAGE_JSON);
+    if (null === raw)
+        return { pkg: null };
+    try {
+        return { pkg: JSON.parse(raw) };
+    }
+    catch (err) {
+        // First line only: JSON.parse's message carries the offending position, and the rest is noise.
+        const detail = String(err instanceof Error ? err.message : err).split('\n')[0] ?? 'unparseable';
+        return { error: detail };
+    }
+}
 function runInitSteps(options, io) {
-    const pkgRaw = io.readFile(PACKAGE_JSON);
+    const manifest = readManifest(io);
+    if ('error' in manifest) {
+        io.print(`${PACKAGE_JSON} is not valid JSON (${manifest.error}). Fix it and re-run — init reads the ` +
+            'framework, the dev script and the package manager from it, and will not guess at any of ' +
+            'them from a file it cannot read.');
+        reportInitOutcome({ ok: false, reason: InitFailure.MALFORMED_PACKAGE_JSON });
+        return { ok: false, applied: 0, manual: 0 };
+    }
+    const pkgRaw = manifest.pkg;
     // Look for the app BEFORE concluding there isn't one.
     //
     // A root with no package.json is not a dead end — it is the ordinary shape of a repo whose app
@@ -735,7 +736,7 @@ function runInitSteps(options, io) {
     //
     // `'{}'` because the redirect only needs the manifest to ask "is THIS directory the app", and a
     // directory with no package.json is definitively not.
-    const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? '{}');
+    const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? {});
     if (redirectedEarly !== null)
         return redirectedEarly;
     if (null === pkgRaw) {
@@ -759,6 +760,20 @@ function runInitSteps(options, io) {
     // 1–6s per app with no explanation of the spread. These three spans split that number into detect
     // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
     const planInput = gatherPlanInput(options, io, pkgRaw);
+    // Before anything is written, and AFTER detection — the package manager to check is the one init
+    // RESOLVED, not a raw lockfile read. An inherited pnpm-lock.yaml at a monorepo root does not mean
+    // the app in frontend/ uses pnpm, and checking the file refused a scaffold the install gate proves
+    // must succeed. Both conditions make every later phase fail, and each arrives far from its cause
+    // when it is not checked here. See preflight.ts.
+    const refusal = preflightRefusal({
+        cwd: () => io.cwd(),
+        canWrite: () => io.canWrite(),
+        probe: (command, args) => io.probe(command, args),
+    }, planInput.detection.packageManager);
+    if (refusal !== undefined) {
+        io.print(refusal);
+        return { ok: false, applied: 0, manual: 1 };
+    }
     const plan = spanSync('init.plan', {}, () => buildPlan(planInput));
     const effects = options.dryRun
         ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
@@ -766,7 +781,7 @@ function runInitSteps(options, io) {
     const { failed, skipped, degraded } = effects;
     // The project's own dev command, so the closing line names what a human would actually type.
     const devCommand = devCommandFrom(pkgRaw, planInput.detection.packageManager);
-    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand, true === options.continuesToRuntime);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (options.dryRun)
         return result;
@@ -777,8 +792,15 @@ function runInitSteps(options, io) {
         // The step's REAL final status, not the absence of a failure — see mcp-registered.
         mcpRegistered: wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped)),
     };
+    const context = {
+        appDir: options.cwd,
+        framework: plan.framework,
+        packageManager: planInput.detection.packageManager,
+        ...(undefined === devCommand ? {} : { devCommand }),
+        ...(true === options.redirected ? { redirectedTo: options.cwd } : {}),
+    };
     if (true === options.deferOutcome)
-        return { ...result, outcome };
+        return { ...result, context, outcome };
     reportInitOutcome(outcome);
-    return result;
+    return { ...result, context };
 }

package/dist/init/slash-command.d.ts

@@ -24,4 +24,4 @@ export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
  * are told apart.
  */
 export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
-export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";
+export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";

package/dist/init/snippets.js

@@ -132,41 +132,51 @@ export function nextReticleDevFile(port, projectId, testids = [], stores = [], f
     // Same rule as the Vite module: a store we found is registered outright, and the commented hint
     // survives only for the libraries we can name but not wire.
     const storeImports = found.map((s) => `import { ${s.ident} } from '${s.importPath}';`).join('\n');
+    // Eight spaces: nested inside useEffect → .then callback (see multiline shape below for #684).
     const storeBlock = found.length > 0
-        ? found.map((s) => `      registerStore('${s.key}', ${s.ident});`).join('\n')
+        ? found.map((s) => `        registerStore('${s.key}', ${s.ident});`).join('\n')
         : 0 === stores.length
-            ? '      // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
-            : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
+            ? '        // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
+            : stores.map((h) => `        // import your store, then: ${h}`).join('\n');
+    const registerNames = found.length > 0 ? ', registerStore' : '';
+    // Multiline connect + single blank after imports (#684): the one-line connect and the double blank
+    // both fail Prettier on a clean Next install.
     return `'use client';
 import { useEffect } from 'react';
-${storeImports.length > 0 ? storeImports : ''}
-
+${storeImports.length > 0 ? `${storeImports}\n` : ''}
 /** Dev-only: connect Reticle + install the React adapter, after hydration. */
 export function ReticleDev() {
   useEffect(() => {
     if (process.env.NODE_ENV !== 'development') return;
-    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities${found.length > 0 ? ', registerStore' : ''} }) => {
-      install();
-      // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
-      // the root makes source paths repo-relative instead of absolute.
-      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
-      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
-      // withReticle() finds the daemon serving this project on every dev-server start. It wins over
-      // any port written into this file at install time, so moving the daemon needs no edit here.
-      const url = process.env.NEXT_PUBLIC_RETICLE_URL;
-      reticle.connect({ ${fields}...(url ? { url } : {}), ...(token ? { token } : {}), ...(root ? { root } : {}) });
+    void import('@reticlehq/react').then(
+      ({ reticle, install, registerCapabilities${registerNames} }) => {
+        install();
+        // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
+        // the root makes source paths repo-relative instead of absolute.
+        const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
+        const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
+        // withReticle() finds the daemon serving this project on every dev-server start. It wins over
+        // any port written into this file at install time, so moving the daemon needs no edit here.
+        const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+        reticle.connect({
+          ${fields}...(url ? { url } : {}),
+          ...(token ? { token } : {}),
+          ...(root ? { root } : {}),
+        });
 
-      // ── Start with ONE flow. ──────────────────────────────────────────────────────────────────
-      // Registering a store is the highest-value line here: it lets the agent check what the app
-      // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the store
-      // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
+        // ── Start with ONE flow. ────────────────────────────────────────────────────────────────
+        // Registering a store is the highest-value line here: it lets the agent check what the app
+        // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the
+        // store form wires \`subscribe\` too, so every mutation emits a diff; the getter form is
+        // read-only.
 ${storeBlock}
-      registerCapabilities({
-        testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
-        signals: [], // names you pass to reticle.signal()
-        stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
-      });
-    });
+        registerCapabilities({
+          testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
+          signals: [], // names you pass to reticle.signal()
+          stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
+        });
+      },
+    );
   }, []);
   return null;
 }
@@ -289,6 +299,12 @@ ${layoutHost(layoutPath)}
     }
   </script>
 
+3. In src/env.d.ts — declare the Vite define names so \`astro check\` can see them (create-astro's
+   default build runs check first, and without this it fails with Cannot find name '__RETICLE_TOKEN__'):
+
+  declare const __RETICLE_TOKEN__: string | undefined;
+  declare const __RETICLE_ROOT__: string | undefined;
+
 Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
 }
 /**

package/dist/init/vite-config.d.ts

@@ -14,5 +14,5 @@ export declare const VitePatchKind: {
 };
 export type VitePatchKind = PatchKind;
 type VitePatch = SourcePatch;
-export declare function patchViteConfig(source: string, port?: number): VitePatch;
+export declare function patchViteConfig(source: string, port?: number, captureBodies?: boolean): VitePatch;
 export {};