@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/serve/site-tree.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { extname, join } from 'node:path';
+import {
+  contentTypeFor,
+  decodeStaticPathname,
+  pipeFileToResponse,
+  resolveStaticFile,
+  resolveStaticPath,
+} from './server.js';
+
+interface StudioRoutesManifest {
+  routes: string[];
+}
+
+interface RequestWithOriginalUrl extends IncomingMessage {
+  originalUrl?: string;
+}
+
+const SITE_TREE_MOUNT_PATH = '/__pyric/ui';
+const SITE_TREE_DESCENDANT_PREFIX = `${SITE_TREE_MOUNT_PATH}/`;
+
+function studioRoutesFromSite(root: string): ReadonlySet<string> {
+  const manifestPath = join(root, 'studio-routes.json');
+  const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as StudioRoutesManifest;
+  if (!Array.isArray(parsed.routes) || parsed.routes.some((route) => typeof route !== 'string')) {
+    throw new Error(`pyric: invalid Studio route manifest at ${manifestPath}`);
+  }
+  return new Set(parsed.routes);
+}
+
+function rawRequestPathname(request: RequestWithOriginalUrl, parsedUrl: URL): string {
+  let requestTarget = request.originalUrl;
+
+  if (requestTarget === undefined) {
+    requestTarget = request.url;
+  }
+
+  if (requestTarget === undefined) {
+    return parsedUrl.pathname;
+  }
+
+  const queryStringStart = requestTarget.indexOf('?');
+
+  if (queryStringStart === -1) {
+    return requestTarget;
+  }
+
+  return requestTarget.slice(0, queryStringStart);
+}
+
+function isSiteTreePath(pathname: string): boolean {
+  if (pathname === SITE_TREE_MOUNT_PATH) {
+    return true;
+  }
+
+  return pathname.startsWith(SITE_TREE_DESCENDANT_PREFIX);
+}
+
+function withWorkerVersion(html: string, workerVersion: string | undefined): string {
+  if (!workerVersion || html.includes('name="pyric-worker-v"')) return html;
+  if (!/^[a-f0-9]{16}$/.test(workerVersion)) {
+    throw new Error(`pyric: invalid SharedWorker epoch '${workerVersion}'`);
+  }
+  const meta = `<meta name="pyric-worker-v" content="${workerVersion}" data-pyric-serve>`;
+  const head = html.match(/<head[^>]*>/i);
+  if (!head || head.index === undefined) return meta + html;
+  const at = head.index + head[0].length;
+  return html.slice(0, at) + meta + html.slice(at);
+}
+
+/** Serve the one Astro tree with SPA fallback limited to generated Studio entries. */
+export function createSiteTreeHandler(root: string, workerVersion?: string) {
+  const studioRoutes = studioRoutesFromSite(root);
+
+  return (
+    req: RequestWithOriginalUrl,
+    res: ServerResponse,
+    url: URL,
+  ): boolean => {
+    // URL parsing normalizes encoded dot segments before `url.pathname`
+    // reaches us. Route and validate against the raw request target so an
+    // encoded traversal cannot cross from Studio into docs or static assets.
+    // Connect preserves that target in `originalUrl` after stripping a mount
+    // prefix from `url`.
+    const rawPathname = rawRequestPathname(req, url);
+    if (!isSiteTreePath(rawPathname)) {
+      return false;
+    }
+    if (rawPathname === SITE_TREE_MOUNT_PATH) {
+      res.writeHead(301, { location: SITE_TREE_DESCENDANT_PREFIX }).end();
+      return true;
+    }
+
+    let relativePath = rawPathname.slice(SITE_TREE_MOUNT_PATH.length);
+
+    if (relativePath === '') {
+      relativePath = '/';
+    }
+
+    const decodedRel = decodeStaticPathname(relativePath);
+    if (decodedRel === null || decodedRel.includes('\\')) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+    const decodedSegments = decodedRel.split('/').filter(Boolean);
+    if (decodedSegments.some((segment) => segment === '.' || segment === '..')) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+    if (!relativePath.endsWith('/') && !extname(relativePath)) {
+      const dir = resolveStaticPath(root, relativePath);
+      if (dir && existsSync(dir) && statSync(dir).isDirectory()) {
+        res.writeHead(301, { location: `${rawPathname}/` }).end();
+        return true;
+      }
+    }
+
+    const first = decodedSegments[0];
+    const studioRequest = first === undefined || studioRoutes.has(first);
+    let file = resolveStaticFile(root, relativePath);
+    // Storage object names commonly contain extensions (logo.png), while the
+    // other Studio routes reserve extension-bearing misses for static assets.
+    const allowsDottedState = first === 'storage';
+    const hasDottedStateSegment = decodedSegments
+      .slice(1)
+      .some((segment) => segment.includes('.'));
+    if (!file && studioRequest && (allowsDottedState || !hasDottedStateSegment)) {
+      const entry = first === undefined ? '/index.html' : `/${first}/index.html`;
+      file = resolveStaticFile(root, entry);
+    }
+    if (!file) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+
+    const contentType = contentTypeFor(file);
+    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' });
+    if (studioRequest && contentType.includes('text/html')) {
+      res.end(withWorkerVersion(readFileSync(file, 'utf8'), workerVersion));
+    } else {
+      pipeFileToResponse(file, res);
+    }
+    return true;
+  };
+}

