@reticlehq/init 3.3.0 → 3.4.0

package/dist/plan/plan-angular.js

@@ -0,0 +1,89 @@
+/**
+ * Angular CLI: the dev-only connect in the browser entry, and the dev-server route that hands it
+ * the pairing token. See `patch/angular.ts` for why the token takes that route and no other.
+ */
+import { ANGULAR_DEFAULT_ENTRY, ANGULAR_PROXY_PATH, ANGULAR_TOKEN_PATH, angularProxyFile, patchAngularJson, patchAngularMain, } from '../patch/angular.js';
+import { PatchKind } from '../patch/patch-kind.js';
+import { ANGULAR_WORKSPACE_FILE } from '../detect/detect.js';
+import { StepTitle } from './connect-steps.js';
+import { patchStep } from './plan-framework.js';
+import { alreadyOrMovedPort, retargetPort } from './port-steps.js';
+import { StepStatus } from './plan-types.js';
+const ANGULAR_SETUP_GATED_NOTE = 'The install gate scaffolds an Angular app (Angular 21, no SSR) on every release and requires a ' +
+    'session, and this wiring was proven by hand on Angular 22 with and without SSR; nothing yet ' +
+    'drives an Angular app to a verdict on each change. DOM, network, console and state ' +
+    'tools work here; component identity does not (that is the React adapter). If no session ' +
+    'appears, please open an issue.';
+const ENTRY_DETAIL = 'connect from the browser entry, dev-only (`ngDevMode`), through a dynamic import the ' +
+    'production build drops';
+const PROXY_DETAIL = 'the `ng serve`-only module that hands the page this machine’s pairing token, read from ' +
+    '~/.reticle at request time — never written into the project';
+const SERVE_DETAIL = `point the serve target's proxyConfig at ${ANGULAR_PROXY_PATH} (\`ng build\` never reads it)`;
+/** The full recipe, for when the entry is not a file `init` can see. */
+function entryManual(input, entryPath) {
+    const recipe = patchAngularMain('', input.options.port, input.options.projectId);
+    const code = recipe.kind === PatchKind.APPLY ? recipe.code : '';
+    return `Add this to your browser entry (${entryPath}):\n\n${code}`;
+}
+function proxyStep(input) {
+    const existing = input.angularProxySource ?? null;
+    if (null !== existing && existing.includes(ANGULAR_TOKEN_PATH)) {
+        return {
+            title: StepTitle.ANGULAR_TOKEN_PROXY,
+            target: ANGULAR_PROXY_PATH,
+            status: StepStatus.ALREADY,
+            detail: 'already there',
+        };
+    }
+    return {
+        title: StepTitle.ANGULAR_TOKEN_PROXY,
+        target: ANGULAR_PROXY_PATH,
+        status: StepStatus.APPLY,
+        detail: PROXY_DETAIL,
+        write: { path: ANGULAR_PROXY_PATH, content: angularProxyFile(), expect: [ANGULAR_TOKEN_PATH] },
+    };
+}
+function serveStep(input) {
+    const workspace = input.angularWorkspace ?? null;
+    const manual = `In ${ANGULAR_WORKSPACE_FILE}, set the serve target's "options.proxyConfig" to "${ANGULAR_PROXY_PATH}".`;
+    if (null === workspace) {
+        return {
+            title: StepTitle.ANGULAR_SERVE_CONFIG,
+            target: ANGULAR_WORKSPACE_FILE,
+            status: StepStatus.MANUAL,
+            detail: manual,
+        };
+    }
+    return patchStep(StepTitle.ANGULAR_SERVE_CONFIG, workspace.path, patchAngularJson(workspace.source), SERVE_DETAIL, manual);
+}
+function entryStep(input) {
+    const entry = input.angularEntry ?? null;
+    if (null === entry) {
+        return {
+            title: StepTitle.CONNECT_SNIPPET_ANGULAR,
+            target: ANGULAR_DEFAULT_ENTRY,
+            status: StepStatus.MANUAL,
+            detail: entryManual(input, ANGULAR_DEFAULT_ENTRY),
+        };
+    }
+    // "already wired" read the entry without reading the port baked into its connect, so a re-run
+    // with a new `--port` left the page dialling the old daemon.
+    const patch = patchAngularMain(entry.source, input.options.port, input.options.projectId);
+    // An entry the previous version wired is rewritten in place (its guard), so a re-run that ALSO
+    // moves the port has to move it in the rewritten code — the ALREADY path below never sees it.
+    const moved = PatchKind.APPLY === patch.kind ? retargetPort(patch.code, input.options.port) : null;
+    return alreadyOrMovedPort(patchStep(StepTitle.CONNECT_SNIPPET_ANGULAR, entry.path, null === moved ? patch : { kind: PatchKind.APPLY, code: moved.code }, ENTRY_DETAIL, entryManual(input, entry.path)), entry.source, input.options.port);
+}
+export function angularSteps(input) {
+    return [
+        {
+            title: StepTitle.ANGULAR_SETUP_GATED,
+            target: ANGULAR_WORKSPACE_FILE,
+            status: StepStatus.NOTICE,
+            detail: ANGULAR_SETUP_GATED_NOTE,
+        },
+        entryStep(input),
+        proxyStep(input),
+        serveStep(input),
+    ];
+}

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

