npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-cli-tutorials-server-adoption/index.html ADDED Viewed

@@ -0,0 +1,219 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Run your firebase-admin app on the pyric sandbox · 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>Tutorials</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Run your firebase-admin app on the pyric sandbox</span> </li> </ol> </nav>  <article class="prose">  <h1 id="run-your-firebase-admin-app-on-the-pyric-sandbox">Run your firebase-admin app on the pyric sandbox</h1>
+<p>You have an existing Node server that uses <code>firebase-admin</code>: Realtime
+Database, Auth, Storage. By the end of this tutorial it runs against the
+<strong>pyric in-browser sandbox</strong> with <strong>zero code changes</strong>: no pyric imports,
+no config edits, no emulator suite, no Firebase project.</p>
+<p>Takes about five minutes.</p>
+<h2 id="prerequisites">Prerequisites</h2>
+<ul>
+<li><strong>Node ≥ 22.15</strong> for full coverage. ESM-only apps work on earlier 22.x,
+but rewriting CJS <code>require('firebase-admin')</code> needs 22.15’s sync module
+hooks (older Nodes print a warning and skip CJS, see
+<a href="#troubleshooting">Troubleshooting</a>).</li>
+<li>A server using <code>firebase-admin</code> (RTDB / Auth / Storage). A
+<code>firebase.json</code> is optional: without one, <code>pyric dev</code> warns and serves
+the current directory.</li>
+</ul>
+<h2 id="step-1-install">Step 1: Install</h2>
+<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"> i</span><span style="color:#D19A66"> -D</span><span style="color:#98C379"> @pyric/cli</span></span></code></pre>
+<p><code>@pyric/cli</code> provides the CLI and Node resolver; its sandbox mirror
+dependencies are installed with it. None of them appear in your app code.</p>
+<h2 id="step-2-run-it">Step 2: Run it</h2>
+<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><code>pyric dev</code> starts the sandbox host and then runs <strong>your own <code>dev</code>
+script</strong> with the environment activated (or run an explicit command:
+<code>npx pyric dev -- node server.mjs</code>). Whenever it runs your server,
+<code>pyric dev</code> also mounts the WebSocket relay the server’s Firebase
+calls travel through, no extra flag needed.</p>
+<p>Your server needs nothing pyric-shaped. This works as-is:</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:#7F848E;font-style:italic">// server.mjs — zero pyric identifiers</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">createServer</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'node:http'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeApp</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase-admin/app'</span><span style="color:#ABB2BF">;</span></span>
+<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:#C678DD">from</span><span style="color:#98C379"> 'firebase-admin/database'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getAuth</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase-admin/auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getStorage</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase-admin/storage'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">initializeApp</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getDatabase</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> auth</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getAuth</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> bucket</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getStorage</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">bucket</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">createServer</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">req</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">res</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">req</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">url</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> '/signup'</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">    const</span><span style="color:#E5C07B"> user</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> auth</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">createUser</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">email</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">`u</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">Date</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">now</span><span style="color:#ABB2BF">()</span><span style="color:#C678DD">}</span><span style="color:#98C379">@example.com`</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">password</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'hunter22'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">    await</span><span style="color:#E5C07B"> db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">ref</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`profiles/</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">user</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">uid</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">plan</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'free'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">    await</span><span style="color:#E5C07B"> bucket</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">file</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`avatars/</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">user</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">uid</span><span style="color:#C678DD">}</span><span style="color:#98C379">.txt`</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">save</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'placeholder avatar'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">    res</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">end</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">JSON</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">stringify</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">user</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">    return</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#E5C07B">  res</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">end</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'ok'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}).</span><span style="color:#61AFEF">listen</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">8080</span><span style="color:#ABB2BF">, () </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'api listening on http://localhost:8080'</span><span style="color:#ABB2BF">));</span></span></code></pre>
+<p>The terminal shows the host banner, then your dev command’s output
+prefixed with <code>[dev]</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>=== Serving from '/Users/you/code/your-app'...</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>✔ hosting  Serving files from: public</span></span>
+<span class="line"><span>✔ hosting  Local server: http://localhost:3473</span></span>
+<span class="line"><span>✔ sandbox  pyric SDK bundles ready (cache)</span></span>
+<span class="line"><span>• rules    no firestore.rules — sandbox runs with default rules</span></span>
+<span class="line"><span>• rules    no database.rules — RTDB sandbox runs with default rules</span></span>
+<span class="line"><span>✔ bridge   MCP endpoint: http://localhost:3473/__pyric/mcp (sandbox peers over ws at /__pyric/sandbox)</span></span>
+<span class="line"><span>✔ capture  session → /Users/you/code/your-app/.pyric/last-session.json (run `pyric verify` to replay it)</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>  ⚠ the pyric sandbox runs IN the served page — keep the browser tab open.</span></span>
+<span class="line"><span>    Firestore/auth data and persistence stop when no page is open.</span></span>
+<span class="line"><span>✔ run      `npm run dev` — firebase-admin/firebase imports are routed to the sandbox at http://localhost:3473</span></span>
+<span class="line"><span>[dev] @pyric/cli/register: active — firebase-admin/firebase imports now resolve to the pyric sandbox (PYRIC_SANDBOX=remote:http://localhost:3473).</span></span>
+<span class="line"><span>[dev]</span></span>
+<span class="line"><span>[dev] > dev</span></span>
+<span class="line"><span>[dev] > node server.mjs</span></span>
+<span class="line"><span>[dev]</span></span>
+<span class="line"><span>[dev] @pyric/cli/register: active — firebase-admin/firebase imports now resolve to the pyric sandbox (PYRIC_SANDBOX=remote:http://localhost:3473).</span></span>
+<span class="line"><span>[dev] pyric: firebase-admin routed to sandbox at http://localhost:3473</span></span>
+<span class="line"><span>[dev] api listening on http://localhost:8080</span></span></code></pre>
+<p>(The <code>register: active</code> line appears once per Node process; <code>npm run dev</code> is itself a Node process, so seeing it twice is normal.)</p>
+<p>A browser tab on <a href="http://localhost:3473" target="_blank" rel="noopener noreferrer" class="external-link">http://localhost:3473</a> auto-opens: <strong>it is the
+backend</strong>, so keep it open. Now:</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">curl</span><span style="color:#98C379"> http://localhost:8080/signup</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic"># {"uid":"user-1"}</span></span></code></pre>
+<p>That user, the RTDB profile, and the stored avatar all landed in the
+sandbox your browser tab hosts. Run with <code>--ui</code> instead and Pyric Studio
+(<code>http://localhost:3473/__pyric/ui/</code>) shows the data live as your server
+writes it (<code>--ui</code> implies <code>--bridge</code>).</p>
+<h2 id="how-it-works">How it works</h2>
+<p>Three small pieces, nothing hidden:</p>
+<ol>
+<li><strong>Activator</strong>: <code>pyric dev</code> runs your dev command with
+<code>PYRIC_SANDBOX=remote:&#x3C;serve url></code> set and
+<code>--import @pyric/cli/register</code> appended to <code>NODE_OPTIONS</code>.</li>
+<li><strong>Loader</strong>: <code>@pyric/cli/register</code> rewrites module resolution:
+<code>firebase-admin/*</code> → <code>pyric-admin/*</code> and <code>firebase/*</code> → <code>pyric/*</code>,
+every subpath 1:1. Without <code>PYRIC_SANDBOX</code> it is completely inert, so
+canonical imports resolve to <code>firebase-admin</code> directly and <code>pyric-admin</code>
+never loads.</li>
+<li><strong>Bridge</strong>: each Firebase call becomes an op relayed over a local
+WebSocket to <code>pyric dev</code>, then into the browser tab, where the sandbox
+runs in a SharedWorker. Your server, the page’s <code>firebase/*</code> code,
+Studio, and any MCP agent all operate on the <strong>same</strong> backend.</li>
+</ol>
+<p>Because the backend lives in the browser, the tab must stay open. Close
+every tab and server calls fail fast with guidance (never a silent no-op).</p>
+<h2 id="what-works-remotely-today">What works remotely today</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Service</th><th>Works</th><th>Not yet (throws a clear error)</th></tr></thead><tbody><tr><td><strong>Realtime Database</strong></td><td><code>ref().get/set/update/remove/push</code>, <code>once('value')</code>, <code>on('value')</code> live listeners; <code>update()</code> is a real multi-path update; <code>push().key</code> is sync</td><td>other event types (<code>child_added</code>, …), queries (<code>orderBy*</code>, <code>limitTo*</code>, …), <code>transaction</code>, <code>onDisconnect</code>, priorities</td></tr><tr><td><strong>Auth (admin)</strong></td><td><code>createUser</code>, <code>updateUser</code> (displayName / email / password / disabled / emailVerified), <code>deleteUser</code>, <code>listUsers</code>, <code>getUser</code> / <code>getUserByEmail</code>, <code>setCustomUserClaims</code>, <code>createCustomToken</code> / <code>verifyIdToken</code></td><td><code>getUserByPhoneNumber</code>, bulk ops (<code>getUsers</code>, <code>deleteUsers</code>, <code>importUsers</code>), session cookies, action links, provider configs, <code>revokeRefreshTokens</code></td></tr><tr><td><strong>Storage</strong></td><td><code>file().save/download/delete/exists</code> up to <strong>8 MiB per object</strong>, <code>getSignedUrl</code> (local stub), single default bucket</td><td>streams (<code>createReadStream</code>/<code>createWriteStream</code>), resumable uploads, named buckets, copy/move, ACL/IAM</td></tr><tr><td><strong>Firestore (admin)</strong></td><td>none</td><td>everything (coming; see below)</td></tr></tbody></table></div>
+<p>Behavior notes you will actually hit. Each error below is quoted from a
+real run:</p>
+<ul>
+<li><strong>Firestore admin isn’t relayed yet.</strong> <code>getFirestore()</code> on the sandbox
+throws: <code>pyric-admin/firestore: Firestore is not yet supported on a remote sandbox — the bridge currently carries Realtime Database and Auth. Use pyric/firestore in the browser (or the MCP Firestore tools) until remote Firestore lands.</code> Your browser code’s <code>firebase/firestore</code>
+is fully supported: only the server-side admin arm is pending.</li>
+<li><strong>Storage is single-bucket.</strong> <code>bucket('other')</code> throws:
+<code>pyric-admin/storage: the remote (browser) sandbox has a single bucket — bucket('other') cannot be isolated. Use bucket() (the default 'pyric-default' bucket) instead.</code></li>
+<li><strong>8 MiB per-op cap, no streams.</strong> An oversized <code>save()</code> throws
+<code>…is 9437184 bytes — over the 8 MiB remote storage op cap. Streaming/ resumable transfers are not supported on the sandbox backend; split the object or keep it under the cap.</code> <code>createReadStream</code>/<code>createWriteStream</code>
+throw with the same remedy (<code>use file.download() (≤ 8 MiB) instead</code>).</li>
+<li><strong><code>getSignedUrl</code> is a deterministic local stub</strong>: it returns
+<code>pyric-sandbox-storage://pyric-default/&#x3C;path>?expires=…&#x26;action=…</code> and
+the sandbox does <strong>not</strong> serve that URL. It exists so code that
+round-trips signed URLs (logs, fixtures) sees a stable shape.</li>
+<li><strong>Tokens are sandbox-local.</strong> <code>createCustomToken</code> mints a deterministic
+sandbox token and <code>verifyIdToken</code> only accepts tokens minted by a pyric
+sandbox: not real Firebase JWTs.</li>
+<li><strong><code>getUser</code>/<code>getUserByEmail</code> go through <code>listUsers</code></strong> plus a client-side
+filter, fine at sandbox scale, worth knowing if you list thousands of
+users in a loop.</li>
+<li><strong>Missing downloads match prod’s message shape:</strong> <code>No such object: pyric-default/missing.bin</code>, so <code>catch</code> blocks that string-match keep
+working. <code>file.delete()</code> on a missing object is a no-op.</li>
+</ul>
+<p>Everything unsupported <strong>throws a remediating error</strong> naming what to do
+instead; nothing silently no-ops.</p>
+<h2 id="escape-hatches">Escape hatches</h2>
+<p><strong>Your own process manager</strong> (foreman, turborepo, docker-compose, a
+second terminal): skip the child runner and set the two env vars
+yourself, with <code>pyric dev --bridge --no-run</code> (or any <code>pyric dev --bridge</code>)
+running elsewhere:</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:#E06C75">PYRIC_SANDBOX</span><span style="color:#56B6C2">=</span><span style="color:#98C379">remote</span><span style="color:#61AFEF"> \</span></span>
+<span class="line"><span style="color:#ABB2BF">NODE_OPTIONS=</span><span style="color:#98C379">"--import @pyric/cli/register"</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#ABB2BF">node </span><span style="color:#98C379">server.mjs</span></span></code></pre>
+<p><code>PYRIC_SANDBOX=remote</code> auto-discovers the running dev server via
+<code>.pyric/serve.json</code> in your project (written when <code>--bridge</code> is on);
+<code>PYRIC_SANDBOX=remote:http://localhost:3473</code> pins the URL explicitly.
+With no dev server running you get: <code>no running `pyric dev --bridge` found (looked for .pyric/serve.json in &#x3C;cwd> and the default ports) — start your dev server with the bridge enabled and retry.</code></p>
+<p><strong>Explicit wiring for tests</strong>: when you want pyric identifiers on
+purpose instead of env-var routing:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">connectRemoteSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/remote'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeApp</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin/app'</span><span style="color:#ABB2BF">;</span></span>
+<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:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin/database'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> connectRemoteSandbox</span><span style="color:#ABB2BF">(); </span><span style="color:#7F848E;font-style:italic">// fails fast if no serve/tab</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> app</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeApp</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getDatabase</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">app</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// ...assertions...</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">close</span><span style="color:#ABB2BF">();</span></span></code></pre>
+<p>An explicit config always bypasses the environment, so pyric-aware test
+code keeps full control even under <code>pyric dev</code>.</p>
+<p><strong>Production guard.</strong> Under <code>NODE_ENV=production</code> both the loader and
+<code>pyric-admin</code> refuse to route to a sandbox: the loader prints
+<code>@pyric/cli/register: refusing to activate under NODE_ENV=production — firebase-admin/firebase imports are NOT rewritten.</code> and your app talks to
+real Firebase. Set <code>PYRIC_SANDBOX_FORCE=1</code> to override (dev/CI only).</p>
+<h2 id="troubleshooting">Troubleshooting</h2>
+<ul>
+<li><strong><code>no browser tab is connected to the sandbox — open http://localhost:3473 in a browser and retry.</code></strong> The backend is browser-resident. Open the
+printed URL (auto-open is suppressed under <code>--json</code>, <code>--no-open</code>, no
+TTY, and CI). The failure isn’t latched: the next call retries. A
+server that fires Firebase calls at boot can race the tab load: the
+first request after the tab is open succeeds.</li>
+<li><strong><code>Unknown method: … — the running sandbox may predate this feature; restart pyric dev and reload the browser tab.</code></strong> A SharedWorker
+survives serve restarts and can’t hot-update. Restart <code>pyric dev</code>,
+then close/reload every tab of the app so the new worker loads.</li>
+<li><strong>Always use the printed URL.</strong> <code>http://localhost:3473</code> and
+<code>http://127.0.0.1:3473</code> are <em>different browser origins</em> with separate
+SharedWorkers: opening the wrong one splits your backend in two.</li>
+<li><strong>Where’s my data?</strong> Ephemeral by default: it lives in the browser
+worker, survives tab reloads, and stops being served the moment no page
+is open. <code>pyric dev --persist</code> additionally writes a committable
+<code>.pyric/state/state.json</code> (Firestore docs + auth users) restored on the
+next run, see the <a href="../pyric-cli-reference-cli/#pyric-dev">CLI reference</a>.</li>
+<li><strong><code>this Node version lacks module.registerHooks (needs >= 22.15)</code></strong> On
+older Nodes ESM imports are still rewritten but CJS
+<code>require('firebase-admin')</code> is not, so a CJS app half-connects. Upgrade
+Node to ≥ 22.15.</li>
+</ul>
+<h2 id="where-next">Where next</h2>
+<ul>
+<li><strong>Every <code>pyric dev</code> flag</strong> (<code>--persist</code>, <code>--seed</code>, <code>--ui</code>, <code>--json</code>, …):
+the <a href="../pyric-cli-reference-cli/">CLI reference</a>.</li>
+<li><strong>New app instead of an existing one:</strong>
+<a href="../start-building/">getting started</a>.</li>
+<li><strong>Let an agent drive the same sandbox</strong> over MCP:
+<a href="../pyric-cli-tutorials-wire-claude-code/">wire-claude-code.md</a>.</li>
+</ul>  </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="#prerequisites">Prerequisites</a> </li><li data-depth="2"> <a href="#step-1-install">Step 1: Install</a> </li><li data-depth="2"> <a href="#step-2-run-it">Step 2: Run it</a> </li><li data-depth="2"> <a href="#how-it-works">How it works</a> </li><li data-depth="2"> <a href="#what-works-remotely-today">What works remotely today</a> </li><li data-depth="2"> <a href="#escape-hatches">Escape hatches</a> </li><li data-depth="2"> <a href="#troubleshooting">Troubleshooting</a> </li><li data-depth="2"> <a href="#where-next">Where next</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-tutorials-server-adoption.md ADDED Viewed

@@ -0,0 +1,251 @@
+# Run your firebase-admin app on the pyric sandbox
+You have an existing Node server that uses `firebase-admin`: Realtime
+Database, Auth, Storage. By the end of this tutorial it runs against the
+**pyric in-browser sandbox** with **zero code changes**: no pyric imports,
+no config edits, no emulator suite, no Firebase project.
+Takes about five minutes.
+## Prerequisites
+- **Node ≥ 22.15** for full coverage. ESM-only apps work on earlier 22.x,
+  but rewriting CJS `require('firebase-admin')` needs 22.15's sync module
+  hooks (older Nodes print a warning and skip CJS, see
+  [Troubleshooting](#troubleshooting)).
+- A server using `firebase-admin` (RTDB / Auth / Storage). A
+  `firebase.json` is optional: without one, `pyric dev` warns and serves
+  the current directory.
+## Step 1: Install
+```bash
+npm i -D @pyric/cli
+```
+`@pyric/cli` provides the CLI and Node resolver; its sandbox mirror
+dependencies are installed with it. None of them appear in your app code.
+## Step 2: Run it
+```bash
+npx pyric dev
+```
+`pyric dev` starts the sandbox host and then runs **your own `dev`
+script** with the environment activated (or run an explicit command:
+`npx pyric dev -- node server.mjs`). Whenever it runs your server,
+`pyric dev` also mounts the WebSocket relay the server's Firebase
+calls travel through, no extra flag needed.
+Your server needs nothing pyric-shaped. This works as-is:
+```js
+// server.mjs — zero pyric identifiers
+import { createServer } from 'node:http';
+import { initializeApp } from 'firebase-admin/app';
+import { getDatabase } from 'firebase-admin/database';
+import { getAuth } from 'firebase-admin/auth';
+import { getStorage } from 'firebase-admin/storage';
+initializeApp();
+const db = getDatabase();
+const auth = getAuth();
+const bucket = getStorage().bucket();
+createServer(async (req, res) => {
+  if (req.url === '/signup') {
+    const user = await auth.createUser({ email: `u${Date.now()}@example.com`, password: 'hunter22' });
+    await db.ref(`profiles/${user.uid}`).set({ plan: 'free' });
+    await bucket.file(`avatars/${user.uid}.txt`).save('placeholder avatar');
+    res.end(JSON.stringify({ uid: user.uid }));
+    return;
+  }
+  res.end('ok');
+}).listen(8080, () => console.log('api listening on http://localhost:8080'));
+```
+The terminal shows the host banner, then your dev command's output
+prefixed with `[dev]`:
+```
+=== Serving from '/Users/you/code/your-app'...
+✔ hosting  Serving files from: public
+✔ hosting  Local server: http://localhost:3473
+✔ sandbox  pyric SDK bundles ready (cache)
+• rules    no firestore.rules — sandbox runs with default rules
+• rules    no database.rules — RTDB sandbox runs with default rules
+✔ bridge   MCP endpoint: http://localhost:3473/__pyric/mcp (sandbox peers over ws at /__pyric/sandbox)
+✔ capture  session → /Users/you/code/your-app/.pyric/last-session.json (run `pyric verify` to replay it)
+  ⚠ the pyric sandbox runs IN the served page — keep the browser tab open.
+    Firestore/auth data and persistence stop when no page is open.
+✔ run      `npm run dev` — firebase-admin/firebase imports are routed to the sandbox at http://localhost:3473
+[dev] @pyric/cli/register: active — firebase-admin/firebase imports now resolve to the pyric sandbox (PYRIC_SANDBOX=remote:http://localhost:3473).
+[dev]
+[dev] > dev
+[dev] > node server.mjs
+[dev]
+[dev] @pyric/cli/register: active — firebase-admin/firebase imports now resolve to the pyric sandbox (PYRIC_SANDBOX=remote:http://localhost:3473).
+[dev] pyric: firebase-admin routed to sandbox at http://localhost:3473
+[dev] api listening on http://localhost:8080
+```
+(The `register: active` line appears once per Node process; `npm run
+dev` is itself a Node process, so seeing it twice is normal.)
+A browser tab on <http://localhost:3473> auto-opens: **it is the
+backend**, so keep it open. Now:
+```bash
+curl http://localhost:8080/signup
+# {"uid":"user-1"}
+```
+That user, the RTDB profile, and the stored avatar all landed in the
+sandbox your browser tab hosts. Run with `--ui` instead and Pyric Studio
+(`http://localhost:3473/__pyric/ui/`) shows the data live as your server
+writes it (`--ui` implies `--bridge`).
+## How it works
+Three small pieces, nothing hidden:
+1. **Activator**: `pyric dev` runs your dev command with
+   `PYRIC_SANDBOX=remote:<serve url>` set and
+   `--import @pyric/cli/register` appended to `NODE_OPTIONS`.
+2. **Loader**: `@pyric/cli/register` rewrites module resolution:
+   `firebase-admin/*` → `pyric-admin/*` and `firebase/*` → `pyric/*`,
+   every subpath 1:1. Without `PYRIC_SANDBOX` it is completely inert, so
+   canonical imports resolve to `firebase-admin` directly and `pyric-admin`
+   never loads.
+3. **Bridge**: each Firebase call becomes an op relayed over a local
+   WebSocket to `pyric dev`, then into the browser tab, where the sandbox
+   runs in a SharedWorker. Your server, the page's `firebase/*` code,
+   Studio, and any MCP agent all operate on the **same** backend.
+Because the backend lives in the browser, the tab must stay open. Close
+every tab and server calls fail fast with guidance (never a silent no-op).
+## What works remotely today
+| Service | Works | Not yet (throws a clear error) |
+|---|---|---|
+| **Realtime Database** | `ref().get/set/update/remove/push`, `once('value')`, `on('value')` live listeners; `update()` is a real multi-path update; `push().key` is sync | other event types (`child_added`, …), queries (`orderBy*`, `limitTo*`, …), `transaction`, `onDisconnect`, priorities |
+| **Auth (admin)** | `createUser`, `updateUser` (displayName / email / password / disabled / emailVerified), `deleteUser`, `listUsers`, `getUser` / `getUserByEmail`, `setCustomUserClaims`, `createCustomToken` / `verifyIdToken` | `getUserByPhoneNumber`, bulk ops (`getUsers`, `deleteUsers`, `importUsers`), session cookies, action links, provider configs, `revokeRefreshTokens` |
+| **Storage** | `file().save/download/delete/exists` up to **8 MiB per object**, `getSignedUrl` (local stub), single default bucket | streams (`createReadStream`/`createWriteStream`), resumable uploads, named buckets, copy/move, ACL/IAM |
+| **Firestore (admin)** | none | everything (coming; see below) |
+Behavior notes you will actually hit. Each error below is quoted from a
+real run:
+- **Firestore admin isn't relayed yet.** `getFirestore()` on the sandbox
+  throws: `pyric-admin/firestore: Firestore is not yet supported on a
+  remote sandbox — the bridge currently carries Realtime Database and
+  Auth. Use pyric/firestore in the browser (or the MCP Firestore tools)
+  until remote Firestore lands.` Your browser code's `firebase/firestore`
+  is fully supported: only the server-side admin arm is pending.
+- **Storage is single-bucket.** `bucket('other')` throws:
+  `pyric-admin/storage: the remote (browser) sandbox has a single bucket —
+  bucket('other') cannot be isolated. Use bucket() (the default
+  'pyric-default' bucket) instead.`
+- **8 MiB per-op cap, no streams.** An oversized `save()` throws
+  `…is 9437184 bytes — over the 8 MiB remote storage op cap. Streaming/
+  resumable transfers are not supported on the sandbox backend; split the
+  object or keep it under the cap.` `createReadStream`/`createWriteStream`
+  throw with the same remedy (`use file.download() (≤ 8 MiB) instead`).
+- **`getSignedUrl` is a deterministic local stub**: it returns
+  `pyric-sandbox-storage://pyric-default/<path>?expires=…&action=…` and
+  the sandbox does **not** serve that URL. It exists so code that
+  round-trips signed URLs (logs, fixtures) sees a stable shape.
+- **Tokens are sandbox-local.** `createCustomToken` mints a deterministic
+  sandbox token and `verifyIdToken` only accepts tokens minted by a pyric
+  sandbox: not real Firebase JWTs.
+- **`getUser`/`getUserByEmail` go through `listUsers`** plus a client-side
+  filter, fine at sandbox scale, worth knowing if you list thousands of
+  users in a loop.
+- **Missing downloads match prod's message shape:** `No such object:
+  pyric-default/missing.bin`, so `catch` blocks that string-match keep
+  working. `file.delete()` on a missing object is a no-op.
+Everything unsupported **throws a remediating error** naming what to do
+instead; nothing silently no-ops.
+## Escape hatches
+**Your own process manager** (foreman, turborepo, docker-compose, a
+second terminal): skip the child runner and set the two env vars
+yourself, with `pyric dev --bridge --no-run` (or any `pyric dev --bridge`)
+running elsewhere:
+```bash
+PYRIC_SANDBOX=remote \
+NODE_OPTIONS="--import @pyric/cli/register" \
+node server.mjs
+```
+`PYRIC_SANDBOX=remote` auto-discovers the running dev server via
+`.pyric/serve.json` in your project (written when `--bridge` is on);
+`PYRIC_SANDBOX=remote:http://localhost:3473` pins the URL explicitly.
+With no dev server running you get: ``no running `pyric dev --bridge`
+found (looked for .pyric/serve.json in <cwd> and the default ports) —
+start your dev server with the bridge enabled and retry.``
+**Explicit wiring for tests**: when you want pyric identifiers on
+purpose instead of env-var routing:
+```ts
+import { connectRemoteSandbox } from '@pyric/cli/remote';
+import { initializeApp } from 'pyric-admin/app';
+import { getDatabase } from 'pyric-admin/database';
+const sandbox = await connectRemoteSandbox(); // fails fast if no serve/tab
+const app = initializeApp({ sandbox });
+const db = getDatabase(app);
+// ...assertions...
+sandbox.close();
+```
+An explicit config always bypasses the environment, so pyric-aware test
+code keeps full control even under `pyric dev`.
+**Production guard.** Under `NODE_ENV=production` both the loader and
+`pyric-admin` refuse to route to a sandbox: the loader prints
+`@pyric/cli/register: refusing to activate under NODE_ENV=production —
+firebase-admin/firebase imports are NOT rewritten.` and your app talks to
+real Firebase. Set `PYRIC_SANDBOX_FORCE=1` to override (dev/CI only).
+## Troubleshooting
+- **`no browser tab is connected to the sandbox — open http://localhost:3473
+  in a browser and retry.`** The backend is browser-resident. Open the
+  printed URL (auto-open is suppressed under `--json`, `--no-open`, no
+  TTY, and CI). The failure isn't latched: the next call retries. A
+  server that fires Firebase calls at boot can race the tab load: the
+  first request after the tab is open succeeds.
+- **`Unknown method: … — the running sandbox may predate this feature;
+  restart pyric dev and reload the browser tab.`** A SharedWorker
+  survives serve restarts and can't hot-update. Restart `pyric dev`,
+  then close/reload every tab of the app so the new worker loads.
+- **Always use the printed URL.** `http://localhost:3473` and
+  `http://127.0.0.1:3473` are *different browser origins* with separate
+  SharedWorkers: opening the wrong one splits your backend in two.
+- **Where's my data?** Ephemeral by default: it lives in the browser
+  worker, survives tab reloads, and stops being served the moment no page
+  is open. `pyric dev --persist` additionally writes a committable
+  `.pyric/state/state.json` (Firestore docs + auth users) restored on the
+  next run, see the [CLI reference](../pyric-cli-reference-cli/#pyric-dev).
+- **`this Node version lacks module.registerHooks (needs >= 22.15)`** On
+  older Nodes ESM imports are still rewritten but CJS
+  `require('firebase-admin')` is not, so a CJS app half-connects. Upgrade
+  Node to ≥ 22.15.
+## Where next
+- **Every `pyric dev` flag** (`--persist`, `--seed`, `--ui`, `--json`, …):
+  the [CLI reference](../pyric-cli-reference-cli/).
+- **New app instead of an existing one:**
+  [getting started](../start-building/).
+- **Let an agent drive the same sandbox** over MCP:
+  [wire-claude-code.md](../pyric-cli-tutorials-wire-claude-code/).