@reticlehq/init 2.14.0

package/dist/tanstack-start.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The TanStack Start connect recipe.
+ *
+ * Its own module rather than another entry in `snippets.ts`, which was at the 1000-line backstop:
+ * Start is the one framework whose document module `init` deliberately refuses to write, so the
+ * recipe and the reasoning behind that refusal are a unit.
+ */
+/** TanStack Start's document module — the file that SSRs `<html>`. */
+export declare const TANSTACK_START_ROOT_PATH = "src/routes/__root.tsx";
+/**
+ * The TanStack Start recipe, printed rather than written.
+ *
+ * `__root.tsx` is the document. A static import of the SDK on that module SSRs and 500s, so `init`
+ * does not write one. The connect has to be a client-only dynamic import inside `useEffect`, with
+ * the pairing token the plugin inlines as `__RETICLE_TOKEN__`. Same judgement React Router already
+ * makes about `app/entry.client.tsx`: a half-written document is worse than a documented manual step.
+ */
+export declare function tanstackStartManual(port: number | undefined, projectId?: string, rootPath?: string): string;

package/dist/tanstack-start.js

@@ -0,0 +1,57 @@
+/**
+ * The TanStack Start connect recipe.
+ *
+ * Its own module rather than another entry in `snippets.ts`, which was at the 1000-line backstop:
+ * Start is the one framework whose document module `init` deliberately refuses to write, so the
+ * recipe and the reasoning behind that refusal are a unit.
+ */
+import { UiLibrary } from './detect.js';
+import { connectArg, sdkImport, UNVERIFIED_TANSTACK_START_NOTE } from './snippets.js';
+/** TanStack Start's document module — the file that SSRs `<html>`. */
+export const TANSTACK_START_ROOT_PATH = 'src/routes/__root.tsx';
+/**
+ * The TanStack Start recipe, printed rather than written.
+ *
+ * `__root.tsx` is the document. A static import of the SDK on that module SSRs and 500s, so `init`
+ * does not write one. The connect has to be a client-only dynamic import inside `useEffect`, with
+ * the pairing token the plugin inlines as `__RETICLE_TOKEN__`. Same judgement React Router already
+ * makes about `app/entry.client.tsx`: a half-written document is worse than a documented manual step.
+ */
+export function tanstackStartManual(port, projectId, rootPath = TANSTACK_START_ROOT_PATH) {
+    const sdk = sdkImport(UiLibrary.REACT);
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
+    const installLine = sdk.usesInstall
+        ? '        install();'
+        : '        // No React adapter here: the sensor has no install() to call.';
+    const imports = sdk.usesInstall ? 'reticle, install' : 'reticle';
+    return `TanStack Start SSRs <html> from ${rootPath} (HeadContent / Scripts) and never sends Vite's
+  index.html, so the plugin's connect injection never fires. Keep the plugin anyway, with
+  reticle({ inject: false }): only the injection half is inapplicable, and the stamping half is
+  what puts data-reticle-source on the JSX. Dropping the plugin because one of its two jobs did
+  not apply is how Remix lost file:line.
+
+  Connect from a CLIENT-ONLY effect in ${rootPath}. A static SDK import on that module SSRs and
+  500s. Do not guard on window.location.hostname === 'localhost' — import.meta.env.DEV is the
+  correct guard, and it does not care what host you develop on.
+
+  Add this useEffect to the App component (import useEffect from react if it is not already there):
+
+      useEffect(() => {
+        if (import.meta.env.DEV) {
+          const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+          void import('${sdk.specifier}').then(({ ${imports} }) => {
+${installLine}
+            reticle.connect({
+              ${fields}...(token.length > 0 ? { token } : {}),
+            });
+          });
+        }
+      }, []);
+
+  The plugin inlines __RETICLE_TOKEN__ when Vite resolves its config. Start the daemon BEFORE the
+  dev server so that file exists; a server that started first froze an empty token and the page
+  looks like it "won't dial". Restart after init, and after the daemon is up.
+
+  ${UNVERIFIED_TANSTACK_START_NOTE}`;
+}

