@reticlehq/init 3.2.0 → 3.4.0

package/dist/plan/plan-types.d.ts

@@ -114,6 +114,13 @@ export interface PlanInput {
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     mcpExists: boolean;
+    /**
+     * Whether `init` is running inside Claude Code itself, which is the one case where writing its
+     * project-scope `.mcp.json` is known to be wanted. See `CLAUDE_PROJECT_SPEC`.
+     */
+    insideClaudeCode?: boolean | undefined;
+    /** The project `.mcp.json` at the agent's root, read so the merge stays idempotent. */
+    claudeProjectConfig?: string | null | undefined;
     /** `process.platform`. Injected so this module stays pure. Windows is the only branch. */
     platform?: string;
     /**
@@ -175,10 +182,15 @@ export interface PlanInput {
         source: string;
     } | null | undefined;
     /**
-     * Existing `src/env.d.ts` content, when present — where the Vite-define ambient declarations go
-     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677).
+     * Existing `src/env.d.ts` content, when present — where the window ambient declarations go
+     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677, #1008).
      */
     astroEnvDts?: string | null | undefined;
+    /**
+     * Existing `src/components/ReticleDev.ts` content, when present — the local module whose
+     * static SDK import is what actually dials the daemon.
+     */
+    astroReticleDev?: string | null | undefined;
     /** Discovered Next config filename (e.g. 'next.config.mjs'), or null. */
     nextConfigFile: string | null;
     /** Source of that Next config, so the export can be wrapped in withReticle. */
@@ -214,6 +226,8 @@ export interface PlanInput {
     viteDevModuleExists?: boolean | undefined;
     /** Whether src/hooks.client.ts already exists (SvelteKit idempotency). */
     svelteKitHooksExists?: boolean;
+    /** Its content, so a re-run with a new `--port` can move the URL baked into it. */
+    svelteKitHooksSource?: string | null | undefined;
     /** Whether app/entry.client.tsx already exists — it decides whether init writes one or patches it. */
     reactRouterEntryExists?: boolean;
     /**
@@ -224,6 +238,8 @@ export interface PlanInput {
      * added to whatever the app already put in it. Existence alone could only ever print a recipe.
      */
     reactRouterEntrySource?: string | null | undefined;
+    /** The installed Vite's major, for the configs that own their Vite (see `installedViteMajor`). */
+    viteMajor?: number | null | undefined;
     /** Discovered Nuxt config: its path + source, or null. It is where the pairing token is inlined. */
     nuxtConfig?: {
         path: string;
@@ -233,6 +249,8 @@ export interface PlanInput {
     nuxtHasAppDir?: boolean | undefined;
     /** Whether the Nuxt client plugin already exists (idempotency — the file is the owner's to edit). */
     nuxtPluginExists?: boolean | undefined;
+    /** Its content, so a re-run with a new `--port` can move the URL baked into it. */
+    nuxtPluginSource?: string | null | undefined;
     /**
      * TanStack Start's document module, when found (`src/routes/__root.tsx` or `app/routes/__root.tsx`).
      *
@@ -240,6 +258,29 @@ export interface PlanInput {
      * 500s — but the path has to be the one that actually exists, not a guess.
      */
     tanstackStartRoot?: string | undefined;
+    /** Its content, so `init` can render the connect component in it rather than print a recipe. */
+    tanstackStartRootSource?: string | null | undefined;
+    /** Whether the connect component `init` writes beside `routes/` already exists (it is the owner's). */
+    tanstackStartConnectExists?: boolean | undefined;
+    /** Its content, so a re-run with a new `--port` can move the URL baked into it. */
+    tanstackStartConnectSource?: string | null | undefined;
+    /** `angular.json`, read so the serve target can be pointed at the token route. */
+    angularWorkspace?: {
+        path: string;
+        source: string;
+    } | null | undefined;
+    /** The browser entry `angular.json` names (`src/main.ts` by default) — where the connect goes. */
+    angularEntry?: {
+        path: string;
+        source: string;
+    } | null | undefined;
+    /** The generated `reticle.proxy.mjs`, when a previous run left one (idempotency). */
+    angularProxySource?: string | null | undefined;
+    /**
+     * The plain-HTML app's `index.html`, when it has one — so a re-run over a page that already
+     * carries the connect snippet reports it as done instead of "will NOT connect".
+     */
+    htmlIndexSource?: string | null | undefined;
     /** CRA's bundled entry (src/index.tsx or .js) — where the connect import has to go. */
     craEntry?: {
         path: string;
@@ -283,6 +324,10 @@ export interface PlanInput {
     claudeCommandContent?: string | null | undefined;
     /** Current .cursor/commands/reticle.md content, or null when absent. */
     cursorCommandContent?: string | null | undefined;
+    /** `--hooks`: install the print-only Claude Code Stop hook. Off unless asked. */
+    hooks?: boolean | undefined;
+    /** Current .claude/settings.json content, or null when absent (the hook is MERGED into it). */
+    claudeSettingsContent?: string | null | undefined;
     /**
      * Absolute directory the AGENT runs in, when that is not the app's directory.
      *

package/dist/plan/plan-vite.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The Vite half of the plan: the `reticle()` plugin in a Vite config, and the dev module that
+ * carries `registerCapabilities` / `registerStore`.
+ *
+ * Split out of `plan-framework.ts`, which had grown to the edge of the line cap. It is its own
+ * module because every Vite-based stack (plain Vite, SvelteKit, React Router, Remix, TanStack
+ * Start, the Electron renderers) composes these steps, while the rest of `plan-framework.ts` is one
+ * builder per framework that has its own files to write.
+ */
+import { type PlanInput, type Step } from './plan-types.js';
+/** What adding `reticle()` to a Vite config buys, which differs by framework. */
+export declare const VITE_PLUGIN_DETAIL: {
+    /** A plain Vite app gets both halves from the plugin. */
+    readonly VITE: "add reticle() to plugins (also injects connect())";
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    readonly SVELTEKIT: "add reticle({ inject: false }) to plugins (stamps data-reticle-source in .svelte components; the client hook connects)";
+    /**
+     * React Router framework mode renders through its own request handler, so the plugin's HTML
+     * injection never fires and connect() comes from the client entry instead. The plugin is still
+     * required for the same reason it is under SvelteKit: without it every verdict on the app comes
+     * back with no file:line at all.
+     */
+    readonly REACT_ROUTER: "add reticle() to plugins (stamps data-reticle-source in .tsx components)";
+    /**
+     * TanStack Start SSRs its own HTML, so the plugin's HTML injection never fires and connect()
+     * comes from a client effect instead. `inject: false` is load-bearing honesty: leaving the
+     * default would keep reporting "also injects connect()" for a transform that never runs.
+     * The plugin is still required for the same reason it is under SvelteKit: without it every
+     * verdict on the app comes back with no file:line at all.
+     */
+    readonly TANSTACK_START: "add reticle({ inject: false }) to plugins (stamps data-reticle-source; Start SSRs its own HTML so connect() cannot come from the plugin)";
+};
+export declare function capabilitiesTodo(path: string, stores: readonly string[]): string;
+/**
+ * The dev module carrying `registerCapabilities` / `registerStore`.
+ *
+ * Without it every app came up `hasCapabilities: false` with a `reticle_state` holding nothing but
+ * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
+ * only when absent, because it is the one generated file a user is expected to EDIT.
+ */
+/**
+ * Is there state left that ONLY the app can hand over?
+ *
+ * This used to ask a much bigger question — "does the generated file register anything at all?" —
+ * and fired on almost every install, because almost every install generated a file whose testids
+ * and stores were both empty. The answer was homework: go read the source, uncomment a line, add
+ * data-testid attributes, then drive to prove it. Several turns, on every onboarding.
+ *
+ * Two of those three are no longer anyone's homework. Testids are read from the live DOM, and a
+ * store passed through a React context provider (Redux, TanStack Query) is discovered and
+ * registered on the first commit. What is left is the genuinely unreachable case: a module-scope
+ * store, or one needing an argument only the source supplies — Zustand, Jotai atoms, an XState
+ * actor. Nothing in the running app points at those, so the notice still has to fire, and it now
+ * fires ONLY there.
+ *
+ * `wired` are stores init resolved and wrote a live `registerStore` call for. Hints are not
+ * registrations: they land in the file as a commented line, and counting one as a registration
+ * silences the notice whose whole purpose is to say "act on the hint".
+ */
+export declare function needsManualStore(hints: readonly string[], wired: readonly unknown[]): boolean;
+export declare function capabilitiesStep(input: PlanInput, path?: string): Step[];
+export declare function viteSteps(input: PlanInput, detail?: string, inject?: boolean): Step[];

package/dist/plan/plan-vite.js

@@ -0,0 +1,256 @@
+/**
+ * The Vite half of the plan: the `reticle()` plugin in a Vite config, and the dev module that
+ * carries `registerCapabilities` / `registerStore`.
+ *
+ * Split out of `plan-framework.ts`, which had grown to the edge of the line cap. It is its own
+ * module because every Vite-based stack (plain Vite, SvelteKit, React Router, Remix, TanStack
+ * Start, the Electron renderers) composes these steps, while the rest of `plan-framework.ts` is one
+ * builder per framework that has its own files to write.
+ */
+import { newViteConfig, patchViteConfig, VitePatchKind, VITE_IMPORT } from '../patch/vite-config.js';
+import { viteManual, viteDevModuleFile, VITE_DEV_MODULE_PATH } from '../patch/snippets.js';
+import { hasOptOut, OPT_OUT_MARKER } from '../detect/declared/init-opt-out.js';
+import { Framework } from '../detect/detect.js';
+import { StepStatus } from './plan-types.js';
+import { StepTitle } from './connect-steps.js';
+import { alreadyOrMovedPort } from './port-steps.js';
+/** What adding `reticle()` to a Vite config buys, which differs by framework. */
+export const VITE_PLUGIN_DETAIL = {
+    /** A plain Vite app gets both halves from the plugin. */
+    VITE: 'add reticle() to plugins (also injects connect())',
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    SVELTEKIT: 'add reticle({ inject: false }) to plugins (stamps data-reticle-source in .svelte components; the client hook connects)',
+    /**
+     * React Router framework mode renders through its own request handler, so the plugin's HTML
+     * injection never fires and connect() comes from the client entry instead. The plugin is still
+     * required for the same reason it is under SvelteKit: without it every verdict on the app comes
+     * back with no file:line at all.
+     */
+    REACT_ROUTER: 'add reticle() to plugins (stamps data-reticle-source in .tsx components)',
+    /**
+     * TanStack Start SSRs its own HTML, so the plugin's HTML injection never fires and connect()
+     * comes from a client effect instead. `inject: false` is load-bearing honesty: leaving the
+     * default would keep reporting "also injects connect()" for a transform that never runs.
+     * The plugin is still required for the same reason it is under SvelteKit: without it every
+     * verdict on the app comes back with no file:line at all.
+     */
+    TANSTACK_START: 'add reticle({ inject: false }) to plugins (stamps data-reticle-source; Start SSRs its own HTML so connect() cannot come from the plugin)',
+};
+const CAPABILITIES_TITLE = StepTitle.CAPABILITIES;
+/**
+ * The one step `init` genuinely cannot finish, addressed to the AGENT reading this report.
+ *
+ * It used to read "Capabilities are empty until you edit that file" and describe the consequence to
+ * a human — homework, in a report a human mostly does not read, naming no file to open and no thing
+ * to look for. The agent that ran `init` is right there, has the codebase, and can finish this in
+ * the same minute; what it needed was the specific instruction, not the rationale.
+ *
+ * What is left is exactly what could not be PROVEN from source: which atoms/actor/queryClient an
+ * adapter-wrapped store should be built from, and which elements matter enough to name. `init`
+ * emits nothing it cannot prove, because a wrong import here throws on every dev page load — worse
+ * than an empty file.
+ */
+const CAPABILITIES_TODO_TITLE = StepTitle.CAPABILITIES_TODO;
+export function capabilitiesTodo(path, stores) {
+    return (`This app's state lives in a library nothing in the running app points at, so it is the one ` +
+        `thing Reticle cannot find for itself — reticle_state will not see it until you say where it ` +
+        `is.\n` +
+        `Do this now, before driving anything:\n` +
+        `  1. In ${path}, uncomment the suggested line and complete it: ${stores.join('; ')}.\n` +
+        `  2. Prove it: drive one flow and check reticle_state returns your key. An empty state read ` +
+        `means the line is still not doing anything, whatever else went green.`);
+}
+/**
+ * The dev module carrying `registerCapabilities` / `registerStore`.
+ *
+ * Without it every app came up `hasCapabilities: false` with a `reticle_state` holding nothing but
+ * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
+ * only when absent, because it is the one generated file a user is expected to EDIT.
+ */
+/**
+ * Is there state left that ONLY the app can hand over?
+ *
+ * This used to ask a much bigger question — "does the generated file register anything at all?" —
+ * and fired on almost every install, because almost every install generated a file whose testids
+ * and stores were both empty. The answer was homework: go read the source, uncomment a line, add
+ * data-testid attributes, then drive to prove it. Several turns, on every onboarding.
+ *
+ * Two of those three are no longer anyone's homework. Testids are read from the live DOM, and a
+ * store passed through a React context provider (Redux, TanStack Query) is discovered and
+ * registered on the first commit. What is left is the genuinely unreachable case: a module-scope
+ * store, or one needing an argument only the source supplies — Zustand, Jotai atoms, an XState
+ * actor. Nothing in the running app points at those, so the notice still has to fire, and it now
+ * fires ONLY there.
+ *
+ * `wired` are stores init resolved and wrote a live `registerStore` call for. Hints are not
+ * registrations: they land in the file as a commented line, and counting one as a registration
+ * silences the notice whose whole purpose is to say "act on the hint".
+ */
+export function needsManualStore(hints, wired) {
+    return hints.length > 0 && 0 === wired.length;
+}
+export function capabilitiesStep(input, path = VITE_DEV_MODULE_PATH) {
+    if (true === input.viteDevModuleExists) {
+        return [
+            {
+                title: CAPABILITIES_TITLE,
+                target: path,
+                status: StepStatus.ALREADY,
+                detail: 'file exists, left alone, it is yours to edit',
+            },
+        ];
+    }
+    const testids = input.testids ?? [];
+    const stores = input.storeHints ?? [];
+    const wired = input.foundStores ?? [];
+    // Testids no longer need counting here. They are read from the live DOM at announce time, so a
+    // number printed at install time would be a stale claim about a codebase that is about to change —
+    // which is exactly what "no data-testid values yet" used to be on an app whose testids arrive with
+    // a lazy route.
+    const found = 'testids read from the live DOM';
+    // A store we found and WIRED is a registration, so the notice must not fire. A store HINT is not:
+    // `stores` holds suggestions, written into the file as a commented line of the form
+    // `// import your store, then: registerStore(...)`. Counting a suggestion as a registration let
+    // the hint silence the notice whose entire job is to say "act on the hint".
+    //
+    // Measured against a real product UI (rowy — 70+ deps, jotai, a whole src/atoms tree): init
+    // detected jotai, offered one commented line, emitted NO notice, and wrote
+    // `registerCapabilities({ testids: [], signals: [], stores: [] })`. So `hasCapabilities` stayed
+    // false, `reticle_state` was empty forever, and the install gate reported "connected: 1,
+    // manual ⚠: none". Every check green, state observability zero.
+    //
+    // jotai is still exactly that case. A Redux or TanStack app is not, any more: its store rides a
+    // context provider and the React adapter registers it on the first commit, so `storeHints` no
+    // longer names either one and this notice no longer fires for them.
+    const nothingToRegister = needsManualStore(stores, wired);
+    return [
+        {
+            title: CAPABILITIES_TITLE,
+            target: path,
+            status: StepStatus.APPLY,
+            detail: `${found}; ${wired.length > 0
+                ? `registered ${wired.map((s) => `'${s.key}'`).join(', ')} from your source`
+                : stores.length > 0
+                    ? `store: uncomment the ${String(stores.length)} suggested line(s)`
+                    : 'no state library detected'}`,
+            write: {
+                path,
+                content: viteDevModuleFile(testids, stores, wired, input.detection.uiLibrary, input.detection.framework),
+            },
+            dependsOnInstall: true,
+        },
+        // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
+        // stores: [] })` registers nothing, so `hasCapabilities` stays false — correctly — and the ✓
+        // above reads as if the feature is on. Reported as exactly that confusion: "hasCapabilities false
+        // on every session while init said ✓ Capabilities + store".
+        //
+        // Beside the write rather than replacing it, for two reasons: only APPLY steps are written
+        // (run.ts), and SKILL.md tells the reader to skip ✓ lines — so a caveat carried on the ✓ is a
+        // caveat nobody reads.
+        ...(nothingToRegister
+            ? [
+                {
+                    title: CAPABILITIES_TODO_TITLE,
+                    target: path,
+                    status: StepStatus.NOTICE,
+                    detail: capabilitiesTodo(path, stores),
+                },
+            ]
+            : []),
+    ];
+}
+export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE, inject = true) {
+    // Capabilities are independent of whether the config needed patching. Attaching them to the APPLY
+    // branch meant a re-run on an already-wired app silently never created the module.
+    return [...viteConfigSteps(input, detail, inject), ...capabilitiesStep(input)];
+}
+function viteConfigSteps(input, detail, inject = true) {
+    const cfg = input.viteConfig;
+    const port = input.options.port;
+    // Stamp `data-reticle-source` unless this app renders through a non-DOM React reconciler, where a
+    // lowercase JSX tag is not an element and the stamp crashes the app at commit time. See
+    // `Detection.customReconciler`.
+    const stampSource = true !== input.detection?.customReconciler;
+    // An explicit "not here" is not an invitation. `init` runs unattended in a repo it has just met,
+    // and it was reported adding the plugin to an app whose config said Reticle was deliberately
+    // excluded. A NOTICE rather than a ⚠: opting out is a decision, not something to go and fix.
+    if (cfg !== null && hasOptOut(cfg.source)) {
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.NOTICE,
+                detail: `left alone: this config carries ${OPT_OUT_MARKER}. Remove that marker to instrument this app.`,
+            },
+        ];
+    }
+    // Plain Vite runs happily with no config file (`npm create vite`'s vanilla template has none), so
+    // make one. Only there: a Vite-based framework's missing config also lost the framework's own
+    // plugin, and a file carrying ours alone would not boot the app.
+    const plainVite = Framework.VITE === input.detection.framework;
+    if (null === cfg) {
+        if (!plainVite) {
+            return [
+                {
+                    title: StepTitle.VITE_PLUGIN,
+                    target: 'vite.config',
+                    status: StepStatus.MANUAL,
+                    detail: viteManual(port, input.detection.uiLibrary, inject, stampSource),
+                },
+            ];
+        }
+        const path = input.detection.typescript ? 'vite.config.ts' : 'vite.config.mjs';
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: path,
+                status: StepStatus.APPLY,
+                detail,
+                write: {
+                    path,
+                    content: newViteConfig(port, true === input.captureBodies, inject, stampSource),
+                    expect: [VITE_IMPORT, 'reticle('],
+                },
+                dependsOnInstall: true,
+            },
+        ];
+    }
+    const patch = patchViteConfig(cfg.source, port, true === input.captureBodies, inject, stampSource);
+    if (patch.kind === VitePatchKind.ALREADY) {
+        return [
+            alreadyOrMovedPort({
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.ALREADY,
+                detail: 'reticle() already in plugins',
+            }, cfg.source, port),
+        ];
+    }
+    if (patch.kind === VitePatchKind.MANUAL) {
+        return [
+            {
+                title: StepTitle.VITE_PLUGIN,
+                target: cfg.path,
+                status: StepStatus.MANUAL,
+                detail: `${patch.reason}\n\n${viteManual(port, input.detection.uiLibrary, inject, stampSource)}`,
+            },
+        ];
+    }
+    return [
+        {
+            title: StepTitle.VITE_PLUGIN,
+            target: cfg.path,
+            status: StepStatus.APPLY,
+            detail,
+            // Both halves, because either alone is a config that does not wire: the import without the
+            // call leaves `plugins` untouched, and the call without the import does not build.
+            write: { path: cfg.path, content: patch.code, expect: [VITE_IMPORT, 'reticle('] },
+            dependsOnInstall: true,
+        },
+    ];
+}