@reticlehq/server 2.13.1 → 2.14.0

package/dist/init/slash-command.d.ts

@@ -1,27 +0,0 @@
-/**
- * The `/reticle` slash command — the entry point the docs have been promising and nothing created.
- *
- * SKILL.md tells the user "Type `/reticle` anytime to verify the app" in three places, and `init`
- * never wrote the file that makes it exist. So the one obvious way in was a command that silently did
- * nothing in every tool. Claude Code and Cursor both read custom commands from a markdown file per
- * command; the body is the prompt the agent receives.
- *
- * Deliberately SCOPED to one flow. A user installing Reticle has an existing app with many flows, and
- * an agent told to "verify the app" will try to instrument all of them — slow, noisy, and nothing to
- * see for minutes. One flow, driven where the human can watch it, is the whole difference between a
- * two-minute first impression and an afternoon.
- */
-/** Claude Code reads project commands from `.claude/commands/<name>.md`. */
-export declare const CLAUDE_COMMAND_PATH = ".claude/commands/reticle.md";
-/** Cursor reads them from `.cursor/commands/<name>.md`. */
-export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
-/**
- * The frontmatter line that marks a command file as OURS.
- *
- * A stale command has to be refreshable — a file frozen at whatever release created it can never be
- * improved for anyone who already ran init — but the path is one a human may have claimed for their
- * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
- * are told apart.
- */
-export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
-export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";

package/dist/init/slash-command.js

@@ -1,132 +0,0 @@
-/**
- * The `/reticle` slash command — the entry point the docs have been promising and nothing created.
- *
- * SKILL.md tells the user "Type `/reticle` anytime to verify the app" in three places, and `init`
- * never wrote the file that makes it exist. So the one obvious way in was a command that silently did
- * nothing in every tool. Claude Code and Cursor both read custom commands from a markdown file per
- * command; the body is the prompt the agent receives.
- *
- * Deliberately SCOPED to one flow. A user installing Reticle has an existing app with many flows, and
- * an agent told to "verify the app" will try to instrument all of them — slow, noisy, and nothing to
- * see for minutes. One flow, driven where the human can watch it, is the whole difference between a
- * two-minute first impression and an afternoon.
- */
-import { DEV_SERVER_POLICY } from './agent-rules.js';
-/** Claude Code reads project commands from `.claude/commands/<name>.md`. */
-export const CLAUDE_COMMAND_PATH = '.claude/commands/reticle.md';
-/** Cursor reads them from `.cursor/commands/<name>.md`. */
-export const CURSOR_COMMAND_PATH = '.cursor/commands/reticle.md';
-/**
- * The frontmatter line that marks a command file as OURS.
- *
- * A stale command has to be refreshable — a file frozen at whatever release created it can never be
- * improved for anyone who already ran init — but the path is one a human may have claimed for their
- * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
- * are told apart.
- */
-export const SLASH_COMMAND_SIGNATURE = 'description: Verify this app in the browser with Reticle';
-export const SLASH_COMMAND_BODY = `---
-${SLASH_COMMAND_SIGNATURE} — drive one real flow and report what happened.
----
-
-Verify this running app with Reticle. Drive it; do not read the code and guess.
-
-## Step 0 — is anything connected?
-
-Call \`reticle_sessions\` first.
-
-**A session is listed?** Go to "Pick ONE flow".
-
-**No session?** Setup is not finished, and stopping to ask the user to run something is not an
-answer. Every step below is yours to do without them. Work these in order, and say which one you are
-on, one line each:
-
-0. **Is Reticle even wired into this project?** \`cat .reticle.json\`. If it is not there, this
-   project was never set up: run \`npx @reticlehq/server@latest init\`,
-   fix every \`⚠\` and \`ℹ\` it prints, and carry on. Do not ask first, and do not ask which
-   framework or port — both come out of the repo you are sitting in.
-
-1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to
-   step 2 — the cause is then almost always that the SDK never loaded in the page, not a missing
-   server, so do not tell the user to start one they are already running. If nothing is listening:
-
-${DEV_SERVER_POLICY}
-
-2. **Is a page open on it?** Do not ask the user to open a browser — open it:
-
-   \`\`\`bash
-   npx @reticlehq/server open <the url the dev server is serving>
-   \`\`\`
-
-   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a
-   machine with no browser to open, take a tab Reticle owns instead:
-   \`reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })\`.
-
-Then, once something is serving the app and a page is on it:
-
-3. **Is the SDK actually in the app?** Read the app's entry file (\`src/main.tsx\`, \`app/layout.tsx\`,
-   \`src/app.vue\`, whatever this project uses). You are looking for an \`import\` from
-   \`@reticlehq/react\` or \`@reticlehq/browser\` and a \`connect()\` call, or the Reticle plugin in
-   \`vite.config.*\`, or \`withReticle\` in \`next.config.*\`. **If it is not there, that is the bug.**
-   Wire it in — see the framework snippets at https://docs.reticle.sh/instrumentation — then restart
-   the dev server and re-check.
-4. **Is the connect guarded on \`hostname === 'localhost'\`?** If so, remove that guard. It is false on
-   any non-localhost dev host, and \`window\` does not exist during SSR, so the guard silently prevents
-   the connect and logs nothing. Use the framework's dev flag instead (\`import.meta.env.DEV\`,
-   \`process.env.NODE_ENV !== 'production'\`, \`import.meta.dev\`).
-5. **Is the dev server serving that entry?** Look in \`reticle_console\`, or in the page you opened in
-   step 2, for a line starting \`[Reticle]\`. That line, or its absence, tells you which side is at
-   fault. Reticle itself never starts a dev server — starting it is your job, under the guards above.
-6. **Do both sides agree on the port?** Run \`npx @reticlehq/server doctor\` and compare the daemon
-   port against the port the page dials.
-
-If you are still stuck after all of those, file it: \`reticle_feedback\` with kind \`gap\`, saying what you
-checked and what you saw. Then tell the user exactly which step is blocked. Do not report the install
-as finished.
-
-## Pick ONE flow
-
-Not the whole app. Pick the single most important flow you can complete in a handful of steps — the
-one a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or
-just changed some code, use that one instead.
-
-State which flow you picked in one line before you start.
-
-## Drive it where the human can see
-
-1. \`reticle_snapshot\` — read the accessibility tree and locate the elements the flow needs. Elements
-   are addressable by role and name; you do **not** need \`data-testid\` to drive them.
-2. Walk the flow with \`reticle_act_and_wait\`, one step at a time. Narrate each step first — the human
-   is watching the page, and the HUD shows what you say.
-3. After each step, check the effect with \`reticle_assert\` — not just that the click dispatched, but
-   that the thing it was supposed to do actually happened.
-4. Finish with \`reticle_console\` and \`reticle_network\` to catch errors the DOM does not show.
-
-**Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** A run that ends on a
-snapshot has proved nothing, however many tools it used.
-
-## Report
-
-- What you drove, step by step, and what each step actually produced.
-- Anything broken, with the \`file:line\` Reticle gave you.
-- If a step could not be verified, say so plainly. "Unknown" is a real answer; a green verdict you
-  cannot back is not.
-
-Do not weaken or skip an assertion to make the run pass — that is a finding, not a fix.
-
-## If the user handed you a license key
-
-Append \`RETICLE_LICENSE_KEY=<key>\` to the project's \`.env\` (create it if absent), make sure \`.env\`
-is in \`.gitignore\`, and confirm with \`npx @reticlehq/server license\`. The CLI folds a project-local
-\`.env\` in on every invocation, so nothing else changes. Never echo the key back, and never put it in
-a commit, a comment, or a feedback report.
-
-## Two things afterwards
-
-- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with
-  \`reticle_feedback\` now, before your context is gone. That report is the only signal that decides
-  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.
-- **If the verification actually succeeded**, add one line for the human: Reticle is open source at
-  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it
-  entirely if the run did not produce a verdict.
-`;

