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

package/src/cli/serve.ts

@@ -10,8 +10,9 @@
  * rules load (fail fast on broken rules) → SDK bundle (cached per pyric
  * version) → static server with the `/__pyric/` namespace + HTML injection.
  */
+import { randomBytes } from 'node:crypto';
 import { join, relative, resolve } from 'node:path';
-import { existsSync, readdirSync, readFileSync, statSync, watch as watchFile } from 'node:fs';
+import { existsSync, watch as watchFile } from 'node:fs';
 import type { ParsedArgs } from './parse-args.js';
 import { readFirebaseJson, readFirebaseRc, type FirebaseJson } from './firebase-json.js';
 import { bundleSdk, bundleWorker, defaultSdkEntries, resolveSiteUiDir } from '../serve/bundler.js';
@@ -22,7 +23,9 @@ import {
   embeddedWorkerVersion,
 } from '../serve/standalone-assets.js';
 import { hasSandboxBuildMarker } from '../serve/sandbox-marker.js';
+import { formatBeaconReceipt } from '../serve/beacon-route.js';
 import type { InitPayload } from '../serve/namespace.js';
+import { formatAiStatusLine } from '../serve/ai-status.js';
 import { injectServeTags } from '../serve/html-injection.js';
 import { formatActivityWarning } from '../serve/activity-warning.js';
 import { consoleServeLogger, startStaticServer, stderrServeLogger, type ServeHandle } from '../serve/server.js';
@@ -38,6 +41,12 @@ import {
   waitForSandboxPeer,
   type SandboxChildHandle,
 } from './sandbox-runner.js';
