@reticlehq/server 3.5.0 → 3.7.0

package/docs/cli/watch.mdx

@@ -1,62 +0,0 @@
----
-title: reticle watch
-description: Watch the working tree and report which saved flows must re-verify on every save.
-icon: eye
----
-
-`reticle watch` is the buddy loop. It watches the current directory and, on every save of a source file, reports which saved flows the change puts at risk. It runs in the environment, so it costs your agent nothing per turn.
-
-```bash
-npx @reticlehq/server watch [url]
-```
-
-Long-running. Stop it with `Ctrl+C`.
-
-## Arguments
-
-| Argument | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `url` | string, positional, optional | unset | Accepted by the parser and reserved for the increment that replays the affected flows against a live app. The current version detects and reports only |
-
-## What it watches
-
-The working directory, recursively, filtered to `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.vue` and `.svelte`. Changes are batched with a 200ms debounce.
-
-## What it prints
-
-Real capture, the first two lines of a run in this repository:
-
-```json
-{"t":"2026-08-15T18:44:08.930Z","event":"reticle_watch_started","cwd":"/Users/you/reticle"}
-{"t":"2026-08-15T18:44:09.104Z","event":"reticle_buddy","status":"✓ 0/47 flows nominal · 9 flaky quarantined"}
-```
-
-A save then produces a `reticle_watch_affected` line naming the changed files and the flows they put at risk, followed by a refreshed buddy line. Real capture, with both lists trimmed:
-
-```json
-{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["init/src/mcp-clients.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
-{"t":"2026-08-15T18:44:09.355Z","event":"reticle_buddy","status":"✗ 39 deviations: ELECTRON-1LINE-flow, ELECTRON-COLD-flow +37 more · 0 nominal · 9 flaky quarantined"}
-```
-
-| Event | When |
-| --- | --- |
-| `reticle_watch_started` | Once, at startup, with the directory being watched |
-| `reticle_buddy` | Once at startup and after every batch. One ambient line, designed to be parked in a status line |
-| `reticle_watch_affected` | After a batch, when at least one flow is affected. Carries `changed` and `affected` |
-| `reticle_watch_failed` | A flow load error. Never fatal |
-
-<Note>
-  The buddy line is deliberately best-effort and silent on failure. A status line that throws is
-  worse than no status line, and it must never interfere with the watch loop it rides on.
-</Note>
-
-## Exit codes
-
-Runs until interrupted.
-
-## Worked example
-
-```bash
-npx @reticlehq/server watch &
-# edit src/components/Login.tsx, and the affected flows are named on save
-```

package/docs/local-registry.md

