duckfn-docs-kit 0.1.0 → 0.2.0

package/AGENTS.md

@@ -42,6 +42,8 @@ src/
 │                    #   + PreviewTabs.ts（预览页签，末尾恒定 Table）+ remark.ts
 │                    #   + extensions.ts（Node：扩展预加载插件）+ runtimeConfig.ts
 │                    #     （两侧共享的注入配置契约，见「扩展预加载」）
+│                    #   + collect.ts / nodeRunner.ts / verify.ts（Node：文档站自己的
+│                    #     SQL 测试与 `duckfn-sql-verify` 命令，见「文档站 SQL 测试」）
 │                    #   + client.ts（dfk-* 元素注册，插件注入到每个页面）
 ├── theme/           # tokens.css —— 全局设计基础设施，无业务归属，单独放
 ├── kit.css          # 全局 CSS 聚合入口（@import theme + toc-toggle + sql）
@@ -76,6 +78,8 @@ src/
   - `duckfn-docs-kit/remark`（**Node 构建期**：版本占位符 remark 插件）
   - `duckfn-docs-kit/sql/remark`（**Node 构建期**：可运行 SQL remark 插件）
   - `duckfn-docs-kit/sql/extensions`（**Node 构建期**：扩展预加载 Docusaurus 插件）
+  - `duckfn-docs-kit/sql/verify`（**Node 运行期**：文档站 SQL 测试的入口与 CLI；
+    `sql/collect`、`sql/nodeRunner` 是它的两半，也可单独用）
   - `duckfn-docs-kit/toc-toggle/plugin`（**Node 构建期**：TOC 胶水插件）
   - `duckfn-docs-kit/sql/client`、`duckfn-docs-kit/toc-toggle/client`（浏览器引导，
     由上面两个插件注入，站点不要手写引用）
@@ -85,6 +89,20 @@ src/
   与源路径脱钩的别名。`home.css` **不作为**全局 CSS 导出 —— 它由
   `home/styles.ts` 内联进 JS bundle，注入各组件的 shadow root。
 
+### TOC 折叠控件（`toc-toggle/`）
+
+- Docusaurus 的桌面目录元素是 `.theme-doc-toc-desktop`，它自带
+  `position: sticky; top: calc(var(--ifm-navbar-height) + 1rem)`（见主题里的
+  `theme/TOC/styles.module.css`）；而按钮由本模块插在它**前面**、同一个
+  `.toc-column` 里。
+- 所以按钮必须自己 `position: sticky`：否则文章一长，TOC 留在视口里悬浮，按钮却随页面滚上去，
+  读者把目录折叠后再往下滚就找不回来。TOC 的 `top` / `max-height` 要相应下移一个按钮高度
+  （按钮 2rem + 上下留白），两者才不会重叠 —— 三条规则都在 `TocToggle.css` 的
+  `@layer docusaurus.theme-classic` 段里，且带 `.toc-column` 前缀：TOC 那条来自 CSS module 的
+  哈希类名，同层同特异性时胜负取决于样式表顺序，前缀是唯一稳妥的写法。
+- 折叠态隐藏的是整个 `.theme-doc-toc-desktop`（按钮在它外面，因此仍在），列收成 2.5rem 宽，
+  按钮此时居中而不是靠右。
+
 ### 可运行 SQL：渲染契约与 DuckDB-Wasm 事实
 
 `sql/` 是一条单向链：`remark.ts`（构建期）→ `DfkSql.ts`（元素）→ `runtime.ts`
@@ -285,6 +303,28 @@ src/
   戳严格校验（1.5.4 的原生 duckdb 会拒绝 v1.5.5 构建的扩展）。升级 duckdb-wasm 或
   改 CI 的 `duckdb_version` 时必须成对验证（跑一遍可运行 SQL 页的两个示例块即可）。
 
