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

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]
@@ -15,6 +15,7 @@
  *   pyric firestore rules resolve <path> [--out <path>]
  *   pyric firestore indexes generate <path...> [--out <path>]
  *   pyric storage rules lint <path>
+ *   pyric storage rules resolve <path> [--out <path>]
  *   pyric storage rules simulate [--stdin]
  *   pyric database rules lint <path>
  *   pyric database rules validate <path>
@@ -54,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]
@@ -71,6 +72,7 @@ USAGE
   pyric firestore rules resolve <path> [--out <path>]
   pyric firestore indexes generate <path...> [--out <path>]
   pyric storage rules lint <path>
+  pyric storage rules resolve <path> [--out <path>]
   pyric storage rules simulate [--stdin]
   pyric database rules lint <path>
   pyric database rules validate <path>
@@ -81,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]\`.
@@ -100,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
@@ -127,64 +127,73 @@ COMMANDS
   firestore rules resolve    Resolve Firestore 2+modules imports to one ruleset.
   firestore indexes generate Generate firestore.indexes.json from application source.
   storage rules lint         Check Storage rules syntax locally.
+  storage rules resolve      Resolve Storage 2+modules imports to one ruleset.
   storage rules simulate     Run the local Storage rules evaluator.
   database rules lint        Run the Realtime Database rules expression linter.
   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.
@@ -333,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/mcp-proxy.ts

@@ -1,17 +1,16 @@
 /**
  * `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: a Claude Code plugin can only declare a STATIC MCP URL in
- * `.mcp.json`, but serve's endpoint is `http://localhost:<PORT>/__pyric/mcp`
- * with a runtime port (scan-forward / AirPlay). So the plugin declares a
- * STDIO server that runs this proxy; the proxy discovers the live serve and
- * forwards the protocol. No manual `claude mcp add`, no fixed port.
+ * Why this exists: the agent plugin declares one static stdio command, while
+ * serve's endpoint is `http://localhost:<PORT>/__pyric/mcp` with a runtime
+ * port (scan-forward / AirPlay). The proxy discovers the live serve and
+ * forwards the protocol. No per-client MCP setup, no fixed port.
  * (design rationale)
  *
  * Relay is at the TRANSPORT level via the MCP SDK's own transports — we do
  * NOT re-implement JSON-RPC/SSE/session framing. `StdioServerTransport`
- * talks to Claude Code; `StreamableHTTPClientTransport` talks to serve; each
+ * talks to the MCP client; `StreamableHTTPClientTransport` talks to serve; each
  * transport's `onmessage` is piped to the other's `send`.
  *
  * Two hardening layers sit on top of that pipe:
@@ -22,7 +21,7 @@
  *     + IPv6 `[::1]:P`); without this, the proxy locks onto whichever family
  *     answers first while the browser is on the other — split-brain.
  *   TIMEOUT — every relayed request is failed with a JSON-RPC error after
- *     REQUEST_TIMEOUT_MS instead of hanging Claude Code forever (a killed
+ *     REQUEST_TIMEOUT_MS instead of hanging the agent forever (a killed
  *     server can leave a half-open keep-alive socket that never FINs). A
  *     `settled` set swallows a late real response so the client never sees a
  *     duplicate after the timeout already failed the call.
@@ -85,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)}`,
+    );
+  }
+}

package/src/cli/rules.ts

@@ -125,14 +125,30 @@ export async function runRulesValidate(parsed: ParsedArgs, deps: RulesDeps = {})
 export async function runRulesResolve(
   parsed: ParsedArgs,
   deps: ResolveRulesDeps = {},
+): Promise<number> {
+  return runServiceRulesResolve('firestore', parsed, deps);
+}
+
+export async function runStorageRulesResolve(
+  parsed: ParsedArgs,
+  deps: ResolveRulesDeps = {},
+): Promise<number> {
+  return runServiceRulesResolve('storage', parsed, deps);
+}
+
+async function runServiceRulesResolve(
+  service: 'firestore' | 'storage',
+  parsed: ParsedArgs,
+  deps: ResolveRulesDeps,
 ): Promise<number> {
   const out = deps.stdout ?? process.stdout;
   const err = deps.stderr ?? process.stderr;
   const cwd = deps.cwd ?? process.cwd();
+  const command = `pyric ${service} rules resolve`;
   const sourcePath = parsed.positional[0];
   if (!sourcePath) {
     err.write(
-      'pyric firestore rules resolve: missing rules-file path. Usage: pyric firestore rules resolve <path> [--out <path>]\n',
+      `${command}: missing rules-file path. Usage: ${command} <path> [--out <path>]\n`,
     );
     return 1;
   }
@@ -143,16 +159,27 @@ export async function runRulesResolve(
     source = await (deps.readFile ?? readFile)(absoluteSourcePath, 'utf-8');
   } catch (error) {
     err.write(
-      `pyric firestore rules resolve: ${error instanceof Error ? error.message : String(error)}\n`,
+      `${command}: ${error instanceof Error ? error.message : String(error)}\n`,
     );
     return 1;
   }
 
+  const expectedService =
+    service === 'storage' ? 'firebase.storage' : 'cloud.firestore';
+  const parsedSource = parseToAST(source);
+  if (parsedSource && parsedSource.service.name !== expectedService) {
+    err.write(
+      `${command}: source declares service ${parsedSource.service.name}; expected ${expectedService}\n`,
+    );
+    return 2;
+  }
+
   const result = (deps.resolveModules ?? resolveModules)(source, {
     basePath: dirname(absoluteSourcePath),
+    sourceFile: sourcePath,
   });
   if (!result.success) {
-    err.write(`pyric firestore rules resolve: ${result.error.message}\n`);
+    err.write(`${command}: ${result.error.message}\n`);
     return 2;
   }
 
@@ -169,7 +196,7 @@ export async function runRulesResolve(
     result.data.resolved.endsWith('\n') ? result.data.resolved : `${result.data.resolved}\n`,
     'utf-8',
   );
-  out.write(`pyric firestore rules resolve: wrote ${outputPath}\n`);
+  out.write(`${command}: wrote ${outputPath}\n`);
   return 0;
 }