@pyric/cli 0.1.0-alpha.18 → 0.1.0-alpha.20

package/src/cli/{dev-runner.ts → sandbox-runner.ts}

@@ -1,5 +1,6 @@
 /**
- * The `pyric dev` child runner — "one command, not two" (adoption design):
+ * The `pyric sandbox` child runner starts the configured application command
+ * after the host is ready:
  * after the host is up, run the user's OWN dev command with the environment
  * activated so their unchanged firebase-admin/firebase imports resolve to the
  * pyric sandbox:
@@ -7,23 +8,20 @@
  *   PYRIC_SANDBOX=remote:<serve url>          (the activator)
  *   NODE_OPTIONS += --import @pyric/cli/register   (the substitution seam)
  *
- * Child-command precedence: explicit `pyric dev -- <cmd>` wins; else the
- * project package.json `dev` script (via the detected package manager); else
- * host-only (today's behavior). `--no-run` forces host-only; `--json`
- * defaults to host-only (an explicit `--` still wins — agents can opt in).
+ * Child-command precedence: `--no-run`, an explicit command, `--json`, the
+ * `pyric.json` command, then host-only. An explicit command still runs with
+ * `--json`.
  *
  * Everything decision-shaped here is pure and exported for the unit suite;
  * only `spawnDevChild` touches the process table.
  */
 import { spawn, type ChildProcess } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 
 // ─── First-run race guard ───────────────────────────────────────────────────
 
 /**
  * Wait (bounded) for a browser tab to register as the bridge's sandbox peer
- * before the child spawns. `pyric dev` opens the tab and spawns the child in
+ * before the child spawns. `pyric sandbox` opens the tab and spawns the child in
  * the same breath; a child whose first line is a sandbox op otherwise races
  * the tab's boot and dies on the no-tab fail-fast — the exact first-run of
  * the two-command story. Polls `/__pyric/health` (`sandboxConnected`).
@@ -63,65 +61,74 @@ export async function waitForSandboxPeer(
 
 // ─── Child-command resolution (pure) ───────────────────────────────────────
 
-export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
-
-/** Lockfile sniff, mirroring how init/vendor pick their install hints. */
-export function detectPackageManager(cwd: string): PackageManager {
-  if (existsSync(join(cwd, 'bun.lock')) || existsSync(join(cwd, 'bun.lockb'))) return 'bun';
-  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
-  return 'npm';
+export interface SandboxChildPlan {
+  /** argv to spawn — argv[0] is the executable. */
+  argv: string[];
+  /** Human-readable command for the pre-spawn line. */
+  label: string;
 }
 
-/** The project's `dev` script, or null (no package.json / no script). */
-export function readDevScript(cwd: string): string | null {
-  try {
-    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as {
-      scripts?: Record<string, unknown>;
-    };
-    const dev = pkg.scripts?.dev;
-    return typeof dev === 'string' && dev.trim().length > 0 ? dev : null;
-  } catch {
-    return null;
+export type DevChildPlan = SandboxChildPlan;
+
+/**
+ * Tokenize a command string into an argv array, preserving quoted strings.
+ */
+export function parseCommandString(cmd: string): string[] {
+  const parts: string[] = [];
+  const regex = /[^\s"']+|"([^"]*)"|'([^']*)'/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(cmd)) !== null) {
+    if (match[1] !== undefined) {
+      parts.push(match[1]);
+    } else if (match[2] !== undefined) {
+      parts.push(match[2]);
+    } else {
+      parts.push(match[0]);
+    }
   }
+  return parts;
 }
 
-export interface DevChildPlan {
-  /** argv to spawn — argv[0] is the executable, no shell. */
-  argv: string[];
-  /** Human-readable command for the pre-spawn line. */
-  label: string;
+export interface ResolveSandboxChildOptions {
+  explicitCommand?: string[] | null;
+  passthrough?: string[];
+  configCommand?: string | null;
+  noRun?: boolean;
+  json?: boolean;
 }
 
 /**
  * Decide what (if anything) to run after the host is up.
  *
- * Matrix:
- *   --no-run                → null, always
- *   `-- <cmd>`              → that command (wins over everything else)
- *   --json (no `--`)        → null (machine mode defaults to host-only)
- *   package.json dev script → `<pm> run dev`
- *   none of the above       → null (host-only, today's behavior)
- *
- * A `dev` script that itself invokes `pyric dev` is treated as absent —
- * running it would recurse forever (pyric dev → npm run dev → pyric dev …).
+ * Precedence:
+ *   --no-run                                → null, always
+ *   explicit CLI command (args or `--`)     → that command (wins over everything else)
+ *   --json (with no explicit command)       → null (machine mode defaults to host-only)
+ *   pyric.json `command`                    → parsed command argv
+ *   none of the above                       → null (host-only)
  */
-export function resolveDevChild(opts: {
-  passthrough: string[];
-  noRun: boolean;
-  json: boolean;
-  devScript: string | null;
-  packageManager: PackageManager;
-}): DevChildPlan | null {
+export function resolveSandboxChild(opts: ResolveSandboxChildOptions): SandboxChildPlan | null {
   if (opts.noRun) return null;
-  if (opts.passthrough.length > 0) {
-    return { argv: [...opts.passthrough], label: opts.passthrough.join(' ') };
+
+  let activeCommand: string[] | null = null;
+  if (opts.explicitCommand && opts.explicitCommand.length > 0) {
+    activeCommand = opts.explicitCommand;
+  } else if (opts.passthrough && opts.passthrough.length > 0) {
+    activeCommand = opts.passthrough;
+  }
+
+  if (activeCommand !== null) {
+    return { argv: [...activeCommand], label: activeCommand.join(' ') };
   }
+
   if (opts.json) return null;
-  if (opts.devScript && !/(^|[\s;&|])pyric\s+dev\b/.test(opts.devScript)) {
-    const label = `${opts.packageManager} run dev`;
-    return { argv: [opts.packageManager, 'run', 'dev'], label };
+
+  if (opts.configCommand && opts.configCommand.trim().length > 0) {
+    const trimmed = opts.configCommand.trim();
+    const argv = parseCommandString(trimmed);
+    return { argv, label: trimmed };
   }
+
   return null;
 }
 
@@ -215,37 +222,73 @@ export function createLinePrefixer(
 
 // ─── Spawn + lifecycle ─────────────────────────────────────────────────────
 
-export interface DevChildHandle {
-  /** Resolves with the exit code to propagate once the child is gone. */
+/** How long a signalled child may linger before SIGKILL. */
+const FORCE_KILL_AFTER_MS = 2_000;
+
+const SHELL_OPERATORS = new Set(['&&', '||', '|', ';', '&']);
+
+export interface SandboxChildHandle {
   exited: Promise<number>;
-  /** Forward a signal (Ctrl-C / SIGTERM). Marks the exit as user-initiated
-   *  so the propagated code is 0, and SIGKILLs a child that lingers. */
   signal(sig: NodeJS.Signals): void;
   child: ChildProcess;
 }
 
-/** How long a signalled child may linger before SIGKILL. */
-const FORCE_KILL_AFTER_MS = 2_000;
+export type DevChildHandle = SandboxChildHandle;
 
 /**
  * Spawn the child with inherited stdin and `[dev]`-prefixed stdout/stderr.
  * In `--json` mode ALL child output goes to stderr — stdout carries exactly
  * the one machine line (the serve --json contract).
  */
-export function spawnDevChild(
-  plan: DevChildPlan,
+export function spawnSandboxChild(
+  plan: SandboxChildPlan,
   opts: { cwd: string; env: NodeJS.ProcessEnv; json: boolean },
-): DevChildHandle {
-  const [command, ...args] = plan.argv;
-  const child = spawn(command!, args, {
-    cwd: opts.cwd,
-    env: opts.env,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    // Own a process group so shutdown reaches package-manager grandchildren
-    // (for example `bun run dev` -> `node server.js`) rather than orphaning
-    // the actual dev server when only the runner exits.
-    detached: process.platform !== 'win32',
-  });
+): SandboxChildHandle {
+  const parts = [...plan.argv];
+  const env: NodeJS.ProcessEnv = { ...opts.env };
+
+  // 1. Extract leading KEY=VAL assignments (e.g. PORT=8080 node server.js)
+  while (parts.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(parts[0]!)) {
+    const token = parts.shift()!;
+    const eq = token.indexOf('=');
+    const key = token.slice(0, eq);
+    const val = token.slice(eq + 1);
+    env[key] = val;
+  }
+
+  // 2. Check for discrete shell operators (&&, ||, |, ;) among top-level tokens
+  const hasShellOperators = parts.some((token) => SHELL_OPERATORS.has(token));
+
+  // 3. Warn if runtime is bun or deno
+  if (parts.length > 0 && (parts[0] === 'bun' || parts[0] === 'deno')) {
+    const runner = parts[0];
+    const target = opts.json ? process.stderr : process.stdout;
+    target.write(
+      `  ⚠ ${runner} detected: pyric intercepts Firebase imports via Node.js module loader hooks (NODE_OPTIONS="--import ..."). ` +
+        `${runner} does not evaluate Node loader hooks — SDK calls in this process will not reach the pyric sandbox. ` +
+        `Use \`node\` (or \`npx tsx\`) to run with the sandbox swap.\n`,
+    );
+  }
+
+  const [command, ...args] = parts;
+  let child: ChildProcess;
+  if (hasShellOperators) {
+    child = spawn(plan.label, [], {
+      cwd: opts.cwd,
+      env,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      shell: true,
+      detached: process.platform !== 'win32',
+    });
+  } else {
+    child = spawn(command!, args, {
+      cwd: opts.cwd,
+      env,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+      detached: process.platform !== 'win32',
+    });
+  }
 
   const outTarget = opts.json ? process.stderr : process.stdout;
   const out = createLinePrefixer('[dev] ', (line) => outTarget.write(line));
@@ -267,7 +310,7 @@ export function spawnDevChild(
 
   const exited = new Promise<number>((resolve) => {
     child.once('error', (e) => {
-      process.stderr.write(`pyric dev: failed to run \`${plan.label}\`: ${e.message}\n`);
+      process.stderr.write(`pyric sandbox: failed to run \`${plan.label}\`: ${e.message}\n`);
       resolve(1);
     });
     child.once('exit', (code, signal) => {
@@ -301,3 +344,5 @@ export function spawnDevChild(
     },
   };
 }
+
+export const spawnDevChild = spawnSandboxChild;

package/src/cli/serve.ts

@@ -1,5 +1,5 @@
 /**
- * `pyric dev` — local dev server with the pyric sandbox standing in for
+ * `pyric sandbox` is the local server with the Pyric sandbox standing in for
  * Firebase. Feels like `firebase serve` (banner, labeled lines, port 3473,
  * SIGINT shutdown) with the sandbox-flavored extras firebase can't do: the
  * served page runs an in-browser backend, your `firestore.rules` deploy into
@@ -28,17 +28,16 @@ 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 { openBrowser, shouldAutoOpen } from '../serve/open-browser.js';
+import { readPyricConfig, type PyricConfig } from './pyric-config.js';
 import {
   buildChildEnv,
-  detectPackageManager,
   formatStartupEnvExport,
-  readDevScript,
   registerModuleUrl,
-  resolveDevChild,
-  spawnDevChild,
+  resolveSandboxChild,
+  spawnSandboxChild,
   waitForSandboxPeer,
-  type DevChildHandle,
-} from './dev-runner.js';
+  type SandboxChildHandle,
+} from './sandbox-runner.js';
 import {
   createFunctionsDevelopmentRuntime,
   createHttpFunctionsPeerReadiness,
@@ -60,7 +59,7 @@ interface HostingConfig {
   rewrites?: Array<{ source?: string; destination?: string }>;
 }
 
-/** Extract the single hosting config `pyric dev` v1 supports. Arrays
+/** Extract the single hosting config `pyric sandbox` supports. Arrays
  *  (multi-site) take the first entry with a warning — multi-site is out of
  *  scope (plan section 6). */
 export function extractHosting(config: FirebaseJson | null): HostingConfig | null {
@@ -84,7 +83,7 @@ export interface ServeRuntime {
   payload: () => InitPayload;
   /** HTTP MCP endpoint when `--bridge` is on; null otherwise. */
   mcpUrl: string | null;
-  /** The Studio app URL (`/__pyric/ui/`) when `--ui` is on and the build is
+  /** The Studio hub URL (`/__pyric/ui/studio`) when `--ui` is on and the build is
    *  present; null otherwise. */
   uiUrl: string | null;
   /** Persistence summary (null when `--persist` is off). */
@@ -147,6 +146,8 @@ export async function startServe(opts: {
    *  (the served project's file tree) + `/__pyric/projects` (single-project
    *  store over `cwd`). The Studio app's `local` mode talks to these. */
   ui?: boolean;
+  /** Explicit opt-in to permissive mode (default-allow RTDB rules when unconfigured). */
+  permissive?: boolean;
   logger?: Parameters<typeof startStaticServer>[0]['logger'];
 }): Promise<ServeRuntime> {
   const logger = opts.logger ?? consoleServeLogger();
@@ -157,7 +158,7 @@ export async function startServe(opts: {
   // Fail fast instead of pretending to reset something.
   if (opts.fresh && !opts.persist) {
     throw new Error(
-      'pyric dev: --fresh requires --persist (it discards .pyric/state/state.json). ' +
+      'pyric sandbox: --fresh requires --persist (it discards .pyric/state/state.json). ' +
         'Browser-stored data is cleared from Studio → Settings → Reset, or DevTools → Clear site data.',
     );
   }
@@ -172,9 +173,29 @@ export async function startServe(opts: {
     logger.note('  ⚠ no firebase.json found — serving the current directory without hosting config');
   }
 
+  const pyricConfig = await readPyricConfig(opts.cwd);
+  if (pyricConfig.rules) {
+    if (!config) config = {};
+    if (typeof pyricConfig.rules === 'string') {
+      config.firestore = { ...config.firestore, rules: pyricConfig.rules };
+    } else {
+      if (pyricConfig.rules.firestore) {
+        config.firestore = { ...config.firestore, rules: pyricConfig.rules.firestore };
+      }
+      if (pyricConfig.rules.database) {
+        config.database = { ...config.database, rules: pyricConfig.rules.database };
+      }
+      if (pyricConfig.rules.storage) {
+        const baseStorage =
+          typeof config.storage === 'object' && !Array.isArray(config.storage) ? config.storage : {};
+        config.storage = { ...baseStorage, rules: pyricConfig.rules.storage };
+      }
+    }
+  }
+
   const hosting = extractHosting(config);
   if (Array.isArray(config?.hosting) && (config.hosting as unknown[]).length > 1) {
-    logger.note('  ⚠ multiple hosting sites configured — pyric dev v1 serves the first entry only');
+    logger.note('  ⚠ multiple hosting sites configured. pyric sandbox serves the first entry only');
   }
   const publicDir = resolve(opts.cwd, hosting?.public ?? '.');
   if (!existsSync(publicDir)) {
@@ -184,16 +205,16 @@ export async function startServe(opts: {
     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 dev\` to preview the production build.`
+        `or \`bun run build\` then \`pyric sandbox\` to preview the production build.`
       : '';
-    throw new Error(`pyric dev: hosting.public directory does not exist: ${publicDir}${hint}`);
+    throw new Error(`pyric sandbox: hosting.public directory does not exist: ${publicDir}${hint}`);
   }
 
   // The import map can only remap BARE `firebase/*` specifiers. A plain bundler
   // build (`vite build`) inlines the real SDK into the app chunk, leaving
   // nothing to intercept — the page would then talk to REAL Firebase endpoints
   // with the sandbox's fake credentials while the injected banner claims
-  // otherwise. That hole is structural, so `pyric dev` REFUSES such a dist
+  // otherwise. That hole is structural, so `pyric sandbox` refuses such a dist
   // rather than serving it. A pyric SANDBOX build (`vite build --mode
   // development`) carries the marker and bundles pyric's in-page adapters, so it
   // is trusted and the scan is skipped (marker present → no real SDK to find).
@@ -201,14 +222,14 @@ export async function startServe(opts: {
     const inlined = scanForInlinedFirebase(publicDir);
     if (inlined.length > 0) {
       throw new Error(
-        `pyric dev: ${inlined[0]} bundles the REAL firebase SDK, so this dist cannot be ` +
+        `pyric sandbox: ${inlined[0]} bundles the real Firebase SDK, so this dist cannot be ` +
           `sandboxed — its firebase/* calls would reach LIVE Google endpoints, not the ` +
           `pyric sandbox. Two ways forward:\n` +
-          `  (a) plain \`pyric dev\` runs the child dev-server flow (the @pyric/cli/vite ` +
+          `  (a) \`pyric sandbox -- <command>\` runs the child server with the @pyric/cli/vite ` +
           `plugin swaps firebase/* live) — use \`bun run dev\`;\n` +
           `  (b) rebuild as a self-contained sandbox bundle and serve THAT: ` +
           `\`vite build --mode development\` (or pyric({ swapInBuild: true })) then ` +
-          `\`pyric dev\`.\n` +
+          `\`pyric sandbox\`.\n` +
           `A plain \`vite build\` is your production build — deploy it, don't sandbox it.`,
       );
     }
@@ -285,15 +306,16 @@ export async function startServe(opts: {
       studio: opts.ui ? { siteUiDir } : false,
       bridgeUrl: () => mount && origin.port > 0 ? mount.wsUrl(origin) : null,
       activity: (incident) => logger.note(formatActivityWarning(incident)),
+      permissive: opts.permissive,
       logger,
     });
   } catch (error) {
     bundle.dispose?.();
     if (error instanceof SandboxSeedError) {
       if (error.kind === 'read') {
-        throw new Error(`pyric dev: failed to read --seed ${error.path}: ${error.detail}`);
+        throw new Error(`pyric sandbox: failed to read --seed ${error.path}: ${error.detail}`);
       }
-      throw new Error(`pyric dev: --seed must be a JSON object of "collection/doc" → fields, ${error.detail}`);
+      throw new Error(`pyric sandbox: --seed must be a JSON object of "collection/doc" to fields, ${error.detail}`);
     }
     throw error;
   }
@@ -376,7 +398,7 @@ export async function startServe(opts: {
   };
   if (bundle.dispose) handle.server.once('close', bundle.dispose);
   handle.server.once('close', () => void closeOwnedResources());
-  const uiUrl = siteUiDir ? `${handle.url}/__pyric/ui/` : null;
+  const uiUrl = siteUiDir ? `${handle.url}/__pyric/ui/studio` : null;
   const docsUrl = siteUiDir ? `${handle.url}/__pyric/ui/docs/` : null;
 
   // Hot-reload: the static adapter observes the filesystem; the session owns
@@ -547,7 +569,7 @@ export function bridgeEnabledFromFlags(flags: { get(key: string): unknown }): bo
  * A dev child also implies the bridge: the runner injects
  * `PYRIC_SANDBOX=remote:<url>` into the child, whose remote client dials the
  * `/__pyric/sandbox` WS — without the bridge mount that upgrade 404s and
- * plain `pyric dev -- <cmd>` (or a detected dev script) breaks its own
+ * `pyric sandbox -- <cmd>` breaks its own
  * child. Pure + exported for unit coverage.
  */
 export function bridgeEnabledFor(
@@ -560,7 +582,7 @@ export function bridgeEnabledFor(
 
 /**
  * Process-level last line of defense for the dev server: a single bad
- * request/WS interaction must never take `pyric dev` down. Node kills the
+ * request/WS interaction must never take `pyric sandbox` down. Node kills the
  * process on an unhandled rejection (default `--unhandled-rejections=throw`
  * since v15) and on any uncaught exception — and the serve process hosts
  * long-lived, browser-driven machinery (WS peers, SSE streams, file watchers,
@@ -578,13 +600,13 @@ export function installServeProcessGuard(
     reason instanceof Error ? (reason.stack ?? reason.message) : String(reason);
   const onRejection = (reason: unknown): void => {
     log(
-      `  ✖ pyric dev: UNHANDLED REJECTION (the server was kept alive — please report this):\n` +
+      `  ✖ pyric sandbox: unhandled rejection. The server was kept alive. Please report this:\n` +
         `    ${describe(reason).split('\n').join('\n    ')}`,
     );
   };
   const onException = (err: unknown): void => {
     log(
-      `  ✖ pyric dev: UNCAUGHT EXCEPTION (the server was kept alive — please report this):\n` +
+      `  ✖ pyric sandbox: uncaught exception. The server was kept alive. Please report this:\n` +
         `    ${describe(err).split('\n').join('\n    ')}`,
     );
   };
@@ -596,10 +618,49 @@ export function installServeProcessGuard(
   };
 }
 
+function resolveServePort(flagPort: unknown, configPort?: number): number {
+  if (typeof flagPort === 'string') return Number(flagPort);
+  if (typeof flagPort === 'number') return flagPort;
+  if (typeof configPort === 'number') return configPort;
+  return 3473;
+}
+
+function resolveProjectIdentifier(
+  flagProject?: unknown,
+  envProject?: string,
+  configProject?: string,
+  rcDefault?: string,
+): string {
+  if (typeof flagProject === 'string' && flagProject.length > 0) return flagProject;
+  if (typeof envProject === 'string' && envProject.length > 0) return envProject;
+  if (typeof configProject === 'string' && configProject.length > 0) return configProject;
+  if (typeof rcDefault === 'string' && rcDefault.length > 0) return rcDefault;
+  return 'demo-project';
+}
+
+function resolveExplicitCommand(parsed: ParsedArgs): string[] | null {
+  if (parsed.passthrough && parsed.passthrough.length > 0) {
+    return parsed.passthrough;
+  }
+  if (parsed.positional.length > 0) {
+    return parsed.positional;
+  }
+  return null;
+}
+
 /** CLI entry. Resolves on SIGINT/SIGTERM after a clean stop. */
 export async function runServe(parsed: ParsedArgs): Promise<number> {
+  const cwd = process.cwd();
+  let pyricConfig: PyricConfig = {};
+  try {
+    pyricConfig = await readPyricConfig(cwd);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 2;
+  }
+
   const flagPort = parsed.flags.get('port');
-  const port = typeof flagPort === 'string' ? Number(flagPort) : 3473;
+  const port = resolveServePort(flagPort, pyricConfig.port);
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     process.stderr.write(`pyric: invalid --port '${flagPort}'.\n`);
     return 1;
@@ -610,7 +671,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   const only = parsed.flags.get('only');
   if (typeof only === 'string' && only !== 'hosting') {
     process.stderr.write(
-      `pyric: --only '${only}' is not supported — pyric dev v1 serves hosting (with the in-page sandbox standing in for firestore/auth).\n`,
+      `pyric: --only '${only}' is not supported. pyric sandbox serves hosting with the in-page sandbox standing in for Firestore and Auth.\n`,
     );
     return 1;
   }
@@ -623,7 +684,6 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   // Resolve the child plan BEFORE the server starts: a planned child implies
   // the bridge (see bridgeEnabledFor) — the child's injected PYRIC_SANDBOX
   // is useless without the /__pyric/sandbox WS mount.
-  const cwd = process.cwd();
   let functionsProject: FunctionsRtdbProject | null;
   let functionsProjectId: string | null = null;
   try {
@@ -631,22 +691,25 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (functionsProject) {
       const flagProject = parsed.flags.get('project');
       const rc = await readFirebaseRc(cwd);
-      functionsProjectId =
-        (typeof flagProject === 'string' ? flagProject : undefined) ??
-        process.env.PYRIC_PROJECT ??
-        rc?.projects?.default ??
-        'demo-project';
+      functionsProjectId = resolveProjectIdentifier(
+        flagProject,
+        process.env.PYRIC_PROJECT,
+        pyricConfig.project,
+        rc?.projects?.default,
+      );
     }
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return 2;
   }
-  const plan = resolveDevChild({
-    passthrough: parsed.passthrough ?? [],
+
+  const explicitCommand = resolveExplicitCommand(parsed);
+
+  const plan = resolveSandboxChild({
+    explicitCommand,
+    configCommand: pyricConfig.command,
     noRun: Boolean(parsed.flags.get('no-run')),
     json,
-    devScript: readDevScript(cwd),
-    packageManager: detectPackageManager(cwd),
   });
   const bridgeOn = bridgeEnabledFor(parsed.flags, plan, functionsProject);
 
@@ -663,6 +726,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       watch: parsed.flags.get('no-watch') ? false : undefined,
       persist: Boolean(parsed.flags.get('persist')),
       fresh: Boolean(parsed.flags.get('fresh')),
+      permissive: Boolean(parsed.flags.get('permissive')),
       // --ui mounts the Pyric Studio storage routes (workspace + projects).
       ui: uiOn,
       // --no-capture disables the default-on session capture. The pattern
@@ -675,7 +739,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       project:
         typeof parsed.flags.get('project') === 'string'
           ? (parsed.flags.get('project') as string)
-          : process.env.PYRIC_PROJECT ?? functionsProjectId ?? undefined,
+          : process.env.PYRIC_PROJECT ?? pyricConfig.project ?? functionsProjectId ?? undefined,
     });
   } catch (e) {
     process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
@@ -691,7 +755,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   // (the banner went to stderr). Readiness probe: GET /__pyric/init.json.
   if (json) process.stdout.write(serveJsonLine(runtime) + '\n');
 
-  // Footgun guard (hybrid-MCP plan Phase 3): plain `dev` mounts no MCP bridge,
+  // A host-only sandbox mounts no MCP bridge unless one is needed.
   // so a `pyric mcp-proxy` in an editor cannot attach. Nudge toward --bridge.
   if (!bridgeOn && !json) {
     process.stderr.write(
@@ -714,7 +778,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     void openBrowser(targetUrl);
   }
 
-  let devChild: DevChildHandle | null = null;
+  let devChild: SandboxChildHandle | null = null;
   let functionsRuntime: FunctionsDevelopmentRuntime | null = null;
   let resolveFunctionsExit!: (code: number) => void;
   const functionsExited = new Promise<number>((resolve) => { resolveFunctionsExit = resolve; });
@@ -793,7 +857,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (result.kind === 'no-peer') {
       process.stderr.write(
         `  ⚠ functions not started — no browser tab connected after 30s. ` +
-          `Open ${runtime.handle.url} and restart pyric dev.\n`,
+          `Open ${runtime.handle.url} and restart pyric sandbox.\n`,
       );
     } else if (result.kind === 'failed') {
       process.stderr.write(`${result.error.message}\n`);
@@ -810,16 +874,15 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       for (const unsupported of ready.unsupportedTriggers) {
         process.stderr.write(
           `  ⚠ functions export ${unsupported.exportName} uses unsupported trigger ` +
-            `${unsupported.eventType}; it will not run in pyric dev.\n`,
+            `${unsupported.eventType}; it will not run in pyric sandbox.\n`,
         );
       }
     }
   }
 
-  // The child runner ("one command, not two"): run the user's own dev
-  // command with the sandbox environment injected. Precedence: `-- <cmd>`
-  // wins; else the package.json dev script; else host-only. --no-run forces
-  // host-only; --json defaults to host-only (explicit `--` still wins).
+  // Run the explicit or configured command with the sandbox environment.
+  // `--no-run` forces host-only. `--json` skips the configured command, but an
+  // explicit command still runs.
   // (`plan` was resolved above so it could imply the bridge mount.)
   if (plan) {
     const info = json ? process.stderr : process.stdout;
@@ -838,11 +901,16 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
           `  ⚠ no browser tab connected after 30s — starting your command anyway; sandbox ops will fail until ${runtime.handle.url} is open.\n`,
         );
       }
+    } else if (!json) {
+      info.write(
+        `  ⓘ Auto-open is disabled (--no-open/CI). The pyric sandbox is browser-resident: ` +
+          `open ${runtime.handle.url} to connect if your command performs Firebase operations.\n`,
+      );
     }
     info.write(
       `✔ run      \`${plan.label}\` — firebase-admin/firebase imports are routed to the sandbox at ${runtime.handle.url}\n`,
     );
-    devChild = spawnDevChild(plan, {
+    devChild = spawnSandboxChild(plan, {
       cwd,
       json,
       env: buildChildEnv(process.env, {
@@ -895,7 +963,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (functionsRuntime) {
       void functionsExited.then((code) => {
         if (!settled && !shuttingDown) {
-          process.stderr.write(`pyric dev: Functions child exited unexpectedly (code ${code}).\n`);
+          process.stderr.write(`pyric sandbox: Functions child exited unexpectedly (code ${code}).\n`);
           finish(code === 0 ? 1 : code);
         }
       });

package/src/cli/service-command-records/storage-rules-resolve.ts

@@ -0,0 +1,4 @@
+import { runStorageRulesResolve } from '../rules.js';
+import type { ServiceCommandHandler } from '../service-commands.js';
+
+export default runStorageRulesResolve satisfies ServiceCommandHandler;