@reticlehq/server 2.6.0 → 2.8.0

package/dist/init/plan.js

@@ -8,14 +8,18 @@ import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.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, craSteps, svelteKitSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
+import { viteSteps, nextSteps, craSteps, svelteKitSteps, nuxtSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { join } from 'node:path';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
+import { devServerPortWarning, isLikelyDevServerPort } from '../cli/cli-port.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
 // plugin for source mapping + connect injection.
 const RETICLE_REACT_KIT = '@reticlehq/react';
+/** The framework-neutral sensor, for stacks the React adapter has nothing to attach to. */
+const RETICLE_BROWSER_SDK = '@reticlehq/browser';
 const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
 const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
 /**
@@ -32,26 +36,56 @@ export function pinnedPackages(packages, version) {
         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) {
+/**
+ * Does this codebase want the React kit, or the framework-neutral sensor?
+ *
+ * The kit is what adds component identity — component names and stacks — and it is worth having
+ * wherever React or Preact is rendering (the adapter reaches Preact through `preact/compat`).
+ * Everywhere else it is a package named `@reticlehq/react`, carrying `react` in its peer
+ * dependencies, being installed into a codebase that has no React in it.
+ *
+ * UNKNOWN keeps the kit deliberately. Absence of evidence is not evidence of Vue, and guessing
+ * "sensor" on no information silently drops component identity from apps that should have it.
+ */
+function wantsReactKit(ui) {
+    return ui !== UiLibrary.VUE && ui !== UiLibrary.SVELTE;
+}
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
+    const kit = wantsReactKit(uiLibrary) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
     switch (framework) {
         case Framework.NEXT:
+            // Next is React by construction, so the detection cannot disagree in a way worth honouring.
             return [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN];
         case Framework.VITE:
         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];
+            // The build plugin stamps `data-reticle-source` regardless of UI library, so a Vue or Svelte
+            // app still gets source pointers — it is only component identity that needs the React kit.
+            return [kit, RETICLE_VITE_PLUGIN];
+        case Framework.NUXT:
+            // The framework-neutral sensor, NOT the React kit. Nuxt renders Vue, and installing a package
+            // named @reticlehq/react — with `react` in its peer dependencies — into a Vue codebase is the
+            // single thing most likely to make someone abandon the setup, whether or not it works.
+            return [RETICLE_BROWSER_SDK];
         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];
