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

package/src/functions-rtdb/in-memory-delivery.ts

@@ -0,0 +1,40 @@
+import type { RtdbTriggerDelivery } from './delivery.js';
+
+function canonicalPath(path: string): string {
+  const normalized = path.split('/').filter(Boolean).join('/');
+  return normalized ? `/${normalized}` : '/';
+}
+
+/** Deterministic test adapter for the snapshot-delivery seam. */
+export class InMemoryRtdbTriggerDelivery implements RtdbTriggerDelivery {
+  readonly #values = new Map<string, unknown>();
+  readonly #listeners = new Map<string, Set<(value: unknown) => void>>();
+
+  seed(path: string, value: unknown): void {
+    this.#values.set(canonicalPath(path), structuredClone(value));
+  }
+
+  emit(path: string, value: unknown): void {
+    const key = canonicalPath(path);
+    const snapshot = structuredClone(value);
+    this.#values.set(key, snapshot);
+    for (const listener of this.#listeners.get(key) ?? []) {
+      listener(structuredClone(snapshot));
+    }
+  }
+
+  subscribe(path: string, listener: (value: unknown) => void): () => void {
+    const key = canonicalPath(path);
+    let listeners = this.#listeners.get(key);
+    if (!listeners) {
+      listeners = new Set();
+      this.#listeners.set(key, listeners);
+    }
+    listeners.add(listener);
+    listener(structuredClone(this.#values.get(key) ?? null));
+    return () => {
+      listeners?.delete(listener);
+      if (listeners?.size === 0) this.#listeners.delete(key);
+    };
+  }
+}

package/src/functions-rtdb/project.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { FirebaseJson } from '../cli/firebase-json.js';
+
+export interface FunctionsRtdbProject {
+  sourceDir: string;
+  entry: string;
+}
+
+interface FunctionsConfig {
+  source?: unknown;
+  codebase?: unknown;
+}
+
+/** Discover the one Node Functions source supported by the first RTDB slice. */
+export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject | null {
+  const firebaseJsonPath = join(cwd, 'firebase.json');
+  if (!existsSync(firebaseJsonPath)) return null;
+
+  let config: FirebaseJson;
+  try {
+    config = JSON.parse(readFileSync(firebaseJsonPath, 'utf8')) as FirebaseJson;
+  } catch (error) {
+    throw new Error(
+      `pyric dev: failed to parse firebase.json while discovering Functions: ` +
+        `${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (config.functions === undefined || config.functions === null) return null;
+
+  const declared = Array.isArray(config.functions)
+    ? config.functions as FunctionsConfig[]
+    : [config.functions as FunctionsConfig];
+  if (declared.length !== 1) {
+    throw new Error(
+      'pyric dev: multiple Functions codebases are not supported by the first ' +
+        'onValueCreated slice; configure one source for this development session.',
+    );
+  }
+  const functions = declared[0];
+  if (typeof functions !== 'object' || functions === null) {
+    throw new Error('pyric dev: firebase.json `functions` must be an object with a source.');
+  }
+  if (functions.source !== undefined && typeof functions.source !== 'string') {
+    throw new Error('pyric dev: firebase.json `functions.source` must be a string.');
+  }
+
+  const sourceDir = resolve(cwd, functions.source ?? 'functions');
+  const packageJsonPath = join(sourceDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    throw new Error(
+      `pyric dev: Functions source is declared but ${packageJsonPath} does not exist.`,
+    );
+  }
+
+  let packageJson: { main?: unknown };
+  try {
+    packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { main?: unknown };
+  } catch (error) {
+    throw new Error(
+      `pyric dev: failed to parse ${packageJsonPath}: ` +
+        `${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (packageJson.main !== undefined && typeof packageJson.main !== 'string') {
+    throw new Error(`pyric dev: ${packageJsonPath} \`main\` must be a string.`);
+  }
+
+  const entry = resolve(sourceDir, packageJson.main ?? 'index.js');
+  if (!existsSync(entry) || !statSync(entry).isFile()) {
+    throw new Error(`pyric dev: Functions entry does not exist: ${entry}`);
+  }
+  return { sourceDir, entry };
+}

package/src/functions-rtdb/projection.ts

@@ -0,0 +1,104 @@
+import {
+  normalizeRtdbReference,
+  rtdbReferenceParamName,
+  rtdbReferenceParts,
+} from './reference-pattern.js';
+
+export interface RtdbSnapshotCommit {
+  path: string;
+  before: unknown;
+  after: unknown;
+}
+
+export interface CreatedValueProjection {
+  ref: string;
+  params: Record<string, string>;
+  value: unknown;
+}
+
+function canonicalPath(path: string): string {
+  const normalized = normalizeRtdbReference(path);
+  return normalized ? `/${normalized}` : '/';
+}
+
+function exists(value: unknown): boolean {
+  return value !== null && value !== undefined;
+}
+
+function child(value: unknown, key: string): unknown {
+  if (typeof value !== 'object' || value === null) return undefined;
+  return Object.prototype.hasOwnProperty.call(value, key)
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+function childKeys(value: unknown): string[] {
+  if (typeof value !== 'object' || value === null) return [];
+  return Object.keys(value).filter((key) => exists(child(value, key))).sort();
+}
+
+export function watchPath(reference: string): string {
+  const literal: string[] = [];
+  for (const segment of rtdbReferenceParts(reference)) {
+    if (rtdbReferenceParamName(segment)) break;
+    literal.push(segment);
+  }
+  return canonicalPath(literal.join('/'));
+}
+
+/** Project absent-to-present values for one v2 RTDB trigger reference. */
+export function projectValueCreates(
+  reference: string,
+  commit: RtdbSnapshotCommit,
+): CreatedValueProjection[] {
+  const pattern = rtdbReferenceParts(reference);
+  const committed = rtdbReferenceParts(commit.path);
+  if (committed.length > pattern.length) return [];
+
+  const params: Record<string, string> = {};
+  for (let index = 0; index < committed.length; index += 1) {
+    const capture = rtdbReferenceParamName(pattern[index]);
+    if (capture) params[capture] = committed[index];
+    else if (pattern[index] !== committed[index]) return [];
+  }
+
+  const projected: CreatedValueProjection[] = [];
+  const visit = (
+    depth: number,
+    before: unknown,
+    after: unknown,
+    concrete: string[],
+    captures: Record<string, string>,
+  ): void => {
+    if (depth === pattern.length) {
+      if (!exists(before) && exists(after)) {
+        projected.push({ ref: concrete.join('/'), params: captures, value: after });
+      }
+      return;
+    }
+    const segment = pattern[depth];
+    const capture = rtdbReferenceParamName(segment);
+    if (capture) {
+      for (const key of childKeys(after)) {
+        visit(
+          depth + 1,
+          child(before, key),
+          child(after, key),
+          [...concrete, key],
+          { ...captures, [capture]: key },
+        );
+      }
+      return;
+    }
+    visit(
+      depth + 1,
+      child(before, segment),
+      child(after, segment),
+      [...concrete, segment],
+      captures,
+    );
+  };
+
+  visit(committed.length, commit.before, commit.after, committed, params);
+  return projected;
+}

package/src/functions-rtdb/reference-pattern.ts

@@ -0,0 +1,20 @@
+export function normalizeRtdbReference(reference: string): string {
+  return reference.split('/').filter(Boolean).join('/');
+}
+
+export function rtdbReferenceParts(reference: string): string[] {
+  const normalized = normalizeRtdbReference(reference);
+  return normalized ? normalized.split('/') : [];
+}
+
+export function rtdbReferenceParamName(segment: string): string | null {
+  return /^\{([A-Za-z0-9_]+)(?:=\*)?\}$/.exec(segment)?.[1] ?? null;
+}
+
+export function supportsRtdbReference(reference: string): boolean {
+  return rtdbReferenceParts(reference).every((segment) =>
+    rtdbReferenceParamName(segment) !== null || (
+      !segment.includes('{') && !segment.includes('}') && !segment.includes('*')
+    ),
+  );
+}

package/src/functions-rtdb/remote-delivery.ts

@@ -0,0 +1,23 @@
+import type { RemoteRtdb } from '../remote/index.js';
+import type { RtdbTriggerDelivery } from './delivery.js';
+
+/** Existing remote RTDB value subscriptions adapted to the execution seam. */
+export class RemoteRtdbTriggerDelivery implements RtdbTriggerDelivery {
+  readonly #rtdb: Pick<RemoteRtdb, 'onValue'>;
+
+  constructor(rtdb: Pick<RemoteRtdb, 'onValue'>) {
+    this.#rtdb = rtdb;
+  }
+
+  subscribe(
+    path: string,
+    listener: (value: unknown) => void,
+    onError?: (error: unknown) => void,
+  ): () => void {
+    return this.#rtdb.onValue(
+      path,
+      (snapshot) => listener(snapshot.value),
+      onError,
+    );
+  }
+}

package/src/pkg-version.ts

@@ -0,0 +1,49 @@
+/**
+ * @pyric/cli' OWN package version, resolved at runtime — the version-skew
+ * stamp both ends of the worker relay compare (integration-smoke fix: an old
+ * `pyric dev` accepting a newer client's frame and dying mid-handling used to
+ * surface as a bare 30s timeout with no hint).
+ *
+ * Resolution order:
+ *   1. A standalone `bun build --compile` binary's baked version
+ *      (`globalThis.__PYRIC_EMBEDDED__.version` — see serve/standalone-assets).
+ *   2. The nearest `package.json` walking up from THIS module (dist/ or src/),
+ *      i.e. the @pyric/cli install actually executing.
+ *   3. `'0.0.0'` when neither resolves (never throws).
+ *
+ * Node-only (node:fs / node:url) — do NOT import from browser-bundled modules
+ * (`bridge/protocol.ts`, the bridge client, worker code). The server
+ * (`bridge/server/peer.ts`) and the Node remote client (`remote/index.ts`)
+ * are the intended consumers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let cached: string | null = null;
+
+export function cliVersion(): string {
+  if (cached !== null) return cached;
+  const embedded = (
+    globalThis as { __PYRIC_EMBEDDED__?: { version?: string } }
+  ).__PYRIC_EMBEDDED__;
+  if (typeof embedded?.version === 'string' && embedded.version.length > 0) {
+    cached = embedded.version;
+    return cached;
+  }
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (!existsSync(join(dir, 'package.json'))) {
+      const parent = dirname(dir);
+      if (parent === dir) break; // filesystem root
+      dir = parent;
+    }
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {
+      version?: string;
+    };
+    cached = pkg.version ?? '0.0.0';
+  } catch {
+    cached = '0.0.0';
+  }
+  return cached;
+}

package/src/register/esm-exports.ts

@@ -0,0 +1,63 @@
+/**
+ * Minimal `exports`-field walker for the CJS→ESM seam in
+ * `@pyric/cli/register`.
+ *
+ * Why it exists: a rewritten CJS `require('firebase-admin/app')` resolves
+ * `pyric-admin/app` under the `require` condition, but the pyric mirrors are
+ * ESM-only (`import`-condition exports) — Node's CJS resolver throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED and ignores hook-supplied condition
+ * overrides. `require(esm)` (Node ≥ 22.12) can LOAD the module fine once we
+ * hand it the file, so the register hook locates the package
+ * (`Module.findPackageJSON`) and resolves the subpath here under import
+ * conditions.
+ *
+ * Deliberately narrow, matching what the pyric packages actually publish:
+ * literal subpaths only (no `*` patterns), string targets, and nested
+ * condition objects tried in `node` → `import` → `default` order (`types`
+ * and unknown conditions are skipped).
+ */
+
+type ExportsValue = string | { [key: string]: ExportsValue } | null;
+
+const CONDITION_ORDER = ['node', 'import', 'default'] as const;
+
+/** Resolve one condition object/string to its file target, or null. */
+function resolveTarget(value: ExportsValue): string | null {
+  if (typeof value === 'string') return value;
+  if (value === null || typeof value !== 'object') return null;
+  for (const condition of CONDITION_ORDER) {
+    if (condition in value) {
+      const resolved = resolveTarget(value[condition] ?? null);
+      if (resolved !== null) return resolved;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve `subpath` (e.g. `'./app'`, or `'.'` for the root) against a
+ * package's `exports` field under import conditions. Returns the relative
+ * file target (e.g. `'./dist/app/index.js'`) or null when the subpath is
+ * not exported.
+ */
+export function resolveEsmOnlySubpath(
+  exportsField: unknown,
+  subpath: string,
+): string | null {
+  if (exportsField === null || exportsField === undefined) return null;
+  if (typeof exportsField === 'string') {
+    return subpath === '.' ? exportsField : null;
+  }
+  if (typeof exportsField !== 'object') return null;
+  const map = exportsField as Record<string, ExportsValue>;
+
+  const keys = Object.keys(map);
+  const isSubpathMap = keys.every((k) => k === '.' || k.startsWith('./'));
+  if (!isSubpathMap) {
+    // Bare conditions object — describes the root subpath only.
+    return subpath === '.' ? resolveTarget(map as ExportsValue) : null;
+  }
+  const entry = map[subpath];
+  if (entry === undefined) return null;
+  return resolveTarget(entry);
+}

package/src/register/hooks.ts

@@ -0,0 +1,30 @@
+/**
+ * `module.register()` fallback hooks — the ASYNC (loader-thread) variant of
+ * the specifier rewrite, used only on Node 22.x older than 22.15 where the
+ * sync `module.registerHooks` API doesn't exist yet.
+ *
+ * Runs on Node's loader thread, so it intercepts ESM `import` ONLY — CJS
+ * `require('firebase-admin')` is NOT rewritten on this path (index.ts logs
+ * a warning saying exactly that). Keep this module free of side effects and
+ * heavy imports: the loader thread re-instantiates it in isolation.
+ */
+import { mapFirebaseSpecifier } from './mapping.js';
+
+interface ResolveContext {
+  parentURL?: string;
+  conditions: string[];
+  importAttributes: Record<string, string>;
+}
+interface ResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+
+export function resolve(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: (specifier: string, context?: ResolveContext) => Promise<ResolveResult>,
+): Promise<ResolveResult> {
+  return nextResolve(mapFirebaseSpecifier(specifier) ?? specifier, context);
+}

package/src/register/index.ts

@@ -0,0 +1,150 @@
+/**
+ * `@pyric/cli/register` — the Node substitution seam (adoption layer 2).
+ *
+ * Loaded via `node --import @pyric/cli/register` (which `pyric dev` injects
+ * through NODE_OPTIONS), it makes the user's UNCHANGED `firebase-admin` /
+ * `firebase` imports resolve to `pyric-admin` / `pyric`, every subpath 1:1,
+ * and installs the sandbox-factory global that `pyric-admin`'s ambient
+ * `initializeApp()` consumes.
+ *
+ * ACTIVATOR, NOT LOCATOR (adoption-experience design): activation is purely
+ * the `PYRIC_SANDBOX` env var injected at invocation — never file presence,
+ * never app code. Without it this module is INERT (import it freely; nothing
+ * happens). Under `NODE_ENV=production` it REFUSES with one stderr line
+ * unless `PYRIC_SANDBOX_FORCE=1`. On activation it logs one stderr line.
+ *
+ * Hooks API: `module.registerHooks` (sync, Node ≥ 22.15) intercepts BOTH
+ * `require()` and `import`. On older 22.x it falls back to
+ * `module.register()` (ESM-only) with a warning that CJS require() is not
+ * rewritten.
+ */
+import Module from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { mapFirebaseSpecifier } from './mapping.js';
+import { resolveEsmOnlySubpath } from './esm-exports.js';
+import { remoteSandbox } from '../remote/index.js';
+
+/** The shared seam with pyric-admin's ambient init: a synchronous factory
+ *  returning the lazy branded handle. `Symbol.for` so both packages agree
+ *  without importing each other's types. */
+const SANDBOX_FACTORY = Symbol.for('pyric.remote.sandboxFactory');
+
+interface SyncResolveContext {
+  parentURL?: string;
+  conditions?: string[];
+}
+interface SyncResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+type SyncResolve = (
+  specifier: string,
+  context: SyncResolveContext,
+  nextResolve: (specifier: string, context?: SyncResolveContext) => SyncResolveResult,
+) => SyncResolveResult;
+
+/** `module.registerHooks` landed in Node 22.15 / 23.5 — feature-detect
+ *  (typed locally: the repo's ambient node types predate it). */
+const moduleApi = Module as unknown as {
+  registerHooks?: (hooks: { resolve: SyncResolve }) => void;
+  register?: (specifier: string | URL) => void;
+  findPackageJSON?: (specifier: string, base: string | URL) => string | undefined;
+};
+
+/**
+ * CJS→ESM seam: a rewritten `require()` fails against the pyric mirrors'
+ * `import`-condition-only exports (the CJS resolver ignores hook-supplied
+ * condition overrides), even though `require(esm)` can load them fine.
+ * Locate the package from this installed CLI and resolve the subpath under
+ * import conditions ourselves. The user's function package is not required
+ * to install Pyric's mapped targets. Returns the resolved file URL, or null
+ * to rethrow the original error.
+ */
+function resolveEsmOnlyForRequire(mapped: string): string | null {
+  if (typeof moduleApi.findPackageJSON !== 'function') return null;
+  const slash = mapped.indexOf('/');
+  const pkgName = slash === -1 ? mapped : mapped.slice(0, slash);
+  const subpath = slash === -1 ? '.' : `.${mapped.slice(slash)}`;
+  let pkgJsonPath: string | undefined;
+  try {
+    pkgJsonPath = moduleApi.findPackageJSON(
+      pkgName,
+      import.meta.url,
+    );
+  } catch {
+    return null;
+  }
+  if (!pkgJsonPath) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as { exports?: unknown };
+    const target = resolveEsmOnlySubpath(pkg.exports, subpath);
+    if (!target) return null;
+    return pathToFileURL(join(dirname(pkgJsonPath), target)).href;
+  } catch {
+    return null;
+  }
+}
+
+function activate(): void {
+  if (typeof moduleApi.registerHooks === 'function') {
+    moduleApi.registerHooks({
+      resolve(specifier, context, nextResolve) {
+        const mapped = mapFirebaseSpecifier(specifier);
+        if (mapped === null) return nextResolve(specifier, context);
+        try {
+          return nextResolve(mapped, { ...context, parentURL: import.meta.url });
+        } catch (err) {
+          // CJS `require('firebase-admin/app')` resolves under the `require`
+          // condition, but the pyric mirrors are ESM-only. Resolve the file
+          // under import conditions ourselves — require(esm) (Node ≥ 22.12)
+          // loads it fine once given the URL.
+          const code = (err as { code?: string }).code;
+          if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' || code === 'MODULE_NOT_FOUND') {
+            const url = resolveEsmOnlyForRequire(mapped);
+            if (url) return { url, shortCircuit: true };
+          }
+          throw err;
+        }
+      },
+    });
+  } else {
+    process.stderr.write(
+      '@pyric/cli/register: this Node version lacks module.registerHooks (needs >= 22.15) — ' +
+        'falling back to module.register: ESM imports of firebase-admin/firebase are rewritten, ' +
+        "but CJS require('firebase-admin') is NOT intercepted. Upgrade Node to >= 22.15 for full coverage.\n",
+    );
+    moduleApi.register?.(new URL('./hooks.js', import.meta.url));
+  }
+
+  // The factory global — exact contract shared with pyric-admin's ambient
+  // init: synchronous, returns the lazy branded handle.
+  (globalThis as Record<symbol, unknown>)[SANDBOX_FACTORY] = (opts?: { url?: string }) =>
+    remoteSandbox(opts);
+
+  process.stderr.write(
+    `@pyric/cli/register: active — firebase-admin/firebase imports now resolve to the ` +
+      `pyric sandbox (PYRIC_SANDBOX=${process.env.PYRIC_SANDBOX}).\n`,
+  );
+}
+
+/** Whether this process's firebase-admin/firebase imports are being rewritten
+ *  to the pyric sandbox — true only when `PYRIC_SANDBOX` was set (and not
+ *  refused by the production guard) at the moment this module loaded. */
+export let active = false;
+
+if (process.env.PYRIC_SANDBOX) {
+  if (process.env.NODE_ENV === 'production' && process.env.PYRIC_SANDBOX_FORCE !== '1') {
+    process.stderr.write(
+      '@pyric/cli/register: refusing to activate under NODE_ENV=production — ' +
+        'firebase-admin/firebase imports are NOT rewritten. ' +
+        'Set PYRIC_SANDBOX_FORCE=1 to override (dev/CI only).\n',
+    );
+  } else {
+    activate();
+    active = true;
+  }
+}
+// No PYRIC_SANDBOX → inert by design: importing this module rewrites nothing.

package/src/register/mapping.ts

@@ -0,0 +1,33 @@
+/**
+ * The specifier map behind `@pyric/cli/register`: unmodified Firebase
+ * imports resolve to their pyric mirrors. Most subpaths map 1:1
+ * (`firebase-admin/app` → `pyric-admin/app`, `firebase/firestore` →
+ * `pyric/firestore`, …). `firebase/app` maps to the Node register adapter,
+ * which translates FirebaseOptions into the process sandbox before entering
+ * the strict `pyric/app` mirror.
+ *
+ * Pure — the resolution hooks (index.ts / hooks.ts) call this and the unit
+ * suite exercises it directly. Deliberately narrow: only the two package
+ * roots match. `@firebase/*` internals, `firebase-functions`, and anything
+ * merely *containing* "firebase" pass through untouched.
+ */
+
+const MAPPINGS: ReadonlyArray<readonly [from: string, to: string]> = [
+  // firebase-admin first — `firebase-admin` must never match the bare
+  // `firebase` root (it can't today, but the order documents the intent).
+  ['firebase-admin', 'pyric-admin'],
+  ['firebase', 'pyric'],
+];
+
+/**
+ * Map a Firebase specifier to its pyric mirror, or return `null` when the
+ * specifier is not a Firebase package (leave it for the default resolver).
+ */
+export function mapFirebaseSpecifier(specifier: string): string | null {
+  if (specifier === 'firebase/app') return 'pyric/app/register';
+  for (const [from, to] of MAPPINGS) {
+    if (specifier === from) return to;
+    if (specifier.startsWith(`${from}/`)) return to + specifier.slice(from.length);
+  }
+  return null;
+}