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

package/src/rtdb/crawl-snapshot.ts

@@ -0,0 +1,118 @@
+/** Structural RTDB traversal over an already-local sandbox snapshot. */
+export interface RtdbStructureNode {
+  path: string;
+  childCount: number;
+  truncated: boolean;
+  children: RtdbStructureNode[];
+  schema: Record<string, string>;
+  valueType?: string;
+}
+
+export interface CrawlSnapshotOptions {
+  path?: string;
+  maxDepth?: number;
+  maxChildren?: number;
+}
+
+function childPath(parent: string, key: string): string {
+  return parent === '/' ? `/${key}` : `${parent}/${key}`;
+}
+
+function valueType(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function normalizePath(path: string | undefined): string {
+  const segments = (path ?? '/').split('/').filter(Boolean);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
+
+function valueAtPath(value: unknown, path: string): unknown {
+  let current = value;
+  for (const segment of path.split('/').filter(Boolean)) {
+    if (current === null || typeof current !== 'object' || Array.isArray(current)) {
+      return null;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current ?? null;
+}
+
+function crawlNode(
+  value: unknown,
+  path: string,
+  depth: number,
+  maxDepth: number,
+  maxChildren: number,
+): RtdbStructureNode {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      path,
+      childCount: 0,
+      truncated: false,
+      children: [],
+      schema: {},
+      valueType: valueType(value),
+    };
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right));
+  const schema: Record<string, string> = {};
+  const objectEntries: Array<[string, Record<string, unknown>]> = [];
+
+  for (const [key, child] of entries) {
+    if (child !== null && typeof child === 'object' && !Array.isArray(child)) {
+      objectEntries.push([key, child as Record<string, unknown>]);
+    } else {
+      schema[key] = valueType(child);
+    }
+  }
+
+  const depthTruncated = depth >= maxDepth && objectEntries.length > 0;
+  const childLimitTruncated = entries.length > maxChildren;
+  const children = depth >= maxDepth
+    ? []
+    : objectEntries
+        .slice(0, maxChildren)
+        .map(([key, child]) => crawlNode(
+          child,
+          childPath(path, key),
+          depth + 1,
+          maxDepth,
+          maxChildren,
+        ));
+
+  return {
+    path,
+    childCount: entries.length,
+    truncated: depthTruncated || childLimitTruncated,
+    children,
+    schema,
+  };
+}
+
+export function crawlSnapshot(
+  snapshot: unknown,
+  options: CrawlSnapshotOptions = {},
+): RtdbStructureNode {
+  const path = normalizePath(options.path);
+  const maxDepth = options.maxDepth ?? 10;
+  const maxChildren = options.maxChildren ?? 100;
+  return crawlNode(
+    valueAtPath(snapshot, path),
+    path,
+    0,
+    maxDepth,
+    maxChildren,
+  );
+}
+
+export function countDescendantObjects(node: RtdbStructureNode): number {
+  return node.children.reduce(
+    (total, child) => total + 1 + countDescendantObjects(child),
+    0,
+  );
+}

package/src/rtdb/inspection.ts

@@ -0,0 +1,137 @@
+/** Local RTDB inspection tools bound to one authoritative sandbox. */
+import type { ToolHandler } from '@inbrowser/agent';
+import { rtdbRules, type RtdbCase } from 'pyric/rules';
+import type { LocalSandbox } from 'pyric/sandbox';
+import { getActiveRules, snapshotState } from 'pyric/sandbox/database';
+import { countDescendantObjects, crawlSnapshot } from './crawl-snapshot.js';
+
+export interface RtdbInspectionToolDeps {
+  resolveSandbox(): LocalSandbox | Promise<LocalSandbox>;
+}
+
+interface SimulateAccessArgs {
+  operation: 'read' | 'write' | 'validate';
+  path: string;
+  auth?: { uid: string; claims?: Record<string, unknown> } | null;
+  newData?: unknown;
+}
+
+interface CrawlStructureArgs {
+  path?: string;
+  maxDepth?: number;
+  maxChildren?: number;
+}
+
+export function createRtdbInspectionTools(
+  deps: RtdbInspectionToolDeps,
+): ToolHandler[] {
+  return [
+    {
+      name: 'rtdb_simulate_access',
+      description:
+        'Simulate one read, write, or validate operation against the RTDB rules and data currently loaded in the local sandbox. No production database is contacted and no prior rules-loading tool call is required.',
+      parameters: {
+        type: 'object',
+        properties: {
+          operation: {
+            type: 'string',
+            enum: ['read', 'write', 'validate'],
+          },
+          path: { type: 'string' },
+          auth: {
+            anyOf: [
+              { type: 'null' },
+              {
+                type: 'object',
+                properties: {
+                  uid: { type: 'string' },
+                  claims: { type: 'object' },
+                },
+                required: ['uid'],
+              },
+            ],
+          },
+          newData: {},
+        },
+        required: ['operation', 'path'],
+      },
+      async execute(rawArgs) {
+        const args = rawArgs as SimulateAccessArgs;
+        const sandbox = await deps.resolveSandbox();
+        const rules = getActiveRules(sandbox);
+        if (!rules) {
+          return {
+            ok: false,
+            summary: 'No RTDB rules are loaded in the local sandbox.',
+            data: { code: 'NO_ACTIVE_RULES' },
+          };
+        }
+
+        const state = snapshotState(sandbox);
+        const data = state !== null && typeof state === 'object' && !Array.isArray(state)
+          ? state as Record<string, unknown>
+          : {};
+        const oneCase: RtdbCase = {
+          expectation: 'ALLOW',
+          operation: args.operation,
+          path: args.path,
+          auth: args.auth
+            ? { uid: args.auth.uid, token: args.auth.claims ?? {} }
+            : null,
+          data,
+          ...(args.newData !== undefined ? { newData: args.newData } : {}),
+        };
+        const result = rtdbRules(rules).simulate([oneCase]).cases[0];
+
+        return {
+          ok: !result.unsupported,
+          summary: result.unsupported
+            ? `Simulation unsupported: ${result.reason}`
+            : `Simulation: ${result.decision.toLowerCase()}`,
+          data: {
+            decision: result.decision,
+            allowed: result.decision === 'ALLOW',
+            unsupported: result.unsupported,
+            matchedPath: result.matchedPath,
+            matchedRule: result.matchedRule,
+            reason: result.reason,
+          },
+        };
+      },
+    },
+    {
+      name: 'rtdb_crawl_structure',
+      description:
+        'Describe the structure of the RTDB data currently loaded in the local sandbox without returning leaf values or contacting a production database.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Root-relative path to inspect. Defaults to /.',
+          },
+          maxDepth: {
+            type: 'number',
+            minimum: 0,
+            description: 'Maximum object depth to return. Defaults to 10.',
+          },
+          maxChildren: {
+            type: 'number',
+            minimum: 1,
+            description: 'Maximum object children to return per node. Defaults to 100.',
+          },
+        },
+      },
+      async execute(rawArgs) {
+        const args = rawArgs as CrawlStructureArgs;
+        const sandbox = await deps.resolveSandbox();
+        const root = crawlSnapshot(snapshotState(sandbox), args);
+        return {
+          ok: true,
+          summary: `Crawled ${countDescendantObjects(root)} object paths from ${root.path}`,
+          data: root,
+        };
+      },
+    },
+  ];
+}

