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

package/src/bridge/server/tool-family-factories.ts

@@ -0,0 +1,40 @@
+/**
+ * Node-side factory for each tool family. This is the only bridge module
+ * that imports `pyric/rules/internal/node` or the conformance tools; the
+ * browser side has its own map in `client/tool-family-factories.ts`.
+ *
+ * The keys are the family record filenames. `satisfies` against the keys
+ * derived from the generated aggregate makes a missing or surplus entry a
+ * compile error.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+import {
+  createFirestoreSimulatorTools,
+  createFirestoreRulesTools,
+} from 'pyric/rules/internal/node';
+import { createFirestoreDataTools, createFirestoreInspectTools } from 'pyric/firestore';
+import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
+import { createConformanceTools } from '../../conformance/tools.js';
+import type { ForwardedFamilyKey, InProcessFamilyKey } from '../tool-families.js';
+
+/** A resolver that must never run: forwarded families are executed by the browser peer, not here. */
+export type StubResolver = () => never;
+
+/** Forwarded families, called with a stub so only metadata is read. */
+export const FORWARDED_METADATA_FACTORIES = {
+  'firestore-simulator': (stub) => createFirestoreSimulatorTools({ resolveSandbox: stub as never }),
+  'firestore-data': (stub) => createFirestoreDataTools({ resolveDb: stub as never }),
+  'firestore-inspect': (stub) => createFirestoreInspectTools({ resolveSandbox: stub as never }),
+  'rtdb-inspection': (stub) => createRtdbInspectionTools({ resolveSandbox: stub as never }),
+} satisfies Record<ForwardedFamilyKey, (stub: StubResolver) => ToolHandler[]>;
+
+/**
+ * In-process families, returned as live handlers the MCP server registers
+ * directly. `scope` reaches the rules factory, which appends a hosted
+ * verification tool only when one is supplied; the default surface supplies
+ * none.
+ */
+export const IN_PROCESS_HANDLER_FACTORIES = {
+  'firestore-rules': (scope) => createFirestoreRulesTools({ scope } as never),
+  conformance: () => createConformanceTools(),
+} satisfies Record<InProcessFamilyKey, (scope?: unknown) => ToolHandler[]>;

package/src/bridge/server/tool-metadata.ts

@@ -1,26 +1,27 @@
 /**
- * Extract tool metadata (name + description + parameters) from the
- * existing `pyric/rules` factories without running any
- * tool logic. Used by the bridge to register MCP tools whose actual
- * dispatch happens against the connected browser peer.
+ * Node-side composition of the tool families the bridge serves over MCP.
  *
- * Why: `createFirestoreSimulatorTools` returns `ToolHandler[]` with
- * `execute` bound to a `LocalEnvironment`. The bridge process doesn't
- * have a `LocalEnvironment` — it forwards. But it does need the
- * metadata to populate the MCP server's tool list. This module calls
- * the factory with a stub resolver and reads only the metadata; the
- * stub never gets invoked because the bridge replaces `execute`
- * before dispatch.
+ * Forwarded families are executed by the browser sandbox peer, so this
+ * process never holds a `LocalEnvironment`. It still needs each tool's
+ * metadata (name, description, parameters) to populate the MCP tool list, so
+ * it calls the family factories with a stub resolver and reads only the
+ * metadata; the bridge replaces `execute` with forward-to-peer dispatch
+ * before any call reaches a handler.
+ *
+ * In-process families run here without a browser peer and are returned as
+ * live handlers.
+ *
+ * Family order comes from the records under `../tool-family-records/`; the
+ * factories come from `./tool-family-factories.ts`.
  */
 
 import type { ToolHandler } from '@inbrowser/agent';
