@reticlehq/init 3.3.0 → 3.4.0

package/dist/detect/capabilities.d.ts

@@ -17,7 +17,10 @@ export declare function scanTestids(sources: readonly string[]): string[];
  * The store libraries this app depends on AND the running app cannot reveal on its own, as
  * ready-to-uncomment registration lines.
  */
-export declare function storeHints(deps: ReadonlySet<string>): string[];
+export declare function storeHints(deps: ReadonlySet<string>, files?: readonly {
+    path: string;
+    source: string;
+}[]): string[];
 /** A store instance we found in the app's own source, with everything needed to import and register it. */
 export interface FoundStore {
     /** The name it registers under — what `reticle_state` keys its output by. */

package/dist/detect/capabilities.js

@@ -55,16 +55,42 @@ const STORE_LIBRARIES = [
     ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
     [
         'zustand',
-        "registerStore('app', useStore) // pass the store itself, not () => store.getState()",
+        "registerStore('app', <yourStore>) // pass the store itself, not () => store.getState()",
     ],
     ['@reduxjs/toolkit', "registerStore('app', store)"],
     ['redux', "registerStore('app', store)"],
-    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],
-    ['valtio', "registerStore('app', valtioStore(state))"],
-    ['mobx', "registerStore('app', mobxStore(state))"],
-    ['xstate', "registerStore('machine', xstateStore(actor))"],
-    ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
-    ['svelte', "registerStore('cart', svelteStore(cartStore))"],
+    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { <yourAtoms> }))"],
+    ['valtio', "registerStore('app', valtioStore(<yourProxyState>))"],
+    ['mobx', "registerStore('app', mobxStore(<yourObservable>))"],
+    ['xstate', "registerStore('machine', xstateStore(<yourActor>))"],
+    ['pinia', "registerStore('<key>', piniaStore(<useYourStore>()))"],
+];
+/**
+ * The adapter-wrapped libraries whose store the SOURCE can name for us, and how.
+ *
+ * Every hint above used to carry a made-up identifier, and two of them were wrong on every app of
+ * their kind: each Svelte app was told `svelteStore(cartStore)` and a create-vue app defining
+ * `useCounterStore` was told `piniaStore(useCartStore())`. An agent that follows a hint imports what
+ * it names. So where the declaration has a shape we can read, the hint names what is actually there;
+ * where it does not, the hint says what to fill in with a placeholder instead of a guess.
+ *
+ * Svelte has no generic hint at all: every Svelte app depends on `svelte`, so the dependency says
+ * nothing about whether it has a store, and a hint on it fired the "finish the capabilities file"
+ * notice on every Svelte app there is.
+ */
+const SOURCE_NAMED_STORES = [
+    [
+        'pinia',
+        /export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*defineStore\s*\(\s*['"`]([^'"`]+)['"`]/g,
+        (m) => m[1] === undefined || m[2] === undefined
+            ? undefined
+            : `registerStore('${m[2]}', piniaStore(${m[1]}()))`,
+    ],
+    [
+        'svelte',
+        /export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:writable|readable|derived)\s*[<(]/g,
+        (m) => (m[1] === undefined ? undefined : `registerStore('${m[1]}', svelteStore(${m[1]}))`),
+    ],
 ];
 /**
  * Libraries that hand their store to React through a context provider, and therefore need no hint.
@@ -87,8 +113,18 @@ const AUTO_DISCOVERED_DEPS = new Set([
  * The store libraries this app depends on AND the running app cannot reveal on its own, as
  * ready-to-uncomment registration lines.
  */
-export function storeHints(deps) {
-    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep) && !AUTO_DISCOVERED_DEPS.has(dep)).map(([, hint]) => hint);
+export function storeHints(deps, files = []) {
+    const named = new Map();
+    for (const [dep, declaration, hint] of SOURCE_NAMED_STORES) {
+        if (!deps.has(dep))
+            continue;
+        const found = files.flatMap(({ source }) => [...source.matchAll(declaration)].flatMap((m) => hint(m) ?? []));
+        if (found.length > 0)
+            named.set(dep, found);
+    }
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep) && !AUTO_DISCOVERED_DEPS.has(dep))
+        .flatMap(([dep, hint]) => named.get(dep) ?? [hint])
+        .concat(named.get('svelte') ?? []);
 }
 /**
  * Store factories whose EXPORTED result is the store instance itself — the form `registerStore`

package/dist/detect/detect.d.ts

@@ -19,6 +19,13 @@ export declare const Framework: {
      * is main's — wiring the SDK where there is no document, and reporting success.
      */
     readonly ELECTRON_VITE: "electron-vite";
+    /**
+     * Electron Forge's Vite template. Its Vite config is split three ways (`vite.main.config.*`,
+     * `vite.preload.config.*`, `vite.renderer.config.*`) and there is no `vite.config.*` at all, so it
+     * used to read as plain Vite with a missing config: a manual step, no preload shim, no capture
+     * helper, and a re-run that could never clear the ⚠. Only the renderer config has a document.
+     */
+    readonly ELECTRON_FORGE: "electron-forge";
     /**
      * React Router in FRAMEWORK mode (v7's `@react-router/dev`, the successor to Remix).
      *
@@ -36,6 +43,16 @@ export declare const Framework: {
      * path.
      */
     readonly REACT_ROUTER: "react-router";
+    /**
+     * Remix v2 (`@remix-run/dev`) — React Router framework mode under its previous name.
+     *
+     * On Vite (`vitePlugin` from `@remix-run/dev`) it renders its own HTML exactly as framework mode
+     * does, so it needs the same client-entry connect. It used to fall through to `Framework.VITE`:
+     * the plugin was wired, every step went green, and the page never connected, because nothing
+     * reaches a document Remix SSRs. On the classic compiler (no Vite) there is no plugin to serve the
+     * connect module at all, and the plan says so rather than wiring half of it.
+     */
+    readonly REMIX: "remix";
     /**
      * TanStack Start SSRs `<html>` from `src/routes/__root.tsx` and never sends Vite's index.html, so
      * the plugin's `transformIndexHtml` injection never fires. It used to fall through to
@@ -51,6 +68,12 @@ export declare const Framework: {
     readonly TANSTACK_START: "tanstack-start";
     readonly SVELTEKIT: "sveltekit";
     readonly ASTRO: "astro";
+    /**
+     * Angular CLI. It has no Vite config to patch (the CLI owns its bundler) and no index.html at the
+     * root, so it used to fall through to HTML — and be handed the React kit, a ⚠ pointing at a file
+     * that does not exist, and two snippets that fail on it.
+     */
+    readonly ANGULAR: "angular";
     /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
     readonly CRA: "cra";
     readonly HTML: "html";
@@ -143,6 +166,14 @@ export interface Detection {
      */
     webGlSubtree?: boolean | undefined;
     packageManager: PackageManager;
+    /**
+     * The prefix this run can actually invoke `packageManager` through — see `preflight.ts` (#1149) for
+     * why that can be `corepack <packageManager>` rather than the bare name. Undefined here: `detect` is
+     * pure and never probes a binary, so this is filled in by `run.ts` from `preflight`'s result, before
+     * the plan is built. Every later spawn or printed command for the package manager reads this rather
+     * than `packageManager` alone.
+     */
+    packageManagerCommand?: string;
     /**
      * Every dependency this package DECLARES, by name, merged across the three blocks.
      *
@@ -155,6 +186,10 @@ export interface Detection {
      */
     dependencies?: Readonly<Record<string, string>> | undefined;
 }
+/** Forge's renderer build — the only one of its three Vite configs with a document. */
+export declare const FORGE_RENDERER_CONFIGS: string[];
+/** The Angular CLI workspace file. */
+export declare const ANGULAR_WORKSPACE_FILE = "angular.json";
 /** What identifies one framework in a project root: a dependency name, or a config file basename. */
 interface FrameworkSignals {
     /** `package.json` dependency names that name this framework outright. */
@@ -223,7 +258,13 @@ export declare function installCommandParts(pm: PackageManager, pkgs: string | r
  * how `npm i -D --legacy-peer-deps` would become a request to install a package called
  * `--legacy-peer-deps` on a manager that does not recognise the flag.
  */
-extraFlags?: readonly string[]): InstallCommand;
+extraFlags?: readonly string[], 
+/**
+ * The prefix that actually invokes `pm` on this machine — `pm` itself, or `corepack ${pm}` on a
+ * corepack-only machine (see `Detection.packageManagerCommand`). Defaults to `pm` so every existing
+ * caller keeps spawning the bare binary without naming this.
+ */
+prefix?: string): InstallCommand;
 /**
  * The install command as a human reads it — and deliberately NOT `installCommandParts` joined.
  *
@@ -232,5 +273,7 @@ extraFlags?: readonly string[]): InstallCommand;
  * directly for that reason; routing it through the parts would put `--no-audit --no-fund` in front of
  * every reader and teach them our noise-suppression as if it were part of installing Reticle.
  */
-export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[]): string;
+export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[], 
+/** As in `installCommandParts` — what a corepack-only machine has to type instead of bare `pm`. */
+prefix?: string): string;
 export {};

package/dist/detect/detect.js

@@ -19,6 +19,13 @@ export const Framework = {
      * is main's — wiring the SDK where there is no document, and reporting success.
      */
     ELECTRON_VITE: 'electron-vite',
+    /**
+     * Electron Forge's Vite template. Its Vite config is split three ways (`vite.main.config.*`,
+     * `vite.preload.config.*`, `vite.renderer.config.*`) and there is no `vite.config.*` at all, so it
+     * used to read as plain Vite with a missing config: a manual step, no preload shim, no capture
+     * helper, and a re-run that could never clear the ⚠. Only the renderer config has a document.
+     */
+    ELECTRON_FORGE: 'electron-forge',
     /**
      * React Router in FRAMEWORK mode (v7's `@react-router/dev`, the successor to Remix).
      *
@@ -36,6 +43,16 @@ export const Framework = {
      * path.
      */
     REACT_ROUTER: 'react-router',
+    /**
+     * Remix v2 (`@remix-run/dev`) — React Router framework mode under its previous name.
+     *
+     * On Vite (`vitePlugin` from `@remix-run/dev`) it renders its own HTML exactly as framework mode
+     * does, so it needs the same client-entry connect. It used to fall through to `Framework.VITE`:
+     * the plugin was wired, every step went green, and the page never connected, because nothing
+     * reaches a document Remix SSRs. On the classic compiler (no Vite) there is no plugin to serve the
+     * connect module at all, and the plan says so rather than wiring half of it.
+     */
+    REMIX: 'remix',
     /**
      * TanStack Start SSRs `<html>` from `src/routes/__root.tsx` and never sends Vite's index.html, so
      * the plugin's `transformIndexHtml` injection never fires. It used to fall through to
@@ -51,6 +68,12 @@ export const Framework = {
     TANSTACK_START: 'tanstack-start',
     SVELTEKIT: 'sveltekit',
     ASTRO: 'astro',
+    /**
+     * Angular CLI. It has no Vite config to patch (the CLI owns its bundler) and no index.html at the
+     * root, so it used to fall through to HTML — and be handed the React kit, a ⚠ pointing at a file
+     * that does not exist, and two snippets that fail on it.
+     */
+    ANGULAR: 'angular',
     /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
     CRA: 'cra',
     HTML: 'html',
@@ -88,6 +111,17 @@ const REACT_ROUTER_CONFIGS = [
     'react-router.config.mjs',
 ];
 const NUXT_CONFIGS = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'];
+/** The classic Remix compiler's config. Remix on Vite has none; its dependency is the signal. */
+const REMIX_CONFIGS = ['remix.config.js', 'remix.config.mjs', 'remix.config.cjs'];
+/** Forge's renderer build — the only one of its three Vite configs with a document. */
+export const FORGE_RENDERER_CONFIGS = [
+    'vite.renderer.config.ts',
+    'vite.renderer.config.mts',
+    'vite.renderer.config.js',
+    'vite.renderer.config.mjs',
+];
+/** The Angular CLI workspace file. */
+export const ANGULAR_WORKSPACE_FILE = 'angular.json';
 const ASTRO_CONFIGS = [
     'astro.config.mjs',
     'astro.config.js',
@@ -148,6 +182,17 @@ export const FRAMEWORK_SIGNALS = {
      * has a DOM, so it must never fall through to the generic Vite path.
      */
     [Framework.ELECTRON_VITE]: { deps: ['electron-vite'], configs: ELECTRON_VITE_CONFIGS },
+    /**
+     * The Vite plugin, not `@electron-forge/cli`: a Forge app on the webpack template has no Vite
+     * config to patch, and claiming it here would hand it steps that cannot apply.
+     */
+    [Framework.ELECTRON_FORGE]: {
+        deps: ['@electron-forge/plugin-vite'],
+        configs: FORGE_RENDERER_CONFIGS,
+    },
+    /** `@remix-run/dev` is both compilers' package; the plan tells them apart by the Vite config. */
+    [Framework.REMIX]: { deps: ['@remix-run/dev'], configs: REMIX_CONFIGS },
+    [Framework.ANGULAR]: { deps: ['@angular/core'], configs: [ANGULAR_WORKSPACE_FILE] },
     /**
      * The Start packages, never Query or Router alone — those stay on the Vite path. Start has no
      * config file of its own to key on.
@@ -177,9 +222,17 @@ export const DETECTION_ORDER = [
     Framework.SVELTEKIT,
     Framework.ASTRO,
     Framework.ELECTRON_VITE,
+    // Before Vite, for the reason electron-vite is: Forge's template depends on `vite` directly.
+    Framework.ELECTRON_FORGE,
     Framework.REACT_ROUTER,
+    // After React Router, so an app half-way through the Remix -> React Router upgrade gets the
+    // successor's wiring; before Vite, because Remix on Vite depends on `vite` directly.
+    Framework.REMIX,
     Framework.TANSTACK_START,
     Framework.VITE,
+    // After Vite: an Analog app is Angular on Vite, and the Vite plugin's index.html injection reaches
+    // it. A CLI app never depends on `vite` itself — the CLI bundles its own.
+    Framework.ANGULAR,
     Framework.CRA,
 ];
 /** Extract the leading major version from a semver range like "^19.0.0" or "19.1.1". */
@@ -356,11 +409,27 @@ export function installCommandParts(pm, pkgs,
  * how `npm i -D --legacy-peer-deps` would become a request to install a package called
  * `--legacy-peer-deps` on a manager that does not recognise the flag.
  */
-extraFlags = []) {
+extraFlags = [], 
+/**
+ * The prefix that actually invokes `pm` on this machine — `pm` itself, or `corepack ${pm}` on a
+ * corepack-only machine (see `Detection.packageManagerCommand`). Defaults to `pm` so every existing
+ * caller keeps spawning the bare binary without naming this.
+ */
+prefix = pm) {
     const list = 'string' === typeof pkgs ? [pkgs] : pkgs;
+    // A bare `pm` is one word and stays the whole command; `corepack ${pm}` splits so `corepack` is the
+    // program `spawnAllowed` runs and `pm` is its first argument — the shape `RUNNABLE_COMMANDS` and the
+    // corepack probe both expect.
+    const [command, ...leadingArgs] = prefix.split(' ');
     return {
-        command: pm,
-        args: [...INSTALL_ARGS[pm], ...list, ...(QUIET_INSTALL_ARGS[pm] ?? []), ...extraFlags],
+        command: command ?? pm,
+        args: [
+            ...leadingArgs,
+            ...INSTALL_ARGS[pm],
+            ...list,
+            ...(QUIET_INSTALL_ARGS[pm] ?? []),
+            ...extraFlags,
+        ],
     };
 }
 /**
@@ -371,7 +440,9 @@ extraFlags = []) {
  * directly for that reason; routing it through the parts would put `--no-audit --no-fund` in front of
  * every reader and teach them our noise-suppression as if it were part of installing Reticle.
  */
-export function installCommand(pm, pkgs) {
+export function installCommand(pm, pkgs, 
+/** As in `installCommandParts` — what a corepack-only machine has to type instead of bare `pm`. */
+prefix = pm) {
     const list = 'string' === typeof pkgs ? [pkgs] : pkgs;
-    return `${pm} ${[...INSTALL_ARGS[pm], ...list].join(' ')}`;
+    return `${prefix} ${[...INSTALL_ARGS[pm], ...list].join(' ')}`;
 }

package/dist/detect/dev-script.d.ts

@@ -38,8 +38,30 @@ interface DevScriptPlan {
  * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
  * When something is already answering we do not care which script exists: the rule is never to
  * start a second server, because the one that is running may be the user's, with their state in it.
+ *
+ * `packageManagerCommand` is `Detection.packageManagerCommand` (see `preflight.ts`, #1149) — the
+ * prefix that actually invokes the package manager on this machine, which is what gets printed AND,
+ * later, spawned by `startDevServer`.
+ */
+export declare function planDevScript(scripts: Readonly<Record<string, string>>, packageManagerCommand: string, serving: boolean): DevScriptPlan;
+/** How a desktop shell is launched: through one of its scripts, or its CLI when none names it. */
+export type DesktopLaunch = {
+    readonly script: string;
+    readonly args: string;
+} | {
+    readonly command: string;
+};
+/**
+ * The desktop shell's own launcher, when the manifest names one; undefined for anything else.
+ *
+ * A desktop project's `dev` script is its RENDERER's dev server: on the official Tauri template it
+ * is plain `vite`, so init ran it, no window ever opened, and the run waited out its whole budget
+ * for a session only the window could create. The shell's CLI is what opens the window.
+ *
+ * Exported because the daemon names a dev command too (its no-session next action), and two
+ * readers of one manifest have to give one answer.
  */
-export declare function planDevScript(scripts: Readonly<Record<string, string>>, packageManager: string, serving: boolean): DevScriptPlan;
+export declare function desktopLaunch(pkg: unknown): DesktopLaunch | undefined;
 /**
  * The command to print for this project, straight from its `package.json`.
  *
@@ -47,5 +69,7 @@ export declare function planDevScript(scripts: Readonly<Record<string, string>>,
  * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
  * read: this phrasing decides nothing, so it must never be able to break an install.
  */
-export declare function devCommandFrom(pkg: unknown, packageManager: string): string | undefined;
+export declare function devCommandFrom(pkg: unknown, packageManagerCommand: string): string | undefined;
+/** The dev script's own command line (`react-router dev`, `vite`), or undefined when there is none. */
+export declare function devScriptBody(pkg: unknown): string | undefined;
 export {};

package/dist/detect/dev-script.js

@@ -31,17 +31,73 @@ export const DevScriptChoice = {
  * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
  * When something is already answering we do not care which script exists: the rule is never to
  * start a second server, because the one that is running may be the user's, with their state in it.
+ *
+ * `packageManagerCommand` is `Detection.packageManagerCommand` (see `preflight.ts`, #1149) — the
+ * prefix that actually invokes the package manager on this machine, which is what gets printed AND,
+ * later, spawned by `startDevServer`.
  */
-export function planDevScript(scripts, packageManager, serving) {
+export function planDevScript(scripts, packageManagerCommand, serving) {
     if (serving)
         return { choice: DevScriptChoice.ALREADY_SERVING };
     const name = CANDIDATES.find((c) => 'string' === typeof scripts[c] && scripts[c] !== '');
     if (name === undefined)
         return { choice: DevScriptChoice.NO_SCRIPT };
-    // `npm` needs `run`; the others take the script name directly. Getting this wrong prints a
-    // command that fails, which is worse than printing nothing.
-    const command = 'npm' === packageManager ? `npm run ${name}` : `${packageManager} ${name}`;
-    return { choice: DevScriptChoice.START, script: name, command };
+    return {
+        choice: DevScriptChoice.START,
+        script: name,
+        command: runScript(packageManagerCommand, name),
+    };
+}
+/**
+ * `npm` needs `run`; the others take the script name directly. Getting this wrong prints a command
+ * that fails, which is worse than printing nothing. `npm` is never corepack-prefixed (it ships with
+ * node), so this comparison still identifies it correctly.
+ */
+function runScript(packageManagerCommand, script) {
+    return 'npm' === packageManagerCommand
+        ? `npm run ${script}`
+        : `${packageManagerCommand} ${script}`;
+}
+const TAURI_CLI_PACKAGE = '@tauri-apps/cli';
+/** The official template's script: `"tauri": "tauri"`, so `<pm> tauri dev` is its dev command. */
+const TAURI_SCRIPT = 'tauri';
+const TAURI_DEV_ARG = 'dev';
+const TAURI_DIRECT = 'npx tauri dev';
+const FORGE_CLI_PACKAGE = '@electron-forge/cli';
+const FORGE_START = /\belectron-forge\s+start\b/;
+const FORGE_DIRECT = 'npx electron-forge start';
+function manifestRecord(pkg, key) {
+    const value = 'object' === typeof pkg && null !== pkg ? Reflect.get(pkg, key) : {};
+    return 'object' === typeof value && null !== value ? value : {};
+}
+/**
+ * The desktop shell's own launcher, when the manifest names one; undefined for anything else.
+ *
+ * A desktop project's `dev` script is its RENDERER's dev server: on the official Tauri template it
+ * is plain `vite`, so init ran it, no window ever opened, and the run waited out its whole budget
+ * for a session only the window could create. The shell's CLI is what opens the window.
+ *
+ * Exported because the daemon names a dev command too (its no-session next action), and two
+ * readers of one manifest have to give one answer.
+ */
+export function desktopLaunch(pkg) {
+    const scripts = manifestRecord(pkg, 'scripts');
+    const deps = {
+        ...manifestRecord(pkg, 'dependencies'),
+        ...manifestRecord(pkg, 'devDependencies'),
+    };
+    const tauriScript = scripts[TAURI_SCRIPT];
+    if ('string' === typeof tauriScript && 0 < tauriScript.trim().length) {
+        return { script: TAURI_SCRIPT, args: TAURI_DEV_ARG };
+    }
+    if (undefined !== deps[TAURI_CLI_PACKAGE])
+        return { command: TAURI_DIRECT };
+    const forge = Object.entries(scripts).find(([, body]) => 'string' === typeof body && FORGE_START.test(body));
+    if (undefined !== forge)
+        return { script: forge[0], args: '' };
+    if (undefined !== deps[FORGE_CLI_PACKAGE])
+        return { command: FORGE_DIRECT };
+    return undefined;
 }
 /**
  * The command to print for this project, straight from its `package.json`.
@@ -50,17 +106,34 @@ export function planDevScript(scripts, packageManager, serving) {
  * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
  * read: this phrasing decides nothing, so it must never be able to break an install.
  */
-export function devCommandFrom(pkg, packageManager) {
+export function devCommandFrom(pkg, packageManagerCommand) {
     try {
         // Takes the PARSED manifest. It used to take the raw string and parse it a fourth time — the
         // caller now reads the file once, through a guard, so there is one place a malformed manifest
         // can be noticed and it is not this one.
+        const desktop = desktopLaunch(pkg);
+        if (undefined !== desktop) {
+            if ('command' in desktop)
+                return desktop.command;
+            const run = runScript(packageManagerCommand, desktop.script);
+            return 0 < desktop.args.length ? `${run} ${desktop.args}` : run;
+        }
         const scripts = 'object' === typeof pkg && null !== pkg
             ? (pkg.scripts ?? {})
             : {};
-        return planDevScript(scripts, packageManager, false).command;
+        return planDevScript(scripts, packageManagerCommand, false).command;
     }
     catch {
         return undefined;
     }
 }
+/** The dev script's own command line (`react-router dev`, `vite`), or undefined when there is none. */
+export function devScriptBody(pkg) {
+    const scripts = 'object' === typeof pkg && null !== pkg ? pkg.scripts : undefined;
+    if ('object' !== typeof scripts || null === scripts)
+        return undefined;
+    const table = scripts;
+    const name = CANDIDATES.find((c) => 'string' === typeof table[c] && table[c] !== '');
+    const body = name === undefined ? undefined : table[name];
+    return 'string' === typeof body ? body : undefined;
+}

package/dist/detect/non-js-project.d.ts

@@ -41,4 +41,4 @@ export declare function detectNonJsEcosystem(exists: (file: string) => boolean):
  * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
  * second needs to know that no path exists and why.
  */
-export declare function noPackageJsonMessage(exists: (file: string) => boolean): string;
+export declare function noPackageJsonMessage(exists: (file: string) => boolean, rootFiles?: readonly string[]): string;

package/dist/detect/non-js-project.js

@@ -104,9 +104,14 @@ export function detectNonJsEcosystem(exists) {
  * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
  * second needs to know that no path exists and why.
  */
-export function noPackageJsonMessage(exists) {
+export function noPackageJsonMessage(exists, rootFiles = []) {
     const ecosystem = detectNonJsEcosystem(exists);
     if (ecosystem === undefined) {
+        if (exists('index.html') || rootFiles.some((name) => name.endsWith('.html'))) {
+            return ('This is a static page with no build step, so there is nothing for `reticle init` to wire. ' +
+                'Add the script-tag snippet below to the page while you develop, then reload it. Remove the ' +
+                'snippet before publishing: a static file has no development build to keep it out of production.');
+        }
         return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
             "your app's directory, or from a repo root that contains it.");
     }

package/dist/detect/workspace-apps.d.ts

@@ -35,4 +35,25 @@ export declare const APP_DEPS: readonly ["next", "vite", "electron-vite"];
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * Every package directory the workspace declares or holds, app-shaped or not.
+ *
+ * For the questions discovery's filter must not answer — "which package does the root config name"
+ * is about identity, and a package `--app` wired is the app whether or not it looks like one.
+ */
+export declare function workspacePackageDirs(io: Pick<InitIo, 'readFile' | 'listDirs'>): string[];
+/**
+ * The workspace root that DECLARES `cwd` as one of its packages, or undefined.
+ *
+ * `init` run inside `apps/web` wrote `.reticle.json` there only, and `reticle mcp` finds that file by
+ * walking UP from where the agent stands — so an agent opened at the repo root never found it, fell
+ * back to the default port, and drove whichever daemon was there. `init --app apps/web` run from the
+ * root writes the root pointer and the agent files at the root; this is what lets a run from inside
+ * the app arrive at the same state.
+ *
+ * Only the NEAREST workspace root is asked, and only its declaration counts: a directory that merely
+ * sits under a repo with a package.json is not that repo's app, and guessing it is would write
+ * config into a stranger's root.
+ */
+export declare function enclosingWorkspaceRoot(cwd: string, io: Pick<InitIo, 'readFile'>): string | undefined;
 export {};