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

package/dist/cli/sandbox-interlock.d.ts

@@ -0,0 +1,97 @@
+import { type GuardMode } from '../register/net-guard.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 declare function describeInterlock(childEnv: NodeJS.ProcessEnv, registerUrl: string): InterlockStatus;
+/**
+ * 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 declare function formatInterlockLine(status: InterlockStatus): string;
+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 declare function reportLaunchChecks(opts: LaunchCheckOptions): InterlockStatus;
+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 declare function formatMissingBeaconWarning(opts: {
+    label: string;
+    graceMs: number;
+    beacon: string;
+}): string;
+/**
+ * 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 declare function startBeaconWatchdog(opts: BeaconWatchdogOptions): BeaconWatchdog;
+//# sourceMappingURL=sandbox-interlock.d.ts.map

package/dist/cli/sandbox-interlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-interlock.d.ts","sourceRoot":"","sources":["../../src/cli/sandbox-interlock.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;2CACuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,CAAC,UAAU,EAC3B,WAAW,EAAE,MAAM,GAClB,eAAe,CAMjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAQnE;AAED,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAM5E;AAKD,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AAED;gEACgE;AAChE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAUT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,cAAc,CAc/E"}

package/dist/cli/sandbox-interlock.js

@@ -0,0 +1,112 @@
+/**
+ * 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 } from '../register/net-guard.js';
+import { detectUnsupportedRuntime, formatUnsupportedRuntimeWarning } from './unsupported-runtime.js';
+/**
+ * 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, registerUrl) {
+    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) {
+    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`;
+}
+/**
+ * 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) {
+    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;
+/** 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) {
+    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) {
+    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() {
+            clearTimeout(timer);
+        },
+    };
+}
+//# sourceMappingURL=sandbox-interlock.js.map

package/dist/cli/sandbox-interlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-interlock.js","sourceRoot":"","sources":["../../src/cli/sandbox-interlock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAkB,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAgBrG;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAA2B,EAC3B,WAAmB;IAEnB,OAAO;QACL,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC3C,gBAAgB,EAAE,CAAC,QAAQ,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,WAAW,EAAE,CAAC;QACnF,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAuB;IACzD,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC7B,OAAO,CACL,qBAAqB,MAAM,CAAC,KAAK,iDAAiD;YAClF,4FAA4F,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,qBAAqB,MAAM,CAAC,KAAK,sCAAsC,CAAC;AACjF,CAAC;AAYD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAwB;IACzD,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3C,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,kBAAkB,KAAK,IAAI;QAAE,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACjG,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,4EAA4E;AAC5E,MAAM,eAAe,GAAG,MAAM,CAAC;AAoB/B;gEACgE;AAChE,MAAM,UAAU,0BAA0B,CAAC,IAI1C;IACC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAChD,OAAO,CACL,oBAAoB,IAAI,CAAC,KAAK,uBAAuB,OAAO,+BAA+B;QAC3F,aAAa,IAAI,CAAC,MAAM,mEAAmE;QAC3F,+FAA+F;QAC/F,8FAA8F;QAC9F,4FAA4F;QAC5F,kCAAkC,CACnC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA2B;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC;IAChD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;YAAE,OAAO;QAChD,IAAI,CAAC,IAAI,CAAC,0BAA0B,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC,EAAE,OAAO,CAAC,CAAC;IACZ,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,OAAO;QACL,IAAI;YACF,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/{dev-runner.d.ts → sandbox-runner.d.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,10 +8,9 @@
  *   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.
@@ -18,7 +18,7 @@
 import { type ChildProcess } from 'node:child_process';
 /**
  * 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`).
@@ -33,37 +33,35 @@ export declare function waitForSandboxPeer(serveUrl: string, opts?: {
     fetchImpl?: typeof fetch;
     sleep?: (ms: number) => Promise<void>;
 }): Promise<boolean>;
-export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
-/** Lockfile sniff, mirroring how init/vendor pick their install hints. */
-export declare function detectPackageManager(cwd: string): PackageManager;
-/** The project's `dev` script, or null (no package.json / no script). */
-export declare function readDevScript(cwd: string): string | null;
-export interface DevChildPlan {
-    /** argv to spawn — argv[0] is the executable, no shell. */
+export interface SandboxChildPlan {
+    /** argv to spawn — argv[0] is the executable. */
     argv: string[];
     /** Human-readable command for the pre-spawn line. */
     label: string;
 }
+export type DevChildPlan = SandboxChildPlan;
+/**
+ * Tokenize a command string into an argv array, preserving quoted strings.
+ */
+export declare function parseCommandString(cmd: string): 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 declare function resolveDevChild(opts: {
-    passthrough: string[];
-    noRun: boolean;
-    json: boolean;
-    devScript: string | null;
-    packageManager: PackageManager;
-}): DevChildPlan | null;
+export declare function resolveSandboxChild(opts: ResolveSandboxChildOptions): SandboxChildPlan | null;
 /**
  * The absolute `file:` URL of the register module, resolved from
  * @pyric/cli' OWN installed location — `import.meta.resolve` walks this
@@ -73,25 +71,33 @@ export declare function resolveDevChild(opts: {
  * dist/register/), for runtimes without a usable import.meta.resolve.
  */
 export declare function registerModuleUrl(): string;
+/** 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 declare function buildChildEnv(base: NodeJS.ProcessEnv, opts: {
-    serveUrl: string;
-    registerUrl: string;
-}): NodeJS.ProcessEnv;
+export declare function buildChildEnv(base: NodeJS.ProcessEnv, opts: ChildActivation): NodeJS.ProcessEnv;
 /**
  * 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 declare function formatStartupEnvExport(opts: {
-    serveUrl: string;
-    registerUrl: string;
-}): string;
+export declare function formatStartupEnvExport(opts: ChildActivation): string;
 /**
  * Incremental line prefixer: every child output line gets `[dev] `, partial
  * lines are buffered until their newline (or flush at stream end).
@@ -100,22 +106,21 @@ export declare function createLinePrefixer(prefix: string, write: (line: string)
     push(chunk: string): void;
     flush(): void;
 };
-export interface DevChildHandle {
-    /** Resolves with the exit code to propagate once the child is gone. */
+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;
 }
