@reticlehq/init 3.2.0 → 3.4.0

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.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/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/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;

package/dist/diagnose/install-hint.js

@@ -24,17 +24,27 @@ const REGISTRY_HINT = 'If it could not reach the registry at all (offline, a pro
  * sent the reader through their dependency versions looking for a problem that was actually
  * about where the store lives (#683).
  */
-const VIRTUAL_STORE_HINT = "If pnpm reported ERR_PNPM_UNEXPECTED_VIRTUAL_STORE, this checkout's node_modules is " +
-    "symlinked into another checkout's pnpm store (a git worktree, or an A/B harness). Either run " +
-    '`pnpm install` once in that other checkout first, or point this one at its own store:\n' +
-    '  pnpm add -D --config.virtual-store-dir=node_modules/.pnpm <packages>';
-export function installFailureHint(pm) {
+function virtualStoreHint(pmCommand) {
+    return ("If pnpm reported ERR_PNPM_UNEXPECTED_VIRTUAL_STORE, this checkout's node_modules is " +
+        "symlinked into another checkout's pnpm store (a git worktree, or an A/B harness). Either run " +
+        `\`${pmCommand} install\` once in that other checkout first, or point this one at its own store:\n` +
+        `  ${pmCommand} add -D --config.virtual-store-dir=node_modules/.pnpm <packages>`);
+}
+/**
+ * `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 function installFailureHint(pm, pmCommand = pm) {
     if (pm !== PackageManager.PNPM) {
         return `If the version was refused, install the SDK yourself. ${REGISTRY_HINT}`;
     }
     return ('If pnpm reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, its minimumReleaseAge setting is holding ' +
         'this release back. Either wait out the window, or allow these packages explicitly:\n' +
-        '  pnpm config set minimumReleaseAgeExclude "@reticlehq/*"\n' +
+        `  ${pmCommand} config set minimumReleaseAgeExclude "@reticlehq/*"\n` +
         'Do NOT drop the version pin — unpinned, pnpm installs an older SDK against a newer daemon, and ' +
-        `that mismatch surfaces as a -32000 with nothing naming a version.\n${VIRTUAL_STORE_HINT}\n${REGISTRY_HINT}`);
+        `that mismatch surfaces as a -32000 with nothing naming a version.\n${virtualStoreHint(pmCommand)}\n${REGISTRY_HINT}`);
 }

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

@@ -6,7 +6,8 @@
  * a different cost and a different sentence to say afterwards.
  */
 import { PackageManager } from '../detect/detect.js';
-export interface InstallRetry {
+import type { InitIo } from '../run-types.js';
+interface InstallRetry {
     command: string;
     args: string[];
     note: string;
@@ -18,4 +19,19 @@ export interface InstallRetry {
  * pnpm, yarn and bun would reject an unknown argument — turning one failed install into two, with
  * 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 declare function installRetries(pm: PackageManager, pinned: readonly string[], unpinned: readonly string[], sdkVersion: string | undefined, 
+/**
+ * The prefix that actually invokes `pm` on this machine — `pm` itself, or `corepack ${pm}` on a
+ * corepack-only machine (see `preflight.ts`, #1149). A retry that spawned the bare binary here,
+ * after the first attempt already went through the resolved prefix, would fail with the same
+ * ENOENT the resolution exists to avoid — on the one machine shape that needs a retry to reach a
+ * working install at all. Defaults to `pm` for callers that never went through preflight.
+ */
+pmCommand?: string): InstallRetry[];
+export declare function quarantineNote(command: string): string;
+/** Why the dependency install failed, when that can be read; undefined keeps the generic text. */
+export declare function explainInstallFailure(io: Pick<InitIo, 'capture'>, packageManager: PackageManager, exec: {
+    command: string;
+    args: readonly string[];
+}, display: string): string | undefined;
+export {};

package/dist/diagnose/install-retries.js

@@ -50,14 +50,61 @@ function unpinnedRetryNote(version, pm) {
  * pnpm, yarn and bun would reject an unknown argument — turning one failed install into two, with
  * the second failure blaming a flag the user never asked for.
  */
-export function installRetries(pm, pinned, unpinned, sdkVersion) {
+export function installRetries(pm, pinned, unpinned, sdkVersion, 
+/**
+ * The prefix that actually invokes `pm` on this machine — `pm` itself, or `corepack ${pm}` on a
+ * corepack-only machine (see `preflight.ts`, #1149). A retry that spawned the bare binary here,
+ * after the first attempt already went through the resolved prefix, would fail with the same
+ * ENOENT the resolution exists to avoid — on the one machine shape that needs a retry to reach a
+ * working install at all. Defaults to `pm` for callers that never went through preflight.
+ */
+pmCommand = pm) {
     return [
         // Peers first: concedes only peer resolution and KEEPS the version pin.
         ...(pm === PackageManager.NPM
-            ? [{ ...installCommandParts(pm, pinned, [LEGACY_PEER_DEPS]), note: LEGACY_PEER_NOTE }]
+            ? [
+                {
+                    ...installCommandParts(pm, pinned, [LEGACY_PEER_DEPS], pmCommand),
+                    note: LEGACY_PEER_NOTE,
+                },
+            ]
             : []),
         // Unpinned, last. pnpm resolves the newest MATURE version there, which is how a project with a
         // release-age hold gets a working install instead of no install.
-        { ...installCommandParts(pm, unpinned), note: unpinnedRetryNote(sdkVersion, pm) },
+        {
+            ...installCommandParts(pm, unpinned, [], pmCommand),
+            note: unpinnedRetryNote(sdkVersion, pm),
+        },
     ];
 }
+/**
+ * Yarn Berry refusing a release for being too new, told as what it is.
+ *
+ * Yarn 4 quarantines versions younger than its `npmMinimalAgeGate`, and answers an exact pin with
+ * `All versions satisfying "<v>" are quarantined`. A Reticle release is exactly that young on the
+ * day a user installs it. `init` printed "run manually: yarn add -D …", which fails the same way,
+ * and the runtime then booted the app and blamed the dev server for an SDK that was never installed.
+ *
+ * `exec` inherits stdio so the install's progress is live, which also means its text never reaches
+ * us. So on a Yarn failure the pinned command is run once more, quietly, to read why — a quarantine
+ * is refused at resolution, before anything is fetched, so the second run costs well under a
+ * second. Every other failure keeps the generic fallback.
+ */
+/** Yarn's own wording, and the environment variable that is its one-shot override. */
+const QUARANTINED = /are quarantined/;
+const AGE_GATE_ENV = 'YARN_NPM_MINIMAL_AGE_GATE';
+export function quarantineNote(command) {
+    return ("Yarn refused the release: it is younger than Yarn's `npmMinimalAgeGate`, so every matching " +
+        'version is quarantined ("are quarantined" above) and running the same command by hand fails ' +
+        'the same way. Nothing was wired, so there is no app to start yet. Either wait until the ' +
+        'release is older than the gate, or lift the gate for this one install and re-run init:\n\n' +
+        `  ${AGE_GATE_ENV}=0 ${command}\n\n` +
+        `  (PowerShell: $env:${AGE_GATE_ENV}=0; ${command})`);
+}
+/** Why the dependency install failed, when that can be read; undefined keeps the generic text. */
+export function explainInstallFailure(io, packageManager, exec, display) {
+    if (PackageManager.YARN !== packageManager || io.capture === undefined)
+        return undefined;
+    const { output } = io.capture(exec.command, exec.args);
+    return QUARANTINED.test(output) ? quarantineNote(display) : undefined;
+}

package/dist/diagnose/terminal-wrap.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Setup output, laid out for the person reading it in a terminal.
+ *
+ * Setup's sentences are written one per line and were printed as they are, so a paragraph ran off
+ * the right edge and the terminal broke it mid-word, or they were broken by hand at a width that
+ * matched nobody's window. This wraps at the reader's real width instead, keeping each line's indent
+ * and hanging continuation lines under a list marker, so a numbered step still reads as one step.
+ *
+ * Commands are never wrapped: a command split across two lines is one nobody can paste. And output
+ * that is not going to a terminal — an agent reading a pipe — is left exactly as written.
+ */
+/** The width to wrap at, or undefined when stdout is not a terminal. */
+export declare function terminalWidth(stream?: {
+    isTTY?: boolean;
+    columns?: number;
+}): number | undefined;
+/** `text` wrapped line by line to `width`; unchanged when `width` is undefined. */
+export declare function wrapForTerminal(text: string, width: number | undefined): string;

package/dist/diagnose/terminal-wrap.js

@@ -0,0 +1,63 @@
+/**
+ * Setup output, laid out for the person reading it in a terminal.
+ *
+ * Setup's sentences are written one per line and were printed as they are, so a paragraph ran off
+ * the right edge and the terminal broke it mid-word, or they were broken by hand at a width that
+ * matched nobody's window. This wraps at the reader's real width instead, keeping each line's indent
+ * and hanging continuation lines under a list marker, so a numbered step still reads as one step.
+ *
+ * Commands are never wrapped: a command split across two lines is one nobody can paste. And output
+ * that is not going to a terminal — an agent reading a pipe — is left exactly as written.
+ */
+/** Narrow enough to read, wide enough that a step is not ten lines tall. */
+const MAX_WIDTH = 100;
+const MIN_WIDTH = 40;
+/** A line a reader runs rather than reads. */
+const COMMAND = /^\s*(?:\$ |npx |npm |pnpm |yarn |bun |reticle |curl |cd |export |import )/;
+/** What a continuation line hangs under: `1. `, `- `, `• `, `✓ `, `⚠ `, `why: `, `[✓] `. */
+const MARKER = /^(\s*)(\d+\.\s+|[-•✓⚠]\s+|why:\s+|\[.\]\s+)?/u;
+/** The width to wrap at, or undefined when stdout is not a terminal. */
+export function terminalWidth(stream = process.stdout) {
+    if (true !== stream.isTTY || stream.columns === undefined)
+        return undefined;
+    return Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, stream.columns - 1));
+}
+function wrapLine(line, width) {
+    if (line.length <= width || COMMAND.test(line))
+        return line;
+    const match = MARKER.exec(line);
+    const lead = match?.[0] ?? '';
+    const hang = ' '.repeat(lead.length);
+    const words = line
+        .slice(lead.length)
+        .split(' ')
+        .filter((w) => w.length > 0);
+    // A path or URL wider than the window cannot be kept whole by wrapping, and breaking the words
+    // around it only strands its label on a line of its own. The terminal's own wrap does better.
+    if (words.some((w) => hang.length + w.length > width))
+        return line;
+    const out = [];
+    let current = lead;
+    let prefix = lead;
+    for (const word of words) {
+        if (current.length > prefix.length && current.length + 1 + word.length > width) {
+            out.push(current);
+            prefix = hang;
+            current = hang + word;
+        }
+        else {
+            current = current.length > prefix.length ? `${current} ${word}` : current + word;
+        }
+    }
+    out.push(current);
+    return out.join('\n');
+}
+/** `text` wrapped line by line to `width`; unchanged when `width` is undefined. */
+export function wrapForTerminal(text, width) {
+    if (width === undefined)
+        return text;
+    return text
+        .split('\n')
+        .map((line) => wrapLine(line, width))
+        .join('\n');
+}

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

@@ -19,6 +19,8 @@ export { runInit, resolveLockfiles, type InitIo, type InitOptions, type InitResu
  */
 export { windowsShellArg } from './register/windows-quote.js';
 export { buildNodeIo, probeCli } from './node-io.js';
+export { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
+export { FEEDBACK_HINT } from './diagnose/closing-hint.js';
 export { type InitHost, SILENT_HOST } from './host.js';
 export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
 export { InitFailure } from './diagnose/init-failure.js';
@@ -26,11 +28,14 @@ export { NodePlatform } from './detect/platform.js';
 export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './detect/dev-server-ports.js';
 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 { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
 export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { desktopLaunch, type DesktopLaunch } from './detect/dev-script.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 { webCspOptionsFor } from './diagnose/csp-step.js';
 export { reticleConfigContent } from './patch/snippets.js';
 /**
  * MCP registration, for a caller that has no project.
@@ -41,5 +46,5 @@ export { reticleConfigContent } from './patch/snippets.js';
  * here", and the two would disagree the first time a client was added to one of them.
  */
 export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
-export { claudeAddCommand, claudeAvailableProbe, claudeExistsProbe, } from './register/mcp.js';
+export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, } from './register/mcp.js';
 export { detectMcpClients, type DetectedClient } from './register/detect-clients.js';

package/dist/index.js

@@ -19,6 +19,8 @@ export { runInit, resolveLockfiles, } from './run.js';
  */
 export { windowsShellArg } from './register/windows-quote.js';
 export { buildNodeIo, probeCli } from './node-io.js';
+export { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
+export { FEEDBACK_HINT } from './diagnose/closing-hint.js';
 export { SILENT_HOST } from './host.js';
 export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
 export { InitFailure } from './diagnose/init-failure.js';
@@ -26,11 +28,14 @@ export { NodePlatform } from './detect/platform.js';
 export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './detect/dev-server-ports.js';
 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 { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
 export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { desktopLaunch } from './detect/dev-script.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 { webCspOptionsFor } from './diagnose/csp-step.js';
 export { reticleConfigContent } from './patch/snippets.js';
 /**
  * MCP registration, for a caller that has no project.
@@ -45,5 +50,5 @@ export { claudeAddCommand,
 // The two probes `run.ts` uses to decide about Claude Code. Exported because `reticle setup mcp`
 // asks the same question and had no way to ask it: Claude Code keeps no config file, so the
 // file-reading detector cannot see it, and the installer silently skipped the commonest client.
-claudeAvailableProbe, claudeExistsProbe, } from './register/mcp.js';
+claudeAvailableProbe, claudeHasReticle, } from './register/mcp.js';
 export { detectMcpClients } from './register/detect-clients.js';

package/dist/no-package-json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `init` in a directory with no package.json, once the workspace redirect has found no app below it.
+ *
+ * Its own module because it is its own flow: nothing here detects a framework, plans steps or runs a
+ * package manager. It scopes the project on disk, then either WRITES the connect snippet into a
+ * static page it can see whole, or prints the snippet for the stack it recognised (Streamlit,
+ * Django, several pages) and stops.
+ */
+import type { InitIo, InitOptions, InitResult } from './run-types.js';
+export declare function initWithoutPackageJson(options: InitOptions, io: InitIo): InitResult;

package/dist/no-package-json.js

@@ -0,0 +1,121 @@
+/**
+ * `init` in a directory with no package.json, once the workspace redirect has found no app below it.
+ *
+ * Its own module because it is its own flow: nothing here detects a framework, plans steps or runs a
+ * package manager. It scopes the project on disk, then either WRITES the connect snippet into a
+ * static page it can see whole, or prints the snippet for the stack it recognised (Streamlit,
+ * Django, several pages) and stops.
+ */
+import { join } from 'node:path';
+import { PackageManager, Framework } from './detect/detect.js';
+import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, noPackageJsonMessage, streamlitSetupMessage, } from './detect/non-js-project.js';
+import { InitFailure } from './diagnose/init-failure.js';
+import { HTML_INDEX_PATH, STATIC_TOKEN_MODULE, staticTokenFiles, withStaticSnippet, } from './patch/static-page.js';
+import { connectArg, connectArgWithToken, djangoMiddlewareSnippet, reticleConfigContent, staticPageSnippet, streamlitPageSnippet, } from './patch/snippets.js';
+import { RETICLE_CONFIG_FILE } from './detect/existing-config.js';
+import { deriveProjectId } from './project/project-id.js';
+import { portMoveDetail, retargetConfigPort, retargetPort } from './plan/port-steps.js';
+import { rememberProjectOnDisk } from './project/remember-project.js';
+const SNIPPET_WRITTEN = `Wrote the dev-only connect snippet into ${HTML_INDEX_PATH}. It runs only when the page is ` +
+    `opened on localhost. This machine’s pairing token is in ${STATIC_TOKEN_MODULE}, which is ` +
+    'gitignored — keep it out of anything you publish, and let each teammate run `reticle init` ' +
+    'for their own.';
+const SNIPPET_ALREADY = `${HTML_INDEX_PATH} already loads the Reticle SDK — nothing to change.`;
+/**
+ * Write the snippet into `index.html`, and hand over to setup as a success.
+ *
+ * This is the path where the snippet is the whole install, proven to connect when pasted. It used to
+ * print the snippet and exit 1 with `no_package_json`, which read to the funnel — and to the person —
+ * as the setup failing on exactly the path that works.
+ */
+function wireStaticPage(options, io, connect) {
+    for (const [path, content] of Object.entries(staticTokenFiles(io.host.pairingToken(), (p) => io.readFile(p)))) {
+        io.writeFile(path, content);
+    }
+    const html = io.readFile(HTML_INDEX_PATH) ?? '';
+    // A page that already connects still has its port compared: the snippet bakes the daemon URL, and
+    // a re-run with a new `--port` that answered "already" left the page dialling the old daemon.
+    const written = withStaticSnippet(html, connect);
+    const moved = null === written ? retargetPort(html, options.port) : null;
+    const patched = written ?? moved?.code ?? null;
+    if (null !== patched)
+        io.writeFile(HTML_INDEX_PATH, patched);
+    io.print(null !== written
+        ? SNIPPET_WRITTEN
+        : null !== moved && options.port !== undefined
+            ? `Updated ${HTML_INDEX_PATH}: ${portMoveDetail(moved.from, options.port)}.`
+            : SNIPPET_ALREADY);
+    const outcome = { ok: true, stack: Framework.HTML };
+    if (true !== options.deferOutcome)
+        io.host.reportOutcome(outcome);
+    return {
+        ok: true,
+        applied: null === patched ? 0 : 1,
+        manual: 0,
+        // Setup takes it from here: with `--url` it opens the page and waits for the session, which is
+        // the only proof that matters; without one it says the page has no dev server to start.
+        context: { appDir: options.cwd, framework: Framework.HTML, packageManager: PackageManager.NPM },
+        ...(true === options.deferOutcome ? { outcome } : {}),
+    };
+}
+export function initWithoutPackageJson(options, io) {
+    const streamlit = detectStreamlitProject((file) => io.readFile(file), io.rootFiles());
+    // Asked only when Streamlit already said no, so the two can never both claim the page.
+    const django = !streamlit && detectDjangoProject((file) => io.exists(join(options.cwd, file)), io.rootFiles());
+    // Scope the project on disk before anything else, so the daemon can serve this page.
+    //
+    // This path used to print and exit, leaving no `.reticle.json` at all — and the reporter who
+    // asked for the Django path had to hand-write one alongside the middleware. Without it the
+    // daemon has no config in its own directory, refuses the page's dial, and every downstream
+    // symptom points somewhere other than the cause (see #685). The projectId derivation already
+    // handles the no-package case: it falls back to the root folder name, fingerprinted by the
+    // absolute path so two checkouts stay distinct.
+    //
+    // Written only when absent. A config a user or an earlier run already placed here is theirs.
+    const nonJsProjectId = deriveProjectId(undefined, io.cwd());
+    const writeConfig = () => {
+        // Except its port. A re-run with a new `--port` starts the daemon there, and a config still
+        // naming the old one sends the agent to a daemon that is no longer running.
+        const existingConfig = io.readFile(RETICLE_CONFIG_FILE);
+        const moved = null === existingConfig ? null : retargetConfigPort(existingConfig, options.port);
+        if (null !== moved && options.port !== undefined) {
+            io.writeFile(RETICLE_CONFIG_FILE, moved.code);
+            io.print(`Updated ${RETICLE_CONFIG_FILE}: ${portMoveDetail(moved.from, options.port)}.`);
+        }
+        if (io.exists(RETICLE_CONFIG_FILE))
+            return;
+        io.writeFile(RETICLE_CONFIG_FILE, reticleConfigContent(Framework.HTML, options.port, nonJsProjectId, io.host.installSource()));
+        rememberProjectOnDisk(io, nonJsProjectId, io.cwd(), Date.now());
+        io.print(`Wrote ${RETICLE_CONFIG_FILE} (project "${nonJsProjectId}").`);
+    };
+    const connect = connectArgWithToken(options.port, nonJsProjectId, io.host.pairingToken());
+    // One page at the root is a page we can see whole. Several, or none, is a choice that is not ours.
+    if (!streamlit && !django && io.exists(HTML_INDEX_PATH)) {
+        writeConfig();
+        // Without the token: the page is the deployable artifact, so the token goes beside it instead.
+        return wireStaticPage(options, io, connectArg(options.port, nonJsProjectId));
+    }
+    io.print(
+    // Two genuinely different situations used to share one sentence: a JS developer in the wrong
+    // directory, and a project that is not JavaScript at all. The second reads the old wording as
+    // a path problem and goes looking for a directory that cannot exist — reported from a
+    // Streamlit app, where the search continued into hunting for a browser bundle to inject by
+    // hand before the real answer surfaced.
+    streamlit
+        ? streamlitSetupMessage()
+        : django
+            ? djangoSetupMessage()
+            : noPackageJsonMessage((file) => io.exists(join(options.cwd, file)), io.rootFiles()));
+    writeConfig();
+    // The message says "add the snippet below". Print the snippet, or the message is the same broken
+    // promise in the other direction.
+    io.print(streamlit
+        ? streamlitPageSnippet(connect)
+        : django
+            ? djangoMiddlewareSnippet(connect)
+            : staticPageSnippet(connect));
+    // The onboarding funnel had NO instrumentation, so a setup that died here was indistinguishable
+    // from someone who never ran the command — the two failure modes with the most different fixes.
+    io.host.reportOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
+    return { ok: false, applied: 0, manual: 0 };
+}

package/dist/node-io.d.ts

@@ -8,11 +8,15 @@ import type { InitHost } from './host.js';
 /**
  * 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