@pyric/cli 0.1.0-alpha.30.2 → 0.1.0-alpha.31

package/dist/serve/site-ui/docs/reference/cli/index.html

@@ -20,7 +20,7 @@ html{scrollbar-gutter:stable}
 <p>The child receives <code>PYRIC_SANDBOX</code> and a <code>NODE_OPTIONS</code> import for <code>@pyric/cli/register</code>. This routes supported <code>firebase-admin/*</code> imports to the sandbox host. With <code>--hosted</code>, <code>firebase/database</code>, <code>firebase/firestore</code>, <code>firebase/auth</code> and <code>firebase/storage</code> in the child reach the Node host as the child’s own signed-in user; other client SDKs, and client SDKs against the browser-hosted sandbox, fail with <code>failed-precondition</code>. A <code>firebase-admin/*</code> subpath the sandbox does not mirror, such as <code>firebase-admin/remote-config</code> or <code>firebase-admin/security-rules</code>, still resolves and returns an <code>App</code>-bound handle from <code>get&#x3C;Service>(app)</code>, so module-level initialization loads cleanly while calling a method on that handle fails with <code>PyricDeferredApiError</code>. The import never reaches the real <code>firebase-admin</code>.</p>
 <h2 id="run-a-command-on-a-running-host">Run a command on a running host</h2>
 <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>pyric run [--sandbox &#x3C;url>] [--wait[=&#x3C;seconds>]] -- &#x3C;command...></span></span></code></pre>
-<p><code>pyric run</code> starts one command against a host that is already running, such as a Vite dev server with the Pyric plugin or a <code>pyric sandbox</code> in another terminal. The command gets the environment <code>pyric sandbox</code> gives its child: <code>PYRIC_SANDBOX=remote:&#x3C;url></code>, <code>PYRIC_SANDBOX_INSTANCE</code> naming that host, and a <code>NODE_OPTIONS</code> import of <code>@pyric/cli/register</code>. <code>--sandbox</code> names the host. Without it, <code>pyric run</code> uses an inherited <code>PYRIC_SANDBOX=remote:&#x3C;url></code>, then the <code>.pyric/serve.json</code> that the host wrote in the project directory. With <code>--wait</code>, it polls the host’s <code>/__pyric/health</code> until the host answers, for 30 seconds or the number of seconds given (<code>--wait=60</code>), so a command started alongside the dev server does not race it. It exits with the command’s exit code, or <code>2</code> when no host answers in time.</p>
+<p><code>pyric run</code> starts one command against a host that is already running, such as a Vite dev server with <code>pyric({ hosted: true })</code> in <code>vite.config.ts</code> or a <code>pyric sandbox --hosted</code> in another terminal. A Vite dev server with the in-page plugin, <code>pyric()</code> with no <code>hosted</code>, has no host: <code>pyric run</code> exits with <code>2</code> at once and names <code>pyric({ hosted: true })</code>. The command gets the environment <code>pyric sandbox</code> gives its child: <code>PYRIC_SANDBOX=remote:&#x3C;url></code>, <code>PYRIC_SANDBOX_INSTANCE</code> naming that host, and a <code>NODE_OPTIONS</code> import of <code>@pyric/cli/register</code>. <code>--sandbox</code> names the host. Without it, <code>pyric run</code> uses an inherited <code>PYRIC_SANDBOX=remote:&#x3C;url></code>, then the <code>.pyric/serve.json</code> that the host wrote in the project directory. With <code>--wait</code>, it polls the host’s <code>/__pyric/health</code> until the host answers, for 30 seconds or the number of seconds given (<code>--wait=60</code>), so a command started alongside the dev server does not race it. It exits with the command’s exit code, or <code>2</code> when no host answers in time.</p>
 <p>The register module is passed by absolute <code>file:</code> URL, resolved from the <code>pyric</code> install that runs the command, as <code>pyric sandbox</code> passes it. So the command can run from a directory where <code>@pyric/cli</code> does not resolve by name, such as a backend beside a <code>tools/</code> folder that pins Pyric:</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:#56B6C2">cd</span><span style="color:#98C379"> backend</span><span style="color:#ABB2BF"> &#x26;&#x26; </span><span style="color:#56B6C2">.</span><span style="color:#98C379">./tools/node_modules/.bin/pyric</span><span style="color:#98C379"> run</span><span style="color:#D19A66"> --sandbox</span><span style="color:#98C379"> http://localhost:5173</span><span style="color:#D19A66"> --</span><span style="color:#98C379"> node</span><span style="color:#98C379"> dist/index.js</span></span></code></pre>
 <p>A Vite config in another folder loads the plugin from that install the same way:</p>
@@ -143,9 +143,10 @@ html{scrollbar-gutter:stable}
 <p><code>owners</code> sets which application frames Pyric records for each listener and SDK call: <code>skip</code> lists globs for the app’s data-layer wrapper modules, whose frames are never shown first, and <code>frames</code> is how many application frames to keep (default <code>3</code>). See <a href="../../build/inspect-activity/#name-the-code-behind-a-data-layer-wrapper">Name the code behind a data-layer wrapper</a>.</p>
 <p>Command-line values override <code>pyric.json</code>. <code>--project</code> overrides <code>PYRIC_PROJECT</code>, and <code>PYRIC_PROJECT</code> overrides the configured project. Without any of them, the project is the one <code>firebase use</code> made active for this directory or a parent directory, then the only <code>.firebaserc</code> alias, else <code>.firebaserc</code> <code>projects.default</code>, as the Firebase CLI resolves it.</p>
 <h2 id="environment-variables">Environment variables</h2>
-<p><code>PYRIC_GUARD</code> selects what the network guard does when a Pyric-launched process opens a connection to a live Google or Firebase endpoint. A sandboxed app routes its Firebase traffic to the local <code>/__pyric/*</code> namespace, so such a connection reaches production: the process may be doing that on purpose, alongside the sandbox, or by accident. The value is <code>warn</code> (the default: report the connection on stderr, naming the service it reached, and let it through), <code>block</code> (report it and fail the request), or <code>off</code> (install no hooks at all and print one notice saying so). An unset, empty, or unrecognized value means <code>warn</code>, except in the Vite plugin’s dev server process, where an unset or empty value means <code>block</code>: nothing in that process is meant to reach live Firebase, and Firebase code the plugin does not swap there, such as a package that imports <code>firebase</code> itself, would (<a href="https://github.com/davideast/pyric/issues/1123" target="_blank" rel="noopener noreferrer" class="external-link">#1123</a>). Under <code>block</code>, each refusal names the two ways to let that host through: add it to <code>PYRIC_GUARD_ALLOW</code>, or set <code>PYRIC_GUARD=warn</code>, and the GCE metadata server is refused whatever <code>PYRIC_GUARD_ALLOW</code> says.</p>
+<p><code>PYRIC_GUARD</code> selects what the network guard does when a Pyric-launched process opens a connection to a live Google or Firebase endpoint. A sandboxed app routes its Firebase traffic to the local <code>/__pyric/*</code> namespace, so such a connection reaches production: the process may be doing that on purpose, alongside the sandbox, or by accident. The value is <code>warn</code> (the default: report the connection on stderr, naming the service it reached, and let it through), <code>block</code> (report it and fail the request), or <code>off</code> (install no hooks at all and print one notice saying so). An unset, empty, or unrecognized value means <code>warn</code>, except in the Vite plugin’s dev server process, where an unset or empty value means <code>block</code>: nothing in that process is meant to reach live Firebase, and Firebase code the plugin does not swap there, such as a package that imports <code>firebase</code> itself, would (<a href="https://github.com/davideast/pyric/issues/1123" target="_blank" rel="noopener noreferrer" class="external-link">#1123</a>). The same holds in the Next dev server that <code>withPyric</code> wraps: there an unset or empty value means <code>block</code>, and <code>withPyric</code> passes <code>PYRIC_GUARD=block</code> to the processes Next starts (<a href="https://github.com/davideast/pyric/issues/1443" target="_blank" rel="noopener noreferrer" class="external-link">#1443</a>). Under <code>block</code>, each refusal names the two ways to let that host through: add it to <code>PYRIC_GUARD_ALLOW</code>, or set <code>PYRIC_GUARD=warn</code>, and the GCE metadata server is refused whatever <code>PYRIC_GUARD_ALLOW</code> says.</p>
+<p>In any process the register activates, an import that resolves into the real <code>firebase-admin</code> fails before the file loads, with the error code <code>PYRIC_REAL_SDK_STOPPED</code>. The register routes every <code>firebase-admin</code> import it recognizes to the sandbox, so a real <code>firebase-admin</code> there is an import it missed, such as an absolute path, an npm alias, or a link under another name, and it would run with your machine’s credentials. The same holds for the real <code>firebase</code> and <code>@firebase/*</code> packages, except where pyric uses the real SDK on purpose: <code>firebase/ai</code> in production AI mode, and the <code>firebase/app</code> and <code>firebase/app-check</code> it attaches to. Only the import that asked fails, and the log names the import, the file that imported it, the file it resolved to, and the import to write instead. The register finds the package from the <code>package.json</code> it ships, not from its folder name. <code>PYRIC_GUARD</code> doesn’t change this, <code>off</code> included, and it applies in every worker thread the process starts. It also applies in every Node child process the process starts: the register adds itself to the child’s <code>NODE_OPTIONS</code> and copies in the <code>PYRIC_*</code> variables the child’s environment lacks, whatever <code>env</code> or <code>execArgv</code> the child is given. A shell command that sets its own <code>NODE_OPTIONS</code>, as in <code>NODE_OPTIONS=--max-old-space-size=4096 node server.js</code>, replaces it. Append to the inherited value instead: <code>NODE_OPTIONS="$NODE_OPTIONS --max-old-space-size=4096"</code>. To run the real SDK, start that process outside a registered process, without <code>@pyric/cli/register</code>. On Node versions older than 22.15, which <code>@pyric/cli</code> doesn’t support, this applies to <code>import</code> only, not to <code>require</code>.</p>
 <p><code>PYRIC_GUARD_ALLOW</code> permits specific hosts that the guard would otherwise flag, so they are reported as permitted, and pass under <code>block</code>. It takes a comma-separated or whitespace-separated list of hostnames or URLs, matched on label boundaries, so <code>cloudfunctions.net</code> also permits <code>us-central1-demo.cloudfunctions.net</code>. Set it when a project deliberately calls a Google endpoint that Pyric does not mirror, such as a Vertex AI base URL. <code>pyric sandbox</code> appends the host of <code>PYRIC_AI_PROXY_UPSTREAM</code> to the value it passes to the command it runs, and the Vite plugin permits the AI upstream in its own options, so a Vertex AI upstream set either way needs no separate entry. An allowed host is still reported once. Under <code>block</code>, the GCE metadata server cannot be allowed.</p>
-<p><code>PYRIC_SANDBOX</code> activates <code>@pyric/cli/register</code> in a process and says which sandbox host it uses. Set it to <code>remote</code> in <code>.env</code> files, package scripts, and agent configuration. With <code>remote</code>, the process finds the running host through the <code>.pyric/serve.json</code> file that <code>pyric sandbox</code> and the Vite plugin write in the project directory, so it follows the host to whatever port it takes, on any machine. <code>pyric sandbox</code> prints <code>export PYRIC_SANDBOX=remote</code> for a command you start yourself. Use <code>remote:&#x3C;url></code> only for a process that runs outside the project directory, where <code>.pyric/serve.json</code> cannot be found. If nothing answers at that url, or a different host answers there, the process warns once and uses this project’s running host when <code>.pyric/serve.json</code> names one. Otherwise it fails and says the url is stale. It never attaches to a host that no <code>.pyric/serve.json</code> in the project names.</p>
+<p><code>PYRIC_SANDBOX</code> activates <code>@pyric/cli/register</code> in a process and says which sandbox host it uses. Set it to <code>remote</code> in <code>.env</code> files, package scripts, and agent configuration. The variable alone doesn’t load the register: the process also needs <code>--import @pyric/cli/register</code> in its <code>NODE_OPTIONS</code>, which <code>pyric sandbox</code> adds. <code>withPyric</code> refuses to start <code>next dev</code> when <code>PYRIC_SANDBOX</code> is set and the register isn’t active, as when the variable comes only from a <code>.env</code> file that Next reads, when <code>NODE_ENV=production</code> makes the register refuse, or when a package script replaces <code>NODE_OPTIONS</code>. With <code>remote</code>, the process finds the running host through the <code>.pyric/serve.json</code> file that <code>pyric sandbox</code> and the Vite plugin write in the project directory, so it follows the host to whatever port it takes, on any machine. <code>pyric sandbox</code> prints <code>export PYRIC_SANDBOX=remote</code> for a command you start yourself. Use <code>remote:&#x3C;url></code> only for a process that runs outside the project directory, where <code>.pyric/serve.json</code> cannot be found. If nothing answers at that url, or a different host answers there, the process warns once and uses this project’s running host when <code>.pyric/serve.json</code> names one. Otherwise it fails and says the url is stale. It never attaches to a host that no <code>.pyric/serve.json</code> in the project names.</p>
 <p><code>PYRIC_SANDBOX_INSTANCE</code> is set by <code>pyric sandbox</code> and the Vite plugin’s Functions runtime on every child they start, beside <code>PYRIC_SANDBOX=remote:&#x3C;url></code>. It names the host at that url, so the child attaches there from any working directory. You do not set it yourself.</p>
 <p><code>PYRIC_BEACON_TOKEN</code> is set by <code>pyric sandbox</code> on every child it starts. A child that has loaded <code>@pyric/cli/register</code> presents it when it reports that interception is installed, and the server rejects a report without it. A process you start yourself has no token, so the server does not count its report.</p>
 <p><code>PYRIC_AVATARS</code> selects the profile-photo source for provider-created auth users. Unset, provider sign-ins get a deterministic generated avatar. <code>0</code> and <code>false</code> disable avatars, matching Firebase’s own behaviour for a provider that supplies no photo. Any other value names a pre-built avatar set directory, resolved from the project root. There is no <code>--avatars</code> flag; <code>pyric sandbox</code> reads this variable only, one tier short of the Vite plugin’s <code>avatars</code> option, which also accepts a custom generation source. See <a href="../../build/default-avatars/">Assign default avatars to sandbox users</a>.</p>

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

@@ -33,7 +33,7 @@ The child receives `PYRIC_SANDBOX` and a `NODE_OPTIONS` import for `@pyric/cli/r
 pyric run [--sandbox <url>] [--wait[=<seconds>]] -- <command...>
 ```
 
-`pyric run` starts one command against a host that is already running, such as a Vite dev server with the Pyric plugin or a `pyric sandbox` in another terminal. The command gets the environment `pyric sandbox` gives its child: `PYRIC_SANDBOX=remote:<url>`, `PYRIC_SANDBOX_INSTANCE` naming that host, and a `NODE_OPTIONS` import of `@pyric/cli/register`. `--sandbox` names the host. Without it, `pyric run` uses an inherited `PYRIC_SANDBOX=remote:<url>`, then the `.pyric/serve.json` that the host wrote in the project directory. With `--wait`, it polls the host's `/__pyric/health` until the host answers, for 30 seconds or the number of seconds given (`--wait=60`), so a command started alongside the dev server does not race it. It exits with the command's exit code, or `2` when no host answers in time.
+`pyric run` starts one command against a host that is already running, such as a Vite dev server with `pyric({ hosted: true })` in `vite.config.ts` or a `pyric sandbox --hosted` in another terminal. A Vite dev server with the in-page plugin, `pyric()` with no `hosted`, has no host: `pyric run` exits with `2` at once and names `pyric({ hosted: true })`. The command gets the environment `pyric sandbox` gives its child: `PYRIC_SANDBOX=remote:<url>`, `PYRIC_SANDBOX_INSTANCE` naming that host, and a `NODE_OPTIONS` import of `@pyric/cli/register`. `--sandbox` names the host. Without it, `pyric run` uses an inherited `PYRIC_SANDBOX=remote:<url>`, then the `.pyric/serve.json` that the host wrote in the project directory. With `--wait`, it polls the host's `/__pyric/health` until the host answers, for 30 seconds or the number of seconds given (`--wait=60`), so a command started alongside the dev server does not race it. It exits with the command's exit code, or `2` when no host answers in time.
 
 The register module is passed by absolute `file:` URL, resolved from the `pyric` install that runs the command, as `pyric sandbox` passes it. So the command can run from a directory where `@pyric/cli` does not resolve by name, such as a backend beside a `tools/` folder that pins Pyric:
 
@@ -130,11 +130,13 @@ Command-line values override `pyric.json`. `--project` overrides `PYRIC_PROJECT`
 
 ## Environment variables
 
-`PYRIC_GUARD` selects what the network guard does when a Pyric-launched process opens a connection to a live Google or Firebase endpoint. A sandboxed app routes its Firebase traffic to the local `/__pyric/*` namespace, so such a connection reaches production: the process may be doing that on purpose, alongside the sandbox, or by accident. The value is `warn` (the default: report the connection on stderr, naming the service it reached, and let it through), `block` (report it and fail the request), or `off` (install no hooks at all and print one notice saying so). An unset, empty, or unrecognized value means `warn`, except in the Vite plugin's dev server process, where an unset or empty value means `block`: nothing in that process is meant to reach live Firebase, and Firebase code the plugin does not swap there, such as a package that imports `firebase` itself, would ([#1123](https://github.com/davideast/pyric/issues/1123)). Under `block`, each refusal names the two ways to let that host through: add it to `PYRIC_GUARD_ALLOW`, or set `PYRIC_GUARD=warn`, and the GCE metadata server is refused whatever `PYRIC_GUARD_ALLOW` says.
+`PYRIC_GUARD` selects what the network guard does when a Pyric-launched process opens a connection to a live Google or Firebase endpoint. A sandboxed app routes its Firebase traffic to the local `/__pyric/*` namespace, so such a connection reaches production: the process may be doing that on purpose, alongside the sandbox, or by accident. The value is `warn` (the default: report the connection on stderr, naming the service it reached, and let it through), `block` (report it and fail the request), or `off` (install no hooks at all and print one notice saying so). An unset, empty, or unrecognized value means `warn`, except in the Vite plugin's dev server process, where an unset or empty value means `block`: nothing in that process is meant to reach live Firebase, and Firebase code the plugin does not swap there, such as a package that imports `firebase` itself, would ([#1123](https://github.com/davideast/pyric/issues/1123)). The same holds in the Next dev server that `withPyric` wraps: there an unset or empty value means `block`, and `withPyric` passes `PYRIC_GUARD=block` to the processes Next starts ([#1443](https://github.com/davideast/pyric/issues/1443)). Under `block`, each refusal names the two ways to let that host through: add it to `PYRIC_GUARD_ALLOW`, or set `PYRIC_GUARD=warn`, and the GCE metadata server is refused whatever `PYRIC_GUARD_ALLOW` says.
+
+In any process the register activates, an import that resolves into the real `firebase-admin` fails before the file loads, with the error code `PYRIC_REAL_SDK_STOPPED`. The register routes every `firebase-admin` import it recognizes to the sandbox, so a real `firebase-admin` there is an import it missed, such as an absolute path, an npm alias, or a link under another name, and it would run with your machine's credentials. The same holds for the real `firebase` and `@firebase/*` packages, except where pyric uses the real SDK on purpose: `firebase/ai` in production AI mode, and the `firebase/app` and `firebase/app-check` it attaches to. Only the import that asked fails, and the log names the import, the file that imported it, the file it resolved to, and the import to write instead. The register finds the package from the `package.json` it ships, not from its folder name. `PYRIC_GUARD` doesn't change this, `off` included, and it applies in every worker thread the process starts. It also applies in every Node child process the process starts: the register adds itself to the child's `NODE_OPTIONS` and copies in the `PYRIC_*` variables the child's environment lacks, whatever `env` or `execArgv` the child is given. A shell command that sets its own `NODE_OPTIONS`, as in `NODE_OPTIONS=--max-old-space-size=4096 node server.js`, replaces it. Append to the inherited value instead: `NODE_OPTIONS="$NODE_OPTIONS --max-old-space-size=4096"`. To run the real SDK, start that process outside a registered process, without `@pyric/cli/register`. On Node versions older than 22.15, which `@pyric/cli` doesn't support, this applies to `import` only, not to `require`.
 
 `PYRIC_GUARD_ALLOW` permits specific hosts that the guard would otherwise flag, so they are reported as permitted, and pass under `block`. It takes a comma-separated or whitespace-separated list of hostnames or URLs, matched on label boundaries, so `cloudfunctions.net` also permits `us-central1-demo.cloudfunctions.net`. Set it when a project deliberately calls a Google endpoint that Pyric does not mirror, such as a Vertex AI base URL. `pyric sandbox` appends the host of `PYRIC_AI_PROXY_UPSTREAM` to the value it passes to the command it runs, and the Vite plugin permits the AI upstream in its own options, so a Vertex AI upstream set either way needs no separate entry. An allowed host is still reported once. Under `block`, the GCE metadata server cannot be allowed.
 
-`PYRIC_SANDBOX` activates `@pyric/cli/register` in a process and says which sandbox host it uses. Set it to `remote` in `.env` files, package scripts, and agent configuration. With `remote`, the process finds the running host through the `.pyric/serve.json` file that `pyric sandbox` and the Vite plugin write in the project directory, so it follows the host to whatever port it takes, on any machine. `pyric sandbox` prints `export PYRIC_SANDBOX=remote` for a command you start yourself. Use `remote:<url>` only for a process that runs outside the project directory, where `.pyric/serve.json` cannot be found. If nothing answers at that url, or a different host answers there, the process warns once and uses this project's running host when `.pyric/serve.json` names one. Otherwise it fails and says the url is stale. It never attaches to a host that no `.pyric/serve.json` in the project names.
+`PYRIC_SANDBOX` activates `@pyric/cli/register` in a process and says which sandbox host it uses. Set it to `remote` in `.env` files, package scripts, and agent configuration. The variable alone doesn't load the register: the process also needs `--import @pyric/cli/register` in its `NODE_OPTIONS`, which `pyric sandbox` adds. `withPyric` refuses to start `next dev` when `PYRIC_SANDBOX` is set and the register isn't active, as when the variable comes only from a `.env` file that Next reads, when `NODE_ENV=production` makes the register refuse, or when a package script replaces `NODE_OPTIONS`. With `remote`, the process finds the running host through the `.pyric/serve.json` file that `pyric sandbox` and the Vite plugin write in the project directory, so it follows the host to whatever port it takes, on any machine. `pyric sandbox` prints `export PYRIC_SANDBOX=remote` for a command you start yourself. Use `remote:<url>` only for a process that runs outside the project directory, where `.pyric/serve.json` cannot be found. If nothing answers at that url, or a different host answers there, the process warns once and uses this project's running host when `.pyric/serve.json` names one. Otherwise it fails and says the url is stale. It never attaches to a host that no `.pyric/serve.json` in the project names.
 
 `PYRIC_SANDBOX_INSTANCE` is set by `pyric sandbox` and the Vite plugin's Functions runtime on every child they start, beside `PYRIC_SANDBOX=remote:<url>`. It names the host at that url, so the child attaches there from any working directory. You do not set it yourself.