@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-cli-how-to-build-a-standalone-binary.md

@@ -0,0 +1,105 @@
+# Build a standalone `pyric` binary
+
+Ship `pyric` as a single self-contained executable: no Node, no npm, no
+`node_modules`. Built with [`bun build --compile`](https://bun.sh/docs/bundler/executables).
+
+## Build
+
+From the repo root:
+
+```bash
+bun run compile:standalone        # clean build + all four cross-targets
+```
+
+or, iterating inside the package (assumes `bun run build` already ran):
+
+```bash
+bun run --cwd packages/cli compile        # all four targets
+bun run --cwd packages/cli compile host   # just this machine (fast)
+```
+
+Binaries land in `packages/cli/dist-bin/`:
+
+| File | Platform |
+|---|---|
+| `pyric-linux-x64` | Linux x64 |
+| `pyric-linux-arm64` | Linux arm64 |
+| `pyric-darwin-x64` | macOS Intel |
+| `pyric-darwin-arm64` | macOS Apple Silicon |
+| `pyric` | copy of this host's binary, for local runs |
+
+`dist-bin/` is git-ignored and **outside the npm `files` allowlist**. The
+~100 MB binaries are release artifacts, never published to npm or committed.
+
+Verify a build:
+
+```bash
+bun run --cwd packages/cli smoke:standalone
+```
+
+## How `dev` works in the binary
+
+Every command runs from the binary, including `dev` (the headline one).
+
+Normally `pyric dev` bundles its `firebase/*` → sandbox SDK shims with esbuild
+**at runtime**, reading the installed `pyric` dist. Neither esbuild's native
+helper nor that on-disk dist exist inside a compiled binary's virtual
+filesystem. But those bundles are **deterministic**: a pure function of
+`@pyric/cli`'s wrapper entries and the `pyric` version baked into the CLI, not
+your project (pyric dev ships its *own* sandbox; your app imports `firebase/*`, nothing more).
+
+So the compile step runs the bundler **once on the build host** and embeds the
+result (the SDK + worker bundles and the Studio UI) into the binary. At
+runtime `dev` materializes those bytes to a temp dir and serves them
+unchanged. `dev`, `dev --ui`, and `dev --bridge` all work fully offline.
+`--no-cache` is a no-op in the binary (there is nothing to rebuild).
+
+## How `init` scaffolds an installable project (vendoring)
+
+`pyric` and `@pyric/cli` are embedded in the standalone binary. It makes them
+available to a scaffold by **vendoring**: the
+compile step also `npm pack`s both packages and embeds the tarballs, and
+`pyric init` (in the standalone binary) writes them into `vendor/` and points the
+project's deps at them:
+
+```jsonc
+"devDependencies": { "@pyric/cli": "file:vendor/pyric-cli.tgz", "pyric": "file:vendor/pyric.tgz", … },
+"overrides": { "pyric": "file:vendor/pyric.tgz" }
+```
+
+`bun install` then resolves `pyric`/`@pyric/cli` from `vendor/` and everything
+else (`firebase`, `vite`, `@inbrowser/agent`, `esbuild`) from npm. The
+`overrides` pin is load-bearing: a **placeholder `pyric` is published to npm at a
+higher version than the local `0.0.0`**, so `@pyric/cli`'s transitive `pyric@*`
+would otherwise pull that empty stub instead of the vendored package.
+(`@pyric/cli`'s own `pyric` dependency is rewritten to `*` at pack time so it dedupes to
+the override.) `vendor/` is committable (the scaffold ignores only `.pyric/`), so
+a clone installs offline too.
+
+### `--deps npm`: opt out of vendoring
+
+Once the packages are published (or against a private registry), scaffold with
+registry deps instead:
+
+```bash
+pyric init --template web --deps npm                 # ^<binary version>
+pyric init --template web --deps npm --pyric-version 0.1.0
+```
+
+Default is `vendor` in the standalone binary, `npm` otherwise (e.g. `npx pyric`
+from the monorepo). `PYRIC_INIT_DEPS=npm` sets the default; `--deps` overrides it.
+
+Smoke the whole chain (`init → bun install → vite build`, offline for
+`pyric`/`@pyric/cli`) against a compiled binary:
+
+```bash
+bun run --cwd packages/cli smoke:vendor
+```
+
+## Contract
+
+- **ESM-only**, like the npm package. The binary embeds its own runtime.
+- The embedded SDK bundle is pinned to the `pyric` version compiled in. To ship
+  a new `pyric`, rebuild the binary.
+- Sourcemaps are not embedded (they 4× the size and only serve devtools); the
+  npm `dev` path still emits them.

package/dist/serve/docs-ui/docs/pyric-cli-how-to-promote-sandbox-state-to-a-fixture/index.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to promote sandbox state to a committable fixture · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Promote sandbox state</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-promote-sandbox-state-to-a-committable-fixture">How to promote sandbox state to a committable fixture</h1>
+<p>You have been working in the sandbox interactively (signing in test users,
+creating documents) and you want to commit that state so teammates, tests, and
+CI all start from the same place. <code>pyric snapshot</code> promotes the lived sandbox
+state into a single fixture file that <code>pyric verify</code> and <code>pyric dev --seed</code>
+can consume.</p>
+<p>The flow is: build state in <code>dev</code> → run <code>pyric snapshot</code> → commit the file →
+re-seed with <code>pyric dev --seed &#x3C;file></code>.</p>
+<p>For the full flag list, see the <a href="../pyric-cli-reference-cli/#pyric-snapshot"><code>pyric snapshot</code>
+reference</a>.</p>
+<h2 id="build-up-the-state">Build up the state</h2>
+<p>Run a persisted dev server and use the app: sign in, write documents, whatever you
+want the fixture to capture:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> dev</span><span style="color:#D19A66"> --persist</span></span></code></pre>
+<p><code>--persist</code> writes runtime state to <code>.pyric/state/state.json</code> as you go, so
+your data survives between sessions while you build it up.</p>
+<h2 id="promote-it-to-a-fixture">Promote it to a fixture</h2>
+<p>With that dev server still running, snapshot it:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> snapshot</span></span></code></pre>
+<p>This reads the live dev server and writes a re-servable fixture to
+<code>pyric-state.json</code> (both docs and auth users). Choose a different path with
+<code>--out</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> snapshot</span><span style="color:#D19A66"> --out</span><span style="color:#98C379"> fixtures/onboarding.json</span></span></code></pre>
+<p><code>pyric snapshot</code> refuses to clobber an existing file. Pass <code>--force</code> to
+overwrite it.</p>
+<p>If the live dev server is on a non-default port, point at it with <code>--port</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> snapshot</span><span style="color:#D19A66"> --port</span><span style="color:#D19A66"> 5002</span></span></code></pre>
+<p>If no dev server is running, <code>pyric snapshot</code> falls back to the on-disk
+<code>.pyric/state/state.json</code>, so you can still promote state from a dev server you have
+since stopped.</p>
+<h2 id="commit-the-fixture">Commit the fixture</h2>
+<p>The fixture is a plain JSON file meant to live in your repository:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">git</span><span style="color:#98C379"> add</span><span style="color:#98C379"> fixtures/onboarding.json</span></span>
+<span class="line"><span style="color:#61AFEF">git</span><span style="color:#98C379"> commit</span><span style="color:#D19A66"> -m</span><span style="color:#98C379"> "Add onboarding fixture"</span></span></code></pre>
+<p>User passwords are <strong>redacted by default</strong>: <code>.pyric/</code> is gitignored, but a
+promoted fixture is not, so committing raw passwords would leak them. The
+redaction sentinel round-trips through seeding, so re-serving still works
+(popup and helper sign-in need no password).</p>
+<p>To keep passwords for a local-only fixture you do not intend to commit, opt in
+explicitly:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> snapshot</span><span style="color:#D19A66"> --out</span><span style="color:#98C379"> local-fixture.json</span><span style="color:#D19A66"> --include-passwords</span></span></code></pre>
+<p>Only do this for trusted, local fixtures. Never commit a fixture produced this
+way.</p>
+<h2 id="re-seed-from-the-fixture">Re-seed from the fixture</h2>
+<p>Anyone with the committed file can start from exactly the same state:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> dev</span><span style="color:#D19A66"> --seed</span><span style="color:#98C379"> fixtures/onboarding.json</span></span></code></pre>
+<p>See <a href="../pyric-cli-how-to-serve-persistence-and-multi-tab/">serve persistence and multi-tab</a> for
+more on <code>--seed</code> and how seeded state interacts with <code>--persist</code>.</p>
+<h2 id="machine-readable-output">Machine-readable output</h2>
+<p>For scripts and CI, <code>--json</code> emits the result (output path, doc and user
+counts, source, redacted-password count) to stdout:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> snapshot</span><span style="color:#D19A66"> --out</span><span style="color:#98C379"> fixtures/onboarding.json</span><span style="color:#D19A66"> --json</span></span></code></pre>  </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="#build-up-the-state">Build up the state</a> </li><li data-depth="2"> <a href="#promote-it-to-a-fixture">Promote it to a fixture</a> </li><li data-depth="2"> <a href="#commit-the-fixture">Commit the fixture</a> </li><li data-depth="2"> <a href="#re-seed-from-the-fixture">Re-seed from the fixture</a> </li><li data-depth="2"> <a href="#machine-readable-output">Machine-readable output</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-how-to-promote-sandbox-state-to-a-fixture.md

@@ -0,0 +1,98 @@
+# How to promote sandbox state to a committable fixture
+
+You have been working in the sandbox interactively (signing in test users,
+creating documents) and you want to commit that state so teammates, tests, and
+CI all start from the same place. `pyric snapshot` promotes the lived sandbox
+state into a single fixture file that `pyric verify` and `pyric dev --seed`
+can consume.
+
+The flow is: build state in `dev` → run `pyric snapshot` → commit the file →
+re-seed with `pyric dev --seed <file>`.
+
+For the full flag list, see the [`pyric snapshot`
+reference](../pyric-cli-reference-cli/#pyric-snapshot).
+
+## Build up the state
+
+Run a persisted dev server and use the app: sign in, write documents, whatever you
+want the fixture to capture:
+
+```sh
+pyric dev --persist
+```
+
+`--persist` writes runtime state to `.pyric/state/state.json` as you go, so
+your data survives between sessions while you build it up.
+
+## Promote it to a fixture
+
+With that dev server still running, snapshot it:
+
+```sh
+pyric snapshot
+```
+
+This reads the live dev server and writes a re-servable fixture to
+`pyric-state.json` (both docs and auth users). Choose a different path with
+`--out`:
+
+```sh
+pyric snapshot --out fixtures/onboarding.json
+```
+
+`pyric snapshot` refuses to clobber an existing file. Pass `--force` to
+overwrite it.
+
+If the live dev server is on a non-default port, point at it with `--port`:
+
+```sh
+pyric snapshot --port 5002
+```
+
+If no dev server is running, `pyric snapshot` falls back to the on-disk
+`.pyric/state/state.json`, so you can still promote state from a dev server you have
+since stopped.
+
+## Commit the fixture
+
+The fixture is a plain JSON file meant to live in your repository:
+
+```sh
+git add fixtures/onboarding.json
+git commit -m "Add onboarding fixture"
+```
+
+User passwords are **redacted by default**: `.pyric/` is gitignored, but a
+promoted fixture is not, so committing raw passwords would leak them. The
+redaction sentinel round-trips through seeding, so re-serving still works
+(popup and helper sign-in need no password).
+
+To keep passwords for a local-only fixture you do not intend to commit, opt in
+explicitly:
+
+```sh
+pyric snapshot --out local-fixture.json --include-passwords
+```
+
+Only do this for trusted, local fixtures. Never commit a fixture produced this
+way.
+
+## Re-seed from the fixture
+
+Anyone with the committed file can start from exactly the same state:
+
+```sh
+pyric dev --seed fixtures/onboarding.json
+```
+
+See [serve persistence and multi-tab](../pyric-cli-how-to-serve-persistence-and-multi-tab/) for
+more on `--seed` and how seeded state interacts with `--persist`.
+
+## Machine-readable output
+
+For scripts and CI, `--json` emits the result (output path, doc and user
+counts, source, redacted-password count) to stdout:
+
+```sh
+pyric snapshot --out fixtures/onboarding.json --json
+```

package/dist/serve/docs-ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/index.html

@@ -0,0 +1,66 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Run an RTDB onValueCreated function locally · 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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @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/sign-in-and-manage-users/">Develop with Firebase APIs</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Run an RTDB function locally</span> </li> </ol> </nav>  <article class="prose">  <h1 id="run-an-rtdb-onvaluecreated-function-locally">Run an RTDB <code>onValueCreated</code> function locally</h1>
+<p>Use <code>pyric dev</code> to run an existing Node
+<code>firebase-functions/v2/database.onValueCreated</code> export against the same local
+Realtime Database as your app and Pyric Studio. The function source keeps its
+production imports and needs no credentials or deployment.</p>
+<p>Your <code>firebase.json</code> must declare one Functions source:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  "hosting"</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">"public"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"public"</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  "functions"</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">"source"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"functions"</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The source package’s <code>main</code> field selects the built CommonJS JavaScript entry.
+It defaults to <code>index.js</code>. Native ESM Functions entries are not supported in
+this first slice; compile an ESM or TypeScript source package to CommonJS and
+point <code>main</code> at that output:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  "name"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"my-functions"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "private"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "main"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"lib/index.js"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "dependencies"</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    "firebase-functions"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"^7.2.5"</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Keep the production function unchanged:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="js"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">onValueCreated</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> require</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'firebase-functions/v2/database'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E5C07B">exports</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">makeUppercase</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> onValueCreated</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#98C379">  '/messages/{pushId}/original'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75;font-style:italic">  event</span><span style="color:#C678DD"> =></span><span style="color:#E5C07B"> event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">ref</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">parent</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">child</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'uppercase'</span><span style="color:#ABB2BF">)</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">val</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">toUpperCase</span><span style="color:#ABB2BF">()),</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Build the Functions package if its <code>main</code> points at generated JavaScript, then
+start the project:</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">npx</span><span style="color:#98C379"> pyric</span><span style="color:#98C379"> dev</span></span></code></pre>
+<p>Keep the browser tab that opens running. Pyric discovers the Functions entry,
+starts it in an isolated Node child, and reports its supported exports:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>• functions waiting for the browser tab to connect the sandbox…</span></span>
+<span class="line"><span>✔ functions 1 onValueCreated trigger from functions/lib/index.js</span></span></code></pre>
+<p>Create the matching value through your ordinary client code:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="js"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getDatabase</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">set</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase/database'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> set</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">ref</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">getDatabase</span><span style="color:#ABB2BF">(), </span><span style="color:#98C379">'messages/id/original'</span><span style="color:#ABB2BF">), </span><span style="color:#98C379">'hello'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>The terminal reports the execution:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>✔ function  makeUppercase ← /messages/id/original (pushId=id)</span></span></code></pre>
+<p>The app and Studio now read <code>messages/id/uppercase</code> as <code>"HELLO"</code> from that
+same sandbox. Press Ctrl-C to stop both <code>pyric dev</code> and the Functions child.</p>
+<h2 id="if-an-export-is-outside-the-first-slice">If an export is outside the first slice</h2>
+<p>Pyric prints each unsupported trigger export and leaves it inactive. The first
+slice supports a CommonJS Node <code>onValueCreated</code> entry, one Functions source,
+one local RTDB instance, exact paths and named single-segment wildcards,
+sequential delivery within the current session, and Admin reads and writes
+through <code>event.data.ref</code>. Flat exports and Firebase-style grouped exports such
+as <code>exports.messages = { makeUppercase }</code> are both discovered.</p>
+<p>Firebase path patterns beyond that grammar, such as <code>{id=prefix/*}</code> and
+<code>{id=**}</code>, and instance selectors such as <code>db-*</code> are reported as unsupported
+instead of being announced and then silently left unmatched. If supported
+exports resolve to more than one database instance, startup fails and names the
+conflicting instances.
+Endpoints declared with <code>omit: true</code> remain inactive, matching Firebase’s
+“do not deploy or emulate” contract. A dynamic expression used for <code>omit</code> is
+reported as unsupported because Pyric cannot resolve its deployment value.</p>
+<p>Native ESM entries, other RTDB trigger types, other Firebase products, retries,
+deployed concurrency, multiple Functions codebases or database instances,
+durable delivery across restarts, secrets, and deployment emulation remain
+outside the slice. See the <a href="../pyric-cli-functions-rtdb-compat/">Functions RTDB compatibility matrix</a>
+for the production-observed behaviour Pyric replays.</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="#if-an-export-is-outside-the-first-slice">If an export is outside the first slice</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-how-to-run-rtdb-onvaluecreated.md

@@ -0,0 +1,100 @@
+# Run an RTDB `onValueCreated` function locally
+
+Use `pyric dev` to run an existing Node
+`firebase-functions/v2/database.onValueCreated` export against the same local
+Realtime Database as your app and Pyric Studio. The function source keeps its
+production imports and needs no credentials or deployment.
+
+Your `firebase.json` must declare one Functions source:
+
+```json
+{
+  "hosting": { "public": "public" },
+  "functions": { "source": "functions" }
+}
+```
+
+The source package's `main` field selects the built CommonJS JavaScript entry.
+It defaults to `index.js`. Native ESM Functions entries are not supported in
+this first slice; compile an ESM or TypeScript source package to CommonJS and
+point `main` at that output:
+
+```json
+{
+  "name": "my-functions",
+  "private": true,
+  "main": "lib/index.js",
+  "dependencies": {
+    "firebase-functions": "^7.2.5"
+  }
+}
+```
+
+Keep the production function unchanged:
+
+```js
+const { onValueCreated } = require('firebase-functions/v2/database');
+
+exports.makeUppercase = onValueCreated(
+  '/messages/{pushId}/original',
+  event => event.data.ref.parent
+    .child('uppercase')
+    .set(event.data.val().toUpperCase()),
+);
+```
+
+Build the Functions package if its `main` points at generated JavaScript, then
+start the project:
+
+```bash
+npx pyric dev
+```
+
+Keep the browser tab that opens running. Pyric discovers the Functions entry,
+starts it in an isolated Node child, and reports its supported exports:
+
+```text
+• functions waiting for the browser tab to connect the sandbox…
+✔ functions 1 onValueCreated trigger from functions/lib/index.js
+```
+
+Create the matching value through your ordinary client code:
+
+```js
+import { getDatabase, ref, set } from 'firebase/database';
+
+await set(ref(getDatabase(), 'messages/id/original'), 'hello');
+```
+
+The terminal reports the execution:
+
+```text
+✔ function  makeUppercase ← /messages/id/original (pushId=id)
+```
+
+The app and Studio now read `messages/id/uppercase` as `"HELLO"` from that
+same sandbox. Press Ctrl-C to stop both `pyric dev` and the Functions child.
+
+## If an export is outside the first slice
+
+Pyric prints each unsupported trigger export and leaves it inactive. The first
+slice supports a CommonJS Node `onValueCreated` entry, one Functions source,
+one local RTDB instance, exact paths and named single-segment wildcards,
+sequential delivery within the current session, and Admin reads and writes
+through `event.data.ref`. Flat exports and Firebase-style grouped exports such
+as `exports.messages = { makeUppercase }` are both discovered.
+
+Firebase path patterns beyond that grammar, such as `{id=prefix/*}` and
+`{id=**}`, and instance selectors such as `db-*` are reported as unsupported
+instead of being announced and then silently left unmatched. If supported
+exports resolve to more than one database instance, startup fails and names the
+conflicting instances.
+Endpoints declared with `omit: true` remain inactive, matching Firebase's
+"do not deploy or emulate" contract. A dynamic expression used for `omit` is
+reported as unsupported because Pyric cannot resolve its deployment value.
+
+Native ESM entries, other RTDB trigger types, other Firebase products, retries,
+deployed concurrency, multiple Functions codebases or database instances,
+durable delivery across restarts, secrets, and deployment emulation remain
+outside the slice. See the [Functions RTDB compatibility matrix](../pyric-cli-functions-rtdb-compat/)
+for the production-observed behaviour Pyric replays.