+**文档站 SQL 测试（`sql/verify` + `sql/collect` / `sql/nodeRunner`）**
+
+- 入口是 `bin/sql-verify.mjs`（bin 名 `duckfn-sql-verify`），它 import `dist/sql/verify.js`。
+  bin **手写**、不进构建：Vite lib 产物是 ESM、不保留 shebang，而 npm 只需要一个带 shebang
+  且有执行位的文件。站点侧接成 `npm test` 即可（本仓库见 `docs/package.json`）。
+- 收集与渲染共用一份 meta 解析（`sql/remark.ts` 导出的 `parseRunnableSqlMeta`）：站点上不是
+  可运行块的，测试也不会跑。
+- 围栏按 CommonMark 收口：闭合围栏同字符、不短于开启围栏、且无 info string —— 这样
+  ````md 包着的 ```sql 示例（`runnable-sql.md` 就这么展示 meta）不会被当成块。
+- 执行用 **Node worker target**（`duckdb-node.cjs`），不用 blocking target：注册期会自行打开
+  连接的扩展（能用文件系统的那些）在 blocking 目标上**死锁**，表现为 `LOAD` 永久卡住（心跳静默，
+  进程内超时也打不断）。浏览器没这问题，因为那边的扩展在 worker 线程里加载。
+- 扩展只能经 **http URL** 加载（裸文件名 / 本地 VFS 路径在 wasm 上直接挂死，`registerFileBuffer`
+  也救不了），所以运行器起一个 loopback 服务。三个随之而来的约束：DuckDB 把拉下来的扩展暂存到
+  `~/.duckdb/extensions/<host>/<URL 一级路径段>/`，故 (1) URL 必须带一层路径段，(2) 该目录要
+  **预先建好**（加载器自己的 `mkdir` 非递归），(3) **Windows 上必须用 80 端口**让 URL 不含端口
+  —— 冒号在 Windows 路径里非法；其它平台用任意空闲端口。缓存目录每次运行前清空，免得测的是上一
+  次的旧扩展。
+- 形态与页面一致：**每页新实例 + 页内共用连接**（页内可以依赖前一个块建的宏/表，页与页隔离）。
+- 故意失败的块在 meta 里声明 `"expect": "error"`（`expectsError(config)` 读它，默认 `ok`）：
+  期望是数据，不能靠对注释做字符串匹配；校验**双向** —— 声明会失败却跑成功同样要报出来。
+
 ## 代码风格（硬性要求）
 
 这些规则是本包存在的意义所在，评审时逐条对照。
@@ -555,8 +595,9 @@ Docusaurus 预渲染在 Node 里 import 本包。
   才调用）：模块级 `new CSSStyleSheet()` 会在 Node 预渲染 import 时直接崩。
   `?inline` import 进来的只是字符串，模块级安全。
 - `iconify-icon` 在 Node 里 import 是安全的（官方包已处理）。
-- Node 构建期模块只有 `src/remark.ts`、`src/sql/remark.ts` 与 `src/sql/extensions.ts`
-  （连同无依赖的共享契约 `src/sql/runtimeConfig.ts`），它们不得 import 任何浏览器模块。
+- Node 侧模块只有 `src/remark.ts`、`src/sql/remark.ts`、`src/sql/extensions.ts`（构建期）
+  与 `src/sql/collect.ts`、`src/sql/nodeRunner.ts`、`src/sql/verify.ts`（测试期），
+  连同无依赖的共享契约 `src/sql/runtimeConfig.ts`；它们都不得 import 任何浏览器模块。
 
 ### 11. React 19 自定义元素
 
@@ -610,7 +651,7 @@ npm whoami               # 没登录先 npm login
 ```
 
 `npm pack --dry-run` 打印 tarball 的文件清单，是发布前最值得看的一项：预期是 `dist/**` +
-`src/**` + `AGENTS.md` + `README.md` + `LICENSE` + `package.json`（当前 64 个文件）。
+`src/**` + `bin/**` + `AGENTS.md` + `README.md` + `LICENSE` + `package.json`（当前 75 个文件）。
 多出别的东西时先查 `files` 白名单，不要靠 `.npmignore` 追着排除。
 
 ### 1. 提升版本号
@@ -669,9 +710,9 @@ just release_kit_dev 0.1.2-dev.0
 
 包内容 = `files` 白名单 + npm 的固定规则，所以**不需要**在包的结构之外维护清单：
 
