@fuzdev/fuz_app 0.135.0 → 0.137.0

package/dist/testing/schema_introspect.d.ts

@@ -21,10 +21,14 @@ import './assert_dev_env.js';
  * Index and constraint definitions are compared as the engine renders them,
  * so both sides of a parity comparison need engines that render alike. pglet
  * leaves an index's modifiers out of `pg_indexes.indexdef` — per-key sort
- * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — so a
- * pglet snapshot diffed against a PostgreSQL one reports every index that
- * uses one, with identical DDL on both sides. Take both snapshots on
- * PostgreSQL.
+ * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — and
+ * that misleads a comparison in both directions: a pglet snapshot diffed
+ * against a PostgreSQL one reports every index that uses a modifier, with
+ * identical DDL on both sides (a false difference), and two pglet snapshots
+ * agree when the two schemas differ only in a modifier (a false agreement).
+ * So `query_schema_snapshot` throws on pglet when the snapshot holds an
+ * index, unless the caller passes `accept_pglet_index_definitions`. Take both
+ * snapshots of a parity comparison on PostgreSQL.
  *
  * Paired with `testing/schema_parity.ts` for comparison + assertion helpers.
  *
@@ -170,6 +174,17 @@ export interface QuerySchemaSnapshotOptions {
      * consumer's domain schema.
      */
     readonly exclude_tables?: ReadonlyArray<string>;
+    /**
+     * Take the snapshot on pglet even though it holds indexes. Default `false`:
+     * pglet's `pg_indexes.indexdef` omits index modifiers (sort direction,
+     * `NULLS` placement, operator classes, `NULLS NOT DISTINCT`), so the
+     * snapshot's index definitions cannot be compared with another engine's,
+     * and do not tell two pglet schemas apart when they differ only in a
+     * modifier. Pass `true` only where no index definition is compared —
+     * reading tables, columns, constraints, sequences or enums off the
+     * snapshot. No effect on PostgreSQL or PGlite.
+     */
+    readonly accept_pglet_index_definitions?: boolean;
 }
 /**
  * Introspect a live database into a deterministic `SchemaSnapshot`.
@@ -180,6 +195,11 @@ export interface QuerySchemaSnapshotOptions {
  * The `schema_version` migration tracker never appears in the `tables`
  * field — it's framework bookkeeping created by the migration runner,
  * identical across consumers, and would only add noise.
+ *
+ * @param db - the database to introspect
+ * @param options - schema, table excludes, and the pglet opt-in
+ * @returns the snapshot, every collection sorted
+ * @throws Error on pglet when the snapshot holds an index and `accept_pglet_index_definitions` is not set — its index definitions omit modifiers, so a comparison built on them is wrong in both directions
  */
 export declare const query_schema_snapshot: (db: Db, options?: QuerySchemaSnapshotOptions) => Promise<SchemaSnapshot>;
 //# sourceMappingURL=schema_introspect.d.ts.map

package/dist/testing/schema_introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema_introspect.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_introspect.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;iBAWzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAOxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,gBAAgB;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAOzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,gBAAgB,CAa9E,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AA8DD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GACjC,IAAI,EAAE,EACN,UAAS,0BAA+B,KACtC,OAAO,CAAC,cAAc,CAyHxB,CAAC"}
+{"version":3,"file":"schema_introspect.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_introspect.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;iBAWzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAOxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,gBAAgB;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAOzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,gBAAgB,CAa9E,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD;;;;;;;;;OASG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAClD;AAiED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GACjC,IAAI,EAAE,EACN,UAAS,0BAA+B,KACtC,OAAO,CAAC,cAAc,CA0IxB,CAAC"}

package/dist/testing/schema_introspect.js

@@ -21,10 +21,14 @@ import './assert_dev_env.js';
  * Index and constraint definitions are compared as the engine renders them,
  * so both sides of a parity comparison need engines that render alike. pglet
  * leaves an index's modifiers out of `pg_indexes.indexdef` — per-key sort
- * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — so a
- * pglet snapshot diffed against a PostgreSQL one reports every index that
- * uses one, with identical DDL on both sides. Take both snapshots on
- * PostgreSQL.
+ * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — and
+ * that misleads a comparison in both directions: a pglet snapshot diffed
+ * against a PostgreSQL one reports every index that uses a modifier, with
+ * identical DDL on both sides (a false difference), and two pglet snapshots
+ * agree when the two schemas differ only in a modifier (a false agreement).
+ * So `query_schema_snapshot` throws on pglet when the snapshot holds an
+ * index, unless the caller passes `accept_pglet_index_definitions`. Take both
+ * snapshots of a parity comparison on PostgreSQL.
  *
  * Paired with `testing/schema_parity.ts` for comparison + assertion helpers.
  *
@@ -136,6 +140,8 @@ export const query_migration_tracker = async (db) => {
         }))
     };
 };
+/** The marker pglet's `version()` carries. */
+const PGLET_VERSION_MARKER = '(pglet)';
 const sort_keys = (record) => {
     const sorted = {};
     for (const key of Object.keys(record).sort()) {
@@ -170,6 +176,11 @@ const contype_to_kind = (contype) => {
  * The `schema_version` migration tracker never appears in the `tables`
  * field — it's framework bookkeeping created by the migration runner,
  * identical across consumers, and would only add noise.
+ *
+ * @param db - the database to introspect
+ * @param options - schema, table excludes, and the pglet opt-in
+ * @returns the snapshot, every collection sorted
+ * @throws Error on pglet when the snapshot holds an index and `accept_pglet_index_definitions` is not set — its index definitions omit modifiers, so a comparison built on them is wrong in both directions
  */
 export const query_schema_snapshot = async (db, options = {}) => {
     const schema = options.schema ?? 'public';
@@ -260,6 +271,18 @@ export const query_schema_snapshot = async (db, options = {}) => {
     for (const row of enum_rows) {
         (enums[row.enum_name] ??= { labels: [] }).labels.push(row.label);
     }
+    if (!options.accept_pglet_index_definitions &&
+        Object.values(tables).some((table) => table.indexes.length > 0)) {
+        const [version_row] = await db.query(`SELECT version() AS version`);
+        if (version_row?.version.includes(PGLET_VERSION_MARKER)) {
+            throw new Error('query_schema_snapshot: this database is pglet, whose pg_indexes.indexdef omits index ' +
+                'modifiers (sort direction, NULLS placement, operator classes, NULLS NOT DISTINCT), so ' +
+                "the snapshot's index definitions report false differences against PostgreSQL and false " +
+                'agreement between two pglet schemas. Take the snapshot on PostgreSQL (a TS backend ' +
+                'config defaults to memory://, which is pglet), or pass ' +
+                '{accept_pglet_index_definitions: true} when no index definition is compared.');
+        }
+    }
     return {
         tables: sort_keys(tables),
         sequences: sort_keys(sequences),

package/dist/testing/transports/raw_http.d.ts

@@ -0,0 +1,78 @@
+import '../assert_dev_env.js';
+/** What a raw exchange read back, and how it ended. */
+export interface RawHttpExchange {
+    /** Every byte the server sent, `latin1`-decoded. */
+    readonly received: string;
+    /**
+     * `true` when the connection ended before the exchange stopped reading —
+     * the server closed it, or it never opened (a refused or unresolvable
+     * address reads as closed, with nothing received).
+     */
+    readonly closed_by_server: boolean;
+}
+/** Options for `raw_http_exchange`. */
+export interface RawHttpExchangeOptions {
+    /** How long to read before giving up on the server. */
+    readonly read_timeout_ms: number;
+    /**
+     * When the exchange stops reading. `'close'` reads until the server closes
+     * the connection; `'response'` stops as soon as one whole response has
+     * arrived (`raw_http_parse_response`), for a server that answers and then
+     * keeps the connection open. Either way the read timeout bounds it.
+     *
+     * `'response'` stops at the first response the bytes frame, so it is for a
+     * final response carrying `Content-Length` or chunked framing: a `1xx`
+     * interim response ends the read, and so does the head of a response
+     * delimited by the connection closing, before its body.
+     *
+     * @default 'close'
+     */
+    readonly until?: 'close' | 'response';
+}
+/** One parsed HTTP/1.1 response. */
+export interface RawHttpResponse {
+    readonly status: number;
+    /** Response headers, names lowercased; a repeated name keeps its last value. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The response body, with any chunked framing removed. */
+    readonly body: string;
+}
+/**
+ * Open a raw TCP socket to `base_url`, write `request_bytes` once, and collect
+ * what the server sends back until it closes the connection, a whole response
+ * has arrived (`until: 'response'`), or `read_timeout_ms` elapses.
+ *
+ * Write errors are swallowed: a server that refuses a request and closes
+ * mid-upload surfaces as `EPIPE` / `ECONNRESET` on the unfinished write, and
+ * what a caller asserts on is what was read back. A write error also ends the
+ * socket, so bytes the server sent just before it can go unread — a caller
+ * that needs to read a refusal reliably sends nothing the server will leave
+ * unread.
+ *
+ * @param base_url - the server's base URL; only its host and port are used
+ * @param request_bytes - the bytes to send, `latin1`-encoded
+ */
+export declare const raw_http_exchange: (base_url: string, request_bytes: string, options: RawHttpExchangeOptions) => Promise<RawHttpExchange>;
+/**
+ * Count HTTP response status lines in a raw byte stream. Deliberately
+ * **unanchored** (no `^`/`m`): a second pipelined response is concatenated
+ * straight after the first response's body, which carries no trailing newline,
+ * so a line-anchored match would miss it — and missing a smuggled second
+ * response is a silent false negative. It counts exactly the status lines as
+ * long as no response header or body contains the literal `HTTP/1.x NNN`.
+ */
+export declare const raw_http_count_responses: (raw: string) => number;
+/** The status code of the first HTTP response in a raw byte stream, or `null` if none. */
+export declare const raw_http_first_status: (raw: string) => number | null;
+/**
+ * Parse the first response in a raw byte stream, once all of it has arrived.
+ *
+ * The body is delimited by `Transfer-Encoding: chunked` or `Content-Length`.
+ * A response carrying neither is delimited by the connection closing, which
+ * the bytes alone don't show, so its body is whatever followed the head.
+ *
+ * @param raw - the bytes read so far, `latin1`-decoded
+ * @returns the response, or `null` when the head or the framed body is incomplete
+ */
+export declare const raw_http_parse_response: (raw: string) => RawHttpResponse | null;
+//# sourceMappingURL=raw_http.d.ts.map

package/dist/testing/transports/raw_http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw_http.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/raw_http.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CACtC;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAC7B,UAAU,MAAM,EAChB,eAAe,MAAM,EACrB,SAAS,sBAAsB,KAC7B,OAAO,CAAC,eAAe,CAwBvB,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,MAAM,KAAG,MACN,CAAC;AAElD,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAG5D,CAAC;AAyBF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,KAAG,eAAe,GAAG,IAyBvE,CAAC"}

package/dist/testing/transports/raw_http.js

@@ -0,0 +1,141 @@
+import '../assert_dev_env.js';
+/**
+ * Raw-socket HTTP/1.1 exchanges, for tests that need to control exactly which
+ * bytes reach the server.
+ *
+ * `fetch` frames a request itself and sends all of it, so some server
+ * behaviors can't be reached through it: what a server does with two requests
+ * in one write, with duplicate or malformed headers, with a request head whose
+ * body never follows, or with a chunked body that is never terminated. This
+ * writes caller-built bytes over `node:net` and hands back what the server
+ * sent, plus just enough parsing to read a status or one whole response.
+ *
+ * Everything is `latin1`-decoded, so a string's length is its byte length.
+ *
+ * Plain TCP only: an `https:` URL is not spoken to over TLS, and the host must
+ * be a name or an IPv4 address — a bracketed IPv6 literal does not connect.
+ *
+ * @module
+ */
+import { connect } from 'node:net';
+/**
+ * Open a raw TCP socket to `base_url`, write `request_bytes` once, and collect
+ * what the server sends back until it closes the connection, a whole response
+ * has arrived (`until: 'response'`), or `read_timeout_ms` elapses.
+ *
+ * Write errors are swallowed: a server that refuses a request and closes
+ * mid-upload surfaces as `EPIPE` / `ECONNRESET` on the unfinished write, and
+ * what a caller asserts on is what was read back. A write error also ends the
+ * socket, so bytes the server sent just before it can go unread — a caller
+ * that needs to read a refusal reliably sends nothing the server will leave
+ * unread.
+ *
+ * @param base_url - the server's base URL; only its host and port are used
+ * @param request_bytes - the bytes to send, `latin1`-encoded
+ */
+export const raw_http_exchange = (base_url, request_bytes, options) => new Promise((resolve) => {
+    const { read_timeout_ms, until = 'close' } = options;
+    const url = new URL(base_url);
+    const port = Number(url.port) || (url.protocol === 'https:' ? 443 : 80);
+    const socket = connect({ host: url.hostname, port });
+    let received = '';
+    let settled = false;
+    const finish = (closed_by_server) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve({ received, closed_by_server });
+    };
+    const timer = setTimeout(() => finish(false), read_timeout_ms);
+    socket.setEncoding('latin1');
+    socket.on('connect', () => socket.write(request_bytes, 'latin1'));
+    socket.on('data', (chunk) => {
+        received += chunk;
+        if (until === 'response' && raw_http_parse_response(received))
+            finish(false);
+    });
+    socket.on('error', () => { }); // EPIPE/ECONNRESET on a mid-write close is expected
+    socket.on('close', () => finish(true));
+});
+/**
+ * Count HTTP response status lines in a raw byte stream. Deliberately
+ * **unanchored** (no `^`/`m`): a second pipelined response is concatenated
+ * straight after the first response's body, which carries no trailing newline,
+ * so a line-anchored match would miss it — and missing a smuggled second
+ * response is a silent false negative. It counts exactly the status lines as
+ * long as no response header or body contains the literal `HTTP/1.x NNN`.
+ */
+export const raw_http_count_responses = (raw) => (raw.match(/HTTP\/1\.[01] \d{3}/g) ?? []).length;
+/** The status code of the first HTTP response in a raw byte stream, or `null` if none. */
+export const raw_http_first_status = (raw) => {
+    const match = /HTTP\/1\.[01] (\d{3})/.exec(raw);
+    return match ? Number(match[1]) : null;
+};
+/**
+ * Remove chunked framing from a body.
+ *
+ * @returns the decoded body, or `null` when the terminating chunk hasn't arrived
+ */
+const decode_chunked = (raw) => {
+    let body = '';
+    let offset = 0;
+    for (;;) {
+        const line_end = raw.indexOf('\r\n', offset);
+        if (line_end === -1)
+            return null;
+        // a chunk-size line may carry `;extension`s after the hex size
+        const size = Number.parseInt(raw.slice(offset, line_end), 16);
+        if (!Number.isFinite(size))
+            return null;
+        const data_start = line_end + 2;
+        // the last chunk is followed by optional trailers and an empty line
+        if (size === 0)
+            return raw.includes('\r\n\r\n', line_end) ? body : null;
+        if (raw.length < data_start + size + 2)
+            return null;
+        body += raw.slice(data_start, data_start + size);
+        offset = data_start + size + 2;
+    }
+};
+/**
+ * Parse the first response in a raw byte stream, once all of it has arrived.
+ *
+ * The body is delimited by `Transfer-Encoding: chunked` or `Content-Length`.
+ * A response carrying neither is delimited by the connection closing, which
+ * the bytes alone don't show, so its body is whatever followed the head.
+ *
+ * @param raw - the bytes read so far, `latin1`-decoded
+ * @returns the response, or `null` when the head or the framed body is incomplete
+ */
+export const raw_http_parse_response = (raw) => {
+    const head_end = raw.indexOf('\r\n\r\n');
+    if (head_end === -1)
+        return null;
+    const [status_line, ...header_lines] = raw.slice(0, head_end).split('\r\n');
+    const status_match = /^HTTP\/1\.[01] (\d{3})/.exec(status_line);
+    if (!status_match)
+        return null;
+    const headers = {};
+    for (const line of header_lines) {
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            continue;
+        headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    const status = Number(status_match[1]);
+    const rest = raw.slice(head_end + 4);
+    if (headers['transfer-encoding']?.toLowerCase().includes('chunked')) {
+        const body = decode_chunked(rest);
+        return body === null ? null : { status, headers, body };
+    }
+    const content_length = headers['content-length'];
+    if (content_length !== undefined) {
+        const length = Number(content_length);
+        if (!Number.isSafeInteger(length) || length < 0 || rest.length < length)
+            return null;
+        return { status, headers, body: rest.slice(0, length) };
+    }
+    return { status, headers, body: rest };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.135.0",
+  "version": "0.137.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -34,7 +34,8 @@
     "@electric-sql/pglite": ">=0.4",
     "@fuzdev/blake3-wasm": ">=0.2.0",
     "@fuzdev/fuz_css": ">=0.65.0",
-    "@fuzdev/fuz_util": ">=0.70.0",
+    "@fuzdev/fuz_schema": "^0.2.0",
+    "@fuzdev/fuz_util": ">=0.73.0",
     "@fuzdev/pglet-wasm": ">=0.1.1",
     "@hono/bun": ">=1",
     "@hono/deno": ">=1",
@@ -92,9 +93,10 @@
     "@fuzdev/blake3-wasm": "^0.2.0",
     "@fuzdev/fuz_code": "^0.52.1",
     "@fuzdev/fuz_css": "^0.66.1",
+    "@fuzdev/fuz_schema": "^0.2.0",
     "@fuzdev/fuz_ui": "^0.213.0",
-    "@fuzdev/fuz_util": "^0.72.0",
-    "@fuzdev/gro": "^0.216.0",
+    "@fuzdev/fuz_util": "^0.73.0",
+    "@fuzdev/gro": "^0.217.0",
     "@fuzdev/mdz": "^0.4.0",
     "@fuzdev/pglet-wasm": "^0.1.1",
     "@hono/bun": "^1.0.1",
@@ -130,7 +132,7 @@
     "vitest": "^5.0.0",
     "ws": "^8.20.1",
     "zimmerframe": "^1.1.4",
-    "zod": "^4.3.6"
+    "zod": "^4.6.7"
   },
   "sideEffects": [
     "**/*.css"

package/dist/env/resolve.d.ts

@@ -1,163 +0,0 @@
-/**
- * Environment variable `$$VAR$$` resolution suite.
- *
- * Resolves `$$VAR$$` references in strings and object trees,
- * scans configs for references, and validates/formats missing vars.
- *
- * The double-dollar bookending syntax is:
- * - Visually distinct from shell `$VAR` syntax
- * - Unambiguous about variable boundaries
- * - Easy to grep: `grep '\$\$'`
- * - Fails loud if accidentally shell-processed (`$$`=PID in shell)
- *
- * # Syntax
- *
- * - `$$VAR$$` — required reference. Missing or empty fails validation
- *   (see `validate_env_vars`).
- * - `$$?VAR$$` — optional reference. Missing or empty resolves to the
- *   empty string and passes validation. Use for vars that exist in the
- *   contract but may be intentionally blank (e.g. `SMTP_PASSWORD=` on
- *   a deployment that hasn't configured SMTP yet).
- * - `\$$VAR$$` — escape. The leading backslash is dropped at resolution
- *   time and the rest is emitted literally. Use this when documenting
- *   the syntax inside a string literal (comments in env-file templates,
- *   for example) where a regex scan would otherwise treat the mention
- *   as a real reference. Combines with `?` as `\$$?VAR$$`.
- *
- * @module
- */
-import type { EnvDeps } from '../runtime/deps.js';
-/**
- * Resolve environment variable references in a string.
- *
- * - `$$VAR$$` resolves from the runtime env; missing values are left as-is
- *   for the validation phase to report.
- * - `$$?VAR$$` is the optional form — missing or empty resolves to the empty
- *   string. Required validation skips refs marked optional.
- * - `\$$VAR$$` / `\$$?VAR$$` are escapes — the leading backslash is dropped
- *   and the body is emitted literally (no resolution attempted).
- *
- * @param runtime - runtime with `env_get` capability
- * @param value - string that may contain `$$VAR$$` references
- * @returns string with env vars resolved
- */
-export declare const resolve_env_vars: (runtime: Pick<EnvDeps, "env_get">, value: string) => string;
-/**
- * Check if a string contains unresolved env var references.
- *
- * Escaped references (`\$$VAR$$`) do not count — they're literal text once
- * resolved.
- *
- * @param value - string to check
- * @returns `true` if string contains unescaped `$$VAR$$` patterns
- */
-export declare const has_env_vars: (value: string) => boolean;
-/**
- * Get list of env var names referenced in a string.
- *
- * Escaped references are skipped; optional and required references are both
- * included (callers that care about the distinction should use `scan_env_vars`
- * which preserves the `optional` flag per ref).
- *
- * @param value - string to scan
- * @returns array of variable names (without `$$` delimiters)
- */
-export declare const get_env_var_names: (value: string) => Array<string>;
-/**
- * Resolve env vars in an object's string values (shallow).
- *
- * @param runtime - runtime with `env_get` capability
- * @param obj - object with string values
- * @returns new object with env vars resolved
- */
-export declare const resolve_env_vars_in_object: <T extends Record<string, unknown>>(runtime: Pick<EnvDeps, "env_get">, obj: T) => T;
-/**
- * Resolve env vars and throw if any are missing/empty.
- *
- * Use this for values that must be present. `$$?VAR$$` (optional) refs
- * resolve to the empty string on miss without contributing to the error.
- * Escaped references (`\$$VAR$$`) emit literally and never check the env.
- *
- * @param runtime - runtime with `env_get` capability
- * @param value - string with `$$VAR$$` references
- * @param context - description for error message (e.g., `"target.host"`)
- * @returns resolved string
- * @throws Error if any referenced env var is missing or empty
- */
-export declare const resolve_env_vars_required: (runtime: Pick<EnvDeps, "env_get">, value: string, context: string) => string;
-/**
- * An env var reference found in a config.
- */
-export interface EnvVarRef {
-    /** Variable name (without `$$` delimiters). */
-    name: string;
-    /** Path where the reference was found (e.g., `"target.host"`, `"resources[3].path"`). */
-    path: string;
-    /**
-     * Whether the reference is optional (`$$?VAR$$`). Optional refs resolve
-     * to the empty string when unset and are skipped by `validate_env_vars` —
-     * a var that's intentionally blank doesn't count as missing.
-     */
-    optional: boolean;
-}
-/**
- * Recursively scan an object for `$$VAR$$` env var references.
- *
- * Walks all string values in the object tree and extracts env var names
- * with their path context for error reporting. Escaped references
- * (`\$$VAR$$`) are skipped — they're literal text, not references.
- * The `optional` flag on each ref distinguishes `$$VAR$$` (required) from
- * `$$?VAR$$` (optional) for downstream validation.
- *
- * @param obj - object to scan (typically a config)
- * @returns array of env var references with paths and optional flags
- */
-export declare const scan_env_vars: (obj: unknown) => Array<EnvVarRef>;
-/**
- * Result of env var validation.
- *
- * Uses discriminated union for better type narrowing:
- * - `ok: true, missing: null` — all vars present
- * - `ok: false, missing: EnvVarRef[]` — some vars missing
- */
-export type EnvValidationResult = {
-    ok: true;
-    missing: null;
-} | {
-    ok: false;
-    missing: Array<EnvVarRef>;
-};
-/**
- * Validate that all referenced env vars exist in the environment.
- *
- * Returns all missing refs (including duplicates by name). Grouping
- * and deduplication is handled by `format_missing_env_vars` at display time.
- * Refs marked `optional: true` (from `$$?VAR$$` syntax) are skipped — a
- * deliberately-blank var is contract, not a missing dependency.
- *
- * @param runtime - runtime with `env_get` capability
- * @param refs - env var references from `scan_env_vars`
- * @returns validation result with any missing vars
- */
-export declare const validate_env_vars: (runtime: Pick<EnvDeps, "env_get">, refs: Array<EnvVarRef>) => EnvValidationResult;
-/**
- * Options for `format_missing_env_vars`.
- */
-export interface FormatMissingEnvVarsOptions {
-    /** Path to env file if one was loaded. */
-    env_file?: string;
-    /** Hint text for how to set up the environment. */
-    setup_hint?: string;
-}
-/**
- * Format missing env vars error message.
- *
- * Groups refs by variable name so each missing var is shown once
- * with all paths where it's referenced.
- *
- * @param missing - missing env var references (may contain duplicate names)
- * @param options - formatting options
- * @returns formatted error message for display
- */
-export declare const format_missing_env_vars: (missing: Array<EnvVarRef>, options?: FormatMissingEnvVarsOptions) => string;
-//# sourceMappingURL=resolve.d.ts.map

package/dist/env/resolve.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAiBlD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,MAAM,KAAG,MAYnF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAQ5C,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,KAAK,CAAC,MAAM,CAS7D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,KAAK,CAAC,KACJ,CAQF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,OAAO,MAAM,EACb,SAAS,MAAM,KACb,MAyBF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,KAAK,CAAC,SAAS,CAI3D,CAAC;AA2BF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,KAAK,CAAC,SAAS,CAAC,KACpB,mBAYF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,KAAK,CAAC,SAAS,CAAC,EACzB,UAAU,2BAA2B,KACnC,MA+BF,CAAC"}