@reticlehq/init 2.14.0

package/dist/next-patch.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure, conservative patchers for the two files a Next app needed edited BY HAND: `next.config.*`
+ * (wrap the export in `withReticle`) and `app/layout.tsx` (mount `<ReticleDev />`). Same contract as
+ * the Vite patcher — recognise the obvious shape, bail to `manual` on anything ambiguous, never
+ * half-edit. Leaving these manual is why Next connected 0% of the time: both edits are silent when
+ * skipped, and one of them is JSX.
+ */
+import { type SourcePatch } from './patch-kind.js';
+/** Where the generated connect component goes, and how the mount file should import it. */
+interface ReticleDevLocation {
+    /** Project-relative path to write. */
+    path: string;
+    /** What the mount file (`app/layout.*` or `pages/_app.*`) should import. */
+    importSpecifier: string;
+}
+/**
+ * Decide where the connect component lives, from the file that will mount it.
+ *
+ * Two things this gets wrong if hardcoded, both of which broke real apps:
+ *
+ * - **Pages Router routes on presence.** EVERY file under `pages/` is a route, so a component
+ *   dropped there has no default export: `/reticle-dev` 500s and `next build` fails. It has to go
+ *   somewhere that is not a route directory. App Router routes on FILENAME (`page`/`layout`/
+ *   `route`), so an extra file beside the layout is inert and can stay there.
+ * - **The extension is not cosmetic.** A `.tsx` file in a JavaScript project makes Next auto-install
+ *   TypeScript on the next `next dev` — and on Next 13 that takes its require-hook down with it, so
+ *   the dev server never starts. The install then looks like it broke the app, because it did.
+ */
+export declare function reticleDevLocation(mountPath: string, typescript: boolean): ReticleDevLocation;
+export declare function patchNextConfig(source: string, sourceMapping?: boolean): SourcePatch;
+/**
+ * Pages Router has no root layout to mount into — `app/layout.tsx` does not exist — so the connect
+ * rides in `pages/_app` instead, wrapped in a fragment alongside the page. Without this, `init`
+ * wrote `app/reticle-dev.tsx` into a directory the app does not have and nothing ever connected,
+ * with no error to say so.
+ */
+export declare function patchPagesApp(source: string, importSpecifier?: string): SourcePatch;
+export declare function patchRootLayout(source: string): SourcePatch;
+/**
+ * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
+ * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
+ */
+export declare const NEXT_LAYOUT_CANDIDATES: string[];
+/**
+ * Pages Router mount points, checked only when there is no App Router layout. A Pages app has no
+ * `app/` directory at all, so writing the component there produced a file nothing imported.
+ */
+export declare const NEXT_PAGES_APP_CANDIDATES: string[];
+export {};

package/dist/next-patch.js

