@bezoar/kit 0.0.0-stage → 0.0.1

package/.dist/_chunks/build.mjs

@@ -0,0 +1,546 @@
+import { basename, dirname, join, posix, resolve, win32 } from "node:path";
+import { pglite } from "@bezoar/pglite";
+import { PGlite } from "@electric-sql/pglite";
+import { createServer } from "node:net";
+import { PGLiteSocketServer } from "@electric-sql/pglite-socket";
+import { createGenerator } from "@ts-safeql/generate";
+import postgres from "postgres";
+import { record, within } from "objectively";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { IDENTIFIER, SCALARS } from "@bezoar/schema";
+import { existsSync } from "node:fs";
+import { createJiti } from "jiti";
+const FILENAME = "bezoar.config.ts";
+const MIGRATIONS = "src/migrations";
+const SEEDS = "src/seeds";
+const QUERIES = "src/queries";
+const OUT_DIR = "bezoar";
+const EXTENSION = ".sql";
+const MIGRATION = /^(\d+)_(.+)$/;
+const SCHEMA = "public";
+const MANIFEST = ".bezoar.json";
+const BANNER = "// Generated by @bezoar/kit. Do not edit by hand.";
+const SILENT = /^\s*(--.*)?$/;
+const HOST = "127.0.0.1";
+const DATABASE = "postgres";
+const CACHE = "bezoar";
+var MissingConfigError = class extends Error {
+	path;
+	constructor(path) {
+		super(`@bezoar/kit: no config file at ${path}`);
+		this.name = "MissingConfigError";
+		this.path = path;
+	}
+};
+var MalformedConfigError = class extends Error {
+	path;
+	constructor(path) {
+		super(`@bezoar/kit: ${path} must default-export a config (defineConfig({ … }))`);
+		this.name = "MalformedConfigError";
+		this.path = path;
+	}
+};
+var InvalidConfigError = class extends Error {
+	issues;
+	constructor(issues) {
+		const lines = issues.map((issue) => `  ${issue}`).join("\n");
+		super(`@bezoar/kit: the config is invalid —\n${lines}`);
+		this.name = "InvalidConfigError";
+		this.issues = issues;
+	}
+};
+var InvalidSourceError = class extends Error {
+	path;
+	constructor(path, reason, options) {
+		super(`@bezoar/kit: ${path} ${reason}`, options);
+		this.name = "InvalidSourceError";
+		this.path = path;
+	}
+};
+var InvalidQueryError = class extends Error {
+	path;
+	constructor(path, reason, options) {
+		super(`@bezoar/kit: ${path} ${reason}`, options);
+		this.name = "InvalidQueryError";
+		this.path = path;
+	}
+};
+const reason = (error) => error instanceof Error ? error.message : String(error);
+const apply = async (executor, sources) => {
+	for (const file of [...sources.migrations, ...sources.seeds]) try {
+		await executor.exec(file.sql);
+	} catch (cause) {
+		throw new InvalidSourceError(file.path, `failed: ${reason(cause)}`, { cause });
+	}
+};
+const ENUMS = `
+  SELECT t.typname AS name,
+         array_agg(e.enumlabel::text ORDER BY e.enumsortorder) AS labels
+  FROM pg_type t
+  JOIN pg_namespace n ON n.oid = t.typnamespace
+  JOIN pg_enum e ON e.enumtypid = t.oid
+  WHERE n.nspname = $1
+  GROUP BY t.typname
+  ORDER BY t.typname`;
+const readEnums = async (executor) => {
+	const enums = {};
+	for (const row of (await executor.query(ENUMS, [SCHEMA])).rows) enums[String(row.name)] = Array.isArray(row.labels) ? row.labels.map(String) : [];
+	return enums;
+};
+const free = () => new Promise((resolve, reject) => {
+	const server = createServer();
+	server.listen(0, HOST, () => {
+		const address = server.address();
+		server.close(() => {
+			if (address === null || typeof address === "string") reject(/* @__PURE__ */ new Error("@bezoar/kit: no free port"));
+			else resolve(address.port);
+		});
+	});
+	server.on("error", reject);
+});
+const admitsNull = (target) => {
+	if (target.kind === "type") return target.type === "null";
+	if (target.kind === "union") return target.value.some(admitsNull);
+	return false;
+};
+const describeQueries = async (client, queries) => {
+	const described = /* @__PURE__ */ new Map();
+	if (queries.length === 0) return described;
+	const port = await free();
+	const server = new PGLiteSocketServer({
+		db: client,
+		port,
+		host: HOST
+	});
+	await server.start();
+	const sql = postgres({
+		host: HOST,
+		port,
+		database: DATABASE,
+		username: DATABASE,
+		max: 1,
+		onnotice: () => {}
+	});
+	const { generate } = createGenerator();
+	try {
+		for (const query of queries) {
+			const result = await generate({
+				sql,
+				query: {
+					text: query.sql,
+					sourcemaps: []
+				},
+				cacheKey: CACHE,
+				fieldTransform: void 0
+			});
+			if (result._tag === "Left") throw new InvalidQueryError(query.path, `failed: ${result.left.message}`, { cause: result.left });
+			const { stmt, output } = result.right;
+			const targets = new Map(output?.value ?? []);
+			described.set(query.name, {
+				params: stmt.types,
+				columns: stmt.columns.map((column) => {
+					const target = targets.get(column.name);
+					return {
+						name: column.name,
+						type: column.type,
+						nullable: target === void 0 || admitsNull(target)
+					};
+				})
+			});
+		}
+	} finally {
+		await sql.end({ timeout: 1 });
+		await server.stop();
+	}
+	return described;
+};
+const json = (value) => JSON.stringify(value, null, 2);
+const literal = (value, depth = 0) => {
+	const pad = "  ".repeat(depth);
+	const inner = "  ".repeat(depth + 1);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "readonly []";
+		return `readonly [\n${value.map((item) => `${inner}${literal(item, depth + 1)},`).join("\n")}\n${pad}]`;
+	}
+	if (record(value)) return `{\n${Object.entries(value).map(([key, member]) => `${inner}readonly ${JSON.stringify(key)}: ${literal(member, depth + 1)};`).join("\n")}\n${pad}}`;
+	return JSON.stringify(value);
+};
+const pair = (name, module, declaration) => [{
+	path: `${name}.mjs`,
+	contents: `${[BANNER, ...module].join("\n")}\n`
+}, {
+	path: `${name}.d.mts`,
+	contents: `${[BANNER, ...declaration].join("\n")}\n`
+}];
+const index = (contract) => pair("index", [
+	`export const contract = Object.freeze(${json(contract)});`,
+	"const known = new Set(Object.keys(contract.queries));",
+	`export const isQuery = (value) => typeof value === "string" && known.has(value);`
+], [
+	`export declare const contract: ${literal(contract)};`,
+	"export type Contract = typeof contract;",
+	"export type Query = keyof Contract[\"queries\"] & string;",
+	"export declare const isQuery: (value: unknown) => value is Query;"
+]);
+const bundle = (sources) => {
+	const sql = {};
+	for (const query of sources.queries) sql[query.name] = query.sql;
+	return pair("queries", [`export const queries = Object.freeze(${json(sql)});`], ["import type { Query } from \"./index.mjs\";", "export declare const queries: Readonly<Record<Query, string>>;"]);
+};
+const migrations = (sources) => {
+	const entries = sources.migrations.map(({ version, name, sql, checksum }) => ({
+		version,
+		name,
+		sql,
+		checksum
+	}));
+	return pair("migrations", [`export const migrations = Object.freeze(${json(entries)});`], [
+		"export declare const migrations: readonly {",
+		"  readonly version: string;",
+		"  readonly name: string;",
+		"  readonly sql: string;",
+		"  readonly checksum: string;",
+		"}[];"
+	]);
+};
+const seeds = (sources) => {
+	const entries = sources.seeds.map(({ name, sql }) => ({
+		name,
+		sql
+	}));
+	return pair("seeds", [`export const seeds = Object.freeze(${json(entries)});`], [
+		"export declare const seeds: readonly {",
+		"  readonly name: string;",
+		"  readonly sql: string;",
+		"}[];"
+	]);
+};
+const emit = (sources, contract) => [
+	...index(contract),
+	...bundle(sources),
+	...migrations(sources),
+	...seeds(sources)
+];
+const starts = (char) => char !== void 0 && /[A-Za-z_]/.test(char);
+const continues = (char) => char !== void 0 && /[A-Za-z0-9_]/.test(char);
+const quoted = (sql, start, escapes) => {
+	const quote = sql[start];
+	let index = start + 1;
+	while (index < sql.length) {
+		const char = sql[index];
+		if (escapes && char === "\\") {
+			index += 2;
+			continue;
+		}
+		if (char === quote) {
+			if (sql[index + 1] === quote) {
+				index += 2;
+				continue;
+			}
+			return index + 1;
+		}
+		index++;
+	}
+	throw new SyntaxError(`has a quote that does not close`);
+};
+const dollar = (sql, start) => {
+	const tag = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(start));
+	if (!tag) return;
+	const close = sql.indexOf(tag[0], start + tag[0].length);
+	if (close === -1) throw new SyntaxError(`has a dollar quote that does not close`);
+	return close + tag[0].length;
+};
+const block = (sql, start) => {
+	let depth = 0;
+	let index = start;
+	while (index < sql.length) if (sql.startsWith("/*", index)) {
+		depth++;
+		index += 2;
+	} else if (sql.startsWith("*/", index)) {
+		depth--;
+		index += 2;
+		if (depth === 0) return index;
+	} else index++;
+	throw new SyntaxError(`has a comment that does not close`);
+};
+const rewrite = (sql) => {
+	const slots = [];
+	let text = "";
+	let index = 0;
+	const copy = (end) => {
+		text += sql.slice(index, end);
+		index = end;
+	};
+	while (index < sql.length) {
+		const char = sql[index];
+		if (char === "'") {
+			const before = sql[index - 1];
+			const escapes = (before === "E" || before === "e") && !continues(sql[index - 2]);
+			copy(quoted(sql, index, escapes));
+		} else if (char === "\"") copy(quoted(sql, index, false));
+		else if (char === "$") {
+			const end = dollar(sql, index);
+			if (end !== void 0) copy(end);
+			else if (/[0-9]/.test(sql[index + 1] ?? "")) throw new SyntaxError(`uses a $n parameter; name the slot instead`);
+			else copy(index + 1);
+		} else if (sql.startsWith("--", index)) {
+			const end = sql.indexOf("\n", index);
+			copy(end === -1 ? sql.length : end);
+		} else if (sql.startsWith("/*", index)) copy(block(sql, index));
+		else if (sql.startsWith("::", index)) copy(index + 2);
+		else if (char === ":" && starts(sql[index + 1])) {
+			let end = index + 1;
+			while (continues(sql[end])) end++;
+			const name = sql.slice(index + 1, end);
+			if (!slots.includes(name)) slots.push(name);
+			text += `$${slots.indexOf(name) + 1}`;
+			index = end;
+		} else copy(index + 1);
+	}
+	return {
+		text,
+		slots
+	};
+};
+const list$1 = async (directory) => {
+	let entries;
+	try {
+		entries = await readdir(directory, { recursive: true });
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	return entries.map((entry) => entry.replaceAll("\\", "/")).filter((entry) => entry.endsWith(EXTENSION)).sort();
+};
+const nameOf = (path, file) => {
+	const segments = file.slice(0, -4).split("/");
+	for (const segment of segments) if (!IDENTIFIER.test(segment)) throw new InvalidQueryError(path, `has "${segment}" in its path; a query is named for its path, so each directory and the file name must be an identifier`);
+	return segments.join(".");
+};
+const queryOf = (path, name, text) => {
+	if (text.split("\n").every((line) => SILENT.test(line))) throw new InvalidQueryError(path, "has no SQL");
+	try {
+		const { text: sql, slots } = rewrite(text.trim().replace(/;\s*$/, ""));
+		return {
+			name,
+			sql,
+			slots,
+			path
+		};
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new InvalidQueryError(path, error.message);
+		throw error;
+	}
+};
+const disjoint = (queries) => {
+	const names = new Set(queries.map((query) => query.name));
+	for (const query of queries) {
+		const segments = query.name.split(".");
+		for (let depth = 1; depth < segments.length; depth += 1) {
+			const group = segments.slice(0, depth).join(".");
+			if (names.has(group)) throw new InvalidQueryError(query.path, `is in the group ${group}, which is also the name of a query`);
+		}
+	}
+};
+const readQueries = async (root, directory) => {
+	const queries = [];
+	for (const file of await list$1(join(root, directory))) {
+		const path = posix.join(directory, file);
+		const name = nameOf(path, file);
+		const text = await readFile(join(root, path), "utf8");
+		queries.push(queryOf(path, name, text));
+	}
+	disjoint(queries);
+	return queries;
+};
+const list = async (directory) => {
+	let entries;
+	try {
+		entries = await readdir(directory);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	return entries.filter((entry) => entry.endsWith(EXTENSION)).sort();
+};
+const checksum = (text) => createHash("sha256").update(text).digest("hex");
+const identity = (file) => {
+	const stem = basename(file, EXTENSION);
+	const match = MIGRATION.exec(stem);
+	if (!match) return {
+		version: stem,
+		name: stem
+	};
+	const [, version = stem, name = stem] = match;
+	return {
+		version,
+		name
+	};
+};
+const readMigrations = async (root, directory) => {
+	const migrations = [];
+	for (const file of await list(join(root, directory))) {
+		const path = posix.join(directory, file);
+		const sql = await readFile(join(root, path), "utf8");
+		migrations.push({
+			path,
+			...identity(file),
+			sql,
+			checksum: checksum(sql)
+		});
+	}
+	return migrations;
+};
+const readSeeds = async (root, directory) => {
+	const seeds = [];
+	for (const file of await list(join(root, directory))) {
+		const path = posix.join(directory, file);
+		seeds.push({
+			path,
+			name: basename(file, EXTENSION),
+			sql: await readFile(join(root, path), "utf8")
+		});
+	}
+	return seeds;
+};
+const readSources = async (root, settings) => ({
+	migrations: await readMigrations(root, settings.migrations),
+	seeds: await readSeeds(root, settings.seeds),
+	queries: await readQueries(root, settings.queries)
+});
+const TYPES = `
+  SELECT t.oid::int AS oid, t.typname AS name, e.typname AS element
+  FROM pg_type t
+  LEFT JOIN pg_type e ON e.oid = t.typelem AND t.typname LIKE '\\_%'
+  WHERE t.oid = ANY($1::int[])`;
+const readTypes = async (executor, described) => {
+	const oids = /* @__PURE__ */ new Set();
+	for (const { params, columns } of described.values()) {
+		for (const oid of params) oids.add(oid);
+		for (const column of columns) oids.add(column.type);
+	}
+	const names = /* @__PURE__ */ new Map();
+	if (oids.size === 0) return names;
+	const { rows } = await executor.query(TYPES, [[...oids]]);
+	for (const row of rows) {
+		const element = row.element === null ? void 0 : String(row.element);
+		names.set(Number(row.oid), element === void 0 ? String(row.name) : `${element}[]`);
+	}
+	return names;
+};
+const define = (queries, described, types, enums) => {
+	const statements = {};
+	for (const query of queries) {
+		const description = described.get(query.name);
+		if (description === void 0) throw new InvalidQueryError(query.path, "was not described");
+		const typeOf = (what, oid) => {
+			const name = types.get(oid) ?? String(oid);
+			const base = name.endsWith("[]") ? name.slice(0, -2) : name;
+			if (!within(SCALARS, base) && !(base in enums)) throw new InvalidQueryError(query.path, `${what} has the type ${name}, which the type table does not have`);
+			return name;
+		};
+		statements[query.name] = {
+			slots: query.slots.map((name, index) => ({
+				name,
+				type: typeOf(`the slot :${name}`, description.params[index] ?? 0),
+				nullable: false
+			})),
+			columns: description.columns.map((column) => ({
+				name: column.name,
+				type: typeOf(`the column ${column.name}`, column.type),
+				nullable: column.nullable
+			}))
+		};
+	}
+	return {
+		enums,
+		queries: statements
+	};
+};
+const normalize = (path) => posix.normalize(path.replaceAll("\\", "/")).replace(/\/$/, "");
+const inside = (path) => {
+	if (posix.isAbsolute(path) || win32.isAbsolute(path)) return false;
+	return path !== "." && path !== ".." && !path.startsWith("../");
+};
+const validate = (config) => {
+	const issues = [];
+	const directory = (label, path, fallback) => {
+		if (path === void 0) return fallback;
+		if (typeof path !== "string" || !inside(normalize(path))) {
+			issues.push(`${label} must be a directory inside the project root`);
+			return fallback;
+		}
+		return normalize(path);
+	};
+	const settings = {
+		migrations: directory("migrations", config.migrations, MIGRATIONS),
+		seeds: directory("seeds", config.seeds, SEEDS),
+		queries: directory("queries", config.queries, QUERIES),
+		outDir: directory("outDir", config.outDir, OUT_DIR)
+	};
+	if (issues.length > 0) throw new InvalidConfigError(issues);
+	return settings;
+};
+const generate = async (config, root) => {
+	const settings = validate(config);
+	const sources = await readSources(root, settings);
+	const client = new PGlite();
+	const executor = pglite(client);
+	try {
+		await apply(executor, sources);
+		const enums = await readEnums(executor);
+		const described = await describeQueries(client, sources.queries);
+		const types = await readTypes(executor, described);
+		const contract = define(sources.queries, described, types, enums);
+		return {
+			outDir: settings.outDir,
+			files: emit(sources, contract),
+			sources,
+			enums,
+			contract
+		};
+	} finally {
+		await executor.close();
+	}
+};
+const loadConfig = async (path) => {
+	if (!existsSync(path)) throw new MissingConfigError(path);
+	const config = await createJiti(import.meta.url, { moduleCache: false }).import(path, { default: true });
+	if (!record(config)) throw new MalformedConfigError(path);
+	return config;
+};
+const readManifest = async (dir) => {
+	let files;
+	try {
+		const manifest = JSON.parse(await readFile(join(dir, MANIFEST), "utf8"));
+		if (record(manifest)) files = manifest.files;
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(files)) return [];
+	return files.filter((path) => typeof path === "string" && inside(normalize(path)));
+};
+const writeManifest = async (dir, files) => {
+	await writeFile(join(dir, MANIFEST), `${JSON.stringify({ files }, null, 2)}\n`);
+};
+const writeOutput = async (output, root) => {
+	const dir = resolve(root, output.outDir);
+	await mkdir(dir, { recursive: true });
+	const produced = output.files.map((file) => file.path);
+	for (const path of await readManifest(dir)) if (!produced.includes(path)) await rm(join(dir, path), { force: true });
+	for (const file of output.files) {
+		const target = join(dir, file.path);
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, file.contents);
+	}
+	await writeManifest(dir, produced);
+};
+const build = async (options = {}) => {
+	const root = resolve(options.root ?? process.cwd());
+	const config = await loadConfig(resolve(root, options.config ?? "bezoar.config.ts"));
+	const output = await generate(config, root);
+	await writeOutput(output, root);
+	return output;
+};
+export { BANNER, CACHE, DATABASE, EXTENSION, FILENAME, HOST, InvalidConfigError, InvalidQueryError, InvalidSourceError, MANIFEST, MIGRATION, MIGRATIONS, MalformedConfigError, MissingConfigError, OUT_DIR, QUERIES, SCHEMA, SEEDS, SILENT, build, generate };

package/.dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/.dist/cli.mjs

@@ -0,0 +1,52 @@
+import { build } from "./_chunks/build.mjs";
+import { parseArgs } from "node:util";
+const HELP = `Usage: bezoar <command> [options]
+
+Commands:
+  build  Apply the migrations and the seeds to a database in memory, describe
+         the queries, and write the output directory. Offline and
+         deterministic.
+
+Options:
+  -c, --config <file>  Config file (default: bezoar.config.ts)
+  -r, --root <dir>     Project root (default: current directory)
+  -h, --help           Show this help`;
+const runBuild = async (config, root) => {
+	const output = await build({
+		config,
+		root
+	});
+	console.log(`@bezoar/kit: wrote ${output.files.length} files to ${output.outDir}`);
+};
+const main = async (argv) => {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			config: {
+				type: "string",
+				short: "c"
+			},
+			root: {
+				type: "string",
+				short: "r"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	if (values.help) {
+		console.log(HELP);
+		return;
+	}
+	if (positionals.length === 1 && positionals[0] === "build") return runBuild(values.config, values.root);
+	console.error(HELP);
+	process.exitCode = 1;
+};
+main(process.argv.slice(2)).catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});
+export {};

