pyric-tools 0.1.0-alpha.7

package/dist/cli/serve.d.ts

@@ -0,0 +1,122 @@
+import type { ParsedArgs } from './parse-args.js';
+import { type FirebaseJson } from './firebase-json.js';
+import { type InitPayload } from '../serve/namespace.js';
+import { startStaticServer, type ServeHandle } from '../serve/server.js';
+interface HostingConfig {
+    public?: string;
+    rewrites?: Array<{
+        source?: string;
+        destination?: string;
+    }>;
+}
+/** Extract the single hosting config `pyric dev` v1 supports. Arrays
+ *  (multi-site) take the first entry with a warning — multi-site is out of
+ *  scope (plan section 6). */
+export declare function extractHosting(config: FirebaseJson | null): HostingConfig | null;
+/** firebase.json's SPA idiom: a `**` rewrite to /index.html. */
+export declare function wantsSpaRewrite(hosting: HostingConfig | null): boolean;
+export interface ServeRuntime {
+    handle: ServeHandle;
+    publicDir: string;
+    payload: () => InitPayload;
+    /** HTTP MCP endpoint when `--bridge` is on; null otherwise. */
+    mcpUrl: string | null;
+    /** The Studio app URL (`/__pyric/ui/`) when `--ui` is on and the build is
+     *  present; null otherwise. */
+    uiUrl: string | null;
+    /** Persistence summary (null when `--persist` is off). */
+    persist: {
+        restoredDocs: number;
+        restoredUsers: number;
+    } | null;
+}
+/** The `--json` stdout contract — one line, keep stable; agents parse this.
+ *  Readiness probe: GET {url}/__pyric/init.json → 200 (body carries the live
+ *  rules hash). */
+export declare function serveJsonLine(runtime: ServeRuntime): string;
+/**
+ * Programmatic entry — everything but flag parsing and process lifecycle.
+ * Exported so integration tests drive a real server without a subprocess.
+ */
+export declare function startServe(opts: {
+    cwd: string;
+    port?: number;
+    host?: string;
+    noCache?: boolean;
+    /** Override the bundle cache root (tests). */
+    cacheRoot?: string;
+    /** Mount the MCP bridge on the serve origin (`--bridge`). */
+    bridge?: boolean;
+    /** Project label for the bridge health/audit surfaces. */
+    project?: string;
+    /** Disable the bridge audit writer (tests). */
+    disableAuditLog?: boolean;
+    /** Path to a seed JSON file (path → fields map), applied at page init. */
+    seed?: string;
+    /** Watch firestore.rules and hot-reload over SSE. Default true when a
+     *  rules file exists. */
+    watch?: boolean;
+    /** Persist sandbox state to `.pyric/state/state.json` (flow doc section 3c).
+     *  Ephemeral remains the default. */
+    persist?: boolean;
+    /** With `--persist`: discard any existing state file and re-seed from
+     *  scratch (the escape hatch from "state wins after the first run"). */
+    fresh?: boolean;
+    /** Extra hostnames allowed past the DNS-rebinding guard. */
+    allowedHosts?: string[];
+    /** Write the session capture to `.pyric/last-session.json` so `pyric verify`
+     *  can replay it. Default true; pass false (via `--no-capture`) to suppress.
+     *  This is independent of `--persist` — capture records the live session
+     *  fixture for the verify loop regardless of whether state is persisted. */
+    capture?: boolean;
+    /** Mount the Pyric Studio storage routes (`--ui`): `/__pyric/workspace`
+     *  (the served project's file tree) + `/__pyric/projects` (single-project
+     *  store over `cwd`). The Studio app's `local` mode talks to these. */
+    ui?: boolean;
+    logger?: Parameters<typeof startStaticServer>[0]['logger'];
+}): Promise<ServeRuntime>;
+/**
+ * `--ui` implies `--bridge` (hybrid-MCP plan Phase 3): a Studio user almost
+ * always wants MCP too, and the two independent flags were a real setup footgun.
+ * Pure + exported for unit coverage.
+ */
+export declare function bridgeEnabledFromFlags(flags: {
+    get(key: string): unknown;
+}): boolean;
+/**
+ * A dev child also implies the bridge: the runner injects
+ * `PYRIC_SANDBOX=remote:<url>` into the child, whose remote client dials the
+ * `/__pyric/sandbox` WS — without the bridge mount that upgrade 404s and
+ * plain `pyric dev -- <cmd>` (or a detected dev script) breaks its own
+ * child. Pure + exported for unit coverage.
+ */
+export declare function bridgeEnabledFor(flags: {
+    get(key: string): unknown;
+}, childPlan: unknown): boolean;
+/**
+ * Process-level last line of defense for the dev server: a single bad
+ * request/WS interaction must never take `pyric dev` down. Node kills the
+ * process on an unhandled rejection (default `--unhandled-rejections=throw`
+ * since v15) and on any uncaught exception — and the serve process hosts
+ * long-lived, browser-driven machinery (WS peers, SSE streams, file watchers,
+ * MCP transports) where one missed error path is fatal. Route both to a LOUD
+ * stderr log instead and keep serving.
+ *
+ * Installed by `runServe` once the server is up (startup errors still fail
+ * fast). Returns the uninstaller. Exported for unit coverage.
+ */
+export declare function installServeProcessGuard(log: (message: string) => void, proc?: Pick<NodeJS.Process, 'on' | 'off'>): () => void;
+/** CLI entry. Resolves on SIGINT/SIGTERM after a clean stop. */
+export declare function runServe(parsed: ParsedArgs): Promise<number>;
+/**
+ * Detect a bundler build that INLINED the real firebase SDK into its served
+ * assets (`vite build` output). The served import map remaps only bare
+ * `firebase/*` specifiers, so such a build cannot be sandboxed — its calls
+ * reach real Google endpoints. Fingerprints are real-SDK-only endpoint hosts
+ * that never appear in a sandbox-clean app (whose calls all route to
+ * `/__pyric/*`). Bounded: depth ≤ 4, ≤ 200 script files, first hit per file.
+ * Returns publicDir-relative paths of offending assets.
+ */
+export declare function scanForInlinedFirebase(dir: string): string[];
+export {};
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/cli/serve.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYzE,OAAO,EAAyD,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIhH,OAAO,EAAsB,iBAAiB,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAchH,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED;;8BAE8B;AAC9B,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAKhF;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAItE;AAGD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,WAAW,CAAC;IAC3B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;mCAC+B;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0DAA0D;IAC1D,OAAO,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE;AAED;;mBAEmB;AACnB,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAY3D;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;6BACyB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;yCACqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;4EACwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;gFAG4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;2EAEuE;IACvE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC5D,GAAG,OAAO,CAAC,YAAY,CAAC,CAkZxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,OAAO,CAEpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACpC,SAAS,EAAE,OAAO,GACjB,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC9B,IAAI,GAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,GAAG,KAAK,CAAW,GACjD,MAAM,IAAI,CAqBZ;AAED,gEAAgE;AAChE,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4JlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA6C5D"}