@@ -1,143 +0,0 @@
----
-title: Local registry
-description: 'Exercise local, unpublished Reticle changes in a real external app before they ship.'
-icon: box
----
-
-To test unpublished `@reticlehq/*` changes in a real external app, publish the workspace to a local Verdaccio with `bash scripts/local-registry.sh`, then point that app's `.npmrc` at `http://localhost:4873/` as the **default** registry, not scoped to `@reticlehq`, for the reason in step 2. That is the whole procedure; the rest of this page is the detail.
-
-> **For normal use, Reticle is on public npm.** Just `npm i -D @reticlehq/react @reticlehq/vite-plugin` (see [Getting Started](getting-started.md)). You only need this guide to test **local, unpublished changes** to the Reticle packages in a real external app before they ship.
-
-Because the `@reticlehq/*` packages depend on each other via the workspace protocol, plain `npm pack` tarballs don't resolve cleanly. The reliable way to exercise your in-progress changes in a real app is a tiny **local registry** (Verdaccio), the same path CI uses to validate a publish.
-
-## 1. Publish @reticlehq/\* to a local registry
-
-From the Reticle repo:
-
-```bash
-bash scripts/local-registry.sh
-```
-
-This starts a **fresh** Verdaccio on `http://localhost:4873`, creates a user/token, and publishes all `@reticlehq/*` packages there at the current workspace version:
-
-| Package | What you install it for |
-| --- | --- |
-| **`@reticlehq/react`** | **install this**: the browser SDK kit you embed (re-exports the browser sensor, so one install gives both `reticle` and `install`) |
-| `@reticlehq/vite-plugin` | dev-only source mapping + `connect()` injection (Vite) |
-| `@reticlehq/next` | Next.js build wrapper (`withReticle`) |
-| `@reticlehq/server` | the bridge + MCP server (your agent runs it, `npx @reticlehq/server mcp`) |
-| `@reticlehq/babel-plugin` | React 19 source stamping (Babel) |
-| `@reticlehq/test` | write declarative, signal-bound specs (`reticleTest`) |
-| `@reticlehq/eslint-plugin` | the `require-signal-on-mutation` lint rule |
-| `@reticlehq/core` | shared wire contract (pulled in automatically) |
-
-For a browser app, install `@reticlehq/react` plus the build plugin for your framework (`@reticlehq/vite-plugin` or `@reticlehq/next`); `@reticlehq/server` is what your agent runs. (Verified: an external `npm i @reticlehq/react` resolves its graph, including `@reticlehq/core`, and imports correctly.) Leave the registry running.
-
-> Note: pre-2.0 docs used a single `@reticlehq/core` umbrella package that re-exported everything; it's been split into the audience-scoped packages above.
-
-## 2. Point your app at the local registry
-
-In your app's project root, add an `.npmrc` pointing the **default** registry at Verdaccio. Verdaccio proxies npm for everything it does not hold, so the rest of your dependencies still resolve normally:
-
-```ini
-registry=http://localhost:4873/
-```
-
-**A scope-only line does not work, and fails in a way that reads as a Reticle bug.** `@reticlehq/core` depends on **`open-verification`**, the protocol package, which is deliberately _unscoped_ because the protocol is not ours to namespace. With `@reticlehq:registry=…` npm sends that one request to npmjs and the install dies:
-
-```
-npm error 404 Not Found - GET https://registry.npmjs.org/open-verification
-npm error 404  The requested resource 'open-verification@3.1.0' could not be found
-```
-
-`reticle init` then correctly reports `⚠ Install dependencies` and skips wiring the build plugin, so the app is left un-instrumented by a registry mistake two steps earlier.
-
-There is no scoped form that fixes this: npm's per-registry setting is `@scope:registry`, and an unscoped package has no scope to key on. The default-registry line above is the only thing that works. Point it back at npm (`npm config delete registry`, or delete the `.npmrc`) when you are done testing.
-
-## 3. Install + wire it up
-
-Install the SDK kit plus the Vite build plugin (source mapping + `connect()` injection):
-
-```bash
-npm i -D @reticlehq/react @reticlehq/vite-plugin
-# Next.js instead of Vite? npm i -D @reticlehq/react @reticlehq/next
-# optional: npm i -D @reticlehq/eslint-plugin   # require-signal-on-mutation lint rule
-```
-
-Then follow [Getting Started](getting-started.md): embed `reticle.connect()` (dev only) from `@reticlehq/react`, add the MCP server to your agent, and (React) `install()` the adapter from `@reticlehq/react`. For the fastest agent loop, also do [Step 6: make your app agent-legible](getting-started.md) (testids, `reticle.signal`, `registerStore`, `registerCapabilities`) and the [integration patterns](integration-patterns.md) (`createReticleEmitter` for zero prod-bundle cost).
-
-> **Upgrading.** `scripts/local-registry.sh` resets Verdaccio and republishes at whatever version the workspace is on right now, so your app will not pick up a rebuild on its own. Pull it explicitly with `@latest`:
->
-> ```bash
-> npm i -D @reticlehq/react@latest @reticlehq/vite-plugin@latest @reticlehq/eslint-plugin@latest
-> ```
-
-**Run the MCP server** from the local registry too; `npx @reticlehq/server` _is_ the server:
-
-```jsonc
-// .mcp.json: point npx at the local registry so it fetches @reticlehq/server from Verdaccio
-{
-  "mcpServers": {
-    "reticle": {
-      "command": "npx",
-      "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
-    },
-  },
-}
-```
-
-## Next.js specifics (verified on Next 15 / React 19)
-
-`next.config.mjs`:
-
-```js
-import reticleNext from '@reticlehq/next';
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
-export default reticleNext.withReticle(nextConfig); // dev-only; keeps SWC; adds file:line mapping
-```
-
-Mount the SDK from a dev-only client component (see the Next.js section in [Getting Started](getting-started.md)).
-
-## Real input for hover/drag (optional)
-
-Synthetic events can't trigger native `onMouseEnter`/pointer state (hover menus, tooltips, pointer drag). Enable **real input** so the server drives genuine pointer input and `reticle_act` reports `inputMode:"real"`:
-
-- **Easiest (`reticle drive`):** Reticle launches its own scriptable, headless-capable browser at your app URL (no flags to juggle):
-
-  ```bash
-  npx --registry http://localhost:4873/ @reticlehq/server drive http://localhost:4310   # add --headed to watch
-  ```
-
-- **Or attach to your own browser:** launch it with `--remote-debugging-port=9222`, then point the MCP server at it via `env`:
-
-  ```jsonc
-  // .mcp.json
-  {
-    "mcpServers": {
-      "reticle": {
-        "command": "npx",
-        "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
-        "env": { "RETICLE_CDP_URL": "http://localhost:9222" },
-      },
-    },
-  }
-  ```
-
-With neither set, Reticle stays synthetic (zero extra deps) and says so via `inputMode`. See [usage §18](usage.md#18-real-input-mode-native-hover--drag).
-
-## Write replayable specs + git-checked flows
-
-- **Specs:** with `@reticlehq/test`, turn checks into `reticleTest("…", async t => { await t.act(...); await t.expectSignal(...) })`. They are signal/testid-bound, `reticle_clock` for determinism, `t.expectInputModeReal()` to skip-with-reason when real input isn't active. Run them headless via `reticle drive` (the same path CI uses).
-- **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_verify { action: "heal" }` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
-
-## When you're ready for real npm
-
-The same packages publish to public npm unchanged: `pnpm -r publish --access public` after `npm login`. The Verdaccio run above is a faithful rehearsal of that.
-
-## Cleanup
-
-```bash
-pkill -f verdaccio     # stop the local registry
-# remove the line from your app's .npmrc when you switch to published packages
-```