package/dist/version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The release this scaffolder belongs to, read from its own package.json at startup.
+ *
+ * Read here rather than injected because it is a MODULE constant in three generators
+ * (`snippets.ts`, `agent-rules.ts`, `mcp.ts`) — the CDN snippet pins `@reticlehq/browser@<this>`
+ * and cannot be built without it. Every published `@reticlehq/*` package shares one version, and
+ * `@reticlehq/server` depends on this one by exact version, so what a user resolves here is by
+ * construction the version of the server that invoked it. `version-lockstep.test.ts` in the server
+ * fails the fast gate if the two manifests ever disagree.
+ */
+export declare const RETICLE_VERSION: string;
+/**
+ * The published npm package that carries the `reticle` bin — the thing this scaffolder tells users
+ * and agents to run. NOT this package's own name: `@reticlehq/init` has no bin, and a self-update
+ * or an `npx` line pointing at it installs a library nobody can execute. Pinned as a constant and
+ * checked against `@reticlehq/server`'s manifest by `version-lockstep.test.ts`.
+ */
+export declare const RETICLE_NPM_PACKAGE = "@reticlehq/server";

package/dist/version.js

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module';
+// NOTE: a RUNTIME path, not an import — `tsc` does not check it and a file move will not rewrite
+// it. One level up because this file sits at the package src root: from `src/` and from `dist/`
+// alike, `../package.json` is the package manifest.
+const _pkg = createRequire(import.meta.url)('../package.json');
+/**
+ * The release this scaffolder belongs to, read from its own package.json at startup.
+ *
+ * Read here rather than injected because it is a MODULE constant in three generators
+ * (`snippets.ts`, `agent-rules.ts`, `mcp.ts`) — the CDN snippet pins `@reticlehq/browser@<this>`
+ * and cannot be built without it. Every published `@reticlehq/*` package shares one version, and
+ * `@reticlehq/server` depends on this one by exact version, so what a user resolves here is by
+ * construction the version of the server that invoked it. `version-lockstep.test.ts` in the server
+ * fails the fast gate if the two manifests ever disagree.
+ */
+export const RETICLE_VERSION = _pkg.version;
+/**
+ * The published npm package that carries the `reticle` bin — the thing this scaffolder tells users
+ * and agents to run. NOT this package's own name: `@reticlehq/init` has no bin, and a self-update
+ * or an `npx` line pointing at it installs a library nobody can execute. Pinned as a constant and
+ * checked against `@reticlehq/server`'s manifest by `version-lockstep.test.ts`.
+ */
+export const RETICLE_NPM_PACKAGE = '@reticlehq/server';

