@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-cli-reference-cli.md

@@ -0,0 +1,249 @@
+# `pyric` CLI reference
+
+The complete command + flag surface of the `pyric` binary. This is the
+authoritative source for flags, defaults, and exit codes: guides and tutorials
+link here rather than restating them.
+
+Run `pyric --help` for the same surface inline, or `pyric --version`.
+
+## Conventions
+
+- `<required>` arguments; `[optional]` arguments and flags.
+- Flags accept `--flag value` or `--flag=value`.
+- Unless noted, commands exit **0** on success, **1** on a usage error, and
+  **2** on a runtime error. Specific non-standard exit codes are called out
+  per command.
+
+## Environment variables
+
+| Variable | Used by | Meaning |
+|---|---|---|
+| `PYRIC_PORT` | `bridge` | Bridge port (default 5174). |
+| `PYRIC_PROJECT` | `bridge`, `verify --engine rules-test-api` | Project id label (falls back to the `.firebaserc` default). |
+| `PYRIC_VERBOSE` | all | Verbose logging when set. |
+| `FIREBASE_SA_BASE64` | `verify --engine rules-test-api\|both` | base64-encoded service-account JSON for the hosted Rules Test API. |
+| `GOOGLE_APPLICATION_CREDENTIALS` | `verify --engine rules-test-api\|both` | Filesystem path to service-account JSON for the hosted Rules Test API. |
+
+Local sandbox commands (`dev`, `init`, `snapshot`, `bridge`, `mcp`, `verify`
+with the default `sandbox` engine, and every service-first rules or index
+command) need no credentials. Hosted Rules Test API verification (`--engine
+rules-test-api` or `both`) needs a project id plus `FIREBASE_SA_BASE64` or
+`GOOGLE_APPLICATION_CREDENTIALS` (or ADC). See
+`@pyric/cli/credentials/node`.
+
+---
+
+## Local development
+
+<a id="pyric-dev"></a>
+### `pyric dev [flags]`
+
+Serve the app locally with the pyric sandbox standing in for Firebase. Unmodified
+`firebase/*` imports resolve, via a served import map, to a sandbox running in a
+**SharedWorker by default** (one authoritative backend shared across all tabs;
+durable in the browser's IndexedDB; service adapters use the per-tab in-page
+sandbox only when SharedWorker is unavailable). The current bundle still
+constructs that inactive fallback primitive eagerly; it is not a second routed
+backend. `firestore.rules` is installed and hot-reloaded over SSE.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--port <n>` | `3473` | Port to serve on ("FIRE" on a phone keypad); scans forward when taken. |
+| `--host <h>` | `localhost` | Host to bind. |
+| `--persist` | off | Persist sandbox state (docs + auth users) to a committable `.pyric/state/state.json`. Once a state file exists it wins; `--seed` then applies only into an empty sandbox. (On the SharedWorker path data is already durable in IndexedDB; this adds the on-disk, shareable copy.) |
+| `--fresh` | off | Requires `--persist`: errors otherwise (there's no state file to discard). Discards the existing state file and re-seeds from scratch. Does **not** clear the browser's IndexedDB, so a browser tab with existing sandbox data keeps it and writes it right back into the new file; also clear site data (or use a private window) for a full reset. |
+| `--seed <file>` | none | Load a `"collection/doc" → fields` JSON map admin-style before app code runs. Also accepts a `pyric snapshot` state file (detected by its `version` key), seeds docs + auth users. Applies only into an empty sandbox: if it already holds restored/lived data (a state file, or IndexedDB from an earlier session even without `--persist`), the seed is skipped and a console line explains why. |
+| `--no-capture` | capture on | Disable the session capture. By default pyric dev writes `.pyric/last-session.json` for `pyric verify` to replay. Captures use `pyric.verify.fixture.v1`, with one event timeline and per-service Firestore/RTDB rules + state blocks. |
+| `--no-watch` | watch on | Disable `firestore.rules` hot-reload. |
+| `--no-open` | auto-open on | Don't auto-open the browser. (Auto-open is already suppressed under `--json`, no TTY, and CI.) |
+| `--no-cache` | cache on | Rebuild the served SDK + worker bundles instead of using `~/.pyric/serve-cache`. |
+| `--bridge` | off | Also mount the MCP bridge on the dev-server origin (`/__pyric/mcp`). `--project` labels health/audit. |
+| `--ui` | off | Serve Pyric Studio at `/__pyric/ui/` and open it instead of the app. Implies `--bridge`. |
+| `--project <id>` | none | Project label exposed by the mounted bridge. |
+| `--allowed-host <h,…>` | none | Extra `Host` headers to accept past the DNS-rebinding guard (`localhost`/`127.0.0.1` always allowed). |
+| `--only hosting` | none | Accepted for firebase-serve parity (hosting is all v1 serves). |
+| `--no-run` | off | Do not run the project's `dev` script; host only. |
+| `--json` | off | One machine line on stdout (`{url, port, mcpUrl, rulesHash, persist, restoredDocs, restoredUsers}`); banner → stderr. Readiness probe: `GET <url>/__pyric/init.json` → 200. |
+
+Append `-- <command>` to run an explicit child process after the host starts.
+Without an explicit command, `pyric dev` runs the package's `dev` script when
+one exists. The child receives the activated package-resolution environment;
+see [package exports and resolution](../pyric-cli-reference-package-and-resolution/).
+
+When `firebase.json` declares one Functions source, `pyric dev` also reads that
+source package's `main` field (`index.js` by default) and starts an isolated
+Node child for supported `firebase-functions/v2/database.onValueCreated`
+exports. A Functions source implies the local bridge even without `--bridge`.
+`--no-run` suppresses only the project's `dev` script; it does not suppress the
+declared Functions source. Unsupported trigger exports are reported and left
+inactive. See [run an RTDB `onValueCreated` function locally](../pyric-cli-how-to-run-rtdb-onvaluecreated/).
+The entry selected by `main` must be CommonJS; native ESM Functions entries are
+outside this first slice.
+
+Persistence, multi-tab, and SharedWorker behaviour are covered in
+[persistence and multi-tab](../pyric-cli-how-to-serve-persistence-and-multi-tab/).
+
+### `pyric init [dir] [flags]`
+
+Scaffold a pyric project. Never prompts; rerunning is safe (idempotent).
+
+| Flag | Default | Description |
+|---|---|---|
+| `--template <web\|static\|node>` | `web` | `web`: a Vite app using canonical `firebase/*` imports. `static`: a no-bundler app served by `pyric dev`. `node`: a script-style scaffold whose canonical Firebase imports are swapped when run through `pyric dev`. |
+| `--name <name>` | dir name | Project name. |
+| `--force` | off | Overwrite scaffold-owned files. |
+| `--json` | off | Machine result on stdout: `{template, dir, created, merged, skipped, conflicts, nextSteps}`. |
+
+### `pyric vendor [dir] [--json]`
+
+Retrofit the standalone-binary package tarballs into an existing project and
+merge their dependencies into `package.json`. This command is available in the
+standalone binary; registry installs normally use `npm install -D @pyric/cli`.
+
+<a id="pyric-snapshot"></a>
+### `pyric snapshot [flags]`
+
+Promote lived sandbox state (a live `dev --persist`, else
+`.pyric/state/state.json`) to a committable fixture that `pyric dev --seed <file>`
+re-serves (docs + auth users).
+
+| Flag | Default | Description |
+|---|---|---|
+| `--out <file>` | none | Output path for the fixture. |
+| `--port <n>` | none | Port of the live `pyric dev` to read from. |
+| `--force` | off | Overwrite an existing output file. |
+| `--include-passwords` | redacted | Keep auth-user passwords in the fixture (default: redacted). Trusted/local fixtures only. |
+| `--json` | off | Machine output on stdout. |
+
+See [promote sandbox state to a fixture](../pyric-cli-how-to-promote-sandbox-state-to-a-fixture/).
+
+<a id="pyric-verify"></a>
+### `pyric verify [fixture|dir] [flags]`
+
+Replay a captured sandbox session against candidate rules. Captures can contain
+Firestore and Realtime Database services; `verify` checks the verifiable
+services present in the fixture unless `--service` filters them. With no
+positional argument it replays the latest `pyric dev` capture at
+`.pyric/last-session.json`.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--service <firestore\|rtdb>` | all services in fixture | Verify one service. Repeat to verify several selected services. |
+| `--engine <sandbox\|rules-test-api\|both>` | `sandbox` | Choose the verification engine. `rules-test-api` and `both` require `--project` (or `.firebaserc`) plus service-account / ADC credentials. Rules Test API verification is Firestore-only. |
+| `--rules <service=path>` | from `firebase.json` | Candidate rules to verify against. Repeat for mixed-service captures. Firestore rules are source files; RTDB rules are JSON files. |
+| `--json` | off | Machine output on stdout. |
+
+Default candidate rules come from `firebase.json.firestore.rules` and
+`firebase.json.database.rules`. Captured rules are informational and are not
+used as the candidate ruleset.
+
+**Exit code:** `1` on any failing divergence, `0` otherwise. Missing fixture or
+missing candidate rules exits `2`. Firestore auto-id aliases, time drift, and
+sentinel drift are informational and do not fail.
+
+Examples:
+
+```sh
+pyric verify
+pyric verify journeys/ --rules firestore=firestore.rules
+pyric verify journeys/checkout.json --engine rules-test-api --project demo-app
+pyric verify journeys/checkout.json --engine both --project demo-app
+pyric verify --service rtdb --rules rtdb=database.rules.json
+pyric verify --rules firestore=firestore.rules --rules rtdb=database.rules.json
+```
+
+See [verify against a captured session](../pyric-cli-how-to-verify-against-a-captured-session/).
+
+### `pyric verify cases [fixture] [flags]`
+
+Derive Firestore Rules Test API cases from a captured fixture without running
+verification.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--service firestore` | `firestore` | The service to derive cases for. Only Firestore is supported. |
+| `--out <path>` | stdout | Write the derived case JSON to a file. |
+
+```sh
+pyric verify cases journeys/checkout.json --service firestore --out journeys/checkout.cases.json
+```
+
+### `pyric mcp`
+
+Start a stdio MCP server for editors. It attaches to a running `pyric dev
+--bridge`, discovered through `.pyric/serve.json`, or hosts a persistent
+headless sandbox when no development server is available. See
+[wire Claude Code](../pyric-cli-tutorials-wire-claude-code/).
+
+### `pyric bridge [flags]`
+
+Stand up the HTTP+WebSocket bridge external MCP clients connect to. It relays
+tool calls to a connected in-browser sandbox. See [bridge](../pyric-cli-bridge/).
+
+| Flag | Default | Description |
+|---|---|---|
+| `--port <n>` | `5174` | Port to bind on `127.0.0.1`. Env: `PYRIC_PORT`. |
+| `--project <id>` | none | Project id surfaced in `/health` + audit log. Env: `PYRIC_PROJECT`. |
+
+---
+
+## Service-first artifact commands
+
+Every service command follows `pyric <service> <artifact> <operation>`. The
+Firestore rules commands wrap the rules toolchain documented in
+[`pyric/docs/rules/`](../pyric-rules/).
+
+### `pyric firestore rules lint <path>`
+
+Run the Firestore rules linter against a file.
+
+### `pyric firestore rules validate <path>`
+
+Validate Firestore rules structure against a file.
+
+### `pyric firestore rules simulate [--stdin]`
+
+Local rules simulator.
+
+| Flag | Description |
+|---|---|
+| `--stdin` | Read a scripted simulation from stdin instead of running the interactive smoke-test. |
+
+### `pyric firestore rules resolve <path> [--out <path>]`
+
+Resolve a Firestore `2+modules` source and write ordinary Firebase rules to
+stdout or `--out`.
+
+### `pyric firestore indexes generate <path...> [--out <path>]`
+
+Derive composite-index definitions from application source. The default output
+is `firestore.indexes.json`.
+
+### `pyric storage rules lint <path>`
+
+Check Storage rules syntax locally.
+
+### `pyric storage rules simulate [--stdin]`
+
+Run the local Storage rules evaluator.
+
+### `pyric database rules lint <path>`
+
+Run the Realtime Database rules JSON expression linter against a file.
+
+### `pyric database rules validate <path>`
+
+Validate Realtime Database rules JSON expressions against the local parser and
+expression validator.
+
+### `pyric database rules simulate [--stdin]`
+
+Local Realtime Database rules simulator. With no flags, reads
+`firebase.json.database.rules` and runs a sample anonymous read. With `--stdin`,
+reads a JSON payload with `rulesJson` or `rulesPath`, `operation`, `path`,
+optional `auth`, `mockData`, and `newData`.
+
+### `pyric database rules generate [--config <path>] [--out <path>]`
+
+Load a constraints module (default `database.rules.ts`), compile it to Firebase
+RTDB rules JSON, and write the file. Does not contact a Firebase project.

package/dist/serve/docs-ui/docs/pyric-cli-reference-package-and-resolution/index.html

@@ -0,0 +1,93 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Package exports and resolution · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/" aria-current="true"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/" aria-current="true"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-cli/">@pyric/cli</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Package exports and resolution</span> </li> </ol> </nav>  <article class="prose">  <h1 id="package-exports-and-resolution">Package exports and resolution</h1>
+<p>Install <code>@pyric/cli</code> as a development dependency. It provides the <code>pyric</code>
+binary and a small set of explicit programmatic subpaths; the package root is
+not an import target.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npm</span><span style="color:#98C379"> install</span><span style="color:#D19A66"> -D</span><span style="color:#98C379"> @pyric/cli</span></span>
+<span class="line"><span style="color:#61AFEF">npx</span><span style="color:#98C379"> pyric</span><span style="color:#D19A66"> --help</span></span></code></pre>
+<h2 id="public-subpaths">Public subpaths</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Import</th><th>Purpose</th></tr></thead><tbody><tr><td><code>@pyric/cli/credentials/node</code></td><td>Build a credential scope for hosted Rules Test API verification.</td></tr><tr><td><code>@pyric/cli/verify</code></td><td>Replay captured sessions and derive Rules Test API cases.</td></tr><tr><td><code>@pyric/cli/assurance</code></td><td>Define and run assurance campaigns.</td></tr><tr><td><code>@pyric/cli/assurance/browser</code></td><td>Attach a browser to an assurance campaign.</td></tr><tr><td><code>@pyric/cli/bridge</code></td><td>Start or connect to a sandbox bridge.</td></tr><tr><td><code>@pyric/cli/bridge/client</code></td><td>Use the browser bridge client directly.</td></tr><tr><td><code>@pyric/cli/discover</code></td><td>Credential-free discovery against a supplied sandbox or data source.</td></tr><tr><td><code>@pyric/cli/vite</code></td><td>Resolve canonical Firebase Web SDK imports to the browser sandbox during Vite development.</td></tr><tr><td><code>@pyric/cli/serve/worker</code></td><td>Use the SharedWorker sandbox host.</td></tr><tr><td><code>@pyric/cli/remote</code></td><td>Connect Node code to a running sandbox.</td></tr><tr><td><code>@pyric/cli/register</code></td><td>Activate Node package-resolution hooks when the development environment requests them.</td></tr></tbody></table></div>
+<p>The package manifest is the authority for this list. An import that is not in
+<code>exports</code> is private and may not resolve from a packed release.</p>
+<h2 id="activated-development-resolution">Activated development resolution</h2>
+<p>Application and server source keeps canonical imports such as
+<code>firebase/firestore</code> and <code>firebase-admin/app</code>.</p>
+<ul>
+<li><code>@pyric/cli/vite</code> activates the Web SDK swap during <code>vite dev</code>. Vite resolves
+canonical <code>firebase/*</code> specifiers to the <code>pyric/*</code> sandbox mirrors, including
+imports made by dependencies.</li>
+<li><code>pyric dev</code> activates the Node swap for the child process it runs. It sets
+<code>PYRIC_SANDBOX</code> and preloads <code>@pyric/cli/register</code>; the hook resolves
+<code>firebase/*</code> to <code>pyric/*</code> and <code>firebase-admin/*</code> to <code>pyric-admin/*</code>.</li>
+<li>A declared Functions source runs its CommonJS entry with the real installed
+<code>firebase-functions</code> package in its own Node child. Native ESM Functions
+entries are outside the first slice. Its <code>firebase-admin/app</code> and
+<code>firebase-admin/database</code> dependencies resolve to the same sandbox Admin
+adapters, so <code>event.data.ref</code> reads and writes share the app’s RTDB.</li>
+</ul>
+<p>Activation belongs to the development invocation, not to application source or
+the presence of a file. That keeps the source identical on both sides of the
+boundary.</p>
+<h2 id="inactive-production-resolution">Inactive production resolution</h2>
+<p>Without <code>PYRIC_SANDBOX</code>, <code>@pyric/cli/register</code> is inert and installs no
+resolution hooks. A production Vite build also leaves the development swap
+inactive. The runtime’s normal resolver therefore loads <code>firebase</code> and
+<code>firebase-admin</code> directly.</p>
+<p><code>NODE_ENV=production</code> refuses accidental sandbox activation unless
+<code>PYRIC_SANDBOX_FORCE=1</code> is set explicitly. That override is for controlled
+development or CI only; it is not a production mode.</p>
+<p>This resolution boundary does not deploy anything. Pyric owns sandbox
+development, artifact generation, and verification. Firebase and
+<code>firebase-tools</code> own production execution and deployment.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#public-subpaths">Public subpaths</a> </li><li data-depth="2"> <a href="#activated-development-resolution">Activated development resolution</a> </li><li data-depth="2"> <a href="#inactive-production-resolution">Inactive production resolution</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-cli-reference-package-and-resolution.md

@@ -0,0 +1,65 @@
+# Package exports and resolution
+
+Install `@pyric/cli` as a development dependency. It provides the `pyric`
+binary and a small set of explicit programmatic subpaths; the package root is
+not an import target.
+
+```bash
+npm install -D @pyric/cli
+npx pyric --help
+```
+
+## Public subpaths
+
+| Import | Purpose |
+|---|---|
+| `@pyric/cli/credentials/node` | Build a credential scope for hosted Rules Test API verification. |
+| `@pyric/cli/verify` | Replay captured sessions and derive Rules Test API cases. |
+| `@pyric/cli/assurance` | Define and run assurance campaigns. |
+| `@pyric/cli/assurance/browser` | Attach a browser to an assurance campaign. |
+| `@pyric/cli/bridge` | Start or connect to a sandbox bridge. |
+| `@pyric/cli/bridge/client` | Use the browser bridge client directly. |
+| `@pyric/cli/discover` | Credential-free discovery against a supplied sandbox or data source. |
+| `@pyric/cli/vite` | Resolve canonical Firebase Web SDK imports to the browser sandbox during Vite development. |
+| `@pyric/cli/serve/worker` | Use the SharedWorker sandbox host. |
+| `@pyric/cli/remote` | Connect Node code to a running sandbox. |
+| `@pyric/cli/register` | Activate Node package-resolution hooks when the development environment requests them. |
+
+The package manifest is the authority for this list. An import that is not in
+`exports` is private and may not resolve from a packed release.
+
+## Activated development resolution
+
+Application and server source keeps canonical imports such as
+`firebase/firestore` and `firebase-admin/app`.
+
+- `@pyric/cli/vite` activates the Web SDK swap during `vite dev`. Vite resolves
+  canonical `firebase/*` specifiers to the `pyric/*` sandbox mirrors, including
+  imports made by dependencies.
+- `pyric dev` activates the Node swap for the child process it runs. It sets
+  `PYRIC_SANDBOX` and preloads `@pyric/cli/register`; the hook resolves
+  `firebase/*` to `pyric/*` and `firebase-admin/*` to `pyric-admin/*`.
+- A declared Functions source runs its CommonJS entry with the real installed
+  `firebase-functions` package in its own Node child. Native ESM Functions
+  entries are outside the first slice. Its `firebase-admin/app` and
+  `firebase-admin/database` dependencies resolve to the same sandbox Admin
+  adapters, so `event.data.ref` reads and writes share the app's RTDB.
+
+Activation belongs to the development invocation, not to application source or
+the presence of a file. That keeps the source identical on both sides of the
+boundary.
+
+## Inactive production resolution
+
+Without `PYRIC_SANDBOX`, `@pyric/cli/register` is inert and installs no
+resolution hooks. A production Vite build also leaves the development swap
+inactive. The runtime's normal resolver therefore loads `firebase` and
+`firebase-admin` directly.
+
+`NODE_ENV=production` refuses accidental sandbox activation unless
+`PYRIC_SANDBOX_FORCE=1` is set explicitly. That override is for controlled
+development or CI only; it is not a production mode.
+
+This resolution boundary does not deploy anything. Pyric owns sandbox
+development, artifact generation, and verification. Firebase and
+`firebase-tools` own production execution and deployment.