@reticlehq/server 2.3.0 → 2.4.0

package/dist/init/plan.d.ts

@@ -4,6 +4,16 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, type Detection } from './detect.js';
+/**
+ * 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[];
 /** 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. */
@@ -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,13 @@ interface Step {
         args: string[];
         fallback: 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 +70,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). */
@@ -57,8 +83,25 @@ export interface PlanInput {
     } | null;
     /** 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;
     /** Whether .reticle.json already exists in the project root (idempotency). */
@@ -69,13 +112,18 @@ export interface PlanInput {
     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;
     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;
     };
 }
 export declare function buildPlan(input: PlanInput): Plan;
-export {};

package/dist/init/plan.js

@@ -3,12 +3,13 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { Framework, installCommand, installCommandParts } from './detect.js';
+import { Framework, PackageManager, UiLibrary, installCommand, installCommandParts, } from './detect.js';
 import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
+import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, } from './slash-command.js';
 import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
-import { patchViteConfig, VitePatchKind } from './vite-config.js';
-import { viteManual, htmlManual, NEXT_LAYOUT_MANUAL, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, reticleConfigContent, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, } from './snippets.js';
+import { viteSteps, nextSteps, svelteKitSteps, VITE_PLUGIN_DETAIL } from './plan-framework.js';
+import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote, astroManual, } from './snippets.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
 // framework adapter (it re-exports the browser sensor), paired with that framework's dev-only build
@@ -16,6 +17,20 @@ import { viteManual, htmlManual, NEXT_LAYOUT_MANUAL, nextReticleDevFile, NEXT_RE
 const RETICLE_REACT_KIT = '@reticlehq/react';
 const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
 const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
+/**
+ * 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 function pinnedPackages(packages, version) {
+    if (version === undefined || version.length === 0)
+        return packages;
+    return packages.map((p) => `${p}@${version}`);
+}
 /** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
 export function frameworkPackages(framework) {
     switch (framework) {
@@ -25,6 +40,10 @@ export function frameworkPackages(framework) {
         case Framework.SVELTEKIT:
             // SvelteKit builds on Vite; until a dedicated Svelte kit exists it uses the Vite build plugin.
             return [RETICLE_REACT_KIT, RETICLE_VITE_PLUGIN];
+        case Framework.ASTRO:
+            // Astro owns its own Vite instance and renders its own HTML, so there is no config for the
+            // plugin to attach to — the kit alone, connected from a page <script> (see astroManual).
+            return [RETICLE_REACT_KIT];
         case Framework.HTML:
             // No bundler plugin to install — just the kit; connect is wired by hand (see htmlManual).
             return [RETICLE_REACT_KIT];
@@ -40,6 +59,13 @@ export const StepStatus = {
     MANUAL: 'manual',
     ALREADY: 'already',
     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.
+     */
+    NOTICE: 'notice',
 };
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
 const CURSOR_MCP_TITLE = 'MCP server (Cursor, global)';
@@ -116,6 +142,37 @@ function mcpSteps(input) {
         },
     ];
 }
+const SLASH_COMMAND_TITLE = 'The /reticle command';
+/**
+ * `/reticle` — the entry point SKILL.md promises in three places and nothing ever created, so it
+ * silently did nothing in every tool. One file per agent that supports custom commands.
+ */
+function slashCommandSteps(input) {
+    const targets = [
+        { path: CLAUDE_COMMAND_PATH, when: input.claudeCli, exists: input.claudeCommandExists === true },
+        {
+            path: CURSOR_COMMAND_PATH,
+            when: input.cursorProjectPresent === true || (input.cursorPresent && !input.claudeCli),
+            exists: input.cursorCommandExists === true,
+        },
+    ];
+    return targets
+        .filter((t) => t.when)
+        .map((t) => t.exists
+        ? {
+            title: SLASH_COMMAND_TITLE,
+            target: t.path,
+            status: StepStatus.ALREADY,
+            detail: 'command already exists',
+        }
+        : {
+            title: SLASH_COMMAND_TITLE,
+            target: t.path,
+            status: StepStatus.APPLY,
+            detail: 'type /reticle to verify one flow in the browser',
+            write: { path: t.path, content: SLASH_COMMAND_BODY },
+        });
+}
 const AGENT_RULE_TITLE = 'Agent verification rule';
 const AGENT_RULE_DETAIL = 'teach the agent to verify features with Reticle after building them';
 function claudeRuleStep(input) {
@@ -138,9 +195,17 @@ function claudeRuleStep(input) {
         write: { path: CLAUDE_MD_PATH, content: r.content },
     };
 }