+import { toolFamilies } from '../tool-families.js';
 import {
-  createFirestoreSimulatorTools,
-  createFirestoreRulesTools,
-} from 'pyric/rules/internal/node';
-import { createFirestoreDataTools, createFirestoreInspectTools } from 'pyric/firestore';
-import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
-import { createConformanceTools } from '../../conformance/tools.js';
+  FORWARDED_METADATA_FACTORIES,
+  IN_PROCESS_HANDLER_FACTORIES,
+  type StubResolver,
+} from './tool-family-factories.js';
 
 export interface ToolMetadata {
   name: string;
@@ -37,63 +38,30 @@ function toMetadata(handler: ToolHandler): ToolMetadata {
 }
 
 /**
- * Tool metadata for the sandbox bridge. Includes the
- * data-plane / sandbox-management tools that the browser dispatches
- * via `LocalEnvironment`. Rules tooling (lint, validate, simulate,
- * test) is NOT included here — those execute in Node and are
- * registered separately, since they don't need the browser sandbox.
+ * Tool metadata for every forwarded family, in family order. The stub
+ * resolver never runs: the bridge replaces `execute()` with its own
+ * forward-to-peer dispatch.
  */
 export function getSandboxToolMetadata(): ToolMetadata[] {
-  // The resolver stub never runs: the bridge replaces execute() with
-  // its own forward-to-peer dispatch.
-  const stubResolver = async () => {
+  const stub: StubResolver = () => {
     throw new Error(
       'BUG: sandbox-tool factory executor invoked on the bridge side — should have been replaced',
     );
   };
-  const handlers: ToolHandler[] = [
-    // Simulator / write / batch / undo / redo / events / transaction —
-    // 8 tools that mutate or read the in-browser sandbox state.
-    ...createFirestoreSimulatorTools({
-      resolveSandbox: stubResolver as never,
-    }),
-    // Data plane — addDoc / setDoc / getDoc / updateDoc / deleteDoc /
-    // collection / query / where — the modular Firestore CRUD surface
-    // routed through the browser sandbox so agents can drive a real app
-    // session rather than only the simulator.
-    ...createFirestoreDataTools({
-      resolveDb: stubResolver as never,
-    }),
-    // `sandbox_inspect` — single-call diagnostic that answers
-    // "what state is the sandbox in?" Born out of CLAUDE_DEBUG_SESSION.md
-    // (a real agent needing 51 tool calls + 72k tokens to figure out
-    // that rules weren't loaded). Routes to the browser sandbox like
-    // the other forwarded tools.
-    ...createFirestoreInspectTools({
-      resolveSandbox: stubResolver as never,
-    }),
-    ...createRtdbInspectionTools({
-      resolveSandbox: stubResolver as never,
-    }),
-  ];
-  return handlers.map(toMetadata);
+  return toolFamilies('forwarded')
+    .flatMap((family) => FORWARDED_METADATA_FACTORIES[family.key](stub))
+    .map(toMetadata);
 }
 
 /**
- * Tooling factories that execute in-process on the bridge
- * (no browser needed). Returned as live ToolHandlers — the bridge
+ * Live handlers for every in-process family, in family order. The bridge
  * registers each handler's `execute` directly.
  *
  * `scope` is forwarded so the hosted Rules Test API verification tool can
  * authenticate without changing the bridge's sandbox-only execution model.
  */
 export function getInProcessToolHandlers(scope?: unknown): ToolHandler[] {
-  // Factory accepts { scope } per packages/pyric/src/rules/tools.ts.
-  // The bridge does not need to own the structurally compatible type.
-  // Includes the rules tool surface plus the Node-only conformance query.
-  // No browser is needed.
-  return [
-    ...createFirestoreRulesTools({ scope } as never),
-    ...createConformanceTools(),
-  ];
+  return toolFamilies('in-process').flatMap((family) =>
+    IN_PROCESS_HANDLER_FACTORIES[family.key](scope),
+  );
 }

package/src/bridge/tool-families.generated.ts

@@ -0,0 +1,17 @@
+// Generated by scripts/generate-tool-family-registry.ts. Do not edit.
+import type { ToolFamily } from './tool-families.js';
+import conformance from './tool-family-records/conformance.js';
+import firestoreData from './tool-family-records/firestore-data.js';
+import firestoreInspect from './tool-family-records/firestore-inspect.js';
+import firestoreRules from './tool-family-records/firestore-rules.js';
+import firestoreSimulator from './tool-family-records/firestore-simulator.js';
+import rtdbInspection from './tool-family-records/rtdb-inspection.js';
+
+export const TOOL_FAMILIES = [
+  { key: "conformance", ...conformance },
+  { key: "firestore-data", ...firestoreData },
+  { key: "firestore-inspect", ...firestoreInspect },
+  { key: "firestore-rules", ...firestoreRules },
+  { key: "firestore-simulator", ...firestoreSimulator },
+  { key: "rtdb-inspection", ...rtdbInspection },
+] as const satisfies readonly ToolFamily[];

package/src/bridge/tool-families.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool family contract shared by both sides of the bridge.
+ *
+ * A family is authored as one record under `tool-family-records/`: its
+ * transport, its position in the default `tools/list` order, and the exact
+ * tool names its factory yields. `scripts/generate-tool-family-registry.ts`
+ * aggregates the records into `tool-families.generated.ts`. This module reads
+ * only that aggregate, so the browser bundle and the MCP process share one
+ * manifest without either importing the other's factories.
+ *
+ * Factories live in `server/tool-family-factories.ts` (Node) and
+ * `client/tool-family-factories.ts` (browser). Each map is typed against the
+ * family keys derived here, so a record without a factory, or a factory
+ * without a record, fails to compile.
+ */
+import { TOOL_FAMILIES } from './tool-families.generated.js';
+
+export type ToolTransport = 'forwarded' | 'in-process';
+
+/** Authored in one record file per family. The key is the filename without `.ts`; the generator adds it. */
+export interface ToolFamilyRecord {
+  /** `forwarded`: executed by the browser sandbox peer. `in-process`: executed in the MCP process. */
+  readonly transport: ToolTransport;
+  /** Stable position in the default `tools/list` order. Unique across all records; authored with gaps of 10. */
+  readonly order: number;
+  /** Exact names the family factory yields for the default surface, in factory order. */
+  readonly tools: readonly string[];
+}
+
+export interface ToolFamily extends ToolFamilyRecord {
+  readonly key: string;
+}
+
+type RegisteredFamily = (typeof TOOL_FAMILIES)[number];
+export type ForwardedFamilyKey = Extract<RegisteredFamily, { transport: 'forwarded' }>['key'];
+export type InProcessFamilyKey = Extract<RegisteredFamily, { transport: 'in-process' }>['key'];
+
+function assertUnique(label: string, values: readonly (string | number)[]): void {
+  const seen = new Set<string | number>();
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(`duplicate tool family ${label} '${value}'`);
+    seen.add(value);
+  }
+}
+
+function validateFamilies(families: readonly RegisteredFamily[]): readonly RegisteredFamily[] {
+  assertUnique('key', families.map((family) => family.key));
+  assertUnique('order', families.map((family) => family.order));
+  assertUnique('tool name', families.flatMap((family) => family.tools));
+  return [...families].sort((a, b) => a.order - b.order);
+}
+
+const FAMILIES_BY_ORDER = validateFamilies(TOOL_FAMILIES);
+
+/** Families of one transport, sorted by `order`. Validates once at load: duplicate key, order, or tool name throws. */
+export function toolFamilies<T extends ToolTransport>(
+  transport: T,
+): readonly Extract<RegisteredFamily, { transport: T }>[] {
+  return FAMILIES_BY_ORDER.filter(
+    (family): family is Extract<RegisteredFamily, { transport: T }> =>
+      family.transport === transport,
+  );
+}
+
+/**
+ * Fail closed when a factory yields a different name set from the records.
+ * Both sides call this with the same message so drift reads the same
+ * wherever it surfaces.
+ */
+export function assertExactToolNames(
+  label: string,
+  actual: readonly string[],
+  expected: readonly string[],
+): void {
+  const actualSorted = [...actual].sort();
+  const expectedSorted = [...expected].sort();
+  if (
+    actualSorted.length !== expectedSorted.length ||
+    actualSorted.some((name, index) => name !== expectedSorted[index])
+  ) {
+    throw new Error(
+      `${label} drifted from the default MCP contract\n` +
+        `expected: ${expected.join(', ')}\n` +
+        `actual:   ${actual.join(', ')}`,
+    );
+  }
+}

package/src/bridge/tool-family-records/conformance.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'in-process',
+  order: 60,
+  tools: ['pyric_can_i_use'],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-data.ts

@@ -0,0 +1,15 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 20,
+  tools: [
+    'firestore_get_document',
+    'firestore_list_documents',
+    'firestore_create_document',
+    'firestore_add_document',
+    'firestore_update_document',
+    'firestore_delete_document',
+    'firestore_batch_write',
+    'firestore_query_where',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-inspect.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 30,
+  tools: ['sandbox_inspect'],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-rules.ts

@@ -0,0 +1,15 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'in-process',
+  order: 50,
+  tools: [
+    'firestore_simulate_rules',
+    'firestore_rules_stdlib_list',
+    'firestore_rules_stdlib_get',
+    'firestore_lint_rules',
+    'firestore_resolve_modules',
+    'rules_stdlib_list',
+    'rules_stdlib_get',
+    'rules_resolve_modules',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-simulator.ts

@@ -0,0 +1,16 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 10,
+  tools: [
+    'firestore_simulator_create',
+    'firestore_simulator_execute',
+    'firestore_simulator_read',
+    'firestore_simulator_batch',
+    'firestore_create_with_auto_id',
+    'firestore_simulator_undo',
+    'firestore_simulator_redo',
+    'firestore_simulator_events',
+    'firestore_simulator_transaction',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/rtdb-inspection.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 40,
+  tools: ['rtdb_simulate_access', 'rtdb_crawl_structure'],
+} as const satisfies ToolFamilyRecord;

package/src/bundler/externals.ts

@@ -0,0 +1,55 @@
+/**
+ * Externalization presets and helpers for Node backend bundlers.
+ *
+ * Prevents backend bundlers (Rolldown, esbuild, tsup, Rollup, Vite, Webpack)
+ * from inlining Firebase and Firebase Admin SDKs into bundled server outputs,
+ * preserving runtime interception by `@pyric/cli/register` under `pyric sandbox`.
+ */
+
+/**
+ * RegExp patterns matching Firebase packages for bundlers that accept RegExp
+ * in their external configuration (Rolldown, Rollup, Vite, Webpack).
+ */
+export const pyricRollupExternals: readonly RegExp[] = Object.freeze([
+  /^firebase-admin(\/.*)?$/,
+  /^firebase(\/.*)?$/,
+  /^@firebase(\/.*)?$/,
+]);
+
+/**
+ * Wildcard string patterns matching Firebase packages for bundlers that require
+ * string arrays with glob wildcards (esbuild, tsup).
+ */
+export const pyricEsbuildExternals: readonly string[] = Object.freeze([
+  'firebase-admin',
+  'firebase-admin/*',
+  'firebase',
+  'firebase/*',
+  '@firebase/*',
+]);
+
+/**
+ * Universal predicate returning true if a module specifier belongs to Firebase
+ * or Firebase Admin SDK surfaces intercepted by Pyric.
+ *
+ * Compatible with bundlers that accept a function in their external setting
+ * (Rolldown, Rollup, Vite, Webpack).
+ */
+export function isPyricExternal(id: string): boolean {
+  if (typeof id !== 'string' || id.length === 0) {
+    return false;
+  }
+  return pyricRollupExternals.some((regex) => regex.test(id));
+}
+
+/**
+ * Convenience presets mapping bundler names to their supported external pattern format.
+ */
+export const pyricExternals = Object.freeze({
+  rolldown: pyricRollupExternals,
+  rollup: pyricRollupExternals,
+  vite: pyricRollupExternals,
+  webpack: pyricRollupExternals,
+  esbuild: pyricEsbuildExternals,
+  tsup: pyricEsbuildExternals,
+});

package/src/bundler/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `@pyric/cli/bundler` — externalization presets and helpers for Node backend
+ * bundlers (Rolldown, esbuild, tsup, Rollup, Vite) to preserve `@pyric/cli/register`
+ * runtime sandbox interception.
+ *
+ *   // rolldown.config.ts / rollup.config.js
+ *   import { pyricExternals } from '@pyric/cli/bundler';
+ *   export default { external: pyricExternals.rolldown };
+ *
+ *   // vite.config.ts (SSR / Node backend builds)
+ *   export default { build: { rollupOptions: { external: pyricExternals.vite } } };
+ *
+ *   // tsup.config.ts / esbuild.config.mjs
+ *   export default { external: pyricExternals.esbuild };
+ */
+export {
+  pyricRollupExternals,
+  pyricEsbuildExternals,
+  isPyricExternal,
+  pyricExternals,
+} from './externals.js';

package/src/cli/cli.test.ts

@@ -461,47 +461,3 @@ describe('runInit', () => {
     expect(io.getOut()).toContain('skipped package.json'); // unchanged merge
   });
 });
-
-describe('scanForInlinedFirebase', () => {
-  it('flags a bundled chunk that inlines real-SDK endpoint hosts', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-scan-'));
-    mkdirSync(join(dir, 'assets'));
-    writeFileSync(
-      join(dir, 'assets', 'index-abc.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    const hits = scanForInlinedFirebase(dir);
-    expect(hits).toEqual(['assets/index-abc.js']);
-  });
-
-  it('stays clean for an unbundled app importing firebase by bare specifier', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-clean-'));
-    writeFileSync(
-      join(dir, 'main.js'),
-      "import { getAuth } from 'firebase/auth'; import { getFirestore } from 'firebase/firestore';",
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-
-  it('ignores hidden frameworks and build cache directories like .next and .git', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-ignore-'));
-    mkdirSync(join(dir, '.next'));
-    writeFileSync(
-      join(dir, '.next', 'bundle.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-});

package/src/cli/inlined-sdk-scanner.ts

@@ -0,0 +1,77 @@
+/**
+ * Detect a served frontend build that inlined the real Firebase SDK.
+ *
+ * The served import map remaps only bare `firebase/*` specifiers, so a plain
+ * `vite build` that compiled the SDK into an app chunk cannot be sandboxed:
+ * its calls reach real Google endpoints while the injected banner claims
+ * otherwise. `cli/serve.ts` refuses such a dist rather than serving it.
+ *
+ * Only the SDK fingerprint hosts are matched, never the full endpoint catalog.
+ * This check throws, and a dist can legitimately carry a bare callable URL, a
+ * public asset URL, or a `databaseURL` literal without any Firebase SDK in it.
+ *
+ * Backend bundles are deliberately out of scope. `withPyric` externalizes
+ * firebase and firebase-admin, the backend-bundler docs tell users to mark them
+ * external, and the net guard reports real egress at runtime with attribution,
+ * which a grep over build output cannot do.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { SDK_FINGERPRINT_HOSTS } from '../google-endpoints.js';
+
+/** Depth limit for the walk. */
+const MAX_DEPTH = 4;
+
+/** Total script files read. */
+const MAX_FILES = 200;
+
+/** Script extensions worth reading in served frontend output. */
+const SCRIPT_FILE = /\.(js|mjs)$/;
+
+/**
+ * Scan `dir` for inlined SDK fingerprints and return the offending paths,
+ * relative to `dir`. Bounded: depth 4, 200 script files, first hit per file.
+ */
+export function scanForInlinedFirebase(dir: string): string[] {
+  const hits: string[] = [];
+  let scanned = 0;
+  const walk = (current: string, rel: string, depth: number): void => {
+    if (depth > MAX_DEPTH || scanned >= MAX_FILES) return;
+    let names: string[];
+    try {
+      names = readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      if (scanned >= MAX_FILES) return;
+      const path = join(current, name);
+      const relPath = rel ? `${rel}/${name}` : name;
+      let stat;
+      try {
+        stat = statSync(path);
+      } catch {
+        continue;
+      }
+      if (stat.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.
+        if (name === 'node_modules' || name.startsWith('.')) continue;
+        walk(path, relPath, depth + 1);
+        continue;
+      }
+      if (!SCRIPT_FILE.test(name)) continue;
+      scanned++;
+      let text: string;
+      try {
+        text = readFileSync(path, 'utf8');
+      } catch {
+        continue; // unreadable asset
+      }
+      if (SDK_FINGERPRINT_HOSTS.some((host) => text.includes(host))) hits.push(relPath);
+    }
+  };
+  walk(dir, '', 0);
+  return hits;
+}