@@ -0,0 +1,237 @@
+/**
+ * Pure, conservative patchers for the two files a Next app needed edited BY HAND: `next.config.*`
+ * (wrap the export in `withReticle`) and `app/layout.tsx` (mount `<ReticleDev />`). Same contract as
+ * the Vite patcher — recognise the obvious shape, bail to `manual` on anything ambiguous, never
+ * half-edit. Leaving these manual is why Next connected 0% of the time: both edits are silent when
+ * skipped, and one of them is JSX.
+ */
+import { PatchKind } from './patch-kind.js';
+const RETICLE_NEXT_PACKAGE = '@reticlehq/next';
+const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
+const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
+const RETICLE_DEV_COMPONENT = 'ReticleDev';
+const RETICLE_DEV_BASENAME = 'reticle-dev';
+/** Default import specifier: the component sits beside the file importing it (App Router). */
+const RETICLE_DEV_SIBLING = `./${RETICLE_DEV_BASENAME}`;
+const reticleDevImport = (specifier) => `import { ${RETICLE_DEV_COMPONENT} } from '${specifier}';`;
+const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
+/**
+ * Decide where the connect component lives, from the file that will mount it.
+ *
+ * Two things this gets wrong if hardcoded, both of which broke real apps:
+ *
+ * - **Pages Router routes on presence.** EVERY file under `pages/` is a route, so a component
+ *   dropped there has no default export: `/reticle-dev` 500s and `next build` fails. It has to go
+ *   somewhere that is not a route directory. App Router routes on FILENAME (`page`/`layout`/
+ *   `route`), so an extra file beside the layout is inert and can stay there.
+ * - **The extension is not cosmetic.** A `.tsx` file in a JavaScript project makes Next auto-install
+ *   TypeScript on the next `next dev` — and on Next 13 that takes its require-hook down with it, so
+ *   the dev server never starts. The install then looks like it broke the app, because it did.
+ */
+export function reticleDevLocation(mountPath, typescript) {
+    const ext = typescript ? '.tsx' : '.jsx';
+    const slash = mountPath.lastIndexOf('/');
+    const dir = -1 === slash ? '' : mountPath.slice(0, slash);
+    const isPagesRouter = /(^|\/)pages$/.test(dir);
+    if (!isPagesRouter) {
+        return {
+            path: `${'' === dir ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
+            importSpecifier: RETICLE_DEV_SIBLING,
+        };
+    }
+    // Siblings of `pages/`, so `src/pages/_app.js` → `src/components/…` and `pages/_app.js` → `components/…`.
+    const parent = dir.slice(0, Math.max(0, dir.length - 'pages'.length));
+    return {
+        path: `${parent}components/${RETICLE_DEV_BASENAME}${ext}`,
+        importSpecifier: `../components/${RETICLE_DEV_BASENAME}`,
+    };
+}
+/** The dev-guarded mount. Production strips it — `process.env.NODE_ENV` is inlined at build time. */
+const RETICLE_DEV_MOUNT = `{process.env.NODE_ENV === 'development' ? <${RETICLE_DEV_COMPONENT} /> : null}`;
+/**
+ * `export default ` / `module.exports = ` at the START of a line — the head of the assignment, not
+ * the whole statement. Where the exported expression ENDS is decided by `expressionEnd` below.
+ *
+ * These used to be `/…([\s\S]+?);?\s*$/`, which reads as "the expression, lazily". It is not: with
+ * no `m` flag the `$` is end-of-FILE and the trailing `;?\s*` is satisfiable only there, so the
+ * capture always ran to the last non-blank character of the file. Every config whose export was not
+ * the final statement got everything after it swallowed into the wrap. On a config exporting
+ * conditionally that produced an unbalanced paren — a syntax error, so `next dev` exited 1 while
+ * `init` reported the step as ✓ and the only symptom was "dev server never served".
+ */
+const ESM_DEFAULT_HEAD = /^[ \t]*export[ \t]+default[ \t]+/gm;
+const CJS_EXPORT_HEAD = /^[ \t]*module\.exports[ \t]*=[ \t]*/gm;
+/** The opening `<body ...>` tag, whose first child is where the mount goes. */
+const BODY_OPEN_TAG = /<body(\s[^>]*)?>/g;
+const NO_EXPORT_REASON = "couldn't find an `export default` or `module.exports` to wrap";
+const NO_BODY_REASON = "couldn't find a single <body> tag to mount <ReticleDev /> inside";
+/** Bracket pairs that keep an expression open. A `;` at depth 0 is what ends it. */
+const OPENERS = '([{';
+const CLOSERS = ')]}';
+const LINE_COMMENT = '//';
+const BLOCK_COMMENT_OPEN = '/*';
+const BLOCK_COMMENT_CLOSE = '*/';
+const QUOTES = '\'"`';
+/**
+ * Index just past the exported expression that starts at `from` — the `;` that closes it, or end of
+ * file. Tracks bracket depth so a multi-line object or a nested call ends in the right place, and
+ * skips strings and comments so a `;` or a brace inside one cannot end it early.
+ *
+ * Deliberately a scanner and not a parser: `next.config.*` is arbitrary JS and this file's contract
+ * is to recognise the obvious shape or bail. It only has to be right about where ONE expression
+ * stops, and wrong is caught by the caller bailing to manual, never by a half-edit.
+ */
+function expressionEnd(source, from) {
+    let depth = 0;
+    for (let i = from; i < source.length; i++) {
+        const ch = source[i] ?? '';
+        const pair = source.slice(i, i + 2);
+        if (pair === LINE_COMMENT) {
+            const nl = source.indexOf('\n', i);
+            if (-1 === nl)
+                return source.length;
+            i = nl;
+            continue;
+        }
+        if (pair === BLOCK_COMMENT_OPEN) {
+            const close = source.indexOf(BLOCK_COMMENT_CLOSE, i + 2);
+            i = -1 === close ? source.length : close + 1;
+            continue;
+        }
+        if (QUOTES.includes(ch)) {
+            for (i++; i < source.length; i++) {
+                if ('\\' === source[i])
+                    i++;
+                else if (source[i] === ch)
+                    break;
+            }
+            continue;
+        }
+        if (OPENERS.includes(ch))
+            depth++;
+        else if (CLOSERS.includes(ch)) {
+            // A closer at depth 0 belongs to an enclosing block, so the expression ended before it.
+            if (0 === depth)
+                return i;
+            depth--;
+        }
+        else if (';' === ch && 0 === depth)
+            return i;
+    }
+    return source.length;
+}
+/** Every top-level export assignment in the file, in source order. */
+function exportSites(source, head) {
+    const sites = [];
+    for (const match of source.matchAll(head)) {
+        if (match.index === undefined)
+            continue;
+        const start = match.index + match[0].length;
+        sites.push({ start, end: expressionEnd(source, start) });
+    }
+    return sites;
+}
+/**
+ * Wrap every listed expression in `withReticle(...)`, leaving every other byte of the file alone.
+ *
+ * All of them, not just the first: a config can export CONDITIONALLY — Sentry-wrapped in one branch,
+ * plain in the other — and which branch runs is an environment variable's business, not ours.
+ * Wrapping each assignment is correct whichever one executes, and it is what turns that shape from a
+ * manual step (an app that boots and never connects) into a working install.
+ *
+ * Applied back-to-front so each splice leaves the earlier offsets valid.
+ */
+function wrapAll(source, sites, secondArg) {
+    let out = source;
+    for (const site of [...sites].sort((a, b) => b.start - a.start)) {
+        out = `${out.slice(0, site.start)}withReticle(${out.slice(site.start, site.end)}${secondArg})${out.slice(site.end)}`;
+    }
+    return out;
+}
+/**
+ * The second argument to `withReticle`, or nothing at all.
+ *
+ * A Next app has no plugin call to carry `sourceMapping: false`, so the only place to say it is the
+ * config wrap itself. Omitted entirely when the stamp stays on, because an install that appends
+ * `, {}` to every config it touches is a diff against the user's file for no reason.
+ */
+function withReticleOptions(sourceMapping) {
+    return sourceMapping ? '' : ', { sourceMapping: false }';
+}
+export function patchNextConfig(source, sourceMapping = true) {
+    if (source.includes(RETICLE_NEXT_PACKAGE))
+        return { kind: PatchKind.ALREADY };
+    const options = withReticleOptions(sourceMapping);
+    const esm = exportSites(source, ESM_DEFAULT_HEAD);
+    if (esm.length > 0) {
+        return {
+            kind: PatchKind.APPLY,
+            code: `${NEXT_CONFIG_IMPORT}\n${wrapAll(source, esm, options)}`,
+        };
+    }
+    const cjs = exportSites(source, CJS_EXPORT_HEAD);
+    if (cjs.length > 0) {
+        return {
+            kind: PatchKind.APPLY,
+            code: `${NEXT_CONFIG_REQUIRE}\n${wrapAll(source, cjs, options)}`,
+        };
+    }
+    return { kind: PatchKind.MANUAL, reason: NO_EXPORT_REASON };
+}
+/** `<Component {...pageProps} />` — the one element every `pages/_app` renders. */
+const PAGES_APP_COMPONENT = /<Component\b[^>]*\/>/g;
+const NO_PAGES_COMPONENT_REASON = "couldn't find a single <Component {...pageProps} /> to wrap in pages/_app";
+/**
+ * Pages Router has no root layout to mount into — `app/layout.tsx` does not exist — so the connect
+ * rides in `pages/_app` instead, wrapped in a fragment alongside the page. Without this, `init`
+ * wrote `app/reticle-dev.tsx` into a directory the app does not have and nothing ever connected,
+ * with no error to say so.
+ */
+export function patchPagesApp(source, importSpecifier = RETICLE_DEV_SIBLING) {
+    if (source.includes(RETICLE_DEV_COMPONENT))
+        return { kind: PatchKind.ALREADY };
+    const matches = [...source.matchAll(PAGES_APP_COMPONENT)];
+    const match = 1 === matches.length ? matches[0] : undefined;
+    if (match?.index === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_PAGES_COMPONENT_REASON };
+    const wrapped = `<>${RETICLE_DEV_MOUNT}${match[0]}</>`;
+    const code = source.slice(0, match.index) + wrapped + source.slice(match.index + match[0].length);
+    return { kind: PatchKind.APPLY, code: `${reticleDevImport(importSpecifier)}\n${code}` };
+}
+export function patchRootLayout(source) {
+    if (source.includes(RETICLE_DEV_COMPONENT))
+        return { kind: PatchKind.ALREADY };
+    const tags = [...source.matchAll(BODY_OPEN_TAG)];
+    // Exactly one <body> or we cannot tell which one actually renders — and mounting into the wrong
+    // one is the same silent no-connect as not mounting at all.
+    const tag = 1 === tags.length ? tags[0] : undefined;
+    if (tag?.index === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_BODY_REASON };
+    const insertAt = tag.index + tag[0].length;
+    const mounted = `${source.slice(0, insertAt)}${RETICLE_DEV_MOUNT}${source.slice(insertAt)}`;
+    return { kind: PatchKind.APPLY, code: `${RETICLE_DEV_IMPORT}\n${mounted}` };
+}
+/**
+ * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
+ * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
+ */
+export const NEXT_LAYOUT_CANDIDATES = [
+    'app/layout.tsx',
+    'app/layout.jsx',
+    'app/layout.js',
+    'src/app/layout.tsx',
+    'src/app/layout.jsx',
+    'src/app/layout.js',
+];
+/**
+ * Pages Router mount points, checked only when there is no App Router layout. A Pages app has no
+ * `app/` directory at all, so writing the component there produced a file nothing imported.
+ */
+export const NEXT_PAGES_APP_CANDIDATES = [
+    'pages/_app.tsx',
+    'pages/_app.jsx',
+    'pages/_app.js',
+    'src/pages/_app.tsx',
+    'src/pages/_app.jsx',
+    'src/pages/_app.js',
+];

package/dist/node-io.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The real (Node filesystem) implementation of `InitIo`. Kept separate from the pure runner so
+ * `runInit` stays testable with an in-memory IO. Prints to stdout — `init` is a one-shot CLI
+ * command, not the MCP stdio transport.
+ */
+import type { InitIo } from './run.js';
+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 `shellOpt`: 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.
+ *
+ * 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 declare const RUNNABLE_COMMANDS: readonly string[];
+export declare function buildNodeIo(cwd: string, host: InitHost): InitIo;

package/dist/node-io.js

@@ -0,0 +1,150 @@
+/**
+ * The real (Node filesystem) implementation of `InitIo`. Kept separate from the pure runner so
+ * `runInit` stays testable with an in-memory IO. Prints to stdout — `init` is a one-shot CLI
+ * command, not the MCP stdio transport.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, } from 'node:fs';
+import { NodePlatform } from './platform.js';
+import { join, dirname, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { windowsShellArg } from './windows-quote.js';
+/**
+ * `shell: true` ONLY where it earns its keep.
+ *
+ * It exists so package-manager shims (`pnpm.cmd`, `npx.cmd`) resolve on Windows. On POSIX it buys
+ * nothing and costs correctness: under a shell, arguments are re-parsed, so a path containing a
+ * space — `/Users/ada/My Projects/app` — silently becomes two arguments and registration fails with
+ * no error anyone can read.
+ */
+function shellOpt() {
+    return NodePlatform.WINDOWS === process.platform ? { shell: true } : {};
+}
+/**
+ * Under a shell, quote what the shell would otherwise split or interpret. Windows only, where
+ * `shell: true` is required (see shellOpt). The rule itself lives in windows-quote.ts as a pure
+ * function so it can be tested on every platform — keeping it inside this branch is why it was
+ * wrong for as long as it was.
+ */
+function shellSafe(args) {
+    if (process.platform !== NodePlatform.WINDOWS)
+        return [...args];
+    return args.map(windowsShellArg);
+}
+/**
+ * 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 `shellOpt`: 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.
+ *
+ * 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'];
+/** 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);
+    if (undefined === found) {
+        throw new Error(`init refused to run ${JSON.stringify(command)}: not one of ${RUNNABLE_COMMANDS.join(', ')}.`);
+    }
+    return found;
+}
+export function buildNodeIo(cwd, host) {
+    // Project-relative by default; absolute paths (e.g. ~/.cursor/mcp.json) pass through unchanged.
+    const abs = (rel) => (isAbsolute(rel) ? rel : join(cwd, rel));
+    return {
+        readFile(rel) {
+            const path = abs(rel);
+            if (!existsSync(path))
+                return null;
+            return readFileSync(path, 'utf8');
+        },
+        writeFile(rel, content) {
+            const path = abs(rel);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, content, 'utf8');
+        },
+        exists(rel) {
+            return existsSync(abs(rel));
+        },
+        homeDir() {
+            return homedir();
+        },
+        cwd() {
+            return cwd;
+        },
+        rootFiles() {
+            return readdirSync(cwd).filter((name) => {
+                try {
+                    return statSync(join(cwd, name)).isFile();
+                }
+                catch {
+                    return false;
+                }
+            });
+        },
+        listDirs(rel) {
+            const path = abs(rel);
+            if (!existsSync(path))
+                return [];
+            try {
+                return readdirSync(path).filter((name) => statSync(join(path, name)).isDirectory());
+            }
+            catch {
+                return [];
+            }
+        },
+        listFiles(rel) {
+            const path = abs(rel);
+            if (!existsSync(path))
+                return [];
+            try {
+                return readdirSync(path).filter((name) => !statSync(join(path, name)).isDirectory());
+            }
+            catch {
+                return [];
+            }
+        },
+        scoped(rel) {
+            // The host travels with the re-rooted IO: a monorepo redirect re-enters `runInit` through
+            // this, and an untraced, unreported inner run is the half of init that actually did the work.
+            return buildNodeIo(abs(rel), host);
+        },
+        exec(command, args) {
+            // Inherit stdio so the install's own progress is visible to the user.
+            const result = spawnSync(runnable(command), shellSafe(args), {
+                cwd,
+                stdio: 'inherit',
+                ...shellOpt(),
+            });
+            return 0 === result.status;
+        },
+        /** One access check, rather than discovering it as an EACCES stack four phases later. */
+        canWrite() {
+            try {
+                accessSync(cwd, constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        probe(command, args) {
+            // Quiet yes/no check (CLI availability, existing registration). Never throws.
+            const result = spawnSync(runnable(command), shellSafe(args), {
+                cwd,
+                stdio: 'ignore',
+                ...shellOpt(),
+            });
+            return 0 === result.status;
+        },
+        print(line) {
+            process.stdout.write(`${line}\n`);
+        },
+        host,
+    };
+}

package/dist/non-js-project.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** Whether the no-package project is specifically a Streamlit app. */
+export declare function detectStreamlitProject(readFile: (file: string) => string | null, rootFiles: readonly string[]): boolean;
+/** The Streamlit-specific explanation printed immediately before its generated helper. */
+export declare function streamlitSetupMessage(): string;
+/**
+ * Whether the no-package project is specifically a Django app.
+ *
+ * `manage.py` is the marker every Django project has and nothing else does, and it is already in
+ * ECOSYSTEM_MARKERS as `Python (Django)` — this asks the narrower question so the setup message can
+ * be Django's rather than Python's in general.
+ *
+ * Confirmed by `settings.py` alongside it where possible, because a bare `manage.py` in a repo root
+ * that also holds the real app deeper down should not claim more than it knows.
+ */
+export declare function detectDjangoProject(exists: (file: string) => boolean, rootDirectories?: readonly string[]): boolean;
+/** The Django-specific explanation printed immediately before its generated middleware. */
+export declare function djangoSetupMessage(): string;
+/** The ecosystem this directory looks like, or undefined when nothing says. */
+export declare function detectNonJsEcosystem(exists: (file: string) => boolean): string | undefined;
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export declare function noPackageJsonMessage(exists: (file: string) => boolean): string;

package/dist/non-js-project.js

@@ -0,0 +1,137 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** Marker files that identify an ecosystem, and what to call it. */
+const ECOSYSTEM_MARKERS = [
+    ['requirements.txt', 'Python'],
+    ['pyproject.toml', 'Python'],
+    ['Pipfile', 'Python'],
+    ['setup.py', 'Python'],
+    ['manage.py', 'Python (Django)'],
+    ['Gemfile', 'Ruby'],
+    ['go.mod', 'Go'],
+    ['composer.json', 'PHP'],
+    ['Cargo.toml', 'Rust'],
+    ['pom.xml', 'Java'],
+    ['build.gradle', 'Java'],
+    ['mix.exs', 'Elixir'],
+    // Not like the others. Every ecosystem above can grow a JS front end that Reticle instruments
+    // perfectly well, so their message ends with a lead. Flutter web paints into a canvas, and there
+    // is no DOM behind it at any path, so the honest answer is a named refusal.
+    ['pubspec.yaml', 'Flutter'],
+];
+/** The one ecosystem where no directory, front end or flag could ever help. */
+const FLUTTER = 'Flutter';
+const STREAMLIT_DEPENDENCY_FILES = ['requirements.txt', 'pyproject.toml', 'Pipfile'];
+const STREAMLIT_DEPENDENCY = /(?:^|[\n,"'])\s*streamlit(?:\[[^\]\n]*\])?\s*(?:[<>=!~;]|$)/im;
+const STREAMLIT_IMPORT = /(?:^|\n)\s*(?:import\s+streamlit(?:\s+as\s+\w+)?|from\s+streamlit(?:\.|\s+import))/m;
+/** Whether the no-package project is specifically a Streamlit app. */
+export function detectStreamlitProject(readFile, rootFiles) {
+    for (const file of STREAMLIT_DEPENDENCY_FILES) {
+        const source = readFile(file);
+        if (null !== source && STREAMLIT_DEPENDENCY.test(source))
+            return true;
+    }
+    for (const file of rootFiles.filter((name) => name.endsWith('.py'))) {
+        const source = readFile(file);
+        if (null !== source && STREAMLIT_IMPORT.test(source))
+            return true;
+    }
+    return false;
+}
+/** The Streamlit-specific explanation printed immediately before its generated helper. */
+export function streamlitSetupMessage() {
+    return ('This is a Streamlit project. Streamlit owns the top-level HTML document, so there is no ' +
+        'served template for the generic script tag, and scripts passed to `st.markdown` do not run. ' +
+        'Use Streamlit 1.63 or newer and add the `st.html` helper below during development. It runs ' +
+        'Reticle in the app document and guards against duplicate connections across reruns.');
+}
+/**
+ * Whether the no-package project is specifically a Django app.
+ *
+ * `manage.py` is the marker every Django project has and nothing else does, and it is already in
+ * ECOSYSTEM_MARKERS as `Python (Django)` — this asks the narrower question so the setup message can
+ * be Django's rather than Python's in general.
+ *
+ * Confirmed by `settings.py` alongside it where possible, because a bare `manage.py` in a repo root
+ * that also holds the real app deeper down should not claim more than it knows.
+ */
+export function detectDjangoProject(exists, rootDirectories = []) {
+    if (!exists('manage.py'))
+        return false;
+    if (exists('settings.py'))
+        return true;
+    return rootDirectories.some((dir) => exists(`${dir}/settings.py`));
+}
+/** The Django-specific explanation printed immediately before its generated middleware. */
+export function djangoSetupMessage() {
+    return ('This is a Django project. Django renders templates server-side, so there is no JS build to ' +
+        'import the SDK from and no single template to paste a script tag into — an app has many, and ' +
+        'may not have a base one. The middleware below is the Django-shaped answer: it runs for every ' +
+        'page, injects Reticle into HTML responses only, and is guarded on `settings.DEBUG` so it can ' +
+        'never reach production. Add it to MIDDLEWARE, start your server as usual, and the page will ' +
+        'dial the daemon on load. ' +
+        'If this project ALSO has a JS front end with its own package.json, running `reticle init` ' +
+        'there instead gives you source mapping and framework state as well: point at it with ' +
+        '`--app <dir>`.');
+}
+/** The ecosystem this directory looks like, or undefined when nothing says. */
+export function detectNonJsEcosystem(exists) {
+    for (const [marker, name] of ECOSYSTEM_MARKERS) {
+        if (exists(marker))
+            return name;
+    }
+    return undefined;
+}
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export function noPackageJsonMessage(exists) {
+    const ecosystem = detectNonJsEcosystem(exists);
+    if (ecosystem === undefined) {
+        return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
+            "your app's directory, or from a repo root that contains it.");
+    }
+    if (ecosystem === FLUTTER) {
+        // An agent on a Flutter workspace asked us to "support Flutter, or clearly identify it as
+        // unsupported during init". The second is the truthful one, and saying it by name in one line
+        // is the difference between an agent that stops and an agent that spends an hour looking for
+        // the package.json we told it was missing.
+        return ('This is a Flutter project. Reticle cannot instrument it, and no directory or flag will ' +
+            'change that: Reticle reads the DOM of a running page, and Flutter web paints its entire UI ' +
+            'into a single canvas element with no DOM behind it. Nothing here is missing or misconfigured. ' +
+            'If this repo also contains an ordinary web app with its own package.json, run `reticle init` ' +
+            'inside that directory instead.');
+    }
+    return (`This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
+        'directory beneath it. That is not a blocker: Reticle needs its SDK loaded by the page, not ' +
+        'built by npm, and a page with no build step can load it from a URL. ' +
+        // The old message ended at "there is no directory you could run this from that would change
+        // that", which read as a refusal and was acted on as one — agents went looking for a bundler,
+        // or for a standalone build to inject by hand, or gave up and used a different tool. The
+        // capability was there the whole time; only the sentence was missing. Proven end to end on a
+        // page served by `python3 -m http.server` before this line was written.
+        'Add the script-tag snippet below to a template you only serve in development, then reload the ' +
+        'page. ' +
+        'If this project ALSO has a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
+        'its own package.json), running `reticle init` there instead gives you source mapping and ' +
+        'framework state as well: point at it with `--app <dir>`.');
+}

package/dist/nuxt-patch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wiring Reticle into a Nuxt app: the config gets the token `define`, the plugin gets written.
+ *
+ * Nuxt owns its own Vite instance and renders its own HTML, so there is no `vite.config` to patch
+ * and no `index.html` to inject into — the same position Astro is in, and it takes the same config
+ * patch (see `vite-owning-config.ts`). The half Nuxt does differently is the connect itself: Nuxt's
+ * own idiom is a `.client` plugin it auto-registers, not a `<script>` in a layout.
+ *
+ * The config patch is not optional and not cosmetic. The bridge requires a pairing token even on
+ * localhost, nothing in a browser can read the file it lives in, and Nuxt loads no plugin of ours
+ * that could inject it — so a plugin written beside an unpatched config is an app that dials the
+ * daemon and is refused, with one line in a console nobody had open. That is why the two halves are
+ * planned atomically.
+ */
+import type { SourcePatch } from './patch-kind.js';
+/** The config filenames Nuxt itself accepts, in the order `init` should prefer them. */
+export declare const NUXT_CONFIG_CANDIDATES: string[];
+export declare function patchNuxtConfig(source: string): SourcePatch;