@reticlehq/server 2.4.0 → 2.5.0

package/dist/init/next-patch.js

@@ -7,14 +7,14 @@
  */
 import { PatchKind } from './patch-kind.js';
 const RETICLE_NEXT_PACKAGE = '@reticlehq/next';
-export const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
-export const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
+const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
+const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
 const RETICLE_DEV_COMPONENT = 'ReticleDev';
 const RETICLE_DEV_BASENAME = 'reticle-dev';
 /** Default import specifier: the component sits beside the file importing it (App Router). */
 const RETICLE_DEV_SIBLING = `./${RETICLE_DEV_BASENAME}`;
 const reticleDevImport = (specifier) => `import { ${RETICLE_DEV_COMPONENT} } from '${specifier}';`;
-export const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
+const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
 /**
  * Decide where the connect component lives, from the file that will mount it.
  *
@@ -31,11 +31,11 @@ export const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
 export function reticleDevLocation(mountPath, typescript) {
     const ext = typescript ? '.tsx' : '.jsx';
     const slash = mountPath.lastIndexOf('/');
-    const dir = slash === -1 ? '' : mountPath.slice(0, slash);
+    const dir = -1 === slash ? '' : mountPath.slice(0, slash);
     const isPagesRouter = /(^|\/)pages$/.test(dir);
     if (!isPagesRouter) {
         return {
-            path: `${dir === '' ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
+            path: `${'' === dir ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
             importSpecifier: RETICLE_DEV_SIBLING,
         };
     }
@@ -48,26 +48,116 @@ export function reticleDevLocation(mountPath, typescript) {
 }
 /** The dev-guarded mount. Production strips it — `process.env.NODE_ENV` is inlined at build time. */
 const RETICLE_DEV_MOUNT = `{process.env.NODE_ENV === 'development' ? <${RETICLE_DEV_COMPONENT} /> : null}`;
-/** `export default <expr>;` — the ESM shape every `create-next-app` config uses. */
-const ESM_DEFAULT_EXPORT = /export\s+default\s+([\s\S]+?);?\s*$/;
-/** `module.exports = <expr>;` — the CJS shape older configs use. */
-const CJS_EXPORT = /module\.exports\s*=\s*([\s\S]+?);?\s*$/;
+/**
+ * `export default ` / `module.exports = ` at the START of a line — the head of the assignment, not
+ * the whole statement. Where the exported expression ENDS is decided by `expressionEnd` below.
+ *
+ * These used to be `/…([\s\S]+?);?\s*$/`, which reads as "the expression, lazily". It is not: with
+ * no `m` flag the `$` is end-of-FILE and the trailing `;?\s*` is satisfiable only there, so the
+ * capture always ran to the last non-blank character of the file. Every config whose export was not
+ * the final statement got everything after it swallowed into the wrap. On a config exporting
+ * conditionally that produced an unbalanced paren — a syntax error, so `next dev` exited 1 while
+ * `init` reported the step as ✓ and the only symptom was "dev server never served".
+ */
+const ESM_DEFAULT_HEAD = /^[ \t]*export[ \t]+default[ \t]+/gm;
+const CJS_EXPORT_HEAD = /^[ \t]*module\.exports[ \t]*=[ \t]*/gm;
 /** The opening `<body ...>` tag, whose first child is where the mount goes. */
 const BODY_OPEN_TAG = /<body(\s[^>]*)?>/g;
 const NO_EXPORT_REASON = "couldn't find an `export default` or `module.exports` to wrap";
 const NO_BODY_REASON = "couldn't find a single <body> tag to mount <ReticleDev /> inside";
