@reticlehq/server 2.4.0 → 2.5.0

package/dist/init/plan.js

@@ -6,10 +6,10 @@
 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 { 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,12 +27,12 @@ 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}`);
 }
 /** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export function frameworkPackages(framework) {
+function frameworkPackages(framework) {
     switch (framework) {
         case Framework.NEXT:
             return [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN];
@@ -44,6 +44,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 +55,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';
@@ -125,14 +150,19 @@ 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);
+    const steps = stepsForAgents(input, (a) => a.mcpStep);
     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 +173,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 +251,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 +269,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 +317,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 +348,14 @@ 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 was refused and the unpinned one worked. */
+function unpinnedRetryNote(version) {
+    const wanted = version === undefined ? 'the exact version' : version;
+    return (`the registry refused ${wanted} (pnpm's minimumReleaseAge holds new releases back), so the ` +
+        `newest ACCEPTED version was installed instead. That may not match the daemon — if the agent ` +
+        `reports protocol errors, check \`versionSkew\` in reticle_sessions, then either wait out the ` +
+        `window or allow these packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"`);
+}
 function installFailureHint(pm) {
     if (pm !== PackageManager.PNPM)
         return 'If the version was refused, install the SDK yourself.';
@@ -293,10 +388,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),
+        },
     };
 }
 function reticleConfigStep(input) {
-    if (input.reticleConfigExists === true) {
+    if (true === input.reticleConfigExists) {
         return {
             title: 'Reticle config',
             target: RETICLE_CONFIG_FILE,
@@ -348,12 +449,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

@@ -15,6 +15,11 @@ export interface InitOptions {
     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;
 }