package/dist/init/snippets.d.ts

@@ -1,134 +0,0 @@
-/**
- * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
- * so the runner never inlines free strings.
- */
-import { UiLibrary } from './detect.js';
-import type { FoundStore } from './capabilities.js';
-/**
- * The same literal, with the pairing token folded in.
- *
- * 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.
- */
-export declare function connectArgWithToken(port: number | undefined, projectId: string | undefined, pairingToken: string | undefined): string;
-/**
- * Which SDK package the GENERATED code should import, and whether `install()` applies.
- *
- * This has to agree with `frameworkPackages`, and it did not. That function was changed so a Vue or
- * Svelte app installs `@reticlehq/browser` instead of the React adapter — correctly — while every
- * generated connect snippet still said `import('@reticlehq/react')`. A SvelteKit app would have
- * installed the sensor and then run a hook importing a package that is not there.
- *
- * `install()` is the React adapter's, not the sensor's: `@reticlehq/browser` exports `reticle` and no
- * `install`, so swapping the specifier alone would trade a missing module for a missing export.
- */
-export declare function sdkImport(uiLibrary: UiLibrary): {
-    specifier: string;
-    usesInstall: boolean;
-};
-/** The Vite-config snippet printed when we can't safely auto-patch the config. */
-export declare function viteManual(port: number | undefined, uiLibrary?: UiLibrary): string;
-/** Next.js config wrap — always printed (we never auto-rewrite next.config). */
-export declare function nextConfigManual(configFile: string): string;
-/**
- * The dev-only client component that connects Reticle after hydration.
- *
- * The token is not optional. The bridge requires a pairing token even on localhost, and unlike Vite
- * (where the plugin injects it) a Next app has to carry it through `withReticle`, which publishes it
- * as `NEXT_PUBLIC_RETICLE_TOKEN`. This file used to connect with only a projectId, so every Next
- * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
- */
-export declare function nextReticleDevFile(port: number | undefined, projectId?: string, testids?: readonly string[], stores?: readonly string[], found?: readonly FoundStore[]): string;
-export declare function astroManual(port: number | undefined, projectId?: string, 
-/**
- * A layout file that actually exists, when one does.
- *
- * Reported from the field: on `examples/framework-react` — which has no layout at all, only
- * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
- * layout". Instructions that name a file the project does not have read as a mistake by the
- * reader, and cost them the time it takes to go and confirm it is missing.
- */
-layoutPath?: string): string;
-/**
- * The app-side dev module the Vite plugin imports by convention.
- *
- * `registerCapabilities` tells the agent what it can drive without guessing; `registerStore` is the
- * one that matters most and the one we cannot write for you — detecting that an app depends on
- * zustand is easy, knowing which module exports the store instance is not, and a wrong import here
- * breaks the module everything else hangs off. So the store lines are generated COMMENTED, naming
- * the libraries actually found in package.json, with the exact call to uncomment.
- */
-export declare function viteDevModuleFile(testids: readonly string[], stores: readonly string[], found?: readonly FoundStore[], uiLibrary?: UiLibrary): string;
-/** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
-export declare const VITE_DEV_MODULE_PATH = "src/reticle-dev.ts";
-/** Default root-layout path, used when no layout was found on disk (reporting only). */
-export declare const NEXT_LAYOUT_PATH = "app/layout.tsx";
-/** Mount instruction for the root layout. */
-export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root layout (app/layout.tsx), dev-only:\n\n  import { ReticleDev } from './reticle-dev';\n  // inside <body>:\n  {process.env.NODE_ENV === 'development' ? <ReticleDev /> : null}";
-/**
- * Manual connect guidance for projects without a Vite/Next plugin. Most such projects still use a
- * BUNDLER (CRA, webpack, Parcel, Vue/Svelte CLIs) — for those, the connect goes in the entry MODULE,
- * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
- * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
- */
-/**
- * The whole install, for a page with no build step, as one block a person can paste.
- *
- * Extracted so the `no package.json` exit can print the SAME snippet `htmlManual` offers. That exit
- * is the one every server-rendered app reaches (FastAPI, Flask, Django, Rails, Streamlit), it is
- * where `init` stops, and until now it stopped with an explanation instead of an answer. A message
- * that says "add the snippet below" and then prints no snippet is the same defect wearing the
- * opposite sign, so the two share a builder rather than a copy.
- */
-export declare function staticPageSnippet(connectArgLiteral: string): string;
-export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string): string;
-export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
-export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
-/**
- * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
- * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
- */
-/**
- * Said out loud when the app does not render through React. The SDK is framework-agnostic — DOM,
- * network, console and routing all still work — but `@reticlehq/react` is a React adapter, so
- * component names and source mapping do not, and no CI gate covers this stack. Reporting all-green
- * here is the one thing this project exists not to do.
- */
-export declare function unverifiedUiLibraryNote(library: string): string;
-export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested \u2014 it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.";
-/**
- * Dev-only client hook that connects Reticle in a SvelteKit app. SvelteKit renders through app.html and
- * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
- * a client hook is the reliable path. SvelteKit runs src/hooks.client.ts on the client at startup.
- */
-export declare function svelteKitHooksFile(port: number | undefined, projectId?: string, uiLibrary?: UiLibrary): string;
-/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
-export declare const NUXT_PLUGIN_PATH = "app/plugins/reticle.client.ts";
-/**
- * The Nuxt recipe, written out in full because every trap in it is one somebody actually hit.
- *
- * Reported from the field, in the order they were hit: `init` classified a Nuxt 4 app as `html`, so
- * it installed a package named `@reticlehq/react` (with `react` in its peer dependencies) into a Vue
- * codebase — the reporter only continued after auditing our dist to confirm there are no React
- * imports at runtime, which most people will not do. It then handed over a snippet guarded on
- * `window.location.hostname === 'localhost'`, which fails twice over in Nuxt: `window` does not
- * exist during SSR, and the dev host here was a hosts-file alias (required for the backend's
- * white-label origin detection), so the guard was false and the connect never ran — no error, no log
- * line, nothing to debug. And nothing said a running dev server does not pick up a new plugin.
- *
- * So: `import.meta.dev` (build-time, host-independent) instead of a hostname check, `.client.ts`
- * instead of an SSR guard, the framework-neutral sensor instead of the React kit, the non-localhost
- * flag named up front, and the restart said out loud.
- */
-export declare function nuxtManual(port: number | undefined, projectId?: string): string;
-/**
- * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
- * and by tooling for the stable projectId (the app's identity across port changes).
- */
-export declare function reticleConfigContent(framework: string, port: number | undefined, projectId?: string, installSource?: string): string;