+/** Bracket pairs that keep an expression open. A `;` at depth 0 is what ends it. */
+const OPENERS = '([{';
+const CLOSERS = ')]}';
+const LINE_COMMENT = '//';
+const BLOCK_COMMENT_OPEN = '/*';
+const BLOCK_COMMENT_CLOSE = '*/';
+const QUOTES = '\'"`';
+/**
+ * Index just past the exported expression that starts at `from` — the `;` that closes it, or end of
+ * file. Tracks bracket depth so a multi-line object or a nested call ends in the right place, and
+ * skips strings and comments so a `;` or a brace inside one cannot end it early.
+ *
+ * Deliberately a scanner and not a parser: `next.config.*` is arbitrary JS and this file's contract
+ * is to recognise the obvious shape or bail. It only has to be right about where ONE expression
+ * stops, and wrong is caught by the caller bailing to manual, never by a half-edit.
+ */
+function expressionEnd(source, from) {
+    let depth = 0;
+    for (let i = from; i < source.length; i++) {
+        const ch = source[i] ?? '';
+        const pair = source.slice(i, i + 2);
+        if (pair === LINE_COMMENT) {
+            const nl = source.indexOf('\n', i);
+            if (-1 === nl)
+                return source.length;
+            i = nl;
+            continue;
+        }
+        if (pair === BLOCK_COMMENT_OPEN) {
+            const close = source.indexOf(BLOCK_COMMENT_CLOSE, i + 2);
+            i = -1 === close ? source.length : close + 1;
+            continue;
+        }
+        if (QUOTES.includes(ch)) {
+            for (i++; i < source.length; i++) {
+                if ('\\' === source[i])
+                    i++;
+                else if (source[i] === ch)
+                    break;
+            }
+            continue;
+        }
+        if (OPENERS.includes(ch))
+            depth++;
+        else if (CLOSERS.includes(ch)) {
+            // A closer at depth 0 belongs to an enclosing block, so the expression ended before it.
+            if (0 === depth)
+                return i;
+            depth--;
+        }
+        else if (';' === ch && 0 === depth)
+            return i;
+    }
+    return source.length;
+}
+/** Every top-level export assignment in the file, in source order. */
+function exportSites(source, head) {
+    const sites = [];
+    for (const match of source.matchAll(head)) {
+        if (match.index === undefined)
+            continue;
+        const start = match.index + match[0].length;
+        sites.push({ start, end: expressionEnd(source, start) });
+    }
+    return sites;
+}
+/**
+ * Wrap every listed expression in `withReticle(...)`, leaving every other byte of the file alone.
+ *
+ * All of them, not just the first: a config can export CONDITIONALLY — Sentry-wrapped in one branch,
+ * plain in the other — and which branch runs is an environment variable's business, not ours.
+ * Wrapping each assignment is correct whichever one executes, and it is what turns that shape from a
+ * manual step (an app that boots and never connects) into a working install.
+ *
+ * Applied back-to-front so each splice leaves the earlier offsets valid.
+ */
+function wrapAll(source, sites) {
+    let out = source;
+    for (const site of [...sites].sort((a, b) => b.start - a.start)) {
+        out = `${out.slice(0, site.start)}withReticle(${out.slice(site.start, site.end)})${out.slice(site.end)}`;
+    }
+    return out;
+}
 export function patchNextConfig(source) {
     if (source.includes(RETICLE_NEXT_PACKAGE))
         return { kind: PatchKind.ALREADY };
-    const esm = ESM_DEFAULT_EXPORT.exec(source);
-    if (esm?.[1] !== undefined) {
-        const wrapped = source.replace(ESM_DEFAULT_EXPORT, `export default withReticle(${esm[1]});\n`);
-        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_IMPORT}\n${wrapped}` };
+    const esm = exportSites(source, ESM_DEFAULT_HEAD);
+    if (esm.length > 0) {
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_IMPORT}\n${wrapAll(source, esm)}` };
     }
-    const cjs = CJS_EXPORT.exec(source);
-    if (cjs?.[1] !== undefined) {
-        const wrapped = source.replace(CJS_EXPORT, `module.exports = withReticle(${cjs[1]});\n`);
-        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_REQUIRE}\n${wrapped}` };
+    const cjs = exportSites(source, CJS_EXPORT_HEAD);
+    if (cjs.length > 0) {
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_REQUIRE}\n${wrapAll(source, cjs)}` };
     }
     return { kind: PatchKind.MANUAL, reason: NO_EXPORT_REASON };
 }
