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

package/src/cli/database-rules.ts

@@ -0,0 +1,329 @@
+/**
+ * `pyric database rules *` subcommands — local tooling for Realtime Database
+ * rules JSON.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import {
+  compileRtdbRules,
+  simulateRtdbRules,
+  type CompiledRtdbRules,
+  type RtdbNode,
+  type SimulationInput,
+  type SimulateResult,
+} from 'pyric/rules/internal/rtdb';
+import type { ParsedArgs } from './parse-args.js';
+import { readFirebaseJson, type FirebaseJson } from './firebase-json.js';
+import {
+  loadRtdbRulesDocument,
+  type LoadRtdbRulesDocumentResult,
+} from '../rtdb/load-rules-document.js';
+
+export interface DatabaseRulesDeps {
+  readFile?: typeof readFile;
+  writeFile?: typeof writeFile;
+  mkdir?: typeof mkdir;
+  readFirebaseJson?: (cwd: string) => Promise<FirebaseJson>;
+  simulate?: (compiled: CompiledRtdbRules, input: SimulationInput) => SimulateResult;
+  loadRulesDocument?: typeof loadRtdbRulesDocument;
+  cwd?: string;
+  readStdin?: () => Promise<string>;
+  stdout?: { write(s: string): void };
+  stderr?: { write(s: string): void };
+}
+
+interface RuleFinding {
+  path: string;
+  rule: '.read' | '.write' | '.validate';
+  code: string;
+  message: string;
+}
+
+function defaultReadStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function parseRulesJson(raw: string): CompiledRtdbRules {
+  return compileRtdbRules(JSON.parse(raw));
+}
+
+function collectFindings(node: RtdbNode, kind: 'errors' | 'warnings'): RuleFinding[] {
+  const findings: RuleFinding[] = [];
+  const rules = [
+    ['.read', node.read],
+    ['.write', node.write],
+    ['.validate', node.validate],
+  ] as const;
+  for (const [rule, expr] of rules) {
+    for (const finding of expr?.parsed[kind] ?? []) {
+      findings.push({
+        path: node.path,
+        rule,
+        code: finding.code,
+        message: finding.message,
+      });
+    }
+  }
+  for (const child of node.children) {
+    findings.push(...collectFindings(child, kind));
+  }
+  return findings;
+}
+
+async function readRulesFile(
+  path: string,
+  deps: DatabaseRulesDeps,
+): Promise<{ ok: true; raw: string } | { ok: false; message: string }> {
+  const cwd = deps.cwd ?? process.cwd();
+  const readFileFn = deps.readFile ?? readFile;
+  try {
+    return { ok: true, raw: await readFileFn(resolvePath(cwd, path), 'utf-8') };
+  } catch (e) {
+    return { ok: false, message: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+function jsonError(code: string, message: string): { errors: RuleFinding[]; warnings: RuleFinding[] } {
+  return {
+    errors: [{ path: '/', rule: '.read', code, message }],
+    warnings: [],
+  };
+}
+
+export async function runDatabaseRulesLint(
+  parsed: ParsedArgs,
+  deps: DatabaseRulesDeps = {},
+): Promise<number> {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  const path = parsed.positional[0];
+  if (!path) {
+    err.write('pyric database rules lint: missing rules-file path. Usage: pyric database rules lint <path>\n');
+    return 1;
+  }
+
+  const file = await readRulesFile(path, deps);
+  if (!file.ok) {
+    err.write(`pyric database rules lint: ${file.message}\n`);
+    return 1;
+  }
+
+  try {
+    const compiled = parseRulesJson(file.raw);
+    out.write(`${JSON.stringify({ warnings: collectFindings(compiled, 'warnings') }, null, 2)}\n`);
+    return 0;
+  } catch (e) {
+    out.write(`${JSON.stringify(jsonError('INVALID_RULES_JSON', e instanceof Error ? e.message : String(e)), null, 2)}\n`);
+    return 2;
+  }
+}
+
+export async function runDatabaseRulesValidate(
+  parsed: ParsedArgs,
+  deps: DatabaseRulesDeps = {},
+): Promise<number> {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  const path = parsed.positional[0];
+  if (!path) {
+    err.write('pyric database rules validate: missing rules-file path. Usage: pyric database rules validate <path>\n');
+    return 1;
+  }
+
+  const file = await readRulesFile(path, deps);
+  if (!file.ok) {
+    err.write(`pyric database rules validate: ${file.message}\n`);
+    return 1;
+  }
+
+  try {
+    const compiled = parseRulesJson(file.raw);
+    out.write(`${JSON.stringify({ errors: collectFindings(compiled, 'errors') }, null, 2)}\n`);
+    return 0;
+  } catch (e) {
+    out.write(`${JSON.stringify(jsonError('INVALID_RULES_JSON', e instanceof Error ? e.message : String(e)), null, 2)}\n`);
+    return 2;
+  }
+}
+
+interface SimulatePayload {
+  rulesJson?: unknown;
+  rules?: unknown;
+  rulesPath?: string;
+  operation?: SimulationInput['operation'];
+  path?: string;
+  auth?: SimulationInput['auth'];
+  mockData?: Record<string, unknown>;
+  newData?: unknown;
+}
+
+async function readFirebaseRules(
+  deps: DatabaseRulesDeps,
+): Promise<{ ok: true; raw: string } | { ok: false; message: string }> {
+  const cwd = deps.cwd ?? process.cwd();
+  const fjRead = deps.readFirebaseJson ?? readFirebaseJson;
+  let firebaseJson: FirebaseJson;
+  try {
+    firebaseJson = await fjRead(cwd);
+  } catch (e) {
+    return { ok: false, message: e instanceof Error ? e.message : String(e) };
+  }
+  const rulesPath = firebaseJson.database?.rules;
+  if (!rulesPath) {
+    return { ok: false, message: 'firebase.json has no `database.rules` path.' };
+  }
+  return readRulesFile(rulesPath, deps);
+}
+
+export async function runDatabaseRulesSimulate(
+  parsed: ParsedArgs,
+  deps: DatabaseRulesDeps = {},
+): Promise<number> {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  const readFileFn = deps.readFile ?? readFile;
+  const simulateFn =
+    deps.simulate ??
+    simulateRtdbRules;
+
+  let rulesJson: unknown;
+  let input: SimulationInput;
+
+  if (parsed.flags.get('stdin') === true) {
+    const readStdinFn = deps.readStdin ?? defaultReadStdin;
+    let payload: SimulatePayload;
+    try {
+      payload = JSON.parse(await readStdinFn()) as SimulatePayload;
+    } catch (e) {
+      err.write(`pyric database rules simulate: failed to parse stdin JSON: ${e instanceof Error ? e.message : String(e)}\n`);
+      return 1;
+    }
+    if (!payload.operation || !payload.path) {
+      err.write('pyric database rules simulate: stdin payload must include `operation` and `path`.\n');
+      return 1;
+    }
+    if (payload.rulesJson !== undefined || payload.rules !== undefined) {
+      rulesJson = payload.rulesJson ?? payload.rules;
+    } else if (payload.rulesPath) {
+      try {
+        rulesJson = JSON.parse(await readFileFn(resolvePath(deps.cwd ?? process.cwd(), payload.rulesPath), 'utf-8'));
+      } catch (e) {
+        err.write(`pyric database rules simulate: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+      }
+    } else {
+      const file = await readFirebaseRules(deps);
+      if (!file.ok) {
+        err.write(`pyric database rules simulate: ${file.message}\n`);
+        return 1;
+      }
+      try {
+        rulesJson = JSON.parse(file.raw);
+      } catch (e) {
+        err.write(`pyric database rules simulate: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 2;
+      }
+    }
+    input = {
+      operation: payload.operation,
+      path: payload.path,
+      auth: payload.auth ?? null,
+      mockData: payload.mockData ?? {},
+      ...(payload.newData !== undefined ? { newData: payload.newData } : {}),
+    };
+  } else {
+    const file = await readFirebaseRules(deps);
+    if (!file.ok) {
+      err.write(`pyric database rules simulate: ${file.message}\n`);
+      return 1;
+    }
+    try {
+      rulesJson = JSON.parse(file.raw);
+    } catch (e) {
+      err.write(`pyric database rules simulate: ${e instanceof Error ? e.message : String(e)}\n`);
+      return 2;
+    }
+    input = {
+      operation: 'read',
+      path: '/sample/x',
+      auth: null,
+      mockData: {},
+    };
+  }
+
+  try {
+    const compiled = compileRtdbRules(rulesJson);
+    const result = simulateFn(compiled, input);
+    out.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result.success ? 0 : 2;
+  } catch (e) {
+    err.write(`pyric database rules simulate: ${e instanceof Error ? e.message : String(e)}\n`);
+    return 2;
+  }
+}
+
+/**
+ * `pyric database rules generate [--config <path>] [--out <path>]`
+ *
+ * Loads a user's RTDB constraints module (a file that calls
+ * `defineRtdbRules(...)` from `pyric/rules`), compiles it via
+ * `RtdbRulesDocument#toJSON()` — the same primitive RTDB deploy uses —
+ * and writes the static `database.rules.json` shape to disk so it can
+ * be inspected, diffed, and committed before deploying.
+ *
+ * `--config` defaults to `database.rules.ts`. `--out` defaults to
+ * `firebase.json`'s `database.rules` path, falling back to
+ * `database.rules.json` when firebase.json has no such entry.
+ */
+export async function runDatabaseRulesGenerate(
+  parsed: ParsedArgs,
+  deps: DatabaseRulesDeps = {},
+): Promise<number> {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+  const writeFileFn = deps.writeFile ?? writeFile;
+  const mkdirFn = deps.mkdir ?? mkdir;
+  const loadRulesDocument = deps.loadRulesDocument ?? loadRtdbRulesDocument;
+
+  const configFlag = parsed.flags.get('config');
+  const configPath = typeof configFlag === 'string' ? configFlag : 'database.rules.ts';
+
+  const loaded: LoadRtdbRulesDocumentResult = await loadRulesDocument(configPath, { cwd });
+  if (!loaded.ok) {
+    err.write(`pyric database rules generate: ${loaded.message}\n`);
+    return 1;
+  }
+
+  const outFlag = parsed.flags.get('out');
+  let outPath: string;
+  if (typeof outFlag === 'string') {
+    outPath = outFlag;
+  } else {
+    const fjRead = deps.readFirebaseJson ?? readFirebaseJson;
+    let firebaseJson: FirebaseJson | null = null;
+    try {
+      firebaseJson = await fjRead(cwd);
+    } catch {
+      firebaseJson = null;
+    }
+    outPath = firebaseJson?.database?.rules ?? 'database.rules.json';
+  }
+
+  const resolvedOut = resolvePath(cwd, outPath);
+  const rulesJson = loaded.document.toJSON();
+  await mkdirFn(dirname(resolvedOut), { recursive: true });
+  await writeFileFn(resolvedOut, `${JSON.stringify(rulesJson, null, 2)}\n`, 'utf-8');
+
+  out.write(`pyric database rules generate: wrote ${resolvedOut}\n`);
+  return 0;
+}

