@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/bridge/server/headless.ts

@@ -0,0 +1,160 @@
+/**
+ * Headless MCP server: runs the pyric sandbox IN this process (no browser, no
+ * serve) and exposes the SAME tool surface the bridge advertises, over stdio.
+ *
+ * This is the zero-setup half of the hybrid MCP server
+ * (design rationale): when no `pyric dev --bridge` is running to
+ * attach to, the MCP server hosts its own sandbox. The tool surface is identical
+ * to the served bridge by construction (`buildSandboxDispatcher` is the shared
+ * source pinned by `tool-parity.test.ts`), including the per-identity `as` arg.
+ *
+ * Persistence (Phase 1b) uses the v3 bundle codec the worker already uses for
+ * transfer/branches (`serializeToBuckets` + `bundleRecords`). It writes its OWN
+ * `.pyric/state/headless.json`, NOT serve's `state.json` (which currently uses a
+ * different on-disk envelope, and carries a controller-blob version that has
+ * drifted from pyric's snapshot SCHEMA_VERSION). Unifying the two formats so a
+ * headless session and a `pyric dev` session can share one file is a tracked
+ * design item, not done here.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import {
+  initializeSandbox,
+  serializeToBuckets,
+  bundleRecords,
+  parseBundle,
+  deserializeFromBuckets,
+  type LocalSandbox,
+} from 'pyric/sandbox';
+import { getFirestore } from 'pyric/firestore';
+import { setRules } from 'pyric/sandbox/firestore';
+import { buildMcpServer } from './mcp.js';
+import { getDefaultMcpToolSurface } from './mcp-contract.js';
+import { createLocalBridge, type LocalBridgeOptions } from './local-bridge.js';
+
+/** Where the headless sandbox snapshot is persisted (relative to the project
+ *  dir). Deliberately separate from serve's `state.json` (different format). */
+export const HEADLESS_STATE_RELATIVE = join('.pyric', 'state', 'headless.json');
+
+/**
+ * Build the headless MCP server around an in-process sandbox. Pure: no I/O and
+ * no transport, so callers (and tests) can drive it however they like. Mirrors
+ * the served bridge's construction (forwarded data-plane + in-process rules
+ * tools), with `dispatch` bound to the local sandbox instead of a ws peer.
+ */
+export function buildHeadlessMcpServer(sandbox: LocalSandbox, opts?: LocalBridgeOptions) {
+  const bridge = createLocalBridge(sandbox, opts);
+  return buildMcpServer(bridge, getDefaultMcpToolSurface());
+}
+
+/**
+ * Load `<cwd>/firestore.rules` into the sandbox when present. Returns the path
+ * it loaded, or null if there was no rules file. Without rules, rules-enforcing
+ * (`as:{uid}`) ops fall back to the sandbox's default; admin ops are unaffected.
+ */
+export function loadProjectRules(sandbox: LocalSandbox, cwd: string): string | null {
+  const rulesPath = join(cwd, 'firestore.rules');
+  if (!existsSync(rulesPath)) return null;
+  setRules(sandbox, readFileSync(rulesPath, 'utf8'));
+  return rulesPath;
+}
+
+/**
+ * Persist the sandbox to `<cwd>/.pyric/state/headless.json` using the v3 bundle
+ * codec (the same `serializeToBuckets` + `bundleRecords` the worker uses). Atomic
+ * tmp+rename so a crash mid-write never truncates the live file.
+ */
+export function saveSandboxSnapshot(sandbox: LocalSandbox, cwd: string): void {
+  const snap = sandbox.snapshot();
+  const bundle = bundleRecords(serializeToBuckets(snap.firestore, snap.services, 0));
+  const path = join(cwd, HEADLESS_STATE_RELATIVE);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, bundle, 'utf8');
+  renameSync(tmp, path);
+}
+
+/**
+ * Restore the sandbox from the headless snapshot file if present (a clobber via
+ * `loadSnapshot`). Returns the restored doc count, or null when there is no file.
+ */
+export function loadSandboxSnapshot(sandbox: LocalSandbox, cwd: string): number | null {
+  const path = join(cwd, HEADLESS_STATE_RELATIVE);
+  if (!existsSync(path)) return null;
+  const snap = deserializeFromBuckets(parseBundle(readFileSync(path, 'utf8')));
+  sandbox.loadSnapshot(snap);
+  return Object.keys(snap.firestore).length;
+}
+
+/**
+ * Run the headless MCP server over stdio. Loads `.pyric/state/headless.json` on
+ * start, debounces a save after each dispatch, and flushes on shutdown. Resolves
+ * with an exit code when the stdio transport closes (the editor disconnects).
+ */
+export async function runHeadlessMcp(cwd: string = process.cwd()): Promise<number> {
+  const log = (m: string): void => {
+    process.stderr.write(`[pyric mcp headless] ${m}\n`);
+  };
+
+  const sandbox = initializeSandbox();
+  const rulesPath = loadProjectRules(sandbox, cwd);
+  log(rulesPath ? `rules loaded from ${rulesPath}` : `no firestore.rules found in ${cwd}`);
+
+  const restored = loadSandboxSnapshot(sandbox, cwd);
+  if (restored !== null) log(`restored ${restored} docs from ${join(cwd, HEADLESS_STATE_RELATIVE)}`);
+
+  // Debounced persistence: a burst of writes collapses to one flush; the final
+  // flush runs on shutdown so a clean disconnect never loses the tail.
+  let saveTimer: ReturnType<typeof setTimeout> | null = null;
+  const flush = (): void => {
+    if (saveTimer) {
+      clearTimeout(saveTimer);
+      saveTimer = null;
+    }
+    try {
+      saveSandboxSnapshot(sandbox, cwd);
+    } catch (e) {
+      log(`persist failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  };
+  const scheduleSave = (): void => {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(flush, 750);
+  };
+
+  const server = buildHeadlessMcpServer(sandbox, { onAfterDispatch: scheduleSave });
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const transport = new StdioServerTransport();
+
+  return await new Promise<number>((resolve) => {
+    let stopping = false;
+    const onStdinEnd = (): void => stop(0);
+    const stop = (code: number): void => {
+      if (stopping) return;
+      stopping = true;
+      process.stdin.off('end', onStdinEnd);
+      flush();
+      void server.close().then(
+        () => resolve(code),
+        (e) => {
+          log(`shutdown failed: ${e instanceof Error ? e.message : String(e)}`);
+          resolve(code === 0 ? 1 : code);
+        },
+      );
+    };
+    transport.onclose = () => stop(0);
+    // StdioServerTransport 1.29 no longer reports stdin EOF through onclose.
+    // Editors close the pipe to end an MCP session, so own that lifecycle
+    // signal explicitly and then close the server/transport above.
+    process.stdin.once('end', onStdinEnd);
+    process.once('SIGINT', () => stop(0));
+    process.once('SIGTERM', () => stop(0));
+    void server.connect(transport).then(
+      () => log(`headless sandbox MCP server ready (persisting to ${HEADLESS_STATE_RELATIVE})`),
+      (e) => {
+        log(`failed to start: ${e instanceof Error ? e.message : String(e)}`);
+        resolve(1);
+      },
+    );
+  });
+}

package/src/bridge/server/json-schema-to-zod.ts

@@ -0,0 +1,108 @@
+/**
+ * Tiny JSON-Schema → Zod shape converter. Handles only the shapes
+ * pyric's tool factories actually produce (string, number, boolean,
+ * object, array, enum, plus untyped catch-all). Anything outside this
+ * grammar becomes `z.any()` — better to under-validate than refuse to
+ * register a tool.
+ *
+ * The MCP SDK's `server.tool()` / `server.registerTool()` insist on
+ * Zod schemas for input validation. Pyric's tool definitions are
+ * plain JSON Schema (matching the inline shape in
+ * `packages/pyric/src/rules/tools.ts`), so the bridge converts
+ * just-in-time when registering each tool with the MCP server.
+ */
+
+import { z, type ZodRawShape, type ZodTypeAny } from 'zod';
+
+type JsonSchemaObject = {
+  type?: string | string[];
+  description?: string;
+  properties?: Record<string, JsonSchemaObject>;
+  items?: JsonSchemaObject;
+  required?: string[];
+  enum?: unknown[];
+  additionalProperties?: boolean | JsonSchemaObject;
+  [k: string]: unknown;
+};
+
+/**
+ * Convert a JSON-Schema-of-an-object into a Zod raw shape suitable
+ * for passing to `server.tool(name, description, shape, handler)`.
+ *
+ * Behaviour:
+ *  - Empty / no `properties` returns `{}` (valid for parameterless tools).
+ *  - Each property becomes a Zod schema chosen from its `type`.
+ *  - Properties NOT in `required` are made `.optional()`.
+ *  - Description metadata is attached via `.describe()` for MCP surfacing.
+ */
+export function jsonSchemaToZodShape(schema: JsonSchemaObject): ZodRawShape {
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const shape: ZodRawShape = {};
+  for (const [key, value] of Object.entries(properties)) {
+    let zodSchema = jsonSchemaToZod(value);
+    if (value.description) {
+      zodSchema = zodSchema.describe(value.description);
+    }
+    if (!required.has(key)) {
+      zodSchema = zodSchema.optional();
+    }
+    shape[key] = zodSchema;
+  }
+  return shape;
+}
+
+function jsonSchemaToZod(schema: JsonSchemaObject): ZodTypeAny {
+  // Enum (irrespective of type)
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const values = schema.enum.filter((v): v is string => typeof v === 'string');
+    if (values.length === schema.enum.length && values.length > 0) {
+      return z.enum(values as [string, ...string[]]);
+    }
+    return z.union(schema.enum.map((v) => z.literal(v as never)) as never);
+  }
+
+  // oneOf / anyOf — a union of sub-schemas (e.g. `as: 'admin' | { uid, … }`).
+  // Without this, a schema with no top-level `type` falls through to z.any(),
+  // silently dropping the contract the agent is supposed to see.
+  const variants = (schema.oneOf ?? schema.anyOf) as JsonSchemaObject[] | undefined;
+  if (Array.isArray(variants) && variants.length > 0) {
+    const members = variants.map((v) => jsonSchemaToZod(v));
+    return members.length === 1
+      ? members[0]
+      : z.union(members as [ZodTypeAny, ZodTypeAny, ...ZodTypeAny[]]);
+  }
+
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case 'string':
+      return z.string();
+    case 'number':
+    case 'integer':
+      return z.number();
+    case 'boolean':
+      return z.boolean();
+    case 'null':
+      return z.null();
+    case 'array': {
+      const items = schema.items
+        ? jsonSchemaToZod(schema.items)
+        : z.any();
+      return z.array(items);
+    }
+    case 'object': {
+      if (!schema.properties || Object.keys(schema.properties).length === 0) {
+        // Open object — pyric tools commonly use `additionalProperties: true`
+        // here to mean "free-form payload" (e.g. `data` for a Firestore doc).
+        return z.record(z.any());
+      }
+      const inner = jsonSchemaToZodShape(schema);
+      return z.object(inner);
+    }
+    default:
+      // Untyped (e.g. the `auth` field that pyric tools accept as
+      // `null | { uid, token? }` without a `type` declaration) —
+      // accept anything.
+      return z.any();
+  }
+}

package/src/bridge/server/local-bridge.ts

@@ -0,0 +1,66 @@
+/**
+ * In-process ("local") Bridge for the headless MCP server.
+ *
+ * The serve / standalone bridges forward data-plane tool calls over a WebSocket
+ * to the in-page sandbox. The headless server has no page: the sandbox runs IN
+ * this process, so the bridge's `dispatch` executes tools directly through
+ * `buildSandboxDispatcher`. Everything else the `Bridge` contract needs is
+ * trivial for a peerless bridge (always "connected", with the tool set from
+ * the dispatcher's `SANDBOX_TOOL_NAMES`).
+ *
+ * Because `buildSandboxDispatcher` is the SAME source the served bridge
+ * advertises (pinned by `tool-parity.test.ts`), the headless tool surface is
+ * identical to the served one, including the per-identity `as` arg.
+ *
+ * See design rationale (headless mode).
+ */
+import type { LocalSandbox } from 'pyric/sandbox';
+import { buildSandboxDispatcher, SANDBOX_TOOL_NAMES } from '../client/dispatch.js';
+import { createBridge, type Bridge } from './bridge.js';
+import { pyricVersion } from '../../serve/standalone-assets.js';
+
+export interface LocalBridgeOptions {
+  /** Reported as the MCP server version. */
+  version?: string;
+  /** Project label surfaced in tool-result metadata. */
+  project?: string;
+  /** Called after each dispatch (success or failure). The headless runner uses
+   *  this to schedule a debounced persistence flush so writes survive a restart. */
+  onAfterDispatch?: () => void;
+}
+
+/**
+ * A {@link Bridge} backed by an in-process {@link Sandbox}. `dispatch` runs tools
+ * locally; the peer-management members are no-ops (there is no remote peer).
+ */
+export function createLocalBridge(sandbox: LocalSandbox, opts: LocalBridgeOptions = {}): Bridge {
+  const dispatcher = buildSandboxDispatcher(sandbox);
+  // Reuse the real bridge for the boilerplate the contract needs (startedAt,
+  // instanceId, health, recordToolEvent, the peer machinery), then override the
+  // three members that differ when the sandbox is in-process rather than a ws
+  // peer. The peer machinery stays idle because `dispatch` never touches it.
+  const base = createBridge({
+    project: opts.project ?? 'sandbox',
+    version: opts.version ?? pyricVersion(),
+  });
+  return {
+    ...base,
+    // The sandbox is in-process: always "connected", and the tool set is the
+    // dispatcher's, not a (nonexistent) peer's hello.
+    isSandboxConnected: () => true,
+    toolNames: () => [...SANDBOX_TOOL_NAMES],
+    // Execute tools locally instead of forwarding to a ws peer. The bridge
+    // contract RETURNS a result (ok:false on failure) rather than rejecting, and
+    // `buildSandboxDispatcher` throws on a tool error (e.g. a rules denial), so
+    // translate that here.
+    async dispatch(name, args) {
+      try {
+        return await dispatcher(name, args);
+      } catch (e) {
+        return { ok: false, summary: e instanceof Error ? e.message : String(e) };
+      } finally {
+        opts.onAfterDispatch?.();
+      }
+    },
+  };
+}

package/src/bridge/server/logger.ts

@@ -0,0 +1,50 @@
+/**
+ * Tiny logger for bridge lifecycle events. The bridge core stays
+ * silent; consumers (standalone CLI, Vite plugin) wire a logger
+ * here when they want visibility.
+ *
+ * Premortem #U1 + #I7 + #U2 + #U3 all stemmed from "we never
+ * print what's happening." This module is the single observability
+ * surface so adding a log line at the bridge happens once, here.
+ *
+ * Levels: `info` for lifecycle (start, peer connect/disconnect),
+ * `verbose` for per-call (only emitted when verbose=true).
+ */
+
+export interface BridgeLogger {
+  info(line: string): void;
+  verbose(line: string): void;
+  error(line: string): void;
+}
+
+/**
+ * Default logger that writes to stderr with a `[pyric]` prefix.
+ * Verbose lines are gated behind `PYRIC_VERBOSE=1` env var unless
+ * the option overrides it.
+ */
+export function createConsoleLogger(options: { verbose?: boolean } = {}): BridgeLogger {
+  const verboseEnabled =
+    options.verbose ?? Boolean(process.env.PYRIC_VERBOSE);
+  return {
+    info(line) {
+      process.stderr.write(`[pyric] ${line}\n`);
+    },
+    verbose(line) {
+      if (verboseEnabled) {
+        process.stderr.write(`[pyric] ${line}\n`);
+      }
+    },
+    error(line) {
+      process.stderr.write(`[pyric] error: ${line}\n`);
+    },
+  };
+}
+
+/** Silent logger — useful in tests. */
+export function createSilentLogger(): BridgeLogger {
+  return {
+    info() {},
+    verbose() {},
+    error() {},
+  };
+}

package/src/bridge/server/mcp-contract.ts

@@ -0,0 +1,93 @@
+import type { ToolHandler } from '@inbrowser/agent';
+import {
+  getInProcessToolHandlers,
+  getSandboxToolMetadata,
+  type ToolMetadata,
+} from './tool-metadata.js';
+
+/**
+ * The exact tools a default local Pyric MCP server forwards to its sandbox.
+ * A tool addition or removal is a public contract change and must update this
+ * manifest deliberately.
+ */
+export const DEFAULT_MCP_FORWARDED_TOOL_NAMES = [
+  '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',
+  'firestore_get_document',
+  'firestore_list_documents',
+  'firestore_create_document',
+  'firestore_add_document',
+  'firestore_update_document',
+  'firestore_delete_document',
+  'firestore_batch_write',
+  'firestore_query_where',
+  'sandbox_inspect',
+  'rtdb_simulate_access',
+  'rtdb_crawl_structure',
+] as const;
+
+/** Local rules tools that run in the MCP process without a browser peer. */
+export const DEFAULT_MCP_IN_PROCESS_TOOL_NAMES = [
+  'firestore_simulate_rules',
+  'firestore_rules_stdlib_list',
+  'firestore_rules_stdlib_get',
+  'firestore_lint_rules',
+  'firestore_resolve_modules',
+  'pyric_can_i_use',
+] as const;
+
+export const DEFAULT_MCP_TOOL_NAMES = [
+  ...DEFAULT_MCP_FORWARDED_TOOL_NAMES,
+  ...DEFAULT_MCP_IN_PROCESS_TOOL_NAMES,
+] as const;
+
+export interface DefaultMcpToolSurface {
+  forwarded: ToolMetadata[];
+  inProcess: ToolHandler[];
+}
+
+function assertExactNames(
+  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(', ')}`,
+    );
+  }
+}
+
+/**
+ * Assemble the default MCP surface and fail closed if a factory changed
+ * without a corresponding public-contract decision.
+ */
+export function getDefaultMcpToolSurface(): DefaultMcpToolSurface {
+  const forwarded = getSandboxToolMetadata();
+  const inProcess = getInProcessToolHandlers();
+  assertExactNames(
+    'forwarded sandbox tools',
+    forwarded.map((tool) => tool.name),
+    DEFAULT_MCP_FORWARDED_TOOL_NAMES,
+  );
+  assertExactNames(
+    'in-process tools',
+    inProcess.map((tool) => tool.name),
+    DEFAULT_MCP_IN_PROCESS_TOOL_NAMES,
+  );
+  return { forwarded, inProcess };
+}

package/src/bridge/server/mcp.ts

@@ -0,0 +1,129 @@
+/**
+ * MCP server assembly. Constructs an `@modelcontextprotocol/sdk`
+ * `McpServer` whose tools dispatch into the supplied bridge for
+ * forwarded calls plus in-process sandbox verification handlers.
+ *
+ * Each tool's MCP handler returns the bridge's `BridgeToolResult`
+ * serialised as a single MCP text content block — a stable shape so
+ * skill prompts work without adjustment.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolHandler } from '@inbrowser/agent';
+import type { Bridge, BridgeToolResult } from './bridge.js';
+import type { ToolMetadata } from './tool-metadata.js';
+import { jsonSchemaToZodShape } from './json-schema-to-zod.js';
+
+export interface RegisterToolsOptions {
+  /** Metadata for tools whose dispatch goes to the bridge peer. */
+  forwarded: ToolMetadata[];
+  /** Live handlers for tools that execute in-process on the bridge. */
+  inProcess: ToolHandler[];
+}
+
+function toMcpResult(result: BridgeToolResult, project: string) {
+  // Wrap the bridge's tool result in MCP's content envelope. Include
+  // sandbox provenance + project label in a metadata block so the calling
+  // agent can always tell which target the tool hit.
+  const body = {
+    ...result,
+    _pyric: { mode: 'sandbox', project },
+  };
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify(body, null, 2),
+      },
+    ],
+    isError: !result.ok,
+  };
+}
+
+/**
+ * Build an MCP server seeded with the supplied tool surface. Caller
+ * connects the returned server to a transport (e.g.
+ * StreamableHTTPServerTransport).
+ */
+export function buildMcpServer(
+  bridge: Bridge,
+  options: RegisterToolsOptions,
+): McpServer {
+  const server = new McpServer({
+    name: 'pyric',
+    version: bridge.version,
+  });
+
+  // Forwarded tools: bridge.dispatch handles the wire round-trip.
+  for (const meta of options.forwarded) {
+    const shape = jsonSchemaToZodShape(meta.parameters as never);
+    // The MCP SDK's `tool()` overloads have a deep generic tree
+    // that trips `Type instantiation is excessively deep` at the call
+    // site for the variadic shape argument. The cast collapses the
+    // inference; the runtime contract is the same.
+    (server.tool as unknown as Function)(
+      meta.name,
+      meta.description,
+      shape,
+      async (args: Record<string, unknown>) => {
+        const result = await bridge.dispatch(meta.name, args ?? {});
+        return toMcpResult(result, bridge.project);
+      },
+    );
+  }
+
+  // In-process tools are sandbox verification and rules helpers that do not
+  // touch real Firebase. Execute them directly and record the result.
+  for (const handler of options.inProcess) {
+    const shape = jsonSchemaToZodShape(handler.parameters as never);
+    (server.tool as unknown as Function)(
+      handler.name,
+      handler.description,
+      shape,
+      async (args: Record<string, unknown>) => {
+        const startedAtMs = Date.now();
+        try {
+          // The bridge supplies an AbortSignal-less ToolContext; tools
+          // that genuinely need cancellation should still respect a
+          // signal supplied via the MCP transport in the future.
+          const ctx = {
+            signal: new AbortController().signal,
+          } as never;
+          const result = await handler.execute(args ?? {}, ctx);
+          const normalised = {
+            ok: result.ok,
+            summary: result.summary,
+            data: result.data,
+          };
+          bridge.recordToolEvent({
+            timestamp: new Date(startedAtMs).toISOString(),
+            mode: 'sandbox',
+            project: bridge.project,
+            tool: handler.name,
+            args: args ?? {},
+            result: normalised,
+            durationMs: Date.now() - startedAtMs,
+          });
+          return toMcpResult(normalised, bridge.project);
+        } catch (err) {
+          const result = {
+            ok: false,
+            summary: err instanceof Error ? err.message : String(err),
+          };
+          bridge.recordToolEvent({
+            timestamp: new Date(startedAtMs).toISOString(),
+            mode: 'sandbox',
+            project: bridge.project,
+            tool: handler.name,
+            args: args ?? {},
+            result,
+            durationMs: Date.now() - startedAtMs,
+          });
+          return toMcpResult(result, bridge.project);
+        }
+      },
+    );
+  }
+
+  return server;
+}