package/src/serve/standalone-assets.ts

@@ -35,12 +35,8 @@ export interface EmbeddedAssets {
   workerVersion: string;
   /** Lazy: flat map of SDK filename -> base64 bytes (app.js, worker.js, chunks). */
   sdk: () => Promise<Record<string, string>>;
-  /** Lazy: Studio UI relpath (posix) -> base64 bytes (index.html, assets/*). */
-  studio: () => Promise<Record<string, string>>;
-  /** Lazy: docs site relpath (posix) -> base64 bytes (the site-docs `dist/`
-   *  tree: `docs/*`, `_astro/*`, `index.html`, `llms.txt`). Optional for older
-   *  compiled binaries; missing means the Studio Docs tab 404s in standalone. */
-  docs?: () => Promise<Record<string, string>>;
+  /** Lazy: unified Astro site relpath (posix) -> base64 bytes. */
+  site: () => Promise<Record<string, string>>;
   /** Lazy: packed npm tarballs of the unpublished workspace packages
    *  (`pyric.tgz`, `pyric-admin.tgz`, `create-pyric.tgz`, `pyric-cli.tgz`)
    *  -> base64. Used by `pyric init` / `pyric vendor` to vendor them into a
@@ -154,27 +150,14 @@ export async function materializeServeAssets(): Promise<{ outDir: string; cached
   return { outDir, cached };
 }
 
-let studioDirOnce: string | null = null;
+let siteDirOnce: string | null = null;
 
-/** Materialize the embedded Studio UI tree to a temp dir for `dev --ui`. */
-export async function materializeStudioUi(): Promise<string> {
-  if (studioDirOnce) return studioDirOnce;
+/** Materialize the embedded Astro documentation + Studio tree for `dev --ui`. */
+export async function materializeSiteUi(): Promise<string> {
+  if (siteDirOnce) return siteDirOnce;
   const e = embedded();
-  const dir = join(materializationRoot(e), 'studio-ui');
-  materialize(dir, await e.studio(), e.version);
-  studioDirOnce = dir;
-  return dir;
-}
-
-let docsDirOnce: string | null = null;
-
-/** Materialize the embedded docs site tree to a temp dir for `dev --ui`. */
-export async function materializeDocsUi(): Promise<string | null> {
-  if (docsDirOnce) return docsDirOnce;
-  const e = embedded();
-  if (!e.docs) return null;
-  const dir = join(materializationRoot(e), 'docs-ui');
-  materialize(dir, await e.docs(), e.version);
-  docsDirOnce = dir;
+  const dir = join(materializationRoot(e), 'site-ui');
+  materialize(dir, await e.site(), e.version);
+  siteDirOnce = dir;
   return dir;
 }

package/src/serve/vite-functions-development.ts

@@ -0,0 +1,201 @@
+import type { Server } from 'node:http';
+import path from 'node:path';
+import type { ViteDevServer } from 'vite';
+import type { FunctionsRtdbProject } from '../functions-rtdb/project.js';
+import {
+  createFunctionsDevelopmentRuntime,
+  createInProcessFunctionsPeerReadiness,
+  type FunctionsDevelopmentEvent,
+  type FunctionsDevelopmentResult,
+  type FunctionsDevelopmentRuntime,
+} from '../functions-rtdb/development-runtime.js';
+import type { BridgeMount } from './bridge-mount.js';
+
+export interface ViteFunctionsDevelopmentOptions {
+  cwd: string;
+  project: FunctionsRtdbProject;
+  projectId: string;
+  instance?: string;
+  region?: string;
+  watch?: boolean;
+  host: string;
+  httpServer: Server;
+  watcher: ViteDevServer['watcher'];
+  logger: ViteDevServer['config']['logger'];
+  bridge: BridgeMount;
+  baseEnv: NodeJS.ProcessEnv;
+  registerUrl: string;
+  childModuleUrl?: string | URL;
+  /** Internal test seam for the host adapter; production uses the shared runtime. */
+  runtimeFactory?: typeof createFunctionsDevelopmentRuntime;
+}
+
+export interface ViteFunctionsDevelopmentAttachment {
+  close(): Promise<void>;
+}
+
+function reportEvent(
+  logger: ViteFunctionsDevelopmentOptions['logger'],
+  event: FunctionsDevelopmentEvent,
+): void {
+  if (event.type === 'output') {
+    const line = event.line.replace(/\n$/, '');
+    if (event.stream === 'stdout') logger.info(line);
+    else logger.warn(line);
+    return;
+  }
+  if (event.type === 'unexpected-exit') {
+    logger.error(`  ✖ [pyric] Functions child exited unexpectedly (code ${event.code}).`);
+    return;
+  }
+  const childEvent = event.event;
+  if (childEvent.type === 'execution') {
+    const params = Object.entries(childEvent.params)
+      .map(([name, value]) => `${name}=${value}`)
+      .join(', ');
+    const suffix = params ? ` (${params})` : '';
+    if (childEvent.status === 'fulfilled') {
+      logger.info(`  ✔ [pyric] function ${childEvent.exportName} ← /${childEvent.ref}${suffix}`);
+    } else {
+      logger.error(
+        `  ✖ [pyric] function ${childEvent.exportName} ← /${childEvent.ref}${suffix}: ${childEvent.error.message}`,
+      );
+    }
+  } else {
+    logger.error(
+      `  ✖ [pyric] functions delivery for ${childEvent.exportName}: ${childEvent.error.message}`,
+    );
+  }
+}
+
+function reportResult(
+  options: ViteFunctionsDevelopmentOptions,
+  result: FunctionsDevelopmentResult,
+  mode: 'initial' | 'reload',
+  serveUrl: string,
+): void {
+  const { logger, project, cwd } = options;
+  if (result.kind === 'no-peer') {
+    logger.warn(
+      mode === 'reload'
+        ? `  ✖ [pyric] functions not restarted — no sandbox peer connected. ` +
+            `Functions stay down until the next save with ${serveUrl} open.`
+        : `  ⚠ [pyric] functions not started — no browser tab connected after 30s. ` +
+            `Open ${serveUrl} and restart the dev server.`,
+    );
+    return;
+  }
+  if (result.kind === 'failed') {
+    logger.error(
+      mode === 'reload'
+        ? `  ✖ [pyric] functions failed to reload: ${result.error.message}\n` +
+            `  ✖ [pyric] functions are down until the next good save.`
+        : `  ✖ [pyric] functions failed to start: ${result.error.message}`,
+    );
+    return;
+  }
+  const ready = result.ready;
+  logger.info(
+    mode === 'reload'
+      ? `  ↻ [pyric] functions reloaded (${ready.triggerCount} trigger${ready.triggerCount === 1 ? '' : 's'})`
+      : `  ✔ [pyric] functions ${ready.triggerCount} onValueCreated ` +
+          `trigger${ready.triggerCount === 1 ? '' : 's'} from ${path.relative(cwd, project.entry)}`,
+  );
+  for (const unsupported of ready.unsupportedTriggers) {
+    logger.warn(
+      `  ⚠ [pyric] functions export ${unsupported.exportName} uses unsupported trigger ` +
+        `${unsupported.eventType}; it will not run.`,
+    );
+  }
+}
+
+/** Own the Vite-only adaptation around the host-neutral Functions runtime. */
+export function attachViteFunctionsDevelopment(
+  options: ViteFunctionsDevelopmentOptions,
+): ViteFunctionsDevelopmentAttachment {
+  const {
+    httpServer,
+    watcher,
+    project,
+    bridge,
+    host,
+  } = options;
+  const runtimeFactory = options.runtimeFactory ?? createFunctionsDevelopmentRuntime;
+  let runtime: FunctionsDevelopmentRuntime | null = null;
+  let reloadDebounce: ReturnType<typeof setTimeout> | null = null;
+  let reportedReload: Promise<FunctionsDevelopmentResult> | null = null;
+  let closed = false;
+  let closePromise: Promise<void> | null = null;
+
+  const serveUrl = (): string | null => {
+    const address = httpServer.address();
+    const port = address && typeof address === 'object' ? address.port : 0;
+    return port > 0 ? `http://${host}:${port}` : null;
+  };
+
+  const onListening = (): void => {
+    const url = serveUrl();
+    if (!url || closed || runtime) return;
+    runtime = runtimeFactory({
+      sourceDir: project.sourceDir,
+      entry: project.entry,
+      baseEnv: options.baseEnv,
+      serveUrl: url,
+      registerUrl: options.registerUrl,
+      instance: options.instance ?? `${options.projectId}-default-rtdb`,
+      location: options.region ?? options.baseEnv.PYRIC_FUNCTIONS_RTDB_REGION ?? 'us-central1',
+      readiness: createInProcessFunctionsPeerReadiness(bridge.sandboxConnected),
+      onEvent: (event) => reportEvent(options.logger, event),
+      ...(options.childModuleUrl === undefined ? {} : { childModuleUrl: options.childModuleUrl }),
+    });
+    void runtime.start().then((result) => {
+      if (!closed) reportResult(options, result, 'initial', url);
+    });
+  };
+
+  const onFunctionsFsEvent = (file: string): void => {
+    const resolved = path.resolve(file);
+    const rel = path.relative(project.sourceDir, resolved);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return;
+    if (rel.split(path.sep).includes('node_modules')) return;
+    if (reloadDebounce) clearTimeout(reloadDebounce);
+    reloadDebounce = setTimeout(() => {
+      if (!runtime || closed) return;
+      const transition = runtime.reload();
+      if (reportedReload === transition) return;
+      reportedReload = transition;
+      void transition.then((result) => {
+        if (!closed) reportResult(options, result, 'reload', serveUrl() ?? `http://${host}:0`);
+      }).finally(() => {
+        if (reportedReload === transition) reportedReload = null;
+      });
+    }, 300);
+  };
+
+  if ((httpServer as unknown as { listening?: boolean }).listening) onListening();
+  else httpServer.once('listening', onListening);
+  if (options.watch !== false) {
+    watcher.add(project.sourceDir);
+    watcher.on('change', onFunctionsFsEvent);
+    watcher.on('add', onFunctionsFsEvent);
+    watcher.on('unlink', onFunctionsFsEvent);
+  }
+
+  return {
+    close(): Promise<void> {
+      if (closePromise) return closePromise;
+      closePromise = (async () => {
+        closed = true;
+        if (reloadDebounce) clearTimeout(reloadDebounce);
+        httpServer.removeListener('listening', onListening);
+        if (options.watch !== false) {
+          watcher.off('change', onFunctionsFsEvent);
+          watcher.off('add', onFunctionsFsEvent);
+          watcher.off('unlink', onFunctionsFsEvent);
+        }
+        await runtime?.close();
+      })();
+      return closePromise;
+    },
+  };
+}

package/src/serve/vite-generation-bridge.ts

@@ -0,0 +1,66 @@
+import type { Server as HttpServer } from 'node:http';
+import type { ViteDevServer } from 'vite';
+import type { FunctionsRtdbProject } from '../functions-rtdb/project.js';
+import type {
+  BridgeHostAttachment,
+  BridgeHostOptions,
+  BridgeMount,
+  BridgeMountOptions,
+} from './bridge-mount.js';
+
+function resolveAllowedHosts(allowedHosts: true | string[] | undefined): true | string[] {
+  if (allowedHosts === true) return true;
+  if (Array.isArray(allowedHosts)) return allowedHosts;
+  return [];
+}
+
+export function createViteGenerationBridge(input: {
+  server: ViteDevServer;
+  projectDir: string;
+  options: Omit<BridgeMountOptions, 'upgradeGuard'> | null;
+  functionsProject: FunctionsRtdbProject | null;
+  functionsProjectId: string | null;
+  createBridge(options: BridgeMountOptions): BridgeMount;
+}): BridgeMount | null {
+  const { server, options, functionsProject, functionsProjectId, createBridge } = input;
+  if (!options && !functionsProject) return null;
+  const serverOptions = server.config.server;
+  const project = options?.project ?? functionsProjectId ?? undefined;
+  const disableAuditLog = options?.disableAuditLog;
+  const boundHost = typeof serverOptions.host === 'string' ? serverOptions.host : 'localhost';
+  const allowedHosts = resolveAllowedHosts(serverOptions.allowedHosts);
+  const bridgeOptions: BridgeMountOptions = {
+    project,
+    disableAuditLog,
+    upgradeGuard: {
+      boundHost,
+      allowedHosts,
+    },
+  };
+  return createBridge(bridgeOptions);
+}
+
+export function attachViteGenerationBridge(input: {
+  server: ViteDevServer;
+  projectDir: string;
+  bridge: BridgeMount | null;
+}): BridgeHostAttachment | null {
+  const { server, projectDir, bridge } = input;
+  if (!bridge || !server.httpServer) return null;
+  const httpServer = server.httpServer as unknown as HttpServer;
+  const host =
+    (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
+  const origin = (): { host: string; port: number } | null => {
+    const address = httpServer.address();
+    const port = address && typeof address === 'object' ? address.port : 0;
+    return port > 0 ? { host, port } : null;
+  };
+  const hostOptions: BridgeHostOptions = {
+    servers: [httpServer],
+    projectDir,
+    origin,
+    collision: server.config.logger,
+    closeOnServerClose: false,
+  };
+  return bridge.attachHost(hostOptions);
+}

package/src/serve/vite-generation-functions.ts

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import type { Server as HttpServer } from 'node:http';
+import path from 'node:path';
+import type { ViteDevServer } from 'vite';
+import type { FirebaseRc } from '../cli/firebase-json.js';
+import type {
+  FunctionsRtdbProject,
+} from '../functions-rtdb/project.js';
+import type { BridgeMount } from './bridge-mount.js';
+import type {
+  ViteFunctionsDevelopmentAttachment,
+  ViteFunctionsDevelopmentOptions,
+} from './vite-functions-development.js';
+
+export interface ResolvedViteGenerationFunctions {
+  options: { region?: string; instance?: string; watch?: boolean };
+  project: FunctionsRtdbProject | null;
+  projectId: string | null;
+}
+
+export async function resolveViteGenerationFunctions(input: {
+  projectDir: string;
+  options: false | { region?: string; instance?: string; watch?: boolean };
+  discover(projectDir: string): FunctionsRtdbProject | null;
+  readFirebaseRc(projectDir: string): Promise<FirebaseRc | null>;
+}): Promise<ResolvedViteGenerationFunctions> {
+  const { projectDir, options, discover, readFirebaseRc } = input;
+  const project = options === false ? null : discover(projectDir);
+  let projectId: string | null = null;
+  if (project) {
+    projectId =
+      process.env.PYRIC_PROJECT ??
+      (await readFirebaseRc(projectDir))?.projects?.default ??
+      'demo-project';
+  }
+  return {
+    options: typeof options === 'object' ? options : {},
+    project,
+    projectId,
+  };
+}
+
+export function attachViteGenerationFunctions(input: {
+  server: ViteDevServer;
+  projectDir: string;
+  cliRoot: string;
+  bridge: BridgeMount | null;
+  resolved: ResolvedViteGenerationFunctions;
+  registerModuleUrl(): string;
+  fileExists?: (path: string) => boolean;
+  attach(options: ViteFunctionsDevelopmentOptions): ViteFunctionsDevelopmentAttachment;
+}): ViteFunctionsDevelopmentAttachment | null {
+  const { server, projectDir, cliRoot, bridge, resolved, registerModuleUrl, attach } = input;
+  if (!resolved.project || !resolved.projectId || !bridge || !server.httpServer) return null;
+  const builtChild = path.join(cliRoot, 'dist/functions-rtdb/child.js');
+  const fileExists = input.fileExists ?? existsSync;
+  const childModuleUrl = fileExists(builtChild) ? builtChild : undefined;
+  const host =
+    (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
+  const registerUrl = registerModuleUrl();
+  const attachmentOptions: ViteFunctionsDevelopmentOptions = {
+    cwd: projectDir,
+    project: resolved.project,
+    projectId: resolved.projectId,
+    instance: resolved.options.instance,
+    region: resolved.options.region,
+    watch: resolved.options.watch,
+    host,
+    httpServer: server.httpServer as unknown as HttpServer,
+    watcher: server.watcher,
+    logger: server.config.logger,
+    bridge,
+    baseEnv: process.env,
+    registerUrl,
+    childModuleUrl,
+  };
+  return attach(attachmentOptions);
+}

package/src/serve/vite-generation-middleware.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ViteDevServer } from 'vite';
+import type { BridgeMount } from './bridge-mount.js';
+import type { SandboxSession } from './sandbox-session.js';
+import { isAllowedHost } from './server.js';
+
+/** Attach one generation's guarded namespace handler to Vite's permanent Connect stack. */
+export function attachViteGenerationMiddleware(input: {
+  server: ViteDevServer;
+  bridge: BridgeMount | null;
+  session: SandboxSession;
+}): () => void {
+  const { server, bridge, session } = input;
+  const serverOptions = server.config.server;
+  let active = true;
+
+  server.middlewares.use(
+    '/__pyric',
+    (req: IncomingMessage & { originalUrl?: string }, res: ServerResponse, next: () => void) => {
+      if (!active) {
+        next();
+        return;
+      }
+      const allowed = serverOptions.allowedHosts === true || isAllowedHost(
+        req.headers.host,
+        typeof serverOptions.host === 'string' ? serverOptions.host : 'localhost',
+        Array.isArray(serverOptions.allowedHosts) ? serverOptions.allowedHosts : [],
+      );
+      if (!allowed) {
+        res.statusCode = 403;
+        res.end(`pyric: refused request for Host '${req.headers.host ?? ''}' (DNS-rebinding guard).`);
+        return;
+      }
+      const url = new URL(
+        req.originalUrl ?? req.url ?? '/',
+        `http://${req.headers.host ?? 'localhost'}`,
+      );
+      let bridgeResult: boolean | Promise<boolean> = false;
+      if (bridge) bridgeResult = bridge.handler(req, res, url);
+      Promise.resolve(bridgeResult)
+        .then((bridged) => {
+          if (bridged) return true;
+          return session.handle(req, res, url);
+        })
+        .then((handled) => {
+          if (!handled) next();
+        })
+        .catch((error: unknown) => {
+          if (!res.headersSent) res.statusCode = 500;
+          res.end(error instanceof Error ? error.message : String(error));
+        });
+    },
+  );
+
+  return () => { active = false; };
+}

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

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import type { ViteDevServer } from 'vite';
+import type { SandboxSession } from './sandbox-session.js';
+
+/** Adapt Vite's watcher to the session's last-good Firestore-rules reload operation. */
+export function watchViteGenerationRules(input: {
+  server: ViteDevServer;
+  session: SandboxSession;
+}): (() => void) | null {
+  const { server, session } = input;
+  const rulesFile = session.summary.rules.firestore.sourcePath;
+  if (!rulesFile) return null;
+
+  let debounce: ReturnType<typeof setTimeout> | null = null;
+  const onRulesChange = (file: string): void => {
+    if (path.resolve(file) !== path.resolve(rulesFile)) return;
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      void session.reloadFirestoreRules().then((result) => {
+        if (result.kind === 'reloaded') {
+          server.config.logger.info(`  ↻ [pyric] rules reloaded (${result.rulesHash})`);
+        } else if (result.kind === 'rejected') {
+          server.config.logger.warn(
+            `  ⚠ [pyric] rules NOT reloaded (last-good stays live): ${result.error.message}`,
+          );
+        }
+      });
+    }, 150);
+  };
+
+  server.watcher.add(rulesFile);
+  server.watcher.on('change', onRulesChange);
+  return () => {
+    if (debounce) clearTimeout(debounce);
+    server.watcher.off('change', onRulesChange);
+  };
+}