duckfn-docs-kit 0.2.1 → 0.4.0

package/dist/remark.d.ts

@@ -13,7 +13,7 @@ import type { Plugin } from 'unified';
  */
 export declare const DEFAULT_VERSION_PLACEHOLDER = "{{DUCKFN_VERSION}}";
 export interface VersionPlaceholderOptions {
-    /** The real version string to substitute in, e.g. `0.0.14`. */
+    /** The real version string to substitute in, e.g. `0.0.17`. */
     version: string;
     /** Override the token if a site uses a different one. */
     placeholder?: string;

package/dist/sql/browserRunner.d.ts

@@ -0,0 +1,41 @@
+/** The extension to `LOAD`: a local `.duckdb_extension.wasm` path or an http(s) URL. */
+export interface RunnerOptions {
+    extension: string;
+    /** DuckDB-Wasm platform bundle; must match how the extension was built. */
+    platform?: WasmPlatform;
+    /** Engine wasm override; defaults to the platform bundle inside duckdb-wasm. */
+    engine?: string;
+    /** Browser executable; defaults to a detected Chrome/Edge (`DFK_BROWSER` wins). */
+    browser?: string;
+}
+export type WasmPlatform = 'eh' | 'mvp';
+export interface RunResult {
+    rows: number;
+    columns: number;
+}
+/** The harness's `__dfkQuery` return shape (see `harness.ts`). */
+export interface QueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    error?: string;
+}
+/**
+ * One DuckDB-Wasm instance at a time, driven through a headless browser.
+ * Mirrors the surface `verify.ts` used from `WasmSqlRunner`.
+ */
+export declare class BrowserSqlRunner {
+    #private;
+    private constructor();
+    static create(options: RunnerOptions): Promise<BrowserSqlRunner>;
+    /** Drops the current page state and opens a fresh one: new instance, new connection. */
+    newPage(): Promise<void>;
+    /** Runs one block; a SQL failure is thrown so the caller can weigh it. */
+    run(sql: string): Promise<RunResult>;
+    /**
+     * Runs one statement and returns its actual rows (not just a count). Used by
+     * the vfs browser probe to read each value; `run()` is the verifier's path.
+     * Unlike `run()`, a failure is returned as `{error}` rather than thrown.
+     */
+    query(sql: string): Promise<QueryResult>;
+    close(): Promise<void>;
+}

package/dist/sql/browserRunner.js

