@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/plan.js

@@ -6,10 +6,11 @@
 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 { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
+import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
 import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
-import { viteSteps, nextSteps, svelteKitSteps, VITE_PLUGIN_DETAIL } from './plan-framework.js';
-import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote, astroManual, } from './snippets.js';
+import { viteSteps, nextSteps, craSteps, svelteKitSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } 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
@@ -27,7 +28,7 @@ const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export function pinnedPackages(packages, version) {
-    if (version === undefined || version.length === 0)
+    if (version === undefined || 0 === version.length)
         return packages;
     return packages.map((p) => `${p}@${version}`);
 }
@@ -44,6 +45,10 @@ export function frameworkPackages(framework) {
             // 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.CRA:
+            // react-scripts owns its webpack config and cannot be extended without ejecting, so there is
+            // no build plugin — the kit alone, imported from src/index.tsx (see cra.ts).
+            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];
@@ -51,6 +56,27 @@ export function frameworkPackages(framework) {
 }
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export const MCP_TARGET = 'global (claude user scope)';
+/**
+ * Titles of the steps WITHOUT which no session ever appears.
+ *
+ * A ⚠ on one of these is not a warning, it is a guaranteed failure: nothing performs the manual step,
+ * so the app will not connect and every Reticle tool will answer "no browser session connected".
+ * Reported from a field sweep, where the ⚠ count and "did it connect" were treated as independent
+ * signals and are not.
+ */
+const CONNECT_STEP_TITLES = new Set([
+    'Connect snippet',
+    'Connect snippet (CRA)',
+    'Connect snippet (Astro)',
+    'Reticle client hook',
+    'Reticle connect module',
+    'ReticleDev component',
+    'Vite plugin',
+]);
+/** True when this step is what makes the app dial the daemon. */
+export function isConnectStep(title) {
+    return CONNECT_STEP_TITLES.has(title);
+}
 /** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
 export const DEPS_TARGET = 'package.json';
 const RETICLE_CONFIG_FILE = '.reticle.json';
@@ -117,6 +143,49 @@ function cursorMcpStep(input) {
         write: { path: input.cursorConfigPath, content: r.content },
     };
 }
+/**
+ * One step per OTHER detected client.
+ *
+ * The shapes differ enough that a shared "write mcp.json" would be wrong for three of them — see
+ * mcp-clients.ts. What is shared is the DECISION: already-correct is left alone, a file we cannot
+ * parse is reported with a paste-able block rather than overwritten, and everything else is written.
+ */
+function otherClientSteps(input) {
+    const steps = [];
+    for (const detected of input.detectedClients ?? []) {
+        const spec = clientSpec(detected.id);
+        const merged = mergeClientConfig(spec, detected.existing);
+        const title = `MCP server (${spec.label})`;
+        if (merged.status === ClientMergeStatus.ALREADY) {
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.ALREADY,
+                detail: `reticle already registered with ${spec.label}`,
+            });
+            continue;
+        }
+        if (merged.status === ClientMergeStatus.MANUAL) {
+            // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
+            // end the same way: say so, and hand over the exact block.
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.MANUAL,
+                detail: `add this to ${detected.configPath} by hand:\n${clientSnippet(spec)}`,
+            });
+            continue;
+        }
+        steps.push({
+            title,
+            target: detected.configPath,
+            status: StepStatus.APPLY,
+            detail: `register reticle with ${spec.label}`,
+            write: { path: detected.configPath, content: merged.content },
+        });
+    }
+    return steps;
+}
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
     if (!input.options.mcp) {
@@ -125,14 +194,22 @@ function mcpSteps(input) {
                 title: 'MCP server (global)',
                 target: MCP_TARGET,
                 status: StepStatus.SKIP,
-                detail: '--no-mcp',
+                // Names everything it turns off. `--no-mcp` reads like "skip one step" and skips three: the
+                // registration, the agent rule files, and the /reticle command. A gate running with this flag
+                // therefore covers far less than its name suggests, which is worth saying out loud.
+                detail: '--no-mcp — also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command',
             },
         ];
     }