package/src/rtdb/load-rules-document.ts

@@ -0,0 +1,56 @@
+/**
+ * Loads a user's RTDB constraints module (a file that calls
+ * `defineRtdbRules(...)` from `pyric/rules`) so the CLI and MCP
+ * `generate` surfaces can turn it into static rules JSON without
+ * reimplementing compilation — the loaded document's `.toJSON()` still
+ * routes through the pure RTDB rules compiler.
+ *
+ * The module may export the `RtdbRulesDocument` as its default export
+ * or as a named `rules` export.
+ */
+
+import { pathToFileURL } from 'node:url';
+import { resolve as resolvePath } from 'node:path';
+import type { RtdbRulesDocument } from 'pyric/rules/internal/rtdb';
+import { isRtdbRulesDocument } from './rules-json.js';
+
+export interface LoadRtdbRulesDocumentOptions {
+  cwd?: string;
+  /** Named export to look for before falling back to `default`. Defaults to `rules`. */
+  exportName?: string;
+}
+
+export type LoadRtdbRulesDocumentResult =
+  | { ok: true; document: RtdbRulesDocument }
+  | { ok: false; message: string };
+
+export async function loadRtdbRulesDocument(
+  configPath: string,
+  options: LoadRtdbRulesDocumentOptions = {},
+): Promise<LoadRtdbRulesDocumentResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const exportName = options.exportName ?? 'rules';
+  const resolved = resolvePath(cwd, configPath);
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(resolved).href)) as Record<string, unknown>;
+  } catch (e) {
+    return {
+      ok: false,
+      message: `failed to load RTDB constraints module at ${resolved}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+
+  const candidate = mod[exportName] ?? mod.default;
+  if (!isRtdbRulesDocument(candidate)) {
+    return {
+      ok: false,
+      message:
+        `${resolved} does not export an RtdbRulesDocument (looked for a named ` +
+        `'${exportName}' export or a default export produced by defineRtdbRules(...)).`,
+    };
+  }
+
+  return { ok: true, document: candidate };
+}

package/src/rtdb/rules-generation-tool.ts

@@ -0,0 +1,38 @@
+import type { ToolHandler } from '@inbrowser/agent';
+import { loadRtdbRulesDocument } from './load-rules-document.js';
+
+/** Local RTDB artifact generation for the CLI's agent registry. */
+export function createRtdbRulesGenerationTools(): ToolHandler[] {
+  return [
+    {
+      name: 'rtdb_generate_rules',
+      description:
+        'Compile a local RTDB constraints module into database.rules.json data for inspection, tests, or committing.',
+      parameters: {
+        type: 'object',
+        properties: {
+          configPath: {
+            type: 'string',
+            description:
+              "Path to the constraints module, relative to cwd. Defaults to 'database.rules.ts'.",
+          },
+          cwd: {
+            type: 'string',
+            description: 'Working directory used to resolve configPath. Defaults to process.cwd().',
+          },
+        },
+      },
+      async execute(args) {
+        const { configPath, cwd } = args as { configPath?: string; cwd?: string };
+        const loaded = await loadRtdbRulesDocument(configPath ?? 'database.rules.ts', { cwd });
+        if (!loaded.ok) return { ok: false, summary: loaded.message };
+
+        return {
+          ok: true,
+          summary: 'Compiled RTDB constraints to database.rules.json',
+          data: { rulesJson: loaded.document.toJSON() },
+        };
+      },
+    },
+  ];
+}

package/src/rtdb/rules-json.ts

@@ -0,0 +1,29 @@
+import type { RtdbRulesDocument } from 'pyric/rules/internal/rtdb';
+
+export interface RtdbRulesJson {
+  rules: Record<string, unknown>;
+}
+
+export function isRtdbRulesJson(value: unknown): value is RtdbRulesJson {
+  return isRtdbRulesObject(value) && isRtdbRulesObject(value.rules);
+}
+
+export function parseRtdbRulesJson(
+  value: unknown,
+  onInvalid: () => Error,
+): RtdbRulesJson {
+  if (!isRtdbRulesJson(value)) throw onInvalid();
+  return value;
+}
+
+export function isRtdbRulesDocument(value: unknown): value is RtdbRulesDocument {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { toJSON?: unknown }).toJSON === 'function'
+  );
+}
+
+function isRtdbRulesObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/serve/activity-guard.ts

@@ -0,0 +1,29 @@
+import {
+  monitorFirebaseActivity,
+  type ActivityFeed,
+  type ActivityMonitor,
+} from 'pyric/firestore/internal';
+
+/** Browser-safe reporter shared by the SharedWorker and in-page pyric dev paths. */
+export function setupFirebaseActivityGuard(
+  feed: ActivityFeed,
+  fetchFn: typeof fetch,
+  activityToken: string,
+): ActivityMonitor {
+  return monitorFirebaseActivity(feed, (incident) => {
+    try {
+      void fetchFn('/__pyric/activity', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-pyric-activity-token': activityToken,
+        },
+        body: JSON.stringify(incident),
+      }).catch(() => {
+        /* Diagnostics are best-effort and must never affect app behavior. */
+      });
+    } catch {
+      /* An injected or unavailable fetch must never affect app behavior. */
+    }
+  });
+}

package/src/serve/activity-route.ts

@@ -0,0 +1,164 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  hasGeneratedActivitySemantics,
+  type ActivityIncident,
+} from 'pyric/firestore/internal';
+
+const MAX_ACTIVITY_BODY_BYTES = 32 * 1024;
+
+class ActivityBodyTooLargeError extends Error {}
+
+export async function handleActivity(
+  onIncident: (incident: ActivityIncident) => void,
+  req: IncomingMessage,
+  res: ServerResponse,
+  activityToken: string,
+): Promise<void> {
+  if (req.method !== 'POST') {
+    res.writeHead(405, { allow: 'POST' }).end('method not allowed');
+    return;
+  }
+  const mediaType = req.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase();
+  if (mediaType !== 'application/json') {
+    res.writeHead(415, { 'content-type': 'text/plain; charset=utf-8' })
+      .end('content-type must be application/json');
+    return;
+  }
+  if (!hasTrustedOrigin(req)) {
+    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
+      .end('cross-origin activity reports are not allowed');
+    return;
+  }
+  if (req.headers['x-pyric-activity-token'] !== activityToken) {
+    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
+      .end('invalid activity capability');
+    return;
+  }
+  try {
+    const body = await collectActivityBody(req);
+    if (!isActivityIncident(body)) throw new Error('invalid activity incident');
+    onIncident(body);
+    res.writeHead(204).end();
+  } catch (error) {
+    res.writeHead(error instanceof ActivityBodyTooLargeError ? 413 : 400, {
+      'content-type': 'text/plain; charset=utf-8',
+    });
+    res.end(error instanceof Error ? error.message : String(error));
+  }
+}
+
+function hasTrustedOrigin(req: IncomingMessage): boolean {
+  const origin = req.headers.origin;
+  if (origin === undefined) return false;
+  const host = req.headers.host;
+  if (!host) return false;
+  try {
+    const parsed = new URL(origin);
+    const protocol = (req.socket as { encrypted?: boolean }).encrypted ? 'https:' : 'http:';
+    return parsed.protocol === protocol && parsed.host === host;
+  } catch {
+    return false;
+  }
+}
+
+async function collectActivityBody(req: IncomingMessage): Promise<unknown> {
+  const declaredLength = Number(req.headers['content-length']);
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_ACTIVITY_BODY_BYTES) {
+    req.resume();
+    throw new ActivityBodyTooLargeError('activity incident exceeds 32 KiB');
+  }
+
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    req.on('data', (chunk: Buffer | string) => {
+      if (settled) return;
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+      size += bytes.byteLength;
+      if (size > MAX_ACTIVITY_BODY_BYTES) {
+        settled = true;
+        chunks.length = 0;
+        reject(new ActivityBodyTooLargeError('activity incident exceeds 32 KiB'));
+        return;
+      }
+      chunks.push(bytes);
+    });
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks, size).toString('utf8')));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+  });
+}
+
+function isActivityIncident(value: unknown): value is ActivityIncident {
+  if (!value || typeof value !== 'object') return false;
+  const incident = value as Record<string, unknown>;
+  const usage = incident.usage as Record<string, unknown> | undefined;
+  const actor = incident.actor as Record<string, unknown> | undefined;
+  const authLens = incident.authLens as Record<string, unknown> | undefined;
+  const listenerBalance = incident.listenerBalance as Record<string, unknown> | undefined;
+  return typeof incident.fingerprint === 'string'
+    && incident.fingerprint.length <= 2_000
+    && (incident.pattern === 'repeated-read'
+      || incident.pattern === 'duplicate-listener'
+      || incident.pattern === 'listener-churn')
+    && (incident.confidence === 'medium' || incident.confidence === 'high')
+    && (incident.severity === 'warning' || incident.severity === 'critical')
+    && incident.service === 'firestore'
+    && (incident.method === 'get' || incident.method === 'list' || incident.method === 'listen')
+    && typeof incident.targetFingerprint === 'string'
+    && incident.targetFingerprint.length <= 2_000
+    && actor?.kind === 'app'
+    && Boolean(authLens)
+    && (authLens!.mode === 'app-session'
+      || authLens!.mode === 'anon'
+      || (authLens!.mode === 'as' && typeof authLens!.uid === 'string'))
+    && (incident.authUid === null || typeof incident.authUid === 'string')
+    && isNonNegativeInteger(incident.count)
+    && incident.count > 0
+    && isNonNegativeInteger(incident.windowMs)
+    && Array.isArray(incident.evidenceEventIds)
+    && incident.evidenceEventIds.length <= 8
+    && incident.evidenceEventIds.every((id) => typeof id === 'string')
+    && Boolean(usage)
+    && (usage!.unit === 'document-reads' || usage!.unit === 'listener-attaches')
+    && isNonNegativeInteger(usage!.lowerBound)
+    && usage!.lowerBound === incident.count
+    && Array.isArray(usage!.limitations)
+    && usage!.limitations.length <= 8
+    && usage!.limitations.every(
+      (limitation) => typeof limitation === 'string' && limitation.length <= 500,
+    )
+    && (incident.sourceAttribution === 'app'
+      || (typeof incident.sourceAttribution === 'string'
+        && /^app [\w.-]{1,64}$/.test(incident.sourceAttribution)))
+    && (listenerBalance === undefined
+      || (isNonNegativeInteger(listenerBalance.attaches)
+        && isNonNegativeInteger(listenerBalance.detaches)
+        && isNonNegativeInteger(listenerBalance.active)
+        && (listenerBalance.isLowerBound === undefined
+          || typeof listenerBalance.isLowerBound === 'boolean')))
+    && (incident.pattern === 'repeated-read'
+      ? ((incident.method === 'get' || incident.method === 'list')
+        && usage!.unit === 'document-reads'
+        && listenerBalance === undefined)
+      : (incident.method === 'listen'
+        && usage!.unit === 'listener-attaches'
+        && listenerBalance !== undefined))
+    && hasGeneratedActivitySemantics(incident as unknown as ActivityIncident);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}

package/src/serve/activity-warning.ts

@@ -0,0 +1,26 @@
+import type { ActivityIncident } from 'pyric/firestore/internal';
+
+/** Format a terminal-safe, warning-only summary of observed Firebase activity. */
+export function formatActivityWarning(incident: ActivityIncident): string {
+  const target = terminalSafe(incident.targetFingerprint);
+  const lowerBound = incident.listenerBalance?.isLowerBound === true ? 'at least ' : '';
+  const activity = incident.pattern === 'repeated-read'
+    ? `${incident.count} repeated Firestore ${incident.method} operations`
+    : incident.pattern === 'duplicate-listener'
+      ? `${lowerBound}${incident.count} duplicate active Firestore listeners`
+      : `${lowerBound}${incident.listenerBalance!.attaches} Firestore listener attaches, `
+        + `${incident.listenerBalance!.detaches} detaches, `
+        + `${incident.listenerBalance!.active} still active (listener churn)`;
+  const unit = incident.usage.unit === 'document-reads' ? 'document reads' : 'listener attachments';
+  return `  ⚠ Firebase Activity Guard: ${activity} on ${target} in ${incident.windowMs}ms. `
+    + `Observed lower bound: ${incident.usage.lowerBound} ${unit}. `
+    + `Source: ${terminalSafe(incident.sourceAttribution)}. Possible causes include repeated render/effect `
+    + 'execution or missing listener cleanup. (warning only; app behavior is unchanged)';
+}
+
+function terminalSafe(value: string): string {
+  return value.replace(
+    /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g,
+    '',
+  );
+}