duckfn-docs-kit 0.2.1 → 0.3.0

package/AGENTS.md

@@ -167,22 +167,32 @@ Constraints that bite:
 
 ## Testing the blocks (`duckfn-sql-verify`)
 
-The kit ships the same runner the browser uses, so a site can execute every block it publishes:
+The kit runs every block in a **real browser**, on the same runtime the page uses, so what CI
+checks is what a reader gets:
 
 ```bash
 duckfn-sql-verify --site .            # or: npx duckfn-sql-verify --site .
 ```
 
 It collects every runnable block (`docs/` plus each `i18n/<locale>/…/current/` by default), runs it
-in DuckDB-Wasm with the site's extension loaded, and fails the process when a block does not behave
-as it declares. Wire it into `package.json` as `"test": "duckfn-sql-verify --site ."`.
+in DuckDB-Wasm **in a headless browser** (driven with `playwright-core`, launching your system
+Chrome/Edge via `executablePath` — so no browser download) with the site's extension loaded, and
+fails the process when a block does not behave as it declares. It is fully offline: the engine and
+the extension are served from local files. Wire it into `package.json` as
+`"test": "duckfn-sql-verify --site ."`.
 
 - **A block that demonstrates a failure must say so**: `{"type":"duckfn","expect":"error"}`. The
   check is two-way — a block that declares `error` and starts succeeding is reported too — and a
   `-- error:` comment in the SQL is *not* read; only the metadata counts.
 - Useful options: `--extension <path|url>`, `--platform eh|mvp`, `--content <dir>` (repeatable),
-  `--timeout <ms>`, `--report <file>`, `--working-dir <dir>`, `--quiet`.
+  `--browser <path>` (the Chrome/Edge executable; otherwise a detected one or `DFK_BROWSER`),
+  `--timeout <ms>`, `--report <file>`, `--quiet`. It needs `playwright-core`, which the kit lists
+  as a dependency; unlike `playwright` it never downloads a browser.
 - The default extension is the single file under `static/duckdb-extensions/`.
+- **File-system examples stay plain code blocks.** Under DuckDB-Wasm the raw file system is not
+  POSIX-faithful: `dfn_file_exists` reads a missing file as "opened" (always `true`), writes/append
+  byte order is wrong, and there is no existence primitive in DuckDB's C API to correct it. So keep
+  any `COPY … TO` / `output_dir` / file-write demo as a non-runnable block and note the reason.
 
 ## TOC collapse control (`dfkTocToggle()`)
 

package/bin/sql-verify.mjs

@@ -1,12 +1,12 @@
-#!/usr/bin/env node
-/**
- * The `duckfn-sql-verify` executable.
- *
- * A hand-written wrapper rather than a built entry: Vite's library build emits
- * ESM and does not preserve a shebang, and npm only needs one file with one and
- * an executable bit. `dist/` is built by `prepack`, so the import below always
- * resolves in a published tarball.
- */
-import {cliMain} from '../dist/sql/verify.js';
-
-await cliMain(process.argv.slice(2));
+#!/usr/bin/env node
+/**
+ * The `duckfn-sql-verify` executable.
+ *
+ * A hand-written wrapper rather than a built entry: Vite's library build emits
+ * ESM and does not preserve a shebang, and npm only needs one file with one and
+ * an executable bit. `dist/` is built by `prepack`, so the import below always
+ * resolves in a published tarball.
+ */
+import {cliMain} from '../dist/sql/verify.js';
+
+await cliMain(process.argv.slice(2));

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, r, t as i } from "./register-DKLiYs-F.js";
+import { a as e, i as t, n, r, t as i } from "./register-CALCwFBv.js";
 export { e as DfkFeatures, t as DfkHero, r as DfkNextSteps, n as DfkSql, i as registerDfkElements };

package/dist/{register-DKLiYs-F.js → register-CALCwFBv.js}

