@reticlehq/server 2.3.0 → 2.5.0

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, 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 { 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, 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
@@ -16,8 +17,22 @@ 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 || 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];
@@ -25,6 +40,14 @@ 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.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];
@@ -32,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';
@@ -40,6 +84,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)';
@@ -99,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)',
@@ -116,6 +172,52 @@ 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.
+ *
+ * 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 commandStepFor(path, present, content) {
+    if (!present)
+        return null;
+    return commandIsSettled(content)
+        ? {
+            title: SLASH_COMMAND_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'command already exists',
+        }
+        : {
+            title: SLASH_COMMAND_TITLE,
+            target: path,
+            status: StepStatus.APPLY,
+            detail: 'type /reticle to verify one flow in the browser',
+            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';
 function claudeRuleStep(input) {
@@ -138,10 +240,20 @@ 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.cursorRuleExists === true) {
+    if (input.cursorProjectPresent !== true && input.claudeCli)
+        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.
+    if (input.cursorRuleContent === cursorRuleFile()) {
         return {
             title: AGENT_RULE_TITLE,
             target: CURSOR_RULE_PATH,
@@ -157,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
@@ -165,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);
@@ -186,9 +338,36 @@ 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.
+ */
+/** 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.';
+    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,132 +383,21 @@ 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 },
+        exec: {
+            command: parts.command,
+            args: parts.args,
+            fallback: `${command}\n\n${installFailureHint(pm)}`,
         },
-    ];
-}
-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),
+        // 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),
         },
-        {
-            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) {
+    if (true === input.reticleConfigExists) {
         return {
             title: 'Reticle config',
             target: RETICLE_CONFIG_FILE,
@@ -346,10 +414,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 +448,18 @@ export function buildPlan(input) {
     else if (input.detection.framework === Framework.NEXT) {
         steps.push(...nextSteps(input));
     }
+    else if (input.detection.framework === Framework.ASTRO) {
+        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));
+        // 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/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,13 @@ 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;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -26,6 +33,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 +50,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 {};