+import {
+  reportLaunchChecks,
+  startBeaconWatchdog,
+  type BeaconWatchdog,
+} from './sandbox-interlock.js';
+import { scanForInlinedFirebase } from './inlined-sdk-scanner.js';
 import {
   createFunctionsDevelopmentRuntime,
   createHttpFunctionsPeerReadiness,
@@ -88,6 +97,12 @@ export interface ServeRuntime {
   uiUrl: string | null;
   /** Persistence summary (null when `--persist` is off). */
   persist: { restoredDocs: number; restoredUsers: number } | null;
+  /** Handshake beacons posted to `/__pyric/beacon` so far, the interlock
+   *  watchdog's only input. */
+  beaconCount: () => number;
+  /** The per-launch secret a beacon must present, placed in every child's
+   *  `PYRIC_BEACON_TOKEN`. */
+  beaconToken: string;
 }
 
 /** The `--json` stdout contract — one line, keep stable; agents parse this.
@@ -152,6 +167,12 @@ export async function startServe(opts: {
 }): Promise<ServeRuntime> {
   const logger = opts.logger ?? consoleServeLogger();
 
+  // Handshake beacons from pyric-launched children, plus the per-launch secret
+  // that authorizes one. Both live here because the route does.
+  let beaconsSeen = 0;
+  const beaconCount = (): number => beaconsSeen;
+  const beaconToken = randomBytes(24).toString('base64url');
+
   // --fresh only means anything against the state.json file `--persist`
   // maintains — without `--persist` there is no file to discard, so
   // `--fresh` alone was a silent no-op (nothing happened, nothing said so).
@@ -212,12 +233,12 @@ export async function startServe(opts: {
 
   // The import map can only remap BARE `firebase/*` specifiers. A plain bundler
   // build (`vite build`) inlines the real SDK into the app chunk, leaving
-  // nothing to intercept — the page would then talk to REAL Firebase endpoints
+  // nothing to intercept: the page would then talk to REAL Firebase endpoints
   // with the sandbox's fake credentials while the injected banner claims
   // otherwise. That hole is structural, so `pyric sandbox` refuses such a dist
   // rather than serving it. A pyric SANDBOX build (`vite build --mode
   // development`) carries the marker and bundles pyric's in-page adapters, so it
-  // is trusted and the scan is skipped (marker present → no real SDK to find).
+  // is trusted and the scan is skipped (marker present, no real SDK to find).
   if (!hasSandboxBuildMarker(publicDir)) {
     const inlined = scanForInlinedFirebase(publicDir);
     if (inlined.length > 0) {
@@ -306,6 +327,11 @@ export async function startServe(opts: {
       studio: opts.ui ? { siteUiDir } : false,
       bridgeUrl: () => mount && origin.port > 0 ? mount.wsUrl(origin) : null,
       activity: (incident) => logger.note(formatActivityWarning(incident)),
+      beaconToken,
+      beacon: (report) => {
+        beaconsSeen += 1;
+        logger.note(formatBeaconReceipt(report));
+      },
       permissive: opts.permissive,
       logger,
     });
@@ -494,7 +520,7 @@ export async function startServe(opts: {
     session.payload().storageRules
       ? `✔ rules    ${session.summary.rules.storage.sourcePath} → deployed to the storage sandbox (hash ${session.summary.rules.storage.hash}; ` +
         `edits require a restart — storage rules do not hot-reload)`
-      : `• rules    no storage.rules — storage sandbox runs open (no rules configured)`,
+      : `• rules    no storage.rules — storage sandbox denies client operations by default`,
   );
   if (uiUrl) {
     logger.info(`✔ studio   Pyric Studio: ${uiUrl}`);
@@ -505,6 +531,13 @@ export async function startServe(opts: {
   if (mount) {
     logger.info(`✔ bridge   MCP endpoint: ${mount.mcpUrl(origin)} (sandbox peers over ws at /__pyric/sandbox)`);
   }
+  // AI is a mounted service like the bridge: `/__pyric/ai-proxy` answers from
+  // the first request on, whether or not anything is configured. `pyric
+  // sandbox` has no AI flag, so the ENGINE is always the page's own `getAI()`
+  // choice (resolved lazily in the browser, since nothing here instantiates a
+  // broker to find out); what this server does decide is where the proxy
+  // forwards, and that is what the line reports.
+  logger.info(formatAiStatusLine({}));
   let persistSummary: ServeRuntime['persist'] = null;
   const persistence = session.summary.persistence;
   if (persistence) {
@@ -553,7 +586,8 @@ export async function startServe(opts: {
   logger.note('');
   logger.note('  ⚠ the pyric sandbox runs IN the served page — keep the browser tab open.');
   logger.note('    Firestore/auth data and persistence stop when no page is open.');
-  return { handle, publicDir, payload, uiUrl, mcpUrl: mount ? mount.mcpUrl(origin) : null, persist: persistSummary };
+  const mcpUrl = mount ? mount.mcpUrl(origin) : null;
+  return { handle, publicDir, payload, uiUrl, mcpUrl, persist: persistSummary, beaconCount, beaconToken };
 }
 
 /**
@@ -779,6 +813,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   }
 
   let devChild: SandboxChildHandle | null = null;
+  let beaconWatchdog: BeaconWatchdog | null = null;
   let functionsRuntime: FunctionsDevelopmentRuntime | null = null;
   let resolveFunctionsExit!: (code: number) => void;
   const functionsExited = new Promise<number>((resolve) => { resolveFunctionsExit = resolve; });
@@ -801,6 +836,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     ]);
   const stopAfterSignal = async (): Promise<number> => {
     (json ? process.stderr : process.stdout).write('\nShutting down...\n');
+    beaconWatchdog?.stop();
     if (devChild && devChild.child.exitCode === null) devChild.signal(await signal);
     await functionsRuntime?.close().catch(() => undefined);
     await runtime.handle.stop().catch(() => undefined);
@@ -845,6 +881,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       baseEnv: process.env,
       serveUrl: runtime.handle.url,
       registerUrl: registerModuleUrl(),
+      beaconToken: runtime.beaconToken,
       instance: `${functionsProjectId}-default-rtdb`,
       location: process.env.PYRIC_FUNCTIONS_RTDB_REGION ?? 'us-central1',
       projectId: functionsProjectId ?? 'demo-project',
@@ -910,19 +947,37 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     info.write(
       `✔ run      \`${plan.label}\` — firebase-admin/firebase imports are routed to the sandbox at ${runtime.handle.url}\n`,
     );
-    devChild = spawnSandboxChild(plan, {
-      cwd,
-      json,
-      env: buildChildEnv(process.env, {
-        serveUrl: runtime.handle.url,
-        registerUrl: registerModuleUrl(),
-      }),
+    const childEnv = buildChildEnv(process.env, {
+      serveUrl: runtime.handle.url,
+      registerUrl: registerModuleUrl(),
+      beaconToken: runtime.beaconToken,
+    });
+    // What we are handing the child, stated before it starts: the interlock
+    // line and the unsupported-runtime check.
+    const interlock = reportLaunchChecks({
+      childEnv,
+      registerUrl: registerModuleUrl(),
+      argv: plan.argv,
+      write: (line) => info.write(line),
+    });
+
+    devChild = spawnSandboxChild(plan, { cwd, json, env: childEnv });
+    // A child still alive well after launch that never posted a beacon is very
+    // likely not intercepted. `startBeaconWatchdog` says why this only warns.
+    const beaconsAtSpawn = runtime.beaconCount();
+    beaconWatchdog = startBeaconWatchdog({
+      label: plan.label,
+      beacon: interlock.beacon,
+      sawBeacon: () => runtime.beaconCount() > beaconsAtSpawn,
+      isAlive: () => devChild !== null && devChild.child.exitCode === null,
+      warn: (line) => void process.stderr.write(`${line}\n`),
     });
   } else if (!json) {
     process.stdout.write(
       formatStartupEnvExport({
         serveUrl: runtime.handle.url,
         registerUrl: registerModuleUrl(),
+        beaconToken: runtime.beaconToken,
       }),
     );
   }
@@ -934,6 +989,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       if (settled) return;
       settled = true;
       void (async () => {
+        beaconWatchdog?.stop();
         await functionsRuntime?.close().catch(() => undefined);
         if (devChild && devChild.child.exitCode === null) {
           devChild.signal('SIGTERM');
@@ -971,60 +1027,3 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     void signal.then(shutdown);
   });
 }
-
-/**
- * Detect a bundler build that INLINED the real firebase SDK into its served
- * assets (`vite build` output). The served import map remaps only bare
- * `firebase/*` specifiers, so such a build cannot be sandboxed — its calls
- * reach real Google endpoints. Fingerprints are real-SDK-only endpoint hosts
- * that never appear in a sandbox-clean app (whose calls all route to
- * `/__pyric/*`). Bounded: depth ≤ 4, ≤ 200 script files, first hit per file.
- * Returns publicDir-relative paths of offending assets.
- */
-export function scanForInlinedFirebase(dir: string): string[] {
-  const FINGERPRINTS = [
-    'identitytoolkit.googleapis.com',
-    'firestore.googleapis.com',
-    'securetoken.googleapis.com',
-    'firebasedatabase.app',
-  ];
-  const hits: string[] = [];
-  let scanned = 0;
-  const walk = (d: string, rel: string, depth: number): void => {
-    if (depth > 4 || scanned >= 200) return;
-    let names: string[];
-    try {
-      names = readdirSync(d);
-    } catch {
-      return;
-    }
-    for (const name of names) {
-      if (scanned >= 200) return;
-      const p = join(d, name);
-      const r = rel ? `${rel}/${name}` : name;
-      let st;
-      try {
-        st = statSync(p);
-      } catch {
-        continue;
-      }
-      if (st.isDirectory()) {
-        // The pyric namespace itself never lands in hosting.public, but a
-        // node_modules inside a served dir would be a scan-cost trap.
-        // Dot-directories (.next, .git, .pyric) are internal caches and must be ignored.
-        if (name === 'node_modules' || name.startsWith('.')) continue;
-        walk(p, r, depth + 1);
-      } else if (/\.(js|mjs)$/.test(name)) {
-        scanned++;
-        try {
-          const text = readFileSync(p, 'utf8');
-          if (FINGERPRINTS.some((f) => text.includes(f))) hits.push(r);
-        } catch {
-          // unreadable asset: skip
-        }
-      }
-    }
-  };
-  walk(dir, '', 0);
-  return hits;
-}

package/src/cli/unsupported-runtime.ts

@@ -0,0 +1,68 @@
+/**
+ * Child runtimes that cannot evaluate Node loader hooks, and the one warning
+ * that says what is lost when a command starts one.
+ */
+
+/** Tokens that end one command and begin the next inside a shell string. */
+export const SHELL_OPERATORS = new Set(['&&', '||', '|', ';', '&']);
+
+/** Command basenames that cannot evaluate Node loader hooks, to the runtime. */
+const UNSUPPORTED_RUNTIME_BINARIES = new Map<string, string>([
+  ['bun', 'bun'],
+  ['bunx', 'bun'],
+  ['deno', 'deno'],
+]);
+
+/** Leading `KEY=VAL` environment assignments in a shell command. */
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/** Strip directory and a Windows `.exe` suffix from a command token. */
+function commandBasename(token: string): string {
+  const base = token.split(/[\\/]/).pop() ?? token;
+  return base.toLowerCase().replace(/\.exe$/, '');
+}
+
+/**
+ * Decide whether the child command starts a runtime that cannot intercept.
+ *
+ * Detection is by command name: argv[0], and any token that begins a new
+ * command after a shell operator, with leading `KEY=VAL` assignments skipped
+ * and the path and `.exe` decoration stripped. That is the honest 90%.
+ * `npm run dev` whose package script shells out to bun is undetectable from
+ * here, and guessing would cost false positives on names that merely start
+ * with the same letters (`bundle exec`).
+ *
+ * Returns the canonical runtime name (`bun` for `bunx` too) or null.
+ */
+export function detectUnsupportedRuntime(argv: readonly string[]): string | null {
+  let atCommandStart = true;
+  for (const token of argv) {
+    if (atCommandStart && ENV_ASSIGNMENT.test(token)) continue;
+    if (SHELL_OPERATORS.has(token)) {
+      atCommandStart = true;
+      continue;
+    }
+    if (atCommandStart) {
+      const runtime = UNSUPPORTED_RUNTIME_BINARIES.get(commandBasename(token));
+      if (runtime !== undefined) return runtime;
+      atCommandStart = false;
+    }
+  }
+  return null;
+}
+
+/**
+ * The one warning. It has to say both halves of what is lost: the loader swap
+ * (interception itself) and the net guard (the socket backstop that would
+ * otherwise catch the egress), because the guard is installed by the same
+ * `--import`ed register module and is therefore just as absent.
+ */
+export function formatUnsupportedRuntimeWarning(runtime: string): string {
+  return (
+    `  ⚠ runtime: pyric interception is not supported under \`${runtime}\`. It does not evaluate ` +
+    `Node loader hooks, so the child's firebase/firebase-admin imports will NOT be rewritten and ` +
+    `may reach LIVE Firebase. The net-guard socket backstop also only applies under Node, so it ` +
+    `will not catch that egress either. Run the command under \`node\` (or \`npx tsx\`) for the ` +
+    `sandbox swap. Warning only: nothing was blocked.\n`
+  );
+}