@pyric/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/src/verify/index.ts

@@ -0,0 +1,519 @@
+import {
+  replay as replayFirestore,
+  type Divergence,
+  type EventService,
+} from 'pyric/sandbox';
+import {
+  replay as replayRtdb,
+  type RtdbReplayDivergence,
+} from 'pyric/rules/internal/rtdb';
+import {
+  SimulateFirestoreRulesHandler,
+  TestFirestoreRulesHandler,
+  type ExpressionReportLevel,
+  type TestCase,
+  type TestResult,
+} from 'pyric/rules/internal';
+import type { RtdbRulesDocument } from 'pyric/rules/internal/rtdb';
+import type { ProjectScope } from '../credentials/core/types.js';
+import {
+  isRtdbRulesDocument,
+  parseRtdbRulesJson,
+  type RtdbRulesJson,
+} from '../rtdb/rules-json.js';
+import {
+  fixtureVerifiableServices,
+  parseVerifyFixture,
+  VERIFY_FIXTURE_SCHEMA,
+  type PyricVerifyFixture,
+} from './fixture.js';
+import {
+  deriveRulesTestCases,
+  type DeriveRulesTestCasesOptions,
+  type DeriveRulesTestCasesResult,
+  type VerifyUnsupportedEvent,
+} from './cases.js';
+
+export {
+  buildVerifyFixture,
+  fixtureVerifiableServices,
+  parseVerifyFixture,
+  restoreStorageRulesFromFixture,
+  VERIFY_FIXTURE_SCHEMA,
+  type BuildVerifyFixtureInput,
+  type PyricVerifyFixture,
+  type VerifyFirestoreRulesBlock,
+  type VerifyRtdbRulesBlock,
+  type VerifyStorageRulesBlock,
+} from './fixture.js';
+export {
+  deriveRulesTestCases,
+  type DerivedRulesTestCase,
+  type DeriveRulesTestCasesOptions,
+  type DeriveRulesTestCasesResult,
+  type VerifyFixtureWarning,
+  type VerifyUnsupportedEvent,
+} from './cases.js';
+export { createVerifyTools, type VerifyToolDeps } from './tools.js';
+
+export type VerifiableService = 'firestore' | 'rtdb';
+export type VerifyEngine = 'sandbox' | 'rulesTestApi';
+
+export type VerifyRulesInput = {
+  firestore?: string | { source: string };
+  rtdb?: { rules: Record<string, unknown> } | RtdbRulesDocument;
+  storage?: string | { source: string };
+};
+
+export interface VerifyFixtureOptions {
+  rules: VerifyRulesInput;
+  services?: VerifiableService[];
+  engines?: VerifyEngine[];
+  rulesTestApi?: {
+    scope: ProjectScope;
+    expressionReportLevel?: ExpressionReportLevel;
+  };
+  caseDerivation?: Omit<DeriveRulesTestCasesOptions, 'service'>;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  services: Partial<Record<VerifiableService, VerifyServiceResult>>;
+}
+
+export interface VerifyServiceResult {
+  service: VerifiableService;
+  ok: boolean;
+  checkedEvents: number;
+  divergences: VerifyDivergence[];
+  engines?: Partial<Record<VerifyEngine, VerifyEngineResult>>;
+}
+
+export interface VerifyEngineResult {
+  engine: VerifyEngine;
+  ok: boolean;
+  checkedEvents: number;
+  divergences: VerifyDivergence[];
+  testCases?: number;
+  passed?: number;
+  failed?: number;
+  unsupported?: number;
+  derivation?: DeriveRulesTestCasesResult;
+  results?: TestResult[];
+}
+
+export type VerifyDivergence =
+  | {
+      service: EventService | string;
+      kind: 'now-denied';
+      path?: string;
+      method?: string;
+      reason?: string;
+    }
+  | {
+      service: EventService | string;
+      kind: 'now-allowed';
+      path?: string;
+      method?: string;
+      reason?: string;
+    }
+  | {
+      service: EventService | string;
+      kind: 'state-drift';
+      path?: string;
+      field?: string;
+      before: unknown;
+      after: unknown;
+    }
+  | {
+      service: EventService | string;
+      kind: 'unsupported';
+      path?: string;
+      method?: string;
+      reason: string;
+    }
+  | {
+      service: EventService | string;
+      kind: 'expected-drift';
+      drift: string;
+      path?: string;
+      field?: string;
+      before?: unknown;
+      after?: unknown;
+    }
+  | {
+      service: EventService | string;
+      kind: 'engine-drift';
+      path?: string;
+      method?: string;
+      sandbox: string;
+      rulesTestApi: string;
+      reason?: string;
+    };
+
+export class VerifyInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VerifyInputError';
+  }
+}
+
+export async function verifyFixture(
+  fixtureInput: PyricVerifyFixture | unknown,
+  opts: VerifyFixtureOptions,
+): Promise<VerifyResult> {
+  const fixture = parseVerifyFixture(fixtureInput);
+  const selected = opts.services ?? fixtureVerifiableServices(fixture);
+  const engines = normalizeEngines(opts.engines);
+  if (selected.length === 0) {
+    throw new VerifyInputError(
+      `fixture ${fixture.schema} does not contain a verifiable rules service.`,
+    );
+  }
+
+  const services: Partial<Record<VerifiableService, VerifyServiceResult>> = {};
+  for (const service of selected) {
+    if (service === 'firestore') {
+      services.firestore = await verifyFirestore(fixture, requireFirestoreRules(opts.rules), engines, opts);
+    } else if (service === 'rtdb') {
+      services.rtdb = await verifyRtdb(fixture, requireRtdbRules(opts.rules), engines);
+    } else {
+      const exhaustive: never = service;
+      throw new VerifyInputError(`unsupported verify service: ${exhaustive}`);
+    }
+  }
+  return {
+    ok: Object.values(services).every((result) => result?.ok !== false),
+    services,
+  };
+}
+
+async function verifyFirestore(
+  fixture: PyricVerifyFixture,
+  rules: string,
+  engines: VerifyEngine[],
+  opts: VerifyFixtureOptions,
+): Promise<VerifyServiceResult> {
+  const firestore = fixture.services.firestore;
+  if (!firestore) {
+    throw new VerifyInputError('fixture does not contain services.firestore.');
+  }
+
+  const engineResults: Partial<Record<VerifyEngine, VerifyEngineResult>> = {};
+  if (engines.includes('sandbox')) {
+    engineResults.sandbox = verifyFirestoreSandbox(fixture, rules);
+  }
+  if (engines.includes('rulesTestApi')) {
+    engineResults.rulesTestApi = await verifyFirestoreRulesTestApi(fixture, rules, opts);
+  }
+  if (engineResults.sandbox && engineResults.rulesTestApi) {
+    addEngineDrift(rules, engineResults.rulesTestApi);
+  }
+
+  const divergences = collectEngineDivergences(engineResults);
+  return {
+    service: 'firestore',
+    ok: divergences.every(isInformational),
+    checkedEvents: serviceCheckedEvents(engineResults),
+    divergences,
+    engines: engineResults,
+  };
+}
+
+function verifyFirestoreSandbox(
+  fixture: PyricVerifyFixture,
+  rules: string,
+): VerifyEngineResult {
+  const firestore = fixture.services.firestore;
+  if (!firestore) {
+    throw new VerifyInputError('fixture does not contain services.firestore.');
+  }
+
+  const { divergences } = replayFirestore(
+    fixture.events,
+    rules,
+    {},
+    firestore.state.documents,
+  );
+  const mapped = divergences.map(mapFirestoreDivergence);
+  return {
+    engine: 'sandbox',
+    ok: mapped.every(isInformational),
+    checkedEvents: fixture.events.filter(isProtectedFirestoreWrite).length,
+    divergences: mapped,
+  };
+}
+
+function isProtectedFirestoreWrite(event: PyricVerifyFixture['events'][number]): boolean {
+  return event.kind === 'write' && event.detail?.admin !== true;
+}
+
+async function verifyFirestoreRulesTestApi(
+  fixture: PyricVerifyFixture,
+  rules: string,
+  opts: VerifyFixtureOptions,
+): Promise<VerifyEngineResult> {
+  const scope = opts.rulesTestApi?.scope;
+  if (!scope) {
+    throw new VerifyInputError('rulesTestApi verification requires rulesTestApi.scope.');
+  }
+
+  const derivation = deriveRulesTestCases(fixture, {
+    service: 'firestore',
+    ...opts.caseDerivation,
+  });
+  const divergences = derivation.unsupportedEvents.map(mapUnsupportedEvent);
+  if (derivation.testCases.length === 0) {
+    return {
+      engine: 'rulesTestApi',
+      ok: divergences.length === 0,
+      checkedEvents: 0,
+      testCases: 0,
+      passed: 0,
+      failed: 0,
+      unsupported: divergences.length,
+      derivation,
+      divergences,
+    };
+  }
+
+  const handler = new TestFirestoreRulesHandler();
+  const result = await handler.execute(scope, rules, derivation.testCases, {
+    expressionReportLevel: opts.rulesTestApi?.expressionReportLevel,
+  });
+  if (!result.success) {
+    divergences.push({
+      service: 'firestore',
+      kind: 'unsupported',
+      reason: `Rules Test API failed: ${result.error.message}`,
+    });
+    return {
+      engine: 'rulesTestApi',
+      ok: false,
+      checkedEvents: 0,
+      testCases: derivation.testCases.length,
+      passed: 0,
+      failed: derivation.testCases.length,
+      unsupported: divergences.length,
+      derivation,
+      divergences,
+    };
+  }
+
+  for (const [index, testResult] of result.data.results.entries()) {
+    if (testResult.state !== 'FAILED') continue;
+    const tc = derivation.testCases[index];
+    divergences.push(mapFailedTestResult(testResult, tc));
+  }
+
+  return {
+    engine: 'rulesTestApi',
+    ok: divergences.every(isInformational),
+    checkedEvents: result.data.results.length,
+    testCases: derivation.testCases.length,
+    passed: result.data.passed,
+    failed: result.data.failed,
+    unsupported: result.data.unsupported + derivation.unsupportedEvents.length,
+    derivation,
+    results: result.data.results,
+    divergences,
+  };
+}
+
+async function verifyRtdb(
+  fixture: PyricVerifyFixture,
+  rulesJson: { rules: Record<string, unknown> },
+  engines: VerifyEngine[],
+): Promise<VerifyServiceResult> {
+  const rtdb = fixture.services.rtdb;
+  if (!rtdb) {
+    throw new VerifyInputError('fixture does not contain services.rtdb.');
+  }
+  if (engines.includes('rulesTestApi')) {
+    throw new VerifyInputError('rulesTestApi verification is Firestore-only; select --service firestore or use the sandbox engine for RTDB.');
+  }
+
+  const replayed = await replayRtdb(fixture.events, {
+    rules: rulesJson,
+    capturedState: rtdb.state.tree,
+    ...(rtdb.databaseUrl ? { databaseUrl: rtdb.databaseUrl } : {}),
+  });
+  const divergences = replayed.divergences.map(mapRtdbReplayDivergence);
+  const sandbox: VerifyEngineResult = {
+    engine: 'sandbox',
+    ok: divergences.every(isInformational),
+    checkedEvents: replayed.checkedEvents,
+    divergences,
+  };
+
+  return {
+    service: 'rtdb',
+    ok: divergences.every(isInformational),
+    checkedEvents: replayed.checkedEvents,
+    divergences,
+    engines: { sandbox },
+  };
+}
+
+function normalizeEngines(input: VerifyEngine[] | undefined): VerifyEngine[] {
+  const engines = input ?? ['sandbox'];
+  const out: VerifyEngine[] = [];
+  for (const engine of engines) {
+    if (engine !== 'sandbox' && engine !== 'rulesTestApi') {
+      throw new VerifyInputError(`unsupported verify engine: ${String(engine)}`);
+    }
+    if (!out.includes(engine)) out.push(engine);
+  }
+  return out.length > 0 ? out : ['sandbox'];
+}
+
+function collectEngineDivergences(
+  engines: Partial<Record<VerifyEngine, VerifyEngineResult>>,
+): VerifyDivergence[] {
+  return Object.values(engines).flatMap((result) => result?.divergences ?? []);
+}
+
+function serviceCheckedEvents(
+  engines: Partial<Record<VerifyEngine, VerifyEngineResult>>,
+): number {
+  return engines.sandbox?.checkedEvents ?? engines.rulesTestApi?.checkedEvents ?? 0;
+}
+
+function mapUnsupportedEvent(event: VerifyUnsupportedEvent): VerifyDivergence {
+  return {
+    service: event.service,
+    kind: 'unsupported',
+    path: event.path,
+    method: event.method,
+    reason: event.reason,
+  };
+}
+
+function mapFailedTestResult(result: TestResult, tc: TestCase | undefined): VerifyDivergence {
+  const path = tc?.path;
+  const method = tc?.method;
+  const reason = result.notes.join('\n') || `expected ${result.expectation}, got ${result.decision}`;
+  if (result.expectation === 'ALLOW') {
+    return {
+      service: 'firestore',
+      kind: 'now-denied',
+      path,
+      method,
+      reason,
+    };
+  }
+  return {
+    service: 'firestore',
+    kind: 'now-allowed',
+    path,
+    method,
+    reason,
+  };
+}
+
+function addEngineDrift(
+  rules: string,
+  rulesTestApi: VerifyEngineResult,
+): void {
+  const hostedCases = rulesTestApi.derivation?.testCases ?? [];
+  if (hostedCases.length === 0) return;
+
+  const simulator = new SimulateFirestoreRulesHandler();
+  const local = simulator.simulate(rules, hostedCases);
+  if (!local.success) return;
+
+  for (const [index, localResult] of local.data.results.entries()) {
+    const hostedResult = rulesTestApi.results?.[index];
+    if (!hostedResult) continue;
+    if (localResult.decision === hostedResult.decision) continue;
+    const tc = hostedCases[index];
+    rulesTestApi.divergences.push({
+      service: 'firestore',
+      kind: 'engine-drift',
+      path: tc?.path,
+      method: tc?.method,
+      sandbox: localResult.decision,
+      rulesTestApi: hostedResult.decision,
+      reason: `sandbox decided ${localResult.decision}; Rules Test API decided ${hostedResult.decision}.`,
+    });
+  }
+  rulesTestApi.ok = rulesTestApi.divergences.every(isInformational);
+}
+
+function requireFirestoreRules(input: VerifyRulesInput): string {
+  const rules = input.firestore;
+  if (typeof rules === 'string') return rules;
+  if (rules && typeof rules.source === 'string') return rules.source;
+  throw new VerifyInputError('missing candidate Firestore rules. Pass rules.firestore.');
+}
+
+function requireRtdbRules(input: VerifyRulesInput): RtdbRulesJson {
+  const rules = input.rtdb;
+  if (isRtdbRulesDocument(rules)) {
+    return parseRtdbRulesJson(
+      rules.toJSON(),
+      () => new VerifyInputError('candidate RTDB rules document must compile to { rules: object }.'),
+    );
+  }
+  if (rules !== undefined) {
+    return parseRtdbRulesJson(
+      rules,
+      () => new VerifyInputError('candidate RTDB rules must be { rules: object }.'),
+    );
+  }
+  throw new VerifyInputError('missing candidate RTDB rules. Pass rules.rtdb.');
+}
+
+function mapFirestoreDivergence(divergence: Divergence): VerifyDivergence {
+  switch (divergence.kind) {
+    case 'real-divergence':
+      return {
+        service: 'firestore',
+        kind: 'state-drift',
+        path: divergence.path,
+        field: divergence.field,
+        before: divergence.before,
+        after: divergence.after,
+      };
+    case 'autoid-alias':
+      return {
+        service: 'firestore',
+        kind: 'expected-drift',
+        drift: 'autoid-alias',
+        path: divergence.originalPath,
+        before: divergence.originalPath,
+        after: divergence.replayedPath,
+      };
+    case 'sentinel-drift':
+      return {
+        service: 'firestore',
+        kind: 'expected-drift',
+        drift: 'sentinel-drift',
+        path: divergence.path,
+        field: divergence.field,
+        before: divergence.before,
+        after: divergence.after,
+      };
+    case 'time-drift':
+      return {
+        service: 'firestore',
+        kind: 'expected-drift',
+        drift: 'time-drift',
+        path: divergence.path,
+        field: divergence.field,
+        before: divergence.before,
+        after: divergence.after,
+      };
+  }
+}
+
+function mapRtdbReplayDivergence(divergence: RtdbReplayDivergence): VerifyDivergence {
+  return {
+    service: 'rtdb',
+    ...divergence,
+  };
+}
+
+function isInformational(divergence: VerifyDivergence): boolean {
+  return divergence.kind === 'expected-drift';
+}

