@reticlehq/init 3.6.0 → 3.8.0

package/dist/no-package-json.js

@@ -6,11 +6,14 @@
  * static page it can see whole, or prints the snippet for the stack it recognised (Streamlit,
  * Django, several pages) and stops.
  */
+import { dirname, join } from 'node:path';
 import { PackageManager, Framework } from './detect/detect.js';
+import { PACKAGE_JSON } from './detect/workspace-apps.js';
 import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, NoPackageJsonCase, noPackageJsonAnswer, 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 { connectArg, reticleConfigContent, staticPageSnippetWithLocalToken, } from './patch/snippets.js';
+import { djangoMiddlewareSnippet, pythonConnectArg, streamlitPageSnippet, } from './patch/python-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';
@@ -19,8 +22,37 @@ const SNIPPET_WRITTEN = `Wrote the dev-only connect snippet into ${HTML_INDEX_PA
     `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 TOKEN_MODULE_WRITTEN = `This machine’s pairing token is in ${STATIC_TOKEN_MODULE}, which is gitignored. Serve it beside ` +
+    'the page: the snippet imports it. Keep it out of anything you publish.';
 const SNIPPET_ALREADY = `${HTML_INDEX_PATH} already loads the Reticle SDK — nothing to change.`;
-const DRY_RUN_PAIRING_TOKEN = 'DRY_RUN_TOKEN_NOT_FOR_USE';
+/** How far up `init` looks for the app it was run inside. The same bound as the workspace walk. */
+const MAX_ANCESTOR_DEPTH = 8;
+const HOME_FOLDER = 'This is your home folder, not a project. Go to the folder of your app (the one with its ' +
+    'package.json) and run `reticle init` there.';
+const insideApp = (dir) => `No package.json here, but this folder is inside the app at ${dir}. Run init from the app's ` +
+    `folder:\n  cd "${dir}" && reticle init`;
+/**
+ * The wrong-directory answer when the right directory can be named.
+ *
+ * Discovery looks DOWN for the app. Run from `src/` of that app, it found nothing and said "run
+ * `reticle init` from your app's directory" with no path, to a person one folder inside it. The
+ * walk up stops at the home folder: a package.json in the home folder is an accident, not an app.
+ */
+function namedDirectory(io) {
+    const home = io.homeDir();
+    let dir = io.cwd();
+    if (dir === home)
+        return HOME_FOLDER;
+    for (let depth = 0; depth < MAX_ANCESTOR_DEPTH; depth++) {
+        const parent = dirname(dir);
+        if (parent === dir || parent === home)
+            return undefined;
+        if (null !== io.readFile(join(parent, PACKAGE_JSON)))
+            return insideApp(parent);
+        dir = parent;
+    }
+    return undefined;
+}
 /**
  * Write the snippet into `index.html`, and hand over to setup as a success.
  *
@@ -28,10 +60,24 @@ const DRY_RUN_PAIRING_TOKEN = 'DRY_RUN_TOKEN_NOT_FOR_USE';
  * 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) {
+/** Write the gitignored token module and its ignore line, only where they change. */
+function writeTokenModule(io) {
     for (const [path, content] of Object.entries(staticTokenFiles(io.host.pairingToken(), (p) => io.readFile(p)))) {
         io.writeFile(path, content);
     }
+}
+/** The snippet for this kind of project. Each one reads the token at run time. */
+function printedSnippet(streamlit, django, connect) {
+    if (streamlit) {
+        return streamlitPageSnippet(pythonConnectArg(connect));
+    }
+    if (django) {
+        return djangoMiddlewareSnippet(pythonConnectArg(connect));
+    }
+    return staticPageSnippetWithLocalToken(connect);
+}
+function wireStaticPage(options, io, connect) {
+    writeTokenModule(io);
     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.
@@ -71,7 +117,7 @@ export function initWithoutPackageJson(options, io) {
     // wrong, then printed a script-tag snippet under a message that asks for none (#1366).
     const answer = noPackageJsonAnswer(existsHere, io.rootFiles());
     if (!streamlit && !django && answer.kind === NoPackageJsonCase.WRONG_DIRECTORY) {
-        io.print(answer.message);
+        io.print(namedDirectory(io) ?? answer.message);
         if (!options.dryRun)
             io.host.reportOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
         return { ok: false, applied: 0, manual: 0 };
@@ -89,7 +135,7 @@ export function initWithoutPackageJson(options, io) {
     const nonJsProjectId = deriveProjectId(undefined, io.cwd());
     const writeConfig = () => {
         if (options.dryRun) {
-            io.print('Dry run: no files written; the snippet uses a placeholder pairing token.');
+            io.print('Dry run: no files written.');
             return;
         }
         // Except its port. A re-run with a new `--port` starts the daemon there, and a config still
@@ -106,16 +152,17 @@ export function initWithoutPackageJson(options, io) {
         rememberProjectOnDisk(io, nonJsProjectId, io.cwd(), Date.now());
         io.print(`Wrote ${RETICLE_CONFIG_FILE} (project "${nonJsProjectId}").`);
     };
-    const connect = connectArgWithToken(options.port, nonJsProjectId, options.dryRun ? DRY_RUN_PAIRING_TOKEN : io.host.pairingToken());
+    // No snippet below holds the token. A printed token stays in terminal history and transcripts.
+    const connect = connectArg(options.port, nonJsProjectId);
     // 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();
         if (options.dryRun) {
-            io.print(staticPageSnippet(connect));
+            io.print(staticPageSnippetWithLocalToken(connect));
             return { ok: true, applied: 0, manual: 0 };
         }
-        // Without the token: the page is the deployable artifact, so the token goes beside it instead.
-        return wireStaticPage(options, io, connectArg(options.port, nonJsProjectId));
+        // The page is the deployable artifact, so the token goes beside it instead.
+        return wireStaticPage(options, io, connect);
     }
     io.print(
     // Two genuinely different situations used to share one sentence: a JS developer in the wrong
@@ -127,11 +174,12 @@ export function initWithoutPackageJson(options, io) {
     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));
+    io.print(printedSnippet(streamlit, django, connect));
+    // The page snippet imports the token from this module. Python reads the token file instead.
+    if (!streamlit && !django && !options.dryRun) {
+        writeTokenModule(io);
+        io.print(TOKEN_MODULE_WRITTEN);
+    }
     // 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.
     if (!options.dryRun)

package/dist/node-io.d.ts

@@ -8,7 +8,7 @@ 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`, `corepack`, and the Claude CLI —
+ * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude and Codex CLIs —
  * 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

package/dist/node-io.js

@@ -4,7 +4,7 @@
  * command, not the MCP stdio transport.
  */
 import { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, lstatSync, } from 'node:fs';
 import { NodePlatform } from './detect/platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
@@ -24,7 +24,7 @@ function shellSafe(args) {
 /**
  * Every program `init` is ever allowed to run.
  *
- * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude CLI —
+ * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude and Codex CLIs —
  * 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
@@ -46,6 +46,7 @@ export const RUNNABLE_COMMANDS = [
     'npx',
     'corepack',
     'claude',
+    'codex',
 ];
 /** The command, proven to be one of `RUNNABLE_COMMANDS` — never the caller's string. */
 function runnable(command) {
@@ -158,6 +159,14 @@ export function buildNodeIo(cwd, host, output = {}) {
                 return [];
             }
         },
+        isSymlink(rel) {
+            try {
+                return lstatSync(abs(rel)).isSymbolicLink();
+            }
+            catch {
+                return false;
+            }
+        },
         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.

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

@@ -5,6 +5,7 @@
  * half-edit. These must not be left manual: both edits fail silently when skipped, and one of them
  * is JSX.
  */
+import type { InitIo } from '../run-types.js';
 import { type SourcePatch } from './patch-kind.js';
 /** Where the generated connect component goes, and how the mount file should import it. */
 interface ReticleDevLocation {
@@ -14,18 +15,17 @@ interface ReticleDevLocation {
     importSpecifier: string;
 }
 /**
- * Decide where the connect component lives, from the file that will mount it.
+ * Whether Next treats the project as TypeScript: Next's own rule, not the package list (#1527).
  *
- * Two things this gets wrong if hardcoded, both of which broke real apps:
+ * Next reads a `tsconfig.json`, and a `.ts`/`.tsx` source file. It does not read a `typescript`
+ * dependency, which a JavaScript app often has for editor types or ESLint. Choosing `.tsx` from that
+ * dependency wrote a TypeScript file into a `jsconfig.json` app. On the next `next dev`, Next then
+ * generated a `tsconfig.json`, ignored the `jsconfig.json` from then on, and every `@/` import broke.
  *
- * - **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.
+ * `mountPath` is the layout or `_app` file the component is mounted from, or `null` when none was
+ * found. Its extension is the project's own answer for the directory being written into.
  */
+export declare function nextUsesTypeScript(mountPath: string | null, hasTsconfig: boolean): boolean;
 export declare function reticleDevLocation(mountPath: string, typescript: boolean): ReticleDevLocation;
 export declare function patchNextConfig(source: string, sourceMapping?: boolean): SourcePatch;
 /**
@@ -41,9 +41,45 @@ export declare function patchRootLayout(source: string): SourcePatch;
  * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
  */
 export declare const NEXT_LAYOUT_CANDIDATES: string[];
+/**
+ * What `findRouteGroupRootLayout` found: the layout to mount into, with the other group root layouts
+ * that do not mount `<ReticleDev />`, or the ones it could not choose between.
+ */
+export type RouteGroupLayouts = {
+    path: string;
+    unmounted: string[];
+} | {
+    candidates: string[];
+};
+type ListingIo = Pick<InitIo, 'listDirs' | 'listFiles' | 'readFile'>;
+/**
+ * The root layout of an App Router app with no top-level `app/layout.*`: its root layouts then live
+ * in route groups (`app/(site)/layout.tsx`), one per group, which Next documents as "multiple root
+ * layouts" (#1538). `null` when the app has none, so the Pages Router candidates are still asked.
+ *
+ * One layout is chosen, because a step patches one file: a group layout that already mounts
+ * `<ReticleDev />` (so the patch reports it already wired), else the one group that renders `/`,
+ * else the only group layout there is. Several and none of those is returned as candidates, so the
+ * manual step can name them rather than say there is no root layout.
+ *
+ * Each group root layout renders its own routes, so the routes under the others render without
+ * `<ReticleDev />`. Those that do not mount it already come back as `unmounted`, for init to name.
+ */
+export declare function findRouteGroupRootLayout(io: ListingIo): RouteGroupLayouts | null;
 /**
  * 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[];
+/**
+ * The file `<ReticleDev />` is mounted in: the App Router's root layout, then a route-group root
+ * layout (#1538), then the Pages Router's `_app`. `candidates` is set when route groups hold several
+ * root layouts and none could be chosen, so the manual step can name them; `unmounted` names the
+ * other group root layouts when one was chosen, so init can say which routes go without it.
+ */
+export declare function findNextMountFile(io: ListingIo & Pick<InitIo, 'exists'>): {
+    path: string | null;
+    candidates?: string[];
+    unmounted?: string[];
+};
 export {};

package/dist/patch/next-patch.js

@@ -28,6 +28,22 @@ const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
  *   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.
  */
+/** A TypeScript source file, as Next counts one. */
+const TS_SOURCE = /\.tsx?$/;
+/**
+ * Whether Next treats the project as TypeScript: Next's own rule, not the package list (#1527).
+ *
+ * Next reads a `tsconfig.json`, and a `.ts`/`.tsx` source file. It does not read a `typescript`
+ * dependency, which a JavaScript app often has for editor types or ESLint. Choosing `.tsx` from that
+ * dependency wrote a TypeScript file into a `jsconfig.json` app. On the next `next dev`, Next then
+ * generated a `tsconfig.json`, ignored the `jsconfig.json` from then on, and every `@/` import broke.
+ *
+ * `mountPath` is the layout or `_app` file the component is mounted from, or `null` when none was
+ * found. Its extension is the project's own answer for the directory being written into.
+ */
+export function nextUsesTypeScript(mountPath, hasTsconfig) {
+    return hasTsconfig || (null !== mountPath && TS_SOURCE.test(mountPath));
+}
 export function reticleDevLocation(mountPath, typescript) {
     const ext = typescript ? '.tsx' : '.jsx';
     const slash = mountPath.lastIndexOf('/');
@@ -223,6 +239,67 @@ export const NEXT_LAYOUT_CANDIDATES = [
     'src/app/layout.jsx',
     'src/app/layout.js',
 ];
+/** The App Router roots, in the order `NEXT_LAYOUT_CANDIDATES` checks them. */
+const NEXT_APP_DIRS = ['app', 'src/app'];
+const LAYOUT_BASENAMES = ['layout.tsx', 'layout.jsx', 'layout.js'];
+const PAGE_FILE = /^page\.(tsx|ts|jsx|js|mdx)$/;
+/** `(marketing)`: a route group, which organises routes without adding a URL segment. */
+const ROUTE_GROUP = /^\(.+\)$/;
+/** Whether `dir` renders `/`: a page of its own, or one in a route group nested under it. */
+function servesRoot(io, dir) {
+    if (io.listFiles(dir).some((name) => PAGE_FILE.test(name)))
+        return true;
+    return io
+        .listDirs(dir)
+        .filter((name) => ROUTE_GROUP.test(name))
+        .some((name) => servesRoot(io, `${dir}/${name}`));
+}
+/**
+ * The root layout of an App Router app with no top-level `app/layout.*`: its root layouts then live
+ * in route groups (`app/(site)/layout.tsx`), one per group, which Next documents as "multiple root
+ * layouts" (#1538). `null` when the app has none, so the Pages Router candidates are still asked.
+ *
+ * One layout is chosen, because a step patches one file: a group layout that already mounts
+ * `<ReticleDev />` (so the patch reports it already wired), else the one group that renders `/`,
+ * else the only group layout there is. Several and none of those is returned as candidates, so the
+ * manual step can name them rather than say there is no root layout.
+ *
+ * Each group root layout renders its own routes, so the routes under the others render without
+ * `<ReticleDev />`. Those that do not mount it already come back as `unmounted`, for init to name.
+ */
+export function findRouteGroupRootLayout(io) {
+    for (const appDir of NEXT_APP_DIRS) {
+        const layouts = io
+            .listDirs(appDir)
+            .filter((name) => ROUTE_GROUP.test(name))
+            .sort()
+            .flatMap((group) => {
+            const dir = `${appDir}/${group}`;
+            const files = io.listFiles(dir);
+            const layout = LAYOUT_BASENAMES.find((name) => files.includes(name));
+            return layout === undefined ? [] : [{ dir, path: `${dir}/${layout}` }];
+        });
+        if (0 === layouts.length)
+            continue;
+        const mounted = new Set(layouts
+            .filter((l) => true === io.readFile(l.path)?.includes(RETICLE_DEV_COMPONENT))
+            .map((l) => l.path));
+        const chosen = (path) => ({
+            path,
+            unmounted: layouts.map((l) => l.path).filter((p) => p !== path && !mounted.has(p)),
+        });
+        const wired = layouts.find((l) => mounted.has(l.path));
+        if (wired !== undefined)
+            return chosen(wired.path);
+        const root = layouts.filter((l) => servesRoot(io, l.dir));
+        if (1 === root.length && root[0] !== undefined)
+            return chosen(root[0].path);
+        if (1 === layouts.length && layouts[0] !== undefined)
+            return chosen(layouts[0].path);
+        return { candidates: layouts.map((l) => l.path) };
+    }
+    return null;
+}
 /**
  * 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.
@@ -235,3 +312,19 @@ export const NEXT_PAGES_APP_CANDIDATES = [
     'src/pages/_app.jsx',
     'src/pages/_app.js',
 ];
+/**
+ * The file `<ReticleDev />` is mounted in: the App Router's root layout, then a route-group root
+ * layout (#1538), then the Pages Router's `_app`. `candidates` is set when route groups hold several
+ * root layouts and none could be chosen, so the manual step can name them; `unmounted` names the
+ * other group root layouts when one was chosen, so init can say which routes go without it.
+ */
+export function findNextMountFile(io) {
+    const top = NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p));
+    if (top !== undefined)
+        return { path: top };
+    const groups = findRouteGroupRootLayout(io);
+    if (groups !== null && 'path' in groups)
+        return { path: groups.path, unmounted: groups.unmounted };
+    const pagesApp = NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p)) ?? null;
+    return null === groups ? { path: pagesApp } : { path: pagesApp, candidates: groups.candidates };
+}

package/dist/patch/nuxt-snippets.js

@@ -130,6 +130,6 @@ and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which i
 
 The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
 source file:line all work in Vue. What you do not get is React component identity, which is the only
-thing the React adapter adds. The install gate scaffolds a Nuxt app on every release and requires a session, so this wiring
+thing the React adapter adds. The install gate scaffolds a Nuxt app whenever the install path changes and requires a session, so this wiring
 is proven; if something does not work, please open an issue.`;
 }

package/dist/patch/prettier-ignore.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keep Reticle's local state out of the project's Prettier check.
+ *
+ * `reticle init` runs in the user's project, and every drive writes JSON under `.reticle/`
+ * (impact.json, runs/, intent/). A project's `prettier --check .` fails on those files —
+ * not just for missing trailing newlines, but because Prettier's JSON formatting differs from
+ * `JSON.stringify` (e.g. short arrays stay on one line). The nested `.reticle/.gitignore` does
+ * not help: Prettier only reads the ignore file of the directory it runs from.
+ *
+ * So when the project uses Prettier, `init` adds `.reticle/` to the project's `.prettierignore`.
+ * This is the root-cause fix: it covers every file Reticle writes, present and future,
+ * regardless of how each one is serialized.
+ *
+ * Idempotent: re-running `init` never duplicates the entry. Never removes anything the user
+ * had — it only appends the one line when it is absent.
+ */
+export declare const PRETTIERIGNORE_PATH = ".prettierignore";
+/** The entry `init` manages in the project's `.prettierignore`. */
+export declare const RETICLE_IGNORE_ENTRY = ".reticle/";
+/**
+ * True when the `.prettierignore` content already excludes `.reticle/`.
+ *
+ * Matches the entry with or without trailing slash, ignoring comments and blank lines —
+ * a user who wrote `.reticle` by hand has already solved this; we must not add a duplicate.
+ */
+export declare function ignoresReticle(content: string): boolean;
+/**
+ * The `.prettierignore` content after `init` ensures `.reticle/` is excluded.
+ *
+ * - No existing file: create one with the managed header and the entry.
+ * - Existing file without the entry: append the entry (keeping a single blank line separator).
+ * - Existing file with the entry: returned unchanged (caller treats this as ALREADY).
+ */
+export declare function withReticleIgnored(existing: string | null): string;

package/dist/patch/prettier-ignore.js

@@ -0,0 +1,49 @@
+/**
+ * Keep Reticle's local state out of the project's Prettier check.
+ *
+ * `reticle init` runs in the user's project, and every drive writes JSON under `.reticle/`
+ * (impact.json, runs/, intent/). A project's `prettier --check .` fails on those files —
+ * not just for missing trailing newlines, but because Prettier's JSON formatting differs from
+ * `JSON.stringify` (e.g. short arrays stay on one line). The nested `.reticle/.gitignore` does
+ * not help: Prettier only reads the ignore file of the directory it runs from.
+ *
+ * So when the project uses Prettier, `init` adds `.reticle/` to the project's `.prettierignore`.
+ * This is the root-cause fix: it covers every file Reticle writes, present and future,
+ * regardless of how each one is serialized.
+ *
+ * Idempotent: re-running `init` never duplicates the entry. Never removes anything the user
+ * had — it only appends the one line when it is absent.
+ */
+export const PRETTIERIGNORE_PATH = '.prettierignore';
+/** The entry `init` manages in the project's `.prettierignore`. */
+export const RETICLE_IGNORE_ENTRY = '.reticle/';
+/**
+ * True when the `.prettierignore` content already excludes `.reticle/`.
+ *
+ * Matches the entry with or without trailing slash, ignoring comments and blank lines —
+ * a user who wrote `.reticle` by hand has already solved this; we must not add a duplicate.
+ */
+export function ignoresReticle(content) {
+    return content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => '' !== line && !line.startsWith('#'))
+        .some((line) => RETICLE_IGNORE_ENTRY === line || '.reticle' === line);
+}
+const MANAGED_HEADER = "# Added by `reticle init`: Reticle's local state (.reticle/) must not break `prettier --check`.";
+/**
+ * The `.prettierignore` content after `init` ensures `.reticle/` is excluded.
+ *
+ * - No existing file: create one with the managed header and the entry.
+ * - Existing file without the entry: append the entry (keeping a single blank line separator).
+ * - Existing file with the entry: returned unchanged (caller treats this as ALREADY).
+ */
+export function withReticleIgnored(existing) {
+    if (null === existing) {
+        return `${MANAGED_HEADER}\n${RETICLE_IGNORE_ENTRY}\n`;
+    }
+    if (ignoresReticle(existing))
+        return existing;
+    const trimmed = existing.replace(/\n+$/, '');
+    return `${trimmed}\n\n${MANAGED_HEADER}\n${RETICLE_IGNORE_ENTRY}\n`;
+}

package/dist/patch/python-snippets.d.ts

@@ -0,0 +1,22 @@
+/** The connect literal for a Python snippet: the token is substituted when the page is served. */
+export declare function pythonConnectArg(connectArgLiteral: string): string;
+/**
+ * Streamlit has no served HTML template, and `st.markdown` inserts script markup without executing
+ * it. Streamlit 1.63 added an explicit JavaScript boundary to `st.html`; use a classic script there
+ * so it can dynamically import the ESM SDK in the app document. A head marker makes reruns
+ * idempotent and is removed after an import failure so the next rerun can retry.
+ */
+export declare function streamlitPageSnippet(connectArgLiteral: string): string;
+/**
+ * DEBUG-only middleware that injects Reticle into every Django-rendered page.
+ *
+ * Django serves templates, so the generic script tag has no single home: an app has many templates
+ * and a base template it may not have. Middleware has exactly one, runs for every page, and is the
+ * idiomatic Django answer — a field reporter arrived at this same shape by hand after `init` printed
+ * a script tag and exited 1, and had to write the middleware and `.reticle.json` themselves.
+ *
+ * Guarded on `settings.DEBUG` so it can never reach production, and on the response being HTML so it
+ * does not corrupt a JSON API response or a file download. Injected before `</body>` rather than in
+ * `<head>`, so the SDK sees a parsed document.
+ */
+export declare function djangoMiddlewareSnippet(connectArgLiteral: string): string;

package/dist/patch/python-snippets.js

@@ -0,0 +1,113 @@
+/**
+ * The connect snippets for Python apps (Streamlit, Django), which have no JS build to inline the
+ * token. Each one reads this machine's pairing token from the token file when the page is served,
+ * so the token is never in `init` output or in the pasted code.
+ */
+import { CDN_SDK_URL, withTokenExpression } from './snippets.js';
+/** Where the Python snippets put the token, until the page is served. */
+const PYTHON_TOKEN_PLACEHOLDER = '__RETICLE_PAIRING_TOKEN__';
+/** Python that reads this machine's pairing token at run time, the way the daemon finds it. */
+const PYTHON_TOKEN_READER = `def _reticle_pairing_token():
+    folder = os.environ.get("RETICLE_PAIRING_TOKEN_DIR") or str(Path.home() / ".reticle")
+    try:
+        return (Path(folder) / "pairing-token").read_text().strip()
+    except OSError:
+        return ""`;
+/** The connect literal for a Python snippet: the token is substituted when the page is served. */
+export function pythonConnectArg(connectArgLiteral) {
+    return withTokenExpression(connectArgLiteral, PYTHON_TOKEN_PLACEHOLDER);
+}
+/**
+ * Streamlit has no served HTML template, and `st.markdown` inserts script markup without executing
+ * it. Streamlit 1.63 added an explicit JavaScript boundary to `st.html`; use a classic script there
+ * so it can dynamically import the ESM SDK in the app document. A head marker makes reruns
+ * idempotent and is removed after an import failure so the next rerun can retry.
+ */
+export function streamlitPageSnippet(connectArgLiteral) {
+    return `import json
+import os
+from pathlib import Path
+
+import streamlit as st
+
+
+${PYTHON_TOKEN_READER}
+
+
+st.html(
+    """
+    <script>
+      (() => {
+        if (document.getElementById('reticle-streamlit-connect')) return;
+        const marker = document.createElement('meta');
+        marker.id = 'reticle-streamlit-connect';
+        document.head.appendChild(marker);
+        void import('${CDN_SDK_URL}')
+          .then(({ reticle }) => reticle.connect(${connectArgLiteral}))
+          .catch((error) => {
+            marker.remove();
+            throw error;
+          });
+      })();
+    </script>
+    """.replace("${PYTHON_TOKEN_PLACEHOLDER}", json.dumps(_reticle_pairing_token())),
+    unsafe_allow_javascript=True,
+)`;
+}
+/**
+ * DEBUG-only middleware that injects Reticle into every Django-rendered page.
+ *
+ * Django serves templates, so the generic script tag has no single home: an app has many templates
+ * and a base template it may not have. Middleware has exactly one, runs for every page, and is the
+ * idiomatic Django answer — a field reporter arrived at this same shape by hand after `init` printed
+ * a script tag and exited 1, and had to write the middleware and `.reticle.json` themselves.
+ *
+ * Guarded on `settings.DEBUG` so it can never reach production, and on the response being HTML so it
+ * does not corrupt a JSON API response or a file download. Injected before `</body>` rather than in
+ * `<head>`, so the SDK sees a parsed document.
+ */
+export function djangoMiddlewareSnippet(connectArgLiteral) {
+    return `# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
+#   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
+import json
+import os
+from pathlib import Path
+
+from django.conf import settings
+
+_SNIPPET = """<script type="module">
+  import { reticle } from '${CDN_SDK_URL}';
+  reticle.connect(${connectArgLiteral});
+</script>"""
+
+
+${PYTHON_TOKEN_READER}
+
+
+class ReticleDevMiddleware:
+    """Inject the Reticle SDK into HTML responses during development only."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if not settings.DEBUG:
+            return response
+        if "text/html" not in response.get("Content-Type", ""):
+            return response
+        # Streaming responses have no .content to rewrite; leave them alone.
+        if getattr(response, "streaming", False):
+            return response
+        body = response.content.decode(response.charset)
+        if "</body>" not in body:
+            return response
+        snippet = _SNIPPET.replace("${PYTHON_TOKEN_PLACEHOLDER}", json.dumps(_reticle_pairing_token()))
+        response.content = body.replace("</body>", snippet + "</body>", 1).encode(
+            response.charset
+        )
+        if response.has_header("Content-Length"):
+            response["Content-Length"] = str(len(response.content))
+        return response
+`;
+}