package/src/cli/dev-runner.ts

@@ -0,0 +1,282 @@
+/**
+ * The `pyric dev` child runner — "one command, not two" (adoption design):
+ * after the host is up, run the user's OWN dev command with the environment
+ * activated so their unchanged firebase-admin/firebase imports resolve to the
+ * pyric sandbox:
+ *
+ *   PYRIC_SANDBOX=remote:<serve url>          (the activator)
+ *   NODE_OPTIONS += --import @pyric/cli/register   (the substitution seam)
+ *
+ * Child-command precedence: explicit `pyric dev -- <cmd>` wins; else the
+ * project package.json `dev` script (via the detected package manager); else
+ * host-only (today's behavior). `--no-run` forces host-only; `--json`
+ * defaults to host-only (an explicit `--` still wins — agents can opt in).
+ *
+ * Everything decision-shaped here is pure and exported for the unit suite;
+ * only `spawnDevChild` touches the process table.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ─── First-run race guard ───────────────────────────────────────────────────
+
+/**
+ * Wait (bounded) for a browser tab to register as the bridge's sandbox peer
+ * before the child spawns. `pyric dev` opens the tab and spawns the child in
+ * the same breath; a child whose first line is a sandbox op otherwise races
+ * the tab's boot and dies on the no-tab fail-fast — the exact first-run of
+ * the two-command story. Polls `/__pyric/health` (`sandboxConnected`).
+ *
+ * Returns true when a peer connected, false on timeout (caller warns and
+ * spawns anyway — the child may not touch the sandbox at all). Injectable
+ * clock/fetch for the unit suite.
+ */
+export async function waitForSandboxPeer(
+  serveUrl: string,
+  opts: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+  } = {},
+): Promise<boolean> {
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const intervalMs = opts.intervalMs ?? 250;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const res = await fetchImpl(`${serveUrl.replace(/\/$/, '')}/__pyric/health`);
+      if (res.ok) {
+        const health = (await res.json()) as { sandboxConnected?: boolean };
+        if (health.sandboxConnected === true) return true;
+      }
+    } catch {
+      // Health not up yet — keep polling until the deadline.
+    }
+    if (Date.now() >= deadline) return false;
+    await sleep(intervalMs);
+  }
+}
+
+// ─── Child-command resolution (pure) ───────────────────────────────────────
+
+export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
+
+/** Lockfile sniff, mirroring how init/vendor pick their install hints. */
+export function detectPackageManager(cwd: string): PackageManager {
+  if (existsSync(join(cwd, 'bun.lock')) || existsSync(join(cwd, 'bun.lockb'))) return 'bun';
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/** The project's `dev` script, or null (no package.json / no script). */
+export function readDevScript(cwd: string): string | null {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as {
+      scripts?: Record<string, unknown>;
+    };
+    const dev = pkg.scripts?.dev;
+    return typeof dev === 'string' && dev.trim().length > 0 ? dev : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface DevChildPlan {
+  /** argv to spawn — argv[0] is the executable, no shell. */
+  argv: string[];
+  /** Human-readable command for the pre-spawn line. */
+  label: string;
+}
+
+/**
+ * Decide what (if anything) to run after the host is up.
+ *
+ * Matrix:
+ *   --no-run                → null, always
+ *   `-- <cmd>`              → that command (wins over everything else)
+ *   --json (no `--`)        → null (machine mode defaults to host-only)
+ *   package.json dev script → `<pm> run dev`
+ *   none of the above       → null (host-only, today's behavior)
+ *
+ * A `dev` script that itself invokes `pyric dev` is treated as absent —
+ * running it would recurse forever (pyric dev → npm run dev → pyric dev …).
+ */
+export function resolveDevChild(opts: {
+  passthrough: string[];
+  noRun: boolean;
+  json: boolean;
+  devScript: string | null;
+  packageManager: PackageManager;
+}): DevChildPlan | null {
+  if (opts.noRun) return null;
+  if (opts.passthrough.length > 0) {
+    return { argv: [...opts.passthrough], label: opts.passthrough.join(' ') };
+  }
+  if (opts.json) return null;
+  if (opts.devScript && !/(^|[\s;&|])pyric\s+dev\b/.test(opts.devScript)) {
+    const label = `${opts.packageManager} run dev`;
+    return { argv: [opts.packageManager, 'run', 'dev'], label };
+  }
+  return null;
+}
+
+// ─── Environment for the child (pure) ──────────────────────────────────────
+
+/**
+ * The absolute `file:` URL of the register module, resolved from
+ * @pyric/cli' OWN installed location — `import.meta.resolve` walks this
+ * package's `exports` (self-reference), so it lands on the right file no
+ * matter how the user's node_modules are laid out (hoisted, pnpm-isolated,
+ * vendored). Fallback: relative to this compiled file (dist/cli/ →
+ * dist/register/), for runtimes without a usable import.meta.resolve.
+ */
+export function registerModuleUrl(): string {
+  try {
+    const url = import.meta.resolve('@pyric/cli/register');
+    if (typeof url === 'string' && url.length > 0) return url;
+  } catch {
+    // fall through
+  }
+  return new URL('../register/index.js', import.meta.url).href;
+}
+
+/**
+ * Child env: sets the activator and APPENDS the loader to NODE_OPTIONS —
+ * never replaces it (the user's own --inspect / --max-old-space-size etc.
+ * must survive). `file:` URLs are percent-encoded, so no quoting is needed
+ * even for paths with spaces.
+ */
+export function buildChildEnv(
+  base: NodeJS.ProcessEnv,
+  opts: { serveUrl: string; registerUrl: string },
+): NodeJS.ProcessEnv {
+  const importFlag = `--import ${opts.registerUrl}`;
+  return {
+    ...base,
+    PYRIC_SANDBOX: `remote:${opts.serveUrl}`,
+    NODE_OPTIONS: base.NODE_OPTIONS ? `${base.NODE_OPTIONS} ${importFlag}` : importFlag,
+  };
+}
+
+// ─── Line prefixing (pure core) ────────────────────────────────────────────
+
+/**
+ * Incremental line prefixer: every child output line gets `[dev] `, partial
+ * lines are buffered until their newline (or flush at stream end).
+ */
+export function createLinePrefixer(
+  prefix: string,
+  write: (line: string) => void,
+): { push(chunk: string): void; flush(): void } {
+  let buffer = '';
+  return {
+    push(chunk: string): void {
+      buffer += chunk;
+      let nl: number;
+      while ((nl = buffer.indexOf('\n')) !== -1) {
+        write(`${prefix}${buffer.slice(0, nl)}\n`);
+        buffer = buffer.slice(nl + 1);
+      }
+    },
+    flush(): void {
+      if (buffer.length > 0) {
+        write(`${prefix}${buffer}\n`);
+        buffer = '';
+      }
+    },
+  };
+}
+
+// ─── Spawn + lifecycle ─────────────────────────────────────────────────────
+
+export interface DevChildHandle {
+  /** Resolves with the exit code to propagate once the child is gone. */
+  exited: Promise<number>;
+  /** Forward a signal (Ctrl-C / SIGTERM). Marks the exit as user-initiated
+   *  so the propagated code is 0, and SIGKILLs a child that lingers. */
+  signal(sig: NodeJS.Signals): void;
+  child: ChildProcess;
+}
+
+/** How long a signalled child may linger before SIGKILL. */
+const FORCE_KILL_AFTER_MS = 2_000;
+
+/**
+ * Spawn the child with inherited stdin and `[dev]`-prefixed stdout/stderr.
+ * In `--json` mode ALL child output goes to stderr — stdout carries exactly
+ * the one machine line (the serve --json contract).
+ */
+export function spawnDevChild(
+  plan: DevChildPlan,
+  opts: { cwd: string; env: NodeJS.ProcessEnv; json: boolean },
+): DevChildHandle {
+  const [command, ...args] = plan.argv;
+  const child = spawn(command!, args, {
+    cwd: opts.cwd,
+    env: opts.env,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    // Own a process group so shutdown reaches package-manager grandchildren
+    // (for example `bun run dev` -> `node server.js`) rather than orphaning
+    // the actual dev server when only the runner exits.
+    detached: process.platform !== 'win32',
+  });
+
+  const outTarget = opts.json ? process.stderr : process.stdout;
+  const out = createLinePrefixer('[dev] ', (line) => outTarget.write(line));
+  const err = createLinePrefixer('[dev] ', (line) => process.stderr.write(line));
+  child.stdout?.setEncoding('utf8');
+  child.stderr?.setEncoding('utf8');
+  child.stdout?.on('data', (chunk: string) => out.push(chunk));
+  child.stderr?.on('data', (chunk: string) => err.push(chunk));
+
+  let signalled = false;
+  let forceTimer: ReturnType<typeof setTimeout> | null = null;
+  const killTree = (signal: NodeJS.Signals): void => {
+    if (process.platform !== 'win32' && child.pid !== undefined) {
+      process.kill(-child.pid, signal);
+    } else {
+      child.kill(signal);
+    }
+  };
+
+  const exited = new Promise<number>((resolve) => {
+    child.once('error', (e) => {
+      process.stderr.write(`pyric dev: failed to run \`${plan.label}\`: ${e.message}\n`);
+      resolve(1);
+    });
+    child.once('exit', (code, signal) => {
+      out.flush();
+      err.flush();
+      if (forceTimer) clearTimeout(forceTimer);
+      // User-initiated stop (Ctrl-C forwarded) is a clean shutdown → 0.
+      if (signalled) resolve(0);
+      else if (typeof code === 'number') resolve(code);
+      else resolve(signal ? 1 : 0);
+    });
+  });
+
+  return {
+    exited,
+    child,
+    signal(sig: NodeJS.Signals): void {
+      if (child.exitCode !== null || signalled) return;
+      signalled = true;
+      try {
+        killTree(sig);
+      } catch {
+        return;
+      }
+      forceTimer = setTimeout(() => {
+        try {
+          killTree('SIGKILL');
+        } catch {}
+      }, FORCE_KILL_AFTER_MS);
+      forceTimer.unref();
+    },
+  };
+}

package/src/cli/firebase-json.ts

@@ -0,0 +1,100 @@
+/**
+ * Minimal `firebase.json` / `.firebaserc` reader for the CLI.
+ *
+ * Surfaces only the fields the subcommands actually touch — the
+ * full firebase.json schema is huge and a full parse isn't needed
+ * for any current subcommand. New fields land alongside the
+ * subcommand that consumes them.
+ *
+ * `.firebaserc` carries the project id under `projects.default`;
+ * the standard Firebase CLI uses the same convention.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface FirebaseJson {
+  firestore?: {
+    rules?: string;
+    indexes?: string;
+    database?: string;
+  };
+  /** Realtime Database rules path plus optional explicit instance URL. */
+  database?: {
+    rules?: string;
+    url?: string;
+  };
+  hosting?: unknown;
+  functions?: unknown;
+  /** Storage rules + (optional) target bucket. A single object, or an array for
+   *  multi-bucket projects. `rules` is a path; `bucket` overrides the default
+   *  `{projectId}.firebasestorage.app`. */
+  storage?: { rules?: string; bucket?: string } | Array<{ rules?: string; bucket?: string }>;
+}
+
+export interface FirebaseRc {
+  projects?: {
+    default?: string;
+    [alias: string]: string | undefined;
+  };
+  /**
+   * Deploy-target maps, keyed project → resource type → target name →
+   * resource ids (mirrors firebase-tools' RCData,
+   * clones/firebase-tools/src/rc.ts:28-36). Only `hosting` (target →
+   * site ids) is consumed today.
+   */
+  targets?: {
+    [projectId: string]: {
+      [targetType: string]: {
+        [targetName: string]: string[] | undefined;
+      } | undefined;
+    } | undefined;
+  };
+}
+
+/**
+ * Read + parse `firebase.json` from `cwd`. Throws when missing — every
+ * subcommand that needs project metadata expects a present file.
+ */
+export async function readFirebaseJson(cwd: string = process.cwd()): Promise<FirebaseJson> {
+  const path = join(cwd, 'firebase.json');
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`pyric: no firebase.json found at ${path}. Run \`pyric init\` to scaffold one.`);
+    }
+    throw e;
+  }
+  try {
+    return JSON.parse(raw) as FirebaseJson;
+  } catch (e) {
+    throw new Error(
+      `pyric: failed to parse firebase.json: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}
+
+/**
+ * Read + parse `.firebaserc` from `cwd`. Returns null when missing —
+ * the project id can also come from `--project` / `PYRIC_PROJECT`, so
+ * absence is not fatal at this layer.
+ */
+export async function readFirebaseRc(cwd: string = process.cwd()): Promise<FirebaseRc | null> {
+  const path = join(cwd, '.firebaserc');
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw e;
+  }
+  try {
+    return JSON.parse(raw) as FirebaseRc;
+  } catch (e) {
+    throw new Error(
+      `pyric: failed to parse .firebaserc: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}