@@ -0,0 +1,186 @@
+import { createRequire as e } from "node:module";
+import { basename as t, dirname as n, join as r } from "node:path";
+import { existsSync as i, readFileSync as a } from "node:fs";
+import { createServer as o } from "node:http";
+import { chromium as s } from "playwright-core";
+//#region src/sql/browserRunner.ts
+var c = e(import.meta.url), l = {
+	eh: {
+		wasm: "duckdb-eh.wasm",
+		worker: "duckdb-browser-eh.worker.js"
+	},
+	mvp: {
+		wasm: "duckdb-mvp.wasm",
+		worker: "duckdb-browser-mvp.worker.js"
+	}
+}, u = class e {
+	#e = null;
+	#t = null;
+	#n = null;
+	#r = "";
+	#i = null;
+	#a;
+	#o;
+	#s;
+	#c;
+	#l;
+	constructor(e) {
+		this.#a = e.extensionUrl, this.#o = e.enginePath, this.#s = e.workerPath, this.#c = e.browserExecutable, this.#l = e.allowUnsigned;
+	}
+	static async create(t) {
+		let i = l[t.platform ?? "eh"], a = n(c.resolve("@duckdb/duckdb-wasm/dist/duckdb-browser.mjs")), o = t.engine ? d(t.engine) : r(a, i.wasm), s = r(a, i.worker), u = /^https?:\/\//i.test(t.extension) ? t.extension : d(t.extension);
+		return new e({
+			extensionUrl: u,
+			enginePath: o,
+			workerPath: s,
+			browserExecutable: m(t.browser),
+			allowUnsigned: !0
+		});
+	}
+	async #u() {
+		if (this.#n) return;
+		this.#e = await f(this.#d());
+		let e = this.#e.address(), t = typeof e == "object" && e ? e.port : 0;
+		this.#r = `http://127.0.0.1:${t}/harness.html`, this.#t = await s.launch({
+			executablePath: this.#c,
+			headless: !0
+		}), this.#n = await this.#t.newPage();
+	}
+	#d() {
+		let e = /^https?:\/\//i.test(this.#a) ? { remoteUrl: this.#a } : {
+			localFile: this.#a,
+			baseName: t(this.#a)
+		};
+		return {
+			harnessScript: c.resolve("duckfn-docs-kit/sql/harness"),
+			engine: {
+				file: this.#o,
+				name: t(this.#o)
+			},
+			worker: {
+				file: this.#s,
+				name: t(this.#s)
+			},
+			extension: e,
+			allowUnsigned: this.#l
+		};
+	}
+	async newPage() {
+		await this.#u();
+		let e = this.#n;
+		if (!e) throw Error("sql/browserRunner: browser is not running");
+		this.#i = null, await e.goto(this.#r, { waitUntil: "load" });
+		try {
+			await e.evaluate(() => window.__dfkReady);
+		} catch (e) {
+			this.#i = h(e);
+		}
+	}
+	async run(e) {
+		if (this.#i) throw Error(this.#i);
+		let t = this.#n;
+		if (!t) throw Error("sql/browserRunner: no page is open — call newPage() first");
+		let n = await t.evaluate((e) => window.__dfkRun(e), e);
+		if (n?.error) throw Error(n.error);
+		return {
+			rows: n.rows,
+			columns: n.columns
+		};
+	}
+	async query(e) {
+		if (this.#i) return {
+			columns: [],
+			rows: [],
+			error: this.#i
+		};
+		let t = this.#n;
+		if (!t) throw Error("sql/browserRunner: no page is open — call newPage() first");
+		return await t.evaluate((e) => window.__dfkQuery(e), e) ?? {
+			columns: [],
+			rows: [],
+			error: "no result"
+		};
+	}
+	async close() {
+		try {
+			await this.#n?.close();
+		} catch {}
+		this.#n = null;
+		try {
+			await this.#t?.close();
+		} catch {}
+		this.#t = null, this.#e &&= (await new Promise((e) => this.#e?.close(() => e())), null);
+	}
+};
+function d(e) {
+	return /^file:\/\//i.test(e) ? new URL(e).pathname.replace(/^\/(\w:)/i, "$1") : e;
+}
+async function f(e) {
+	let t = a(e.harnessScript), n = a(e.engine.file), r = a(e.worker.file), i = "localFile" in e.extension ? a(e.extension.localFile) : null, s = "baseName" in e.extension ? e.extension.baseName : "", c = "remoteUrl" in e.extension ? e.extension.remoteUrl : `ext/${e.extension.baseName}`, l = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>duckfn sql harness</title>
+    <script>
+      window.DFK_HARNESS_BUNDLE = {
+        mainModule: '/vendor/${e.engine.name}',
+        mainWorker: '/vendor/${e.worker.name}',
+      };
+    <\/script>
+    <script id="dfk-sql-runtime" type="application/json">
+      {"allowUnsignedExtensions":${e.allowUnsigned},"preload":[{"url":"${c}"}]}
+    <\/script>
+  </head>
+  <body>
+    <script type="module" src="/harness.js"><\/script>
+  </body>
+</html>`, u = o((a, o) => {
+		let c = new URL(a.url ?? "/", "http://localhost").pathname;
+		if (c === "/harness.html") {
+			p(o, "text/html; charset=utf-8", Buffer.from(l, "utf8"));
+			return;
+		}
+		if (c === "/harness.js") {
+			p(o, "text/javascript; charset=utf-8", t);
+			return;
+		}
+		if (c === `/vendor/${e.engine.name}`) {
+			p(o, "application/wasm", n);
+			return;
+		}
+		if (c === `/vendor/${e.worker.name}`) {
+			p(o, "text/javascript; charset=utf-8", r);
+			return;
+		}
+		if (i && c === `/ext/${s}`) {
+			p(o, "application/octet-stream", i);
+			return;
+		}
+		o.writeHead(404, { "content-type": "text/plain" }), o.end("not found");
+	});
+	return await new Promise((e, t) => {
+		u.once("error", t), u.listen(0, "127.0.0.1", e);
+	}), u;
+}
+function p(e, t, n) {
+	e.writeHead(200, {
+		"content-type": t,
+		"content-length": n.length
+	}), e.end(n);
+}
+function m(e) {
+	let t = e ?? process.env.DFK_BROWSER;
+	if (t) return t;
+	let n = [];
+	if (process.platform === "win32") {
+		let e = process.env.PROGRAMFILES ?? "C:\\Program Files", t = process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", i = process.env.LOCALAPPDATA ?? "";
+		n.push(r(e, "Google", "Chrome", "Application", "chrome.exe"), r(t, "Google", "Chrome", "Application", "chrome.exe"), r(t, "Microsoft", "Edge", "Application", "msedge.exe"), r(e, "Microsoft", "Edge", "Application", "msedge.exe"), i ? r(i, "Google", "Chrome", "Application", "chrome.exe") : "");
+	} else process.platform === "darwin" ? n.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge") : n.push("/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/microsoft-edge", "/usr/bin/chromium", "/usr/bin/chromium-browser");
+	for (let e of n) if (e && i(e)) return e;
+	throw Error("sql/browserRunner: no Chrome/Edge found — pass --browser <path> or set DFK_BROWSER");
+}
+function h(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+export { u as BrowserSqlRunner };

package/dist/sql/client.js

@@ -1,4 +1,4 @@
-import { t as e } from "../register-DKLiYs-F.js";
+import { t as e } from "../register-Dev_kc3Z.js";
 //#region src/sql/client.ts
 typeof window < "u" && e();
 //#endregion

package/dist/sql/harness.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `duckfn-docs-kit/sql/harness` — the browser page the offline SQL verifier
+ * (`sql/browserRunner`) drives with Playwright.
+ *
+ * It is deliberately thin: it reuses the site's own runtime (`sql/runtime`) so
+ * a verified block runs through exactly the code path a reader's **Run** click
+ * does — same `AsyncDuckDB` wiring, same ordered extension preload, same
+ * "multi-statement returns the last result" `execute()`. The only difference is
+ * where the engine comes from: instead of the jsDelivr CDN, the runner serves
+ * `duckdb-*.wasm` and its worker script same-origin and hands those URLs in
+ * through {@link window.DFK_HARNESS_BUNDLE}, which `runtime.init` accepts as a
+ * {@link LocalBundle}.
+ *
+ * The two contracts the page reads are injected by the served `harness.html`:
+ *
+ * - `window.DFK_HARNESS_BUNDLE` — `{mainModule, mainWorker, pthreadWorker?}`,
+ *   the locally-served engine bundle (an absolute same-origin URL each).
+ * - the `<script id="dfk-sql-runtime">` JSON tag — the preload list and
+ *   `allowUnsignedExtensions`, in the very shape the site plugin injects
+ *   (see `sql/runtimeConfig`), so nothing here re-implements extension loading.
+ *
+ * The runner communicates through `window.__dfkReady`, `window.__dfkRun` and
+ * `window.__dfkQuery`, each reached with a Playwright `page.evaluate` (which
+ * awaits the returned promise and marshals the value back to Node). Page reload
+ * per content file is what gives "one instance per page": a fresh document
+ * resets the module-level singleton, so pages never share a DuckDB instance
+ * while the blocks of one page keep sharing its connection (via
+ * `DuckDBRuntime.execute`).
+ */
+import { type LocalBundle } from './runtime';
+declare global {
+    interface Window {
+        /** The locally-served engine bundle, injected by the runner's harness.html. */
+        DFK_HARNESS_BUNDLE?: LocalBundle;
+        /** Resolves once the instance is up and the site preloads have loaded. */
+        __dfkReady?: Promise<void>;
+        /** Runs one block and reports rows/columns, or a captured error message. */
+        __dfkRun?: (sql: string) => Promise<HarnessRunResult>;
+        /**
+         * Runs one statement and returns its actual result — the rows, not just a
+         * count. Used by the vfs browser probe (`browserRunner.query`) to read the
+         * value each statement produced; the docs verifier never needs it.
+         */
+        __dfkQuery?: (sql: string) => Promise<HarnessQueryResult>;
+    }
+}
+/** What {@link window.__dfkRun} resolves with; mirrors the runner's `RunResult`. */
+export interface HarnessRunResult {
+    rows: number;
+    columns: number;
+    /** Set when the block failed; `rows`/`columns` are then 0. */
+    error?: string;
+}
+/** What {@link window.__dfkQuery} resolves with: the marshalled result rows. */
+export interface HarnessQueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    error?: string;
+}