@reticlehq/server 2.11.0 → 2.13.0

package/dist/init/capabilities.d.ts

@@ -13,7 +13,10 @@
 export declare const MAX_TESTIDS = 60;
 /** Every distinct `data-testid` literal in the given sources, in first-seen order. */
 export declare function scanTestids(sources: readonly string[]): string[];
-/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+/**
+ * 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[];
 /** A store instance we found in the app's own source, with everything needed to import and register it. */
 export interface FoundStore {
@@ -24,8 +27,6 @@ export interface FoundStore {
     /** Module specifier relative to `src/reticle-dev.ts`. */
     importPath: string;
 }
-/** Where the generated dev module lives, for Vite. Next passes its own. */
-export declare const DEFAULT_DEV_MODULE_DIR = "src";
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/capabilities.js

@@ -49,9 +49,29 @@ const STORE_LIBRARIES = [
     ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
     ['svelte', "registerStore('cart', svelteStore(cartStore))"],
 ];
-/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+/**
+ * Libraries that hand their store to React through a context provider, and therefore need no hint.
+ *
+ * `<Provider store>` and `<QueryClientProvider client>` put the store instance in the fiber tree as
+ * a prop, so the React adapter finds and registers it on the first commit — see `auto-stores.ts` in
+ * `@reticlehq/react`. Offering a commented `registerStore` line for these was asking someone to do
+ * by hand, and be nagged about, work that is already done by the time they read the report.
+ *
+ * Everything absent from this set is module-scope (Zustand, Valtio, a MobX singleton) or needs an
+ * argument only the source supplies (Jotai atoms, an XState actor). Nothing in the running app
+ * points at those, so they still need the app to hand them over, and the hint still earns its place.
+ */
+const AUTO_DISCOVERED_DEPS = new Set([
+    '@tanstack/react-query',
+    '@reduxjs/toolkit',
+    'redux',
+]);
+/**
+ * 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)).map(([, hint]) => hint);
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep) && !AUTO_DISCOVERED_DEPS.has(dep)).map(([, hint]) => hint);
 }
 /**
  * Store factories whose EXPORTED result is the store instance itself — the form `registerStore`
@@ -102,7 +122,7 @@ function importPathFor(storePath, fromDir) {
     return rel.startsWith('.') ? rel : `./${rel}`;
 }
 /** Where the generated dev module lives, for Vite. Next passes its own. */
-export const DEFAULT_DEV_MODULE_DIR = 'src';
+const DEFAULT_DEV_MODULE_DIR = 'src';
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/closing-hint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined, 
+/** The project's own dev command, when package.json named one. */
+devCommand?: string): string;

package/dist/init/closing-hint.js

