@reticlehq/init 3.2.0 → 3.4.0

package/dist/node-io.js

@@ -3,6 +3,7 @@
  * `runInit` stays testable with an in-memory IO. Prints to stdout — `init` is a one-shot CLI
  * command, not the MCP stdio transport.
  */
+import { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, } from 'node:fs';
 import { NodePlatform } from './detect/platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
@@ -23,17 +24,29 @@ function shellSafe(args) {
 /**
  * Every program `init` is ever allowed to run.
  *
- * The set is closed and tiny — the four package managers, `npx`, and the Claude CLI — because those
- * are the only things the plan can ask for. It is a named constant for the same reason every other
- * wire string here is one, and it is CHECKED because of the shell: on Windows these spawn through
- * a shell, and a shell turns the command name into something the shell parses rather than a file it
- * executes. Arguments are quoted by `shellSafe`; the command name was the half nothing covered.
+ * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude CLI —
+ * because those are the only things the plan can ask for. It is a named constant for the same reason
+ * every other wire string here is one, and it is CHECKED because of the shell: on Windows these spawn
+ * through a shell, and a shell turns the command name into something the shell parses rather than a
+ * file it executes. Arguments are quoted by `shellSafe`; the command name was the half nothing
+ * covered.
+ *
+ * `corepack` runs the package manager, never IS it (see `preflight.ts`, #1149) — the allowlist has to
+ * name the actual program being spawned.
  *
  * A command outside this set is a programming error — the plan built something no branch of this
  * package can produce — so it throws rather than returning `false`, which would read to the caller
  * as "the command ran and failed" and hide the bug in a retry.
  */
-export const RUNNABLE_COMMANDS = ['pnpm', 'yarn', 'bun', 'npm', 'npx', 'claude'];
+export const RUNNABLE_COMMANDS = [
+    'pnpm',
+    'yarn',
+    'bun',
+    'npm',
+    'npx',
+    'corepack',
+    'claude',
+];
 /** The command, proven to be one of `RUNNABLE_COMMANDS` — never the caller's string. */
 function runnable(command) {
     const found = RUNNABLE_COMMANDS.find((allowed) => allowed === command);
@@ -155,6 +168,11 @@ export function buildNodeIo(cwd, host) {
             const result = spawnAllowed(command, args, { cwd, stdio: 'inherit' });
             return 0 === result.status;
         },
+        capture(command, args) {
+            const result = spawnAllowed(command, args, { cwd, stdio: 'pipe', encoding: 'utf8' });
+            const text = (part) => ('string' === typeof part ? part : '');
+            return { ok: 0 === result.status, output: `${text(result.stdout)}${text(result.stderr)}` };
+        },
         /** One access check, rather than discovering it as an EACCES stack four phases later. */
         canWrite() {
             try {
@@ -171,7 +189,7 @@ export function buildNodeIo(cwd, host) {
             return 0 === result.status;
         },
         print(line) {
-            process.stdout.write(`${line}\n`);
+            process.stdout.write(`${wrapForTerminal(line, terminalWidth())}\n`);
         },
         host,
     };

package/dist/patch/angular.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Angular CLI: a dev-only connect in the browser entry, and a way for the pairing token to reach it.
+ *
+ * The connect is the part proven by hand on Angular 22, with and without SSR: a dynamic
+ * `import('@reticlehq/browser')` guarded on `ngDevMode` (see DEV_GUARD for why not `isDevMode()`),
+ * which the production build folds to `false` and drops together with the chunk it would load.
+ *
+ * The token is the hard part, and why this is not one line. The bridge refuses a hello without the
+ * machine's pairing token even on localhost, and every other stack inlines it from Node at build
+ * time — the Vite plugin's `define`, Next's `NEXT_PUBLIC_*`, CRA's gitignored `.env.development.local`.
+ * The Angular CLI has no config file that runs code, so each of those has a failure here, all
+ * measured on a scaffolded Angular 21 app before this was written:
+ *
+ * - A literal in `angular.json` (`define`, `fileReplacements`) commits a per-machine secret.
+ * - A gitignored module imported from `main.ts` is bundled by `ng build` too: with the file present
+ *   the production output held a lazy chunk carrying the token behind `isDevMode()`, which the
+ *   build cannot fold — and a token must not depend on a guard being written exactly right.
+ * - Making that module a dev-only `fileReplacements` target breaks `ng serve` for every teammate
+ *   who has not run `init` ("path in file replacements does not exist").
+ *
+ * What is left is the serve target, which `ng build` never reads. Its `proxyConfig` is a JavaScript
+ * module that `ng serve` loads in Node, so `reticle.proxy.mjs` reads `~/.reticle/pairing-token` at
+ * request time — the same file the Vite and Next plugins read — and answers one same-origin route
+ * with it. The token is never written into the project, and a production build has no route to it.
+ */
+import { type SourcePatch } from './patch-kind.js';
+/** The generated dev-server module, beside `angular.json`. */
+export declare const ANGULAR_PROXY_PATH = "reticle.proxy.mjs";
+/** The one route that module answers, fetched by the entry's dev-only connect. */
+export declare const ANGULAR_TOKEN_PATH = "/__reticle/pairing-token";
+/** What an Angular CLI app's browser entry is when `angular.json` does not say. */
+export declare const ANGULAR_DEFAULT_ENTRY = "src/main.ts";
+/**
+ * The browser entry `angular.json` names — `browser` on the application builder (v17+), `main` on
+ * the webpack one — or the CLI's default when it cannot be read.
+ */
+export declare function angularEntry(source: string | null): string;
+/**
+ * Point the one app's serve target at `reticle.proxy.mjs`.
+ *
+ * An existing `proxyConfig` is the app's, and is never replaced: the step goes MANUAL naming the
+ * entry to add to it. The file is rewritten through `JSON.stringify` with the CLI's own two-space
+ * indent, which is how `ng new` writes it, so the diff is the one key.
+ */
+export declare function patchAngularJson(source: string): SourcePatch;
+/**
+ * The dev-server module. Plain ESM, no dependencies, because it runs in the app's `ng serve`.
+ *
+ * Two refusals, both about who may read a token: a request that did not come over loopback (an
+ * `ng serve --host 0.0.0.0` on a shared network), and a browser request from another origin — a
+ * different localhost app — which `Sec-Fetch-Site` names on every current browser.
+ *
+ * `bypass` answers the request itself and returns `false`, so the dummy `target` is never dialled.
+ * ponytail: relies on the Vite-based dev server (Angular 17+) ignoring the 404 it sets after the
+ * response has already ended; the older webpack dev server calls `next()` instead, and if it ever
+ * matters there the upgrade is a `configure` hook instead of `bypass`.
+ */
+export declare function angularProxyFile(): string;
+/**
+ * Add the dev-only connect to the browser entry, or ALREADY when it is there.
+ *
+ * Appended after the bootstrap rather than before it: the app must never wait on Reticle, and a
+ * connect that fails (no daemon yet) must not be able to stop Angular from starting.
+ *
+ * An entry wired by the previous version (`if (isDevMode())`) is rewritten in place, so a re-run is
+ * what takes the connect out of an existing app's production bundle.
+ */
+export declare function patchAngularMain(source: string, port: number | undefined, projectId: string | undefined): SourcePatch;

package/dist/patch/angular.js

@@ -0,0 +1,216 @@
+/**
+ * Angular CLI: a dev-only connect in the browser entry, and a way for the pairing token to reach it.
+ *
+ * The connect is the part proven by hand on Angular 22, with and without SSR: a dynamic
+ * `import('@reticlehq/browser')` guarded on `ngDevMode` (see DEV_GUARD for why not `isDevMode()`),
+ * which the production build folds to `false` and drops together with the chunk it would load.
+ *
+ * The token is the hard part, and why this is not one line. The bridge refuses a hello without the
+ * machine's pairing token even on localhost, and every other stack inlines it from Node at build
+ * time — the Vite plugin's `define`, Next's `NEXT_PUBLIC_*`, CRA's gitignored `.env.development.local`.
+ * The Angular CLI has no config file that runs code, so each of those has a failure here, all
+ * measured on a scaffolded Angular 21 app before this was written:
+ *
+ * - A literal in `angular.json` (`define`, `fileReplacements`) commits a per-machine secret.
+ * - A gitignored module imported from `main.ts` is bundled by `ng build` too: with the file present
+ *   the production output held a lazy chunk carrying the token behind `isDevMode()`, which the
+ *   build cannot fold — and a token must not depend on a guard being written exactly right.
+ * - Making that module a dev-only `fileReplacements` target breaks `ng serve` for every teammate
+ *   who has not run `init` ("path in file replacements does not exist").
+ *
+ * What is left is the serve target, which `ng build` never reads. Its `proxyConfig` is a JavaScript
+ * module that `ng serve` loads in Node, so `reticle.proxy.mjs` reads `~/.reticle/pairing-token` at
+ * request time — the same file the Vite and Next plugins read — and answers one same-origin route
+ * with it. The token is never written into the project, and a production build has no route to it.
+ */
+import { connectArg } from './snippets.js';
+import { PatchKind } from './patch-kind.js';
+/** The generated dev-server module, beside `angular.json`. */
+export const ANGULAR_PROXY_PATH = 'reticle.proxy.mjs';
+/** The one route that module answers, fetched by the entry's dev-only connect. */
+export const ANGULAR_TOKEN_PATH = '/__reticle/pairing-token';
+/** What an Angular CLI app's browser entry is when `angular.json` does not say. */
+export const ANGULAR_DEFAULT_ENTRY = 'src/main.ts';
+const SENSOR = '@reticlehq/browser';
+const DEV_SERVER_BUILDER = /:dev-server$/;
+const UNPARSEABLE_REASON = 'angular.json is not plain JSON, so it is not safe to rewrite by hand';
+const NO_SERVE_TARGET_REASON = 'no project in angular.json has a `serve` target on a dev-server builder, so there is nowhere ' +
+    'for `ng serve` to pick up the token route';
+const SEVERAL_APPS_REASON = 'angular.json has several projects with a `serve` target, and which one is the app is not ours ' +
+    'to guess';
+function parseWorkspace(source) {
+    try {
+        const parsed = JSON.parse(source);
+        if ('object' !== typeof parsed || null === parsed)
+            return undefined;
+        const root = parsed;
+        const projects = root['projects'];
+        if ('object' !== typeof projects || null === projects)
+            return undefined;
+        return { root, projects: projects };
+    }
+    catch {
+        return undefined;
+    }
+}
+function targetsOf(project) {
+    return project.architect ?? project.targets ?? {};
+}
+/** The projects `ng serve` can serve — the only ones with a page to connect. */
+function servedProjects(projects) {
+    return Object.values(projects).filter((p) => DEV_SERVER_BUILDER.test(targetsOf(p)['serve']?.builder ?? ''));
+}
+/**
+ * The browser entry `angular.json` names — `browser` on the application builder (v17+), `main` on
+ * the webpack one — or the CLI's default when it cannot be read.
+ */
+export function angularEntry(source) {
+    const workspace = null === source ? undefined : parseWorkspace(source);
+    const [only, ...rest] = workspace === undefined ? [] : servedProjects(workspace.projects);
+    if (only === undefined || rest.length > 0)
+        return ANGULAR_DEFAULT_ENTRY;
+    const options = targetsOf(only)['build']?.options ?? {};
+    const named = options['browser'] ?? options['main'];
+    return 'string' === typeof named && named.length > 0 ? named : ANGULAR_DEFAULT_ENTRY;
+}
+/**
+ * Point the one app's serve target at `reticle.proxy.mjs`.
+ *
+ * An existing `proxyConfig` is the app's, and is never replaced: the step goes MANUAL naming the
+ * entry to add to it. The file is rewritten through `JSON.stringify` with the CLI's own two-space
+ * indent, which is how `ng new` writes it, so the diff is the one key.
+ */
+export function patchAngularJson(source) {
+    const workspace = parseWorkspace(source);
+    if (workspace === undefined)
+        return { kind: PatchKind.MANUAL, reason: UNPARSEABLE_REASON };
+    const served = servedProjects(workspace.projects);
+    const [only, ...rest] = served;
+    if (only === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_SERVE_TARGET_REASON };
+    if (rest.length > 0)
+        return { kind: PatchKind.MANUAL, reason: SEVERAL_APPS_REASON };
+    const serve = targetsOf(only)['serve'];
+    if (serve === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_SERVE_TARGET_REASON };
+    const existing = serve.options?.['proxyConfig'];
+    if (ANGULAR_PROXY_PATH === existing)
+        return { kind: PatchKind.ALREADY };
+    if (existing !== undefined) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: `the serve target already uses ${JSON.stringify(existing)} as its proxyConfig, and it is yours — ` +
+                `add the \`${ANGULAR_TOKEN_PATH}\` entry from ${ANGULAR_PROXY_PATH} to it`,
+        };
+    }
+    serve.options = { ...serve.options, proxyConfig: ANGULAR_PROXY_PATH };
+    return { kind: PatchKind.APPLY, code: `${JSON.stringify(workspace.root, null, 2)}\n` };
+}
+/**
+ * The dev-server module. Plain ESM, no dependencies, because it runs in the app's `ng serve`.
+ *
+ * Two refusals, both about who may read a token: a request that did not come over loopback (an
+ * `ng serve --host 0.0.0.0` on a shared network), and a browser request from another origin — a
+ * different localhost app — which `Sec-Fetch-Site` names on every current browser.
+ *
+ * `bypass` answers the request itself and returns `false`, so the dummy `target` is never dialled.
+ * ponytail: relies on the Vite-based dev server (Angular 17+) ignoring the 404 it sets after the
+ * response has already ended; the older webpack dev server calls `next()` instead, and if it ever
+ * matters there the upgrade is a `configure` hook instead of `bypass`.
+ */
+export function angularProxyFile() {
+    return `// Written by \`reticle init\`. Read by \`ng serve\` only — \`ng build\` never loads a proxy config.
+//
+// Hands the page this machine's Reticle pairing token, read at request time from the file the
+// Reticle daemon keeps (~/.reticle/pairing-token). The token is per-machine and never written into
+// this project, so nothing here needs to be kept out of version control.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+function pairingToken() {
+  const dir = process.env.RETICLE_PAIRING_TOKEN_DIR || join(homedir(), '.reticle');
+  try {
+    return readFileSync(join(dir, 'pairing-token'), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+export default {
+  '${ANGULAR_TOKEN_PATH}': {
+    target: 'http://127.0.0.1:9',
+    bypass(req, res) {
+      const site = req.headers['sec-fetch-site'];
+      const allowed =
+        LOOPBACK.has(req.socket.remoteAddress ?? '') && (site === undefined || site === 'same-origin');
+      res.writeHead(allowed ? 200 : 403, { 'content-type': 'text/plain', 'cache-control': 'no-store' });
+      res.end(allowed ? pairingToken() : '');
+      return false;
+    },
+  },
+};
+`;
+}
+/** Everything `connect()` is called with, as the literal's inner fields — `url` only off 4400. */
+function connectFields(port, projectId) {
+    const literal = connectArg(port, projectId);
+    return literal.length > 0 ? `${literal.slice(1, -1).trim()}, ` : '';
+}
+/**
+ * The guard the connect sits under: Angular's own `ngDevMode` global, not `isDevMode()`.
+ *
+ * `isDevMode()` is a runtime call, so `ng build` cannot fold it: the production bundle shipped the
+ * whole connect — the bridge URL included — plus ~300KB of lazy Reticle chunks that nothing
+ * would ever load. The Angular CLI defines `ngDevMode` to `false` in a production build, which lets
+ * esbuild drop the branch and, with it, the dynamic import; in dev it is undefined or an object, so
+ * this reads exactly as `isDevMode()` did there. It is the check Angular's own sources use.
+ */
+const DEV_GUARD = "if (typeof ngDevMode === 'undefined' || ngDevMode) {";
+/** Declared locally so strict TypeScript accepts the global without the app importing anything. */
+const NG_DEV_MODE_DECLARATION = 'declare const ngDevMode: unknown;';
+/** The guard the previous version wrote, which is rewritten in place on a re-run. */
+const LEGACY_GUARD = /^if \(isDevMode\(\)\) \{(?=\s*void Promise\.all\(\[\s*import\('@reticlehq\/browser'\))/m;
+/** The comment the previous version wrote above it, which named the guard it no longer uses. */
+const LEGACY_COMMENT = /^\/\/ Reticle, dev only — written by `reticle init`\. `isDevMode\(\)` is false in a production build,\n\/\/ so this never runs there\./m;
+const HEADER = '// Reticle, dev only — written by `reticle init`. `ngDevMode` is false in a production build,\n' +
+    '// so the build drops this block.';
+/**
+ * Add the dev-only connect to the browser entry, or ALREADY when it is there.
+ *
+ * Appended after the bootstrap rather than before it: the app must never wait on Reticle, and a
+ * connect that fails (no daemon yet) must not be able to stop Angular from starting.
+ *
+ * An entry wired by the previous version (`if (isDevMode())`) is rewritten in place, so a re-run is
+ * what takes the connect out of an existing app's production bundle.
+ */
+export function patchAngularMain(source, port, projectId) {
+    if (LEGACY_GUARD.test(source)) {
+        const guarded = source
+            .replace(LEGACY_COMMENT, HEADER)
+            .replace(LEGACY_GUARD, `${NG_DEV_MODE_DECLARATION}\n${DEV_GUARD}`);
+        return { kind: PatchKind.APPLY, code: guarded };
+    }
+    if (source.includes(SENSOR))
+        return { kind: PatchKind.ALREADY };
+    const declaration = source.includes(NG_DEV_MODE_DECLARATION)
+        ? ''
+        : `${NG_DEV_MODE_DECLARATION}\n`;
+    const block = `
+${HEADER} The pairing token comes from \`ng serve\` (${ANGULAR_PROXY_PATH}), so it
+// is never in a source file or a bundle.
+${declaration}${DEV_GUARD}
+  void Promise.all([
+    import('${SENSOR}'),
+    fetch('${ANGULAR_TOKEN_PATH}')
+      .then((res) => (res.ok ? res.text() : ''))
+      .catch(() => ''),
+  ]).then(([{ reticle }, token]) => {
+    reticle.connect({ ${connectFields(port, projectId)}...(token ? { token } : {}) });
+  });
+}
+`;
+    return { kind: PatchKind.APPLY, code: `${source.trimEnd()}\n${block}` };
+}

package/dist/patch/astro-patch.d.ts

@@ -1,33 +1,68 @@
 /**
- * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
- * raised build target, one layout gets the dev-only connect `<script>`.
+ * Pure, conservative patchers for an Astro app: the config gets the raised build target and the
+ * watcher ignore, one layout gets the pairing token via frontmatter `<meta>` tags and a processed
+ * `<script>` that statically imports a local connect module.
  *
  * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
  * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
  * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
- * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
- * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ * there is no entry module to wire: the connect has to live in a page or layout.
+ *
+ * The token used to be inlined by `vite.define`. On Astro 7.2+ that substitution no longer reaches
+ * the client pipeline (#1008), so the identifier stays literal, `connect()` omits `token`, and the
+ * bridge refuses with "no pairing token on the page". The channel that does work is a `<meta>`: read
+ * the file in frontmatter and let a local module query `meta[name="reticle-pairing-token"]`. Reading
+ * per request also means a token written after the dev server started needs no restart. The SDK import
+ * lives in `src/components/ReticleDev.ts` so the page only ever statically imports a project module.
  *
  * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
  * Half-editing a build config is worse than a documented manual step.
  */
 import { type SourcePatch } from './patch-kind.js';
 import { UiLibrary } from '../detect/detect.js';
-export declare function patchAstroConfig(source: string): SourcePatch;
-export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary, testids?: readonly string[]): SourcePatch;
+/**
+ * Local module `init` writes for Astro. A processed page `<script>` statically imports this file
+ * so Vite owns the SDK the same way it owns any other project module.
+ *
+ * `.ts`, not `.tsx`: the install-gate scaffold is `create-astro --template minimal`, which has no
+ * React integration. The example app uses the same static import in a processed page `<script>`.
+ */
+export declare const ASTRO_RETICLE_DEV_PATH = "src/components/ReticleDev.ts";
+/**
+ * Dev-only Astro connect module. Static SDK import, token from frontmatter `<meta>` tags.
+ */
+export declare function astroReticleDevFile(port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary, testids?: readonly string[]): string;
+/**
+ * Written into the Astro `vite:` block so a second init reports ALREADY. The Nuxt path uses
+ * `__RETICLE_TOKEN__` in `define` as its marker; Astro no longer writes that name into the config.
+ */
+export declare const ASTRO_VITE_OWNING_MARKER = "reticle-vite-owning";
+/**
+ * The one runtime condition that guarantees a refused connect, said out loud on the page.
+ *
+ * Matching the Vite plugin's missing-token wording, because Astro never loads that plugin. The
+ * token is read at render time now, not at config load, so a reload is enough — the user does not
+ * have to restart the dev server.
+ */
+export declare const ASTRO_MISSING_TOKEN_WARNING: string;
+export declare function patchAstroConfig(source: string, viteMajor?: number | null): SourcePatch;
+/**
+ * Import path from a layout/page to the generated connect module, always relative and posix.
+ *
+ * `src/layouts/Layout.astro` and `src/pages/index.astro` both resolve to `../components/ReticleDev`.
+ */
+export declare function astroReticleDevImport(layoutPath: string): string;
+export declare function patchAstroLayout(source: string, layoutPath?: string): SourcePatch;
 /** Where Astro keeps ambient types — `create-astro` ships this file. */
 export declare const ASTRO_ENV_DTS_PATH = "src/env.d.ts";
 /**
- * The declarations `astro check` needs for the Vite `define` names (#677).
- *
- * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
- * absent when the pairing token file is missing.
+ * The declarations `astro check` needs for the window names the inline script writes (#677, #1008).
  */
 export declare const ASTRO_ENV_DTS_DECLARES: string;
 /**
- * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ * Append the window ambient declarations to `src/env.d.ts`, or create the file.
  *
- * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
- * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with
+ * `ts(2339) Property '__RETICLE_TOKEN__' does not exist on type 'Window'` after a clean init.
  */
 export declare function patchAstroEnvDts(existing: string | null): SourcePatch;