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

package/src/bridge/surface/types.ts

@@ -9,6 +9,7 @@
  */
 import type { LocalSandbox } from 'pyric/sandbox';
 import type { SandboxDispatch } from '../client/dispatch.js';
+import type { DatabaseInstanceCatalog } from './database-instance-catalog.js';
 import type { SurfaceIdentity } from './identity.js';
 
 /** What one operation returns. Mirrors the dispatcher's result shape. */
@@ -28,11 +29,37 @@ export interface SurfaceTargetRouter {
   ): Promise<OperationResult>;
 }
 
-/** Everything a handler is given: the sandbox, the shared dispatcher, and the caller identity. */
-export interface SurfaceContext {
+/**
+ * What a handler is given wherever the sandbox lives: the sandbox, the
+ * dispatcher over the forwarded tool families, the caller identity, and the
+ * RTDB instances a `database` method may name. A record that runs in the
+ * sandbox (`runsIn: 'sandbox'`) is given only this, so it cannot reach the
+ * project directory or a tool family that exists only in Node.
+ */
+export interface SandboxSurfaceContext {
   sandbox: LocalSandbox;
   dispatch: SandboxDispatch;
   identity: SurfaceIdentity;
+  /**
+   * The RTDB instances a `database` method may name. A host answers from the
+   * instances it serves; the bridge process reads the project's files on each
+   * call.
+   */
+  databaseInstances(): Promise<DatabaseInstanceCatalog>;
+  /**
+   * The name the served app knows its default Storage bucket by (its
+   * `storageBucket` option), when the host serving the sandbox knows it.
+   * Storage rules simulation binds it as the bucket's name.
+   */
+  storageBucketName?: () => string | undefined;
+}
+
+/**
+ * Everything a handler in the bridge process is given: the sandbox context,
+ * plus the project directory, the checkpoint store, the target router, and a
+ * dispatcher that also reaches the in-process tool families.
+ */
+export interface SurfaceContext extends SandboxSurfaceContext {
   /**
    * The directory the session's own files live under: the rules files, the
    * in-process state, and everything else below `.pyric/`. A method that reaches
@@ -41,15 +68,10 @@ export interface SurfaceContext {
    * project directory that is not where the process was started.
    */
   projectDir: string;
-  /** Dynamic target router for hosted following (ADR 0016). */
   /** Where the host keeps checkpoints, when not the project's directory. */
   checkpoints?: import('pyric/sandbox/checkpoints').CheckpointBackend;
+  /** Dynamic target router for hosted following (ADR 0016). */
   targetRouter?: SurfaceTargetRouter;
-  /**
-   * The RTDB instances a `database` method may name, when the host serving the
-   * sandbox knows them. Absent, they are read from the project's files.
-   */
-  databaseInstances?: import('./database-instance-catalog.js').DatabaseInstanceCatalog;
 }
 
 /** One tool as an MCP client sees it. */

package/src/cli/firebase-json.ts

@@ -15,11 +15,13 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 export interface FirebaseJson {
-  firestore?: {
-    rules?: string;
-    indexes?: string;
-    database?: string;
-  };
+  /**
+   * Firestore rules and indexes, as the Firebase CLI reads them: one object
+   * that deploys to its `database`, or to `(default)`, or an array whose
+   * entries each name a `database`, or a `target` that `.firebaserc` maps to
+   * databases. `firestoreRulesConfig` in `pyric/sandbox/internal` resolves it.
+   */
+  firestore?: FirestoreConfig | FirestoreConfigEntry[];
   /**
    * Realtime Database rules, as the Firebase CLI reads them: one object whose
    * `rules` file deploys to the project's default instance, or an array whose
@@ -35,6 +37,41 @@ export interface FirebaseJson {
   storage?: { rules?: string; bucket?: string } | Array<{ rules?: string; bucket?: string }>;
 }
 
+/** The single-object `firestore` form. */
+export interface FirestoreConfig {
+  rules?: string;
+  indexes?: string;
+  /** The database the object deploys to. Defaults to `(default)`. */
+  database?: string;
+}
+
+/** One entry of the array `firestore` form. */
+export interface FirestoreConfigEntry extends FirestoreConfig {
+  /** A deploy target that `.firebaserc` maps to database ids. Wins over `database`. */
+  target?: string;
+  /**
+   * Pyric's own key, never in a `firebase.json`: the rules file a Vite or
+   * `pyric.config` override serves on `(default)`. See `withDefaultFirestoreRules`.
+   */
+  pyricRulesOverride?: string;
+}
+
+/**
+ * `firestore` with `rules` served on `(default)` in place of what it names
+ * there. An object gets the `rules` key. An array gets a
+ * `{ pyricRulesOverride: rules }` entry, which `firestoreRulesConfig` applies
+ * after it resolves the array, so the override reaches `(default)` however
+ * the array deploys to it, through `database` or a `.firebaserc` target.
+ */
+export function withDefaultFirestoreRules(
+  firestore: FirebaseJson['firestore'],
+  rules: string,
+): FirestoreConfig | FirestoreConfigEntry[] {
+  if (!Array.isArray(firestore)) return { ...firestore, rules };
+  const entries = firestore.filter((entry) => entry.pyricRulesOverride === undefined);
+  return [...entries, { pyricRulesOverride: rules }];
+}
+
 /** The single-object `database` form: `rules` deploys to the default instance. */
 export interface DatabaseRulesConfig {
   rules?: string;
@@ -63,8 +100,9 @@ export interface FirebaseRc {
   /**
    * Deploy-target maps, keyed project → resource type → target name →
    * resource ids (mirrors firebase-tools' RCData,
-   * clones/firebase-tools/src/rc.ts:28-36). `hosting` (target → site ids)
-   * and `database` (target → instance names) are consumed.
+   * clones/firebase-tools/src/rc.ts:28-36). `hosting` (target → site ids),
+   * `database` (target → instance names) and `firestore` (target → database
+   * ids) are consumed.
    */
   targets?: {
     [projectId: string]: {

package/src/cli/firestore-indexes.ts

@@ -6,6 +6,7 @@ import {
 } from 'pyric/rules/internal/extract';
 import type { ParsedArgs } from './parse-args.js';
 import { readFirebaseJson, type FirebaseJson } from './firebase-json.js';
+import { defaultFirestoreDatabase, firestoreRulesConfig } from 'pyric/sandbox/internal';
 
 type ExtractResult = ReturnType<ExtractFirestoreIndexesHandler['execute']>;
 
@@ -46,7 +47,7 @@ export async function runFirestoreIndexesGenerate(
   let configuredPath: string | undefined;
   if (typeof outFlag !== 'string') {
     try {
-      configuredPath = (await (deps.readFirebaseJson ?? readFirebaseJson)(cwd)).firestore?.indexes;
+      configuredPath = defaultFirestoreDatabase(firestoreRulesConfig((await (deps.readFirebaseJson ?? readFirebaseJson)(cwd)).firestore))?.indexesFile;
     } catch {
       configuredPath = undefined;
     }

package/src/cli/index.ts

@@ -40,14 +40,38 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { parseArgs, type ParsedArgs } from './parse-args.js';
-import { runInit, runVendor } from './init.js';
-import { runSnapshot } from './snapshot.js';
-import { runVerify } from './verify.js';
-import { runMcpProxy } from './mcp-proxy.js';
 import { pyricVersion } from '../serve/standalone-assets.js';
 import { cliVersion } from '../pkg-version.js';
 import { FIREBASE_TESTED_AGAINST } from '../version/compat-target.js';
-import { dispatchServiceCommand } from './service-commands.js';
+
+// Each command's module is imported when that command runs, never at startup.
+// The service commands alone load about 500 modules, the TypeScript compiler
+// among them, which made every `pyric run` spend about 0.5 s at idle (over 3 s
+// on a loaded CI runner) before its first request (#1671).
+
+/**
+ * The commands this dispatcher runs itself that no service command starts
+ * with, so they skip loading the service command registry. `sandbox` is not
+ * here: `pyric sandbox inspect` is a service command.
+ */
+export const COMMANDS_BEFORE_SERVICES: ReadonlySet<string> = new Set([
+  'bridge',
+  'run',
+  'snapshot',
+  'verify',
+  'can-i-use',
+  'mcp',
+  'init',
+  'vendor',
+]);
+
+async function dispatchServiceCommand(parsed: ParsedArgs): Promise<number | null> {
+  const subcommand = parsed.subcommand;
+  const skipsServices = subcommand == null || COMMANDS_BEFORE_SERVICES.has(subcommand);
+  if (skipsServices) return null;
+  const services = await import('./service-commands.js');
+  return services.dispatchServiceCommand(parsed);
+}
 
 // The standalone binary bakes the real `pyric` version onto the embedded-assets
 // global; the npm bin has no such global and falls back to '0.0.0'.
@@ -86,7 +110,9 @@ USAGE
   pyric --version
 
 COMMANDS
-  bridge                     Start the HTTP+WebSocket bridge external MCP clients point at.
+  bridge                     Start an HTTP MCP server with the rules, conformance, identity
+                             and capture tools. It has no browser socket: for an agent
+                             that drives the sandbox in a page, run \`pyric sandbox --bridge\`.
   sandbox [command...]       Run an application command or script inside the local Firebase sandbox
                              with unmodified firebase/* and firebase-admin/* imports routed to the
                              in-memory mirror. When [command...] is omitted, runs the command
@@ -94,9 +120,12 @@ COMMANDS
                              A firebase.json Functions source is discovered automatically;
                              supported RTDB onValueCreated exports run in isolated Node.
   run [--sandbox URL]        Run a command against a sandbox host that is already
-                             running (a Vite dev server with the pyric plugin, or
-                             \`pyric sandbox\`), with the environment \`pyric sandbox\`
-                             gives its child. --sandbox URL names the host; without
+                             running, with the environment \`pyric sandbox\` gives
+                             its child. The host is \`pyric sandbox --hosted\`, or a
+                             Vite dev server with \`pyric({ hosted: true })\` in
+                             vite.config.ts. A Vite server with the in-page
+                             \`pyric()\` plugin has no host, so pyric run refuses it.
+                             --sandbox URL names the host; without
                              it, PYRIC_SANDBOX=remote:<url>, then .pyric/serve.json.
                              The register module is passed by absolute file URL, so
                              the command can run outside pyric's install tree.
@@ -361,11 +390,12 @@ async function runBridge(parsed: ParsedArgs): Promise<number> {
       `  project: ${handle.bridge.project}\n` +
       `  health:  ${handle.url}/health\n` +
       `  mcp:     ${handle.url}/mcp\n` +
-      `  sandbox: ${handle.url.replace('http://', 'ws://')}/sandbox\n` +
       (handle.auditLogPath ? `  audit:   ${handle.auditLogPath}\n` : '') +
       `\nRegister with Claude Code:\n` +
       `  claude mcp add --transport http pyric ${handle.url}/mcp --scope project\n` +
-      `\nBridge will log peer connect/disconnect to stderr. Set PYRIC_VERBOSE=1 for per-tool-call logs.\n` +
+      `\nThis bridge serves the tools that run in this process. A browser page cannot attach to it;\n` +
+      `for an agent that drives the sandbox in a page, run \`pyric sandbox --bridge\`.\n` +
+      `Set PYRIC_VERBOSE=1 for per-tool-call logs.\n` +
       `Press Ctrl-C to stop.\n`,
   );
 
@@ -415,17 +445,22 @@ export async function dispatch(parsed: ParsedArgs): Promise<number> {
       const { runRun } = await import('./run.js');
       return runRun(parsed);
     case 'snapshot':
+      const { runSnapshot } = await import('./snapshot.js');
       return await runSnapshot(parsed);
     case 'verify':
+      const { runVerify } = await import('./verify.js');
       return await runVerify(parsed);
     case 'can-i-use':
       const { runCanIUse } = await import('./can-i-use.js');
       return runCanIUse(parsed);
     case 'mcp':
+      const { runMcpProxy } = await import('./mcp-proxy.js');
       return await runMcpProxy(parsed);
     case 'init':
+      const { runInit } = await import('./init.js');
       return await runInit(parsed);
     case 'vendor':
+      const { runVendor } = await import('./init.js');
       return await runVendor(parsed);
     default:
       process.stderr.write(

package/src/cli/public-dir-hint.ts

@@ -0,0 +1,35 @@
+/**
+ * The hint `pyric sandbox` adds when `hosting.public` does not exist.
+ *
+ * A missing `dist/` almost always means "no build yet": the web scaffold's
+ * hosting.public is the Vite output, so the hint points at the dev and build
+ * loop. With `--hosted` in a Vite project the user wants the Node host for a
+ * Vite app, and that runs inside Vite's dev server with `pyric({ hosted: true })`
+ * (#1423); `pyric sandbox` only serves a built directory.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cts', 'vite.config.cjs'];
+
+/** The Vite config file in `cwd`, or `null` when the project has none. */
+export function viteConfigIn(cwd: string): string | null {
+  return VITE_CONFIG_FILES.find((file) => existsSync(join(cwd, file))) ?? null;
+}
+
+/** The text to append to the missing-directory error, starting with a newline, or `''`. */
+export function missingPublicDirHint(publicDir: string, opts: { cwd: string; hosted: boolean }): string {
+  const viteConfig = opts.hosted ? viteConfigIn(opts.cwd) : null;
+  if (viteConfig !== null) {
+    return (
+      `\n  For a Vite app, the Node host runs in the Vite dev server: set pyric({ hosted: true }) in ${viteConfig}, ` +
+      'then start Vite on its own, without pyric sandbox.'
+    );
+  }
+  const looksLikeBuildOutput = /(^|[\\/])(dist|build|out)$/.test(publicDir);
+  if (!looksLikeBuildOutput) return '';
+  return (
+    `\n  No build yet? Run \`bun run dev\` for the live sandbox dev server, ` +
+    `or \`bun run build\` then \`pyric sandbox\` to preview the production build.`
+  );
+}

package/src/cli/run.ts

@@ -1,7 +1,7 @@
 /**
  * `pyric run [--sandbox <url>] -- <command...>`: run one command against a
- * sandbox host that is already running, such as a Vite dev server with the
- * pyric plugin or a `pyric sandbox` in another terminal.
+ * sandbox host that is already running, such as a Vite dev server with
+ * `pyric({ hosted: true })` or a `pyric sandbox --hosted` in another terminal.
  *
  * The child gets the environment `pyric sandbox` gives its own child
  * (`buildChildEnv`): the activator, the host's identity, and `--import` with
@@ -16,7 +16,8 @@ import {
   spawnSandboxChild,
   type SandboxChildPlan,
 } from './sandbox-runner.js';
-import { discoverServe, probeHostUrl } from '../serve/discovery.js';
+import { discoverServe, probeHostUrlAnswer, servesViteClient } from '../serve/discovery.js';
+import { viteConfigIn } from './public-dir-hint.js';
 
 export interface RunInvocation {
   /** The host URL named by `--sandbox` or `PYRIC_SANDBOX=remote:<url>`; null to discover it. */
@@ -92,6 +93,24 @@ export async function pollUntil<T>(
   }
 }
 
+/**
+ * The refusal for a URL that answers but is not a sandbox host (#1568). A Vite
+ * dev server whose plugin is in-page, `pyric()` with no `hosted`, is the
+ * common one: it has no sandbox host, and `hosted: true` gives it one.
+ */
+export function notAHostMessage(hostUrl: string, isVite: boolean, viteConfig: string): string {
+  if (isVite) {
+    return (
+      `pyric run: reached a Vite server without a hosted pyric sandbox at ${hostUrl}, so it can't run this command.\n` +
+      `  Set pyric({ hosted: true }) in ${viteConfig}, restart Vite, then run this command again.\n`
+    );
+  }
+  return (
+    `pyric run: ${hostUrl} answers, but it is not a sandbox host: /__pyric/health did not return a health reply.\n` +
+    `  Start a host with pyric sandbox --hosted, or for a Vite dev server set pyric({ hosted: true }) in ${viteConfig}.\n`
+  );
+}
+
 export async function runRun(parsed: ParsedArgs): Promise<number> {
   const invocation = parseRunInvocation(parsed, process.env);
   if (typeof invocation === 'string') {
@@ -103,14 +122,23 @@ export async function runRun(parsed: ParsedArgs): Promise<number> {
   let instanceId: string | null;
   if (invocation.hostUrl !== null) {
     const hostUrl = invocation.hostUrl;
-    const host = await pollUntil(() => probeHostUrl(hostUrl), { timeoutMs: invocation.waitMs });
-    if (host === null) {
+    // A server that answers but is not a sandbox host will not become one, so only silence is waited out.
+    const answer = await pollUntil(async () => {
+      const probed = await probeHostUrlAnswer(hostUrl);
+      return probed.kind === 'no-answer' ? null : probed;
+    }, { timeoutMs: invocation.waitMs });
+    if (answer === null) {
       const waited = invocation.waitMs > 0 ? ` after waiting ${invocation.waitMs / 1000}s` : '';
       process.stderr.write(`pyric run: no sandbox host answers at ${hostUrl}/__pyric/health${waited}.\n`);
       return 2;
     }
-    serveUrl = host.base;
-    instanceId = host.instanceId;
+    if (answer.kind === 'not-a-host') {
+      const viteConfig = viteConfigIn(cwd) ?? 'vite.config.ts';
+      process.stderr.write(notAHostMessage(hostUrl, await servesViteClient(answer.base), viteConfig));
+      return 2;
+    }
+    serveUrl = answer.host.base;
+    instanceId = answer.host.instanceId;
   } else {
     const log = (line: string): void => void process.stderr.write(`pyric run: ${line}\n`);
     const host = await pollUntil(() => discoverServe(cwd, log), { timeoutMs: invocation.waitMs });

package/src/cli/sandbox-runner.ts

@@ -18,6 +18,7 @@
  */
 import { spawn, type ChildProcess } from 'node:child_process';
 import { SHELL_OPERATORS } from './unsupported-runtime.js';
+import { boundedFetch } from '../bounded-request.js';
 import type { WorkerInitPayload } from '../serve/init-payload.js';
 
 // ─── First-run race guard ───────────────────────────────────────────────────
@@ -44,12 +45,19 @@ export async function waitForSandboxPeer(
 ): Promise<boolean> {
   const timeoutMs = opts.timeoutMs ?? 30_000;
   const intervalMs = opts.intervalMs ?? 250;
-  const fetchImpl = opts.fetchImpl ?? fetch;
   const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const deadline = Date.now() + timeoutMs;
+  // By default each poll is bounded by the time left, connect included, so a
+  // health port whose connect never completes cannot carry the wait past its
+  // timeout or hold the process open after it (#1167).
+  const fetchHealth = (url: string): Promise<Response> => {
+    const injected = opts.fetchImpl;
+    if (injected) return injected(url);
+    return boundedFetch(url, { deadlineMs: Math.max(1, deadline - Date.now()) });
+  };
   for (;;) {
     try {
-      const res = await fetchImpl(`${serveUrl.replace(/\/$/, '')}/__pyric/health`);
+      const res = await fetchHealth(`${serveUrl.replace(/\/$/, '')}/__pyric/health`);
       if (res.ok) {
         const health = (await res.json()) as { sandboxConnected?: boolean };
         if (health.sandboxConnected === true) return true;

package/src/cli/serve-diagnostics.ts

@@ -1,7 +1,11 @@
 import type { ParsedArgs } from './parse-args.js';
+import { boundedFetch } from '../bounded-request.js';
 import { discoverServe } from '../serve/discovery.js';
 import { DIAGNOSTICS_PATH } from '../serve/runtime/diagnostics-report.js';
 
+/** Milliseconds the diagnostics request has, connect and body included. */
+const DIAGNOSTICS_DEADLINE_MS = 3000;
+
 export async function runServeDiagnostics(parsed: ParsedArgs, deps: {
   cwd?: string;
   stdout?: { write(value: string): void };
@@ -27,7 +31,14 @@ export async function runServeDiagnostics(parsed: ParsedArgs, deps: {
   }
   let reachedServer = false;
   try {
-    const response = await fetch(endpoint, { signal: AbortSignal.timeout(3000), redirect: 'error' });
+    // Bounded, connect included, so a port whose connect never completes
+    // cannot hold the command open past its answer (#1167). The report is
+    // read whole within the deadline, as fetch's abort covered the body too.
+    const response = await boundedFetch(endpoint, {
+      deadlineMs: DIAGNOSTICS_DEADLINE_MS,
+      maxBytes: Number.POSITIVE_INFINITY,
+      redirect: 'error',
+    });
     reachedServer = true;
     if (!response.ok) {
       print({ version: 1, server: { http: 'responding', status: response.status }, error: 'Diagnostics endpoint unavailable. Check the URL and CLI version.' });

package/src/cli/serve.ts

@@ -14,7 +14,7 @@ import { randomBytes } from 'node:crypto';
 import { join, relative, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import type { ParsedArgs } from './parse-args.js';
-import { readFirebaseJson, readFirebaseRc, type FirebaseJson } from './firebase-json.js';
+import { readFirebaseJson, readFirebaseRc, withDefaultFirestoreRules, type FirebaseJson } from './firebase-json.js';
 import { resolveFirebaseProject, type FirebaseProjectResolution } from './firebase-project.js';
 import { bundleSdk, bundleWorker, defaultSdkEntries, planProjectFirebase, resolveSiteUiDir } from '../serve/bundler.js';
 import {
@@ -38,6 +38,7 @@ import { resolveAiMode } from '../serve/firebase-module-swap.js';
 import { formatActivityWarning } from '../serve/activity-warning.js';
 import { consoleServeLogger, startStaticServer, stderrServeLogger, type ServeHandle } from '../serve/server.js';
 import { createBridgeMount } from '../serve/bridge-mount.js';
+import { createAppPorts } from '../serve/app-ports.js';
 import { openBrowser, shouldAutoOpen } from '../serve/open-browser.js';
 import { readPyricConfig, type PyricConfig } from './pyric-config.js';
 import {
@@ -60,11 +61,11 @@ import {
   createHttpFunctionsPeerReadiness,
   type FunctionsDevelopmentEvent,
   type FunctionsDevelopmentRuntime,
-} from '../functions-rtdb/development-runtime.js';
+} from '../functions/development-runtime.js';
 import {
-  discoverFunctionsRtdbProject,
-  type FunctionsRtdbProject,
-} from '../functions-rtdb/project.js';
+  discoverFunctionsProject,
+  type FunctionsProject,
+} from '../functions/project.js';
 import {
   createSandboxSession,
   SandboxSeedError,
@@ -72,6 +73,7 @@ import {
 } from '../serve/sandbox-session.js';
 import { resolveAvatarsConfig } from '../serve/avatars-config.js';
 import { createVerifyHint } from '../serve/verify-hint.js';
+import { missingPublicDirHint } from './public-dir-hint.js';
 
 interface HostingConfig {
   public?: string;
@@ -252,11 +254,12 @@ async function startServeRuntime(opts: {
     config ??= {};
     const isFirestorePath = typeof ruleOverrides === 'string';
     if (isFirestorePath) {
-      config.firestore = { ...config.firestore, rules: ruleOverrides };
+      config.firestore = withDefaultFirestoreRules(config.firestore, ruleOverrides);
     } else {
-      const hasFirestoreOverride = Boolean(ruleOverrides.firestore);
+      const firestoreOverride = ruleOverrides.firestore;
+      const hasFirestoreOverride = firestoreOverride !== undefined && firestoreOverride !== '';
       if (hasFirestoreOverride) {
-        config.firestore = { ...config.firestore, rules: ruleOverrides.firestore };
+        config.firestore = withDefaultFirestoreRules(config.firestore, firestoreOverride);
       }
       const hasDatabaseOverride = Boolean(ruleOverrides.database);
       if (hasDatabaseOverride) {
@@ -283,14 +286,7 @@ async function startServeRuntime(opts: {
   const publicDir = resolve(opts.cwd, hosting?.public ?? '.');
   const isPublicDirectoryMissing = !existsSync(publicDir);
   if (isPublicDirectoryMissing) {
-    // A missing `dist/` almost always means "no build yet" — the web scaffold's
-    // hosting.public is the Vite output. Point at the dev/build loop instead of
-    // a bare path error (serve previews a build; `vite dev` is the dev server).
-    const looksLikeBuildOutput = /(^|[\\/])(dist|build|out)$/.test(publicDir);
-    const hint = looksLikeBuildOutput
-      ? `\n  No build yet? Run \`bun run dev\` for the live sandbox dev server, ` +
-        `or \`bun run build\` then \`pyric sandbox\` to preview the production build.`
-      : '';
+    const hint = missingPublicDirHint(publicDir, { cwd: opts.cwd, hosted: opts.hosted === true });
     throw new Error(`pyric sandbox: hosting.public directory does not exist: ${publicDir}${hint}`);
   }
 
@@ -370,6 +366,9 @@ async function startServeRuntime(opts: {
   }
   const bundleMs = Math.round(performance.now() - t0);
 
+  // `pyric sandbox -- next dev` serves the page from Next's port, so the
+  // bridge and the guarded `/__pyric/*` routes accept the port they learn.
+  const appPorts = createAppPorts(opts.host ?? 'localhost');
   const needsBridge = Boolean(opts.bridge || opts.hosted);
   let bridgeMount: ReturnType<typeof createBridgeMount> | null = null;
   if (needsBridge) {
@@ -379,6 +378,8 @@ async function startServeRuntime(opts: {
         projectKey: opts.cwd,
         disableAuditLog: opts.disableAuditLog,
         upgradeGuard: { boundHost: opts.host ?? 'localhost', allowedHosts: opts.allowedHosts },
+        learnsProxyPorts: true,
+        appPorts,
     });
   }
   const mount = bridgeMount;
@@ -417,6 +418,7 @@ async function startServeRuntime(opts: {
   try {
     session = await createSandboxSession({
       projectDir: opts.cwd,
+      appPorts,
       firebaseConfig: config,
       sdk: { dir: bundle.outDir, workerVersion },
       seedFile: opts.seed,
@@ -472,14 +474,13 @@ async function startServeRuntime(opts: {
   }
   const payload = session.payload;
   const hosted = usesHostedSandbox ? { projectKey: opts.cwd } : undefined;
-  let namespaceHandler: SandboxSession['handle'] = session.handle;
-  if (hasBridge) {
-    namespaceHandler = async (req, res, url) => {
-      const handledByBridge = await mount.handler(req, res, url);
-      if (handledByBridge) return true;
-      return session.handle(req, res, url);
-    };
-  }
+  // Learn before any guard runs: a page's first request may be a guarded write.
+  const namespaceHandler: SandboxSession['handle'] = async (req, res, url) => {
+    appPorts.learn(req);
+    const handledByBridge = hasBridge && await mount.handler(req, res, url);
+    if (handledByBridge) return true;
+    return session.handle(req, res, url);
+  };
   let handle: Awaited<ReturnType<typeof startStaticServer>>;
   try {
     handle = await startStaticServer({
@@ -934,10 +935,10 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   // the bridge (see bridgeEnabledFor) — the child's injected PYRIC_SANDBOX
   // is useless without the /__pyric/sandbox WS mount.
   // One project for the database rules, deploy targets and functions child.
-  let discoveredFunctionsProject: FunctionsRtdbProject | null;
+  let discoveredFunctionsProject: FunctionsProject | null;
   let firebaseProject: FirebaseProjectResolution;
   try {
-    discoveredFunctionsProject = discoverFunctionsRtdbProject(cwd);
+    discoveredFunctionsProject = discoverFunctionsProject(cwd);
     const flagProject = parsed.flags.get('project');
     firebaseProject = resolveFirebaseProject({
       projectDir: cwd,

package/src/cli/service-commands.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from 'bun:test';
 
+import { COMMANDS_BEFORE_SERVICES } from './index.js';
 import { parseArgs } from './parse-args.js';
+import { SERVICE_COMMANDS } from './service-commands.generated.js';
 import {
   createServiceCommandRegistry,
   dispatchServiceCommand,
@@ -25,6 +27,11 @@ describe('service command dispatcher', () => {
     expect(await dispatchServiceCommand(parseArgs(['sandbox', 'npm', 'run', 'dev']))).toBeNull();
   });
 
+  it('starts no route with a command the top-level dispatcher runs before loading the routes', () => {
+    const shadowed = SERVICE_COMMANDS.filter(({ path }) => COMMANDS_BEFORE_SERVICES.has(path[0]));
+    expect(shadowed.map(({ path }) => path.join(' '))).toEqual([]);
+  });
+
   it('rejects duplicate route paths when constructing a registry', () => {
     const run = async (): Promise<number> => 0;
 

package/src/cli/snapshot.ts

@@ -20,6 +20,7 @@ import { copyFileSync, createWriteStream, existsSync, mkdirSync, renameSync, rmS
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { dirname, join, resolve } from 'node:path';
+import { boundedFetch } from '../bounded-request.js';
 import { hashFile } from '../serve/hosted/persistence/blob-store.js';
 import { hostedStateDirectory, loadHostedSnapshot } from '../serve/hosted/persistence.js';
 import { isStorageReference, objectFileIn, type StorageObjectReference, type StorageStateEntry } from '../serve/state-file.js';
@@ -27,6 +28,13 @@ import { firestoreDocCount } from '../serve/state-summary.js';
 import type { ParsedArgs } from './parse-args.js';
 import { createStateStore, type PyricStateFile } from '../serve/state-store.js';
 
+/**
+ * Milliseconds each live probe (init.json, then state) has, connect included.
+ * A bounded request, so a port whose connect never completes cannot hold the
+ * process open past it (#1167).
+ */
+const LIVE_PROBE_DEADLINE_MS = 750;
+
 /** Ports probed when --port is absent — serve's default + scan window. */
 const SCAN_PORTS = [3473, 3474, 3475, 3476, 3477];
 
@@ -53,9 +61,7 @@ async function fetchLive(port: number): Promise<LiveState | null> {
   try {
     let headers: Record<string, string> | undefined;
     try {
-      const initRes = await fetch(`http://localhost:${port}/__pyric/init.json`, {
-        signal: AbortSignal.timeout(750),
-      });
+      const initRes = await boundedFetch(`http://localhost:${port}/__pyric/init.json`, { deadlineMs: LIVE_PROBE_DEADLINE_MS });
       if (initRes.status === 200) {
         const initData = (await initRes.json()) as { sessionToken?: string };
         if (initData.sessionToken) {
@@ -65,10 +71,13 @@ async function fetchLive(port: number): Promise<LiveState | null> {
     } catch {
       // If init.json probe fails, attempt state fetch directly
     }
-    const requestHeaders: HeadersInit = headers ?? {};
-    const res = await fetch(`http://localhost:${port}/__pyric/state`, {
+    const requestHeaders: Record<string, string> = headers ?? {};
+    // The whole state document is read within the deadline, as fetch's
+    // abort covered the body too, so it has no size cap of its own.
+    const res = await boundedFetch(`http://localhost:${port}/__pyric/state`, {
       headers: requestHeaders,
-      signal: AbortSignal.timeout(750),
+      deadlineMs: LIVE_PROBE_DEADLINE_MS,
+      maxBytes: Number.POSITIVE_INFINITY,
     });
     if (res.status !== 200) return null;
     const body = (await res.json()) as PyricStateFile;

package/src/cli/surface-method-runner.ts

@@ -134,7 +134,7 @@ export async function runSurfaceMethod(
     const sandbox = initializeSandbox();
     const storage = openPersistedServices(sandbox, cwd);
     loadSandboxSnapshot(sandbox, cwd);
-    const projectRules = loadProjectRules(sandbox, cwd);
+    const projectRules = loadProjectRules(sandbox, cwd, (warning) => stderr.write(`pyric: ${warning}\n`));
     if (projectRules?.refused) {
       stderr.write(`pyric: rules not loaded from ${projectRules.path}: ${projectRules.refused}\n`);
     }