@pvidaal07/heydb 0.0.0-stage → 2.0.0-beta.1

package/lib/store/envfile.ts

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ENV_FILE, PASSWORD_REFERENCE, REFERENCE_RULE, parseEnvFile, parseEnvLine } from "../secrets.ts";
+import { writeFileAtomic } from "./files.ts";
+import { assertNoSymlinks } from "./guards.ts";
+import { HEYDB_DIR } from "./project.ts";
+
+// Writes .heydb/.env, the one file where heydb keeps a secret: the password a
+// person typed, so they do not have to set a variable by hand. The file is
+// local (.heydb/.gitignore excludes it; callers make sure of that before
+// writing) and readable by its owner only. Every line heydb does not own is
+// kept byte for byte: the file is also the person's own.
+//
+// What it does not protect: anyone who can read files as this user, or the
+// disk itself, can read the password. The system keychain would; it remains
+// a future option (ADR-0005).
+
+/** Owner read and write only. Windows ignores it: there the folder's permissions apply. */
+const OWNER_ONLY = 0o600;
+
+/**
+ * The line that stores `value` under `name`, encoded so parseEnvFile reads
+ * back exactly `value`. That reader trims the value and strips one pair of
+ * matching quotes around it, without escapes. So quotes are needed only when
+ * something would otherwise be lost: whitespace at either end, or a quote at
+ * the start that could be taken for a pair. A leading "#" is quoted too, so no
+ * .env reader mistakes the value for a comment. Inside the quotes nothing is
+ * special (parseEnvFile only looks at the first and last character), so a
+ * value with both kinds of quote is fine. A line break is the one thing the
+ * format cannot hold.
+ */
+export function envLine(name: string, value: string): string {
+	assertVariable(name);
+	if (/[\r\n]/.test(value)) {
+		// Never the value: it is a password.
+		throw new Error(`the value for ${name} has a line break, which .heydb/.env cannot hold: set ${name} in your shell instead`);
+	}
+	if (value === value.trim() && !/^["'#]/.test(value)) return `${name}=${value}`;
+	const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+	return `${name}=${quote}${value}${quote}`;
+}
+
+/**
+ * Sets `name` in .heydb/.env: replaces the definition that counts (the last)
+ * and removes the earlier ones, so an old password does not stay in the file;
+ * appends one when there is none.
+ */
+export function setEnvValue(projectRoot: string, name: string, value: string): void {
+	const line = envLine(name, value);
+	const text = readEnvText(projectRoot) ?? "";
+	const lines = text.split("\n");
+	const index = lines.findLastIndex((raw, at) => keyOf(raw, at) === name);
+
+	let next: string;
+	if (index === -1) {
+		const newline = text.includes("\r\n") ? "\r\n" : "\n";
+		const separator = text === "" || text.endsWith("\n") ? "" : newline;
+		next = `${text}${separator}${line}${newline}`;
+	} else {
+		const old = lines[index] as string;
+		const bom = index === 0 && old.startsWith("\uFEFF") ? "\uFEFF" : "";
+		lines[index] = `${bom}${line}${old.endsWith("\r") ? "\r" : ""}`;
+		next = withoutDefinitions(lines, name, index);
+	}
+
+	// The proof, before anything is written: the file as heydb will read it
+	// gives back exactly this value. It also refuses a file with lines that
+	// are not KEY=VALUE, reporting their number only.
+	if (parseEnvFile(next)[name] !== value) {
+		throw new Error(`${name} could not be written to .heydb/.env so that it reads back the same: set it in your shell instead`);
+	}
+	writeFileAtomic(envPath(projectRoot), next, OWNER_ONLY);
+}
+
+/** Removes every definition of `name`; false when there was none (or no file). */
+export function removeEnvValue(projectRoot: string, name: string): boolean {
+	assertVariable(name);
+	const text = readEnvText(projectRoot);
+	if (text === null) return false;
+	const lines = text.split("\n");
+	if (!lines.some((raw, at) => keyOf(raw, at) === name)) return false;
+	writeFileAtomic(envPath(projectRoot), withoutDefinitions(lines, name), OWNER_ONLY);
+	return true;
+}
+
+/**
+ * The file without the lines that define `name`, except the one at `keep`.
+ * Every other line is kept byte for byte, and the byte order mark stays at
+ * the start of the file even when the first line goes.
+ */
+function withoutDefinitions(lines: readonly string[], name: string, keep = -1): string {
+	const bom = lines[0]?.startsWith("\uFEFF") ? "\uFEFF" : "";
+	const kept = lines
+		.map((raw, at) => (at === 0 ? raw.slice(bom.length) : raw))
+		.filter((raw, at) => at === keep || parseEnvLine(raw)?.key !== name);
+	return `${bom}${kept.join("\n")}`;
+}
+
+function envPath(projectRoot: string): string {
+	return join(projectRoot, HEYDB_DIR, ENV_FILE);
+}
+
+/** The file's text, or null when it does not exist. */
+function readEnvText(projectRoot: string): string | null {
+	// A committed symbolic link could point .env at any file on this machine.
+	assertNoSymlinks(projectRoot, ENV_FILE);
+	try {
+		return readFileSync(envPath(projectRoot), "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+/** The name a line defines, read exactly as parseEnvFile reads it (byte order mark included). */
+function keyOf(raw: string, index: number): string | undefined {
+	return parseEnvLine(index === 0 ? raw.replace(/^\uFEFF/, "") : raw)?.key;
+}
+
+// The same rule as references in config.json: heydb only ever touches its own variables.
+function assertVariable(name: string): void {
+	if (!PASSWORD_REFERENCE.test(`env:${name}`)) throw new Error(`${JSON.stringify(name)} is not a heydb variable: ${REFERENCE_RULE}`);
+}

package/lib/store/files.ts

@@ -0,0 +1,57 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Writes the whole file or nothing. The content goes to a temporary file in
+ * the same directory, is flushed to disk (fsync), and is then renamed over the
+ * target. A rename within one directory is atomic, so if heydb crashes the
+ * target is either the old file or the new one, never half of each. After a
+ * power loss the rename itself may be lost (the old file remains): the
+ * directory is not flushed, because Windows does not support that.
+ *
+ * `mode` sets the permissions of the new file (0o600 for secrets). It is
+ * applied when the temporary file is created, so the content is never
+ * readable by others, not even for an instant. Windows only honors the
+ * read-only bit, so there the file keeps the folder's permissions.
+ *
+ * A string is written as UTF-8; bytes (a compressed file) as they are.
+ */
+export function writeFileAtomic(path: string, content: string | Uint8Array, mode?: number): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	try {
+		const fd = openSync(temporary, "w", mode);
+		try {
+			if (typeof content === "string") writeSync(fd, content, null, "utf8");
+			else writeSync(fd, content);
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(temporary, path);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+
+/**
+ * JSON with object keys sorted alphabetically, two-space indentation and a
+ * final newline. The same data always produces the same bytes, whatever order
+ * the code built the objects in, so git diffs only show real changes.
+ * Array order is kept: sort arrays before calling this when their order is
+ * not meaningful.
+ */
+export function stableJson(value: unknown): string {
+	return `${JSON.stringify(value, sortKeys, 2)}\n`;
+}
+
+function sortKeys(_key: string, value: unknown): unknown {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+	const sorted: Record<string, unknown> = {};
+	for (const key of Object.keys(value).sort()) {
+		sorted[key] = (value as Record<string, unknown>)[key];
+	}
+	return sorted;
+}

package/lib/store/guards.ts

@@ -0,0 +1,68 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+
+import { HEYDB_DIR } from "./project.ts";
+
+// Safety checks shared by every file heydb keeps under .heydb/. Keeping them
+// in one place means snapshots and knowledge can never drift apart.
+
+// The connection name becomes a file name, so it is an allow-list:
+// - no path separators or dots, so it can never point outside .heydb/ ("../evil");
+// - lowercase only, because "Prod" and "prod" are the same file on macOS and Windows;
+// - none of the device names Windows reserves (a file "nul.json" cannot be checked out there).
+const CONNECTION_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/;
+
+export function assertConnectionName(name: string): void {
+	if (!CONNECTION_NAME.test(name)) {
+		throw new Error(
+			`invalid connection name ${JSON.stringify(name)}: use 1-64 lowercase letters, digits, "-" or "_", starting with a letter or digit`,
+		);
+	}
+	if (WINDOWS_RESERVED.test(name)) {
+		throw new Error(`invalid connection name ${JSON.stringify(name)}: reserved name on Windows`);
+	}
+}
+
+/**
+ * Turns what a person typed ("Acme", "Prod EU", "Producción") into a name
+ * assertConnectionName accepts ("acme", "prod-eu", "produccion"), so the
+ * rule protects the files without getting in the user's way. Returns null
+ * when nothing usable is left.
+ */
+export function toConnectionName(input: string): string | null {
+	let name = input
+		.normalize("NFD")
+		.replace(/\p{M}/gu, "") // accents: "ó" → "o"
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, "-") // spaces, dots and anything else become a dash
+		.replace(/-{2,}/g, "-")
+		.replace(/^[-_]+|[-_]+$/g, "")
+		.slice(0, 64)
+		.replace(/[-_]+$/, "");
+	if (name === "") return null;
+	if (WINDOWS_RESERVED.test(name)) name = `${name}-db`;
+	return name;
+}
+
+/**
+ * .heydb/ is committed, and git can commit symbolic links. A link named .heydb
+ * or .heydb/<entry> (a subdirectory such as "snapshots", or a file such as
+ * ".env") pointing elsewhere would make heydb read or overwrite files outside
+ * the project, so links are refused, never followed.
+ */
+export function assertNoSymlinks(projectRoot: string, entry: string): void {
+	for (const relative of [HEYDB_DIR, join(HEYDB_DIR, entry)]) {
+		if (isSymlink(join(projectRoot, relative))) {
+			throw new Error(`${relative.replaceAll("\\", "/")} is a symbolic link; heydb refuses to follow it`);
+		}
+	}
+}
+
+function isSymlink(path: string): boolean {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false; // does not exist yet
+	}
+}

package/lib/store/knowledge.ts

@@ -0,0 +1,139 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { emptyKnowledge, sortKnowledge } from "../knowledge/operations.ts";
+import type { Knowledge, RelationshipSide } from "../knowledge/types.ts";
+import { validateKnowledge, validateProjectKnowledge } from "../knowledge/validate.ts";
+import { stableJson, writeFileAtomic } from "./files.ts";
+import { assertConnectionName, assertNoSymlinks } from "./guards.ts";
+import { HEYDB_DIR } from "./project.ts";
+
+// Knowledge lives in <project>/.heydb/knowledge/<connection>.json, next to the
+// snapshot, and is committed too: a teammate gets the notes with a git pull.
+// One file per connection, not per table: table names are not safe file names
+// (dots, case, names Windows reserves). See ADR-0012.
+//
+// Project notes live next to them in _project.json: a connection name must
+// start with a letter or digit, so no connection can ever own that file.
+
+const SUPPORTED_FORMAT_VERSION = 1;
+const PROJECT_FILE = "_project.json";
+
+export function knowledgePath(projectRoot: string, connection: string): string {
+	assertConnectionName(connection);
+	return join(projectRoot, HEYDB_DIR, "knowledge", `${connection}.json`);
+}
+
+export function saveKnowledge(projectRoot: string, connection: string, knowledge: Knowledge): void {
+	const path = knowledgePath(projectRoot, connection);
+	assertNoSymlinks(projectRoot, "knowledge");
+	writeFileAtomic(path, stableJson(sortKnowledge(knowledge)));
+}
+
+/**
+ * Returns the stored knowledge; a connection nobody annotated yet has empty
+ * knowledge. A relationship side naming this same connection is the same as
+ * one naming none, so it comes back without it: "no connection" is the only
+ * way the rest of heydb has to say "this connection".
+ */
+export function loadKnowledge(projectRoot: string, connection: string): Knowledge {
+	// "knowledge/" in messages tells it apart from the snapshot, also called <connection>.json.
+	const knowledge = readKnowledge(projectRoot, knowledgePath(projectRoot, connection), `knowledge/${connection}.json`, validateKnowledge);
+	const own = (side: RelationshipSide): RelationshipSide =>
+		side.connection === connection ? { table: side.table, columns: side.columns } : side;
+	return {
+		...knowledge,
+		relationships: knowledge.relationships.map((item) => ({ ...item, from: own(item.from), to: own(item.to) })),
+	};
+}
+
+export function projectKnowledgePath(projectRoot: string): string {
+	return join(projectRoot, HEYDB_DIR, "knowledge", PROJECT_FILE);
+}
+
+/** Notes about the whole project; empty when there are none yet. */
+export function loadProjectKnowledge(projectRoot: string): Knowledge {
+	return readKnowledge(projectRoot, projectKnowledgePath(projectRoot), `knowledge/${PROJECT_FILE}`, validateProjectKnowledge);
+}
+
+/** Checked before writing, so a bug elsewhere can never store a database note where nobody looks for it. */
+export function saveProjectKnowledge(projectRoot: string, knowledge: Knowledge): void {
+	const checked = validateProjectKnowledge(sortKnowledge(knowledge));
+	assertNoSymlinks(projectRoot, "knowledge");
+	writeFileAtomic(projectKnowledgePath(projectRoot), stableJson(checked));
+}
+
+/**
+ * The connections that have a knowledge file, sorted: every <name>.json whose
+ * name is a valid connection name, whether or not it is still configured.
+ * The project file and anything else in the folder are left out.
+ */
+export function knowledgeConnections(projectRoot: string): string[] {
+	assertNoSymlinks(projectRoot, "knowledge");
+	let entries: string[];
+	try {
+		entries = readdirSync(join(projectRoot, HEYDB_DIR, "knowledge"));
+	} catch (error) {
+		if (isMissingFile(error)) return [];
+		throw error;
+	}
+	return entries
+		.filter((entry) => entry.endsWith(".json"))
+		.map((entry) => entry.slice(0, -".json".length))
+		.filter(isConnectionName)
+		.sort();
+}
+
+function isConnectionName(name: string): boolean {
+	try {
+		assertConnectionName(name);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function readKnowledge(projectRoot: string, path: string, fileName: string, validate: (data: unknown) => Knowledge): Knowledge {
+	assertNoSymlinks(projectRoot, "knowledge");
+
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return emptyKnowledge();
+		throw error;
+	}
+
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		throw new Error(`${fileName} is not valid JSON (${path})`);
+	}
+	return checkKnowledge(data, fileName, validate);
+}
+
+function checkKnowledge(data: unknown, fileName: string, validate: (data: unknown) => Knowledge): Knowledge {
+	if (data === null || typeof data !== "object" || Array.isArray(data)) {
+		throw new Error(`${fileName} is not a heydb knowledge file: expected a JSON object`);
+	}
+	const record = data as Record<string, unknown>;
+	if (!("formatVersion" in record)) {
+		throw new Error(`${fileName} is not a heydb knowledge file: missing "formatVersion"`);
+	}
+	if (record.formatVersion !== SUPPORTED_FORMAT_VERSION) {
+		throw new Error(
+			`${fileName}: unsupported knowledge formatVersion ${JSON.stringify(record.formatVersion)} (expected ${SUPPORTED_FORMAT_VERSION}); update heydb`,
+		);
+	}
+	try {
+		return validate(data);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${fileName} is not a heydb knowledge file: ${reason}`, { cause: error });
+	}
+}
+
+function isMissingFile(error: unknown): boolean {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/lib/store/project.ts

@@ -0,0 +1,28 @@
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Directory that marks a heydb project, like .git marks a git repository. */
+export const HEYDB_DIR = ".heydb";
+
+/**
+ * Walks up from `start` until it finds a directory containing `.heydb/`.
+ * Returns that directory, or null when no ancestor is a heydb project.
+ * This is how git finds its repository, so heydb works from any subfolder.
+ */
+export function findProjectRoot(start: string): string | null {
+	let current = start;
+	while (true) {
+		if (isDirectory(join(current, HEYDB_DIR))) return current;
+		const parent = dirname(current);
+		if (parent === current) return null; // reached the filesystem root
+		current = parent;
+	}
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false; // does not exist or cannot be read
+	}
+}

package/lib/store/snapshots.ts

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { constants, gunzipSync, gzipSync } from "node:zlib";
+
+import { sortSnapshot } from "../model/order.ts";
+import type { Snapshot } from "../model/snapshot.ts";
+import { validateSnapshot } from "../model/validate.ts";
+import { stableJson, writeFileAtomic } from "./files.ts";
+import { assertConnectionName, assertNoSymlinks } from "./guards.ts";
+import { HEYDB_DIR } from "./project.ts";
+
+// Snapshots live in <project>/.heydb/snapshots/<connection>.json.gz and are
+// meant to be committed: teammates without database credentials still get the
+// schema. The content is the same stable JSON earlier builds wrote as plain
+// <connection>.json, gzip-compressed: a schema with about 1,500 tables was
+// about 400,000 lines of JSON, which nobody reviews in a pull request.
+// Reading decompresses on every load: on 1,500 tables × 60 columns that is
+// ~13 ms of the ~75 ms a load takes (JSON.parse and validation are the rest),
+// so a decompressed local copy would save little and add a second file to
+// keep in step.
+
+const SUPPORTED_FORMAT_VERSION = 1;
+
+/** Where saveSnapshot writes: <connection>.json.gz. */
+export function snapshotPath(projectRoot: string, connection: string): string {
+	assertConnectionName(connection);
+	return join(projectRoot, HEYDB_DIR, "snapshots", `${connection}.json.gz`);
+}
+
+/** The plain <connection>.json earlier builds wrote; still read, replaced on the next save. */
+function legacySnapshotPath(projectRoot: string, connection: string): string {
+	assertConnectionName(connection);
+	return join(projectRoot, HEYDB_DIR, "snapshots", `${connection}.json`);
+}
+
+/** The file the snapshot of `connection` is read from, or null when it was never synced. */
+export function storedSnapshotPath(projectRoot: string, connection: string): string | null {
+	for (const path of [snapshotPath(projectRoot, connection), legacySnapshotPath(projectRoot, connection)]) {
+		if (existsSync(path)) return path;
+	}
+	return null;
+}
+
+export function saveSnapshot(projectRoot: string, connection: string, snapshot: Snapshot): void {
+	const path = snapshotPath(projectRoot, connection);
+	assertNoSymlinks(projectRoot, "snapshots");
+	writeFileAtomic(path, gzipStable(stableJson(sortSnapshot(snapshot))));
+	// Only after the new file is in place, so a failed write keeps the old one.
+	rmSync(legacySnapshotPath(projectRoot, connection), { force: true });
+}
+
+/**
+ * gzip with the header fields that depend on the machine fixed, so the same
+ * snapshot gives the same bytes everywhere: modification time 0 and no file
+ * name (what gzipSync already writes), and operating system 255, "unknown"
+ * (zlib writes the one it was built for: 3 on Linux, 19 on macOS). The
+ * compressed data itself depends only on the zlib build; a different one may
+ * pick other bytes for the same JSON, which is harmless because the file is
+ * only rewritten when the structure changed.
+ */
+function gzipStable(text: string): Buffer {
+	const bytes = gzipSync(text, { level: constants.Z_BEST_COMPRESSION });
+	bytes.writeUInt32LE(0, 4);
+	bytes[9] = 0xff;
+	return bytes;
+}
+
+/** Returns the stored snapshot, or null when this connection was never synced. */
+export function loadSnapshot(projectRoot: string, connection: string): Snapshot | null {
+	const path = snapshotPath(projectRoot, connection);
+	const legacyPath = legacySnapshotPath(projectRoot, connection);
+	assertNoSymlinks(projectRoot, "snapshots");
+
+	const compressed = readIfExists(path);
+	if (compressed !== null) {
+		const fileName = `${connection}.json.gz`;
+		let text: string;
+		try {
+			text = gunzipSync(compressed).toString("utf8");
+		} catch {
+			throw new Error(`${fileName} is not a valid gzip file (${path})`);
+		}
+		return parseSnapshot(text, fileName, path);
+	}
+	const plain = readIfExists(legacyPath);
+	if (plain === null) return null;
+	return parseSnapshot(plain.toString("utf8"), `${connection}.json`, legacyPath);
+}
+
+function readIfExists(path: string): Buffer | null {
+	try {
+		return readFileSync(path);
+	} catch (error) {
+		if (isMissingFile(error)) return null;
+		throw error;
+	}
+}
+
+function parseSnapshot(text: string, fileName: string, path: string): Snapshot {
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		throw new Error(`${fileName} is not valid JSON (${path})`);
+	}
+	return checkSnapshot(data, fileName);
+}
+
+// First the top-level checks, whose messages say what kind of file this is
+// (not a snapshot at all, or one from a newer heydb); then validateSnapshot
+// checks every field down to each column.
+function checkSnapshot(data: unknown, fileName: string): Snapshot {
+	if (data === null || typeof data !== "object" || Array.isArray(data)) {
+		throw new Error(`${fileName} is not a heydb snapshot: expected a JSON object`);
+	}
+	const record = data as Record<string, unknown>;
+	if (!("formatVersion" in record)) {
+		throw new Error(`${fileName} is not a heydb snapshot: missing "formatVersion"`);
+	}
+	if (record.formatVersion !== SUPPORTED_FORMAT_VERSION) {
+		throw new Error(
+			`${fileName}: unsupported snapshot formatVersion ${JSON.stringify(record.formatVersion)} (expected ${SUPPORTED_FORMAT_VERSION}); update heydb`,
+		);
+	}
+	for (const field of ["engine", "capturedAt", "databases", "warnings"]) {
+		if (!(field in record)) {
+			throw new Error(`${fileName} is not a heydb snapshot: missing "${field}"`);
+		}
+	}
+	if (!Array.isArray(record.databases) || !Array.isArray(record.warnings)) {
+		throw new Error(`${fileName} is not a heydb snapshot: "databases" and "warnings" must be lists`);
+	}
+	try {
+		return validateSnapshot(data);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${fileName} is not a heydb snapshot: ${reason}`, { cause: error });
+	}
+}
+
+function isMissingFile(error: unknown): boolean {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/lib/usecases/author.ts

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import { userInfo } from "node:os";
+
+// Every note carries its author, so a team can ask whoever wrote it. The name
+// comes from where people already set it, in this order:
+//   1. git user.name, read in the project folder (it may differ per repository);
+//   2. the HEYDB_AUTHOR environment variable, for machines without git config;
+//   3. the operating system user.
+// Entry points add their own suffix: notes written by an agent end in
+// "(via agent)", so a reader knows a person did not type them.
+
+const GIT_TIMEOUT_MS = 2000;
+
+export interface AuthorOptions {
+	readonly cwd: string;
+	readonly env?: Readonly<Record<string, string | undefined>>;
+	/** Returns git user.name for `cwd`, or null; replaced in tests so no git is needed. */
+	readonly runGit?: (cwd: string) => Promise<string | null>;
+	readonly osUser?: () => string;
+}
+
+export async function resolveAuthor(options: AuthorOptions): Promise<string> {
+	const { cwd, env = process.env, runGit = gitUserName, osUser = () => userInfo().username } = options;
+	const fromGit = (await runGit(cwd))?.trim();
+	if (fromGit) return fromGit;
+	const fromEnv = env.HEYDB_AUTHOR?.trim();
+	if (fromEnv) return fromEnv;
+	try {
+		const fromOs = osUser().trim();
+		if (fromOs) return fromOs;
+	} catch {
+		// Some containers have no user entry for the current uid.
+	}
+	return "unknown";
+}
+
+/**
+ * `git config user.name` in `cwd`, or null when git is missing, the folder is
+ * gone, the name is not set or git takes too long. execFile with an argument
+ * list never goes through a shell, so nothing in the path is interpreted.
+ */
+export function gitUserName(cwd: string): Promise<string | null> {
+	return new Promise((resolve) => {
+		execFile(
+			"git",
+			["config", "user.name"],
+			{ cwd, timeout: GIT_TIMEOUT_MS, shell: false, windowsHide: true, encoding: "utf8" },
+			(error, stdout) => resolve(error === null ? stdout : null),
+		);
+	});
+}