+            return [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];
+            return [kit];
     }
 }
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
@@ -68,6 +102,7 @@ const CONNECT_STEP_TITLES = new Set([
     'Connect snippet',
     'Connect snippet (CRA)',
     'Connect snippet (Astro)',
+    'Connect snippet (Nuxt)',
     'Reticle client hook',
     'Reticle connect module',
     'ReticleDev component',
@@ -93,6 +128,19 @@ export const StepStatus = {
      */
     NOTICE: 'notice',
 };
+/**
+ * Where the agent-facing files go, which is not always where the app is.
+ *
+ * Reported from the field (#318): a repo with its app at `src/admin` got `.claude/commands/reticle.md`
+ * written into the app directory, while the human's agent session runs at the repo root — so
+ * `/reticle` did not exist for them at all until they copied it up by hand. The rule and command
+ * files are read by the AGENT, so they belong where the agent stands; the app files stay with the
+ * app. The two are the same directory in a single-package repo, which is why this went unnoticed.
+ */
+function agentFile(input, relPath) {
+    const root = input.agentFileRoot;
+    return root === undefined || 0 === root.length ? relPath : join(root, relPath);
+}
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
 const CURSOR_MCP_TITLE = 'MCP server (Cursor, global)';
 function claudeMcpStep(input) {
@@ -259,32 +307,35 @@ function commandStepFor(path, present, content) {
         };
 }
 function claudeCommandStep(input) {
-    return commandStepFor(CLAUDE_COMMAND_PATH, input.claudeCli, input.claudeCommandContent);
+    return commandStepFor(agentFile(input, 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);
+    return commandStepFor(agentFile(input, 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';
+const RETICLE_MD_TITLE = 'Full agent rules';
+const RETICLE_MD_DETAIL = 'the reference the always-loaded rule points at (when NOT to verify, recovery, feedback)';
 function claudeRuleStep(input) {
     if (!input.claudeCli)
         return null;
+    const path = agentFile(input, CLAUDE_MD_PATH);
     const r = mergeMarkedInstruction(input.claudeMdContent);
     if (r.status === AgentRuleStatus.ALREADY) {
         return {
             title: AGENT_RULE_TITLE,
-            target: CLAUDE_MD_PATH,
+            target: path,
             status: StepStatus.ALREADY,
             detail: 'Reticle rule already in CLAUDE.md',
         };
     }
     return {
         title: AGENT_RULE_TITLE,
-        target: CLAUDE_MD_PATH,
+        target: path,
         status: StepStatus.APPLY,
         detail: AGENT_RULE_DETAIL,
-        write: { path: CLAUDE_MD_PATH, content: r.content },
+        write: { path, content: r.content },
     };
 }
 /**
@@ -300,20 +351,21 @@ function cursorRuleStep(input) {
         return null;
     // 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.
+    const path = agentFile(input, CURSOR_RULE_PATH);
     if (input.cursorRuleContent === cursorRuleFile()) {
         return {
             title: AGENT_RULE_TITLE,
-            target: CURSOR_RULE_PATH,
+            target: path,
             status: StepStatus.ALREADY,
             detail: 'Reticle rule already in .cursor/rules',
         };
     }
     return {
         title: AGENT_RULE_TITLE,
-        target: CURSOR_RULE_PATH,
+        target: path,
         status: StepStatus.APPLY,
         detail: AGENT_RULE_DETAIL,
-        write: { path: CURSOR_RULE_PATH, content: cursorRuleFile() },
+        write: { path, content: cursorRuleFile() },
     };
 }
 /**
@@ -357,33 +409,70 @@ 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
- * is detected. Rides with the MCP wiring — `--no-mcp` opts out of registering the tools AND the rule.
+ * `AGENTS.md`, always. It is the file every agent that is not Claude or Cursor reads.
+ *
+ * This used to be a FALLBACK, written only when no agent was detected. So a repo set up on a machine
+ * with Claude Code got `CLAUDE.md` and nothing else, and the next person to open it with Codex,
+ * Copilot, Amp, Gemini or any other agent found a fully instrumented app whose rules were addressed
+ * to somebody else's tool. The detection tells you which agent is running the install; it says
+ * nothing about which agents will open the repository afterwards.
+ */
+function agentsMdStep(input) {
+    const r = mergeMarkedInstruction(input.agentsMdContent);
+    const path = agentFile(input, AGENTS_MD_PATH);
+    if (r.status === AgentRuleStatus.ALREADY) {
+        return {
+            title: AGENT_RULE_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'Reticle rule already in AGENTS.md',
+        };
+    }
+    return {
+        title: AGENT_RULE_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: AGENT_RULE_DETAIL,
+        write: { path, content: r.content },
+    };
+}
+/**
+ * `RETICLE.md`, the reference the always-loaded blocks point at.
+ *
+ * Written whole rather than merged, because `init` owns the entire file: there is no user content to
+ * preserve, and the marker dance exists only for files somebody else already writes in.
+ */
+function reticleMdStep(input) {
+    const path = agentFile(input, RETICLE_MD_PATH);
+    const content = reticleMdFile();
+    if (input.reticleMdContent === content) {
+        return {
+            title: RETICLE_MD_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'full rules already current',
+        };
+    }
+    return {
+        title: RETICLE_MD_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: RETICLE_MD_DETAIL,
+        write: { path, content },
+    };
+}
+/**
+ * The behavioral rules that make the agent actually USE Reticle, and know when not to.
+ *
+ * Every detected agent's own file, plus `AGENTS.md` for the ones that will open this repo later, plus
+ * `RETICLE.md` holding the reference half. Rides with the MCP wiring: `--no-mcp` opts out of
+ * registering the tools AND of every rule file, because rules for tools the agent cannot reach are
+ * noise.
  */
 function agentRuleSteps(input) {
     if (!input.options.mcp)
         return [];
-    const detected = stepsForAgents(input, (a) => a.ruleStep);
-    if (detected.length > 0)
-        return detected;
-    const r = mergeMarkedInstruction(input.agentsMdContent);
-    return [
-        r.status === AgentRuleStatus.ALREADY
-            ? {
-                title: AGENT_RULE_TITLE,
-                target: AGENTS_MD_PATH,
-                status: StepStatus.ALREADY,
-                detail: 'Reticle rule already in AGENTS.md',
-            }
-            : {
-                title: AGENT_RULE_TITLE,
-                target: AGENTS_MD_PATH,
-                status: StepStatus.APPLY,
-                detail: AGENT_RULE_DETAIL,
-                write: { path: AGENTS_MD_PATH, content: r.content },
-            },
-    ];
+    return [...stepsForAgents(input, (a) => a.ruleStep), agentsMdStep(input), reticleMdStep(input)];
 }
 /**
  * What to say when the install command fails.
@@ -431,7 +520,7 @@ function installFailureHint(pm) {
 }
 function installStep(input) {
     const pm = input.detection.packageManager;
-    const packages = pinnedPackages(frameworkPackages(input.detection.framework), input.options.sdkVersion);
+    const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
     const command = installCommand(pm, packages);
     if (!input.options.install) {
         return {
@@ -455,13 +544,55 @@ function installStep(input) {
         // 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)),
+            ...installCommandParts(pm, frameworkPackages(input.detection.framework, input.detection.uiLibrary)),
             note: unpinnedRetryNote(input.options.sdkVersion, pm),
         },
     };
 }
+/**
+ * What is wrong with the config that is already there, if anything.
+ *
+ * Reported from the field (#317): a project carried `"port": 3000` — its own dev-server port, which
+ * is the confusion SKILL.md names as the top setup failure — and `init` printed `.reticle.json
+ * already exists` on every re-run without reading a single field of it, so the file could never be
+ * repaired by the command that wrote it. It stayed invisible because a daemon on `127.0.0.1:3000`
+ * and Vite on `[::1]:3000` split the port by address family and neither reported a conflict.
+ *
+ * Narrower than the issue asked for on purpose: `init`'s IO surface is synchronous, so this cannot
+ * probe what is LISTENING right now. `isLikelyDevServerPort` covers the framework defaults, which is
+ * where the mistake is actually made.
+ */
+function existingConfigProblem(source) {
+    if (null === source || source === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return (`${RETICLE_CONFIG_FILE} is present but is not valid JSON, so nothing reads it — neither the ` +
+            'daemon nor the SDK. Delete it and re-run `reticle init`.');
+    }
+    if ('object' !== typeof parsed || null === parsed)
+        return undefined;
+    const port = parsed['port'];
+    if ('number' !== typeof port || !isLikelyDevServerPort(port))
+        return undefined;
+    return `${devServerPortWarning(port)} Fix it by removing the "port" field from ${RETICLE_CONFIG_FILE}.`;
+}
 function reticleConfigStep(input) {
     if (true === input.reticleConfigExists) {
+        const problem = existingConfigProblem(input.reticleConfigSource);
+        if (problem !== undefined) {
+            // `ℹ`, not `·`: the step is done and something about the result still stops things working,
+            // which is the one mark that says "there is something here to read".
+            return {
+                title: 'Reticle config',
+                target: RETICLE_CONFIG_FILE,
+                status: StepStatus.NOTICE,
+                detail: problem,
+            };
+        }
         return {
             title: 'Reticle config',
             target: RETICLE_CONFIG_FILE,
@@ -484,8 +615,14 @@ function reticleConfigStep(input) {
  */
 function uiLibraryStep(input) {
     const lib = input.detection.uiLibrary;
-    if (lib === UiLibrary.REACT || input.detection.framework === Framework.SVELTEKIT)
+    // Nuxt and SvelteKit each carry their own unverified wording inside the recipe, so a second,
+    // more generic notice beside it would only argue with the specific one.
+    const framework = input.detection.framework;
+    if (lib === UiLibrary.REACT ||
+        framework === Framework.SVELTEKIT ||
+        framework === Framework.NUXT) {
         return [];
+    }
     if (lib === UiLibrary.UNKNOWN)
         return [];
     return [
@@ -518,6 +655,9 @@ export function buildPlan(input) {
     else if (input.detection.framework === Framework.CRA) {
         steps.push(...craSteps(input));
     }
+    else if (input.detection.framework === Framework.NUXT) {
+        steps.push(...nuxtSteps(input));
+    }
     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
@@ -530,8 +670,8 @@ export function buildPlan(input) {
             title: 'Connect snippet',
             target: 'index.html',
             status: StepStatus.MANUAL,
-            detail: htmlManual(input.options.port, input.options.projectId),
+            detail: htmlManual(input.options.port, input.options.projectId, input.pairingToken),
         });
     }
-    return { framework: input.detection.framework, steps };
+    return { framework: input.detection.framework, uiLibrary: input.detection.uiLibrary, steps };
 }

package/dist/init/run.d.ts

@@ -3,6 +3,7 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
+import type { InitOutcome } from '@reticlehq/core';
 /**
  * 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
@@ -29,6 +30,23 @@ export interface InitOptions {
     app?: string;
     /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
     redirected?: boolean;
+    /**
+     * Where the human ran the command, carried across a workspace redirect.
+     *
+     * The agent rule and `/reticle` command files are read by the AGENT, whose session runs where the
+     * human started it — the repo root. Writing them beside the app instead is how a repo with its app
+     * at `src/admin` ended up with no `/reticle` at all (#318).
+     */
+    agentRoot?: string;
+    /**
+     * Hand the telemetry outcome back rather than emitting it here.
+     *
+     * `init` now stays to watch for an app to connect, and whether it saw one belongs on the SAME
+     * `init_completed` event — the funnel it exists to measure would be double-counted by a second
+     * emit and unjoinable as a second event kind. Only the CLI sets this; every other caller keeps
+     * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
+     */
+    deferOutcome?: boolean;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -52,10 +70,15 @@ export interface InitIo {
     probe(command: string, args: readonly string[]): boolean;
     print(line: string): void;
 }
-interface InitResult {
+export interface InitResult {
     ok: boolean;
     applied: number;
     manual: number;
+    /**
+     * The event body this run would report, handed to the caller instead of emitted, when
+     * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
+     */
+    outcome?: InitOutcome;
 }
 /**
  * App directories under a workspace root.
@@ -77,4 +100,3 @@ export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile'
  */
 export declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
-export {};