@@ -1,8 +1,10 @@
 /**
- * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
+ * The plan's Electron half: the renderer plugin, capabilities, and the two Electron steps — for
+ * electron-vite and for Electron Forge's Vite template, which differ only in where the renderer's
+ * Vite config lives.
  *
- * Its own module because this is the only framework whose wiring reaches outside the renderer, into
- * a preload and a main process the web frameworks have no equivalent of.
+ * Its own module because these are the only frameworks whose wiring reaches outside the renderer,
+ * into a preload and a main process the web frameworks have no equivalent of.
  */
 import { type PlanInput, type Step } from './plan-types.js';
 /**
@@ -13,3 +15,4 @@ import { type PlanInput, type Step } from './plan-types.js';
  * manual recipe the way Astro's config+layout pair does.
  */
 export declare function electronViteSteps(input: PlanInput): Step[];
+export declare function electronForgeSteps(input: PlanInput): Step[];

package/dist/plan/plan-electron-vite.js

@@ -1,12 +1,16 @@
 /**
- * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
+ * The plan's Electron half: the renderer plugin, capabilities, and the two Electron steps — for
+ * electron-vite and for Electron Forge's Vite template, which differ only in where the renderer's
+ * Vite config lives.
  *
- * Its own module because this is the only framework whose wiring reaches outside the renderer, into
- * a preload and a main process the web frameworks have no equivalent of.
+ * Its own module because these are the only frameworks whose wiring reaches outside the renderer,
+ * into a preload and a main process the web frameworks have no equivalent of.
  */
 import { StepStatus } from './plan-types.js';
 import { StepTitle } from './connect-steps.js';
-import { capabilitiesStep, patchStep } from './plan-framework.js';
+import { patchStep } from './plan-framework.js';
+import { capabilitiesStep, viteSteps } from './plan-vite.js';
+import { alreadyOrMovedPort } from './port-steps.js';
 import { patchElectronViteConfig } from '../patch/electron-vite-patch.js';
 import { patchElectronMain, patchElectronPreload } from '../patch/electron-patch.js';
 import { ELECTRON_CAPTURE_FIX, ELECTRON_PRELOAD_FIX } from '../diagnose/desktop-doctor.js';
@@ -29,15 +33,19 @@ export function electronViteSteps(input) {
             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);
+        : alreadyOrMovedPort(patchStep(StepTitle.ELECTRON_VITE_PLUGIN, cfg.path, patchElectronViteConfig(cfg.source, port), 'add reticle({ desktop: true }) to the renderer plugins (also injects connect())', manual), cfg.source, port);
     return [
         plugin,
         ...capabilitiesStep(input, ELECTRON_VITE_DEV_MODULE_PATH),
-        ...electronPreloadStep(input),
+        ...electronPreloadStep(input, false),
         ...electronCaptureStep(input),
     ];
 }