-    const steps = [claudeMcpStep(input), cursorMcpStep(input)].filter((s) => s !== null);
+    // Claude and Cursor first (they have their own registration paths), then every other detected
+    // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
+    // how a user ends up with Reticle in the editor they were not using.
+    const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
     if (steps.length > 0)
         return steps;
-    // No supported agent detected — print the one-time global instructions.
+    // No supported agent detected — print the one-time global instructions. Reached when the `claude`
+    // CLI is absent AND ~/.cursor does not exist, which includes Cursor installed with a fresh profile
+    // that has not written its config directory yet, so the manual text covers both agents.
     return [
         {
             title: 'MCP server (global)',
@@ -143,35 +220,50 @@ function mcpSteps(input) {
     ];
 }
 const SLASH_COMMAND_TITLE = 'The /reticle command';
+/**
+ * Nothing to do for this command file: it already holds the CURRENT body, or it is not ours at all.
+ *
+ * Gating on mere existence froze the command at whatever release wrote it. Rewriting anything found
+ * there would be worse — a human may have claimed `/reticle` for their own prompt — so a file without
+ * our signature is left exactly as it is.
+ */
+function commandIsSettled(content) {
+    if (null === content || content === undefined)
+        return false;
+    return content === SLASH_COMMAND_BODY || !content.includes(SLASH_COMMAND_SIGNATURE);
+}
 /**
  * `/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.
+ * silently did nothing in every tool.
+ *
+ * CURRENT, not merely present — same reason as the Cursor rule: a command file frozen at whatever
+ * release created it is a command that can never be improved for anyone who already ran init. The
+ * whole file is Reticle's, so a stale one is rewritten.
  */
-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
+function commandStepFor(path, present, content) {
+    if (!present)
+        return null;
+    return commandIsSettled(content)
         ? {
             title: SLASH_COMMAND_TITLE,
-            target: t.path,
+            target: path,
             status: StepStatus.ALREADY,
             detail: 'command already exists',
         }
         : {
             title: SLASH_COMMAND_TITLE,
-            target: t.path,
+            target: path,
             status: StepStatus.APPLY,
             detail: 'type /reticle to verify one flow in the browser',
-            write: { path: t.path, content: SLASH_COMMAND_BODY },
-        });
+            write: { path, content: SLASH_COMMAND_BODY },
+        };
+}
+function claudeCommandStep(input) {
+    return commandStepFor(CLAUDE_COMMAND_PATH, input.claudeCli, input.claudeCommandContent);
+}
+function cursorCommandStep(input) {
+    const present = true === input.cursorProjectPresent || (input.cursorPresent && !input.claudeCli);
+    return commandStepFor(CURSOR_COMMAND_PATH, present, input.cursorCommandContent);
 }
 const AGENT_RULE_TITLE = 'Agent verification rule';
 const AGENT_RULE_DETAIL = 'teach the agent to verify features with Reticle after building them';
