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

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/snapshot.ts

@@ -6,13 +6,13 @@
  *   pyric snapshot [--out FILE] [--port N] [--force] [--json]
  *
  * Source preference:
- *   1. LIVE state from a running `pyric dev --persist`
+ *   1. Live state from a running `pyric sandbox --persist`
  *      (`GET /__pyric/state` — `--port`, else the 3473+ scan window),
  *   2. else the on-disk `.pyric/state/state.json`,
  *   3. else exit 2 with a clear message.
  *
  * The output is a `PyricStateFile` envelope — directly re-servable:
- * `pyric dev --seed <out>` (the state-file shape is detected by its
+ * `pyric sandbox --seed <out>` (the state-file shape is detected by its
  * `version` key and seeds docs + users).
  */
 import { existsSync, writeFileSync } from 'node:fs';
@@ -44,7 +44,7 @@ async function fetchLive(port: number): Promise<LiveState | null> {
     if (!body || typeof body !== 'object' || !('version' in body)) return null;
     return { envelope: body, projectDir: res.headers.get('x-pyric-project-dir') };
   } catch {
-    return null; // nothing listening / not a pyric dev — fall through
+    return null; // No Pyric sandbox is listening. Fall through.
   }
 }
 
@@ -110,7 +110,7 @@ export async function runSnapshot(parsed: ParsedArgs, deps: SnapshotDeps = {}):
   }
   if (!envelope) {
     err.write(
-      'pyric snapshot: no state found — no `pyric dev --persist` is running here and ' +
+      'pyric snapshot: no state found. No `pyric sandbox --persist` is running here and ' +
         'no .pyric/state/state.json exists. Run with --persist (and use the app) first.\n',
     );
     return 2;
@@ -158,7 +158,7 @@ export async function runSnapshot(parsed: ParsedArgs, deps: SnapshotDeps = {}):
   if (redactedCount > 0) {
     report.write(`  ⓘ redacted ${redactedCount} password(s) — re-run with --include-passwords to keep them\n`);
   }
-  report.write(`  Re-serve it: pyric dev --seed ${typeof outFlag === 'string' ? outFlag : 'pyric-state.json'}\n`);
+  report.write(`  Re-serve it: pyric sandbox --seed ${typeof outFlag === 'string' ? outFlag : 'pyric-state.json'}\n`);
   if (json) out.write(JSON.stringify({ out: outPath, docs, users, source, redactedPasswords: redactedCount }) + '\n');
   return 0;
 }

package/src/cli/verify.ts

@@ -108,7 +108,7 @@ export async function runVerify(parsed: ParsedArgs, deps: VerifyCliDeps = {}): P
     } else {
       process.stderr.write(
         `pyric verify: no captured session at ${SERVE_CAPTURE_PATH}.\n` +
-          '  Run `pyric dev`, exercise your app, then `pyric verify`, or pass a fixture path.\n',
+          '  Run `pyric sandbox`, exercise your app, then `pyric verify`, or pass a fixture path.\n',
       );
     }
     return 2;

package/src/functions-rtdb/development-runtime.ts

@@ -6,7 +6,7 @@ import {
   type FunctionsRtdbChildReady,
   type SpawnFunctionsRtdbChildOptions,
 } from './child.js';
-import { buildChildEnv, createLinePrefixer } from '../cli/dev-runner.js';
+import { buildChildEnv, createLinePrefixer } from '../cli/sandbox-runner.js';
 
 const INITIAL_PEER_TIMEOUT_MS = 30_000;
 const RELOAD_PEER_TIMEOUT_MS = 5_000;

package/src/functions-rtdb/project.ts

@@ -22,7 +22,7 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     config = JSON.parse(readFileSync(firebaseJsonPath, 'utf8')) as FirebaseJson;
   } catch (error) {
     throw new Error(
-      `pyric dev: failed to parse firebase.json while discovering Functions: ` +
+      `pyric sandbox: failed to parse firebase.json while discovering Functions: ` +
         `${error instanceof Error ? error.message : String(error)}`,
     );
   }
@@ -33,23 +33,23 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     : [config.functions as FunctionsConfig];
   if (declared.length !== 1) {
     throw new Error(
-      'pyric dev: multiple Functions codebases are not supported by the first ' +
+      'pyric sandbox: multiple Functions codebases are not supported by the first ' +
         'onValueCreated slice; configure one source for this development session.',
     );
   }
   const functions = declared[0];
   if (typeof functions !== 'object' || functions === null) {
-    throw new Error('pyric dev: firebase.json `functions` must be an object with a source.');
+    throw new Error('pyric sandbox: firebase.json `functions` must be an object with a source.');
   }
   if (functions.source !== undefined && typeof functions.source !== 'string') {
-    throw new Error('pyric dev: firebase.json `functions.source` must be a string.');
+    throw new Error('pyric sandbox: firebase.json `functions.source` must be a string.');
   }
 
   const sourceDir = resolve(cwd, functions.source ?? 'functions');
   const packageJsonPath = join(sourceDir, 'package.json');
   if (!existsSync(packageJsonPath)) {
     throw new Error(
-      `pyric dev: Functions source is declared but ${packageJsonPath} does not exist.`,
+      `pyric sandbox: Functions source is declared but ${packageJsonPath} does not exist.`,
     );
   }
 
