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

package/src/cli/sandbox-interlock.ts

@@ -0,0 +1,167 @@
+/**
+ * The interlock: the launcher's statement about interception in the child it
+ * is about to start, plus the warn-only watchdog for the child's answer.
+ *
+ * The status line is knowable synchronously from the env `pyric sandbox` just
+ * assembled: guard mode, whether NODE_OPTIONS really carries the register
+ * import, and where the child's handshake beacon will land. The watchdog is
+ * the other half: a child still alive well after launch that never posted a
+ * beacon is probably not intercepted.
+ */
+import { beaconEndpoint } from '../register/beacon.js';
+import { parseGuardMode, type GuardMode } from '../register/net-guard.js';
+import { detectUnsupportedRuntime, formatUnsupportedRuntimeWarning } from './unsupported-runtime.js';
+
+/**
+ * What `pyric sandbox` can say about the interception it is about to hand the
+ * child, entirely from the env it just assembled: no waiting, no round trip.
+ */
+export interface InterlockStatus {
+  /** Net-guard mode the child will run under (`PYRIC_GUARD`, default warn). */
+  readonly guard: GuardMode;
+  /** Whether `NODE_OPTIONS` actually carries the register `--import`. */
+  readonly registerImported: boolean;
+  /** Where the child's handshake beacon will land, or null when the
+   *  activator carries no bridge URL. */
+  readonly beacon: string | null;
+}
+
+/**
+ * Read the interlock off the child env. Everything here is synchronous by
+ * construction: it is a statement about the launch, printed before anything at
+ * runtime has had a chance to go wrong.
+ */
+export function describeInterlock(
+  childEnv: NodeJS.ProcessEnv,
+  registerUrl: string,
+): InterlockStatus {
+  return {
+    guard: parseGuardMode(childEnv.PYRIC_GUARD),
+    registerImported: (childEnv.NODE_OPTIONS ?? '').includes(`--import ${registerUrl}`),
+    beacon: beaconEndpoint(childEnv.PYRIC_SANDBOX),
+  };
+}
+
+/**
+ * The startup status line, alongside the other `✔ <service>` checks.
+ *
+ * The healthy line is deliberately short: one fact per field and nothing the
+ * reader has to skim past. The degraded line is long because it reports a
+ * broken launch, which is worth every word.
+ */
+export function formatInterlockLine(status: InterlockStatus): string {
+  if (!status.registerImported) {
+    return (
+      `⚠ interlock guard=${status.guard}, register is NOT in the child's NODE_OPTIONS. ` +
+      `Its firebase-admin/firebase imports will NOT be rewritten and would reach LIVE Firebase.\n`
+    );
+  }
+  return `✔ interlock guard=${status.guard}, register loaded via NODE_OPTIONS\n`;
+}
+
+export interface LaunchCheckOptions {
+  /** The environment the child is about to receive. */
+  readonly childEnv: NodeJS.ProcessEnv;
+  /** Absolute `file:` URL of the register module, to look for in NODE_OPTIONS. */
+  readonly registerUrl: string;
+  /** The child's argv, for the unsupported-runtime check. */
+  readonly argv: readonly string[];
+  readonly write: (line: string) => void;
+}
+
+/**
+ * Every statement the launcher makes about the child, printed in one block
+ * before the spawn, and the interlock status it derived on the way.
+ *
+ * Two checks: the interlock status line, from the env alone, and the
+ * unsupported-runtime warning for the other way interception can be absent, a
+ * child runtime that never evaluates Node loader hooks at all.
+ */
+export function reportLaunchChecks(opts: LaunchCheckOptions): InterlockStatus {
+  const interlock = describeInterlock(opts.childEnv, opts.registerUrl);
+  opts.write(formatInterlockLine(interlock));
+  const unsupportedRuntime = detectUnsupportedRuntime(opts.argv);
+  if (unsupportedRuntime !== null) opts.write(formatUnsupportedRuntimeWarning(unsupportedRuntime));
+  return interlock;
+}
+
+/** How long a child may live without its beacon before we say something. */
+const BEACON_GRACE_MS = 15_000;
+
+export interface BeaconWatchdogOptions {
+  /** The child command, for attribution in the warning. */
+  readonly label: string;
+  /** The endpoint the child would post to. Null means nothing to watch. */
+  readonly beacon: string | null;
+  /** Whether a beacon from this child has been recorded. */
+  readonly sawBeacon: () => boolean;
+  /** Whether the child is still running. */
+  readonly isAlive: () => boolean;
+  readonly warn: (line: string) => void;
+  readonly graceMs?: number;
+}
+
+export interface BeaconWatchdog {
+  /** Cancel a pending check. Idempotent. */
+  stop(): void;
+}
+
+/** The warning itself: one paragraph naming what the silence means and what
+ *  to check. Kept separate so its exact wording is testable. */
+export function formatMissingBeaconWarning(opts: {
+  label: string;
+  graceMs: number;
+  beacon: string;
+}): string {
+  const seconds = Math.round(opts.graceMs / 1000);
+  return (
+    `  ⚠ interlock: \`${opts.label}\` has been running ${seconds}s without posting a register ` +
+    `beacon to ${opts.beacon}. Its firebase-admin/firebase imports are probably NOT routed to ` +
+    `the pyric sandbox, which means they would reach LIVE Firebase. Check that the command starts ` +
+    `a Node process (bun and deno do not evaluate Node loader hooks), that it does not overwrite ` +
+    `NODE_OPTIONS, and that NODE_ENV is not production. Warning only: nothing was blocked, and ` +
+    `this is reported once per child.`
+  );
+}
+
+/**
+ * The warn-only interlock watchdog.
+ *
+ * It never kills the child and never blocks a request. The reason is the
+ * signal's own honesty: beacon delivery is best-effort (see
+ * `register/beacon.ts`), and a plausible silent child is not the same thing as
+ * a broken one. A short-lived script that exits before its POST lands, a child
+ * that reaches the sandbox only through a grandchild, a dev server slow to
+ * boot: each would be killed by a fail-closed version of this check, and each
+ * is fine.
+ *
+ * So the heuristic is the simple, attributable one: the child is still alive
+ * `graceMs` after launch and no beacon has arrived. Both halves matter. An
+ * exited child was never expected to say anything, and a child whose beacon
+ * landed has already proved the point. One warning per child, guaranteed by
+ * the one-shot timer; the timer is unref'd so a watchdog can never be the
+ * reason a process stays up.
+ *
+ * `sawBeacon` is a count delta rather than a pid match, deliberately. The
+ * process that loads register is often a grandchild (`npm run dev` starts
+ * node, `next dev` starts its worker), so the spawned child's own pid is
+ * frequently not the pid in the beacon, and matching on it would warn about
+ * perfectly healthy launches. The delta's known imprecision runs the other
+ * way: a sibling runtime's beacon that lands inside the grace window can mask
+ * a real miss. Erring toward silence is the right bias for a warn-only check.
+ */
+export function startBeaconWatchdog(opts: BeaconWatchdogOptions): BeaconWatchdog {
+  const beacon = opts.beacon;
+  if (beacon === null) return { stop: () => {} };
+  const graceMs = opts.graceMs ?? BEACON_GRACE_MS;
+  const timer = setTimeout(() => {
+    if (opts.sawBeacon() || !opts.isAlive()) return;
+    opts.warn(formatMissingBeaconWarning({ label: opts.label, graceMs, beacon }));
+  }, graceMs);
+  timer.unref?.();
+  return {
+    stop(): void {
+      clearTimeout(timer);
+    },
+  };
+}

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,21 @@
  *   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';
