@reticlehq/server 2.7.0 → 2.9.0

package/dist/init/plan.js

@@ -8,9 +8,12 @@ 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, nuxtSteps, 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, cspStep, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { join } from 'node:path';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
+import { declaredInstallSource } from '../telemetry/install-source.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
@@ -34,15 +37,40 @@ 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
@@ -51,43 +79,21 @@ export function frameworkPackages(framework) {
         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. */
 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)',
-    'Connect snippet (Nuxt)',
-    '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';
+export const RETICLE_CONFIG_FILE = '.reticle.json';
 export const StepStatus = {
     APPLY: 'apply',
     MANUAL: 'manual',
@@ -101,6 +107,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) {
@@ -267,32 +286,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 },
     };
 }
 /**
@@ -308,20 +330,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() },
     };
 }
 /**
@@ -365,33 +388,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.
@@ -439,7 +499,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 {
@@ -463,29 +523,127 @@ 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),
         },
     };
 }
-function reticleConfigStep(input) {
+/**
+ * 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}.`;
+}
+const RETICLE_CONFIG_TITLE = 'Reticle config';
+const AGENT_ROOT_CONFIG_TITLE = 'Reticle config (agent root)';
+/**
+ * The SECOND `.reticle.json`, in the directory the agent runs from.
+ *
+ * `.reticle.json` is not app wiring — nothing in the app reads it. The CLI and `reticle mcp` read it
+ * from their own CWD (see cli-port), and that CWD is the repo root, not the app directory a redirect
+ * wired. Reported from the field: an app in `frontend/` on a non-default bridge port left the root
+ * with no config at all, so `reticle mcp` fell back to 4400 — which on that machine was ANOTHER
+ * project's daemon, and `reticle_sessions` would have listed a different app's tabs while the wired
+ * app sat unseen. Nothing in the report said so; every step was green.
+ *
+ * Written in BOTH places rather than moved: a human standing in the app runs `reticle status` there,
+ * and the two files are byte-identical, so neither can disagree with the other about the port or the
+ * project identity.
+ */
+function agentRootConfigStep(input, content) {
+    const root = input.agentFileRoot;
+    if (root === undefined || 0 === root.length)
+        return [];
+    const path = agentFile(input, RETICLE_CONFIG_FILE);
+    if (input.agentRootConfigSource === content) {
+        return [
+            {
+                title: AGENT_ROOT_CONFIG_TITLE,
+                target: path,
+                status: StepStatus.ALREADY,
+                detail: 'the agent already reads the same project config',
+            },
+        ];
+    }
+    return [
+        {
+            title: AGENT_ROOT_CONFIG_TITLE,
+            target: path,
+            status: StepStatus.APPLY,
+            detail: 'the same config where the agent runs — `reticle mcp` reads it from ITS cwd, and without ' +
+                'it the agent talks to whatever daemon is on the default port',
+            write: { path, content },
+        },
+    ];
+}
+function reticleConfigStep(input, content) {
     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_TITLE,
+                target: RETICLE_CONFIG_FILE,
+                status: StepStatus.NOTICE,
+                detail: problem,
+            };
+        }
         return {
-            title: 'Reticle config',
+            title: RETICLE_CONFIG_TITLE,
             target: RETICLE_CONFIG_FILE,
             status: StepStatus.ALREADY,
             detail: '.reticle.json already exists',
         };
     }
-    const content = reticleConfigContent(input.detection.framework, input.options.port, input.options.projectId);
     return {
-        title: 'Reticle config',
+        title: RETICLE_CONFIG_TITLE,
         target: RETICLE_CONFIG_FILE,
         status: StepStatus.APPLY,
         detail: 'write project config (framework + port)',
         write: { path: RETICLE_CONFIG_FILE, content },
     };
 }
+/**
+ * The project config, in every directory that has to read it: the app's, and — after a redirect —
+ * the one the agent runs from. One content string for both, so they cannot disagree; an existing
+ * app-side config wins over a freshly derived one, or a re-run would copy a DIFFERENT identity up.
+ */
+function reticleConfigSteps(input) {
+    const existing = input.reticleConfigSource;
+    const content = true === input.reticleConfigExists && null !== existing && existing !== undefined
+        ? existing
+        : reticleConfigContent(input.detection.framework, input.options.port, input.options.projectId, 
+        // Only when it is actually known. Writing `unknown` would be indistinguishable from a
+        // config written before this field existed, and the two mean different things.
+        declaredInstallSource());
+    return [reticleConfigStep(input, content), ...agentRootConfigStep(input, 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.
@@ -513,12 +671,13 @@ function uiLibraryStep(input) {
 }
 export function buildPlan(input) {
     const steps = [
+        ...cspStep(input),
         ...mcpSteps(input),
         ...agentRuleSteps(input),
         ...slashCommandSteps(input),
         ...uiLibraryStep(input),
         installStep(input),
-        reticleConfigStep(input),
+        ...reticleConfigSteps(input),
     ];
     if (input.detection.framework === Framework.VITE) {
         steps.push(...viteSteps(input));
@@ -550,5 +709,5 @@ export function buildPlan(input) {
             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 {};