package/src/verify/tools.ts

@@ -0,0 +1,108 @@
+import type { ToolHandler } from '@inbrowser/agent';
+import type { ProjectScope } from '../credentials/core/types.js';
+import {
+  deriveRulesTestCases,
+  verifyFixture,
+  type VerifyEngine,
+  type VerifyRulesInput,
+  type VerifiableService,
+} from './index.js';
+
+export interface VerifyToolDeps {
+  scope?: ProjectScope;
+}
+
+export function createVerifyTools(deps: VerifyToolDeps = {}): ToolHandler[] {
+  return [
+    {
+      name: 'pyric_verify_fixture',
+      description:
+        'Verify a pyric captured fixture against candidate rules. Uses local sandbox replay by default; rulesTestApi is Firestore-only and requires configured project credentials.',
+      parameters: {
+        type: 'object',
+        properties: {
+          fixture: { type: 'object' },
+          rules: { type: 'object' },
+          services: { type: 'array', items: { type: 'string', enum: ['firestore', 'rtdb'] } },
+          engines: { type: 'array', items: { type: 'string', enum: ['sandbox', 'rulesTestApi'] } },
+          expressionReportLevel: { type: 'string', enum: ['NONE', 'VISITED', 'FULL'] },
+          caseDerivation: { type: 'object' },
+        },
+        required: ['fixture', 'rules'],
+      },
+      async execute(args) {
+        const input = args as {
+          fixture: unknown;
+          rules: VerifyRulesInput;
+          services?: VerifiableService[];
+          engines?: VerifyEngine[];
+          expressionReportLevel?: 'NONE' | 'VISITED' | 'FULL';
+          caseDerivation?: { includeAllowed?: boolean; includeDenied?: boolean; mockReads?: 'strict' | 'omit' };
+        };
+        try {
+          if (input.engines?.includes('rulesTestApi') && !deps.scope) {
+            throw new Error('pyric_verify_fixture: rulesTestApi engine requires a ProjectScope.');
+          }
+          const result = await verifyFixture(input.fixture, {
+            rules: input.rules,
+            ...(input.services ? { services: input.services } : {}),
+            ...(input.engines ? { engines: input.engines } : {}),
+            ...(input.caseDerivation ? { caseDerivation: input.caseDerivation } : {}),
+            ...(input.engines?.includes('rulesTestApi') && deps.scope
+              ? { rulesTestApi: { scope: deps.scope, expressionReportLevel: input.expressionReportLevel } }
+              : {}),
+          });
+          return {
+            ok: result.ok,
+            summary: result.ok ? 'Fixture verified' : 'Fixture verification found divergences',
+            data: result,
+          };
+        } catch (e) {
+          return { ok: false, summary: e instanceof Error ? e.message : String(e) };
+        }
+      },
+    },
+    {
+      name: 'pyric_derive_rules_test_cases',
+      description:
+        'Derive Firestore Rules Test API test cases from a pyric captured fixture. This is inspection-only and does not call Firebase.',
+      parameters: {
+        type: 'object',
+        properties: {
+          fixture: { type: 'object' },
+          service: { type: 'string', enum: ['firestore'] },
+          includeAllowed: { type: 'boolean' },
+          includeDenied: { type: 'boolean' },
+          mockReads: { type: 'string', enum: ['strict', 'omit'] },
+        },
+        required: ['fixture'],
+      },
+      async execute(args) {
+        const input = args as {
+          fixture: unknown;
+          service?: 'firestore';
+          includeAllowed?: boolean;
+          includeDenied?: boolean;
+          mockReads?: 'strict' | 'omit';
+        };
+        try {
+          const result = deriveRulesTestCases(input.fixture, {
+            service: input.service ?? 'firestore',
+            includeAllowed: input.includeAllowed,
+            includeDenied: input.includeDenied,
+            mockReads: input.mockReads,
+          });
+          return {
+            ok: result.ok,
+            summary: result.ok
+              ? `Derived ${result.testCases.length} Firestore test case(s)`
+              : `Derived ${result.testCases.length} case(s), ${result.unsupportedEvents.length} unsupported event(s)`,
+            data: result,
+          };
+        } catch (e) {
+          return { ok: false, summary: e instanceof Error ? e.message : String(e) };
+        }
+      },
+    },
+  ];
+}