package/dist/vite-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure, conservative patcher for a Vite config: add the `@reticlehq/vite-plugin` import and drop
+ * `reticle` into the `plugins` array. Only handles the obvious, common shape — anything ambiguous
+ * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
+ * documented manual step).
+ */
+import { PatchKind, type SourcePatch } from './patch-kind.js';
+export declare const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+/** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
+export declare const VitePatchKind: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type VitePatchKind = PatchKind;
+type VitePatch = SourcePatch;
+export declare function patchViteConfig(source: string, port?: number, captureBodies?: boolean, inject?: boolean, sourceMapping?: boolean): VitePatch;
+export {};

package/dist/vite-config.js

@@ -0,0 +1,111 @@
+/**
+ * Pure, conservative patcher for a Vite config: add the `@reticlehq/vite-plugin` import and drop
+ * `reticle` into the `plugins` array. Only handles the obvious, common shape — anything ambiguous
+ * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
+ * documented manual step).
+ */
+import { PatchKind } from './patch-kind.js';
+export const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+const RETICLE_MARKER = '@reticlehq/vite-plugin';
+/**
+ * The `reticle(...)` call — the bridge port so the injected connect targets it.
+ *
+ * **`captureNetworkBodies` is OPT-IN.** It was written in by default, and the argument for that was
+ * a good one: without a body, a write that answers 2xx grades `unknown / outcome_unread`, because a
+ * 200 describes the transport and not the result. Measured on a real payments UI — a refund posted
+ * rupees into a paise field, the server answered 200 having refunded a hundredth of it, the page
+ * rendered the amount the user had typed, and every DOM-level check passed.
+ *
+ * That argument justifies the CAPABILITY. It does not justify the default, and the distinction is
+ * what #705 is about. A healthcare workspace proxying authenticated API traffic through Vite ran
+ * `init`, and on the first drive their login tokens and patient payloads were in the daemon's
+ * buffer. The old comment here conceded the exact gap — "the credential classes are redacted ... but
+ * an address or an email is not, and nothing here should decide that for someone silently" — and
+ * then decided it for them, because writing the line into their config IS deciding. `init` is run
+ * unattended by an agent; the person who knows the data is sensitive is not in the room.
+ *
+ * So the default is off and the ways in are all deliberate:
+ *   - `reticle init --capture-bodies` writes the line, for someone who has decided
+ *   - `VITE_RETICLE_CAPTURE_BODIES=1` turns it on for ONE dev-server run, no config edit
+ *   - adding the option by hand, which is what the tools tell you to do
+ *
+ * Nothing goes quiet in exchange. Every tool that needs a body already says so when it is missing
+ * and names the option — see honesty/uncaptured-bodies.ts, honesty/verified.ts, predicate-eval.ts
+ * and reconcile-tools.ts — so the capability is discovered at the moment it is wanted, by the person
+ * who wanted it, instead of being switched on before anyone has asked.
+ */
+function reticlePluginCall(opts) {
+    const options = [
+        ...(opts.port === undefined ? [] : [`port: ${String(opts.port)}`]),
+        ...(false === opts.inject ? ['inject: false'] : []),
+        ...(opts.captureBodies ? ['captureNetworkBodies: true'] : []),
+        ...(opts.sourceMapping ? [] : ['sourceMapping: false']),
+    ];
+    return 0 === options.length ? 'reticle()' : `reticle({ ${options.join(', ')} })`;
+}
+/** Matches the start of a `plugins: [` array literal. */
+const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
+/** Matches an ES import statement (used to place our import after the last one). */
+const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
+/**
+ * The opening `{` of the exported config object — `defineConfig({`, or a bare `export default {`.
+ * Used only when there is no `plugins` array to extend: the object is right there, so adding the
+ * key is the same edit as extending the array, and bailing sent a user whose config merely set
+ * `server.port` to a manual paste for a change we can make correctly.
+ *
+ * A config built by a call (`defineConfig(buildOptions())`) has no literal to extend and still
+ * bails — the rule stays "only edit a shape we can see whole".
+ */
+const CONFIG_OBJECT = /(export\s+default\s+(?:defineConfig\s*\(\s*)?)\{/;
+/** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
+export const VitePatchKind = PatchKind;
+const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
+function insertImport(source) {
+    const matches = [...source.matchAll(IMPORT_LINE)];
+    const last = matches[matches.length - 1];
+    if (last?.index === undefined) {
+        return `${VITE_IMPORT}\n${source}`;
+    }
+    const end = last.index + last[0].length;
+    return `${source.slice(0, end)}\n${VITE_IMPORT}${source.slice(end)}`;
+}
+/**
+ * Insert right after the opening `[` of the plugins array, spaced the way the surrounding line is.
+ *
+ * A multi-line array puts a newline next, and `[reticle(), \n` leaves trailing whitespace — exactly
+ * what a formatter rewrites, turning a one-line install into a diff against the user's own style. A
+ * single-line array needs the space, or the result reads `[reticle(),react()]`.
+ */
+function insertPlugin(source, call) {
+    return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
+        const next = source[offset + match.length] ?? '';
+        const separator = '' === next || /\s/.test(next) ? '' : ' ';
+        return `${match}${call},${separator}`;
+    });
+}
+/**
+ * Add a whole `plugins: [reticle()]` key to a config object that has none, matching the layout of
+ * the object it lands in: a multi-line object gets its own indented line, a one-liner stays inline.
+ */
+function insertPluginsKey(source, call) {
+    return source.replace(CONFIG_OBJECT, (_match, prefix, offset) => {
+        const rest = source.slice(offset + _match.length);
+        const multiline = /^\s*\n/.test(rest);
+        const indent = /^\s*\n(\s*)\S/.exec(rest)?.[1] ?? '  ';
+        const key = `plugins: [${call}],`;
+        return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
+    });
+}
+export function patchViteConfig(source, port, captureBodies = false, inject = true, sourceMapping = true) {
+    if (source.includes(RETICLE_MARKER)) {
+        return { kind: VitePatchKind.ALREADY };
+    }
+    const call = reticlePluginCall({ port, captureBodies, inject, sourceMapping });
+    if (PLUGINS_ARRAY.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, call)) };
+    }
+    if (CONFIG_OBJECT.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, call)) };
+    }
+    return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
+}