package/.dist/index.d.mts

@@ -0,0 +1,255 @@
+import { Definition } from "@bezoar/schema";
+import { Migration, Seed } from "@bezoar/core";
+/**
+ * The authored `bezoar.config.ts`: where the SQL lives and where the build
+ * writes. Every path is relative to the project root.
+ */
+export interface KitConfig {
+  /**
+   * The directory of migrations. The files apply in name order, and the
+   * name of a file is its version. Defaults to `src/migrations`.
+   */
+  migrations?: string;
+  /**
+   * The directory of seeds. Each file is `<name>.sql`, and the files run in
+   * name order. Defaults to `src/seeds`.
+   */
+  seeds?: string;
+  /**
+   * The directory of queries. Each file is one query, named for its path.
+   * Defaults to `src/queries`.
+   */
+  queries?: string;
+  /**
+   * The output directory. Defaults to `bezoar`.
+   */
+  outDir?: string;
+}
+/**
+ * A config through validation: every default applied, every path normalized.
+ */
+export interface Settings {
+  migrations: string;
+  seeds: string;
+  queries: string;
+  outDir: string;
+}
+/**
+ * A migration as the kit read it: the migration, and the file it came from.
+ */
+export interface MigrationFile extends Migration {
+  /** The path of the file, relative to the project root. */
+  readonly path: string;
+}
+/**
+ * A seed as the kit read it: the seed, and the file it came from.
+ */
+export interface SeedFile extends Seed {
+  /** The path of the file, relative to the project root. */
+  readonly path: string;
+}
+/**
+ * A query as the kit read it: its name, its SQL with the slots rewritten to
+ * positions, and the slots in position order.
+ */
+export interface Query {
+  /** The name, from the path of the file: `events/list.sql` is `events.list`. */
+  readonly name: string;
+  /** The SQL, with `$1` in place of the first slot, and so on. */
+  readonly sql: string;
+  /** The slot names, in position order. */
+  readonly slots: readonly string[];
+  /** The path of the file, relative to the project root. */
+  readonly path: string;
+}
+/**
+ * The SQL of a project, as the kit read it.
+ */
+export interface Sources {
+  /** The migrations, in file name order. */
+  migrations: MigrationFile[];
+  /** The seeds, in file name order. */
+  seeds: SeedFile[];
+  /** The queries, in file name order. */
+  queries: Query[];
+}
+/**
+ * What Postgres and SafeQL say about one query: the type OID of each slot,
+ * and the name, type OID, and nullability of each column.
+ */
+export interface Described {
+  readonly params: readonly number[];
+  readonly columns: readonly {
+    readonly name: string;
+    readonly type: number;
+    readonly nullable: boolean;
+  }[];
+}
+/**
+ * The enums of the database after the migrations ran: each enum type with
+ * its labels, in declaration order. What the contract carries as `enums`.
+ */
+export type Enums = Readonly<Record<string, readonly string[]>>;
+/**
+ * One file of the output.
+ */
+export interface OutputFile {
+  /** The path, relative to the output directory. */
+  path: string;
+  /** The text of the file. */
+  contents: string;
+}
+/**
+ * What a build produces: the files to write, and what they were made from.
+ */
+export interface Output {
+  /** The output directory, normalized and relative to the project root. */
+  outDir: string;
+  /** The files of the output. */
+  files: OutputFile[];
+  /** The SQL the build read. */
+  sources: Sources;
+  /** The enums of the hermetic database after the migrations ran. */
+  enums: Enums;
+  /** The contract: every query with its slots and columns typed. */
+  contract: Definition;
+}
+/**
+ * The options of a build: where the project lives.
+ */
+export interface BuildOptions {
+  /** The project root. Defaults to `process.cwd()`. */
+  root?: string;
+  /** The config file, relative to the root. Defaults to `bezoar.config.ts`. */
+  config?: string;
+}
+/**
+ * The whole build: load the config, generate, and write the output
+ * directory. What the CLI runs.
+ *
+ * @param options - The root and the config path.
+ */
+export declare const build: (options?: BuildOptions) => Promise<Output>;
+/**
+ * Identity helper that types a `bezoar.config.ts`.
+ *
+ * @param config - The kit config.
+ * @returns The same config.
+ */
+export declare const defineConfig: (config: KitConfig) => KitConfig;
+/**
+ * The config file the CLI looks for in the project root when `--config` is
+ * not given.
+ */
+export declare const FILENAME = "bezoar.config.ts";
+/**
+ * The default directory of migrations, relative to the project root.
+ */
+export declare const MIGRATIONS = "src/migrations";
+/**
+ * The default directory of seeds, relative to the project root.
+ */
+export declare const SEEDS = "src/seeds";
+/**
+ * The default directory of queries, relative to the project root.
+ */
+export declare const QUERIES = "src/queries";
+/**
+ * The default output directory, relative to the project root.
+ */
+export declare const OUT_DIR = "bezoar";
+/**
+ * The extension of a source file.
+ */
+export declare const EXTENSION = ".sql";
+/**
+ * Matches a migration whose file name starts with digits and an underscore,
+ * as in `0001_events.sql`. The digits are the version. The rest is the name.
+ * A file name of another form is its own version and name.
+ */
+export declare const MIGRATION: RegExp;
+/**
+ * The schema of the database the kit reads the enums from.
+ */
+export declare const SCHEMA = "public";
+/**
+ * The manifest a write leaves in the output directory: the paths it
+ * produced, so the next write can remove the ones it no longer produces
+ * without touching anything the kit did not write.
+ */
+export declare const MANIFEST = ".bezoar.json";
+/**
+ * The banner at the top of each emitted module.
+ */
+export declare const BANNER = "// Generated by @bezoar/kit. Do not edit by hand.";
+/**
+ * Matches a line that is blank or a line comment. A query file of such lines
+ * alone has no SQL.
+ */
+export declare const SILENT: RegExp;
+/**
+ * The host the hermetic database listens on for the describe of each query.
+ */
+export declare const HOST = "127.0.0.1";
+/**
+ * The database and the user of a PGlite instance.
+ */
+export declare const DATABASE = "postgres";
+/**
+ * The key of the catalog cache SafeQL keeps for a build.
+ */
+export declare const CACHE = "bezoar";
+/**
+ * Raised when there is no config file at the path the build was pointed at.
+ * Carries the `path` it looked for.
+ */
+export declare class MissingConfigError extends Error {
+  readonly path: string;
+  constructor(path: string);
+}
+/**
+ * Raised when a config file does not default-export a config. Carries the
+ * `path` of the file.
+ */
+export declare class MalformedConfigError extends Error {
+  readonly path: string;
+  constructor(path: string);
+}
+/**
+ * Raised when a config breaks the rules of the kit, such as a directory
+ * outside the project root. Carries every issue found. Thrown before any
+ * file is read.
+ */
+export declare class InvalidConfigError extends Error {
+  readonly issues: string[];
+  constructor(issues: string[]);
+}
+/**
+ * Raised when Postgres rejects the SQL of a source file. Carries the `path`
+ * of the file, relative to the project root, and the error of Postgres as
+ * `cause`.
+ */
+export declare class InvalidSourceError extends Error {
+  readonly path: string;
+  constructor(path: string, reason: string, options?: ErrorOptions);
+}
+/**
+ * Raised when a query cannot be built: a path that does not name a query, a
+ * file without SQL, a slot the SQL cannot type, SQL that Postgres rejects,
+ * or a column of a type the type table does not have. Carries the `path` of
+ * the file, relative to the project root.
+ */
+export declare class InvalidQueryError extends Error {
+  readonly path: string;
+  constructor(path: string, reason: string, options?: ErrorOptions);
+}
+/**
+ * Generates the output of a project without writing it. The function
+ * validates the config, reads the SQL, applies the migrations and the seeds
+ * to a database in memory, reads the enums, describes each query, builds
+ * the contract, and emits the files.
+ *
+ * @param config - The authored config.
+ * @param root - The project root.
+ */
+export declare const generate: (config: KitConfig, root: string) => Promise<Output>;