+import { SHELL_OPERATORS } from './unsupported-runtime.js';
 
 // ─── 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 +62,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;
 }
 
@@ -145,41 +153,60 @@ export function registerModuleUrl(): string {
   return new URL('../register/index.js', import.meta.url).href;
 }
 
+/** What the launcher has to put in a child's environment for interception. */
+export interface ChildActivation {
+  /** The serve host the child's sandbox calls reach. */
+  readonly serveUrl: string;
+  /** Absolute `file:` URL of the register module. */
+  readonly registerUrl: string;
+  /** The per-launch secret the child's handshake beacon must present.
+   *  Absent when the launcher runs no beacon receiver, as the Vite plugin's
+   *  Functions runtime does; the child then reports on stderr only. */
+  readonly beaconToken?: string | undefined;
+}
+
 /**
- * Child env: sets the activator and APPENDS the loader to NODE_OPTIONS —
- * never replaces it (the user's own --inspect / --max-old-space-size etc.
- * must survive). `file:` URLs are percent-encoded, so no quoting is needed
- * even for paths with spaces.
+ * Child env: sets the activator and the beacon secret, and APPENDS the loader
+ * to NODE_OPTIONS rather than replacing it (the user's own --inspect /
+ * --max-old-space-size and so on must survive). `file:` URLs are
+ * percent-encoded, so no quoting is needed even for paths with spaces.
  */
 export function buildChildEnv(
   base: NodeJS.ProcessEnv,
-  opts: { serveUrl: string; registerUrl: string },
+  opts: ChildActivation,
 ): NodeJS.ProcessEnv {
   const importFlag = `--import ${opts.registerUrl}`;
-  return {
+  const env: NodeJS.ProcessEnv = {
     ...base,
     PYRIC_SANDBOX: `remote:${opts.serveUrl}`,
     NODE_OPTIONS: base.NODE_OPTIONS ? `${base.NODE_OPTIONS} ${importFlag}` : importFlag,
   };
+  if (opts.beaconToken !== undefined) env.PYRIC_BEACON_TOKEN = opts.beaconToken;
+  return env;
 }
 
 /**
  * Format copy-pasteable POSIX export statements for host-only startup.
  * Grouped in a cleanly formatted console block for easy selection and copying
  * into a separate terminal (for example, when running Next.js independently).
+ *
+ * The beacon secret is part of the block: without it a process started this
+ * way still intercepts, but the dev server cannot confirm that it did.
  */
-export function formatStartupEnvExport(opts: { serveUrl: string; registerUrl: string }): string {
-  const pyricSandbox = `remote:${opts.serveUrl}`;
-  const nodeOptions = `--import ${opts.registerUrl}`;
-  const line1 = `export PYRIC_SANDBOX="${pyricSandbox}"`;
-  const line2 = `export NODE_OPTIONS="${nodeOptions}"`;
-  const divider = '─'.repeat(Math.max(line1.length, line2.length) + 4);
+export function formatStartupEnvExport(opts: ChildActivation): string {
+  const lines = [`export PYRIC_SANDBOX="remote:${opts.serveUrl}"`];
+  if (opts.beaconToken !== undefined) {
+    lines.push(`export PYRIC_BEACON_TOKEN="${opts.beaconToken}"`);
+  }
+  lines.push(`export NODE_OPTIONS="--import ${opts.registerUrl}"`);
+  const width = Math.max(...lines.map((line) => line.length));
+  const divider = '─'.repeat(width + 4);
+  const body = lines.map((line) => `  ${line}\n`).join('');
   return (
     '\n' +
     '  To run external commands against this sandbox, paste in another terminal:\n' +
     `  ${divider}\n` +
-    `  ${line1}\n` +
-    `  ${line2}\n` +
+    body +
     `  ${divider}\n`
   );
 }
@@ -215,37 +242,64 @@ 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;
+
+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));
+
+  // The bun/deno warning is emitted by the launch seam in serve.ts, alongside
+  // the interlock line, so every pre-spawn statement about the child prints in
+  // one block and in order.
+
+  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 +321,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 +355,5 @@ export function spawnDevChild(
     },
   };
 }
+
+export const spawnDevChild = spawnSandboxChild;