pyric-tools 0.1.0-alpha.7

package/dist/serve/rules.js

@@ -0,0 +1,139 @@
+/**
+ * `pyric dev` rules wiring — load the project's `firestore.rules`, make it
+ * executable for the in-page sandbox, and fail FAST at startup on broken
+ * rules (a clear CLI error beats a silently rule-less page).
+ *
+ * `2+modules` sources are resolved node-side (`resolveModulesBrowser` — pure,
+ * stdlib inlined, no disk reads) before embedding, so the page runtime only
+ * ever sees plain-v2 source the in-browser evaluator understands. This is the
+ * same lesson the playground's write_file learned (a capable model authored
+ * correct modular rules that scored 0/5 unresolved — auth-sdk work, PR #525).
+ */
+import { createHash } from 'node:crypto';
+import { watch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { lintFirestoreRules, resolveModulesBrowser } from 'pyric/rules';
+import { parseRtdbRulesJson } from '../rtdb/rules-json.js';
+export function rulesHashOf(source) {
+    return createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+/**
+ * Resolve + lint a raw rules source into sandbox-ready plain v2.
+ * Throws with an actionable message on unresolvable imports or lint errors.
+ */
+export function prepareRulesSource(raw, sourcePath) {
+    let source = raw;
+    if (/^\s*rules_version\s*=\s*['"]2\+modules['"]/m.test(raw)) {
+        const resolved = resolveModulesBrowser(raw);
+        if (!resolved.success) {
+            throw new Error(`pyric dev: ${sourcePath} uses 2+modules but module resolution failed: ${resolved.error.message}`);
+        }
+        source = resolved.data.resolved;
+    }
+    const lint = lintFirestoreRules(source);
+    if (lint.parseError) {
+        const { line, column } = lint.parseError;
+        throw new Error(`pyric dev: ${sourcePath} failed to parse (line ${line}, col ${column}) — fix the rules before serving.`);
+    }
+    const errors = lint.warnings.filter((w) => w.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`pyric dev: ${sourcePath} has ${errors.length} rules error(s):\n` +
+            errors.map((e) => `  - ${e.message}`).join('\n'));
+    }
+    return source;
+}
+/**
+ * Load the project rules per `firebase.json` (`firestore.rules` path,
+ * defaulting to `firestore.rules` in cwd when the key is absent but the file
+ * exists). Missing file with no explicit config → `{ rules: null }` (serving
+ * without rules is fine; the runtime logs it). Missing file that IS
+ * explicitly configured → throw (the project says it should exist).
+ */
+export async function loadProjectRules(cwd, config) {
+    const configured = config?.firestore?.rules;
+    const rel = configured ?? 'firestore.rules';
+    const path = isAbsolute(rel) ? rel : join(cwd, rel);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            if (configured) {
+                throw new Error(`pyric dev: firebase.json points firestore.rules at ${path}, but it does not exist.`);
+            }
+            return { rules: null, rulesHash: null, sourcePath: null };
+        }
+        throw e;
+    }
+    const rules = prepareRulesSource(raw, path);
+    return { rules, rulesHash: rulesHashOf(rules), sourcePath: path };
+}
+export async function loadProjectDatabaseRules(cwd, config) {
+    const configured = config?.database?.rules;
+    if (!configured) {
+        return {
+            rules: null,
+            rulesHash: null,
+            sourcePath: null,
+            databaseUrl: config?.database?.url ?? null,
+        };
+    }
+    const path = isAbsolute(configured) ? configured : join(cwd, configured);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            throw new Error(`pyric dev: firebase.json points database.rules at ${path}, but it does not exist.`);
+        }
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`pyric dev: ${path} failed to parse as RTDB rules JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const rules = parseRtdbRulesJson(parsed, () => new Error(`pyric dev: ${path} must contain a top-level "rules" object.`));
+    return {
+        rules,
+        rulesHash: rulesHashOf(raw),
+        sourcePath: path,
+        databaseUrl: config?.database?.url ?? null,
+    };
+}
+/**
+ * Watch the rules file and invoke `onChange` with freshly prepared
+ * (resolved + linted) source. Broken intermediate saves are LOGGED and
+ * skipped — the last-good ruleset stays live (the write_file lesson:
+ * never replace a working ruleset with un-evaluatable source).
+ * Debounced; returns the watcher for shutdown.
+ */
+export function watchProjectRules(sourcePath, onChange, onError, debounceMs = 150) {
+    let timer = null;
+    const watcher = watch(sourcePath, () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            void readFile(sourcePath, 'utf8').then((raw) => {
+                try {
+                    const rules = prepareRulesSource(raw, sourcePath);
+                    onChange({ rules, rulesHash: rulesHashOf(rules) });
+                }
+                catch (e) {
+                    onError(e instanceof Error ? e.message : String(e));
+                }
+            }, (e) => onError(e instanceof Error ? e.message : String(e)));
+        }, debounceMs);
+    });
+    // An FSWatcher with no 'error' listener throws at the event-loop level on
+    // watcher failure (EMFILE, the watched file renamed away on some platforms)
+    // and would kill the serve process. Degrade to "no hot reload" instead.
+    watcher.on('error', (e) => onError(`rules watcher failed (hot reload off): ${e instanceof Error ? e.message : String(e)}`));
+    return watcher;
+}
+//# sourceMappingURL=rules.js.map

package/dist/serve/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/serve/rules.ts"],"names":[],"mappings":"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"}

package/dist/serve/sandbox-marker.d.ts

@@ -0,0 +1,9 @@
+/** The attribute stamped into a sandbox build's `index.html` head. Presence in
+ *  an asset's text is the signal — the value is fixed, never parsed. */
+export declare const SANDBOX_BUILD_MARKER = "data-pyric-sandbox-build";
+/** The full `<meta>` tag the plugin injects at the start of `<head>`. */
+export declare const SANDBOX_BUILD_META = "<meta name=\"pyric-sandbox-build\" content=\"1\" data-pyric-sandbox-build>";
+/** True when `dir`'s `index.html` carries the sandbox-build marker. Missing or
+ *  unreadable index → false (treated as an ordinary build). */
+export declare function hasSandboxBuildMarker(dir: string): boolean;
+//# sourceMappingURL=sandbox-marker.d.ts.map

package/dist/serve/sandbox-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-marker.d.ts","sourceRoot":"","sources":["../../src/serve/sandbox-marker.ts"],"names":[],"mappings":"AAcA;wEACwE;AACxE,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,+EAA0E,CAAC;AAE1G;+DAC+D;AAC/D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ1D"}

package/dist/serve/sandbox-marker.js

@@ -0,0 +1,32 @@
+/**
+ * The sandbox-build marker — the single source of truth shared by the three
+ * places that produce or read it: the Vite plugin stamps it into a
+ * `vite build --mode pyric` output's `index.html`; `pyric dev` trusts it (a
+ * marked dist bundles pyric's in-page adapters, so its assets never inline the
+ * real SDK — the inlined-firebase scanner is skipped); and `pyric deploy
+ * hosting` REFUSES it (a sandbox build must never reach production).
+ *
+ * Dependency-free (fs/path only) so the deploy provider can import it without
+ * pulling in the browser bundler.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The attribute stamped into a sandbox build's `index.html` head. Presence in
+ *  an asset's text is the signal — the value is fixed, never parsed. */
+export const SANDBOX_BUILD_MARKER = 'data-pyric-sandbox-build';
+/** The full `<meta>` tag the plugin injects at the start of `<head>`. */
+export const SANDBOX_BUILD_META = `<meta name="pyric-sandbox-build" content="1" ${SANDBOX_BUILD_MARKER}>`;
+/** True when `dir`'s `index.html` carries the sandbox-build marker. Missing or
+ *  unreadable index → false (treated as an ordinary build). */
+export function hasSandboxBuildMarker(dir) {
+    const index = join(dir, 'index.html');
+    if (!existsSync(index))
+        return false;
+    try {
+        return readFileSync(index, 'utf8').includes(SANDBOX_BUILD_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sandbox-marker.js.map

package/dist/serve/sandbox-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-marker.js","sourceRoot":"","sources":["../../src/serve/sandbox-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;wEACwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG,gDAAgD,oBAAoB,GAAG,CAAC;AAE1G;+DAC+D;AAC/D,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/serve/server.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `pyric dev` static server — the hosting half of the command.
+ *
+ * Bare `node:http` (house style — the bridge does the same; no superstatic
+ * dependency). Serves `hosting.public` from `firebase.json` with the minimal
+ * rewrite the local-dev case needs (`** → /index.html` SPA fallback when
+ * configured), and exposes two seams the `/__pyric/` namespace plugs into
+ * (`namespaceHandler`) and the import-map injection uses (`transformHtml`).
+ *
+ * UX parity targets: the `=== Serving from` banner, the labeled `Local server:`
+ * line, port 3473 default ("FIRE" on a phone keypad) with scan-forward on conflict, and SIGINT →
+ * `Shutting down...`.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+export interface ServeLogger {
+    /** User-facing lines (banner, URLs) → stdout. */
+    info(message: string): void;
+    /** Lifecycle/diagnostics (requests, warnings) → stderr. */
+    note(message: string): void;
+}
+export declare function consoleServeLogger(): ServeLogger;
+export declare function silentServeLogger(): ServeLogger;
+/** `--json` mode: the whole human banner moves to stderr so stdout carries
+ *  exactly one machine-readable line (the agent contract). */
+export declare function stderrServeLogger(): ServeLogger;
+export interface StaticServerOptions {
+    /** Directory to serve. Caller resolves it from firebase.json (or cwd). */
+    publicDir: string;
+    port?: number;
+    host?: string;
+    /** SPA fallback: unmatched extension-less GETs serve /index.html. */
+    spaRewrite?: boolean;
+    /** Handles reserved routes (the `/__pyric/` namespace). Return true when
+     *  the request was handled. */
+    namespaceHandler?: (req: IncomingMessage, res: ServerResponse, url: URL) => boolean | Promise<boolean>;
+    /** Applied to every served `.html` body (import-map/init injection). */
+    transformHtml?: (html: string) => string;
+    logger?: ServeLogger;
+    /** How many sequential ports to try past `port` on EADDRINUSE/EACCES. */
+    portScanLimit?: number;
+    /** Extra hostnames allowed past the DNS-rebinding guard (besides
+     *  localhost/127.0.0.1/[::1]/the bound host). `--allowed-host`. */
+    allowedHosts?: string[];
+}
+/**
+ * DNS-rebinding guard. A dev server bound to localhost is reachable by any
+ * webpage whose hostname resolves to 127.0.0.1 (`attacker.com` → A
+ * 127.0.0.1): the victim's browser then treats `http://attacker.com:PORT`
+ * as same-origin to the attacker's page and can read/write our endpoints —
+ * including `/__pyric/state` (auth users + plaintext passwords, and writes).
+ * Vite addresses the same class with `server.allowedHosts`.
+ *
+ * We accept only loopback hostnames + the host the server was bound to +
+ * any `--allowed-host`. A request with NO Host header is allowed (curl /
+ * same-origin fetches omit nothing in practice, but non-browser clients may;
+ * the attack requires a browser sending the attacker's Host).
+ */
+export declare function isAllowedHost(hostHeader: string | undefined, boundHost: string, extra?: string[]): boolean;
+/**
+ * Origin allowlist for WebSocket `upgrade` handshakes. A browser sends an
+ * `Origin` header on WS handshakes carrying the page's origin; a hostile page
+ * that opens a WS to our loopback bridge sends ITS OWN cross-origin Origin,
+ * which we reject — otherwise the page hijacks the agent tool channel
+ * (`registerSandboxPeer` last-wins). We reuse `isAllowedHost`'s allow rule on
+ * the Origin's hostname (loopback names + bound host + `--allowed-host`).
+ *
+ * A missing `Origin` is allowed: the same-origin/non-browser peer (a CLI ws
+ * client, a test) is not the hijack vector, which requires a browser attaching
+ * the attacker's Origin. A malformed Origin is rejected.
+ */
+export declare function isAllowedOrigin(originHeader: string | undefined, boundHost: string, extra?: string[]): boolean;
+/**
+ * The combined guard for a WS `upgrade` request: BOTH the `Host` header
+ * (DNS-rebinding) AND the `Origin` header (cross-origin hijack) must pass.
+ * `upgrade` is a separate listener from the HTTP `request` event, so the
+ * static server's request-time `isAllowedHost` never runs on it — every
+ * upgrade mount point must call this before `wss.handleUpgrade`.
+ */
+export declare function isAllowedUpgrade(headers: {
+    host?: string;
+    origin?: string;
+}, boundHost: string, extra?: string[]): boolean;
+export interface ServeHandle {
+    port: number;
+    host: string;
+    url: string;
+    /** The primary bound server. For the default `localhost` host this is the
+     *  IPv4 (127.0.0.1) listener; see `servers` for all of them. */
+    server: Server;
+    /** Every bound server. For `localhost` the server binds BOTH loopback
+     *  families (127.0.0.1 + ::1) so any client reaches it; callers that wire a
+     *  WS upgrade (the bridge) must attach to each. One entry for an explicit host. */
+    servers: Server[];
+    stop(): Promise<void>;
+}
+export declare function contentTypeFor(path: string): string;
+/** Resolve a request path inside `publicDir`, refusing traversal. Returns
+ *  null when the path escapes the root or doesn't exist as a file. */
+export declare function resolveStaticFile(publicDir: string, pathname: string): string | null;
+/**
+ * Stream a file to a response with the read stream's `'error'` event handled.
+ * A bare `createReadStream(file).pipe(res)` leaves the stream's error event
+ * unhandled — an fs error between the exists-check and the read (file swapped
+ * out, EMFILE under fd pressure, EISDIR race) then throws at the event-loop
+ * level and KILLS the whole serve process. Headers are usually already sent
+ * when the stream errors, so the recovery is: log, destroy the response (the
+ * client sees a truncated body), keep the server alive.
+ */
+export declare function pipeFileToResponse(file: string, res: ServerResponse, onError?: (err: Error) => void): void;
+/** The subset of `Server` the scan logic needs — injectable for tests
+ *  (bun's sockets allow same-port rebinds on macOS, so real-socket conflict
+ *  tests are runtime-dependent; node, the npx production runtime, raises
+ *  EADDRINUSE as expected). */
+export interface ListenableLike {
+    listen(port: number, host: string, cb: () => void): unknown;
+    once(event: 'error', cb: (err: NodeJS.ErrnoException) => void): unknown;
+    removeListener(event: 'error', cb: (err: NodeJS.ErrnoException) => void): unknown;
+    address(): {
+        port: number;
+    } | string | null;
+}
+/** Listen, scanning forward from `port` on conflict (default 3473 avoids macOS AirPlay, which squats 5000 on
+ *  macOS). Resolves with the bound port. */
+export declare function listenWithScan(server: ListenableLike, host: string, port: number, limit: number, logger: ServeLogger): Promise<number>;
+/**
+ * Loopback families to bind for `host`. The default `localhost` binds BOTH
+ * 127.0.0.1 (IPv4) and ::1 (IPv6) so a client using either reaches the server:
+ * `localhost` resolves to only ONE family, so the other 404s at the socket (the
+ * IPv4/IPv6 loopback trap). An explicit host binds only itself. Loopback
+ * families only — NEVER all-interfaces — so the sandbox stays off the LAN behind
+ * the DNS-rebinding guard.
+ */
+export declare function loopbackHosts(host: string): string[];
+export declare function startStaticServer(opts: StaticServerOptions): Promise<ServeHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/serve/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/serve/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAKjG,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wBAAgB,kBAAkB,IAAI,WAAW,CAKhD;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED;8DAC8D;AAC9D,wBAAgB,iBAAiB,IAAI,WAAW,CAK/C;AAED,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;mCAC+B;IAC/B,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvG,wEAAwE;IACxE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;uEACmE;IACnE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAM,EAAO,GACnB,OAAO,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAM,EAAO,GACnB,OAAO,CAST;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAM,EAAO,GACnB,OAAO,CAKT;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;oEACgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;uFAEmF;IACnF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAuBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;sEACsE;AACtE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAC7B,IAAI,CAoBN;AA0ED;;;+BAG+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC;IACxE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC;IAClF,OAAO,IAAI;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;4CAC4C;AAC5C,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpD;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CA2EvF"}