+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 declare function spawnDevChild(plan: DevChildPlan, opts: {
+export declare function spawnSandboxChild(plan: SandboxChildPlan, opts: {
     cwd: string;
     env: NodeJS.ProcessEnv;
     json: boolean;
-}): DevChildHandle;
-//# sourceMappingURL=dev-runner.d.ts.map
+}): SandboxChildHandle;
+export declare const spawnDevChild: typeof spawnSandboxChild;
+//# sourceMappingURL=sandbox-runner.d.ts.map

package/dist/cli/sandbox-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-runner.d.ts","sourceRoot":"","sources":["../../src/cli/sandbox-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,GACL,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAID,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAcxD;AAED,MAAM,WAAW,0BAA0B;IACzC,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,gBAAgB,GAAG,IAAI,CAuB7F;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAQ1C;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;yEAEqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,UAAU,EACvB,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,UAAU,CASnB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAgBpE;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC5B;IAAE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAkB9C;AAOD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3D,kBAAkB,CA6FpB;AAED,eAAO,MAAM,aAAa,0BAAoB,CAAC"}

package/dist/cli/{dev-runner.js → sandbox-runner.js}

@@ -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,21 +8,19 @@
  *   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 } 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`).
@@ -53,51 +52,55 @@ export async function waitForSandboxPeer(serveUrl, opts = {}) {
         await sleep(intervalMs);
     }
 }
-/** Lockfile sniff, mirroring how init/vendor pick their install hints. */
-export function detectPackageManager(cwd) {
-    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';
-}
-/** The project's `dev` script, or null (no package.json / no script). */
-export function readDevScript(cwd) {
-    try {
-        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
-        const dev = pkg.scripts?.dev;
-        return typeof dev === 'string' && dev.trim().length > 0 ? dev : null;
-    }
-    catch {
-        return null;
+/**
+ * Tokenize a command string into an argv array, preserving quoted strings.
+ */
+export function parseCommandString(cmd) {
+    const parts = [];
+    const regex = /[^\s"']+|"([^"]*)"|'([^']*)'/g;
+    let match;
+    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;
 }
 /**
  * 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) {
+export function resolveSandboxChild(opts) {
     if (opts.noRun)
         return null;
-    if (opts.passthrough.length > 0) {
-        return { argv: [...opts.passthrough], label: opts.passthrough.join(' ') };
+    let activeCommand = 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;
 }
@@ -122,35 +125,43 @@ export function registerModuleUrl() {
     return new URL('../register/index.js', import.meta.url).href;
 }
 /**
- * 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, opts) {
     const importFlag = `--import ${opts.registerUrl}`;
-    return {
+    const env = {
         ...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) {
-    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);
+    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`);
 }
 // ─── Line prefixing (pure core) ────────────────────────────────────────────
@@ -177,6 +188,7 @@ export function createLinePrefixer(prefix, write) {
         },
     };
 }
+// ─── Spawn + lifecycle ─────────────────────────────────────────────────────
 /** How long a signalled child may linger before SIGKILL. */
 const FORCE_KILL_AFTER_MS = 2_000;
 /**
@@ -184,17 +196,42 @@ const FORCE_KILL_AFTER_MS = 2_000;
  * In `--json` mode ALL child output goes to stderr — stdout carries exactly
  * the one machine line (the serve --json contract).
  */
-export function spawnDevChild(plan, opts) {
-    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',
-    });
+export function spawnSandboxChild(plan, opts) {
+    const parts = [...plan.argv];
+    const env = { ...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;
+    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));
     const err = createLinePrefixer('[dev] ', (line) => process.stderr.write(line));
@@ -214,7 +251,7 @@ export function spawnDevChild(plan, opts) {
     };
     const exited = new Promise((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) => {
@@ -254,4 +291,5 @@ export function spawnDevChild(plan, opts) {
         },
     };
 }
-//# sourceMappingURL=dev-runner.js.map
+export const spawnDevChild = spawnSandboxChild;
+//# sourceMappingURL=sandbox-runner.js.map