duckfn-docs-kit 0.2.1 → 0.4.0

package/src/sql/sql.css

@@ -237,11 +237,13 @@ dfk-sql:not(:defined) {
 
 /* --- Icon buttons and their tooltips ------------------------------------- */
 
-/* The same rules (and the `[data-tip]` tooltip below) are declared in
-   `DfkSql.css`, because the buttons are split across the shadow boundary: the
-   code-block actions live in the shadow tree, the fullscreen toggle lives in
-   this light-DOM tab strip. Keep the two copies in sync. */
-.dfk-sql-icon-button {
+/* The class names are written by the shared `IconButton` widget
+   (`src/IconButton.ts`). The same rules (and the `[data-tip]` tooltip below) are
+   declared in `DfkSql.css` and `DfkMermaid.css`, because the buttons are split
+   across shadow boundaries: the code-block actions live in `<dfk-sql>`'s tree,
+   a diagram's cluster in `<dfk-mermaid>`'s, and the fullscreen toggle in this
+   light-DOM tab strip. Keep the copies in sync. */
+.dfk-icon-button {
   position: relative;
   display: inline-flex;
   align-items: center;
@@ -257,27 +259,27 @@ dfk-sql:not(:defined) {
   transition: background 0.12s ease, color 0.12s ease;
 }
 
-.dfk-sql-icon-button:hover:not(:disabled),
-.dfk-sql-icon-button:focus-visible {
+.dfk-icon-button:hover:not(:disabled),
+.dfk-icon-button:focus-visible {
   background: var(--ifm-color-emphasis-200, #e6e6e6);
   color: var(--ifm-color-primary, #14459b);
 }
 
-.dfk-sql-icon-button:disabled {
+.dfk-icon-button:disabled {
   opacity: 0.45;
   cursor: progress;
 }
 
-.dfk-sql-icon-button[hidden] {
+.dfk-icon-button[hidden] {
   display: none;
 }
 
 /* A sticky state, e.g. the wrap toggle while wrapping is on. */
-.dfk-sql-icon-on {
+.dfk-icon-on {
   color: var(--ifm-color-primary, #14459b);
 }
 
-.dfk-sql-icon {
+.dfk-icon {
   font-size: 1rem;
 }
 

package/src/sql/verify.ts

@@ -3,10 +3,10 @@
  * publishes, so a broken example is caught by CI instead of by a reader
  * clicking **Run**.
  *
- * It is the same environment the site gives a block: DuckDB-Wasm in a worker,
+ * It is the same environment the site gives a block: DuckDB-Wasm in a browser,
  * the site's extension preloaded, one instance per page and the page's blocks
- * sharing a connection (see `sql/nodeRunner.ts` for why it is this target and
- * not the blocking one).
+ * sharing a connection (see `sql/browserRunner.ts` for why this is a real
+ * browser and not the Node worker the kit used to run).
  *
  * A block may fail *on purpose* — half the guide ends on a statement that
  * demonstrates an error. Such a block says so in its own metadata
@@ -15,12 +15,11 @@
  * on has to be data rather than a string match on a comment. Only blocks that
  * did not behave as declared make the command exit non-zero.
  */
-import {mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
-import {tmpdir} from 'node:os';
+import {readdirSync, statSync, writeFileSync} from 'node:fs';
 import {join, resolve} from 'node:path';
 
 import {collectRunnableSql, expectsError, type RunnableSqlBlock} from './collect';
-import {WasmSqlRunner, type WasmPlatform} from './nodeRunner';
+import {BrowserSqlRunner, type WasmPlatform} from './browserRunner';
 
 export interface VerifyOptions {
   /** Docs site root; defaults to the working directory. */
@@ -39,11 +38,10 @@ export interface VerifyOptions {
   /** Per-block timeout in milliseconds; a hang is reported instead of blocking CI. */
   timeoutMs?: number;
   /**
-   * Directory the blocks run in. Defaults to a fresh temporary directory that
-   * is removed afterwards: a block may `COPY … TO 'a.csv'`, and on Node
-   * DuckDB's file system is the real one, relative to the working directory.
+   * The browser executable that runs the blocks. Defaults to a detected
+   * Chrome/Edge; the `DFK_BROWSER` environment variable is the same override.
    */
-  workingDir?: string;
+  browser?: string;
   /** Write the full result list here as JSON. */
   reportFile?: string;
 }
@@ -79,8 +77,6 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 
 /** Runs every runnable block of the site and returns the outcome of each. */
 export async function verifySqlDocs(options: VerifyOptions = {}): Promise<VerifyReport> {
-  // Everything is resolved to absolute paths first: the run changes the working
-  // directory (see below).
   const siteDir = resolve(options.siteDir ?? process.cwd());
   const blocks = collectRunnableSql({
     siteDir,
@@ -94,26 +90,10 @@ export async function verifySqlDocs(options: VerifyOptions = {}): Promise<Verify
     : defaultExtension(siteDir);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
-  // A block may write files — `COPY (SELECT 1) TO 'a.csv'` — and on Node the
-  // file system behind DuckDB is the real one, resolved against the working
-  // directory. Giving the run a scratch directory of its own keeps the docs tree
-  // clean instead of dropping test residue into it.
-  const scratch = options.workingDir
-    ? resolve(options.workingDir)
-    : mkdtempSync(join(tmpdir(), 'duckfn-sql-verify-'));
-  mkdirSync(scratch, {recursive: true});
-  const previousCwd = process.cwd();
-  process.chdir(scratch);
-
-  let results: BlockResult[];
-  try {
-    results = await runPages(blocks, extension, options, timeoutMs);
-  } finally {
-    process.chdir(previousCwd);
-    if (!options.workingDir) {
-      rmSync(scratch, {recursive: true, force: true});
-    }
-  }
+  // No working directory: in a browser DuckDB's file system is the instance's
+  // own memory, so `COPY … TO` / `dfn_file_write_*` never touch the docs tree —
+  // they land in the page and vanish on the next `newPage()`.
+  const results = await runPages(blocks, extension, options, timeoutMs);
 
   const report: VerifyReport = {
     blocks: results,
@@ -135,10 +115,11 @@ async function runPages(
   options: VerifyOptions,
   timeoutMs: number,
 ): Promise<BlockResult[]> {
-  const runner = await WasmSqlRunner.create({
+  const runner = await BrowserSqlRunner.create({
     extension,
     platform: options.platform,
     engine: options.engine,
+    browser: options.browser,
   });
   const results: BlockResult[] = [];
   try {
@@ -158,7 +139,7 @@ async function runPages(
 
 /** Runs one block and judges the result against the block's own declaration. */
 async function runBlock(
-  runner: WasmSqlRunner,
+  runner: BrowserSqlRunner,
   block: RunnableSqlBlock,
   timeoutMs: number,
 ): Promise<BlockResult> {
@@ -278,9 +259,9 @@ export async function cliMain(argv: readonly string[]): Promise<void> {
 
 const USAGE = `Usage: duckfn-sql-verify [options]
 
-Runs every runnable SQL block of a duckfn docs site in DuckDB-Wasm, and checks
-that each one behaves as its own metadata declares ("expect": "error" for a
-block that demonstrates a failure).
+Runs every runnable SQL block of a duckfn docs site in a headless browser
+(DuckDB-Wasm), and checks that each one behaves as its own metadata declares
+("expect": "error" for a block that demonstrates a failure).
 
   --site <dir>          Docs site root (default: the working directory)
   --content <dir>       Content directory, relative to the site root (repeatable;
@@ -291,8 +272,9 @@ block that demonstrates a failure).
   --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build
                         (default: eh)
   --engine <path>       Engine wasm override
+  --browser <path>      Browser executable (default: a detected Chrome/Edge,
+                        or the DFK_BROWSER environment variable)
   --timeout <ms>        Per-block timeout (default: 30000)
-  --working-dir <dir>   Directory the blocks run in (default: a temporary one)
   --report <file>       Write the full result list as JSON
   --quiet               Only report unexpected behaviour
   --help                Show this help
@@ -330,12 +312,12 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
       case '--engine':
         options.engine = next();
         break;
+      case '--browser':
+        options.browser = next();
+        break;
       case '--timeout':
         options.timeoutMs = Number(next());
         break;
-      case '--working-dir':
-        options.workingDir = next();
-        break;
       case '--report':
         options.reportFile = next();
         break;

package/dist/sql/editor.d.ts

@@ -1,16 +0,0 @@
-/**
- * The CodeMirror 6 editor that *is* the code view of a runnable SQL block.
- *
- * Every CodeMirror module arrives through dynamic `import()` inside
- * {@link mountSqlEditor}: a page full of SQL examples pays nothing for the
- * editor on its critical path, and Docusaurus' Node prerender never evaluates
- * any of it.
- */
-export interface SqlEditor {
-    getValue(): string;
-    setValue(value: string): void;
-    /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
-    setWrap(wrapped: boolean): void;
-    destroy(): void;
-}
-export declare function mountSqlEditor(container: HTMLElement, value: string, onChange: (value: string) => void): Promise<SqlEditor>;

package/dist/sql/nodeRunner.d.ts

@@ -1,51 +0,0 @@
-export interface DuckdbQueryResult {
-    numRows: number;
-    schema: {
-        fields: {
-            name: string;
-        }[];
-    };
-}
-export interface DuckdbConnection {
-    query(sql: string): Promise<DuckdbQueryResult>;
-}
-export type WasmPlatform = 'eh' | 'mvp';
-export interface RunnerOptions {
-    /**
-     * The extension to `LOAD`: a local `.duckdb_extension.wasm` path (served to
-     * the worker over a loopback http server) or an absolute `http(s)` URL.
-     */
-    extension: string;
-    /**
-     * DuckDB-Wasm platform. Must match how the extension was built — a site
-     * serving `duckfn-wasm_eh.duckdb_extension.wasm` runs the `eh` bundle.
-     */
-    platform?: WasmPlatform;
-    /** The engine wasm; defaults to the one shipped beside the worker bundle. */
-    engine?: string;
-}
-export interface RunResult {
-    rows: number;
-    columns: number;
-}
-/**
- * One DuckDB-Wasm instance at a time, driven from Node.
- *
- * `newPage()` is what a docs site does per page load: a fresh instance, a fresh
- * connection, the extension loaded again. Blocks of one page then share state
- * (a table created in one block is visible to the next), while pages stay
- * isolated — which is why the runner is used one page at a time rather than
- * over a single long-lived connection.
- */
-export declare class WasmSqlRunner {
-    #private;
-    private constructor();
-    static create(options: RunnerOptions): Promise<WasmSqlRunner>;
-    /** Drops the current instance and starts a fresh page: new instance, new connection. */
-    newPage(): Promise<void>;
-    /** Runs one block; the caller decides whether a failure is expected. */
-    run(sql: string): Promise<RunResult>;
-    /** Where the fetched extension was staged, for diagnostics. */
-    get stagingDir(): string | null;
-    close(): Promise<void>;
-}

package/dist/sql/nodeRunner.js

@@ -1,115 +0,0 @@
-import { createRequire as e } from "node:module";
-import { basename as t, dirname as n, join as r } from "node:path";
-import { mkdirSync as i, readFileSync as a, rmSync as o } from "node:fs";
-import { createServer as s } from "node:http";
-import { Worker as c } from "node:worker_threads";
-import { homedir as l } from "node:os";
-//#region src/sql/nodeRunner.ts
-var u = e(import.meta.url), d = "@duckdb/duckdb-wasm/dist/duckdb-node.cjs", f = class {
-	#e;
-	#t = /* @__PURE__ */ new Map();
-	onmessage = null;
-	onerror = null;
-	onclose = null;
-	constructor(e) {
-		this.#e = new c(u.resolve(d), { workerData: {
-			mod: e,
-			name: "",
-			type: ""
-		} }), this.#e.on("message", (e) => this.#n("message", e)), this.#e.on("error", (e) => this.#n("error", e)), this.#e.on("exit", () => this.#n("close"));
-	}
-	#n(e, t) {
-		let n = {
-			type: e,
-			data: t,
-			target: this,
-			currentTarget: this
-		}, r = this[`on${e}`];
-		typeof r == "function" && r(n);
-		for (let t of this.#t.get(e) ?? []) t(n);
-	}
-	addEventListener(e, t) {
-		this.#t.set(e, [...this.#t.get(e) ?? [], t]);
-	}
-	removeEventListener(e, t) {
-		this.#t.set(e, (this.#t.get(e) ?? []).filter((e) => e !== t));
-	}
-	postMessage(e, t) {
-		this.#e.postMessage(e, t ?? []);
-	}
-	terminate() {
-		return this.#e.terminate();
-	}
-}, p = class e {
-	#e = null;
-	#t = null;
-	#n = null;
-	#r = null;
-	#i;
-	#a;
-	#o;
-	constructor(e, t, n) {
-		this.#i = e, this.#a = t, this.#o = n;
-	}
-	static async create(t) {
-		let i = t.platform ?? "eh", a = u.resolve(`@duckdb/duckdb-wasm/dist/duckdb-node-${i}.worker.cjs`), o = t.engine ?? r(n(a), `duckdb-${i}.wasm`), s = /^https?:\/\//i.test(t.extension) ? null : await m(t.extension), c = s ? s.url : t.extension, l = new e(c, o, a);
-		return l.#n = s ? s.server : null, l.#r = s ? h(s.stagingHost, s.stagingSegment) : null, l;
-	}
-	async newPage() {
-		this.#e && (await this.#e.terminate(), this.#e = null, this.#t = null);
-		let e = await import(
-			/* @vite-ignore */
-			d
-), t = new e.AsyncDuckDB(new e.ConsoleLogger(), new f(this.#o));
-		await t.instantiate(this.#a, null), await t.open({ allowUnsignedExtensions: !0 });
-		let n = await t.connect();
-		await n.query(`LOAD '${this.#i}'`), this.#e = t, this.#t = n;
-	}
-	async run(e) {
-		let t = this.#t;
-		if (!t) throw Error("sql/verify: no page is open — call newPage() first");
-		let n = await t.query(e);
-		return {
-			rows: n.numRows,
-			columns: n.schema.fields.length
-		};
-	}
-	get stagingDir() {
-		return this.#r;
-	}
-	async close() {
-		this.#e && (await this.#e.terminate(), this.#e = null, this.#t = null), this.#n &&= (await new Promise((e) => this.#n?.close(() => e())), null);
-	}
-};
-async function m(e) {
-	let n = a(e), r = t(e), i = g(e), o = s((e, t) => {
-		t.writeHead(200, {
-			"content-type": "application/octet-stream",
-			"content-length": n.length
-		}), t.end(n);
-	}), c = process.platform === "win32" ? 80 : 0;
-	await new Promise((e, t) => {
-		o.once("error", (e) => {
-			t(/* @__PURE__ */ Error(`sql/verify: cannot serve the extension on port ${c} (${e.code}): a port in the URL would put a colon into DuckDB's staging path, which is not a legal Windows path — free port 80, or load the extension from an http(s) URL with --extension`));
-		}), o.listen(c, "localhost", e);
-	});
-	let l = o.address(), u = typeof l == "object" && l ? l.port : c, d = u === 80 ? "localhost" : `localhost:${u}`;
-	return {
-		server: o,
-		url: `http://${d}/${i}/${r}`,
-		stagingHost: d,
-		stagingSegment: i
-	};
-}
-function h(e, t) {
-	let n = r(l(), ".duckdb", "extensions", e, t);
-	return o(n, {
-		recursive: !0,
-		force: !0
-	}), i(n, { recursive: !0 }), n;
-}
-function g(e) {
-	return t(e).split(".")[0] ?? "";
-}
-//#endregion
-export { p as WasmSqlRunner };

package/src/sql/editor.ts

@@ -1,75 +0,0 @@
-/**
- * The CodeMirror 6 editor that *is* the code view of a runnable SQL block.
- *
- * Every CodeMirror module arrives through dynamic `import()` inside
- * {@link mountSqlEditor}: a page full of SQL examples pays nothing for the
- * editor on its critical path, and Docusaurus' Node prerender never evaluates
- * any of it.
- */
-
-export interface SqlEditor {
-  getValue(): string;
-  setValue(value: string): void;
-  /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
-  setWrap(wrapped: boolean): void;
-  destroy(): void;
-}
-
-export async function mountSqlEditor(
-  container: HTMLElement,
-  value: string,
-  onChange: (value: string) => void,
-): Promise<SqlEditor> {
-  const [
-    {basicSetup},
-    {sql},
-    {EditorView, keymap},
-    {defaultKeymap, historyKeymap},
-    {Compartment},
-  ] = await Promise.all([
-    import('codemirror'),
-    import('@codemirror/lang-sql'),
-    import('@codemirror/view'),
-    import('@codemirror/commands'),
-    import('@codemirror/state'),
-  ]);
-
-  // Wrapping is toggled from the outside, and reconfiguring it must not disturb
-  // the document or the undo history — that is exactly what a compartment is
-  // for, so the extension is swapped in place rather than rebuilt.
-  const wrap = new Compartment();
-
-  const view = new EditorView({
-    doc: value,
-    extensions: [
-      basicSetup,
-      sql(),
-      keymap.of([...defaultKeymap, ...historyKeymap]),
-      wrap.of([]),
-      EditorView.updateListener.of((update) => {
-        if (update.docChanged) {
-          onChange(update.state.doc.toString());
-        }
-      }),
-    ],
-    parent: container,
-    // `root` is left to CodeMirror's own `getRoot(container)`. The container sits
-    // in `<dfk-sql>`'s shadow root, so style-mod mounts the base theme into that
-    // same shadow root — exactly where the `.cm-*` rules are needed. Pinning it
-    // to `document` would put them outside the editor's tree instead, where a
-    // shadow boundary stops them.
-  });
-
-  return {
-    getValue: () => view.state.doc.toString(),
-    setValue: (next: string) =>
-      view.dispatch({
-        changes: {from: 0, to: view.state.doc.length, insert: next},
-      }),
-    setWrap: (wrapped: boolean) =>
-      view.dispatch({
-        effects: wrap.reconfigure(wrapped ? EditorView.lineWrapping : []),
-      }),
-    destroy: () => view.destroy(),
-  };
-}