@reticlehq/init 3.2.0 → 3.3.0

package/dist/detect/detect.d.ts

@@ -143,9 +143,20 @@ export interface Detection {
      */
     webGlSubtree?: boolean | undefined;
     packageManager: PackageManager;
+    /**
+     * Every dependency this package DECLARES, by name, merged across the three blocks.
+     *
+     * So the planner can tell "not wired yet" from "wired already". Without it the install step could
+     * only ever say APPLY, and a re-run over an instrumented project therefore ran a package-manager
+     * install it did not need - which is the step that touches `node_modules`.
+     *
+     * Optional so every existing construction keeps working; absent reads as "nothing known", which
+     * installs, and installing twice is the harmless direction.
+     */
+    dependencies?: Readonly<Record<string, string>> | undefined;
 }
 /** What identifies one framework in a project root: a dependency name, or a config file basename. */
-export interface FrameworkSignals {
+interface FrameworkSignals {
     /** `package.json` dependency names that name this framework outright. */
     readonly deps: readonly string[];
     /** Root config-file basenames that name it when the dependency is absent. */
@@ -196,7 +207,7 @@ export declare function parseMajor(range: string | undefined): number | undefine
  * lockfile once the project's own tree can answer the question.
  */
 export declare function namesAPackageManager(markers: ReadonlySet<string>): boolean;
-export declare function detectPackageManager(lockfiles: ReadonlySet<string>, nodeModulesMarkers: ReadonlySet<string>): PackageManager;
+export declare function detectPackageManager(lockfiles: ReadonlySet<string>, nodeModulesMarkers: ReadonlySet<string>, pkg?: unknown): PackageManager;
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;

package/dist/detect/detect.js

@@ -221,7 +221,41 @@ function packageManagerFromNodeModules(markers) {
 export function namesAPackageManager(markers) {
     return packageManagerFromNodeModules(markers) !== undefined;
 }
-export function detectPackageManager(lockfiles, nodeModulesMarkers) {
+/**
+ * The manager a project DECLARES, via corepack's `packageManager` field.
+ *
+ * The strongest signal there is, and stronger than anything else here: a lockfile is evidence of
+ * what was run once, an installed tree is evidence of what was run last, and this is the project
+ * SAYING which one it uses. Corepack enforces it — it refuses to run a different manager on the
+ * project's behalf — so choosing against it produces a command that cannot work.
+ *
+ * Unrecognised values fall through rather than defaulting. A field naming something we do not know
+ * must not quietly become npm; that is how a pnpm repo gets an `npm i`.
+ */
+function packageManagerFromField(pkg) {
+    if ('object' !== typeof pkg || null === pkg)
+        return undefined;
+    const declared = pkg['packageManager'];
+    if ('string' !== typeof declared)
+        return undefined;
+    // `name@version`, and the version is not ours to care about — only which binary runs.
+    const name = declared.split('@')[0]?.trim().toLowerCase();
+    const known = {
+        npm: PackageManager.NPM,
+        pnpm: PackageManager.PNPM,
+        yarn: PackageManager.YARN,
+        bun: PackageManager.BUN,
+    };
+    return name === undefined ? undefined : known[name];
+}
+export function detectPackageManager(lockfiles, nodeModulesMarkers, pkg) {
+    // What the project SAYS beats every trace of what was once run in it. Reported from the field: an
+    // already-instrumented npm workspaces project had a pnpm dependency migration run over it, which
+    // moved its `node_modules` aside and broke the dev server. Moving an installed tree is not
+    // something a scaffolder may do to a working checkout.
+    const declared = packageManagerFromField(pkg);
+    if (declared !== undefined)
+        return declared;
     if (lockfiles.has('pnpm-lock.yaml'))
         return PackageManager.PNPM;
     if (lockfiles.has('yarn.lock'))
@@ -231,6 +265,10 @@ export function detectPackageManager(lockfiles, nodeModulesMarkers) {
     // No lockfile is not the same as "npm". An already-installed tree says which manager built it.
     return packageManagerFromNodeModules(nodeModulesMarkers) ?? PackageManager.NPM;
 }
+/** Every declared dependency, by name. Later blocks do not override earlier ones by accident. */
+function declaredDependencies(pkg) {
+    return { ...pkg.peerDependencies, ...pkg.devDependencies, ...pkg.dependencies };
+}
 function detectFramework(input) {
     for (const framework of DETECTION_ORDER) {
         const signals = FRAMEWORK_SIGNALS[framework];
@@ -272,7 +310,8 @@ export function detect(input) {
         needsSourceMapping: reactMajor !== undefined && reactMajor >= 19,
         customReconciler: CUSTOM_RECONCILER_DEPS.some((name) => depVersion(input.pkg, name) !== undefined),
         webGlSubtree: WEBGL_SUBTREE_DEPS.some((name) => depVersion(input.pkg, name) !== undefined),
-        packageManager: detectPackageManager(input.lockfiles, input.nodeModulesMarkers ?? new Set()),
+        packageManager: detectPackageManager(input.lockfiles, input.nodeModulesMarkers ?? new Set(), input.pkg),
+        dependencies: declaredDependencies(input.pkg),
     };
 }
 const INSTALL_ARGS = {

package/dist/detect/workspace-redirect.d.ts

@@ -10,7 +10,7 @@
  */
 import type { InitIo, InitOptions, InitResult } from '../run-types.js';
 /** Re-enter `init`, scoped to one directory of the workspace. */
-export type RunInit = (options: InitOptions, io: InitIo) => InitResult;
+type RunInit = (options: InitOptions, io: InitIo) => InitResult;
 /**
  * When the current directory is a workspace root with no app of its own, wire the app instead of the
  * root. One candidate is wired silently (there is nothing to ask about); several are listed, because
@@ -18,3 +18,4 @@ export type RunInit = (options: InitOptions, io: InitIo) => InitResult;
  * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
  */
 export declare function redirectToWorkspaceApp(options: InitOptions, io: InitIo, pkg: unknown, runInit: RunInit): InitResult | null;
+export {};

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

@@ -13,13 +13,24 @@
  */
 /** Read a project-relative file, or undefined when it is absent/unreadable. */
 type ReadFile = (relative: string) => string | undefined;
-interface CspDiagnosis {
+export declare const CspBasis: {
+    readonly OBSERVED: "observed";
+    readonly PREDICTED: "predicted";
+};
+export interface CspDiagnosis {
     /** Which file to look at. */
     file: string;
     /** What is wrong, in one line. */
     problem: string;
     /** Exactly what to add — copy-pasteable, with the port actually in use. */
     fix: string;
+    /** Whether the policy was read from the served document or inferred from project source. */
+    basis: (typeof CspBasis)[keyof typeof CspBasis];
+}
+export interface ObservedWebDocument {
+    url: string;
+    headers: readonly string[];
+    html: string;
 }
 /**
  * The places a Content-Security-Policy gets written in a JS app.
@@ -29,4 +40,12 @@ interface CspDiagnosis {
  */
 export declare const CSP_FILES: readonly string[];
 export declare function diagnoseWebCsp(read: ReadFile, port: number, alsoCheck?: readonly string[]): 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. */
+export declare function resolveWebCspFindings(input: {
+    predicted: readonly CspDiagnosis[];
+    observed?: readonly CspDiagnosis[];
+    connected: boolean;
+}): CspDiagnosis[];
 export {};

package/dist/diagnose/csp-doctor.js

@@ -12,6 +12,10 @@
  * would find policy strings in test fixtures and documentation.
  */
 import { cspConnectSrcProblem, cspInlineScriptProblem, devCspAddition, externalScriptRemedy, } from './csp-check.js';
+export const CspBasis = {
+    OBSERVED: 'observed',
+    PREDICTED: 'predicted',
+};
 /**
  * The places a Content-Security-Policy gets written in a JS app.
  *
@@ -39,24 +43,117 @@ export const CSP_FILES = [
     'vercel.json',
     'netlify.toml',
 ];
+/**
+ * Next's `images.contentSecurityPolicy` is sent only with optimized images, never with the page.
+ * Treating it as a document policy tells a working app to weaken a header that cannot block it.
+ */
+function pagePolicySource(file, source) {
+    if (!file.startsWith('next.config.'))
+        return source;
+    return source.replace(/contentSecurityPolicy\s*[:=]\s*(['\x22`])[\s\S]*?\1/g, '');
+}
 export function diagnoseWebCsp(read, port, alsoCheck = []) {
     const findings = [];
     for (const file of [...alsoCheck, ...CSP_FILES]) {
-        const source = read(file);
-        if (source === undefined)
+        const raw = read(file);
+        if (raw === undefined)
             continue;
+        const source = pagePolicySource(file, raw);
         // `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);
         if (inline !== undefined) {
-            findings.push({ file, problem: inline, fix: externalScriptRemedy() });
+            findings.push({
+                file,
+                problem: inline,
+                fix: externalScriptRemedy(),
+                basis: CspBasis.PREDICTED,
+            });
             continue;
         }
         const problem = cspConnectSrcProblem(source, port);
         if (problem === undefined)
             continue;
-        findings.push({ file, problem, fix: devCspAddition(port) });
+        findings.push({ file, problem, fix: devCspAddition(port), basis: CspBasis.PREDICTED });
+    }
+    return findings;
+}
+function observedFinding(policy, file, port) {
+    const inline = cspInlineScriptProblem(policy, port);
+    if (inline !== undefined) {
+        return {
+            file,
+            problem: inline,
+            fix: externalScriptRemedy(),
+            basis: CspBasis.OBSERVED,
+        };
+    }
+    const connect = cspConnectSrcProblem(policy, port);
+    return connect === undefined
+        ? undefined
+        : {
+            file,
+            problem: connect,
+            fix: devCspAddition(port),
+            basis: CspBasis.OBSERVED,
+        };
+}
+function attributeValue(tag, name) {
+    const pattern = new RegExp(`\\b${name}\\s*=\\s*(?:\\x22([^\\x22]*)\\x22|'([^']*)'|([^\\s>]+))`, 'i');
+    const match = pattern.exec(tag);
+    return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+/** CSP meta policies from the document the development server actually returned. */
+function withoutHtmlComments(html) {
+    const visible = [];
+    let cursor = 0;
+    while (cursor < html.length) {
+        const start = html.indexOf('<!--', cursor);
+        if (-1 === start) {
+            visible.push(html.slice(cursor));
+            break;
+        }
+        visible.push(html.slice(cursor, start));
+        const end = html.indexOf('-->', start + 4);
+        if (-1 === end)
+            break;
+        cursor = end + 3;
+    }
+    return visible.join('');
+}
+function metaPolicies(html) {
+    const withoutComments = withoutHtmlComments(html);
+    const policies = [];
+    for (const match of withoutComments.matchAll(/<meta\b[^>]*>/gi)) {
+        const tag = match[0];
+        const equivalent = attributeValue(tag, 'http-equiv');
+        if (equivalent?.toLowerCase() !== 'content-security-policy')
+            continue;
+        const content = attributeValue(tag, 'content');
+        if (content !== undefined && content.length > 0)
+            policies.push(content);
+    }
+    return policies;
+}
+/** Diagnose only policies observed on the served development document. */
+export function diagnoseObservedWebCsp(document, port) {
+    const findings = [];
+    for (const policy of document.headers) {
+        const found = observedFinding(policy, `response header at ${document.url}`, port);
+        if (found !== undefined)
+            findings.push(found);
+    }
+    for (const policy of metaPolicies(document.html)) {
+        const found = observedFinding(policy, `<meta> in ${document.url}`, port);
+        if (found !== undefined)
+            findings.push(found);
     }
     return findings;
 }
+/** Runtime evidence outranks source prediction; a connected SDK disproves a blocking policy. */
+export function resolveWebCspFindings(input) {
+    if (input.connected)
+        return [];
+    return [...(input.observed ?? input.predicted)];
+}

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

@@ -23,7 +23,7 @@ export declare const DesktopFinding: {
     readonly ELECTRON_CAPTURE_MISSING: "electron-capture-missing";
 };
 export type DesktopFinding = (typeof DesktopFinding)[keyof typeof DesktopFinding];
-export interface DesktopDiagnosis {
+interface DesktopDiagnosis {
     code: DesktopFinding;
     /** Which file to look at. */
     file: string;

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

@@ -6,7 +6,7 @@
  * a different cost and a different sentence to say afterwards.
  */
 import { PackageManager } from '../detect/detect.js';
-export interface InstallRetry {
+interface InstallRetry {
     command: string;
     args: string[];
     note: string;
@@ -19,3 +19,4 @@ export interface InstallRetry {
  * the second failure blaming a flag the user never asked for.
  */
 export declare function installRetries(pm: PackageManager, pinned: readonly string[], unpinned: readonly string[], sdkVersion: string | undefined): InstallRetry[];
+export {};

package/dist/host.d.ts

@@ -43,6 +43,12 @@ export interface InitHost {
     pairingToken(): string;
     /** The install channel the environment declares, or undefined when nothing declared one. */
     installSource(): string | undefined;
+    /**
+     * Whether this run was started from inside Claude Code: the one case where writing its project
+     * `.mcp.json` is known to be wanted. A host question because it is read from the environment,
+     * which the scaffolder does not read for itself.
+     */
+    insideClaudeCode(): boolean;
 }
 /**
  * A host that does nothing, for callers that drive `init`'s file surface without running an install

package/dist/host.js

@@ -21,4 +21,7 @@ export const SILENT_HOST = {
     installSource() {
         return undefined;
     },
+    insideClaudeCode() {
+        return false;
+    },
 };

package/dist/index.d.ts

@@ -28,9 +28,10 @@ export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './project/remember-project.js';
 export { detectPackageManager, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
 export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { deriveProjectId, packageName } from './project/project-id.js';
 export { refreshAgentRules } from './project/refresh-rules.js';
 export { diagnoseDesktop, isDesktopProject } from './diagnose/desktop-doctor.js';
-export { diagnoseWebCsp } from './diagnose/csp-doctor.js';
+export { CspBasis, diagnoseObservedWebCsp, diagnoseWebCsp, resolveWebCspFindings, type CspDiagnosis, type ObservedWebDocument, } from './diagnose/csp-doctor.js';
 export { reticleConfigContent } from './patch/snippets.js';
 /**
  * MCP registration, for a caller that has no project.

package/dist/index.js

@@ -28,9 +28,10 @@ export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk } from './project/remember-project.js';
 export { detectPackageManager, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
 export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { deriveProjectId, packageName } from './project/project-id.js';
 export { refreshAgentRules } from './project/refresh-rules.js';
 export { diagnoseDesktop, isDesktopProject } from './diagnose/desktop-doctor.js';
-export { diagnoseWebCsp } from './diagnose/csp-doctor.js';
+export { CspBasis, diagnoseObservedWebCsp, diagnoseWebCsp, resolveWebCspFindings, } from './diagnose/csp-doctor.js';
 export { reticleConfigContent } from './patch/snippets.js';
 /**
  * MCP registration, for a caller that has no project.

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';
+/**
+ * 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): SourcePatch;
-export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary, testids?: readonly string[]): 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;