-function electronPreloadStep(input) {
+/**
+ * `viteTypes` is for Forge, whose tsconfig has no `import.meta.env` types for the dev guard. See
+ * `patchElectronPreload`.
+ */
+function electronPreloadStep(input, viteTypes) {
     const file = input.electronPreload ?? null;
     if (null === file) {
         return [
@@ -50,7 +58,7 @@ function electronPreloadStep(input) {
         ];
     }
     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),
+        patchStep(StepTitle.ELECTRON_PRELOAD, file.path, patchElectronPreload(file.source, file.path, viteTypes), 'require the IPC shim as the first line of preload, dev only', ELECTRON_PRELOAD_FIX),
     ];
 }
 function electronCaptureStep(input) {
@@ -69,3 +77,26 @@ function electronCaptureStep(input) {
         patchStep(StepTitle.ELECTRON_CAPTURE, file.path, patchElectronMain(file.source, file.path), 'installReticleCapture on the BrowserWindow so screenshots work', ELECTRON_CAPTURE_FIX),
     ];
 }
+/**
+ * Electron Forge's Vite template: the renderer config, then the same two Electron halves.
+ *
+ * Forge's renderer config is an ordinary Vite config (`defineConfig({})`), so it is patched by the
+ * ordinary Vite patcher — `run.ts` hands it over as `viteConfig` when the framework is Forge.
+ *
+ * The plugin goes in WITHOUT `desktop: true`. `electron-forge start` serves the renderer through a
+ * real Vite dev server, so the plugin's ordinary serve-time injection reaches the window; the flag
+ * exists for a packaged renderer driven with no dev server, which is built in a non-production mode
+ * on purpose. Without it a packaged Forge app has no connect() in any mode, which is the web default
+ * and the safe direction. Measured on a
+ * scaffolded Forge 8 app: `tsc --noEmit` and `electron-forge package` both pass after `init`, and the
+ * packaged renderer carries no Reticle code.
+ */
+const FORGE_RENDERER_DETAIL = 'add reticle() to the renderer plugins — the only one of Forge’s three Vite builds with a ' +
+    'document (also injects connect() while `electron-forge start` serves it)';
+export function electronForgeSteps(input) {
+    return [
+        ...viteSteps(input, FORGE_RENDERER_DETAIL),
+        ...electronPreloadStep(input, true),
+        ...electronCaptureStep(input),
+    ];
+}

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

@@ -1,40 +1,12 @@
 /**
- * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
- * `plan.ts` is the plan's SHAPE (statuses, ordering, the agent/MCP steps); this is the per-framework
- * detail, and they grow for different reasons.
+ * How each framework gets wired: the three Next files, the SvelteKit client hook, CRA, Nuxt, Astro
+ * and the rest. `plan.ts` is the plan's SHAPE (statuses, ordering, the agent/MCP steps); this is the
+ * per-framework detail, and they grow for different reasons. The Vite plugin and the capabilities
+ * module every Vite-based stack shares live in `plan-vite.ts`.
  */
 import { type SourcePatch } from '../patch/patch-kind.js';
 import { type PlanInput, type Step } from './plan-types.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.
@@ -75,12 +47,12 @@ export declare function nuxtSteps(input: PlanInput): Step[];
  * 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[];
+export declare function reactRouterSteps(input: PlanInput, title?: StepTitle, newEntry?: () => string): Step[];
 /**
- * TanStack Start: the client-document connect, printed rather than written.
+ * TanStack Start: a client connect component, written, and rendered in the root document.
  *
- * `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`.
+ * ATOMIC, like Astro: the component on disk with nothing rendering it is a guaranteed
+ * non-connection, so when the root cannot be patched BOTH halves go back to the recipe.
  */
 export declare function tanstackStartSteps(input: PlanInput): Step[];
 export declare function svelteKitSteps(input: PlanInput): Step[];
@@ -93,16 +65,6 @@ export declare function svelteKitSteps(input: PlanInput): Step[];
  * 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.
  *