-- `files: ["dist", "src", "AGENTS.md"]`：`dist` 是构建产物；`src` 必须带上（CSS 子路径
-  `duckfn-docs-kit/src/kit.css` 直接指向源文件）；`AGENTS.md` 随包发布，下游读者因此能看到
-  本包的全部约定。
+- `files: ["dist", "src", "bin", "AGENTS.md"]`：`dist` 是构建产物；`src` 必须带上（CSS 子路径
+  `duckfn-docs-kit/src/kit.css` 直接指向源文件）；`bin` 是 `duckfn-sql-verify` 的入口（它 import
+  `dist/`，所以两者都要在包里）；`AGENTS.md` 随包发布，下游读者因此能看到本包的全部约定。
 - `README.md`、`LICENSE`、`package.json` 由 npm 自动收录：本包目录下有自己的 `LICENSE`
   （根目录那份不会被带进来），README 是 npm 包页的正文。
 - `dist/` 在 `.gitignore` 里，但照样进包 —— `files` 白名单优先于 gitignore。`prepack` 脚本

package/bin/sql-verify.mjs

@@ -0,0 +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));

package/dist/sql/collect.d.ts

@@ -0,0 +1,29 @@
+import { type RunnableSqlConfig } from './remark';
+/** One runnable block, positioned so a failure can name it. */
+export interface RunnableSqlBlock {
+    /** Path relative to the site root, always with forward slashes. */
+    file: string;
+    /** 1-based line of the opening fence. */
+    line: number;
+    config: RunnableSqlConfig;
+    sql: string;
+}
+export interface CollectRunnableSqlOptions {
+    /** Site root the reported paths are relative to, and the base of a relative dir. */
+    siteDir: string;
+    /**
+     * Directories to scan (absolute, or relative to `siteDir`). Missing ones are
+     * skipped rather than reported: a site may have no translations.
+     */
+    contentDirs: readonly string[];
+    /** File extensions to scan; both `.md` and `.mdx` are markdown to us. */
+    extensions?: readonly string[];
+}
+/** Every runnable block under `contentDirs`, in file order, then line order. */
+export declare function collectRunnableSql(options: CollectRunnableSqlOptions): RunnableSqlBlock[];
+/**
+ * Whether a block is expected to fail — the block's own `"expect": "error"`
+ * metadata, never its prose or its comments: an expectation that the SQL test
+ * suite acts on has to be data, not a string match on a comment.
+ */
+export declare function expectsError(config: RunnableSqlConfig): boolean;

package/dist/sql/collect.js