package/dist/vite-owning-config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Patching a build config that owns its own Vite instance.
+ *
+ * Astro and Nuxt are the same problem twice: each runs Vite itself and renders its own HTML, so the
+ * Vite plugin never loads and nothing sits in the page's path to inject the pairing token. So the
+ * token has to be inlined by the config, the dep cache has to be warmed for the dynamic SDK import,
+ * and the daemon's journal has to be kept out of the dev-server watcher — three edits to one `vite:`
+ * block, merged into whatever the app already put there.
+ *
+ * Lifted out of `astro-patch.ts` unchanged when Nuxt needed the identical patch. The two frameworks
+ * differ in exactly two ways, and both are parameters here: the config-factory call to extend
+ * (`defineConfig` / `defineNuxtConfig`), and which SDK package to pre-bundle.
+ *
+ * Every branch bails to `manual` (the printed recipe) on a shape it does not fully recognise.
+ * Half-editing somebody's build config is worse than a documented manual step.
+ */
+import { type SourcePatch } from './patch-kind.js';
+/** What differs between one Vite-owning framework and the next. */
+export interface ViteOwningConfig {
+    /** The config-factory call whose object literal our `vite:` block goes into. */
+    readonly defineCall: RegExp;
+    /** The SDK package this framework's connect imports, declared so Vite pre-bundles it. */
+    readonly sdkSpecifier: string;
+}
+export declare function patchViteOwningConfig(source: string, config: ViteOwningConfig): SourcePatch;

package/dist/vite-owning-config.js

