@reticlehq/server 2.3.0 → 2.5.0

package/dist/init/plan-framework.js

@@ -0,0 +1,341 @@
+/**
+ * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
+ * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
+ * this one is the per-framework detail, and they grow for different reasons.
+ */
+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, 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 = {
+    /** A plain Vite app gets both halves from the plugin. */
+    VITE: 'add reticle() to plugins (also injects connect())',
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    SVELTEKIT: 'add reticle() to plugins (stamps data-reticle-source in .svelte components)',
+};
+const CAPABILITIES_TITLE = 'Capabilities + store';
+/**
+ * The dev module carrying `registerCapabilities` / `registerStore`.
+ *
+ * Without it every app came up `hasCapabilities: false` with a `reticle_state` holding nothing but
+ * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
+ * only when absent, because it is the one generated file a user is expected to EDIT.
+ */
+function capabilitiesStep(input) {
+    if (true === input.viteDevModuleExists) {
+        return [
+            {
+                title: CAPABILITIES_TITLE,
+                target: VITE_DEV_MODULE_PATH,
+                status: StepStatus.ALREADY,
+                detail: 'file exists — left alone, it is yours to edit',
+            },
+        ];
+    }
+    const testids = input.testids ?? [];
+    const stores = input.storeHints ?? [];
+    const found = testids.length > 0
+        ? `${String(testids.length)} data-testid values`
+        : 'no data-testid values yet';
+    return [
+        {
+            title: CAPABILITIES_TITLE,
+            target: VITE_DEV_MODULE_PATH,
+            status: StepStatus.APPLY,
+            detail: `${found}; ${stores.length > 0 ? `store: uncomment the ${String(stores.length)} suggested line(s)` : 'no state library detected'}`,
+            write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
+            dependsOnInstall: true,
+        },
+    ];
+}
+export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE) {
+    // Capabilities are independent of whether the config needed patching. Attaching them to the APPLY
+    // branch meant a re-run on an already-wired app silently never created the module.
+    return [...viteConfigSteps(input, detail), ...capabilitiesStep(input)];
+}
+function viteConfigSteps(input, detail) {
+    const cfg = input.viteConfig;
+    const port = input.options.port;
+    if (null === cfg) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: 'vite.config',
+                status: StepStatus.MANUAL,
+                detail: viteManual(port),
+            },
+        ];
+    }
+    const patch = patchViteConfig(cfg.source, port);
+    if (patch.kind === VitePatchKind.ALREADY) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: cfg.path,
+                status: StepStatus.ALREADY,
+                detail: 'reticle() already in plugins',
+            },
+        ];
+    }
+    if (patch.kind === VitePatchKind.MANUAL) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: cfg.path,
+                status: StepStatus.MANUAL,
+                detail: `${patch.reason}\n\n${viteManual(port)}`,
+            },
+        ];
+    }
+    return [
+        {
+            title: 'Vite plugin',
+            target: cfg.path,
+            status: StepStatus.APPLY,
+            detail,
+            write: { path: cfg.path, content: patch.code },
+            dependsOnInstall: true,
+        },
+    ];
+}
+/**
+ * Turn a conservative source patch into a step: applied when it patched, already when the wiring is
+ * there, and the hand-edit instructions when the file shape wasn't one we recognise.
+ */
+function patchStep(title, path, patch, applyDetail, manualDetail) {
+    if (patch.kind === PatchKind.ALREADY) {
+        return { title, target: path, status: StepStatus.ALREADY, detail: 'already wired' };
+    }
+    if (patch.kind === PatchKind.MANUAL) {
+        return {
+            title,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${patch.reason}\n\n${manualDetail}`,
+        };
+    }
+    return {
+        title,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: applyDetail,
+        write: { path, content: patch.code },
+        dependsOnInstall: true,
+    };
+}
+/**
+ * Next used to be the ONLY stack with hand edits left over — and both of them fail silently when
+ * skipped, so a Next user's app booted, connected to nothing, and said nothing about why. Both are
+ * now patched by the same conservative rules the Vite config gets.
+ */
+export function nextSteps(input) {
+    const configFile = input.nextConfigFile ?? 'next.config.mjs';
+    const devPath = input.nextReticleDevPath ?? NEXT_RETICLE_DEV_PATH;
+    const devFile = input.nextReticleDevExists
+        ? {
+            title: 'ReticleDev component',
+            target: devPath,
+            status: StepStatus.ALREADY,
+            detail: 'file exists',
+        }
+        : {
+            title: 'ReticleDev component',
+            target: devPath,
+            status: StepStatus.APPLY,
+            detail: 'create dev-only connect component',
+            write: {
+                path: devPath,
+                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? []),
+            },
+            dependsOnInstall: true,
+        };
+    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 = null === layout
+        ? { kind: PatchKind.MANUAL, reason: 'no root layout (app/layout.tsx) or pages/_app found' }
+        : isPagesRouter
+            ? patchPagesApp(layout.source, input.nextReticleDevImport)
+            : patchRootLayout(layout.source);
+    return [
+        devFile,
+        patchStep('Next config (withReticle)', configFile, configPatch, 'wrap the export in withReticle (source mapping, dev-only)', nextConfigManual(configFile)),
+        patchStep('Mount ReticleDev', layout?.path ?? NEXT_LAYOUT_PATH, layoutPatch, 'mount <ReticleDev /> in the root layout (dev-only)', NEXT_LAYOUT_MANUAL),
+    ];
+}
+/**
+ * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.
+ *
+ * There is no SvelteKit app in `apps/` and no CI gate for one, so nothing proves this hook still
+ * registers a session — every other framework init offers (React, Next, Remix, Astro) has both. The
+ * 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',
+        target: SVELTEKIT_HOOKS_PATH,
+        status: StepStatus.NOTICE,
+        detail: UNVERIFIED_FRAMEWORK_NOTE,
+    };
+    // 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 (true === input.svelteKitHooksExists) {
+        return [
+            unverified,
+            {
+                title: 'Reticle client hook',
+                target: SVELTEKIT_HOOKS_PATH,
+                status: StepStatus.ALREADY,
+                detail: 'file exists',
+            },
+        ];
+    }
+    return [
+        unverified,
+        {
+            title: 'Reticle client hook',
+            target: SVELTEKIT_HOOKS_PATH,
+            status: StepStatus.APPLY,
+            detail: 'create dev-only client connect (SvelteKit renders via app.html)',
+            write: {
+                path: SVELTEKIT_HOOKS_PATH,
+                content: svelteKitHooksFile(input.options.port, input.options.projectId),
+            },
+            dependsOnInstall: true,
+        },
+    ];
+}
+/**
+ * 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,10 +4,20 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, type Detection } from './detect.js';
-/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export declare function frameworkPackages(framework: Framework): readonly string[];
+/**
+ * Pin the SDK to the CLI's own version.
+ *
+ * `pnpm add -D @reticlehq/react` installed **2.2.1** in one project while npm and yarn took 2.3.0 in
+ * the next — a stale registry metadata cache, invisible to the user and to us. A version-skewed SDK
+ * talking to a newer daemon is the `-32000` failure path: the app connects, the protocol disagrees,
+ * and nothing on either side names a version. Asking for the CLI's exact version makes the cache
+ * irrelevant, and a skewed pair impossible to install by accident.
+ */
+export declare function pinnedPackages(packages: readonly string[], version: string | undefined): 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: {
@@ -15,9 +25,16 @@ export declare const StepStatus: {
     readonly MANUAL: "manual";
     readonly ALREADY: "already";
     readonly SKIP: "skip";
+    /**
+     * Something the user should KNOW, not something they must DO. The UNVERIFIED lines are the case:
+     * a Preact or SvelteKit app is wired and working, it just isn't covered by a gate. Reporting those
+     * as `manual` made "steps left to do" a number that could never reach zero, and made a release gate
+     * read two regressions that were not regressions.
+     */
+    readonly NOTICE: "notice";
 };
 export type StepStatus = (typeof StepStatus)[keyof typeof StepStatus];
-interface Step {
+export interface Step {
     title: string;
     target: string;
     status: StepStatus;
@@ -33,6 +50,27 @@ 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
+     * `@reticlehq/next` took a dev server down exactly this way. Installing Reticle must never be the
+     * reason an app stops booting.
+     */
+    dependsOnInstall?: boolean;
 }
 export interface Plan {
     framework: Framework;
@@ -46,6 +84,8 @@ export interface PlanInput {
     mcpExists: boolean;
     /** Whether Cursor is installed for this user (its global config dir exists). */
     cursorPresent: boolean;
+    /** Whether THIS project has a .cursor/ directory — the signal that Cursor works on this repo. */
+    cursorProjectPresent?: boolean | undefined;
     /** Current ~/.cursor/mcp.json content, or null if absent. */
     cursorConfig: string | null;
     /** Absolute path of ~/.cursor/mcp.json (the write target). */
@@ -55,27 +95,100 @@ 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;
-    /** Whether app/reticle-dev.tsx already exists. */
+    /** Source of that Next config, so the export can be wrapped in withReticle. */
+    nextConfigSource?: string | null | undefined;
+    /** Discovered Next root layout: its path + source, or null (App Router only). */
+    nextLayout?: {
+        path: string;
+        source: string;
+    } | null | undefined;
+    /** Where the dev-only connect component goes — never inside `pages/`, which routes on presence. */
+    nextReticleDevPath?: string | undefined;
+    /** What the mount file should import — a sibling for App Router, `../components/…` for Pages. */
+    nextReticleDevImport?: string | undefined;
+    /** Whether the ReticleDev component file already exists. */
     nextReticleDevExists: boolean;
+    /** `data-testid` values scanned from the app's source, for the generated capabilities block. */
+    testids?: readonly string[] | undefined;
+    /** Ready-to-uncomment `registerStore` lines for the state libraries the app actually depends on. */
+    storeHints?: readonly string[] | undefined;
+    /** Whether src/reticle-dev.ts already exists — it is the one generated file users are meant to edit. */
+    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;
+    /**
+     * 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;
         install: boolean;
         /** Stable project identity derived at init (package.json name + root). Baked into snippets/.reticle.json. */
         projectId?: string;
+        /** The CLI's own version, pinned onto the SDK install so a stale registry cache cannot skew it. */
+        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 {};