@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/node-io.js

@@ -4,9 +4,33 @@
  * 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';
+import { windowsShellArg } from './windows-quote.js';
+/**
+ * `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 or interpret. Windows only, where
+ * `shell: true` is required (see shellOpt). The rule itself lives in windows-quote.ts as a pure
+ * function so it can be tested on every platform — keeping it inside this branch is why it was
+ * wrong for as long as it was.
+ */
+function shellSafe(args) {
+    if (process.platform !== NodePlatform.WINDOWS)
+        return [...args];
+    return args.map(windowsShellArg);
+}
 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 +88,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, CRA_TOKEN_PER_MACHINE_NOTICE, 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,10 @@ 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';
+    const nothingToRegister = 0 === testids.length && 0 === stores.length;
     return [
         {
             title: CAPABILITIES_TITLE,
@@ -51,6 +56,28 @@ function capabilitiesStep(input) {
             write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
             dependsOnInstall: true,
         },
+        // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
+        // stores: [] })` registers nothing, so `hasCapabilities` stays false — correctly — and the ✓
+        // above reads as if the feature is on. Reported as exactly that confusion: "hasCapabilities false
+        // on every session while init said ✓ Capabilities + store".
+        //
+        // Beside the write rather than replacing it, for two reasons: only APPLY steps are written
+        // (run.ts), and SKILL.md tells the reader to skip ✓ lines — so a caveat carried on the ✓ is a
+        // caveat nobody reads.
+        ...(nothingToRegister
+            ? [
+                {
+                    title: 'Capabilities are empty until you edit that file',
+                    target: VITE_DEV_MODULE_PATH,
+                    status: StepStatus.NOTICE,
+                    detail: 'the module was written but registers nothing — no data-testid values were found and ' +
+                        'no state library was detected, so `hasCapabilities` stays false and reticle_state ' +
+                        'has nothing to read. Add data-testid to the elements your main flow touches, or ' +
+                        'register a store in that file, and the agent gains what the app BELIEVES rather than ' +
+                        'only what it rendered.',
+                },
+            ]
+            : []),
     ];
 }
 export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE) {
@@ -61,7 +88,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 +181,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 +207,90 @@ 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 },
+        });
+        // Beside the write, not inside it. A ✓ line is one SKILL.md tells the reader to skip, and this
+        // is the fact that decides whether the install works for anyone but the person running it.
+        steps.push({
+            title: 'Pairing token is per-machine',
+            target: CRA_ENV_PATH,
+            status: StepStatus.NOTICE,
+            detail: CRA_TOKEN_PER_MACHINE_NOTICE,
+        });
+    }
+    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,
+            // `reticle serve`, not `reticle start` — the latter is not a verb this CLI dispatches, and
+            // this message is read by someone whose app boots and never pairs. Handing them a command
+            // that errors is a second dead end on the first.
+            detail: `no pairing token yet — the daemon writes one on first run. Start it with \`reticle serve\` (or let your agent run \`reticle mcp\`), 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 +300,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 +326,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

@@ -4,6 +4,7 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, type Detection } from './detect.js';
+import { type McpClient } from './mcp-clients.js';
 /**
  * Pin the SDK to the CLI's own version.
  *
@@ -18,6 +19,8 @@ export declare function pinnedPackages(packages: readonly string[], version: str
 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 +53,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
@@ -76,11 +93,38 @@ export interface PlanInput {
     cursorConfig: string | null;
     /** Absolute path of ~/.cursor/mcp.json (the write target). */
     cursorConfigPath: string;
+    /**
+     * Every OTHER MCP client detected on this machine, with its config path and current content.
+     *
+     * Claude Code and Cursor keep their own steps — Claude registers through its CLI, and Cursor's
+     * predates this. Everything else is uniform: read the file, merge, write.
+     */
+    detectedClients?: readonly {
+        id: McpClient;
+        configPath: string;
+        existing: string | null;
+    }[] | undefined;
     /** Discovered Vite config: its path + source, or null if none found. */
     viteConfig: {
         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 +148,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 +185,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 {};