@@ -0,0 +1,120 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { CLI } from './agent-rules.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    'one thing that decides what gets fixed:\n' +
+    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/**
+ * What to say about the dev server.
+ *
+ * Names the project's own script when `package.json` has a recognisable one, and otherwise says the
+ * THING rather than guessing the command.
+ *
+ * The guesses that used to live here — `vite`, `next dev`, `astro dev` — were wrong often enough to
+ * be worth deleting. Measured on a real app: rowy has no `dev` script at all, so "Restart `vite`"
+ * sent the reader to work out what was meant instead of starting a server. Nobody needs the guess:
+ * an agent reading this can open package.json, and a human already knows how they start their own
+ * app. A wrong command costs more than a missing one.
+ */
+function devServerRestart(_framework, devCommand) {
+    return devCommand === undefined
+        ? 'Restart your dev server'
+        : `Restart your dev server (\`${devCommand}\`)`;
+}
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export function restartHint(framework, mcpStatus, 
+/** The project's own dev command, when package.json named one. */
+devCommand) {
+    const dev = `${devServerRestart(framework, devCommand)}.`;
+    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
+    //
+    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
+    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
+    // people complete the agent half, never complete the app half, and keep a daemon running for
+    // weeks with nothing to drive — so this is the last instruction most of them read.
+    //
+    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
+    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
+    // running, an app running that never dialled us, a tab that closed — with the fix for each.
+    // The one thing that works BEFORE the restart, so it goes before it.
+    //
+    // What comes after the restart, named as a JOB rather than as a capability.
+    //
+    // This used to point at a `reticle demo` command that opened its own browser and drove one
+    // control. It was cut: a demo command is a side show. The thing a user needs to see is THEIR app,
+    // instrumented in THEIR codebase, driven by THEIR agent through the tools they just installed —
+    // because that is the workflow they are deciding whether to adopt, and a bespoke demo path proves
+    // nothing about it.
+    //
+    // So the close hands the agent the sequence instead. It is deliberately one drive of one real
+    // flow ending in a verdict, because an install that ends in "the tools are available" is an
+    // install that ends in nothing.
+    const demo = 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
+        "proving itself, and it is the agent's job, not a separate command.";
+    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
+        'it has not.';
+    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
+    // up nothing, so advice about one would be advice about something we did not do.
+    if (!wasMcpRegistered(mcpStatus))
+        return `${dev}\n${demo}\n${prove}`;
+    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
+    //
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
+    // was written for and wrong here, because the two cases have opposite answers to "must anybody
+    // restart". Every second project on a machine, and every Claude Code plugin install, took the
+    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
+    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
+    // stops with the project wired and nothing driven, which is the exact failure the install path
+    // exists to prevent, caused by the install path itself.
+    if (mcpStatus === StepStatus.ALREADY) {
+        return (`${dev}\n` +
+            `${demo}\n` +
+            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+            'and the tools are available now.\n' +
+            `${prove}\n` +
+            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+            'nothing here is waiting on a human.');
+    }
+    return (`${dev}\n` +
+        `${demo}\n` +
+        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
+        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
+        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
+        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
+        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
+        'project starts with the tools already there.\n' +
+        `${prove}\n` +
+        'Once it shows a session, drive one flow and report the verdict — that is the install ' +
+        'finished. Do it now; nothing here is waiting on a human.');
+}

package/dist/init/confirm.d.ts

@@ -19,26 +19,29 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
- *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
- *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
- *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
- *    the ONE command that is outstanding and the one that proves it worked.
+ *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
+ *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
+ *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
+ *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
+ *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
+ *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
+ *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
+ *    it worked.
  */
 import { InitConfirmation } from '@reticlehq/core';