package/.dist/index.mjs

@@ -0,0 +1,3 @@
+import { BANNER, CACHE, DATABASE, EXTENSION, FILENAME, HOST, InvalidConfigError, InvalidQueryError, InvalidSourceError, MANIFEST, MIGRATION, MIGRATIONS, MalformedConfigError, MissingConfigError, OUT_DIR, QUERIES, SCHEMA, SEEDS, SILENT, build, generate } from "./_chunks/build.mjs";
+const defineConfig = (config) => config;
+export { BANNER, CACHE, DATABASE, EXTENSION, FILENAME, HOST, InvalidConfigError, InvalidQueryError, InvalidSourceError, MANIFEST, MIGRATION, MIGRATIONS, MalformedConfigError, MissingConfigError, OUT_DIR, QUERIES, SCHEMA, SEEDS, SILENT, build, defineConfig, generate };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Thorwaldson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @bezoar/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The build kit of bezoar. The kit reads the SQL of a database package,
+applies it to a Postgres in memory, and writes modules for the runtime.
+
+## Install
+
+```sh
+pnpm add -D @bezoar/kit
+```
+
+## Config
+
+Put `bezoar.config.ts` in the project root.
+
+```ts
+import { defineConfig } from "@bezoar/kit";
+
+export default defineConfig({
+  // Optional. The directory of migrations. Defaults to src/migrations.
+  migrations: "src/migrations",
+
+  // Optional. The directory of seeds. Defaults to src/seeds.
+  seeds: "src/seeds",
+
+  // Optional. The directory of queries. Defaults to src/queries.
+  queries: "src/queries",
+
+  // Optional. The output directory. Defaults to bezoar.
+  outDir: ".output",
+});
+```
+
+Every path is relative to the project root and must stay inside it. The kit
+checks the config before it reads a file, and reports every problem
+together.
+
+## Sources
+
+A migration is a `.sql` file. The files apply in name order, so a name has
+to sort: a counter or a timestamp first. The name of a file is its version,
+which the runner records. A name of the form `<digits>_<rest>` also gives
+the rest as the name for people. A migration is plain SQL and can hold many
+statements.
+
+```
+src/migrations/0001_events.sql
+src/migrations/0002_staff.sql
+```
+
+A seed is `<name>.sql`. The seeds run in name order. A seed is not tracked
+by the runner, so write a seed that is safe to run again.
+
+## Queries
+
+A query is one `.sql` file, named for its path. Each directory is a group,
+and the file name is the name: `events/list.sql` is `events.list`, and
+`admin/staff/leaders.sql` is `admin.staff.leaders`. Each directory and the
+file name must be an identifier. A file at the root of the directory is a
+query with no group. A file beside a directory of the same name fails the
+build, since the name would be both a query and a group.
+
+```sql
+-- src/queries/events/list.sql
+SELECT id, slug, title, day
+FROM events
+WHERE day = :day
+ORDER BY id;
+```
+
+```sql
+-- src/queries/events/bySlug.sql
+SELECT id, title FROM events WHERE slug = :slug;
+```
+
+A file holds one statement. A comment is fine anywhere. A file of comments
+and blank lines alone fails the build. What a call returns follows from the
+columns of the statement: a query with a column returns its rows, and the
+service offers `first` beside it for the first row or `null`. A query with
+no column, a write without `RETURNING`, returns the count of the rows the
+statement changed. Nothing in the file declares this.
+
+A slot is `:name`, the syntax of psql. The build rewrites each slot to a
+position, so `:day` is `$1` in the SQL the service runs, and a name used
+twice binds one position. A colon inside a string, a quoted identifier, a
+dollar quote, or a comment is text, and `::` is a cast. A `$1` in the source
+is an error: a query names its slots.
+
+Every lever of a query is a SQL lever. A cast sets the type of a slot. An
+alias names a column. Two columns with one name fail the build.
+
+## Build
+
+```sh
+bezoar build
+```
+
+The build boots [PGlite](https://pglite.dev) in memory and applies the
+migrations and the seeds in order. It reads the enums. Then it serves the
+database on a local port and describes each query through
+[SafeQL](https://safeql.dev): Postgres reports the type of each slot and
+each column, and SafeQL reports whether each column can be null, through
+outer joins, `COALESCE`, aggregates, CTEs, and views.
+
+A file that Postgres rejects fails the build with the file and the error of
+Postgres:
+
+```
+@bezoar/kit: src/migrations/0002_staff.sql failed: relation "evnts" does not exist
+@bezoar/kit: src/queries/events/bySlug.sql failed: column "slgu" does not exist
+@bezoar/kit: src/queries/events/list.sql the column ip has the type inet, which the type table does not have
+```
+
+The build writes to the output directory:
+
+- `index.mjs` and its declaration: the `contract` and the `isQuery` guard.
+  The declaration carries the contract as literal types, so `Arguments`,
+  `Row`, and `Returns` of `@bezoar/schema` derive from it. `Contract` and
+  `Query` are its types. The module holds no SQL.
+- `queries.mjs` and its declaration: the SQL of each query, by name, with
+  the slots at their positions.
+- `migrations.mjs` and its declaration: each migration as data, with its
+  version, name, SQL, and checksum, for `migrate` of `@bezoar/core`.
+- `seeds.mjs` and its declaration: each seed as data, for `seed`.
+
+The kit writes a manifest beside the files. A later build removes the files
+the manifest lists that it no longer produces, and touches nothing else.
+
+## API
+
+- `defineConfig(config)` types a config file.
+- `build(options?)` runs the whole build. `options.root` is the project
+  root, and `options.config` the config file relative to it.
+- `generate(config, root)` produces the output without writing it.
+
+## Errors
+
+- `MissingConfigError`: no file at the config path.
+- `MalformedConfigError`: the config file does not default-export a record.
+- `InvalidConfigError`: the config breaks a rule. Carries every issue.
+- `InvalidSourceError`: Postgres rejected a migration or a seed. Carries its
+  path and the error of Postgres as `cause`.
+- `InvalidQueryError`: a query cannot be built. Carries the path of its
+  file.
+
+## Related
+
+- [`@bezoar/core`](../core): the runtime that imports the build.
+- [`@bezoar/schema`](../schema): the contract the build writes.
+- [`@bezoar/pglite`](../pglite): the database the build runs in.

package/bin/bezoar.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The `bezoar` command. A committed launcher rather than the built file
+// itself, so package managers can link the bin before the kit is built.
+import "../.dist/cli.mjs";

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@bezoar/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Build kit: SQL in a hermetic Postgres to a typed contract",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/bezoar.git",
+    "directory": "packages/kit"
+  },
+  "type": "module",
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    }
+  },
+  "bin": {
+    "bezoar": "./bin/bezoar.mjs"
+  },
+  "files": [
+    ".dist",
+    "bin"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.5.10",
+    "@electric-sql/pglite-socket": "^0.2.13",
+    "@ts-safeql/generate": "5.4.1",
+    "jiti": "^2.7.0",
+    "libpg-query": "18.1.5",
+    "objectively": "^0.3.0",
+    "postgres": "^3.4.9",
+    "@bezoar/pglite": "0.0.1",
+    "@bezoar/core": "0.0.1",
+    "@bezoar/schema": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.9"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }