@pyric/cli 0.1.0-alpha.25 → 0.1.0-alpha.27

package/src/rtdb/inspect-deployed-rules.ts

@@ -9,25 +9,14 @@
  * URL, and it is not returned in any result or message.
  */
 import type { ToolHandler } from 'pyric/sandbox/internal';
+import { diffRtdbRules, type RtdbRuleChange } from 'pyric/rules/internal/rtdb';
 import { parseRtdbRulesText } from './rules-json.js';
 import { HOSTED_CREDENTIAL_SOURCES } from '../credentials/node/scope.js';
 
-/** The rule kinds the diff compares. */
-export const DIFFED_RULE_KINDS = ['.indexOn', '.read', '.validate', '.write'] as const;
-export type RtdbRuleKind = (typeof DIFFED_RULE_KINDS)[number];
-
-/**
- * One rule expression that differs. `deployed` is absent for `added` and
- * `local` is absent for `removed`: the change is what deploying the local
- * ruleset would do to the deployed one.
- */
-export interface RtdbRuleChange {
-  path: string;
-  kind: RtdbRuleKind;
-  change: 'added' | 'removed' | 'changed';
-  deployed?: string;
-  local?: string;
-}
+// The diff itself is pure and lives in `pyric` (public from `pyric/rules`);
+// it is re-exported here so this module's exports stay as they were.
+export { DIFFED_RULE_KINDS, diffRtdbRules } from 'pyric/rules/internal/rtdb';
+export type { DiffRtdbRulesOptions, RtdbRuleChange, RtdbRuleKind } from 'pyric/rules/internal/rtdb';
 
 export interface InspectDeployedRtdbRulesOptions {
   scope: { resolveToken(): Promise<string> };
@@ -96,67 +85,6 @@ export async function inspectDeployedRtdbRules(
   return { ok: true, deployed, diff: diffRtdbRules(deployed.rules, local.rules) };
 }
 
-/** Node-level diff of two `rules` trees, ordered by path then rule kind. */
-export function diffRtdbRules(
-  deployed: Record<string, unknown>,
-  local: Record<string, unknown>,
-): RtdbRuleChange[] {
-  const deployedRules = collectRules(deployed);
-  const localRules = collectRules(local);
-  const changes: RtdbRuleChange[] = [];
-  for (const key of new Set([...deployedRules.keys(), ...localRules.keys()])) {
-    const d = deployedRules.get(key);
-    const l = localRules.get(key);
-    if (d?.value === l?.value) continue;
-    const node = (d ?? l)!;
-    const change: RtdbRuleChange = {
-      path: node.path,
-      kind: node.kind,
-      change: d === undefined ? 'added' : l === undefined ? 'removed' : 'changed',
-    };
-    if (d !== undefined) change.deployed = d.value;
-    if (l !== undefined) change.local = l.value;
-    changes.push(change);
-  }
-  return changes.sort((a, b) => compare(a.path, b.path) || compare(a.kind, b.kind));
-}
-
-const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
-
-interface CollectedRule {
-  path: string;
-  kind: RtdbRuleKind;
-  value: string;
-}
-
-function formatRuleValue(kind: RtdbRuleKind, value: unknown): string {
-  if (kind === '.indexOn') {
-    const normalized = typeof value === 'string' ? [value] : value;
-    return JSON.stringify(normalized);
-  }
-  // A boolean and its string form are one expression: `true` and "true".
-  return typeof value === 'string' ? value : JSON.stringify(value);
-}
-
-function collectRules(root: Record<string, unknown>): Map<string, CollectedRule> {
-  const out = new Map<string, CollectedRule>();
-  const walk = (node: Record<string, unknown>, path: string): void => {
-    for (const [key, child] of Object.entries(node)) {
-      if (key.startsWith('.')) {
-        if ((DIFFED_RULE_KINDS as readonly string[]).includes(key)) {
-          const kind = key as RtdbRuleKind;
-          const value = formatRuleValue(kind, child);
-          out.set(`${path}\u0000${kind}`, { path, kind, value });
-        }
-      } else if (typeof child === 'object' && child !== null && !Array.isArray(child)) {
-        walk(child as Record<string, unknown>, `${path === '/' ? '' : path}/${key}`);
-      }
-    }
-  };
-  walk(root, '/');
-  return out;
-}
-
 export interface RtdbInspectRulesToolDeps {
   scope: { resolveToken(): Promise<string> };
   databaseURL: string;

package/src/serve/repro/denials.ts

@@ -179,5 +179,6 @@ export function formatDenials(groups: DenialGroup[], loggedFrom?: number): strin
     for (const reason of group.trace) lines.push(`  trace: ${reason}`);
     return lines.join('\n');
   });
-  return `${bounded}${blocks.join('\n\n')}\n`;
+  const tip = '\nTip: After changing rules, run `pyric verify` to replay the captured session against them and confirm your fixes.';
+  return `${bounded}${blocks.join('\n\n')}\n${tip}\n`;
 }

package/src/serve/verify-hint.ts

@@ -0,0 +1,8 @@
+export function createVerifyHint(): () => string {
+  let printedVerifyHint = false;
+  return () => {
+    if (printedVerifyHint) return '';
+    printedVerifyHint = true;
+    return ' (run `pyric verify` to replay the captured session against these rules)';
+  };
+}

package/src/serve/vite-generation-rules-watch.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 import type { ViteDevServer } from 'vite';
 import { formatDatabaseRulesRemoved, formatStorageRulesRemoved } from './rules.js';
 import type { SandboxSession } from './sandbox-session.js';
+import { createVerifyHint } from './verify-hint.js';
 
 /**
  * Adapt Vite's watcher to the session's last-good rules reload operations.
@@ -17,6 +18,8 @@ export function watchViteGenerationRules(input: {
   server: ViteDevServer;
   session: SandboxSession;
 }): () => void {
+  const getVerifyHint = createVerifyHint();
+
   const { server, session } = input;
   const databaseFiles = session.databaseRulesFiles();
   const databaseFileByResolved = new Map(databaseFiles.map((file) => [path.resolve(file), file]));
@@ -53,7 +56,7 @@ export function watchViteGenerationRules(input: {
           server.watcher.add([...session.firestoreRulesFiles()]);
           const isReloaded = result.kind === 'reloaded';
           if (isReloaded) {
-            server.config.logger.info(`  ↻ [pyric] rules reloaded (${result.rulesHash})`);
+            server.config.logger.info(`  ↻ [pyric] rules reloaded (${result.rulesHash})${getVerifyHint()}`);
             if (result.fixtureCheck && result.fixtureCheck.ran > 0) {
               const logFn = result.fixtureCheck.ok
                 ? (m: string) => server.config.logger.info(m)
@@ -74,7 +77,7 @@ export function watchViteGenerationRules(input: {
         void session.reloadDatabaseRules(databaseFile).then((results) => {
           for (const { instance, result } of results) {
             if (result.kind === 'reloaded') {
-              server.config.logger.info(`  ↻ [pyric] rtdb rules reloaded for ${instance} (${result.rulesHash})`);
+              server.config.logger.info(`  ↻ [pyric] rtdb rules reloaded for ${instance} (${result.rulesHash})${getVerifyHint()}`);
               if (result.fixtureCheck && result.fixtureCheck.ran > 0) {
                 const logFn = result.fixtureCheck.ok
                   ? (m: string) => server.config.logger.info(m)
@@ -94,7 +97,7 @@ export function watchViteGenerationRules(input: {
       if (isStorageMatch) {
         void session.reloadStorageRules().then((result) => {
           if (result.kind === 'reloaded') {
-            server.config.logger.info(`  ↻ [pyric] storage rules reloaded (${result.rulesHash})`);
+            server.config.logger.info(`  ↻ [pyric] storage rules reloaded (${result.rulesHash})${getVerifyHint()}`);
           } else if (result.kind === 'rejected') {
             server.config.logger.warn(
               `  ⚠ [pyric] storage rules NOT reloaded (last-good stays live): ${result.error.message}`,

package/src/verify/index.ts

@@ -39,6 +39,8 @@ import {
   VERIFY_FIXTURE_SCHEMA,
   type PyricVerifyFixture,
 } from './fixture.js';
+import { runStagingInstance, StagingDeployRefusedError, withStagingInstance, type StagingRunHooks } from './staging/engine.js';
+import type { RtdbRestClient } from './staging/rest.js';
 import {
   recordedRtdbInstances,
   recordsDefaultRtdbInstance,
@@ -94,7 +96,7 @@ export {
 } from './hosted-rules-test.js';
 
 export type VerifiableService = 'firestore' | 'rtdb' | 'storage';
-export type VerifyEngine = 'sandbox' | 'rulesTestApi';
+export type VerifyEngine = 'sandbox' | 'rulesTestApi' | 'staging';
 
 type RtdbCandidateRules = { rules: Record<string, unknown> } | RtdbRulesDocument;
 
@@ -120,6 +122,12 @@ export interface VerifyFixtureOptions {
     expressionReportLevel?: ExpressionReportLevel;
   };
   caseDerivation?: Omit<DeriveRulesTestCasesOptions, 'service'>;
+  /**
+   * The staging engine's instance: a client for a dedicated RTDB instance
+   * enrolled with `pyric verify staging init`, and the project it is
+   * enrolled for. Required when `engines` includes `staging`.
+   */
+  staging?: { client: RtdbRestClient; projectId: string } & StagingRunHooks;
 }
 
 export interface VerifyResult {
@@ -198,7 +206,10 @@ type VerifyDivergenceKind =
       path?: string;
       method?: string;
       sandbox: string;
-      rulesTestApi: string;
+      /** Firestore: the hosted Rules Test API's decision. */
+      rulesTestApi?: string;
+      /** RTDB: what production did on the staging instance. */
+      staging?: string;
       reason?: string;
     };
 
@@ -224,10 +235,15 @@ export async function verifyFixture(
 
   const services: Partial<Record<VerifiableService, VerifyServiceResult>> = {};
   for (const service of selected) {
+    if (engines.includes('staging') && service !== 'rtdb') {
+      throw new VerifyInputError(
+        `the staging engine checks RTDB only; ${service} is not supported by it yet. Select --service rtdb, or the sandbox engine for ${service}.`,
+      );
+    }
     if (service === 'firestore') {
       services.firestore = await verifyFirestore(fixture, requireFirestoreRules(opts.rules), engines, opts);
     } else if (service === 'rtdb') {
-      services.rtdb = await verifyRtdb(fixture, opts.rules, engines);
+      services.rtdb = await verifyRtdb(fixture, opts.rules, engines, opts.staging);
     } else if (service === 'storage') {
       services.storage = await verifyStorage(fixture, opts.rules, engines);
     } else {
@@ -578,19 +594,24 @@ async function verifyRtdb(
   fixture: PyricVerifyFixture,
   rules: VerifyRulesInput,
   engines: VerifyEngine[],
+  staging: VerifyFixtureOptions['staging'],
 ): 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.');
+    throw new VerifyInputError('rulesTestApi verification is Firestore-only; select --service firestore or use the sandbox or staging engine for RTDB.');
+  }
+  if (engines.includes('staging') && staging === undefined) {
+    throw new VerifyInputError('the staging engine needs a staging instance (opts.staging).');
   }
 
-  const replays = [];
+  // The instances to check, each with its candidate rules.
+  const checks: Array<{ instance?: string; rules: RtdbRulesJson; capturedState: unknown }> = [];
   const checksDefault = rules.rtdb !== undefined || recordsDefaultRtdbInstance(fixture);
   if (checksDefault) {
-    replays.push(await replayRtdbInstance(fixture, requireRtdbRules(rules.rtdb, 'missing candidate RTDB rules. Pass rules.rtdb.')));
+    checks.push({ rules: requireRtdbRules(rules.rtdb, 'missing candidate RTDB rules. Pass rules.rtdb.'), capturedState: rtdb.state.tree });
   }
   const skippedInstances: string[] = [];
   for (const instance of recordedRtdbInstances(fixture)) {
@@ -600,28 +621,107 @@ async function verifyRtdb(
       continue;
     }
     const parsed = requireRtdbRules(candidate, `missing candidate RTDB rules for instance "${instance}".`, instance);
-    replays.push(await replayRtdbInstance(fixture, parsed, instance));
+    checks.push({ instance, rules: parsed, capturedState: rtdb.instances?.[instance]?.state.tree });
   }
 
-  const divergences = replays.flatMap((replayed) => replayed.divergences.map(mapRtdbReplayDivergence));
-  const checkedEvents = replays.reduce((total, replayed) => total + replayed.checkedEvents, 0);
-  const sandbox: VerifyEngineResult = {
-    engine: 'sandbox',
-    ok: divergences.every(isInformational),
-    checkedEvents,
-    divergences,
-  };
+  const engineResults: Partial<Record<VerifyEngine, VerifyEngineResult>> = {};
+  if (engines.includes('sandbox')) {
+    const replays = [];
+    for (const check of checks) replays.push(await replayRtdbInstance(fixture, check.rules, check.instance));
+    const divergences = replays.flatMap((replayed) => replayed.divergences.map(mapRtdbReplayDivergence));
+    engineResults.sandbox = {
+      engine: 'sandbox',
+      ok: divergences.every(isInformational),
+      checkedEvents: replays.reduce((total, replayed) => total + replayed.checkedEvents, 0),
+      divergences,
+    };
+  }
+  if (engines.includes('staging') && staging !== undefined) {
+    engineResults.staging = await verifyRtdbOnStaging(fixture, checks, staging);
+  }
+  if (engineResults.sandbox && engineResults.staging) {
+    addRtdbEngineDrift(engineResults.sandbox, engineResults.staging);
+  }
 
+  const divergences = collectEngineDivergences(engineResults);
   return {
     service: 'rtdb',
     ok: divergences.every(isInformational),
-    checkedEvents,
+    checkedEvents: engineResults.sandbox?.checkedEvents ?? engineResults.staging?.checkedEvents ?? 0,
     divergences,
-    engines: { sandbox },
+    engines: engineResults,
     ...(skippedInstances.length > 0 ? { skippedInstances } : {}),
   };
 }
 
+/**
+ * Replay each instance on the staging instance in turn, each run guarded and
+ * the instance put back before the next. Production refusing to deploy an
+ * instance's candidate rules is reported for that instance; the others run.
+ */
+async function verifyRtdbOnStaging(
+  fixture: PyricVerifyFixture,
+  checks: Array<{ instance?: string; rules: RtdbRulesJson; capturedState: unknown }>,
+  staging: NonNullable<VerifyFixtureOptions['staging']>,
+): Promise<VerifyEngineResult> {
+  const divergences: VerifyDivergence[] = [];
+  let checkedEvents = 0;
+  for (const check of checks) {
+    const tag = check.instance === undefined ? {} : { instance: check.instance };
+    try {
+      const { result } = await withStagingInstance(staging.client, staging.projectId, () =>
+        runStagingInstance({
+          client: staging.client,
+          events: fixture.events,
+          rules: check.rules,
+          capturedState: check.capturedState,
+          ...(check.instance === undefined ? {} : { instance: check.instance }),
+          ...(staging.signal ? { signal: staging.signal } : {}),
+        }), staging);
+      checkedEvents += result.checkedEvents;
+      divergences.push(...result.divergences.map((divergence) => ({ service: 'rtdb', ...divergence, ...tag })));
+    } catch (error) {
+      if (!(error instanceof StagingDeployRefusedError)) throw error;
+      divergences.push({ service: 'rtdb', kind: 'unsupported', reason: error.message, ...tag });
+    }
+  }
+  return { engine: 'staging', ok: divergences.every(isInformational), checkedEvents, divergences };
+}
+
+/**
+ * Where the sandbox and production decided a captured step differently: one
+ * engine reports `now-denied`, `now-allowed` or `unsupported` for a step and
+ * the other reports something else, or nothing. Steps are matched by their
+ * index in the replay both engines walk.
+ */
+function addRtdbEngineDrift(sandbox: VerifyEngineResult, staging: VerifyEngineResult): void {
+  const decisive = new Set(['now-denied', 'now-allowed', 'unsupported']);
+  const keyOf = (divergence: VerifyDivergence) =>
+    `${divergence.instance ?? ''}|${(divergence as { step?: number }).step ?? `${(divergence as { method?: string }).method}|${divergence.path}`}`;
+  const byKey = (divergences: VerifyDivergence[]) =>
+    new Map(divergences.filter((divergence) => decisive.has(divergence.kind)).map((divergence) => [keyOf(divergence), divergence]));
+  const local = byKey(sandbox.divergences);
+  const remote = byKey(staging.divergences);
+  for (const key of new Set([...local.keys(), ...remote.keys()])) {
+    const sandboxKind = local.get(key)?.kind ?? 'unchanged';
+    const stagingKind = remote.get(key)?.kind ?? 'unchanged';
+    if (sandboxKind === stagingKind) continue;
+    const sample = (local.get(key) ?? remote.get(key))!;
+    staging.divergences.push({
+      service: 'rtdb',
+      kind: 'engine-drift',
+      path: sample.path,
+      method: (sample as { method?: string }).method,
+      sandbox: sandboxKind,
+      staging: stagingKind,
+      reason: `the sandbox reported ${sandboxKind}; production reported ${stagingKind}.`,
+      ...(sample.instance === undefined ? {} : { instance: sample.instance }),
+      ...((sample as { step?: number }).step === undefined ? {} : { step: (sample as { step?: number }).step }),
+    });
+  }
+  staging.ok = staging.divergences.every(isInformational);
+}
+
 async function verifyStorage(
   fixture: PyricVerifyFixture,
   rules: VerifyRulesInput,
@@ -864,7 +964,7 @@ function normalizeEngines(input: VerifyEngine[] | undefined): VerifyEngine[] {
   const engines = input ?? ['sandbox'];
   const out: VerifyEngine[] = [];
   for (const engine of engines) {
-    if (engine !== 'sandbox' && engine !== 'rulesTestApi') {
+    if (engine !== 'sandbox' && engine !== 'rulesTestApi' && engine !== 'staging') {
       throw new VerifyInputError(`unsupported verify engine: ${String(engine)}`);
     }
     if (!out.includes(engine)) out.push(engine);
@@ -881,7 +981,7 @@ function collectEngineDivergences(
 function serviceCheckedEvents(
   engines: Partial<Record<VerifyEngine, VerifyEngineResult>>,
 ): number {
-  return engines.sandbox?.checkedEvents ?? engines.rulesTestApi?.checkedEvents ?? 0;
+  return engines.sandbox?.checkedEvents ?? engines.rulesTestApi?.checkedEvents ?? engines.staging?.checkedEvents ?? 0;
 }
 
 function mapUnsupportedEvent(event: VerifyUnsupportedEvent): VerifyDivergence {