+/**
+ * The Cursor rule is a PROJECT file, so it is written only when Cursor plausibly works on THIS
+ * project — the repo has a `.cursor/` dir, or Cursor is the only agent found. `~/.cursor` merely
+ * existing on the machine meant every Claude Code user got an unexplained `.cursor/rules/reticle.mdc`
+ * committed into their repo. (Global MCP registration is different: it is global, and stays.)
+ */
 function cursorRuleStep(input) {
     if (!input.cursorPresent)
         return null;
+    if (input.cursorProjectPresent !== true && input.claudeCli)
+        return null;
     if (input.cursorRuleExists === true) {
         return {
             title: AGENT_RULE_TITLE,
@@ -186,9 +251,28 @@ function agentRuleSteps(input) {
             },
     ];
 }
+/**
+ * What to say when the install command fails.
+ *
+ * pnpm's `minimumReleaseAge` refuses any release younger than the configured window — a deliberate
+ * supply-chain policy, not a bug — with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Unpinned it silently
+ * resolves to an OLDER version instead, which is how an app ends up running a 2.2.1 SDK against a
+ * 2.3.0 daemon: the connection succeeds, the protocol disagrees, and the failure surfaces as -32000
+ * with nothing naming a version. Pinning turns that into this loud failure, which is the better
+ * trade — but only if the message says what to do about it.
+ */
+function installFailureHint(pm) {
+    if (pm !== PackageManager.PNPM)
+        return 'If the version was refused, install the SDK yourself.';
+    return ('If pnpm reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, its minimumReleaseAge setting is holding ' +
+        'this release back. Either wait out the window, or allow these packages explicitly:\n' +
+        '  pnpm config set minimumReleaseAgeExclude "@reticlehq/*"\n' +
+        'Do NOT drop the version pin — unpinned, pnpm installs an older SDK against a newer daemon, and ' +
+        'that mismatch surfaces as a -32000 with nothing naming a version.');
+}
 function installStep(input) {
     const pm = input.detection.packageManager;
-    const packages = frameworkPackages(input.detection.framework);
+    const packages = pinnedPackages(frameworkPackages(input.detection.framework), input.options.sdkVersion);
     const command = installCommand(pm, packages);
     if (!input.options.install) {
         return {
@@ -204,129 +288,12 @@ function installStep(input) {
         target: 'package.json',
         status: StepStatus.APPLY,
         detail: command,
-        exec: { command: parts.command, args: parts.args, fallback: command },
-    };
-}
-function viteSteps(input) {
-    const cfg = input.viteConfig;
-    const port = input.options.port;
-    if (cfg === null) {
-        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: 'add reticle() to plugins (also injects connect())',
-            write: { path: cfg.path, content: patch.code },
-        },
-    ];
-}
-function nextSteps(input) {
-    const configFile = input.nextConfigFile ?? 'next.config.mjs';
-    const devFile = input.nextReticleDevExists
-        ? {
-            title: 'ReticleDev component',
-            target: NEXT_RETICLE_DEV_PATH,
-            status: StepStatus.ALREADY,
-            detail: 'file exists',
-        }
-        : {
-            title: 'ReticleDev component',
-            target: NEXT_RETICLE_DEV_PATH,
-            status: StepStatus.APPLY,
-            detail: 'create dev-only connect component',
-            write: {
-                path: NEXT_RETICLE_DEV_PATH,
-                content: nextReticleDevFile(input.options.port, input.options.projectId),
-            },
-        };
-    return [
-        devFile,
-        {
-            title: 'Next config (withReticle)',
-            target: configFile,
-            status: StepStatus.MANUAL,
-            detail: nextConfigManual(configFile),
+        exec: {
+            command: parts.command,
+            args: parts.args,
+            fallback: `${command}\n\n${installFailureHint(pm)}`,
         },
-        {
-            title: 'Mount ReticleDev',
-            target: 'app/layout.tsx',
-            status: StepStatus.MANUAL,
-            detail: 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.
- */
-function svelteKitSteps(input) {
-    const unverified = {
-        title: 'SvelteKit is UNVERIFIED',
-        target: SVELTEKIT_HOOKS_PATH,
-        status: StepStatus.MANUAL,
-        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 (input.svelteKitHooksExists === true) {
-        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),
-            },
-        },
-    ];
 }
 function reticleConfigStep(input) {
     if (input.reticleConfigExists === true) {
@@ -346,10 +313,31 @@ function reticleConfigStep(input) {
         write: { path: RETICLE_CONFIG_FILE, content },
     };
 }
+/**
+ * A step that says out loud when the app isn't React. SvelteKit already carries its own unverified
+ * note, so it isn't doubled up here.
+ */
+function uiLibraryStep(input) {
+    const lib = input.detection.uiLibrary;
+    if (lib === UiLibrary.REACT || input.detection.framework === Framework.SVELTEKIT)
+        return [];
+    if (lib === UiLibrary.UNKNOWN)
+        return [];
+    return [
+        {
+            title: `${lib} is UNVERIFIED`,
+            target: 'package.json',
+            status: StepStatus.NOTICE,
+            detail: unverifiedUiLibraryNote(lib),
+        },
+    ];
+}
 export function buildPlan(input) {
     const steps = [
         ...mcpSteps(input),
         ...agentRuleSteps(input),
+        ...slashCommandSteps(input),
+        ...uiLibraryStep(input),
         installStep(input),
         reticleConfigStep(input),
     ];
@@ -359,8 +347,20 @@ export function buildPlan(input) {
     else if (input.detection.framework === Framework.NEXT) {
         steps.push(...nextSteps(input));
     }
+    else if (input.detection.framework === Framework.ASTRO) {
+        steps.push({
+            title: 'Connect snippet (Astro)',
+            target: 'astro.config + layout',
+            status: StepStatus.MANUAL,
+            detail: astroManual(input.options.port, input.options.projectId),
+        });
+    }
     else if (input.detection.framework === Framework.SVELTEKIT) {
         steps.push(...svelteKitSteps(input));
+        // The Vite plugin as well as the client hook. `init` already INSTALLS @reticlehq/vite-plugin for
+        // SvelteKit and then never wired it into the config, so it sat in package.json doing nothing —
+        // which is why a SvelteKit app connected fine and every verdict came back with no file:line.
+        steps.push(...viteSteps(input, VITE_PLUGIN_DETAIL.SVELTEKIT));
     }
     else {
         steps.push({

package/dist/init/run.d.ts

@@ -15,6 +15,8 @@ export interface InitOptions {
     mcp: boolean;
     dryRun: boolean;
     install: boolean;
+    /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
+    redirected?: boolean;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -26,6 +28,12 @@ export interface InitIo {
     homeDir(): string;
     /** Basenames present in the project root. */
     rootFiles(): readonly string[];
+    /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
+    listDirs(relPath: string): readonly string[];
+    /** File (non-directory) basenames inside a project-relative directory, including dotfiles. */
+    listFiles(relPath: string): readonly string[];
+    /** The same IO re-rooted at a project-relative subdirectory (used for the workspace redirect). */
+    scoped(relPath: string): InitIo;
     /** Runs a subprocess to completion (inherits stdio); returns true on exit code 0. */
     exec(command: string, args: readonly string[]): boolean;
     /** Runs a subprocess quietly (no stdio) for a yes/no check; returns true on exit code 0. */
@@ -37,5 +45,14 @@ interface InitResult {
     applied: number;
     manual: number;
 }
+/**
+ * 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 declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
 export {};