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

package/src/cli/cli.test.ts

@@ -412,7 +412,7 @@ describe('runInit', () => {
 
     // Missing Pyric development scripts + deps added.
     expect(written.scripts.bridge).toBe('pyric bridge');
-    expect(written.scripts.dev).toBe('pyric dev --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts');
+    expect(written.scripts.dev).toBe('pyric sandbox --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts');
     expect(Object.keys(written.scripts).some((name) => name.startsWith('deploy'))).toBe(false);
     expect(written.dependencies.firebase).toBe('^12.12.0');
     expect(written.dependencies.pyric).toBeUndefined();
@@ -437,7 +437,7 @@ describe('runInit', () => {
         private: true,
         scripts: {
           start: 'node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
-          dev: 'pyric dev --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
+          dev: 'pyric sandbox --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
           bridge: 'pyric bridge',
         },
         dependencies: { firebase: '^12.12.0' },
@@ -461,47 +461,3 @@ describe('runInit', () => {
     expect(io.getOut()).toContain('skipped package.json'); // unchanged merge
   });
 });
-
-describe('scanForInlinedFirebase', () => {
-  it('flags a bundled chunk that inlines real-SDK endpoint hosts', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-scan-'));
-    mkdirSync(join(dir, 'assets'));
-    writeFileSync(
-      join(dir, 'assets', 'index-abc.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    const hits = scanForInlinedFirebase(dir);
-    expect(hits).toEqual(['assets/index-abc.js']);
-  });
-
-  it('stays clean for an unbundled app importing firebase by bare specifier', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-clean-'));
-    writeFileSync(
-      join(dir, 'main.js'),
-      "import { getAuth } from 'firebase/auth'; import { getFirestore } from 'firebase/firestore';",
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-
-  it('ignores hidden frameworks and build cache directories like .next and .git', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-ignore-'));
-    mkdirSync(join(dir, '.next'));
-    writeFileSync(
-      join(dir, '.next', 'bundle.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-});

package/src/cli/index.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * `pyric` CLI — front door to the bridge + project tooling.
+ * `pyric` CLI front door to the bridge and project tooling.
  *
  * Subcommands:
  *   pyric bridge [--port N] [--project ID]
- *   pyric dev [--port N] [--host H] [--no-cache] [--bridge] [--ui] [--seed FILE] [--no-watch] [--no-open] [--no-capture] [--no-run] [--json] [--persist] [--fresh] [-- <cmd>]
+ *   pyric sandbox [flags] [--] [command...]
  *   pyric init [dir] [--template web|node] [--name N] [--force] [--json]
  *   pyric vendor [dir] [--json]
  *   pyric snapshot [--out FILE] [--port N] [--force] [--json] [--include-passwords]
@@ -55,12 +55,12 @@ const VERSION = pyricVersion();
 
 function printUsage(): void {
   process.stdout.write(`pyric ${VERSION}
-Firebase for agents — bridge an in-browser pyric sandbox to external MCP
+Firebase for agents. Bridge an in-browser Pyric sandbox to external MCP
 clients (Claude Code, Cursor, ...).
 
 USAGE
   pyric bridge [flags]
-  pyric dev [flags] [-- <cmd>]
+  pyric sandbox [flags] [--] [command...]
   pyric init [dir] [--template=web|node]
   pyric snapshot [--out=FILE]
   pyric verify [fixture|dir] [--engine sandbox|rules-test-api|both]
@@ -83,16 +83,14 @@ USAGE
 
 COMMANDS
   bridge                     Start the HTTP+WebSocket bridge external MCP clients point at.
-  dev                        Serve the app locally with the pyric sandbox standing in for
-                             Firebase — unmodified firebase/* imports hit an in-page sandbox
-                             with your firestore.rules deployed. Also runs your own dev
-                             command (\`-- <cmd>\`, else the package.json \`dev\` script) with
-                             unchanged firebase-admin/firebase imports routed to the
-                             sandbox (PYRIC_SANDBOX + \`--import @pyric/cli/register\`). A
-                             firebase.json Functions source is discovered automatically;
+  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
+                             configured in pyric.json; if none is configured, runs the sandbox host only.
+                             A firebase.json Functions source is discovered automatically;
                              supported RTDB onValueCreated exports run in isolated Node.
   init [dir]                 Scaffold a pyric project. --template=web (default; Vite app
-                             on \`@pyric/cli/vite\`), static (\`pyric dev\`), or node.
+                             on \`@pyric/cli/vite\`), static (\`pyric sandbox\`), or node.
                              --name=NAME --force (overwrite scaffold files) --json (machine
                              output on stdout). Never prompts; rerunning is safe.
                              Greenfield shortcut: \`npm create pyric [dir]\`.
@@ -102,15 +100,15 @@ COMMANDS
                              bun install. Standalone binary only.
   mcp                        Stdio MCP server for editors (Cursor / Claude /
                              Antigravity). Hosts a headless in-process sandbox,
-                             or attaches to a running \`pyric dev --bridge\`
+                             or attaches to a running \`pyric sandbox --bridge\`
                              (found via .pyric/serve.json) for shared-live Studio.
-  snapshot [--out=FILE]      Promote lived sandbox state (live dev --persist, else
+  snapshot [--out=FILE]      Promote lived sandbox state (live sandbox --persist, else
                              .pyric/state/state.json) to a committable fixture that
-                             \`pyric dev --seed FILE\` re-serves. Passwords are redacted
+                             \`pyric sandbox --seed FILE\` re-serves. Passwords are redacted
                              by default (--include-passwords keeps them). --port, --force, --json.
   verify [fixture|dir]       Replay a captured sandbox session against candidate rules
                              for the Firestore/RTDB services present in the fixture.
-                             No arg replays the latest \`pyric dev\` capture
+                             No arg replays the latest \`pyric sandbox\` capture
                              (.pyric/last-session.json). --service filters services.
                              --engine sandbox (default), rules-test-api, or both.
                              Hosted Rules Test API verification is Firestore-only
@@ -135,59 +133,67 @@ COMMANDS
   database rules validate    Validate Realtime Database rules expressions.
   database rules simulate    Run the local Realtime Database rules simulator.
   database rules generate    Compile a constraints module to database.rules.json.
-CORE FLAGS (dev)
-  --port             Port to serve on. Default 3473 — "FIRE" on a phone keypad (scans forward when taken;
-                     macOS AirPlay squats 5000).
+CORE FLAGS (sandbox)
+  --port             Port to serve on. Default 3473. Pyric scans forward when
+                     the selected port is taken.
   --host             Host to bind. Default localhost.
   --no-cache         Rebuild the served pyric SDK bundles (skip ~/.pyric/serve-cache).
   --only hosting     Accepted for firebase-serve parity (hosting is all v1 serves).
-  --bridge           Also mount the MCP bridge on the serve origin — agents point
+  --bridge           Also mount the MCP bridge on the serve origin. Agents point
                      at http://<host>:<port>/__pyric/mcp and drive the sandbox
                      living in the served page. --project labels health/audit.
-  --ui               Also serve the Pyric Studio app at <url>/__pyric/ui/ (and
-                     mount its disk-backed workspace + project data routes).
-                     Auto-opens Studio instead of the served page. Needs a full
-                     build so the app assets are present.
-  --seed FILE        JSON map of "collection/doc" → fields, loaded admin-style.
+  --ui               Open Studio instead of the served page. Studio and docs
+                     are served by default at <url>/__pyric/ui/.
+  --no-ui            Do not serve Studio, docs, workspace, or project routes.
+  --seed FILE        JSON map of "collection/doc" to fields, loaded with admin access.
                      Also accepts a pyric state file (from \`pyric snapshot\`,
-                     detected by its version key) — seeds docs + auth users.
-                     into the page sandbox before app code runs.
+                     detected by its version key). Seeds documents and auth users
+                     before application code runs.
   --no-watch         Disable firestore.rules hot-reload (on by default).
-  --no-open          Don't auto-open the browser. dev opens the served page
+  --no-open          Don't auto-open the browser. sandbox opens the served page
                      by default (the sandbox is browser-resident); auto-open
                      is already suppressed under --json, no TTY, and CI.
-  --no-capture       Don't write the session capture. dev writes
+  --no-capture       Don't write the session capture. sandbox writes
                      .pyric/last-session.json by default so \`pyric verify\`
                      can replay your session; --no-capture disables it.
+  --permissive       Allow unauthenticated Realtime Database reads and writes when no
+                     rules file is present. For local prototyping only.
   --allowed-host H   Allow an extra Host header past the DNS-rebinding guard
                      (comma-separated; localhost/127.0.0.1 always allowed).
   --persist          Persist sandbox state (docs + auth users) to
-                     .pyric/state/state.json — survives reloads and dev
+                     .pyric/state/state.json. It survives reloads and sandbox
                      restarts. Once a state file exists it wins; --seed
                      applies only on the first (state-less) run. Ephemeral
                      is the default.
   --fresh            Requires --persist: discard the existing state file and
                      re-seed from scratch (escape hatch when you've edited
-                     seed.json). Without --persist, --fresh errors — there is
+                     seed.json). Without --persist, --fresh errors because there is
                      no state file to discard. Half-reset warning: a browser
                      tab that already has sandbox data in IndexedDB keeps it
                      and writes it back to the new file; also clear the
-                     browser store (Studio → Settings → Reset, or an
+                     browser store in Studio under Settings, Reset, or use an
                      incognito window) for a full reset.
-  -- <cmd>           Run <cmd> once the host is up, with PYRIC_SANDBOX set and
+  [command...]       Run a command once the host is up, with PYRIC_SANDBOX set and
                      NODE_OPTIONS extended with --import @pyric/cli/register
-                     so firebase-admin/firebase resolve to the sandbox. When
-                     omitted, the package.json \`dev\` script runs (via the
-                     detected package manager); no script → host-only.
-  --no-run           Don't run the project's dev command (for users with their
-                     own process manager). A declared Functions source still
-                     runs. --json skips the dev command unless a \`-- <cmd>\`
-                     is given explicitly.
+                     so firebase-admin/firebase resolve to the sandbox. Put
+                     Pyric flags before the command. A bare -- separates the
+                     command and its flags. When omitted, pyric.json#command
+                     runs. With no configured command, the host runs alone.
+  --no-run           Don't run an explicit or configured command. A declared
+                     Functions source still runs.
   --json             One machine-readable line on stdout ({url, port, mcpUrl,
                      rulesHash, persist, restoredDocs, restoredUsers}); the
-                     banner moves to stderr. Readiness probe:
+                     banner moves to stderr. A pyric.json command is skipped
+                     unless a command is supplied explicitly. Readiness probe:
                      GET <url>/__pyric/init.json → 200 (live rules hash).
 
+PROJECT CONFIG (pyric.json)
+  command            Default child command. An explicit CLI command overrides it.
+  port               Default sandbox port. --port overrides it.
+  project            Project label. --project, then PYRIC_PROJECT, override it.
+  rules              Firestore rules path, or an object with firestore,
+                     database, and storage paths.
+
 CORE FLAGS (bridge)
   --port             Port to bind on 127.0.0.1. Default 5174. Env: PYRIC_PORT.
   --project          Project label surfaced in /health + audit output.
@@ -336,7 +342,7 @@ export async function dispatch(parsed: ParsedArgs): Promise<number> {
       return parsed.subcommand === null ? 0 : 1;
     case 'bridge':
       return await runBridge(parsed);
-    case 'dev':
+    case 'sandbox':
       const { runServe } = await import('./serve.js');
       return runServe(parsed);
     case 'snapshot':

package/src/cli/inlined-sdk-scanner.ts

@@ -0,0 +1,77 @@
+/**
+ * Detect a served frontend build that inlined the real Firebase SDK.
+ *
+ * The served import map remaps only bare `firebase/*` specifiers, so a plain
+ * `vite build` that compiled the SDK into an app chunk cannot be sandboxed:
+ * its calls reach real Google endpoints while the injected banner claims
+ * otherwise. `cli/serve.ts` refuses such a dist rather than serving it.
+ *
+ * Only the SDK fingerprint hosts are matched, never the full endpoint catalog.
+ * This check throws, and a dist can legitimately carry a bare callable URL, a
+ * public asset URL, or a `databaseURL` literal without any Firebase SDK in it.
+ *
+ * Backend bundles are deliberately out of scope. `withPyric` externalizes
+ * firebase and firebase-admin, the backend-bundler docs tell users to mark them
+ * external, and the net guard reports real egress at runtime with attribution,
+ * which a grep over build output cannot do.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { SDK_FINGERPRINT_HOSTS } from '../google-endpoints.js';
+
+/** Depth limit for the walk. */
+const MAX_DEPTH = 4;
+
+/** Total script files read. */
+const MAX_FILES = 200;
+
+/** Script extensions worth reading in served frontend output. */
+const SCRIPT_FILE = /\.(js|mjs)$/;
+
+/**
+ * Scan `dir` for inlined SDK fingerprints and return the offending paths,
+ * relative to `dir`. Bounded: depth 4, 200 script files, first hit per file.
+ */
+export function scanForInlinedFirebase(dir: string): string[] {
+  const hits: string[] = [];
+  let scanned = 0;
+  const walk = (current: string, rel: string, depth: number): void => {
+    if (depth > MAX_DEPTH || scanned >= MAX_FILES) return;
+    let names: string[];
+    try {
+      names = readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      if (scanned >= MAX_FILES) return;
+      const path = join(current, name);
+      const relPath = rel ? `${rel}/${name}` : name;
+      let stat;
+      try {
+        stat = statSync(path);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        // The pyric namespace itself never lands in hosting.public, but a
+        // node_modules inside a served dir would be a scan-cost trap.
+        // Dot-directories (.next, .git, .pyric) are internal caches.
+        if (name === 'node_modules' || name.startsWith('.')) continue;
+        walk(path, relPath, depth + 1);
+        continue;
+      }
+      if (!SCRIPT_FILE.test(name)) continue;
+      scanned++;
+      let text: string;
+      try {
+        text = readFileSync(path, 'utf8');
+      } catch {
+        continue; // unreadable asset
+      }
+      if (SDK_FINGERPRINT_HOSTS.some((host) => text.includes(host))) hits.push(relPath);
+    }
+  };
+  walk(dir, '', 0);
+  return hits;
+}

package/src/cli/mcp-proxy.ts

@@ -1,6 +1,6 @@
 /**
  * `pyric mcp-proxy` — a stdio MCP server that relays to a RUNNING
- * `pyric dev --bridge`'s HTTP MCP endpoint.
+ * the HTTP MCP endpoint from `pyric sandbox --bridge`.
  *
  * Why this exists: the agent plugin declares one static stdio command, while
  * serve's endpoint is `http://localhost:<PORT>/__pyric/mcp` with a runtime
@@ -84,12 +84,12 @@ export async function runMcpProxy(
   if (!found) {
     // Hybrid mode (design rationale): no dev server to attach to, so host the
     // sandbox IN this process. Zero setup, no browser tab required. A running
-    // `pyric dev --bridge` upgrades to the shared-live experience on reconnect.
+    // `pyric sandbox --bridge` upgrades to the shared session on reconnect.
     log(
-      'no running `pyric dev --bridge` found (looked for .pyric/serve.json and ports ' +
+      'no running `pyric sandbox --bridge` found (looked for .pyric/serve.json and ports ' +
         `${SCAN_PORTS.join(', ')}); starting a headless in-process sandbox (zero-setup).\n` +
         '  Data persists to .pyric/state/headless.json. For a shared-live Studio\n' +
-        '  session, start `pyric dev --bridge` BEFORE connecting the agent (a dev server\n' +
+        '  session, start `pyric sandbox --bridge` before connecting the agent (a sandbox host\n' +
         '  started mid-session does not yet adopt this headless data).',
     );
     const headless =

package/src/cli/parse-args.ts

@@ -12,17 +12,54 @@ export interface ParsedArgs {
   subcommand: string | null;
   flags: Map<string, FlagValue>;
   positional: string[];
-  /** Everything after a bare `--`, verbatim (e.g. `pyric dev -- npm start`).
+  /** Everything after a bare `--`, verbatim (e.g. `pyric sandbox -- npm start`).
    *  Optional so hand-built ParsedArgs literals stay valid. */
   passthrough?: string[];
 }
 
 export type FlagValue = string | boolean | Array<string | boolean>;
 
-// Flags whose command contract is boolean must not consume a following
-// positional. Value-bearing flags retain the Firebase-style `--flag value`
-// form, while explicit boolean values remain available as `--json=true`.
-const BOOLEAN_FLAGS = new Set(['json']);
+const BOOLEAN_FLAGS = new Set([
+  'json',
+  'bridge',
+  'ui',
+  'no-ui',
+  'no-open',
+  'no-run',
+  'no-cache',
+  'no-watch',
+  'no-capture',
+  'persist',
+  'fresh',
+  'force',
+  'permissive',
+  'help',
+  'version',
+]);
+
+function isBooleanFlag(key: string): boolean {
+  return BOOLEAN_FLAGS.has(key) || key.startsWith('no-');
+}
+
+const SHORT_VALUE_ALIASES: ReadonlyMap<string, string> = new Map([
+  ['p', 'port'],
+]);
+
+function consumeFlag(
+  flags: Map<string, FlagValue>,
+  key: string,
+  argv: string[],
+  currentIndex: number,
+  canTakeValue: boolean,
+): number {
+  const next = argv[currentIndex + 1];
+  if (canTakeValue && next !== undefined && !next.startsWith('-')) {
+    setFlag(flags, key, next);
+    return currentIndex + 1;
+  }
+  setFlag(flags, key, true);
+  return currentIndex;
+}
 
 export function parseArgs(argv: string[]): ParsedArgs {
   const flags = new Map<string, FlagValue>();
@@ -38,26 +75,31 @@ export function parseArgs(argv: string[]): ParsedArgs {
     }
     if (arg === '--') {
       // Everything after a bare `--` belongs to the child command, verbatim
-      // — never parsed as flags (`pyric dev -- npm start --port 3000`).
+      // — never parsed as flags (`pyric sandbox -- npm start --port 3000`).
       passthrough.push(...argv.slice(i + 1).filter((a): a is string => a !== undefined));
       break;
     }
+    if (isExecutionSubcommand(subcommand) && positional.length > 0) {
+      positional.push(arg);
+      i += 1;
+      continue;
+    }
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
       if (eq !== -1) {
         setFlag(flags, arg.slice(2, eq), arg.slice(eq + 1));
       } else {
         const key = arg.slice(2);
-        const next = argv[i + 1];
-        if (!BOOLEAN_FLAGS.has(key) && next && !next.startsWith('-')) {
-          setFlag(flags, key, next);
-          i += 1;
-        } else {
-          setFlag(flags, key, true);
-        }
+        i = consumeFlag(flags, key, argv, i, !isBooleanFlag(key));
+      }
+    } else if (arg.startsWith('-') && arg !== '-') {
+      const raw = arg.slice(1);
+      const longKey = SHORT_VALUE_ALIASES.get(raw);
+      if (longKey !== undefined) {
+        i = consumeFlag(flags, longKey, argv, i, true);
+      } else {
+        setFlag(flags, raw, true);
       }
-    } else if (arg.startsWith('-')) {
-      setFlag(flags, arg.slice(1), true);
     } else if (subcommand === null) {
       subcommand = arg;
     } else {
@@ -68,6 +110,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
   return { subcommand, flags, positional, passthrough };
 }
 
+function isExecutionSubcommand(subcommand: string | null): boolean {
+  return subcommand === 'sandbox';
+}
+
 function setFlag(flags: Map<string, FlagValue>, key: string, value: string | boolean): void {
   const current = flags.get(key);
   if (current === undefined) {

package/src/cli/pyric-config.ts

@@ -0,0 +1,45 @@
+/**
+ * Reader for the optional project-level `pyric.json` configuration file.
+ *
+ * Configures defaults for `pyric sandbox` (such as a default `command`,
+ * custom `port`, or explicit `rules` paths) without requiring CLI flags
+ * or magic process sniffing.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface PyricRulesConfig {
+  firestore?: string;
+  database?: string;
+  storage?: string;
+}
+
+export interface PyricConfig {
+  /** Default command to execute under the sandbox if none is passed on CLI. */
+  command?: string;
+  /** Local port to bind the Pyric sandbox host. */
+  port?: number;
+  /** Path to Firestore, RTDB, or Storage rules files. */
+  rules?: string | PyricRulesConfig;
+  /** Project ID label for emulation. */
+  project?: string;
+}
+
+export async function readPyricConfig(cwd: string = process.cwd()): Promise<PyricConfig> {
+  const path = join(cwd, 'pyric.json');
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw e;
+  }
+  try {
+    return JSON.parse(raw) as PyricConfig;
+  } catch (e) {
+    throw new Error(
+      `pyric: failed to parse pyric.json: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}