@agentplate/cli 1.0.0

package/src/deploy/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Deploy target adapter contract.
+ *
+ * A *DeployTarget* is the pluggable mechanism for shipping an app to one place
+ * (Docker+GHA, a PaaS, a cloud, Kubernetes, on-prem). It mirrors the runtime
+ * adapter split: pure mechanics, no AI, one file per target, resolved by a
+ * registry. The staged agent pipeline (architect → builder → devops → deployer →
+ * verifier) *calls* these methods; it never embeds target-specific shell.
+ *
+ * Secrets flow through {@link DeployTarget.buildSecretEnv} (env-by-name, never
+ * hardcoded), exactly like the runtime adapters' `buildEnv`.
+ */
+
+/** A secret store handle: resolve a deploy secret value by its env-var name. */
+export interface DeploySecretStore {
+	/** Get a secret value by env-var name (file store, then process.env). */
+	get(key: string): string | undefined;
+	/** Is a secret available for this env-var name? */
+	has(key: string): boolean;
+}
+
+/** What kind of app a target detected — drives config generation. Project-agnostic. */
+export interface AppProfile {
+	language:
+		| "node"
+		| "bun"
+		| "python"
+		| "go"
+		| "rust"
+		| "java"
+		| "ruby"
+		| "php"
+		| "static"
+		| "unknown";
+	/** Framework if detectable (next, vite, fastapi, django, …). */
+	framework: string | null;
+	/** Long-running server | static site | batch job | serverless function. */
+	kind: "service" | "static" | "job" | "function";
+	/** Build command, or null when none is needed. */
+	buildCommand: string | null;
+	/** Start command for a service, or null. */
+	startCommand: string | null;
+	/** Listen port if known. */
+	port: number | null;
+	/** Detected lockfile family ("bun.lock", "package-lock.json", …). */
+	packageManager: string | null;
+	/** Runtime env var NAMES the app expects (never values). */
+	runtimeEnvKeys: string[];
+}
+
+/** Result of {@link DeployTarget.detect}. */
+export interface DetectResult {
+	fit: boolean;
+	/** 0..1 confidence used to rank targets when auto-selecting. */
+	confidence: number;
+	profile: AppProfile;
+	reason: string;
+}
+
+/** A file the adapter wants written into the worktree. */
+export interface GeneratedArtifact {
+	/** Path RELATIVE to the worktree root (e.g. "Dockerfile"). */
+	path: string;
+	content: string;
+	/** File mode (default 0o644). */
+	mode?: number;
+	kind: "dockerfile" | "ci" | "iac" | "manifest" | "helm" | "script" | "config" | "ignore";
+}
+
+/** Output of {@link DeployTarget.generateConfig}. */
+export interface GeneratedConfig {
+	artifacts: GeneratedArtifact[];
+	/** Secret env-var NAMES this config needs at deploy time (names only). */
+	requiredSecretKeys: string[];
+	summary: string;
+}
+
+/** Everything a deploy/verify/rollback step needs. */
+export interface DeployContext {
+	target: string;
+	/** "preview" | "staging" | "production" (extensible per target). */
+	environment: string;
+	worktreePath: string;
+	projectRoot: string;
+	profile: AppProfile;
+	/** Resolved secret env (KEY→value). Never persisted, never logged. */
+	secretEnv: Record<string, string>;
+	/** Non-secret target settings from config. */
+	settings: Record<string, string | number | boolean>;
+	/** When true: generate + plan only; no outward-facing mutation. */
+	dryRun: boolean;
+	runId: string | null;
+	agentName: string;
+}
+
+/** Result of a deploy/rollback execution. */
+export interface DeployResult {
+	ok: boolean;
+	/** Live URL(s) the deploy produced (empty for non-URL targets). */
+	urls: string[];
+	/** Provider deployment id used by rollback (image digest, release, …). */
+	deploymentId: string | null;
+	/** Captured CLI output tail (already secret-redacted). */
+	log: string;
+	outputs: Record<string, string>;
+	errorMessage: string | null;
+}
+
+/** Health/smoke-check outcome from {@link DeployTarget.verify}. */
+export interface VerifyResult {
+	healthy: boolean;
+	checks: Array<{ name: string; ok: boolean; detail: string }>;
+	probedUrl: string | null;
+}
+
+/** Capability guards declared by a target (checked by the engine before phases). */
+export interface DeployCaps {
+	canRollback: boolean;
+	/** Irreversible in practice → always force a confirm gate. */
+	irreversible: boolean;
+	environments: string[];
+	requiresCredentials: boolean;
+}
+
+/** The contract every deploy target implements (shaped like AgentRuntime). */
+export interface DeployTarget {
+	id: string;
+	readonly stability: "stable" | "beta" | "experimental";
+	readonly label: string;
+	readonly description: string;
+	readonly caps: DeployCaps;
+
+	/** Inspect a project dir and decide fit + app profile. Read-only. */
+	detect(projectDir: string): Promise<DetectResult>;
+
+	/** Emit config artifacts (engine writes them, so --dry-run can diff). */
+	generateConfig(ctx: DeployContext): Promise<GeneratedConfig>;
+
+	/** Execute the deployment (the only outward-facing mutation; honors dryRun). */
+	deploy(ctx: DeployContext): Promise<DeployResult>;
+
+	/** Smoke-test / health-check the live target. Read-only. */
+	verify(ctx: DeployContext, deployment: DeployResult): Promise<VerifyResult>;
+
+	/** Best-effort rollback (caps.canRollback honest). */
+	rollback(ctx: DeployContext, deployment: DeployResult): Promise<DeployResult>;
+
+	/** Build the secret env map from named env vars (the deploy buildEnv). */
+	buildSecretEnv(store: DeploySecretStore): Record<string, string>;
+
+	/** Optional: verify CLI + creds without deploying (for doctor). */
+	preflight?(ctx: DeployContext): Promise<Array<{ name: string; ok: boolean; detail: string }>>;
+}