@@ -58,17 +58,17 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { main?: unknown };
   } catch (error) {
     throw new Error(
-      `pyric dev: failed to parse ${packageJsonPath}: ` +
+      `pyric sandbox: failed to parse ${packageJsonPath}: ` +
         `${error instanceof Error ? error.message : String(error)}`,
     );
   }
   if (packageJson.main !== undefined && typeof packageJson.main !== 'string') {
-    throw new Error(`pyric dev: ${packageJsonPath} \`main\` must be a string.`);
+    throw new Error(`pyric sandbox: ${packageJsonPath} \`main\` must be a string.`);
   }
 
   const entry = resolve(sourceDir, packageJson.main ?? 'index.js');
   if (!existsSync(entry) || !statSync(entry).isFile()) {
-    throw new Error(`pyric dev: Functions entry does not exist: ${entry}`);
+    throw new Error(`pyric sandbox: Functions entry does not exist: ${entry}`);
   }
   return { sourceDir, entry };
 }

package/src/next/guard.ts

@@ -54,7 +54,7 @@ export function enforceSandboxGuard(options?: PyricNextOptions): void {
   const errorMessage =
     '[Pyric] Next.js development server started without active Pyric sandbox environment variables.\n' +
     'To prevent accidental connections to production Firebase databases, launch this server using:\n' +
-    '  pyric dev -- next dev\n' +
+    '  pyric sandbox -- next dev\n' +
     'or source environment keys via `pyric env`.\n' +
     'To disable this guard, pass { guard: false } to withPyric(config, options).';
   throw new Error(errorMessage);

package/src/remote/index.ts

@@ -5,7 +5,7 @@
  * Server-side Node code (ultimately `pyric-admin`'s remote dispatch arm)
  * reaches the ONE sandbox the app + Studio + agent share:
  *
- *   Node process ──ws──> `pyric dev --bridge` ──ws──> browser tab
+ *   Node process -> `pyric sandbox --bridge` -> browser tab
  *                 (attach/consumer leg)        (peer leg)
  *                                        ──MessagePort──> SharedWorker
  *
@@ -320,7 +320,7 @@ export function createRemoteSandboxCore(
           reject(
             remoteError(
               'deadline-exceeded',
-              `remote sandbox op timed out after ${opTimeoutMs}ms (op: ${payload.method}) — is pyric dev still running?` +
+              `remote sandbox op timed out after ${opTimeoutMs}ms (op: ${payload.method}). Is pyric sandbox still running?` +
                 // A version-skewed old worker accepts frames it cannot
                 // handle and never responds — a timeout is its signature.
                 (versionSkewGuidance ? ` ${versionSkewGuidance}` : ''),
@@ -379,8 +379,8 @@ export function createRemoteSandboxCore(
           msg.serveVersion !== cliVersion()
         ) {
           versionSkewGuidance =
-            `pyric dev is running version ${msg.serveVersion}, this client is ` +
-            `${cliVersion()} — restart pyric dev and reload the browser tab.`;
+            `pyric sandbox is running version ${msg.serveVersion}, this client is ` +
+            `${cliVersion()}. Restart pyric sandbox and reload the browser tab.`;
           process.stderr.write(`pyric: ${versionSkewGuidance}\n`);
         }
         if (msg.peerConnected) readyResolve();
@@ -405,7 +405,7 @@ export function createRemoteSandboxCore(
             // Version skew: a live tab whose SharedWorker predates this op.
             // Other open pages of this origin keep the old worker alive.
             message +=
-              ' — the running sandbox may predate this feature; restart pyric dev ' +
+              '. The running sandbox may predate this feature. Restart pyric sandbox ' +
               'and close other open pages of this origin, then reload.';
           }
           call.reject(remoteError(code, message, msg.error?.denialContext, (msg.error as any)?.envelope));
@@ -721,7 +721,7 @@ export function createRemoteSandboxHandle(opts: {
     enablePersistence: () =>
       throwMember(
         'enablePersistence',
-        'the browser worker owns persistence; it is already enabled by `pyric dev`',
+        'the browser worker owns persistence; it is already enabled by `pyric sandbox`',
       ),
     flush: () =>
       throwMember('flush()', 'the browser worker owns persistence and flushes itself'),
@@ -742,7 +742,7 @@ export function createRemoteSandboxHandle(opts: {
 // ─── connect ───────────────────────────────────────────────────────────────
 
 /**
- * Discover the running `pyric dev --bridge`, attach to its bridge WS as a
+ * Discover the running `pyric sandbox --bridge`, attach to its bridge WS as a
  * worker-relay CONSUMER (never a peer — attaching cannot kick the browser
  * tab out of last-connection-wins), and return the typed remote handle.
  *
@@ -770,7 +770,7 @@ export async function connectRemoteSandbox(
     if (!found) {
       throw remoteError(
         'not-found',
-        'no running `pyric dev --bridge` found (looked for .pyric/serve.json in ' +
+        'no running `pyric sandbox --bridge` found (looked for .pyric/serve.json in ' +
           `${cwd} and the default ports) — start your dev server with the bridge enabled and retry.`,
       );
     }
@@ -953,7 +953,7 @@ export function createLazyRemoteSandbox(
     // Before discovery the URL is unknown; op-level errors always carry the
     // real URL (they come from the inner connect), and `serveUrl` is patched
     // to the discovered value as soon as the first connect succeeds.
-    serveUrl: options.url?.replace(/\/$/, '') ?? '<pyric dev url (pending discovery)>',
+    serveUrl: options.url?.replace(/\/$/, '') ?? '<pyric sandbox url (pending discovery)>',
     close() {
       if (closed) return;
       closed = true;