@reticlehq/init 3.3.0 → 3.5.0

package/dist/detect/workspace-apps.js

@@ -1,4 +1,6 @@
+import { dirname, join, relative, sep } from 'node:path';
 import { DEV_SCRIPT_NAMES } from './dev-script.js';
+import { detect, Framework, UiLibrary } from './detect.js';
 /**
  * The file names that say what a directory IS, shared by everything that has to ask.
  *
@@ -117,27 +119,65 @@ function hasDevScript(pkgRaw) {
         return false;
     }
 }
-function looksLikeApp(dir, io) {
+/** How strongly a directory claims to be the app somebody is working in. */
+const AppSignal = {
+    /** A page to connect: a bundler, a UI framework, or an index.html of its own. */
+    UI: 'ui',
+    /** Something that can be served and shows no page — an API, a worker, a server-rendered backend. */
+    SERVED: 'served',
+    NONE: 'none',
+};
+/** The pages a package can serve without any framework to say so. */
+const OWN_PAGES = ['index.html', 'public/index.html', 'src/index.html'];
+function parsedManifest(pkgRaw) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        return 'object' === typeof parsed && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Whether a package with a dev script has a page. Asked of the same detector the plan uses, so
+ * "is this the app" and "which framework is it" cannot disagree about what a UI dependency is.
+ */
+function hasPage(dir, pkgRaw, io) {
+    const found = detect({
+        pkg: parsedManifest(pkgRaw),
+        configFiles: new Set(),
+        lockfiles: new Set(),
+    });
+    if (Framework.HTML !== found.framework || UiLibrary.UNKNOWN !== found.uiLibrary)
+        return true;
+    return OWN_PAGES.some((page) => io.exists(`${dir}/${page}`));
+}
+function appSignal(dir, io) {
     const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
     if (null === pkgRaw)
-        return false;
+        return AppSignal.NONE;
     const configs = [
         ...VITE_CONFIG_CANDIDATES,
         ...ELECTRON_VITE_CONFIG_CANDIDATES,
         ...NEXT_CONFIG_CANDIDATES,
     ];
     if (configs.some((c) => io.exists(`${dir}/${c}`)))
-        return true;
+        return AppSignal.UI;
     // `next.config` is optional in Next, so the dependency list is the other half of the signal.
     if (APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`)))
-        return true;
+        return AppSignal.UI;
     // And the honest third: an app somebody can SERVE. Asking only for a bundler missed every app
     // built on anything else — Remix, Astro, a plain node server — and in a monorepo missing it means
     // init never redirects, wires the ROOT, and reports ✓ for files nothing compiles.
     //
     // A monorepo root has no dev script by design, and a package that can only be BUILT is not the app
     // somebody is working in, so this stays a filter rather than matching every directory.
-    return hasDevScript(pkgRaw);
+    if (!hasDevScript(pkgRaw))
+        return AppSignal.NONE;
+    // But a dev script alone is also what an API package has, and counting it made every workspace
+    // with a backend beside its web app "ambiguous" (#1148): the root refused, and its hint named the
+    // backend. A package with a dev script and no page is only a candidate when nothing else is.
+    return hasPage(dir, pkgRaw, io) ? AppSignal.UI : AppSignal.SERVED;
 }
 /**
  * App directories under a workspace root.
@@ -173,14 +213,73 @@ export function findWorkspaceApps(io) {
     });
     // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
     // its children rather than assuming one level of nesting.
+    const served = [];
+    const consider = (dir) => {
+        const signal = appSignal(dir, io);
+        if (AppSignal.UI === signal)
+            found.push(dir);
+        if (AppSignal.SERVED === signal)
+            served.push(dir);
+    };
     for (const parent of parents) {
-        if (looksLikeApp(parent, io))
-            found.push(parent);
-        for (const name of io.listDirs(parent)) {
-            const dir = `${parent}/${name}`;
-            if (looksLikeApp(dir, io))
-                found.push(dir);
+        consider(parent);
+        for (const name of io.listDirs(parent))
+            consider(`${parent}/${name}`);
+    }
+    // A backend is still the app when it is the only thing that can be served — a server-rendered
+    // app is exactly that — so it is demoted, never dropped.
+    return [...new Set(found.length > 0 ? found : served)];
+}
+/**
+ * Every package directory the workspace declares or holds, app-shaped or not.
+ *
+ * For the questions discovery's filter must not answer — "which package does the root config name"
+ * is about identity, and a package `--app` wired is the app whether or not it looks like one.
+ */
+export function workspacePackageDirs(io) {
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    const pnpmWorkspace = io.readFile(PNPM_WORKSPACE);
+    const parents = workspaceParents({
+        ...(null === pnpmWorkspace ? {} : { pnpmWorkspace }),
+        ...(null === pkgRaw ? {} : { pkgWorkspaces: parsedManifest(pkgRaw)['workspaces'] }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    return [...new Set(parents.flatMap((p) => [p, ...io.listDirs(p).map((n) => `${p}/${n}`)]))];
+}
+/** How far up `init` looks for the workspace a package belongs to. Deeper than any real layout. */
+const MAX_WORKSPACE_DEPTH = 8;
+/**
+ * The workspace root that DECLARES `cwd` as one of its packages, or undefined.
+ *
+ * `init` run inside `apps/web` wrote `.reticle.json` there only, and `reticle mcp` finds that file by
+ * walking UP from where the agent stands — so an agent opened at the repo root never found it, fell
+ * back to the default port, and drove whichever daemon was there. `init --app apps/web` run from the
+ * root writes the root pointer and the agent files at the root; this is what lets a run from inside
+ * the app arrive at the same state.
+ *
+ * Only the NEAREST workspace root is asked, and only its declaration counts: a directory that merely
+ * sits under a repo with a package.json is not that repo's app, and guessing it is would write
+ * config into a stranger's root.
+ */
+export function enclosingWorkspaceRoot(cwd, io) {
+    let dir = dirname(cwd);
+    for (let depth = 0; depth < MAX_WORKSPACE_DEPTH; depth++) {
+        const pnpmWorkspace = io.readFile(join(dir, PNPM_WORKSPACE));
+        const pkgRaw = io.readFile(join(dir, PACKAGE_JSON));
+        const pkgWorkspaces = null === pkgRaw ? undefined : parsedManifest(pkgRaw)['workspaces'];
+        if (null !== pnpmWorkspace || pkgWorkspaces !== undefined) {
+            const declared = workspaceParents({
+                ...(null === pnpmWorkspace ? {} : { pnpmWorkspace }),
+                ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+            });
+            const rel = relative(dir, cwd).split(sep).join('/');
+            const member = declared.some((base) => rel === base || dirname(rel) === base);
+            return member ? dir : undefined;
         }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
     }
-    return [...new Set(found)];
+    return undefined;
 }

package/dist/detect/workspace-redirect.js

@@ -10,8 +10,25 @@
  */
 import { join } from 'node:path';
 import { detect, Framework } from './detect.js';
-import { findWorkspaceApps, PACKAGE_JSON } from './workspace-apps.js';
+import { detectNonJsEcosystem, noPackageJsonMessage } from './non-js-project.js';
+import { findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs } from './workspace-apps.js';
+import { projectIdOf, RETICLE_CONFIG_FILE } from './existing-config.js';
 import { chooseWorkspaceApp, withoutTrailingSlashes } from './declared/app-choice.js';
+const ROOT_CONFIG_LEAD = `This root's ${RETICLE_CONFIG_FILE} names`;
+/**
+ * The one workspace package whose `.reticle.json` carries the project the root's does.
+ *
+ * The root config is a copy of the app's (see `agentRootConfigStep`), so the projectId is what ties
+ * the two together; no path is stored. Searched across every package directory rather than the
+ * discovered apps, because the app `--app` named is the app whether or not discovery would list it.
+ */
+function appNamedByRootConfig(io) {
+    const wanted = projectIdOf(io.readFile(RETICLE_CONFIG_FILE));
+    if (wanted === undefined)
+        return undefined;
+    const named = workspacePackageDirs(io).filter((dir) => projectIdOf(io.readFile(`${dir}/${RETICLE_CONFIG_FILE}`)) === wanted);
+    return 1 === named.length ? named[0] : undefined;
+}
 const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` inside the one you want:';
 /**
  * When the current directory is a workspace root with no app of its own, wire the app instead of the
@@ -44,11 +61,20 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
         const wanted = withoutTrailingSlashes(named);
         if (io.exists(`${wanted}/${PACKAGE_JSON}`))
             return enterApp(options, io, wanted, 'Wiring', runInit);
-        io.print(`--app ${named} does not name a directory with a package.json in it.`);
+        const inWanted = (file) => io.exists(`${wanted}/${file}`);
+        io.print(detectNonJsEcosystem(inWanted) === undefined
+            ? `--app ${named} does not name a directory with a package.json in it.`
+            : noPackageJsonMessage(inWanted));
         return { ok: false, applied: 0, manual: 1 };
     }
     if (here.framework !== Framework.HTML)
         return null; // this directory IS the app
+    // A root that an earlier `--app` run (or a run inside the app) already pointed at one app has
+    // answered the question discovery would ask. Ignoring it made every re-run at the root refuse
+    // again with the same list, and exit 1 over a setup that had worked.
+    const pointed = appNamedByRootConfig(io);
+    if (pointed !== undefined)
+        return enterApp(options, io, pointed, ROOT_CONFIG_LEAD, runInit);
     const apps = findWorkspaceApps(io);
     // An explicitly named app answers the ambiguity. Refusing to guess is right, but "re-run inside the
     // one you want" is not something a script, a CI step, or an agent that cannot change directory can

package/dist/diagnose/containerised-dev-server.d.ts

@@ -17,10 +17,11 @@
  * container — it needs an image rebuild and a fresh volume. The same field install lost two and a
  * half minutes discovering that through a failed build.
  *
- * DETECTION IS DELIBERATELY CHEAP AND OVER-EAGER. A Dockerfile or a compose file near the app is not
- * proof the dev server runs in one — plenty of repos containerise only production. But this step
- * asks for nothing and changes nothing, so a false positive costs one paragraph the reader skips,
- * while a false negative costs what it cost in the field.
+ * DETECTION IS CHEAP, AND ERRS TOWARDS SPEAKING — but a container file counts only when it RUNS a
+ * dev server (see runsDevServer). It used to count on presence alone, and React Router's own
+ * template ships a production Dockerfile, so every React Router install was told to rebuild an image
+ * and mount a token for a dev server that runs on the host. A devcontainer still counts on presence:
+ * it is the development environment by definition.
  */
 /** Files whose presence means this repo builds a container image somewhere near the app. */
 export declare const CONTAINER_MARKERS: readonly ["Dockerfile", "dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml", ".devcontainer/devcontainer.json"];
@@ -30,3 +31,10 @@ export declare const CONTAINERISED_TITLE = "Containerised dev server";
  * the page — the SDK loads, the socket opens, no session appears — so they are told together.
  */
 export declare function containerisedDevServerNote(marker: string): string;
+/**
+ * Does this container file run the app's dev server?
+ *
+ * @param devScript the app's own `scripts.dev`, so a container that runs it by its command rather
+ *   than through the package manager (`CMD react-router dev`) still counts.
+ */
+export declare function runsDevServer(marker: string, content: string, devScript: string | undefined): boolean;

package/dist/diagnose/containerised-dev-server.js

@@ -17,10 +17,11 @@
  * container — it needs an image rebuild and a fresh volume. The same field install lost two and a
  * half minutes discovering that through a failed build.
  *
- * DETECTION IS DELIBERATELY CHEAP AND OVER-EAGER. A Dockerfile or a compose file near the app is not
- * proof the dev server runs in one — plenty of repos containerise only production. But this step
- * asks for nothing and changes nothing, so a false positive costs one paragraph the reader skips,
- * while a false negative costs what it cost in the field.
+ * DETECTION IS CHEAP, AND ERRS TOWARDS SPEAKING — but a container file counts only when it RUNS a
+ * dev server (see runsDevServer). It used to count on presence alone, and React Router's own
+ * template ships a production Dockerfile, so every React Router install was told to rebuild an image
+ * and mount a token for a dev server that runs on the host. A devcontainer still counts on presence:
+ * it is the development environment by definition.
  */
 import { ReticleEnv } from '@reticlehq/core';
 /** Files whose presence means this repo builds a container image somewhere near the app. */
@@ -54,3 +55,34 @@ export function containerisedDevServerNote(marker) {
         '     The token is inlined when the dev server resolves its config, so restart it afterwards. ' +
         'Run the Reticle daemon at least once first, or Docker creates a DIRECTORY at that host path.');
 }
+const DEVCONTAINER = '.devcontainer/devcontainer.json';
+/**
+ * Commands that start a dev server, in shell form or Dockerfile exec form (`["npm", "run", "dev"]`).
+ * The separator class takes quotes and commas so both spellings match. `vite` counts bare, or
+ * followed by a flag, but never as `vite build` / `vite preview`, which serve nothing live.
+ */
+const SEP = `["',\\s]+`;
+const DEV_SERVER_COMMANDS = [
+    new RegExp(`\\b(?:npm|pnpm|yarn|bun)${SEP}(?:run${SEP})?dev\\b`),
+    new RegExp(`\\b(?:next|nuxt|nuxi|astro|react-router|remix|vinxi)${SEP}dev\\b`),
+    new RegExp(`\\bng${SEP}serve\\b`),
+    new RegExp(`\\breact-scripts${SEP}start\\b`),
+    new RegExp(`\\bwebpack${SEP}serve\\b|\\bwebpack-dev-server\\b`),
+    /\bvite["']?(?=\s*(?:$|--|["']?\s*[\],]))/m,
+];
+/**
+ * Does this container file run the app's dev server?
+ *
+ * @param devScript the app's own `scripts.dev`, so a container that runs it by its command rather
+ *   than through the package manager (`CMD react-router dev`) still counts.
+ */
+export function runsDevServer(marker, content, devScript) {
+    if (DEVCONTAINER === marker)
+        return true;
+    if (devScript !== undefined &&
+        0 < devScript.trim().length &&
+        content.includes(devScript.trim())) {
+        return true;
+    }
+    return DEV_SERVER_COMMANDS.some((command) => command.test(content));
+}

package/dist/diagnose/csp-check.d.ts

@@ -38,12 +38,18 @@ export declare const EXTERNAL_CONNECT_PATH = "public/reticle-connect.js";
 export declare function externalScriptRemedy(): string;
 /** The exact addition to paste. Text to copy, not advice to interpret. */
 export declare function devCspAddition(port: number): string;
-/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
-export declare const CSP_STEP_TITLE = "Content-Security-Policy";
 /**
- * The first blocking policy among the sources `init` already has in hand, or undefined.
+ * The same HTML with every CSP `<meta>` that blocks the bridge made to admit it, or undefined when
+ * none needed it — the one policy location `init` can edit safely, because it is a file of the app's
+ * own and the edit is a pair of sources appended to one directive.
  *
- * At most one finding: a second copy of the same policy in a second file is the same problem, and
- * two identical notices read as two problems.
+ * Reproduced on electron-vite's own template: `default-src 'self'` and no `connect-src`, so the
+ * bridge WebSocket is refused and init waited out its whole budget. The origins are loopback-only;
+ * a static `<meta>` has no development branch, so they are present in a packaged build too, where
+ * nothing listens on them. On a port move the pair is REPLACED (see stalePairs).
  */
-export declare function cspPlanProblem(sources: readonly (string | null | undefined)[], port: number): string | undefined;
+export declare function patchCspMetaConnectSrc(html: string, port: number): string | undefined;
+/** What the patched step says it did. */
+export declare function cspPatchedDetail(port: number): string;
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export declare const CSP_STEP_TITLE = "Content-Security-Policy";

package/dist/diagnose/csp-check.js

@@ -148,21 +148,69 @@ export function devCspAddition(port) {
         `\`process.env.NODE_ENV === 'development'\`): ` +
         `${bridgeOrigins(port).join(' ')}`);
 }
-/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
-export const CSP_STEP_TITLE = 'Content-Security-Policy';
+/** A `<meta http-equiv="Content-Security-Policy" content=…>` tag's content attribute, by quote. */
+const CSP_META = /<meta\b[^>]*http-equiv\s*=\s*["']?content-security-policy["']?[^>]*>/gi;
+const CONTENT_ATTR = /(\bcontent\s*=\s*)(["'])((?:(?!\2).)*)\2/i;
+/** A loopback WebSocket source, with its port captured. */
+const LOOPBACK_WS = /^ws:\/\/(?:localhost|127\.0\.0\.1):(\d+)$/;
 /**
- * The first blocking policy among the sources `init` already has in hand, or undefined.
+ * The ports for which BOTH bridge origins are present — the pair this file writes, and the only
+ * loopback sources it may take back out.
  *
- * At most one finding: a second copy of the same policy in a second file is the same problem, and
- * two identical notices read as two problems.
+ * A port move used to APPEND the new pair beside the old one, so the policy kept admitting a port
+ * nothing listened on and grew a pair per move. One `ws://localhost:3000` the app wrote for its own
+ * dev server is not a pair, and is left alone.
  */
-export function cspPlanProblem(sources, port) {
-    for (const source of sources) {
-        if ('string' !== typeof source)
-            continue;
-        const problem = cspConnectSrcProblem(source, port);
-        if (problem !== undefined)
-            return problem;
+function stalePairs(sources, port) {
+    const ports = sources.flatMap((source) => LOOPBACK_WS.exec(source)?.[1] ?? []);
+    return new Set(ports.filter((p) => String(port) !== p && bridgeOrigins(Number(p)).every((origin) => sources.includes(origin))));
+}
+/** The policy with both bridge origins admitted to `connect-src`, every other directive untouched. */
+function withBridgeOrigins(policy, port) {
+    const origins = bridgeOrigins(port);
+    const directives = policy.split(';');
+    const connect = directives.findIndex((d) => /^\s*connect-src\b/i.test(d));
+    if (-1 !== connect) {
+        const current = directives[connect] ?? '';
+        const sources = current.trim().split(/\s+/);
+        const stale = stalePairs(sources, port);
+        const kept = sources.filter((source) => !stale.has(LOOPBACK_WS.exec(source)?.[1] ?? ''));
+        const missing = origins.filter((origin) => !kept.includes(origin));
+        const lead = /^\s*/.exec(current)?.[0] ?? '';
+        directives[connect] = `${lead}${[...kept, ...missing].join(' ')}`;
+        return directives.join(';');
     }
-    return undefined;
+    // No connect-src: the socket falls back to default-src, so the new directive starts from what
+    // default-src already allowed — adding it bare would take 'self' away from every fetch the app does.
+    const fallback = directiveSources(policy, 'default-src') ?? [];
+    const added = ` connect-src ${[...fallback, ...origins].join(' ')}`;
+    const trimmed = policy.trimEnd();
+    return trimmed.endsWith(';') ? `${trimmed}${added};` : `${trimmed};${added}`;
+}
+/**
+ * The same HTML with every CSP `<meta>` that blocks the bridge made to admit it, or undefined when
+ * none needed it — the one policy location `init` can edit safely, because it is a file of the app's
+ * own and the edit is a pair of sources appended to one directive.
+ *
+ * Reproduced on electron-vite's own template: `default-src 'self'` and no `connect-src`, so the
+ * bridge WebSocket is refused and init waited out its whole budget. The origins are loopback-only;
+ * a static `<meta>` has no development branch, so they are present in a packaged build too, where
+ * nothing listens on them. On a port move the pair is REPLACED (see stalePairs).
+ */
+export function patchCspMetaConnectSrc(html, port) {
+    let changed = false;
+    const out = html.replace(CSP_META, (tag) => tag.replace(CONTENT_ATTR, (whole, head, quote, policy) => {
+        if (cspConnectSrcProblem(policy, port) === undefined)
+            return whole;
+        changed = true;
+        return `${head}${quote}${withBridgeOrigins(policy, port)}${quote}`;
+    }));
+    return changed ? out : undefined;
+}
+/** What the patched step says it did. */
+export function cspPatchedDetail(port) {
+    return (`admit the Reticle bridge (${bridgeOrigins(port).join(' ')}) to connect-src — the policy ` +
+        'blocked the WebSocket, so the app could never connect');
 }
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export const CSP_STEP_TITLE = 'Content-Security-Policy';

package/dist/diagnose/csp-doctor.d.ts

@@ -39,7 +39,19 @@ export interface ObservedWebDocument {
  * plain `index.html` cover the `<meta http-equiv>` style. Both reported cases were in this list.
  */
 export declare const CSP_FILES: readonly string[];
-export declare function diagnoseWebCsp(read: ReadFile, port: number, alsoCheck?: readonly string[]): CspDiagnosis[];
+export interface WebCspOptions {
+    /**
+     * Whether this app connects through the hand-pasted INLINE snippet — the plain-HTML path. Only
+     * then can `script-src` stop the connect from running. Every plugin-wired app connects from an
+     * external module (web) or from its entry module (desktop), and for those the inline rule was
+     * reported INSTEAD of the connect-src block that actually stopped them — with a fix (move the
+     * snippet to public/reticle-connect.js) that does not apply to an app with no snippet. Defaults to
+     * true because `doctor` does not know how the app is wired, and the inline finding carries the
+     * connect-src addition too.
+     */
+    readonly inlineSnippet?: boolean;
+}
+export declare function diagnoseWebCsp(read: ReadFile, port: number, alsoCheck?: readonly string[], options?: WebCspOptions): CspDiagnosis[];
 /** Diagnose only policies observed on the served development document. */
 export declare function diagnoseObservedWebCsp(document: ObservedWebDocument, port: number): CspDiagnosis[];
 /** Runtime evidence outranks source prediction; a connected SDK disproves a blocking policy. */

package/dist/diagnose/csp-doctor.js

@@ -52,7 +52,7 @@ function pagePolicySource(file, source) {
         return source;
     return source.replace(/contentSecurityPolicy\s*[:=]\s*(['\x22`])[\s\S]*?\1/g, '');
 }
-export function diagnoseWebCsp(read, port, alsoCheck = []) {
+export function diagnoseWebCsp(read, port, alsoCheck = [], options = {}) {
     const findings = [];
     for (const file of [...alsoCheck, ...CSP_FILES]) {
         const raw = read(file);
@@ -62,7 +62,7 @@ export function diagnoseWebCsp(read, port, alsoCheck = []) {
         // `script-src` first, because it is the earlier failure. A policy that blocks the inline
         // snippet means there is no SDK at all, so a `connect-src` finding on the same file would be
         // describing a socket that is never opened -- true, and the wrong thing to fix first (#679).
-        const inline = cspInlineScriptProblem(source, port);
+        const inline = false === options.inlineSnippet ? undefined : cspInlineScriptProblem(source, port);
         if (inline !== undefined) {
             findings.push({
                 file,

package/dist/diagnose/csp-step.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The plan's Content-Security-Policy step: the one check that runs before any framework's wiring,
+ * because a policy that refuses the bridge makes every other step moot.
+ */
+import { type PlanInput, type Step } from '../plan/plan-types.js';
+import { type WebCspOptions } from './csp-doctor.js';
+/**
+ * How the app connects, as the CSP diagnosis needs to know it. Only the plain-HTML path pastes an
+ * inline snippet, so only there can `script-src` stop the connect; see WebCspOptions.
+ *
+ * Shared with `reticle doctor`, which reads the framework `init` stamped into `.reticle.json`. It
+ * used to assume the inline snippet for every app, so on electron-vite it reported the inline rule
+ * while `init` reported the connect-src block that actually stops the bridge. Unknown wiring keeps
+ * the conservative default.
+ */
+export declare function webCspOptionsFor(framework: string | undefined): WebCspOptions;
+/**
+ * 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. It was a NOTICE, and on electron-vite's own template that meant init
+ * waited out its whole connect budget without saying the app could not connect. So a `<meta>` policy
+ * in the app's HTML is now edited to admit the bridge, and a policy anywhere else is a blocking ⚠
+ * carrying the exact text to paste.
+ */
+export declare function cspStep(input: PlanInput): Step[];

package/dist/diagnose/csp-step.js

@@ -0,0 +1,86 @@
+/**
+ * The plan's Content-Security-Policy step: the one check that runs before any framework's wiring,
+ * because a policy that refuses the bridge makes every other step moot.
+ */
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { Framework } from '../detect/detect.js';
+import { StepStatus } from '../plan/plan-types.js';
+import { CSP_STEP_TITLE, cspPatchedDetail, externalScriptRemedy, patchCspMetaConnectSrc, } from './csp-check.js';
+import { diagnoseWebCsp } from './csp-doctor.js';
+/**
+ * How the app connects, as the CSP diagnosis needs to know it. Only the plain-HTML path pastes an
+ * inline snippet, so only there can `script-src` stop the connect; see WebCspOptions.
+ *
+ * Shared with `reticle doctor`, which reads the framework `init` stamped into `.reticle.json`. It
+ * used to assume the inline snippet for every app, so on electron-vite it reported the inline rule
+ * while `init` reported the connect-src block that actually stops the bridge. Unknown wiring keeps
+ * the conservative default.
+ */
+export function webCspOptionsFor(framework) {
+    return framework === undefined ? {} : { inlineSnippet: Framework.HTML === framework };
+}
+/**
+ * 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. It was a NOTICE, and on electron-vite's own template that meant init
+ * waited out its whole connect budget without saying the app could not connect. So a `<meta>` policy
+ * in the app's HTML is now edited to admit the bridge, and a policy anywhere else is a blocking ⚠
+ * carrying the exact text to paste.
+ */
+export function cspStep(input) {
+    // Reads the SAME list `reticle doctor` reads. It used to read a hand-written pair —
+    // `[nextConfigSource, nextLayout?.source]` — while csp-doctor.ts already carried the full set
+    // including `index.html`, which is where every Vite and Electron app declares its policy. So the
+    // command you run BEFORE anything works checked less than the one you run after it has failed.
+    //
+    // Measured on MarkText, a production Electron editor: its renderer sets `default-src 'self'` with
+    // no `connect-src`, the browser blocked the bridge WebSocket, and `init` printed a clean plan. The
+    // daemon cannot see a dial that never left the page, so nothing anywhere said why — and the check
+    // that would have said it was sitting one import away.
+    // The pre-read Next sources are folded in ON TOP of the shared list, not replaced by it: init
+    // resolves `nextConfigFile` across more spellings than CSP_FILES names (`.mts`, for one), and a
+    // layout is found by search rather than by a fixed path. Two sources of the same truth is the
+    // problem being fixed here — one of them being a SUPERSET is not.
+    const extra = {
+        ...(input.nextConfigFile !== null && input.nextConfigFile !== undefined
+            ? { [input.nextConfigFile]: input.nextConfigSource ?? undefined }
+            : {}),
+        ...(input.nextLayout ? { [input.nextLayout.path]: input.nextLayout.source } : {}),
+    };
+    const read = (file) => extra[file] ?? input.cspSources?.[file];
+    const port = input.options.port ?? RETICLE_DEFAULT_PORT;
+    const findings = diagnoseWebCsp(read, port, [...Object.keys(extra)], webCspOptionsFor(input.detection.framework));
+    const first = findings[0];
+    if (first === undefined)
+        return [];
+    // A `<meta>` policy in the app's own HTML is edited in place. Anything else — a header built in
+    // next.config, middleware, a host's config — is a ⚠ that fails init: the browser is guaranteed to
+    // refuse the socket, and a NOTICE let init wait out its whole budget without saying so.
+    const source = read(first.file);
+    const patched = first.file.endsWith('.html') && source !== undefined && first.fix !== externalScriptRemedy()
+        ? patchCspMetaConnectSrc(source, port)
+        : undefined;
+    if (patched !== undefined) {
+        return [
+            {
+                title: CSP_STEP_TITLE,
+                target: first.file,
+                status: StepStatus.APPLY,
+                detail: cspPatchedDetail(port),
+                write: { path: first.file, content: patched },
+            },
+        ];
+    }
+    return [
+        {
+            title: CSP_STEP_TITLE,
+            target: first.file,
+            status: StepStatus.MANUAL,
+            // `problem` already ends with the text to paste; `fix` is the same sentence for callers that
+            // want it on its own (doctor renders them separately). Printing both said it twice.
+            detail: first.problem,
+        },
+    ];
+}

package/dist/diagnose/desktop-doctor.js

@@ -1,4 +1,4 @@
-import { RETICLE_IPC_GLOBAL, realmOf, realmOfProject } from '@reticlehq/core';
+import { RETICLE_CAPTURE_CHANNEL, RETICLE_IPC_GLOBAL, realmOf, realmOfProject, } from '@reticlehq/core';
 /**
  * Setup RCA for desktop apps.
  *
@@ -165,7 +165,13 @@ function diagnoseElectron(read, main) {
         });
     }
     const mainSource = read(main);
-    if (mainSource !== undefined && !mainSource.includes(CAPTURE_REQUIRE)) {
+    // The require OR the contract's capture channel. `main` is usually the BUILD output, and bundling
+    // erases the require: an electron-vite app that did install the helper was told it never had. The
+    // helper registers the channel by its contract string, which survives bundling — the same
+    // artifact-level evidence the preload check above reads from the IPC global.
+    const captureWired = true === mainSource?.includes(CAPTURE_REQUIRE) ||
+        true === mainSource?.includes(RETICLE_CAPTURE_CHANNEL);
+    if (mainSource !== undefined && !captureWired) {
         findings.push({
             code: DesktopFinding.ELECTRON_CAPTURE_MISSING,
             file: main,

package/dist/diagnose/init-failure.d.ts

@@ -13,6 +13,13 @@ export declare const InitFailure: {
     readonly DEPENDENCY_INSTALL: "dependency_install";
     /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
     readonly MCP_REGISTRATION: "mcp_registration";
+    /** The checkout or required tooling failed preflight. */
+    readonly PREFLIGHT: "preflight";
+    /** Runtime continuation could not start the app or connect its SDK. */
+    readonly DEV_SERVER: "dev_server";
+    readonly APP_CONNECTION: "app_connection";
+    readonly BRIDGE_OCCUPIED: "bridge_occupied";
+    readonly RUNTIME_ERROR: "runtime_error";
     readonly OTHER: "other";
 };
 export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];

package/dist/diagnose/init-failure.js

@@ -13,5 +13,12 @@ export const InitFailure = {
     DEPENDENCY_INSTALL: 'dependency_install',
     /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
     MCP_REGISTRATION: 'mcp_registration',
+    /** The checkout or required tooling failed preflight. */
+    PREFLIGHT: 'preflight',
+    /** Runtime continuation could not start the app or connect its SDK. */
+    DEV_SERVER: 'dev_server',
+    APP_CONNECTION: 'app_connection',
+    BRIDGE_OCCUPIED: 'bridge_occupied',
+    RUNTIME_ERROR: 'runtime_error',
     OTHER: 'other',
 };

package/dist/diagnose/install-hint.d.ts

@@ -5,4 +5,12 @@
  * which package manager was used.
  */
 import { PackageManager } from '../detect/detect.js';
-export declare function installFailureHint(pm: PackageManager): string;
+/**
+ * `pm` picks which hint applies; `pmCommand` is what the reader actually types.
+ *
+ * A corepack-only machine (see `preflight.ts`, #1149) has no bare `pnpm` on PATH — that is the whole
+ * shape of the bug this hint is used alongside. Printing `pnpm config set …` to that reader hands them
+ * a command that fails the same way the original install did; `pmCommand` is the resolved invocation
+ * (`corepack pnpm`, there) that is actually run on this machine.
+ */
+export declare function installFailureHint(pm: PackageManager, pmCommand?: string): string;