package/src/errors.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import {
+	AgentplateError,
+	ConfigError,
+	isAgentplateError,
+	NotFoundError,
+	SubprocessError,
+	ValidationError,
+} from "./errors.ts";
+
+describe("errors", () => {
+	test("AgentplateError carries code and exitCode", () => {
+		const err = new AgentplateError("boom");
+		expect(err.code).toBe("AGENTPLATE_ERROR");
+		expect(err.exitCode).toBe(1);
+		expect(err.message).toBe("boom");
+		expect(err.name).toBe("AgentplateError");
+	});
+
+	test("subclasses set stable codes and exit codes", () => {
+		expect(new ConfigError("x").code).toBe("CONFIG_ERROR");
+		expect(new ValidationError("x").code).toBe("VALIDATION_ERROR");
+		expect(new ValidationError("x").exitCode).toBe(2);
+		expect(new NotFoundError("x").exitCode).toBe(4);
+	});
+
+	test("subclass names reflect the class", () => {
+		expect(new ConfigError("x").name).toBe("ConfigError");
+	});
+
+	test("SubprocessError preserves the child exit code", () => {
+		const err = new SubprocessError("git failed", 128);
+		expect(err.subprocessExitCode).toBe(128);
+		expect(err.code).toBe("SUBPROCESS_ERROR");
+	});
+
+	test("isAgentplateError narrows correctly", () => {
+		expect(isAgentplateError(new ConfigError("x"))).toBe(true);
+		expect(isAgentplateError(new Error("plain"))).toBe(false);
+		expect(isAgentplateError("nope")).toBe(false);
+	});
+});

package/src/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * Custom error types for Agentplate.
+ *
+ * All Agentplate errors extend {@link AgentplateError}, which carries a stable string
+ * `code` (for JSON output / programmatic handling) and an `exitCode` used by the
+ * CLI entry point when terminating the process. Throw these from anywhere; the
+ * top-level handler in `src/index.ts` formats them consistently.
+ */
+
+/** Base class for every error Agentplate raises intentionally. */
+export class AgentplateError extends Error {
+	/** Stable, machine-readable error code (e.g. "CONFIG_ERROR"). */
+	readonly code: string;
+	/** Process exit code the CLI should use for this error. */
+	readonly exitCode: number;
+
+	constructor(message: string, code = "AGENTPLATE_ERROR", exitCode = 1) {
+		super(message);
+		this.name = new.target.name;
+		this.code = code;
+		this.exitCode = exitCode;
+		// Maintains a clean stack trace where supported.
+		Error.captureStackTrace?.(this, new.target);
+	}
+}
+
+/** Configuration is missing, malformed, or fails validation. */
+export class ConfigError extends AgentplateError {
+	constructor(message: string) {
+		super(message, "CONFIG_ERROR", 1);
+	}
+}
+
+/** A user-supplied value (flag, argument, input) is invalid. */
+export class ValidationError extends AgentplateError {
+	constructor(message: string) {
+		super(message, "VALIDATION_ERROR", 2);
+	}
+}
+
+/** A git worktree operation failed. */
+export class WorktreeError extends AgentplateError {
+	constructor(message: string) {
+		super(message, "WORKTREE_ERROR", 1);
+	}
+}
+
+/** An external subprocess (git, a runtime CLI, a deploy CLI) failed. */
+export class SubprocessError extends AgentplateError {
+	/** Exit code reported by the failed subprocess, if known. */
+	readonly subprocessExitCode: number | null;
+
+	constructor(message: string, subprocessExitCode: number | null = null) {
+		super(message, "SUBPROCESS_ERROR", 1);
+		this.subprocessExitCode = subprocessExitCode;
+	}
+}
+
+/** A requested resource (agent, session, skill, target) could not be found. */
+export class NotFoundError extends AgentplateError {
+	constructor(message: string) {
+		super(message, "NOT_FOUND", 4);
+	}
+}
+
+/** Type guard: is the given value a AgentplateError? */
+export function isAgentplateError(value: unknown): value is AgentplateError {
+	return value instanceof AgentplateError;
+}

package/src/events/store.test.ts

@@ -0,0 +1,183 @@
+// Tests for the events SQLite store.
+//
+// We use a real in-memory SQLite database (":memory:") per test — no mocks. The
+// store's only side effects are SQL writes, so an in-memory DB exercises the
+// real code path (schema creation, inserts, filtered SELECTs) with no cleanup.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { EventStore } from "./store.ts";
+import { createEventStore } from "./store.ts";
+
+describe("createEventStore", () => {
+	let store: EventStore;
+
+	beforeEach(() => {
+		store = createEventStore(":memory:");
+	});
+
+	afterEach(() => {
+		store.close();
+	});
+
+	test("record assigns an id and createdAt and echoes input fields", () => {
+		const rec = store.record({
+			agentName: "builder-1",
+			runId: "run-abc",
+			type: "tool-start",
+			tool: "Bash",
+			detail: "ls -la",
+		});
+
+		// id should be a UUID-shaped string.
+		expect(typeof rec.id).toBe("string");
+		expect(rec.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+
+		// createdAt should be a valid ISO-8601 timestamp.
+		expect(typeof rec.createdAt).toBe("string");
+		expect(new Date(rec.createdAt).toISOString()).toBe(rec.createdAt);
+
+		// Input fields round-trip.
+		expect(rec.agentName).toBe("builder-1");
+		expect(rec.runId).toBe("run-abc");
+		expect(rec.type).toBe("tool-start");
+		expect(rec.tool).toBe("Bash");
+		expect(rec.detail).toBe("ls -la");
+	});
+
+	test("record normalises omitted optional fields to null", () => {
+		const rec = store.record({ agentName: "scout-1", type: "session-start" });
+
+		expect(rec.runId).toBeNull();
+		expect(rec.tool).toBeNull();
+		expect(rec.detail).toBeNull();
+	});
+
+	test("record assigns unique ids across calls", () => {
+		const a = store.record({ agentName: "a", type: "x" });
+		const b = store.record({ agentName: "a", type: "x" });
+		expect(a.id).not.toBe(b.id);
+	});
+
+	test("list returns events newest first", () => {
+		// Insert in a known order; the third insert is the most recent.
+		store.record({ agentName: "a", type: "first" });
+		store.record({ agentName: "a", type: "second" });
+		store.record({ agentName: "a", type: "third" });
+
+		const events = store.list();
+		expect(events.length).toBe(3);
+		// Newest first => reverse of insertion order.
+		expect(events.map((e) => e.type)).toEqual(["third", "second", "first"]);
+
+		// createdAt should be monotonically non-increasing down the list.
+		for (let i = 1; i < events.length; i++) {
+			const prev = events[i - 1];
+			const curr = events[i];
+			expect(prev).toBeDefined();
+			expect(curr).toBeDefined();
+			if (prev && curr) {
+				expect(prev.createdAt >= curr.createdAt).toBe(true);
+			}
+		}
+	});
+
+	test("list filters by agentName", () => {
+		store.record({ agentName: "builder", type: "t" });
+		store.record({ agentName: "scout", type: "t" });
+		store.record({ agentName: "builder", type: "t" });
+
+		const builderEvents = store.list({ agentName: "builder" });
+		expect(builderEvents.length).toBe(2);
+		expect(builderEvents.every((e) => e.agentName === "builder")).toBe(true);
+
+		const scoutEvents = store.list({ agentName: "scout" });
+		expect(scoutEvents.length).toBe(1);
+		expect(scoutEvents[0]?.agentName).toBe("scout");
+	});
+
+	test("list filters by runId", () => {
+		store.record({ agentName: "a", runId: "run-1", type: "t" });
+		store.record({ agentName: "a", runId: "run-2", type: "t" });
+		store.record({ agentName: "a", runId: "run-1", type: "t" });
+
+		const run1 = store.list({ runId: "run-1" });
+		expect(run1.length).toBe(2);
+		expect(run1.every((e) => e.runId === "run-1")).toBe(true);
+	});
+
+	test("list filters by type", () => {
+		store.record({ agentName: "a", type: "tool-start" });
+		store.record({ agentName: "a", type: "tool-end" });
+		store.record({ agentName: "a", type: "tool-start" });
+
+		const starts = store.list({ type: "tool-start" });
+		expect(starts.length).toBe(2);
+		expect(starts.every((e) => e.type === "tool-start")).toBe(true);
+	});
+
+	test("list combines multiple filters with AND", () => {
+		store.record({ agentName: "builder", runId: "run-1", type: "tool-start" });
+		store.record({ agentName: "builder", runId: "run-1", type: "tool-end" });
+		store.record({ agentName: "builder", runId: "run-2", type: "tool-start" });
+		store.record({ agentName: "scout", runId: "run-1", type: "tool-start" });
+
+		const matched = store.list({
+			agentName: "builder",
+			runId: "run-1",
+			type: "tool-start",
+		});
+		expect(matched.length).toBe(1);
+		expect(matched[0]?.agentName).toBe("builder");
+		expect(matched[0]?.runId).toBe("run-1");
+		expect(matched[0]?.type).toBe("tool-start");
+	});
+
+	test("list applies a positive limit and keeps newest-first ordering", () => {
+		store.record({ agentName: "a", type: "1" });
+		store.record({ agentName: "a", type: "2" });
+		store.record({ agentName: "a", type: "3" });
+		store.record({ agentName: "a", type: "4" });
+
+		const limited = store.list({ limit: 2 });
+		expect(limited.length).toBe(2);
+		// The two newest events.
+		expect(limited.map((e) => e.type)).toEqual(["4", "3"]);
+	});
+
+	test("list with a limit larger than the row count returns all rows", () => {
+		store.record({ agentName: "a", type: "1" });
+		store.record({ agentName: "a", type: "2" });
+
+		const events = store.list({ limit: 100 });
+		expect(events.length).toBe(2);
+	});
+
+	test("list treats non-positive limit as no limit", () => {
+		store.record({ agentName: "a", type: "1" });
+		store.record({ agentName: "a", type: "2" });
+		store.record({ agentName: "a", type: "3" });
+
+		// 0 and negative should not silently truncate to nothing.
+		expect(store.list({ limit: 0 }).length).toBe(3);
+		expect(store.list({ limit: -5 }).length).toBe(3);
+	});
+
+	test("list on an empty store returns an empty array", () => {
+		expect(store.list()).toEqual([]);
+		expect(store.list({ agentName: "nobody" })).toEqual([]);
+	});
+
+	test("filter + limit compose correctly", () => {
+		// 3 builder events, 1 scout event interleaved.
+		store.record({ agentName: "builder", type: "a" });
+		store.record({ agentName: "scout", type: "a" });
+		store.record({ agentName: "builder", type: "b" });
+		store.record({ agentName: "builder", type: "c" });
+
+		const limited = store.list({ agentName: "builder", limit: 2 });
+		expect(limited.length).toBe(2);
+		expect(limited.every((e) => e.agentName === "builder")).toBe(true);
+		// Newest two builder events.
+		expect(limited.map((e) => e.type)).toEqual(["c", "b"]);
+	});
+});

package/src/events/store.ts

@@ -0,0 +1,201 @@
+// Events SQLite store.
+//
+// A deliberately small, single-table event log for agent activity. Each row is
+// an `EventRecord` (see src/types.ts): an append-only fact about what an agent
+// did (a tool call, a state transition, etc.). The store is intentionally much
+// simpler than agentplate's blueprint — no timelines, no error rollups, no
+// arg filtering. It exists so observability commands (feed/trace/errors) have a
+// uniform place to read from, and so multiple agents can append concurrently.
+//
+// WHY a single insert + one filtered SELECT: high-frequency writes from many
+// worktrees dominate this workload, so we keep the schema flat and let WAL mode
+// (configured by openDatabase) handle concurrency. Filtering/limiting is pushed
+// into SQL so callers never load the whole log into memory.
+
+import type { Database } from "bun:sqlite";
+import { openDatabase } from "../db/sqlite.ts";
+import type { EventRecord } from "../types.ts";
+
+/** Input accepted by `record()`. `id`/`createdAt` are assigned by the store. */
+export interface RecordEventInput {
+	agentName: string;
+	// Optional run grouping. `undefined` and `null` are treated identically and
+	// stored as SQL NULL so "no run" is a single canonical value.
+	runId?: string | null;
+	type: string;
+	// Optional tool name (e.g. "Bash", "Edit") and free-form detail string.
+	tool?: string | null;
+	detail?: string | null;
+}
+
+/** Filters for `list()`. All fields are optional; omitted fields are ignored. */
+export interface ListEventsFilter {
+	agentName?: string;
+	runId?: string;
+	type?: string;
+	// Max rows to return. Must be a positive integer when provided; otherwise the
+	// whole (filtered) log is returned newest-first.
+	limit?: number;
+}
+
+/** Public surface returned by {@link createEventStore}. */
+export interface EventStore {
+	record(event: RecordEventInput): EventRecord;
+	list(filter?: ListEventsFilter): EventRecord[];
+	close(): void;
+}
+
+// Raw column shape as returned by bun:sqlite. SQLite has no boolean/null typing
+// at the JS boundary beyond "value or null", so we map TEXT columns to
+// `string | null` and convert to the `EventRecord` shape in one place.
+//
+// `seq` is an internal, monotonically increasing insertion counter (autoincrement
+// rowid). It is NOT part of the public `EventRecord` — it exists solely so we can
+// order strictly by insertion order. We can't rely on `created_at` for ordering
+// because many events can land in the same millisecond (ISO-8601 has ms
+// resolution), and the public `id` is a random UUID with no temporal meaning.
+interface EventRow {
+	seq: number;
+	id: string;
+	agent_name: string;
+	run_id: string | null;
+	type: string;
+	tool: string | null;
+	detail: string | null;
+	created_at: string;
+}
+
+// Translate a DB row into the shared `EventRecord` type. Centralised so the
+// snake_case <-> camelCase mapping lives in exactly one spot. `seq` is dropped
+// here because it is an internal ordering key, not part of the public contract.
+function rowToRecord(row: EventRow): EventRecord {
+	return {
+		id: row.id,
+		agentName: row.agent_name,
+		runId: row.run_id,
+		type: row.type,
+		tool: row.tool,
+		detail: row.detail,
+		createdAt: row.created_at,
+	};
+}
+
+/**
+ * Open (creating if needed) the events store at `dbPath`.
+ *
+ * `dbPath` may be ":memory:" for tests or an absolute file path in a project's
+ * `.agentplate/` directory. The table is created on open so callers never need a
+ * separate migration step.
+ */
+export function createEventStore(dbPath: string): EventStore {
+	// Guard on `events.seq` against an incompatible foreign `events` table.
+	const db: Database = openDatabase(dbPath, { guard: { table: "events", columns: ["seq"] } });
+
+	// Flat schema. `seq` (INTEGER PRIMARY KEY AUTOINCREMENT) is the canonical
+	// insertion-order key we sort by — see EventRow for why created_at/id can't
+	// serve that role. `id` is the public UUID, kept UNIQUE so callers can look up
+	// by it. `created_at` is an ISO-8601 string (lexically sortable, used only for
+	// display and time-range filtering, not as the primary sort key).
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS events (
+			seq INTEGER PRIMARY KEY AUTOINCREMENT,
+			id TEXT NOT NULL UNIQUE,
+			agent_name TEXT NOT NULL,
+			run_id TEXT,
+			type TEXT NOT NULL,
+			tool TEXT,
+			detail TEXT,
+			created_at TEXT NOT NULL
+		)
+	`);
+
+	// Index the columns we filter by. Ordering is on `seq` (the PRIMARY KEY), which
+	// is already indexed, so no extra index is needed for the newest-first sort.
+	db.exec("CREATE INDEX IF NOT EXISTS idx_events_agent ON events(agent_name)");
+	db.exec("CREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id)");
+
+	function record(event: RecordEventInput): EventRecord {
+		// Assign identity + timestamp here so callers stay declarative. UUID is the
+		// public id; ISO-8601 keeps timestamps human-readable. `seq` is omitted from
+		// the insert — SQLite autoincrements it.
+		const record: EventRecord = {
+			id: crypto.randomUUID(),
+			agentName: event.agentName,
+			// Normalise `undefined` -> `null` so the column is always an explicit value.
+			runId: event.runId ?? null,
+			type: event.type,
+			tool: event.tool ?? null,
+			detail: event.detail ?? null,
+			createdAt: new Date().toISOString(),
+		};
+
+		db.query(
+			`INSERT INTO events (id, agent_name, run_id, type, tool, detail, created_at)
+			 VALUES ($id, $agent_name, $run_id, $type, $tool, $detail, $created_at)`,
+		).run({
+			$id: record.id,
+			$agent_name: record.agentName,
+			$run_id: record.runId,
+			$type: record.type,
+			$tool: record.tool,
+			$detail: record.detail,
+			$created_at: record.createdAt,
+		});
+
+		// We already hold every public field, so return directly rather than reading
+		// the row back (the only thing the DB added is the internal `seq`).
+		return record;
+	}
+
+	function list(filter: ListEventsFilter = {}): EventRecord[] {
+		// Build the WHERE clause from only the provided filters. Using named
+		// parameters keeps the query injection-safe and lets us add clauses
+		// conditionally without positional bookkeeping.
+		const clauses: string[] = [];
+		// Bind values can be strings (filters) or a number (limit), so the map is
+		// typed accordingly. Building one params object keeps binding injection-safe.
+		const params: Record<string, string | number> = {};
+
+		if (filter.agentName !== undefined) {
+			clauses.push("agent_name = $agent_name");
+			params.$agent_name = filter.agentName;
+		}
+		if (filter.runId !== undefined) {
+			clauses.push("run_id = $run_id");
+			params.$run_id = filter.runId;
+		}
+		if (filter.type !== undefined) {
+			clauses.push("type = $type");
+			params.$type = filter.type;
+		}
+
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+
+		// Order strictly by `seq DESC` (insertion order, newest first). This is
+		// deterministic even when many events share a millisecond `created_at` — see
+		// EventRow for the rationale.
+		let sql = `SELECT seq, id, agent_name, run_id, type, tool, detail, created_at
+		           FROM events ${where}
+		           ORDER BY seq DESC`;
+
+		// Only apply LIMIT for a positive, finite integer. Anything else (0,
+		// negative, NaN, undefined) is treated as "no limit" rather than silently
+		// returning nothing or erroring. Capturing into a local `const` lets TS
+		// narrow it to `number` for the bind below.
+		const { limit } = filter;
+		if (typeof limit === "number" && Number.isInteger(limit) && limit > 0) {
+			sql += " LIMIT $limit";
+			params.$limit = limit;
+		}
+
+		const rows = db.query(sql).all(params) as EventRow[];
+
+		return rows.map(rowToRecord);
+	}
+
+	function close(): void {
+		db.close();
+	}
+
+	return { record, list, close };
+}