@@ -84,7 +174,7 @@ export function patchPagesApp(source, importSpecifier = RETICLE_DEV_SIBLING) {
     if (source.includes(RETICLE_DEV_COMPONENT))
         return { kind: PatchKind.ALREADY };
     const matches = [...source.matchAll(PAGES_APP_COMPONENT)];
-    const match = matches.length === 1 ? matches[0] : undefined;
+    const match = 1 === matches.length ? matches[0] : undefined;
     if (match?.index === undefined)
         return { kind: PatchKind.MANUAL, reason: NO_PAGES_COMPONENT_REASON };
     const wrapped = `<>${RETICLE_DEV_MOUNT}${match[0]}</>`;
@@ -97,7 +187,7 @@ export function patchRootLayout(source) {
     const tags = [...source.matchAll(BODY_OPEN_TAG)];
     // Exactly one <body> or we cannot tell which one actually renders — and mounting into the wrong
     // one is the same silent no-connect as not mounting at all.
-    const tag = tags.length === 1 ? tags[0] : undefined;
+    const tag = 1 === tags.length ? tags[0] : undefined;
     if (tag?.index === undefined)
         return { kind: PatchKind.MANUAL, reason: NO_BODY_REASON };
     const insertAt = tag.index + tag[0].length;

package/dist/init/node-io.js

@@ -4,9 +4,27 @@
  * command, not the MCP stdio transport.
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { NodePlatform } from '../platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+/**
+ * `shell: true` ONLY where it earns its keep.
+ *
+ * It exists so package-manager shims (`pnpm.cmd`, `npx.cmd`) resolve on Windows. On POSIX it buys
+ * nothing and costs correctness: under a shell, arguments are re-parsed, so a path containing a
+ * space — `/Users/ada/My Projects/app` — silently becomes two arguments and registration fails with
+ * no error anyone can read.
+ */
+function shellOpt() {
+    return NodePlatform.WINDOWS === process.platform ? { shell: true } : {};
+}
+/** Under a shell, quote what the shell would otherwise split. Windows only, where shell is required. */
+function shellSafe(args) {
+    if (process.platform !== NodePlatform.WINDOWS)
+        return [...args];
+    return args.map((arg) => (/[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg));
+}
 export function buildNodeIo(cwd) {
     // Project-relative by default; absolute paths (e.g. ~/.cursor/mcp.json) pass through unchanged.
     const abs = (rel) => (isAbsolute(rel) ? rel : join(cwd, rel));
@@ -64,15 +82,14 @@ export function buildNodeIo(cwd) {
             return buildNodeIo(abs(rel));
         },
         exec(command, args) {
-            // `shell: true` lets package-manager shims (pnpm.cmd, etc.) resolve on Windows; inherit
-            // stdio so the install's own progress is visible to the user.
-            const result = spawnSync(command, [...args], { cwd, stdio: 'inherit', shell: true });
-            return result.status === 0;
+            // Inherit stdio so the install's own progress is visible to the user.
+            const result = spawnSync(command, shellSafe(args), { cwd, stdio: 'inherit', ...shellOpt() });
+            return 0 === result.status;
         },
         probe(command, args) {
             // Quiet yes/no check (CLI availability, existing registration). Never throws.
-            const result = spawnSync(command, [...args], { cwd, stdio: 'ignore', shell: true });
-            return result.status === 0;
+            const result = spawnSync(command, shellSafe(args), { cwd, stdio: 'ignore', ...shellOpt() });
+            return 0 === result.status;
         },
         print(line) {
             process.stdout.write(`${line}\n`);

package/dist/init/plan-framework.d.ts

@@ -16,7 +16,6 @@ export declare const VITE_PLUGIN_DETAIL: {
      */
     readonly SVELTEKIT: "add reticle() to plugins (stamps data-reticle-source in .svelte components)";
 };
-export declare const CAPABILITIES_TITLE = "Capabilities + store";
 export declare function viteSteps(input: PlanInput, detail?: string): Step[];
 /**
  * Next used to be the ONLY stack with hand edits left over — and both of them fail silently when
@@ -32,4 +31,20 @@ export declare function nextSteps(input: PlanInput): Step[];
  * wiring is real and may well work; what is missing is anything that would tell us when it stops.
  * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
  */
+/**
+ * Create React App: the connect goes in `src/index.tsx`, the token in `.env.development.local`.
+ *
+ * The previous plan pointed at `index.html`, which cannot work — CRA's is a static template the
+ * bundler never processes for modules. Reported from a real cra-redux-saga app.
+ */
+export declare function craSteps(input: PlanInput): Step[];
 export declare function svelteKitSteps(input: PlanInput): Step[];
+/**
+ * Astro: the config define + build target, and the connect script in ONE layout.
+ *
+ * Astro was the last gated stack left printing a recipe it did not apply. It still falls back to the
+ * printed one whenever the choice is not obvious — no config, no single layout, or a shape the
+ * patchers do not fully recognise — because which page or layout to instrument is a real decision
+ * and a half-edited build config is worse than a documented manual step.
+ */
+export declare function astroSteps(input: PlanInput): Step[];

package/dist/init/plan-framework.js

@@ -5,8 +5,10 @@
  */
 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, TOKEN_VAR, craDevModuleFile, 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, } from './snippets.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, } from './snippets.js';
 import { StepStatus } from './plan.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
@@ -20,7 +22,7 @@ export const VITE_PLUGIN_DETAIL = {
      */
     SVELTEKIT: 'add reticle() to plugins (stamps data-reticle-source in .svelte components)',
 };
-export const CAPABILITIES_TITLE = 'Capabilities + store';
+const CAPABILITIES_TITLE = 'Capabilities + store';
 /**
  * The dev module carrying `registerCapabilities` / `registerStore`.
  *
@@ -29,7 +31,7 @@ export const CAPABILITIES_TITLE = 'Capabilities + store';
  * only when absent, because it is the one generated file a user is expected to EDIT.
  */
 function capabilitiesStep(input) {
-    if (input.viteDevModuleExists === true) {
+    if (true === input.viteDevModuleExists) {
         return [
             {
                 title: CAPABILITIES_TITLE,
@@ -41,7 +43,9 @@ function capabilitiesStep(input) {
     }
     const testids = input.testids ?? [];
     const stores = input.storeHints ?? [];
-    const found = testids.length > 0 ? `${String(testids.length)} data-testid values` : 'no data-testid values yet';
+    const found = testids.length > 0
+        ? `${String(testids.length)} data-testid values`
+        : 'no data-testid values yet';
     return [
         {
             title: CAPABILITIES_TITLE,
@@ -61,7 +65,7 @@ export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE) {
 function viteConfigSteps(input, detail) {
     const cfg = input.viteConfig;
     const port = input.options.port;
-    if (cfg === null) {
+    if (null === cfg) {
         return [
             {
                 title: 'Vite plugin',
@@ -154,14 +158,14 @@ export function nextSteps(input) {
             },
             dependsOnInstall: true,
         };
-    const configPatch = input.nextConfigSource === null || input.nextConfigSource === undefined
+    const configPatch = null === input.nextConfigSource || input.nextConfigSource === undefined
         ? { kind: PatchKind.MANUAL, reason: `no ${configFile} found` }
         : patchNextConfig(input.nextConfigSource);
     const layout = input.nextLayout ?? null;
     // Pages Router mounts through pages/_app, App Router through the root layout — different edits,
     // and picking by path is what stops a Pages app being handed the layout patch that cannot apply.
     const isPagesRouter = layout !== null && /(^|\/)pages\/_app\.[jt]sx?$/.test(layout.path);
-    const layoutPatch = layout === null
+    const layoutPatch = null === layout
         ? { kind: PatchKind.MANUAL, reason: 'no root layout (app/layout.tsx) or pages/_app found' }
         : isPagesRouter
             ? patchPagesApp(layout.source, input.nextReticleDevImport)
@@ -180,6 +184,79 @@ export function nextSteps(input) {
  * wiring is real and may well work; what is missing is anything that would tell us when it stops.
  * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
  */
+/**
+ * Create React App: the connect goes in `src/index.tsx`, the token in `.env.development.local`.
+ *
+ * The previous plan pointed at `index.html`, which cannot work — CRA's is a static template the
+ * bundler never processes for modules. Reported from a real cra-redux-saga app.
+ */
+export function craSteps(input) {
+    const entry = input.craEntry ?? null;
+    const steps = [
+        {
+            title: 'Reticle connect module',
+            target: CRA_DEV_MODULE_PATH,
+            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),
+            },
+            dependsOnInstall: true,
+        },
+    ];
+    const token = input.pairingToken ?? '';
+    const env = craEnvPatch(input.craEnv ?? null, token);
+    if (env !== null) {
+        steps.push({
+            title: 'Pairing token',
+            target: CRA_ENV_PATH,
+            status: StepStatus.APPLY,
+            // REACT_APP_* is the only thing CRA inlines into browser code; without the token the bridge
+            // refuses the connection and no session appears. Say the file is gitignored HERE, at the one
+            // moment someone is looking: the token is per-machine and cannot travel, so every teammate
+            // has to run init once or their clone is dead with no explanation.
+            detail: `set ${TOKEN_VAR} (the only channel CRA inlines) — ${CRA_ENV_PATH} is gitignored, so each teammate must run \`reticle init\` on their own machine`,
+            write: { path: CRA_ENV_PATH, content: env },
+        });
+    }
+    else if ('' === token) {
+        // No daemon has ever run here, so there is no token to inline. Omitting the step entirely made
+        // init report all-green for an app that could never pair.
+        steps.push({
+            title: 'Pairing token',
+            target: CRA_ENV_PATH,
+            status: StepStatus.MANUAL,
+            detail: `no pairing token yet — run \`reticle start\`, then \`reticle init\` again to write ${TOKEN_VAR}`,
+        });
+    }
+    if (null === entry) {
+        steps.push({
+            title: 'Connect snippet (CRA)',
+            target: 'src/index.tsx',
+            status: StepStatus.MANUAL,
+            detail: `Add \`${CRA_DEV_MODULE_IMPORT}\` to your app entry (src/index.tsx or src/index.js), after the existing imports.`,
+        });
+        return steps;
+    }
+    const patched = craImportPatch(entry.source);
+    steps.push(null === patched
+        ? {
+            title: 'Connect snippet (CRA)',
+            target: entry.path,
+            status: StepStatus.ALREADY,
+            detail: 'already imported',
+        }
+        : {
+            title: 'Connect snippet (CRA)',
+            target: entry.path,
+            status: StepStatus.APPLY,
+            detail: 'import the dev-only connect module',
+            write: { path: entry.path, content: patched },
+            dependsOnInstall: true,
+        });
+    return steps;
+}
 export function svelteKitSteps(input) {
     const unverified = {
         title: 'SvelteKit is UNVERIFIED',
@@ -189,7 +266,7 @@ export function svelteKitSteps(input) {
     };
     // SvelteKit can't use the Vite-plugin injection (it renders via app.html) — wire a client hook
     // that SvelteKit runs on startup, which is the path that can register a session at all.
-    if (input.svelteKitHooksExists === true) {
+    if (true === input.svelteKitHooksExists) {
         return [
             unverified,
             {
@@ -215,3 +292,50 @@ export function svelteKitSteps(input) {
         },
     ];
 }
+/**
+ * Astro: the config define + build target, and the connect script in ONE layout.
+ *
+ * Astro was the last gated stack left printing a recipe it did not apply. It still falls back to the
+ * printed one whenever the choice is not obvious — no config, no single layout, or a shape the
+ * patchers do not fully recognise — because which page or layout to instrument is a real decision
+ * and a half-edited build config is worse than a documented manual step.
+ */
+export function astroSteps(input) {
+    const config = input.astroConfig ?? null;
+    const layout = input.astroLayout ?? null;
+    const manual = astroManual(input.options.port, input.options.projectId, layout?.path);
+    if (null === config || null === layout) {
+        return [
+            {
+                title: 'Connect snippet (Astro)',
+                // Name what is actually there. `astro.config + layout` pointed at a layout this project may
+                // not have — reported on a fixture with only src/pages/index.astro.
+                target: null === layout ? 'astro.config + a page (no layout found)' : 'astro.config + layout',
+                status: StepStatus.MANUAL,
+                detail: manual,
+            },
+        ];
+    }
+    // ATOMIC. The connect snippet is useless without the config: the token is inlined by the config,
+    // so a layout patched on its own gives an app that dials the bridge and is refused. Measured on a
+    // real fixture — config ⚠, layout ✓ — which reads as one step done and one caveat when it is
+    // actually a guaranteed non-connection. If either half cannot be applied, BOTH go manual with the
+    // single recipe that does the whole job.
+    const manualWithLayout = astroManual(input.options.port, input.options.projectId, layout.path);
+    const configPatch = patchAstroConfig(config.source);
+    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId);
+    if (configPatch.kind === PatchKind.MANUAL || layoutPatch.kind === PatchKind.MANUAL) {
+        return [
+            {
+                title: 'Connect snippet (Astro)',
+                target: `${config.path} + ${layout.path}`,
+                status: StepStatus.MANUAL,
+                detail: manualWithLayout,
+            },
+        ];
+    }
+    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),
+    ];
+}

package/dist/init/plan.d.ts

@@ -14,10 +14,10 @@ import { Framework, type Detection } from './detect.js';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
-/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export declare function frameworkPackages(framework: Framework): readonly string[];
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
+/** True when this step is what makes the app dial the daemon. */
+export declare function isConnectStep(title: string): boolean;
 /** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
 export declare const DEPS_TARGET = "package.json";
 export declare const StepStatus: {
@@ -50,6 +50,20 @@ export interface Step {
         args: string[];
         fallback: string;
     };
+    /**
+     * A second, weaker attempt to run when `exec` fails, with what to tell the user if it succeeds.
+     *
+     * The pinned install is refused outright by pnpm's `minimumReleaseAge` for as long as its window
+     * lasts — so for ~48 hours after every release, a project with that setting could not install
+     * Reticle at all. An unpinned install still works there (it resolves the newest MATURE version), so
+     * the fallback trades an exact version for a working install and says which it did. It must never
+     * be silent: an older SDK against a newer daemon is the skew this pin exists to prevent.
+     */
+    retry?: {
+        command: string;
+        args: string[];
+        note: string;
+    };
     /**
      * This step wires the app to a package the install step provides. If that install fails, applying
      * it anyway leaves the app importing a module that is not there — `next.config.ts` importing
@@ -81,6 +95,22 @@ export interface PlanInput {
         path: string;
         source: string;
     } | null;
+    /** Discovered Astro config: its path + source, or null if none found. */
+    astroConfig?: {
+        path: string;
+        source: string;
+    } | null | undefined;
+    /**
+     * The single layout to instrument, or null when the choice is not obvious.
+     *
+     * WHICH page or layout to instrument is a real decision — so `init` only makes it when there is
+     * exactly one candidate. Zero or several falls back to the printed recipe rather than guessing at
+     * the file every page of the user's site inherits from.
+     */
+    astroLayout?: {
+        path: string;
+        source: 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. */
@@ -104,18 +134,33 @@ export interface PlanInput {
     viteDevModuleExists?: boolean | undefined;
     /** Whether src/hooks.client.ts already exists (SvelteKit idempotency). */
     svelteKitHooksExists?: boolean;
+    /** CRA's bundled entry (src/index.tsx or .js) — where the connect import has to go. */
+    craEntry?: {
+        path: string;
+        source: string;
+    } | null;
+    /** Existing .env.development.local, so an unrelated variable in it survives. */
+    craEnv?: string | null;
+    /** The daemon's pairing token, inlined for CRA through the one channel it supports. */
+    pairingToken?: string;
     /** Whether .reticle.json already exists in the project root (idempotency). */
     reticleConfigExists?: boolean;
     /** Current project-root CLAUDE.md content (for the idempotent agent-rule merge), or null/undefined. */
     claudeMdContent?: string | null | undefined;
     /** Current project-root AGENTS.md content (cross-agent fallback rule), or null/undefined. */
     agentsMdContent?: string | null | undefined;
-    /** Whether .cursor/rules/reticle.mdc already exists (agent-rule idempotency). */
-    cursorRuleExists?: boolean | undefined;
-    /** Whether .claude/commands/reticle.md already exists (slash-command idempotency). */
-    claudeCommandExists?: boolean | undefined;
-    /** Whether .cursor/commands/reticle.md already exists. */
-    cursorCommandExists?: boolean | undefined;
+    /**
+     * Current .cursor/rules/reticle.mdc content, or null when absent.
+     *
+     * CONTENT, not existence. Gating on the file merely being there froze a Cursor project's rule at
+     * whatever release wrote it — so the CLAUDE.md path refreshed itself while the Cursor one never
+     * could, and a rule added later (`version_skew`) never reached a Cursor-only project at all.
+     */
+    cursorRuleContent?: string | null | undefined;
+    /** Current .claude/commands/reticle.md content, or null when absent (slash-command idempotency). */
+    claudeCommandContent?: string | null | undefined;
+    /** Current .cursor/commands/reticle.md content, or null when absent. */
+    cursorCommandContent?: string | null | undefined;
     options: {
         port: number | undefined;
         mcp: boolean;
@@ -126,4 +171,24 @@ export interface PlanInput {
         sdkVersion?: string;
     };
 }
+/**
+ * Every coding agent `reticle init` knows how to wire itself into, and the three surfaces it wires:
+ * the global MCP registration, the project rule file that makes the agent USE Reticle, and the
+ * `/reticle` command.
+ *
+ * One list, because those three surfaces used to enumerate Claude and Cursor separately in three
+ * places — so supporting a fourth agent meant finding all three and getting each right. Adding one
+ * is now an entry here plus its builders; each builder answers null when that agent is not present
+ * for this user or this project, which is also how "no agent detected" falls through to the
+ * cross-agent AGENTS.md.
+ *
+ * Deliberately functions rather than data: registering with Claude runs its CLI while Cursor merges
+ * a JSON file, and pretending those are the same shape would cost more than it saves.
+ */
+declare const AgentId: {
+    readonly CLAUDE: "claude";
+    readonly CURSOR: "cursor";
+};
+export type AgentId = (typeof AgentId)[keyof typeof AgentId];
 export declare function buildPlan(input: PlanInput): Plan;
+export {};