@reticlehq/init 3.7.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/patch/next-patch.d.ts

@@ -15,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;
 /**
@@ -42,9 +41,13 @@ 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, or the ones it could not choose between. */
+/**
+ * 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[];
 };
@@ -58,6 +61,9 @@ type ListingIo = Pick<InitIo, 'listDirs' | 'listFiles' | 'readFile'>;
  * `<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;
 /**
@@ -68,10 +74,12 @@ 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.
+ * 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('/');
@@ -247,6 +263,9 @@ function servesRoot(io, dir) {
  * `<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) {
@@ -262,14 +281,21 @@ export function findRouteGroupRootLayout(io) {
         });
         if (0 === layouts.length)
             continue;
-        const wired = layouts.find((l) => true === io.readFile(l.path)?.includes(RETICLE_DEV_COMPONENT));
+        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 { path: wired.path };
+            return chosen(wired.path);
         const root = layouts.filter((l) => servesRoot(io, l.dir));
         if (1 === root.length && root[0] !== undefined)
-            return { path: root[0].path };
+            return chosen(root[0].path);
         if (1 === layouts.length && layouts[0] !== undefined)
-            return { path: layouts[0].path };
+            return chosen(layouts[0].path);
         return { candidates: layouts.map((l) => l.path) };
     }
     return null;
@@ -289,7 +315,8 @@ export const NEXT_PAGES_APP_CANDIDATES = [
 /**
  * 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.
+ * 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));
@@ -297,7 +324,7 @@ export function findNextMountFile(io) {
         return { path: top };
     const groups = findRouteGroupRootLayout(io);
     if (groups !== null && 'path' in groups)
-        return { path: groups.path };
+        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/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
+`;
+}

package/dist/patch/snippets.d.ts

@@ -35,19 +35,16 @@ export declare const CDN_SDK_URL: string;
  * (so the app is identifiable across port changes). Empty string only when neither applies.
  */
 export declare function connectArg(port: number | undefined, projectId?: string): string;
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export declare const LOCAL_TOKEN_MODULE = "reticle.local.js";
 /**
- * The same literal, with the pairing token folded in.
+ * A connect literal with `token` set to a JS expression, never to the token itself.
  *
- * The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
- * it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); the hand-wired
- * paths have none, so `init` inlines the literal it already read. Without it the bridge closes the
- * socket with AUTH_FAILED and no session ever appears: see Bridge's hello handler.
- *
- * An empty token is omitted rather than emitted as `token: ''`. A daemon that could not write to
- * $HOME runs without auth and trusts loopback, and an empty string would fail the comparison against
- * one that does hold a token.
+ * The token used to be a literal in every printed snippet. It then stayed in terminal history,
+ * in agent transcripts, and in every file the snippet was pasted into. The snippets now read it at
+ * run time: from the gitignored module, or, in Python, from the token file.
  */
-export declare function connectArgWithToken(port: number | undefined, projectId: string | undefined, pairingToken: string | undefined): string;
+export declare function withTokenExpression(connectArgLiteral: string, tokenExpression: string): string;
 export declare function usesReactKit(uiLibrary: UiLibrary, framework?: Framework): boolean;
 /**
  * Which SDK package the GENERATED code should import, and whether `install()` applies.
@@ -152,26 +149,8 @@ export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root lay
  * opposite sign, so the two share a builder rather than a copy.
  */
 export declare function staticPageSnippet(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;
+/** The same snippet, with the token read from the gitignored module beside the page. */
+export declare function staticPageSnippetWithLocalToken(connectArgLiteral: string): string;
 export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string, uiLibrary?: UiLibrary): string;
 export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
 export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";