package/src/version/compat-target.ts

@@ -0,0 +1,17 @@
+/**
+ * Single source of truth for the Firebase version pyric is conformance-
+ * tested against — the number `pyric --version` prints alongside
+ * @pyric/cli' own version, and the number `scripts/publish-alpha.sh`
+ * reads to derive the `fb<major>.<minor>` dist-tag it moves on a green
+ * `compat:check` (see
+ * packages/site-docs/src/content/trust/versioning-and-compatibility.md).
+ *
+ * This is a pin, not @pyric/cli' own version: bumping it starts a
+ * re-snapshot of the upstream surface, and no release claims the new
+ * `fb` line until `compat:check` passes against it.
+ *
+ * TODO: once the upstream-surface snapshot lands, that snapshot becomes
+ * the source of truth for this value and this constant should read
+ * from it instead of being hand-set.
+ */
+export const FIREBASE_TESTED_AGAINST = '12.13.0';

package/src/vite.ts

@@ -0,0 +1,17 @@
+/**
+ * `@pyric/cli/vite` — the dev-only Vite plugin that swaps `firebase/*` to the
+ * in-process pyric sandbox during `vite dev` (the serve analog for source-driven
+ * apps). See `./serve/vite-plugin.ts` and the design rationale.
+ *
+ *   import { pyric } from '@pyric/cli/vite';
+ *   export default defineConfig({ plugins: [pyric()] });
+ */
+export { pyric } from './serve/vite-plugin.js';
+export type { PyricOptions } from './serve/vite-plugin.js';
+
+// The benign node-builtin shims serve's bundler and this plugin apply when
+// bundling pyric's browser graph (`fs`/`path`/`url` reached via the rules
+// module resolver — see `serve/bundler.ts`). Exported so a browser app that
+// bundles @pyric/cli' browser-side bridge client (Pyric Studio registers as
+// the bridge peer) applies the SAME shims instead of re-deriving them.
+export { NODE_BUILTIN_RE, NODE_BUILTIN_SHIMS } from './serve/bundler.js';