@@ -0,0 +1,65 @@
+import { parseRunnableSqlMeta as e } from "./remark.js";
+import { join as t, relative as n, sep as r } from "node:path";
+import { readFileSync as i, readdirSync as a, statSync as o } from "node:fs";
+//#region src/sql/collect.ts
+var s = [".md", ".mdx"];
+function c(e) {
+	let { siteDir: a, contentDirs: o, extensions: c = s } = e, d = [];
+	for (let e of o) l(t(a, e), c, d);
+	let f = [];
+	for (let e of d.sort()) for (let t of u(i(e, "utf8"))) f.push({
+		...t,
+		file: n(a, e).split(r).join("/")
+	});
+	return f;
+}
+function l(e, n, r) {
+	let i;
+	try {
+		i = a(e);
+	} catch {
+		return;
+	}
+	for (let a of i) {
+		let i = t(e, a);
+		o(i).isDirectory() ? l(i, n, r) : n.some((e) => a.endsWith(e)) && r.push(i);
+	}
+}
+function u(t) {
+	let n = t.split("\n"), r = [], i = null, a = [];
+	for (let t = 0; t < n.length; t++) {
+		let o = n[t] ?? "", s = /^(`{3,}|~{3,})(.*)$/.exec(o);
+		if (!s) {
+			i && a.push(o);
+			continue;
+		}
+		let [c, l] = [s[1] ?? "", (s[2] ?? "").trim()];
+		if (!i) {
+			i = {
+				marker: c,
+				info: l,
+				line: t + 1
+			}, a = [];
+			continue;
+		}
+		if (!(c.charAt(0) === i.marker.charAt(0) && c.length >= i.marker.length && l === "")) {
+			a.push(o);
+			continue;
+		}
+		if (i.info.startsWith("sql")) {
+			let t = e(i.info.slice(3).trim());
+			t && r.push({
+				line: i.line,
+				config: t,
+				sql: a.join("\n")
+			});
+		}
+		i = null, a = [];
+	}
+	return r;
+}
+function d(e) {
+	return e.expect === "error";
+}
+//#endregion
+export { c as collectRunnableSql, d as expectsError };

package/dist/sql/nodeRunner.d.ts

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,115 @@
+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/dist/sql/remark.d.ts

@@ -36,6 +36,17 @@ export interface RunnableSqlConfig {
      * iframe, so scripts run with an opaque origin.
      */
     show?: 'table' | 'html' | 'iframe' | 'svg' | 'text';
+    /**
+     * What this block is expected to do when the docs' own SQL test suite runs it
+     * (`duckfn-docs-kit/sql/verify`). Defaults to `'ok'`; `'error'` marks a block
+     * that demonstrates a failure — the suite then *requires* it to fail, and
+     * reports it when it unexpectedly succeeds instead.
+     *
+     * This is the only source of truth for the expectation: the prose around a
+     * block, and a `-- error: …` comment inside it, are there for readers, and
+     * neither is machine-checked.
+     */
+    expect?: 'ok' | 'error';
     /**
      * The column holding the markup, for the preview renderers. A single-column
      * result is unambiguous and is used as-is.
@@ -85,4 +96,13 @@ export interface RunnableSqlOptions {
 }
 /** The custom element the plugin emits; must match `register.ts`. */
 export declare const DFK_SQL_TAG = "dfk-sql";
+/**
+ * Parse the metastring; `null` means "not a runnable block, leave it alone".
+ *
+ * Exported because the block contract has two consumers: this plugin, which
+ * turns a block into `<dfk-sql>` at build time, and `sql/verify` (via
+ * `sql/collect`), which runs those same blocks in CI. Both have to agree on
+ * what counts as runnable, so there is one parser.
+ */
+export declare function parseRunnableSqlMeta(meta: string | null | undefined): RunnableSqlConfig | null;
 export declare const remarkRunnableSql: Plugin<[RunnableSqlOptions?]>;

package/dist/sql/remark.js

@@ -66,4 +66,4 @@ var a = (e = {}) => (e) => {
 	n(e);
 };
 //#endregion
-export { e as DFK_SQL_TAG, a as remarkRunnableSql };
+export { e as DFK_SQL_TAG, t as parseRunnableSqlMeta, a as remarkRunnableSql };

package/dist/sql/verify.d.ts

@@ -0,0 +1,61 @@
+import { type WasmPlatform } from './nodeRunner';
+export interface VerifyOptions {
+    /** Docs site root; defaults to the working directory. */
+    siteDir?: string;
+    /** Content directories relative to the site root; defaults to the site layout. */
+    contentDirs?: readonly string[];
+    /**
+     * The extension to `LOAD`: a path, or an absolute `http(s)` URL. Defaults to
+     * the single file under `<siteDir>/static/duckdb-extensions/`.
+     */
+    extension?: string;
+    /** DuckDB-Wasm platform, which must match the extension build. */
+    platform?: WasmPlatform;
+    /** Engine wasm override, for pinning a specific DuckDB-Wasm build. */
+    engine?: string;
+    /** 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.
+     */
+    workingDir?: string;
+    /** Write the full result list here as JSON. */
+    reportFile?: string;
+}
+/** What happened to a block, judged against what it declared. */
+export type BlockOutcome = 
+/** Ran, and was expected to run. */
+'ok'
+/** Failed, and declared `"expect": "error"`. */
+ | 'error-as-expected'
+/** Failed, but was expected to run. */
+ | 'unexpected-error'
+/** Ran, but declared `"expect": "error"`. */
+ | 'unexpected-success';
+export interface BlockResult {
+    file: string;
+    line: number;
+    outcome: BlockOutcome;
+    detail: string;
+}
+export interface VerifyReport {
+    blocks: BlockResult[];
+    /** Blocks that behaved as declared: they ran, or they failed as declared. */
+    asDeclared: BlockResult[];
+    /** Blocks that did not behave as declared — the ones that should fail CI. */
+    unexpected: BlockResult[];
+}
+/** Runs every runnable block of the site and returns the outcome of each. */
+export declare function verifySqlDocs(options?: VerifyOptions): Promise<VerifyReport>;
+export interface CliOptions extends VerifyOptions {
+    quiet?: boolean;
+}
+/**
+ * `duckfn-sql-verify` — the command line around {@link verifySqlDocs}.
+ *
+ * Exit code 1 when a block did not behave as it declared, so a docs site can
+ * wire it straight into `npm test`.
+ */
+export declare function cliMain(argv: readonly string[]): Promise<void>;

package/dist/sql/verify.js

@@ -0,0 +1,148 @@
+import { collectRunnableSql as e, expectsError as t } from "./collect.js";
+import { WasmSqlRunner as n } from "./nodeRunner.js";
+import { join as r, resolve as i } from "node:path";
+import { mkdirSync as a, mkdtempSync as o, readdirSync as s, rmSync as c, statSync as l, writeFileSync as u } from "node:fs";
+import { tmpdir as d } from "node:os";
+//#region src/sql/verify.ts
+var f = ["docs", "i18n"], p = 3e4;
+async function m(t = {}) {
+	let n = i(t.siteDir ?? process.cwd()), s = e({
+		siteDir: n,
+		contentDirs: t.contentDirs ?? v(n)
+	}), l = t.extension, f = l ? /^https?:\/\//i.test(l) ? l : i(l) : y(n), m = t.timeoutMs ?? p, g = t.workingDir ? i(t.workingDir) : o(r(d(), "duckfn-sql-verify-"));
+	a(g, { recursive: !0 });
+	let _ = process.cwd();
+	process.chdir(g);
+	let b;
+	try {
+		b = await h(s, f, t, m);
+	} finally {
+		process.chdir(_), t.workingDir || c(g, {
+			recursive: !0,
+			force: !0
+		});
+	}
+	let x = {
+		blocks: b,
+		asDeclared: b.filter((e) => e.outcome === "ok" || e.outcome === "error-as-expected"),
+		unexpected: b.filter((e) => e.outcome === "unexpected-error" || e.outcome === "unexpected-success")
+	};
+	return t.reportFile && u(t.reportFile, `${JSON.stringify(x, null, 2)}\n`), x;
+}
+async function h(e, t, r, i) {
+	let a = await n.create({
+		extension: t,
+		platform: r.platform,
+		engine: r.engine
+	}), o = [];
+	try {
+		let t = null;
+		for (let n of e) n.file !== t && (t = n.file, await a.newPage()), o.push(await g(a, n, i));
+	} finally {
+		await a.close();
+	}
+	return o;
+}
+async function g(e, n, r) {
+	let i = t(n.config);
+	try {
+		let t = await _(e.run(n.sql), r);
+		return {
+			file: n.file,
+			line: n.line,
+			outcome: i ? "unexpected-success" : "ok",
+			detail: i ? `declared "expect": "error" but succeeded (${t.rows}×${t.columns})` : `ok (${t.rows}×${t.columns})`
+		};
+	} catch (e) {
+		let t = String(e?.message ?? e).split("\n")[0] ?? "";
+		return {
+			file: n.file,
+			line: n.line,
+			outcome: i ? "error-as-expected" : "unexpected-error",
+			detail: t
+		};
+	}
+}
+function _(e, t) {
+	let n, r = new Promise((e, r) => {
+		n = setTimeout(() => r(/* @__PURE__ */ Error(`timed out after ${t}ms`)), t);
+	});
+	return Promise.race([e, r]).finally(() => clearTimeout(n));
+}
+function v(e) {
+	let t = [];
+	b(r(e, f[0])) && t.push(f[0]);
+	let n = r(e, f[1]);
+	if (b(n)) for (let e of s(n)) b(r(n, e, "docusaurus-plugin-content-docs", "current")) && t.push(r("i18n", e, "docusaurus-plugin-content-docs", "current"));
+	return t.length > 0 ? t : ["."];
+}
+function y(e) {
+	let t = r(e, "static", "duckdb-extensions"), n = b(t) ? s(t).filter((e) => e.endsWith(".duckdb_extension.wasm")) : [];
+	if (n.length === 0) throw Error(`sql/verify: no extension found in ${t} — pass --extension <file|url>, or let the site's extension preload plugin fetch it first`);
+	if (n.length > 1) throw Error(`sql/verify: several extensions found in ${t} (${n.join(", ")}) — pass --extension to pick one`);
+	return r(t, n[0]);
+}
+function b(e) {
+	return l(e, { throwIfNoEntry: !1 })?.isDirectory() ?? !1;
+}
+async function x(e) {
+	let t = C(e);
+	if (t.help) {
+		process.stdout.write(S);
+		return;
+	}
+	let n = Date.now(), r = await m(t), i = ((Date.now() - n) / 1e3).toFixed(1), a = r.blocks.filter((e) => e.outcome === "error-as-expected").length;
+	if (t.quiet || (process.stdout.write(`\n${r.blocks.length} block(s) in ${i}s\n`), process.stdout.write(`  ${r.asDeclared.length} as declared (${a} erroring on purpose), ${r.unexpected.length} unexpected\n`)), r.unexpected.length > 0) {
+		process.stdout.write("unexpected behaviour:\n");
+		for (let e of r.unexpected) process.stdout.write(`- ${e.file}:${e.line} [${e.outcome}] :: ${e.detail}\n`);
+		process.exitCode = 1;
+	}
+}
+var S = "Usage: duckfn-sql-verify [options]\n\nRuns every runnable SQL block of a duckfn docs site in DuckDB-Wasm, and checks\nthat each one behaves as its own metadata declares (\"expect\": \"error\" for a\nblock that demonstrates a failure).\n\n  --site <dir>          Docs site root (default: the working directory)\n  --content <dir>       Content directory, relative to the site root (repeatable;\n                        default: docs/ plus every i18n/<locale>/… translation)\n  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,\n                        or an absolute http(s) URL (default: the single file under\n                        static/duckdb-extensions/)\n  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build\n                        (default: eh)\n  --engine <path>       Engine wasm override\n  --timeout <ms>        Per-block timeout (default: 30000)\n  --working-dir <dir>   Directory the blocks run in (default: a temporary one)\n  --report <file>       Write the full result list as JSON\n  --quiet               Only report unexpected behaviour\n  --help                Show this help\n";
+function C(e) {
+	let t = {}, n = [];
+	for (let r = 0; r < e.length; r++) {
+		let i = e[r], a = () => {
+			let t = e[++r];
+			if (t === void 0) throw Error(`sql/verify: ${i} needs a value`);
+			return t;
+		};
+		switch (i) {
+			case "--site":
+				t.siteDir = a();
+				break;
+			case "--content":
+				n.push(a());
+				break;
+			case "--extension":
+				t.extension = a();
+				break;
+			case "--platform":
+				t.platform = a();
+				break;
+			case "--engine":
+				t.engine = a();
+				break;
+			case "--timeout":
+				t.timeoutMs = Number(a());
+				break;
+			case "--working-dir":
+				t.workingDir = a();
+				break;
+			case "--report":
+				t.reportFile = a();
+				break;
+			case "--quiet":
+				t.quiet = !0;
+				break;
+			case "--help":
+			case "-h":
+				t.help = !0;
+				break;
+			default: throw Error(`sql/verify: unknown option ${i}`);
+		}
+	}
+	return n.length > 0 && (t.contentDirs = n), t;
+}
+//#endregion
+export { x as cliMain, m as verifySqlDocs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [
@@ -24,6 +24,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "duckfn-sql-verify": "./bin/sql-verify.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,6 +41,7 @@
   "files": [
     "dist",
     "src",
+    "bin",
     "AGENTS.md"
   ],
   "scripts": {