@reticlehq/init 2.14.0

package/dist/nuxt-patch.js

@@ -0,0 +1,33 @@
+/**
+ * Wiring Reticle into a Nuxt app: the config gets the token `define`, the plugin gets written.
+ *
+ * Nuxt owns its own Vite instance and renders its own HTML, so there is no `vite.config` to patch
+ * and no `index.html` to inject into — the same position Astro is in, and it takes the same config
+ * patch (see `vite-owning-config.ts`). The half Nuxt does differently is the connect itself: Nuxt's
+ * own idiom is a `.client` plugin it auto-registers, not a `<script>` in a layout.
+ *
+ * The config patch is not optional and not cosmetic. The bridge requires a pairing token even on
+ * localhost, nothing in a browser can read the file it lives in, and Nuxt loads no plugin of ours
+ * that could inject it — so a plugin written beside an unpatched config is an app that dials the
+ * daemon and is refused, with one line in a console nobody had open. That is why the two halves are
+ * planned atomically.
+ */
+import { patchViteOwningConfig } from './vite-owning-config.js';
+import { sdkImport } from './snippets.js';
+import { UiLibrary } from './detect.js';
+/** The config filenames Nuxt itself accepts, in the order `init` should prefer them. */
+export const NUXT_CONFIG_CANDIDATES = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'];
+/**
+ * Nuxt's half of the Vite-owning config patch.
+ *
+ * The framework-neutral sensor, never the React kit: Nuxt renders Vue, and `FRAMEWORK_ADAPTERS`
+ * installs `@reticlehq/browser` for it — so that is what the plugin imports and what Vite must
+ * pre-bundle. Declaring the React kit here would warm a dep cache for a package that is not there.
+ */
+const NUXT_VITE_CONFIG = {
+    defineCall: /defineNuxtConfig\s*\(\s*\{/,
+    sdkSpecifier: sdkImport(UiLibrary.VUE).specifier,
+};
+export function patchNuxtConfig(source) {
+    return patchViteOwningConfig(source, NUXT_VITE_CONFIG);
+}

package/dist/patch-kind.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The outcome vocabulary shared by every conservative source patcher in `init` (Vite config, Next
+ * config, Next root layout). One enum so a new patcher cannot invent a fourth status the reporter
+ * has no symbol for.
+ */
+export declare const PatchKind: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type PatchKind = (typeof PatchKind)[keyof typeof PatchKind];
+export type SourcePatch = {
+    kind: typeof PatchKind.APPLY;
+    code: string;
+} | {
+    kind: typeof PatchKind.ALREADY;
+} | {
+    kind: typeof PatchKind.MANUAL;
+    reason: string;
+};

package/dist/patch-kind.js

@@ -0,0 +1,10 @@
+/**
+ * The outcome vocabulary shared by every conservative source patcher in `init` (Vite config, Next
+ * config, Next root layout). One enum so a new patcher cannot invent a fourth status the reporter
+ * has no symbol for.
+ */
+export const PatchKind = {
+    APPLY: 'apply',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+};

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

@@ -0,0 +1,16 @@
+/**
+ * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
+ *
+ * Its own module rather than more of `plan-framework.ts`, which was at the 1000-line backstop.
+ * Cohesive on its own terms: this is the only framework whose wiring reaches outside the renderer,
+ * into a preload and a main process that the web frameworks have no equivalent of.
+ */
+import { type PlanInput, type Step } from './plan.js';
+/**
+ * electron-vite: the renderer plugin, then capabilities, then the two Electron halves.
+ *
+ * The plugin and the Electron steps are independent. A renderer without the preload still
+ * connects — it only loses IPC visibility — so they stay separate rather than collapsing to one
+ * manual recipe the way Astro's config+layout pair does.
+ */
+export declare function electronViteSteps(input: PlanInput): Step[];

package/dist/plan-electron-vite.js

@@ -0,0 +1,72 @@
+/**
+ * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
+ *
+ * Its own module rather than more of `plan-framework.ts`, which was at the 1000-line backstop.
+ * Cohesive on its own terms: this is the only framework whose wiring reaches outside the renderer,
+ * into a preload and a main process that the web frameworks have no equivalent of.
+ */
+import { StepStatus } from './plan.js';
+import { StepTitle } from './connect-steps.js';
+import { capabilitiesStep, patchStep } from './plan-framework.js';
+import { patchElectronViteConfig } from './electron-vite-patch.js';
+import { patchElectronMain, patchElectronPreload } from './electron-patch.js';
+import { ELECTRON_CAPTURE_FIX, ELECTRON_PRELOAD_FIX } from './desktop-doctor.js';
+import { electronViteManual, ELECTRON_VITE_DEV_MODULE_PATH } from './snippets.js';
+/**
+ * electron-vite: the renderer plugin, then capabilities, then the two Electron halves.
+ *
+ * The plugin and the Electron steps are independent. A renderer without the preload still
+ * connects — it only loses IPC visibility — so they stay separate rather than collapsing to one
+ * manual recipe the way Astro's config+layout pair does.
+ */
+export function electronViteSteps(input) {
+    const port = input.options.port;
+    const manual = electronViteManual(port, input.detection.uiLibrary);
+    const cfg = input.electronViteConfig ?? null;
+    const plugin = null === cfg
+        ? {
+            title: StepTitle.ELECTRON_VITE_PLUGIN,
+            target: 'electron.vite.config',
+            status: StepStatus.MANUAL,
+            detail: manual,
+        }
+        : patchStep(StepTitle.ELECTRON_VITE_PLUGIN, cfg.path, patchElectronViteConfig(cfg.source, port), 'add reticle({ desktop: true }) to the renderer plugins (also injects connect())', manual);
+    return [
+        plugin,
+        ...capabilitiesStep(input, ELECTRON_VITE_DEV_MODULE_PATH),
+        ...electronPreloadStep(input),
+        ...electronCaptureStep(input),
+    ];
+}
+function electronPreloadStep(input) {
+    const file = input.electronPreload ?? null;
+    if (null === file) {
+        return [
+            {
+                title: StepTitle.ELECTRON_PRELOAD,
+                target: 'preload',
+                status: StepStatus.MANUAL,
+                detail: ELECTRON_PRELOAD_FIX,
+            },
+        ];
+    }
+    return [
+        patchStep(StepTitle.ELECTRON_PRELOAD, file.path, patchElectronPreload(file.source, file.path), 'require the IPC shim as the first line of preload', ELECTRON_PRELOAD_FIX),
+    ];
+}
+function electronCaptureStep(input) {
+    const file = input.electronMain ?? null;
+    if (null === file) {
+        return [
+            {
+                title: StepTitle.ELECTRON_CAPTURE,
+                target: 'main',
+                status: StepStatus.MANUAL,
+                detail: ELECTRON_CAPTURE_FIX,
+            },
+        ];
+    }
+    return [
+        patchStep(StepTitle.ELECTRON_CAPTURE, file.path, patchElectronMain(file.source, file.path), 'installReticleCapture on the BrowserWindow so screenshots work', ELECTRON_CAPTURE_FIX),
+    ];
+}

package/dist/plan-framework.d.ts

@@ -0,0 +1,122 @@
+/**
+ * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
+ * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
+ * this one is the per-framework detail, and they grow for different reasons.
+ */
+import { type SourcePatch } from './patch-kind.js';
+import { type PlanInput, type Step } from './plan.js';
+import { StepTitle } from './connect-steps.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() to plugins (stamps data-reticle-source in .svelte components)";
+    /**
+     * 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 capabilitiesStep(input: PlanInput, path?: string): Step[];
+export declare function viteSteps(input: PlanInput, detail?: string, inject?: boolean): Step[];
+/**
+ * Turn a conservative source patch into a step: applied when it patched, already when the wiring is
+ * there, and the hand-edit instructions when the file shape wasn't one we recognise.
+ */
+export declare function patchStep(title: StepTitle, path: string, patch: SourcePatch, applyDetail: string, manualDetail: string): Step;
+export declare function nextSteps(input: PlanInput): Step[];
+/**
+ * Create React App: the connect goes in `src/index.tsx`, the token in `.env.development.local`.
+ *
+ * The previous plan pointed at `index.html`, which cannot work — CRA's is a static template the
+ * bundler never processes for modules. Reported from a real cra-redux-saga app.
+ */
+export declare function craSteps(input: PlanInput): Step[];
+/**
+ * Nuxt: the client plugin written, and the config patched so it can pair.
+ *
+ * This used to be one MANUAL step carrying the whole recipe, so `init` ended on a ⚠ and exited 1 —
+ * a correct recipe nobody applies is the same outcome as no recipe. What it could not do until now
+ * was the pairing token: the bridge requires one even on localhost, nothing in a browser can read
+ * the file it lives in, and Nuxt loads no plugin of ours that could inject it. `nuxt.config`'s
+ * `vite.define` is the one place that can, which is also where the journal watch-ignore goes.
+ *
+ * ATOMIC, for the reason `astroSteps` is: a plugin written beside a config we could not patch is an
+ * app that dials the bridge and is refused, reported as one green step and one caveat when it is a
+ * guaranteed non-connection. If the config cannot be patched, BOTH halves go back to the recipe.
+ */
+export declare function nuxtSteps(input: PlanInput): Step[];
+/**
+ * React Router framework mode: the client entry, WRITTEN.
+ *
+ * #678 happened here — every step reported green and the daemon showed zero sessions for 20+
+ * minutes, because framework mode renders HTML through its own request handler and the Vite plugin's
+ * `transformIndexHtml` injection never fires. The connect has to come from `app/entry.client.tsx`,
+ * and that used to be printed as a recipe: `init` exited 0 over an app that could not connect.
+ *
+ * The file is an OVERRIDE of a default React Router supplies, so when it is absent the generated one
+ * carries React Router's own default entry as well as the import — a file containing only our import
+ * would replace that default with one that never hydrates. When it is present, one line is added to
+ * it and nothing else is touched.
+ */
+export declare function reactRouterSteps(input: PlanInput): Step[];
+/**
+ * TanStack Start: the client-document connect, printed rather than written.
+ *
+ * `src/routes/__root.tsx` is the document Start SSRs. A static import of the SDK on that module
+ * 500s, so writing one is worse than a documented manual step. See `tanstackStartManual`.
+ */
+export declare function tanstackStartSteps(input: PlanInput): Step[];
+export declare function svelteKitSteps(input: PlanInput): Step[];
+/**
+ * Astro: the config define + build target, and the connect script in ONE layout.
+ *
+ * Astro was the last gated stack left printing a recipe it did not apply. It still falls back to the
+ * printed one whenever the choice is not obvious — no config, no single layout, or a shape the
+ * patchers do not fully recognise — because which page or layout to instrument is a real decision
+ * and a half-edited build config is worse than a documented manual step.
+ */
+export declare function astroSteps(input: PlanInput): Step[];
+/**
+ * A Content-Security-Policy whose `connect-src` excludes the bridge, said out loud at install time.
+ *
+ * Both reported cases were Next apps where `init` printed success for every step and the app then
+ * never connected: the browser blocked the WebSocket and reported it in its own console, which
+ * nothing on this side reads. A NOTICE rather than a step, because editing someone's security policy
+ * is theirs to do — but it carries the exact text to paste, which is the difference between a
+ * warning and a fix.
+ */
+export declare function cspStep(input: PlanInput): Step[];
+/**
+ * The plain-HTML path: no bundler to hook, so the connect snippet is printed for a hand edit.
+ *
+ * A function of its own, and NOT a fallthrough. Every framework is sent here on purpose or not at
+ * all — a member of `Framework` with no adapter entry is a compile error in `FRAMEWORK_ADAPTERS`,
+ * where the if/else chain this replaced used to hand it these instructions silently.
+ */
+export declare function htmlSteps(input: PlanInput): Step[];
+/**
+ * The per-framework half of the plan, looked up rather than switched.
+ *
+ * `FRAMEWORK_ADAPTERS` is a `Record<Framework, FrameworkAdapter>`, so a member added to `Framework`
+ * is a compile error in that one table instead of a framework the plan quietly does not serve. The
+ * exhaustive switch this replaced gave the same guarantee for the steps alone; the record gives it
+ * for the packages, the connect-step titles and the unverified-note flag in the same edit.
+ */
+export declare function frameworkSteps(input: PlanInput): Step[];