@@ -206,7 +298,9 @@ function cursorRuleStep(input) {
         return null;
     if (input.cursorProjectPresent !== true && input.claudeCli)
         return null;
-    if (input.cursorRuleExists === true) {
+    // The whole file is Reticle's — init created it — so a stale one is REWRITTEN rather than merged.
+    // Comparing content is what makes the rule updatable; comparing existence made it permanent.
+    if (input.cursorRuleContent === cursorRuleFile()) {
         return {
             title: AGENT_RULE_TITLE,
             target: CURSOR_RULE_PATH,
@@ -222,6 +316,46 @@ function cursorRuleStep(input) {
         write: { path: CURSOR_RULE_PATH, content: cursorRuleFile() },
     };
 }
+/**
+ * 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.
+ */
+const AgentId = {
+    CLAUDE: 'claude',
+    CURSOR: 'cursor',
+};
+const AGENT_INTEGRATIONS = [
+    {
+        id: AgentId.CLAUDE,
+        mcpStep: claudeMcpStep,
+        ruleStep: claudeRuleStep,
+        commandStep: claudeCommandStep,
+    },
+    {
+        id: AgentId.CURSOR,
+        mcpStep: cursorMcpStep,
+        ruleStep: cursorRuleStep,
+        commandStep: cursorCommandStep,
+    },
+];
+/** The steps one surface contributes across every known agent, in registry order. */
+function stepsForAgents(input, surface) {
+    return AGENT_INTEGRATIONS.map((a) => surface(a)(input)).filter((s) => s !== null);
+}
+/** The `/reticle` command file for every agent that has a command surface and is present here. */
+function slashCommandSteps(input) {
+    return stepsForAgents(input, (a) => a.commandStep);
+}
 /**
  * The behavioral rule that makes the agent actually USE Reticle. Written into the detected agent's
  * instruction file (Claude / Cursor, or both), falling back to the cross-agent AGENTS.md when neither
@@ -230,7 +364,7 @@ function cursorRuleStep(input) {
 function agentRuleSteps(input) {
     if (!input.options.mcp)
         return [];
-    const detected = [claudeRuleStep(input), cursorRuleStep(input)].filter((s) => s !== null);
+    const detected = stepsForAgents(input, (a) => a.ruleStep);
     if (detected.length > 0)
         return detected;
     const r = mergeMarkedInstruction(input.agentsMdContent);
@@ -261,6 +395,31 @@ function agentRuleSteps(input) {
  * 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.
  */
+/**
+ * Said out loud when the exact-version install failed and the unpinned one worked.
+ *
+ * It used to assert a cause it cannot know. Every one of nine fixture apps got the same sentence —
+ * "the registry refused 2.5.0 (pnpm's minimumReleaseAge holds new releases back)" — when the actual
+ * cause on that run was that the version did not exist yet, and the remedy offered was a `pnpm
+ * config` command handed to a yarn 1 project that will never read it.
+ *
+ * This note is built at PLAN time, before anything runs, and `io.exec` returns a bare boolean, so
+ * the apply layer has no failure text to hand back either. The honest move is therefore to report
+ * the CONSEQUENCE (which is certain and is the part that bites) and offer the remedy that belongs to
+ * the manager actually in use — rather than name a cause that is one possibility among several.
+ */
+function unpinnedRetryNote(version, pm) {
+    const wanted = version === undefined ? 'the exact version' : version;
+    // Kept verbatim for pnpm, where minimumReleaseAge is a real and common cause with a real remedy.
+    const remedy = pm === PackageManager.PNPM
+        ? ' One common cause on pnpm is minimumReleaseAge holding a new release back; if pnpm ' +
+            'reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, either wait out the window or allow these ' +
+            'packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"'
+        : '';
+    return (`the pinned install of ${wanted} failed, so the newest version the registry WOULD accept was ` +
+        `installed instead. That may not match the daemon — if the agent reports protocol errors, check ` +
+        `\`versionSkew\` in reticle_sessions.${remedy}`);
+}
 function installFailureHint(pm) {
     if (pm !== PackageManager.PNPM)
         return 'If the version was refused, install the SDK yourself.';
@@ -293,10 +452,16 @@ function installStep(input) {
             args: parts.args,
             fallback: `${command}\n\n${installFailureHint(pm)}`,
         },
+        // Unpinned. pnpm resolves the newest MATURE version there, which is how a project with a
+        // release-age hold gets a working install instead of no install.
+        retry: {
+            ...installCommandParts(pm, frameworkPackages(input.detection.framework)),
+            note: unpinnedRetryNote(input.options.sdkVersion, pm),
+        },
     };
 }
 function reticleConfigStep(input) {
-    if (input.reticleConfigExists === true) {
+    if (true === input.reticleConfigExists) {
         return {
             title: 'Reticle config',
             target: RETICLE_CONFIG_FILE,
@@ -348,12 +513,10 @@ export function buildPlan(input) {
         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),
-        });
+        steps.push(...astroSteps(input));
+    }
+    else if (input.detection.framework === Framework.CRA) {
+        steps.push(...craSteps(input));
     }
     else if (input.detection.framework === Framework.SVELTEKIT) {
         steps.push(...svelteKitSteps(input));

package/dist/init/project-id.d.ts

@@ -1,16 +1,12 @@
 /**
- * Project-identity derivation for `reticle init` — the Next/HTML/.reticle.json side of the same scheme the
- * Vite plugin uses at build time. Kept algorithmically identical (slug of package.json name + 8-char
- * hash of the absolute root) so a Vite app's plugin-stamped projectId matches what init records.
+ * Project-identity for `reticle init` — the `.reticle.json` side of the scheme the Vite plugin
+ * stamps at build time. The RULE lives in `@reticlehq/core` (projectIdFrom) so both sides spell the
+ * id the same way by construction; this file supplies only the Node-only hashing it needs.
  */
-/** `@acme/web` → `acme-web`; non-alphanumerics collapse to single dashes; edges trimmed. */
-export declare function slugifyPackageName(name: string): string;
+export { slugifyPackageName } from '@reticlehq/core';
 /** Short, stable hex fingerprint of the absolute project root. */
 export declare function shortHash(input: string): string;
-/**
- * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
- * Falls back to the root folder name, then "app". Pure.
- */
+/** Derive the stable projectId from the package name (may be undefined) and the absolute root path. */
 export declare function deriveProjectId(pkgName: string | undefined, rootPath: string): string;
 /** Pull a string `name` out of an already-parsed package.json object, or undefined. */
 export declare function packageName(pkg: unknown): string | undefined;

package/dist/init/project-id.js

@@ -1,36 +1,24 @@
 /**
- * Project-identity derivation for `reticle init` — the Next/HTML/.reticle.json side of the same scheme the
- * Vite plugin uses at build time. Kept algorithmically identical (slug of package.json name + 8-char
- * hash of the absolute root) so a Vite app's plugin-stamped projectId matches what init records.
+ * Project-identity for `reticle init` — the `.reticle.json` side of the scheme the Vite plugin
+ * stamps at build time. The RULE lives in `@reticlehq/core` (projectIdFrom) so both sides spell the
+ * id the same way by construction; this file supplies only the Node-only hashing it needs.
  */
 import { createHash } from 'node:crypto';
-import { basename } from 'node:path';
-/** `@acme/web` → `acme-web`; non-alphanumerics collapse to single dashes; edges trimmed. */
-export function slugifyPackageName(name) {
-    return name
-        .toLowerCase()
-        .replace(/^@/, '')
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
+import { PROJECT_ID_HASH_LENGTH, projectIdFrom } from '@reticlehq/core';
+export { slugifyPackageName } from '@reticlehq/core';
 /** Short, stable hex fingerprint of the absolute project root. */
 export function shortHash(input) {
-    return createHash('sha1').update(input).digest('hex').slice(0, 8);
+    return createHash('sha1').update(input).digest('hex').slice(0, PROJECT_ID_HASH_LENGTH);
 }
-/**
- * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
- * Falls back to the root folder name, then "app". Pure.
- */
+/** Derive the stable projectId from the package name (may be undefined) and the absolute root path. */
 export function deriveProjectId(pkgName, rootPath) {
-    const fromName = pkgName !== undefined ? slugifyPackageName(pkgName) : '';
-    const base = fromName.length > 0 ? fromName : slugifyPackageName(basename(rootPath)) || 'app';
-    return `${base}-${shortHash(rootPath)}`;
+    return projectIdFrom(pkgName, rootPath, shortHash);
 }
 /** Pull a string `name` out of an already-parsed package.json object, or undefined. */
 export function packageName(pkg) {
-    if (typeof pkg === 'object' && pkg !== null) {
+    if ('object' === typeof pkg && pkg !== null) {
         const name = pkg['name'];
-        if (typeof name === 'string' && name.length > 0)
+        if ('string' === typeof name && name.length > 0)
             return name;
     }
     return undefined;

package/dist/init/run.d.ts

@@ -7,14 +7,26 @@
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
  * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
  * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
+ *
+ * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
+ * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
+ * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
+ * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
+ * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
+ * tree — it is a deliberate statement about this package, not an inheritance.
  */
-export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>): Set<string>;
+export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;
 export interface InitOptions {
     cwd: string;
     port: number | undefined;
     mcp: boolean;
     dryRun: boolean;
     install: boolean;
+    /**
+     * Which app in a monorepo to wire, when several are found. Without it `init` refuses to guess, and
+     * "re-run inside the one you want" is not an instruction a script or an agent can follow.
+     */
+    app?: string;
     /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
     redirected?: boolean;
 }
@@ -54,5 +66,15 @@ interface InitResult {
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
 export {};