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

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/{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;