@@ -0,0 +1,219 @@
+/**
+ * Patching a build config that owns its own Vite instance.
+ *
+ * Astro and Nuxt are the same problem twice: each runs Vite itself and renders its own HTML, so the
+ * Vite plugin never loads and nothing sits in the page's path to inject the pairing token. So the
+ * token has to be inlined by the config, the dep cache has to be warmed for the dynamic SDK import,
+ * and the daemon's journal has to be kept out of the dev-server watcher — three edits to one `vite:`
+ * block, merged into whatever the app already put there.
+ *
+ * Lifted out of `astro-patch.ts` unchanged when Nuxt needed the identical patch. The two frameworks
+ * differ in exactly two ways, and both are parameters here: the config-factory call to extend
+ * (`defineConfig` / `defineNuxtConfig`), and which SDK package to pre-bundle.
+ *
+ * Every branch bails to `manual` (the printed recipe) on a shape it does not fully recognise.
+ * Half-editing somebody's build config is worse than a documented manual step.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { blockAfter } from './brace-scan.js';
+import { PatchKind } from './patch-kind.js';
+/** Present in a patched config AND in a hand-followed recipe — so both count as already wired. */
+const CONFIG_MARKER = '__RETICLE_TOKEN__';
+/**
+ * The SDK, declared so Vite pre-bundles it BEFORE the first page load.
+ *
+ * The connect does `await import('@reticlehq/react')`. Undeclared, Vite meets that import mid-load,
+ * pre-bundles it, and the hashed `/node_modules/.vite/deps/@reticlehq_react.js?v=…` URL the browser
+ * already requested stops existing — the import rejects with "Failed to fetch dynamically imported
+ * module", connect() never runs, and the page looks entirely normal. Measured on astro-nanostores,
+ * intermittent on whether the dep cache was warm. The Vite plugin has declared the SDK for this
+ * exact reason since the bug was first found on React; a hand-patched config never got it.
+ */
+function sdkInclude(config) {
+    return `'${config.sdkSpecifier}'`;
+}
+/**
+ * The daemon's journal directory, kept out of the dev server's watcher.
+ *
+ * The daemon writes `.reticle/` into the project root and rewrites `ambient.json` atomically
+ * (`.tmp` + rename) for as long as a session is live. These dev servers are Vite watching that root,
+ * and `.reticle/` is not in Vite's default ignore list — so every journal write read as a project
+ * file changing and Vite answered with a full page reload. That closes a loop with no exit: the page
+ * loads, the SDK connects and streams events, the daemon journals them, Vite reloads the page, the
+ * SDK reconnects. It ran several times a second for as long as the dev server was up, and the
+ * symptom looked nothing like the cause — stale refs, actions dying mid-flight, and a log full of
+ * connect/disconnect pairs that read as a flapping SDK.
+ *
+ * The Vite plugin sets the same ignore in its `config` hook. These frameworks never load that
+ * plugin, so they need their own.
+ *
+ * A RegExp, not a glob. chokidar dropped glob support in v4 and Vite 7+ ships v4/v5, where a
+ * double-star pattern is accepted and matches nothing — the ignore would be visibly present in the
+ * config and do nothing at all. Measured against the chokidar this repo resolves.
+ */
+const WATCH_IGNORE_LITERAL = `/(^|[\\\\/])\\.${ReticleDir.ROOT.slice(1)}([\\\\/]|$)/`;
+/**
+ * An `include:` the app already declared — ours joins that array instead of adding a second key.
+ * Deliberately not anchored to a newline: `optimizeDeps: { include: ['x'] }` on one line is the
+ * common way to write it, and requiring a line break made the merge miss it and duplicate the key.
+ */
+const EXISTING_INCLUDE = /(\s*include\s*:\s*\[)/;
+/** A `vite:` key whose value is an object LITERAL — the one shape we can merge into safely. */
+const VITE_OBJECT_KEY = /(^\s*vite\s*:\s*\{)/m;
+/** Any `vite:` key at all. One that is not an object literal (a spread, an imported config) is ours to refuse. */
+const ANY_VITE_KEY = /^\s*vite\s*:/m;
+const HELPER = `
+function reticleToken() {
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+  try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+}
+`;
+const HELPER_IMPORTS = `import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+`;
+/**
+ * The keys we add inside `vite:`, each with what it must contain.
+ *
+ * Kept as a list rather than one blob because a config that already sets one of these must be merged
+ * INTO, not duplicated: the real astro-nanostores config has `build: { chunkSizeWarningLimit }`, and
+ * inserting our own `build` beside it gave the object two — where the last one wins, so
+ * `target: 'es2022'` was silently discarded while init reported success. Losing that target is not
+ * cosmetic: Astro's default down-levels the modern SDK bundle and dies on a destructuring transform.
+ */
+function viteKeys(config) {
+    return [
+        { key: 'build', inner: `\n      target: 'es2022',` },
+        {
+            key: 'optimizeDeps',
+            inner: `\n      include: [${sdkInclude(config)}],\n      esbuildOptions: { target: 'es2022' },`,
+        },
+        {
+            key: 'define',
+            inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
+        },
+        // Merged in first, so a `server: { port }` the app already set keeps its port. An app that
+        // already sets `server.watch` itself is the one shape this loses to — the inner `watch` key would
+        // be duplicated and the app's would win — which is the same nested-merge ceiling `build` has.
+        { key: 'server', inner: `\n      watch: { ignored: [${WATCH_IGNORE_LITERAL}] },` },
+    ];
+}
+/** Whole-key form, for a `vite:` block that does not have the key at all. */
+function wholeKeys(config) {
+    return {
+        build: `\n    build: { target: 'es2022' },`,
+        optimizeDeps: `\n    optimizeDeps: { include: [${sdkInclude(config)}], esbuildOptions: { target: 'es2022' } },`,
+        define: `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`,
+        server: `\n    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },`,
+    };
+}
+/**
+ * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
+ *
+ * Returns null when a colliding key is not an object literal (`build: sharedConfig`) — there is no
+ * brace to merge into, and duplicating or replacing it would corrupt someone's build.
+ */
+function mergeIntoViteBlock(source, braceAt, config) {
+    let out = source;
+    const whole = wholeKeys(config);
+    for (const { key, inner } of viteKeys(config)) {
+        // Scoped to the vite block by searching from its opening brace: a `build:` under `markdown:` or
+        // at the top level is somebody else's key and must not be touched.
+        const existing = new RegExp(`(\\n\\s*${key}\\s*:\\s*)([\\{A-Za-z_])`).exec(out.slice(braceAt));
+        if (existing?.index === undefined) {
+            out = `${out.slice(0, braceAt)}${whole[key] ?? ''}${out.slice(braceAt)}`;
+            continue;
+        }
+        // The character after the colon decides: `{` is a literal we can open; anything else is a
+        // reference we must not touch.
+        if (existing[2] !== '{')
+            return null;
+        const at = braceAt + existing.index + existing[0].length; // just past the `{`
+        // An `include:` the app already wrote is an ARRAY, and a second `include:` key in the same
+        // object literal is not a merge — the last one wins and one of the two silently disappears.
+        // That is how `build.target` was lost while init still reported success. Join their array.
+        // Scoped to THIS block's braces: an `include:` under a later key is somebody else's array, and
+        // appending the SDK to it would both miss the target and edit a config we were not asked to.
+        const own = 'optimizeDeps' === key ? EXISTING_INCLUDE.exec(blockAfter(out, at)) : null;
+        if (own?.index === undefined) {
+            out = insertAt(out, at, inner);
+            continue;
+        }
+        // Their array first, then the rest of our keys at the block's start — inserting at the LOWER
+        // offset second keeps the first offset valid.
+        out = insertAt(out, at + own.index + own[0].length, `${sdkInclude(config)}, `);
+        out = insertAt(out, at, withoutInclude(inner, config));
+    }
+    return out;
+}
+function insertAt(source, at, text) {
+    return `${source.slice(0, at)}${text}${source.slice(at)}`;
+}
+/** The optimizeDeps inner minus our `include:` line, for when the app already has one to join. */
+function withoutInclude(inner, config) {
+    return inner.replace(`\n      include: [${sdkInclude(config)}],`, '');
+}
+/**
+ * The `vite:` block these frameworks need. `build.target` is raised because Astro's default
+ * down-levels the modern SDK bundle and dies on a destructuring transform; `__RETICLE_ROOT__` is
+ * defined because without it every source pointer comes back as an absolute path from the machine
+ * that ran `init`.
+ */
+function viteBlock(config) {
+    return `  vite: {
+    build: { target: 'es2022' },
+    optimizeDeps: { include: [${sdkInclude(config)}], esbuildOptions: { target: 'es2022' } },
+    define: {
+      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+      __RETICLE_ROOT__: JSON.stringify(process.cwd()),
+    },
+    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },
+  },
+`;
+}
+export function patchViteOwningConfig(source, config) {
+    if (source.includes(CONFIG_MARKER))
+        return { kind: PatchKind.ALREADY };
+    // A `vite: { ... }` block is an object literal, so our keys can go straight after the brace and
+    // whatever is already in there is untouched. Refusing outright was the only genuine install defect
+    // left in the gate: the config bailed while the LAYOUT patch applied anyway, leaving an app with a
+    // connect snippet, no inlined token and no raised build target — which cannot connect, reported as
+    // one OK step and one warning.
+    const viteObject = VITE_OBJECT_KEY.exec(source);
+    if (viteObject?.index !== undefined) {
+        const at = viteObject.index + viteObject[0].length;
+        const merged = mergeIntoViteBlock(source, at, config);
+        if (merged !== null) {
+            return {
+                kind: PatchKind.APPLY,
+                code: `${HELPER_IMPORTS}${merged.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+            };
+        }
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets a `vite` key Reticle needs (build / optimizeDeps / define) to something ' +
+                'other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    if (ANY_VITE_KEY.test(source)) {
+        // `vite: sharedConfig` — not an object literal, so there is no brace to merge into and guessing
+        // would corrupt a build config. The recipe is the honest answer here.
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets `vite:` to something other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    const opening = config.defineCall.exec(source);
+    if (opening?.index === undefined) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a config call to extend",
+        };
+    }
+    const at = opening.index + opening[0].length;
+    const withBlock = `${source.slice(0, at)}\n${viteBlock(config)}${source.slice(at)}`;
+    return {
+        kind: PatchKind.APPLY,
+        code: `${HELPER_IMPORTS}${withBlock.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+    };
+}

package/dist/windows-quote.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+export declare function windowsShellArg(arg: string): string;

package/dist/windows-quote.js

@@ -0,0 +1,70 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+/**
+ * Characters that make cmd.exe do something other than pass the text along.
+ *
+ * Whitespace and `"` split or delimit; the rest are the shell's control operators. An argument
+ * containing any of them must be quoted, not just one containing a space.
+ */
+const NEEDS_QUOTING = /[\s"&|<>^()!%,;=]/;
+export function windowsShellArg(arg) {
+    // An empty argument must still occupy a slot in argv. Unquoted it disappears entirely, silently
+    // shifting every argument after it by one.
+    if (0 === arg.length)
+        return '""';
+    if (!NEEDS_QUOTING.test(arg))
+        return arg;
+    let out = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if ('\\' === ch) {
+            backslashes += 1;
+            continue;
+        }
+        if ('"' === ch) {
+            // 2n+1 backslashes → n literal backslashes and an escaped quote.
+            out += '\\'.repeat(2 * backslashes + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        out += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // A trailing run sits immediately before the closing quote, so it must be doubled or it escapes it.
+    return `${out}${'\\'.repeat(2 * backslashes)}"`;
+}

package/dist/workspace-apps.d.ts

@@ -0,0 +1,40 @@
+import type { InitIo } from './run.js';
+/**
+ * The file names that say what a directory IS, shared by everything that has to ask.
+ *
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
+ */
+export declare const PACKAGE_JSON = "package.json";
+export declare const VITE_CONFIG_CANDIDATES: string[];
+export declare const ELECTRON_VITE_CONFIG_CANDIDATES: string[];
+export declare const NEXT_CONFIG_CANDIDATES: string[];
+interface WorkspaceSources {
+    /** Raw contents of pnpm-workspace.yaml, when present. */
+    pnpmWorkspace?: string;
+    /** The `workspaces` field of package.json — array form or the yarn/npm object form. */
+    pkgWorkspaces?: unknown;
+    /** Directory names at the repo root, used when nothing is declared. */
+    topLevelDirs?: readonly string[];
+}
+export declare function workspaceParents(sources: WorkspaceSources): string[];
+/**
+ * Which directories under this workspace are runnable apps.
+ *
+ * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
+ * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
+ * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
+ * shape, next to `workspaceParents`, which answers the other half of it.
+ */
+/** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
+export declare const APP_DEPS: readonly ["next", "vite", "electron-vite"];
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+export {};