duckfn-docs-kit 0.1.0 → 0.2.1

package/README.md

@@ -24,7 +24,7 @@ npm install duckfn-docs-kit
 | --- | --- | --- |
 | `duckfn-docs-kit` | browser | Home-page custom elements (`<dfk-hero>`, `<dfk-features>`, `<dfk-next-steps>`, `<dfk-sql>`), `registerDfkElements()` and the value types their setters accept |
 | `duckfn-docs-kit/remark` | Node (build) | `remarkVersionPlaceholder`: replaces `{{DUCKFN_VERSION}}` inside `text` / `inlineCode` / `code` nodes |
-| `duckfn-docs-kit/sql/remark` | Node (build) | `remarkRunnableSql`: turns fenced `sql run` blocks into `<dfk-sql>` elements |
+| `duckfn-docs-kit/sql/remark` | Node (build) | `remarkRunnableSql`: turns fenced `sql {"type":"duckfn",…}` blocks into `<dfk-sql>` elements |
 | `duckfn-docs-kit/sql/extensions` | Node (build) | `dfkExtensions()` Docusaurus plugin: preloads a site's DuckDB extensions before the first block runs |
 | `duckfn-docs-kit/toc-toggle/plugin` | Node (build) | `dfkTocToggle()` Docusaurus plugin: adds the TOC collapse control |
 | `duckfn-docs-kit/toc-toggle/TocToggle` | browser | The TOC collapse class, for a site that drives it itself |
@@ -97,10 +97,12 @@ styles inside the JS bundle, so they need nothing here.
 
 ## Documentation
 
-The user guide lives at <https://shijianjs.github.io/duckfn/docs/docs-kit>. The
-conventions this package is written to — retained-mode components, shadow DOM,
-SSR safety, the SQL rendering contract — are documented in
-[`AGENTS.md`](./AGENTS.md), which ships inside the package.
+The user guide lives at <https://shijianjs.github.io/duckfn/docs/docs-kit>. If you —
+or an AI agent — are *using* this package, read [`AGENTS.md`](./AGENTS.md): it ships
+inside the package and states the contracts (the block metastring, the config
+fields, the traps). The conventions this package is *written to* — retained-mode
+components, shadow DOM, SSR safety — live in `CONVENTIONS.md` in the repository and
+are not published.
 
 ## License
 

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/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.13`. */
+    /** The real version string to substitute in, e.g. `0.0.14`. */
     version: string;
     /** Override the token if a site uses a different one. */
     placeholder?: string;

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.1",
   "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": {

package/src/remark.ts

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

package/src/sql/DfkSql.ts

@@ -18,7 +18,7 @@ import {el, HTMLElementBase} from '../dom';
  * Everything but the result is in the shadow root. The result is a slotted
  * light-DOM sibling because VTable injects a *document-level* stylesheet that a
  * shadow boundary could not host — and it is only created when a query runs,
- * long after hydration, so the light DOM still starts empty (AGENTS.md rule 11).
+ * long after hydration, so the light DOM still starts empty (CONVENTIONS.md rule 11).
  * The editor has no such problem: it sits in this shadow root, so CodeMirror's
  * style-mod resolves the root to the same tree its styles are used in.
  *
@@ -30,7 +30,7 @@ import {el, HTMLElementBase} from '../dom';
  * which a renderer builds, so the component keeps the node (and its state) and
  * hands it over through `RenderContext.fullscreenButton`.
  *
- * Content entry is an **attribute seed** (see AGENTS.md rule 5 exception): the
+ * Content entry is an **attribute seed** (see CONVENTIONS.md rule 5 exception): the
  * `config` / `sql` attributes are read once in `connectedCallback` because the
  * remark-generated JSX cannot hand content through a ref setter. Reading once
  * to initialise is not an attribute→render loop, so the retained-mode contract