-import type { InitOutcome } from '@reticlehq/core';
-/**
- * How long a human is asked to wait.
- *
- * Long enough for a page that is already loading to finish dialling, short enough that somebody who
- * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
- * have not typed the command that would make it succeed, and the message tells them which one.
- */
-export declare const CONFIRM_WINDOW_MS = 12000;
-export declare const CONFIRM_POLL_MS = 500;
+import type { DevServerEntry, InitOutcome } from '@reticlehq/core';
 export interface ConfirmDeps {
     /** Session ids connected right now, or null when nothing is listening on the bridge port. */
     listSessionIds: () => Promise<readonly string[] | null>;
+    /**
+     * The dev servers that have announced themselves, read at the END of the wait rather than the
+     * start: a dev server booting alongside `init` is the common case, and asking before it has
+     * finished listening would report the state we are trying to move away from.
+     *
+     * Optional so every existing construction of these deps — and any embedder's — keeps working and
+     * simply gets today's less specific message.
+     */
+    listDevServers?: () => readonly DevServerEntry[];
     now: () => number;
     sleep: (ms: number) => Promise<void>;
     windowMs?: number;
@@ -77,23 +80,19 @@ export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConf
  * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
  * up when the agent loads the tools — so it is a notice.
  */
-export declare function confirmationMessage(confirmation: InitConfirmation, port: number): string;
 /**
- * What a non-TTY run says instead of waiting.
+ * Narrow "no app connected" using what the dev servers themselves announced.
  *
- * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
- * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
- * other half of that decision: the agent path IS the prescribed path (every skill and every README
- * block tells an agent to run exactly this command), so the one message joining "init finished" to
- * "an app connected" was withheld from most of the people who run it. They were left with files on
- * disk, an exit code of 0, and nothing saying the page half had not happened.
+ * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
+ * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
+ * opened. An announced entry is proof the plugin is loaded in the process that is actually running
+ * — which means the config is right and it has already been restarted.
  *
- * It claims nothing it did not check. It did not look for a session, so it does not say whether one
- * exists — a one-shot look would be worse than none, because a daemon is shared across every project
- * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
- * green `confirmAppConnected` refuses by design.
+ * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
+ * different fact; neither becomes more true because a dev server is up.
  */
-export declare function unwatchedMessage(port: number): string;
+export declare function sharpenWithDevServers(confirmation: InitConfirmation, running: readonly DevServerEntry[]): InitConfirmation;
+export declare function confirmationMessage(confirmation: InitConfirmation, port: number, running?: readonly DevServerEntry[]): string;
 /**
  * Finish `init` on evidence rather than on a write.
  *

package/dist/init/confirm.js

@@ -19,14 +19,21 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
- *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
- *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
- *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
- *    the ONE command that is outstanding and the one that proves it worked.
+ *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
+ *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
+ *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
+ *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
+ *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
+ *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
+ *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
+ *    it worked.
  */
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
+import { readDevServers } from '../daemon/dev-servers.js';
+import { devServersForProject } from '@reticlehq/core';
+import { readProjectId } from '../cli/cli-port.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 import { reportInitOutcome } from '../telemetry/init-telemetry.js';
 /**
  * How long a human is asked to wait.
@@ -35,8 +42,8 @@ import { reportInitOutcome } from '../telemetry/init-telemetry.js';
  * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
  * have not typed the command that would make it succeed, and the message tells them which one.
  */
-export const CONFIRM_WINDOW_MS = 12_000;
-export const CONFIRM_POLL_MS = 500;
+const CONFIRM_WINDOW_MS = 12_000;
+const CONFIRM_POLL_MS = 500;
 /**
  * Poll until an app connects or the window runs out.
  *
@@ -78,7 +85,23 @@ const PROVE_COMMAND = '`npx @reticlehq/server status`';
  * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
  * up when the agent loads the tools — so it is a notice.
  */
-export function confirmationMessage(confirmation, port) {
+/**
+ * Narrow "no app connected" using what the dev servers themselves announced.
+ *
+ * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
+ * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
+ * opened. An announced entry is proof the plugin is loaded in the process that is actually running
+ * — which means the config is right and it has already been restarted.
+ *
+ * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
+ * different fact; neither becomes more true because a dev server is up.
+ */
+export function sharpenWithDevServers(confirmation, running) {
+    if (confirmation !== InitConfirmation.NO_SESSION)
+        return confirmation;
+    return 0 === running.length ? InitConfirmation.NO_SESSION : InitConfirmation.NO_PAGE;
+}
+export function confirmationMessage(confirmation, port, running = []) {
     if (confirmation === InitConfirmation.CONNECTED) {
         return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
             '      Ask your agent to drive a flow.');
@@ -89,6 +112,15 @@ export function confirmationMessage(confirmation, port) {
             '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
             `${PROVE_COMMAND} confirms the app.`);
     }
+    if (confirmation === InitConfirmation.NO_PAGE) {
+        // Deliberately never says "restart". The announcement is proof they already did — telling them
+        // again is how a correct instruction reads as the tool not knowing what is going on.
+        const where = running.map((s) => `        ${s.url}`).join('\n');
+        return ('  [⚠] your dev server has Reticle loaded, and no page has connected yet — so the only step ' +
+            'left is opening the app.\n' +
+            `      Open it in a browser:\n${where}\n` +
+            `      ${PROVE_COMMAND} then confirms it.`);
+    }
     return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
         'done.\n' +
         '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
@@ -110,7 +142,7 @@ export function confirmationMessage(confirmation, port) {
  * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
  * green `confirmAppConnected` refuses by design.
  */
-export function unwatchedMessage(port) {
+function unwatchedMessage(port) {
     return ('  [ℹ] the files are written. An app CONNECTING is what finishes the install, and this run did ' +
         'not wait to see one.\n' +
         '      Start the dev server, load the app in a browser, then ' +
@@ -142,13 +174,21 @@ export async function confirmInstall(result, io, deps, report = reportInitOutcom
     }
     io.print('');
     io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
-    const confirmation = await confirmAppConnected(deps);
-    io.print(confirmationMessage(confirmation, deps.port));
+    const observed = await confirmAppConnected(deps);
+    const running = deps.listDevServers?.() ?? [];
+    const confirmation = sharpenWithDevServers(observed, running);
+    io.print(confirmationMessage(confirmation, deps.port, running));
     report({ ...outcome, confirmation });
 }
 /** The real deps: the daemon's own status endpoint, and whether a human is watching. */
 export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
     return {
+        // Scoped to the project being set up. The registry is machine-wide, so unscoped it reported a
+        // sibling app's dev server as this one's — see devServersForProject.
+        listDevServers: () => devServersForProject(readDevServers(reticleStateHome()), {
+            projectId: readProjectId(process.cwd()),
+            root: process.cwd(),
+        }),
         listSessionIds: async () => {
             const payload = await fetchStatus(port);
             // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"

package/dist/init/cra.d.ts

@@ -12,11 +12,32 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
-/** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
 export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
-export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export declare function craDevModulePath(typescript: boolean): string;
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export declare const CRA_DEV_MODULE_PATH: string;
 export declare const CRA_ENV_PATH = ".env.development.local";
 export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export declare const URL_VAR = "REACT_APP_RETICLE_URL";
 /**
  * What the app itself says when the token is not there.
  *
@@ -45,6 +66,14 @@ export declare const CRA_TOKEN_PER_MACHINE_NOTICE: string;
 /** Add the import after the last existing one, or null when it is already present. */
 export declare function craImportPatch(source: string): string | null;
 /** Set the token variable, or null when nothing needs to change. */
-export declare function craEnvPatch(existing: string | null, token: string): string | null;
-/** The dev-only connect module imported from `src/index.tsx`. */
-export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;
+export declare function craEnvPatch(existing: string | null, token: string, url?: string): string | null;
+/** Options for the CRA connect module. */
+export interface CraDevModuleOptions {
+    /**
+     * When false, emit a `.js`-shaped body (no `export {}`). Default true for callers that predate
+     * the language branch.
+     */
+    typescript?: boolean;
+}
+/** The dev-only connect module imported from the app entry. */
+export declare function craDevModuleFile(port: number | undefined, projectId?: string, options?: CraDevModuleOptions): string;

package/dist/init/cra.js

@@ -12,12 +12,36 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
+import { bridgeWsUrl } from '@reticlehq/core';
 import { CLI } from './agent-rules.js';
-/** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
-export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export function craDevModulePath(typescript) {
+    return typescript ? 'src/reticle-dev.ts' : 'src/reticle-dev.js';
+}
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export const CRA_DEV_MODULE_PATH = craDevModulePath(true);
 export const CRA_ENV_PATH = '.env.development.local';
 export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export const URL_VAR = 'REACT_APP_RETICLE_URL';
 /**
  * What the app itself says when the token is not there.
  *
@@ -64,44 +88,91 @@ export function craImportPatch(source) {
     return lines.join('\n');
 }
 /** Set the token variable, or null when nothing needs to change. */
-export function craEnvPatch(existing, token) {
+export function craEnvPatch(existing, token, url) {
     if ('' === token)
         return null;
-    const line = `${TOKEN_VAR}=${token}`;
-    if (null === existing || '' === existing.trim())
-        return `${line}\n`;
-    if (existing.includes(line))
-        return null;
-    // Replace rather than append: two assignments of one variable is a silent coin flip on which wins.
-    if (new RegExp(`^${TOKEN_VAR}=`, 'm').test(existing)) {
-        return existing.replace(new RegExp(`^${TOKEN_VAR}=.*$`, 'm'), line);
+    const pairs = [
+        [TOKEN_VAR, token],
+        ...(url !== undefined && url.length > 0 ? [[URL_VAR, url]] : []),
+    ];
+    let next = null === existing || '' === existing.trim() ? '' : existing;
+    for (const [name, value] of pairs) {
+        const line = `${name}=${value}`;
+        if (next.includes(line))
+            continue;
+        // Replace rather than append: two assignments of one variable is a silent coin flip on which
+        // wins, and for the URL that coin decides which daemon the app talks to.
+        if (new RegExp(`^${name}=`, 'm').test(next)) {
+            next = next.replace(new RegExp(`^${name}=.*$`, 'm'), line);
+        }
+        else {
+            next = `${'' === next || next.endsWith('\n') ? next : `${next}\n`}${line}\n`;
+        }
     }
-    return `${existing.endsWith('\n') ? existing : `${existing}\n`}${line}\n`;
+    return next === (existing ?? '') ? null : next;
 }
-/** The dev-only connect module imported from `src/index.tsx`. */
-export function craDevModuleFile(port, projectId) {
+/** The dev-only connect module imported from the app entry. */
+export function craDevModuleFile(port, projectId, options = {}) {
+    const typescript = false !== options.typescript;
     const fields = [];
+    // `bridgeWsUrl`, not a hand-written string. This was the only client URL in the product spelling
+    // the host as `127.0.0.1` while every other generator said `localhost` — same endpoint, but a
+    // difference with no reason behind it is the kind that becomes a real one after somebody edits half
+    // of it.
     if (port !== undefined)
-        fields.push(`url: 'ws://127.0.0.1:${String(port)}/reticle'`);
+        fields.push(`url: '${bridgeWsUrl(port)}'`);
     if (projectId !== undefined && projectId.length > 0)
         fields.push(`projectId: '${projectId}'`);
-    const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
+    // Multiline on purpose (#684): a single-line connect + console.error fails CRA boilerplate
+    // Prettier (printWidth 80) and the project's own lint blocks a clean install.
+    const connectFields = [
+        ...fields.map((f) => `      ${f},`),
+        '      ...(url.length > 0 ? { url } : {}),',
+        '      ...(token.length > 0 ? { token } : {}),',
+    ].join('\n');
+    // Split so every emitted line stays under a CRA boilerplate printWidth of 80 (#684). A single
+    // JSON.stringify of the whole note is ~290 characters and fails prettier-as-eslint on install.
+    // Chunks are joined with `+` in the emitted file; together they equal `[reticle] ${CRA_TOKEN_MISSING_NOTE}`.
+    const missingChunks = [
+        `[reticle] ${TOKEN_VAR} is not set, so Reticle `,
+        'cannot pair with the daemon. The pairing token is ',
+        `per-machine and ${CRA_ENV_PATH} is gitignored by `,
+        "CRA's template, so it does not survive a clone. Run ",
+        `\`${CLI} init\` in this project to write it for this `,
+        'machine.',
+    ].map((c) => JSON.stringify(c));
+    // Eight spaces match the indent inside `console.error(` below.
+    const missingExpr = missingChunks.join(' +\n        ');
+    // `export {}` is a TypeScript empty-module marker. A `.js` file with it is fine under Babel, but
+    // the workaround reporters used was to drop it when renaming to `.js` — keep the JS emit clean.
+    const trailer = typescript ? '\nexport {};\n' : '\n';
     return `// Dev-only: connect Reticle. Imported for its side effect from src/index.tsx.
 //
-// CRA's public/index.html is a static template the bundler never processes for modules, so the
-// connect cannot live there. The pairing token arrives through REACT_APP_RETICLE_TOKEN because
-// REACT_APP_* is the only thing CRA inlines into browser code.
+// CRA's public/index.html is a static template the bundler never processes for
+// modules, so the connect cannot live there. The pairing token arrives through
+// REACT_APP_RETICLE_TOKEN because REACT_APP_* is the only thing CRA inlines
+// into browser code.
 if (process.env.NODE_ENV === 'development') {
   void import('@reticlehq/react').then(({ reticle, install }) => {
     install();
     const token = process.env.${TOKEN_VAR} ?? '';
-    // Loud on purpose: without this the only symptom is the bridge's generic auth failure.
-    if (token.length === 0) console.error(${JSON.stringify(`[reticle] ${CRA_TOKEN_MISSING_NOTE}`)});
+    // Written by \`reticle init\` from the daemon that was live when it ran, and
+    // refreshed by re-running it. CRA gives us no hook to resolve this at
+    // dev-server start, so if the daemon moves, re-run \`reticle init\` rather
+    // than editing the url below.
+    const url = process.env.${URL_VAR} ?? '';
+    // Loud on purpose: without this the only symptom is the bridge's generic
+    // auth failure.
+    if (token.length === 0) {
+      console.error(
+        ${missingExpr},
+      );
+    }
     // Still attempt it — a bridge running without a token pairs fine.
-    reticle.connect({ ${inline}...(token.length > 0 ? { token } : {}) });
+    reticle.connect({
+${connectFields}
+    });
   });
 }
-
-export {};
-`;
+${trailer}`;
 }