@@ -168,7 +168,8 @@ var p = class extends c {
 	#i = null;
 	#a = !1;
 	#o = null;
-	#s = /* @__PURE__ */ new Map();
+	#s = null;
+	#c = /* @__PURE__ */ new Map();
 	get state() {
 		return this.#e;
 	}
@@ -176,24 +177,32 @@ var p = class extends c {
 		return this.#t;
 	}
 	init(e = {}) {
-		if (e.allowUnsignedExtensions && (this.#a = !0), this.#e === "ready") return Promise.resolve();
+		if (e.allowUnsignedExtensions && (this.#a = !0), e.bundle && (this.#o = e.bundle), this.#e === "ready") return Promise.resolve();
 		if (this.#n) return this.#n;
-		let t = this.#c();
-		return t.allowUnsignedExtensions && (this.#a = !0), this.#e = "loading", this.#n = this.#l(t.preload).catch((e) => {
+		let t = this.#l();
+		return t.allowUnsignedExtensions && (this.#a = !0), this.#e = "loading", this.#n = this.#u(t.preload).catch((e) => {
 			throw this.#e = "error", this.#t = y(e), this.#n = null, e;
 		}), this.#n;
 	}
-	#c() {
-		return this.#o ??= re(), this.#o;
+	#l() {
+		return this.#s ??= re(), this.#s;
 	}
-	async #l(e) {
-		let t = await import("@duckdb/duckdb-wasm"), n = await t.selectBundle(t.getJsDelivrBundles());
+	async #u(e) {
+		let t = await import("@duckdb/duckdb-wasm");
+		if (this.#o) {
+			let n = new Worker(this.#o.mainWorker);
+			this.#r = new t.AsyncDuckDB(new t.ConsoleLogger(), n), await this.#r.instantiate(this.#o.mainModule, this.#o.pthreadWorker ?? null), await this.#r.open({ allowUnsignedExtensions: this.#a }), this.#i = await this.#r.connect();
+			for (let t of e) await this.#d(t);
+			this.#e = "ready", this.#t = "";
+			return;
+		}
+		let n = await t.selectBundle(t.getJsDelivrBundles());
 		if (!n.mainWorker) throw Error("The selected DuckDB-Wasm bundle has no worker script");
 		let r = URL.createObjectURL(new Blob([`importScripts("${n.mainWorker}");`], { type: "text/javascript" })), i = new Worker(r);
 		URL.revokeObjectURL(r);
 		let a = new t.ConsoleLogger();
 		this.#r = new t.AsyncDuckDB(a, i), await this.#r.instantiate(n.mainModule, n.pthreadWorker), await this.#r.open({ allowUnsignedExtensions: this.#a }), this.#i = await this.#r.connect();
-		for (let t of e) await this.#u(t);
+		for (let t of e) await this.#d(t);
 		this.#e = "ready", this.#t = "";
 	}
 	async execute(e) {
@@ -219,38 +228,38 @@ var p = class extends c {
 		}
 	}
 	async loadExtension(e, t = {}) {
-		return await this.init(), this.#u({
+		return await this.init(), this.#d({
 			name: e,
 			repository: t.repository
 		});
 	}
-	#u(e) {
+	#d(e) {
 		let t = o(e);
-		if (typeof t == "string") return this.#d(`\u0000${t}`, () => this.#f(t));
+		if (typeof t == "string") return this.#f(`\u0000${t}`, () => this.#p(t));
 		if ("name" in t) {
 			let { name: e, repository: n } = t;
-			return this.#d(`${n ?? ""}\u0000${e}`, () => this.#f(e, n));
+			return this.#f(`${n ?? ""}\u0000${e}`, () => this.#p(e, n));
 		}
 		let { url: n } = t;
-		return this.#d(`url\u0000${n}`, () => this.#p(n));
+		return this.#f(`url\u0000${n}`, () => this.#m(n));
 	}
-	#d(e, t) {
-		let n = this.#s.get(e);
+	#f(e, t) {
+		let n = this.#c.get(e);
 		if (n) return n;
 		let r = t().catch((t) => {
-			throw this.#s.delete(e), t;
+			throw this.#c.delete(e), t;
 		});
-		return this.#s.set(e, r), r;
+		return this.#c.set(e, r), r;
 	}
-	async #f(e, t) {
+	async #p(e, t) {
 		if (!r.test(e)) throw Error(`Not a valid extension name: ${e}`);
-		let n = this.#m();
+		let n = this.#h();
 		t !== void 0 && await n.query(`INSTALL ${e} FROM ${ne(t)}`), await n.query(`LOAD ${e}`);
 	}
-	async #p(e) {
-		await this.#m().query(`LOAD '${v(e)}'`);
+	async #m(e) {
+		await this.#h().query(`LOAD '${v(e)}'`);
 	}
-	#m() {
+	#h() {
 		let e = this.#i;
 		if (!e) throw Error(this.#t || "DuckDB unavailable");
 		return e;

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.15`. */
     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-CALCwFBv.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;
+}