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

package/extensions/context.ts

@@ -0,0 +1,37 @@
+import type { BeforeAgentStartEvent, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { projectConnections } from "../lib/usecases/project.ts";
+
+// One line in the system prompt, only inside a heydb project, so the model
+// knows the schema is a tool call away before it writes SQL from memory.
+// It runs before every agent turn, so it stays cheap: it finds .heydb/ and
+// reads config.json, never a snapshot. Anything unexpected adds nothing; the
+// tools report problems when they are actually used.
+//
+// It sets a named prompt section instead of returning a new system prompt:
+// Pi compares sections between turns and only sends what changed, so an
+// unchanged line costs nothing after the first turn.
+
+export const PROMPT_SECTION = "heydb";
+
+export function heydbPromptLine(cwd: string): string | null {
+	let names: string[];
+	try {
+		names = projectConnections(cwd)?.names ?? [];
+	} catch {
+		return null;
+	}
+	if (names.length === 0) return null;
+	return (
+		`This project has a heydb schema snapshot (connections: ${names.join(", ")}). ` +
+		"Use heydb_overview, heydb_table and heydb_search before writing SQL."
+	);
+}
+
+export function createContextHandler() {
+	return (event: BeforeAgentStartEvent, ctx: ExtensionContext): undefined => {
+		const line = heydbPromptLine(ctx.cwd);
+		if (line !== null) event.systemPromptOptions.sections[PROMPT_SECTION] = line;
+		return undefined;
+	};
+}

package/extensions/deps.ts

@@ -0,0 +1,32 @@
+import { introspect } from "../lib/engines/index.ts";
+import type { KnowledgeOptions } from "../lib/knowledge/operations.ts";
+import type { CaptureOptions } from "../lib/usecases/project.ts";
+import { resolveAuthor } from "../lib/usecases/author.ts";
+
+// Everything the extension needs from the outside world, in one place. Pi
+// gets the real ones; tests pass fakes, so commands and tools run without a
+// database, git, the real clock or the process folder.
+
+export interface HeydbDeps {
+	/** Where password references are looked up first (then .heydb/.env). */
+	readonly env: Readonly<Record<string, string | undefined>>;
+	/** Captures a live schema. Only /heydb:sync and /heydb:status call it; tools never do. */
+	readonly introspect: NonNullable<CaptureOptions["introspect"]>;
+	/** The person behind the session, for the author of new notes. */
+	readonly author: (cwd: string) => Promise<string>;
+	/** Clock and id generator for new notes. */
+	readonly knowledge: KnowledgeOptions;
+	/** The folder argument completion looks in; Pi passes completions no context. */
+	readonly cwd: () => string;
+}
+
+export function defaultDeps(): HeydbDeps {
+	return {
+		env: process.env,
+		// The engine module loads its driver on first use (ADR-0006), so this costs nothing until a sync.
+		introspect,
+		author: (cwd) => resolveAuthor({ cwd }),
+		knowledge: {},
+		cwd: () => process.cwd(),
+	};
+}

package/extensions/heydb.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerHeydbCommands } from "./commands.ts";
+import { createContextHandler } from "./context.ts";
+import { type HeydbDeps, defaultDeps } from "./deps.ts";
+import { registerHeydbTools } from "./tools.ts";
+
+// Pi glue only: every behavior lives in lib/ so it stays testable and reusable
+// outside Pi. This file wires the pieces; each piece takes its dependencies
+// as an argument, so tests run them with fakes.
+
+export default function heydb(pi: ExtensionAPI): void {
+	registerHeydb(pi, defaultDeps());
+}
+
+export function registerHeydb(pi: ExtensionAPI, deps: HeydbDeps): void {
+	registerHeydbCommands(pi, deps);
+	registerHeydbTools(pi, deps);
+	pi.on("before_agent_start", createContextHandler());
+}

package/extensions/secret-input.ts

@@ -0,0 +1,120 @@
+import type { ExtensionCommandContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { type Component, type TUI, decodeKittyPrintable, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// A one-line input that never shows what is typed, for passwords. Pi's
+// ctx.ui.input() echoes every character, and it has no hidden mode, so this
+// is a small custom component shown through ctx.ui.custom().
+//
+// The key handling is a pure function, reduceSecret(state, key) → state, so
+// tests drive it key by key without a terminal; the component around it only
+// draws and forwards. The value lives in the component's state and is handed
+// to the caller on Enter: it is never rendered, logged or put in an error.
+
+export interface SecretState {
+	readonly value: string;
+	/** A bracketed paste still arriving in chunks; null when not pasting. */
+	readonly paste: string | null;
+	readonly outcome: "editing" | "submitted" | "cancelled";
+}
+
+export const EMPTY_SECRET: SecretState = { value: "", paste: null, outcome: "editing" };
+
+/** What reduceSecret needs from Pi's key table. */
+export type KeyMatcher = Pick<KeybindingsManager, "matches">;
+
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+const segmenter = new Intl.Segmenter();
+
+/** The next state after one chunk of terminal input. Never changes `state`. */
+export function reduceSecret(state: SecretState, data: string, keys: KeyMatcher): SecretState {
+	if (state.outcome !== "editing") return state;
+
+	// A pasted password arrives between bracket markers, possibly split over
+	// several chunks, and may end with a line break; like Pi's own input, the
+	// breaks are dropped and the paste is taken whole.
+	if (state.paste !== null || data.includes(PASTE_START)) {
+		const buffer = state.paste ?? "";
+		const incoming = state.paste === null ? data.slice(data.indexOf(PASTE_START) + PASTE_START.length) : data;
+		const pasted = buffer + incoming;
+		const end = pasted.indexOf(PASTE_END);
+		if (end === -1) return { ...state, paste: pasted };
+		const next = { ...state, value: state.value + pasted.slice(0, end).replace(/[\r\n]/g, ""), paste: null };
+		const rest = pasted.slice(end + PASTE_END.length);
+		return rest === "" ? next : reduceSecret(next, rest, keys);
+	}
+
+	if (keys.matches(data, "tui.select.cancel")) return { ...state, outcome: "cancelled" };
+	if (keys.matches(data, "tui.input.submit") || data === "\n") return { ...state, outcome: "submitted" };
+	if (keys.matches(data, "tui.editor.deleteCharBackward")) {
+		const graphemes = [...segmenter.segment(state.value)];
+		return { ...state, value: graphemes.slice(0, -1).map((item) => item.segment).join("") };
+	}
+	// Words cannot be seen, so deleting "a word" would delete an unknown part: these clear everything.
+	if (keys.matches(data, "tui.editor.deleteToLineStart") || keys.matches(data, "tui.editor.deleteWordBackward")) {
+		return { ...state, value: "" };
+	}
+
+	// Terminals with the Kitty keyboard protocol send even plain letters as escape sequences.
+	const printable = decodeKittyPrintable(data) ?? (hasControlCharacters(data) ? undefined : data);
+	return printable === undefined ? state : { ...state, value: state.value + printable };
+}
+
+function hasControlCharacters(data: string): boolean {
+	return [...data].some((char) => {
+		const code = char.charCodeAt(0);
+		return code < 32 || code === 0x7f || (code >= 0x80 && code <= 0x9f);
+	});
+}
+
+interface Theme {
+	fg(color: "accent" | "dim", text: string): string;
+}
+
+/**
+ * The component: a title, one "•" per character typed and a key hint. It
+ * calls `done` with the value on Enter and with undefined on Escape.
+ */
+export function createSecretInput(
+	title: string,
+	tui: Pick<TUI, "requestRender">,
+	theme: Theme,
+	keys: KeyMatcher,
+	done: (value: string | undefined) => void,
+): Component {
+	let state = EMPTY_SECRET;
+	return {
+		render(width: number): string[] {
+			const dots = "•".repeat([...segmenter.segment(state.value)].length);
+			// A long password shows its last dots, where the next one appears.
+			const visible = dots.length + 2 > width ? dots.slice(dots.length - Math.max(0, width - 3)) : dots;
+			return [
+				// The title says where the password goes, so it wraps instead of being cut.
+				...wrapTextWithAnsi(theme.fg("accent", title), width),
+				truncateToWidth(`> ${visible}`, width),
+				truncateToWidth(theme.fg("dim", "enter saves · esc cancels"), width),
+			];
+		},
+		handleInput(data: string): void {
+			state = reduceSecret(state, data, keys);
+			if (state.outcome === "submitted") return done(state.value);
+			if (state.outcome === "cancelled") return done(undefined);
+			tui.requestRender();
+		},
+		invalidate(): void {},
+	};
+}
+
+/**
+ * Asks for a secret with the masked input. Returns the value, undefined when
+ * the person pressed Escape, or null when Pi has no terminal UI to show it
+ * (RPC, print and JSON modes): the caller then explains how to set it instead.
+ */
+export async function askSecret(ctx: ExtensionCommandContext, title: string): Promise<string | undefined | null> {
+	if (ctx.mode !== "tui") return null;
+	return ctx.ui.custom<string | undefined>(
+		(tui, theme, keybindings, done) => createSecretInput(title, tui, theme, keybindings, done),
+		// Terminals that show program status then mark Pi as waiting for an answer.
+		{ blocked: { kind: "question", message: title } },
+	);
+}

package/extensions/tools.ts

@@ -0,0 +1,402 @@
+import type { AgentToolResult, ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import { knowledgeForTable } from "../lib/knowledge/query.ts";
+import type { Annotation, RelationshipSide } from "../lib/knowledge/types.ts";
+import { displayNameOf } from "../lib/model/names.ts";
+import { incomingReferences } from "../lib/model/references.ts";
+import { renderOverview, renderSearch, renderTable } from "../lib/render/markdown.ts";
+import { searchSchema } from "../lib/search.ts";
+import { PROJECT_TARGET } from "../lib/knowledge/types.ts";
+import { annotate, annotateProject, editNote, projectNotes, relate, relationshipsFromOtherConnections } from "../lib/usecases/knowledge.ts";
+import { ProjectError, forgetById, openConnection, openProjectRoot, openSnapshot, resolveTarget } from "../lib/usecases/project.ts";
+import { resolveTable } from "../lib/usecases/resolve.ts";
+import { SHARE_NOTES_HINT, knowledgeSharing } from "../lib/usecases/sharing.ts";
+import type { HeydbDeps } from "./deps.ts";
+
+// Tools are what the model calls. They read the stored snapshot and the
+// knowledge files, and write knowledge; they never connect to a database.
+// Connecting needs a password and may hit production, so only the human
+// commands (/heydb:sync, /heydb:status) do it, when a person asks.
+//
+// Every failure comes back as text with isError, never as a thrown error: the
+// model reads the message and can fix its call or tell the user what to run.
+// Tools run one at a time ("sequential"): two notes saved in the same turn
+// must not both read the file before either writes it.
+
+interface ToolDetails {
+	/** The connection the call used; null when it failed before picking one. */
+	readonly connection: string | null;
+}
+
+type Result = AgentToolResult<ToolDetails>;
+
+const CONNECTION = {
+	type: "string",
+	description: "Connection name from .heydb/config.json; omit to use the default.",
+} as const;
+
+/** The suffix that tells readers a note was written by an agent, not typed by a person. */
+export const AGENT_AUTHOR_SUFFIX = " (via agent)";
+
+export function registerHeydbTools(pi: ExtensionAPI, deps: HeydbDeps): void {
+	pi.registerTool(createOverviewTool());
+	pi.registerTool(createTableTool());
+	pi.registerTool(createSearchTool());
+	pi.registerTool(createAnnotateTool(deps));
+	pi.registerTool(createRelateTool(deps));
+	pi.registerTool(createEditNoteTool(deps));
+	pi.registerTool(createForgetTool());
+}
+
+const OVERVIEW_PARAMETERS = {
+	type: "object",
+	properties: { connection: CONNECTION },
+	additionalProperties: false,
+} as const;
+
+export function createOverviewTool(): ToolDefinition<typeof OVERVIEW_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_overview",
+		label: "heydb overview",
+		description:
+			"Project notes, then a summary of the schema snapshot: per database comment coverage, name prefixes, most referenced tables; warnings; noted tables.",
+		promptSnippet: "Summarize the database schema of this project (stored snapshot)",
+		promptGuidelines: ["Use heydb_overview first when you do not know the database schema of a heydb project."],
+		parameters: OVERVIEW_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(() => {
+				const opened = openSnapshot(ctx.cwd, params.connection);
+				const options = { connection: opened.name, projectNotes: projectNotes(opened.root) };
+				return ok(renderOverview(opened.snapshot, opened.knowledge, options), opened.name);
+			});
+		},
+	};
+}
+
+const TABLE_PARAMETERS = {
+	type: "object",
+	properties: {
+		table: { type: "string", description: 'Table or view: "orders", "shop.orders" or "shop.shop.orders".' },
+		columns: {
+			anyOf: [{ type: "string", const: "all" }, { type: "integer", minimum: 1 }],
+			description: 'How many columns to list (default 60, most telling first), or "all".',
+		},
+		column_filter: { type: "string", description: "Only columns whose name or comment contains this text; ignores case and accents." },
+		connection: CONNECTION,
+	},
+	required: ["table"],
+	additionalProperties: false,
+} as const;
+
+export function createTableTool(): ToolDefinition<typeof TABLE_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_table",
+		label: "heydb table",
+		description:
+			"One table or view: comment, team notes (with ids), keys, relationships both ways (who references it), then its most relevant columns.",
+		promptSnippet: "Show what one database table means and its columns, keys, relationships and notes",
+		promptGuidelines: [
+			"Before writing or changing SQL in a heydb project, check heydb_table (or heydb_search) for the tables involved instead of guessing names, columns or joins.",
+			"Read the heydb_table header (comment, notes, referenced by) before concluding what a table is; when its meaning comes from inference (columns, references, name), say it is an inference and ask the user before saving it with heydb_annotate.",
+		],
+		parameters: TABLE_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(() => {
+				// Pi validates the schema, but the check is repeated so no other caller can pass 0 or 2.5.
+				const { columns } = params;
+				if (columns !== undefined && columns !== "all" && !(Number.isInteger(columns) && columns >= 1)) {
+					throw new Error('columns must be "all" or an integer of at least 1');
+				}
+				const opened = openSnapshot(ctx.cwd, params.connection);
+				const resolved = resolveTable(opened.snapshot, params.table);
+				const knowledge = knowledgeForTable(opened.knowledge, resolved.name);
+				const incoming = incomingReferences(opened.snapshot, opened.knowledge, resolved.name);
+				const other = relationshipsFromOtherConnections(opened.root, opened.name, resolved.name);
+				const options = {
+					...(columns !== undefined && { columns }),
+					...(params.column_filter !== undefined && { columnFilter: params.column_filter }),
+					connection: opened.name,
+					external: other.relationships,
+					unreadable: other.unreadable,
+				};
+				return ok(renderTable(resolved.table, resolved.name, knowledge, incoming, options), opened.name);
+			});
+		},
+	};
+}
+
+const MAX_SEARCH_LIMIT = 50;
+
+const SEARCH_PARAMETERS = {
+	type: "object",
+	properties: {
+		query: { type: "string", description: "Text to find; case and accents are ignored." },
+		limit: { type: "integer", minimum: 1, maximum: MAX_SEARCH_LIMIT, description: "Maximum results (default 20)." },
+		database: { type: "string", description: 'Only this database, e.g. "shop" (PostgreSQL: "app.public").' },
+		connection: CONNECTION,
+	},
+	required: ["query"],
+	additionalProperties: false,
+} as const;
+
+export function createSearchTool(): ToolDefinition<typeof SEARCH_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_search",
+		label: "heydb search",
+		description:
+			"Search tables by name, comment, team notes and columns, plus tables whose meaning is inferred from the columns that reference them; ignores case, accents and plurals.",
+		promptSnippet: "Search the database schema and its notes by keyword",
+		promptGuidelines: [
+			"Use heydb_search to find which tables or columns hold a concept before writing SQL.",
+			"A heydb_search result marked (inferred) matched only through the comments of columns that reference it: present it as an inference and confirm with the user before relying on it or saving it.",
+		],
+		parameters: SEARCH_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(() => {
+				// Pi validates the schema, but the check is repeated so no other caller can ask for 10,000 results.
+				const { limit = 20 } = params;
+				if (!Number.isInteger(limit) || limit < 1 || limit > MAX_SEARCH_LIMIT) {
+					throw new Error(`limit must be an integer from 1 to ${MAX_SEARCH_LIMIT}`);
+				}
+				const opened = openSnapshot(ctx.cwd, params.connection);
+				const options = { limit, ...(params.database !== undefined && { database: params.database }) };
+				return ok(renderSearch(searchSchema(opened.snapshot, opened.knowledge, params.query, options)), opened.name);
+			});
+		},
+	};
+}
+
+const ANNOTATE_PARAMETERS = {
+	type: "object",
+	properties: {
+		target: {
+			type: "string",
+			description: 'Database ("shop"), table ("orders", "shop.orders") or column ("orders.status"). Omit with scope "project".',
+		},
+		scope: { type: "string", const: "project", description: 'Set to "project", without target, for a note about the whole project.' },
+		text: { type: "string", description: "Short, factual note." },
+		connection: CONNECTION,
+	},
+	required: ["text"],
+	additionalProperties: false,
+} as const;
+
+export function createAnnotateTool(deps: HeydbDeps): ToolDefinition<typeof ANNOTATE_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_annotate",
+		label: "heydb annotate",
+		description:
+			"Save a note on the project, a database, table or column in .heydb/knowledge; the team gets it when the project commits .heydb/.",
+		promptSnippet: "Record what a database, table or column means, for the whole team",
+		promptGuidelines: [
+			"When you learn what a table or column means (valid values, units, legacy quirks), save it with heydb_annotate: one or two factual sentences, never invent or guess.",
+			"Before heydb_annotate, read the existing notes with heydb_table; fix a wrong note with heydb_edit_note instead of adding a contradicting one.",
+			'End a heydb_annotate note with its source: "(code: src/Models/Order.php)" when code shows it, "(told by the user)" when the user said it. Save an inference only after the user confirms it.',
+			'For a fact about the whole project rather than one database (one database per client, which connection is central), use heydb_annotate with scope: "project" and no target.',
+		],
+		parameters: ANNOTATE_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(async () => {
+				// A separate scope, not a magic target: a table called "project" must stay reachable as target "project".
+				if (params.scope === "project") {
+					if (params.target !== undefined) throw new Error('a project note has no target: omit target with scope "project"');
+					const root = openProjectRoot(ctx.cwd);
+					const note = annotateProject(root, { text: params.text, author: await agentAuthor(deps, ctx.cwd) }, deps.knowledge);
+					return ok(`Saved project note ${note.id} (author: ${note.author}).${await sharingWarning(root, PROJECT_FILE_SHARING)}`, null);
+				}
+				if (params.target === undefined) throw new Error('target is required, unless scope is "project"');
+				const opened = openSnapshot(ctx.cwd, params.connection);
+				const target = resolveProjectHint(params.target, () => resolveTarget(opened.snapshot, params.target as string));
+				const author = await agentAuthor(deps, ctx.cwd);
+				const note = annotate(opened.root, opened.name, { target: target.name, text: params.text, author }, deps.knowledge);
+				const saved = `Saved note ${note.id} on ${target.kind} ${displayNameOf(note.target)} (author: ${note.author}).`;
+				return ok(saved + (await sharingWarning(opened.root, opened.name)), opened.name);
+			});
+		},
+	};
+}
+
+const COLUMNS = { type: "array", items: { type: "string" }, minItems: 1 } as const;
+
+const RELATE_PARAMETERS = {
+	type: "object",
+	properties: {
+		from_table: { type: "string", description: "Table holding the reference, e.g. orders." },
+		from_columns: { ...COLUMNS, description: "Referencing columns, in order." },
+		to_table: { type: "string", description: "Referenced table, e.g. customers." },
+		to_columns: { ...COLUMNS, description: "Referenced columns, same order and count." },
+		to_connection: { type: "string", description: "Connection of to_table when it is not the from connection." },
+		note: { type: "string", description: "How you know, briefly." },
+		connection: CONNECTION,
+	},
+	required: ["from_table", "from_columns", "to_table", "to_columns"],
+	additionalProperties: false,
+} as const;
+
+export function createRelateTool(deps: HeydbDeps): ToolDefinition<typeof RELATE_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_relate",
+		label: "heydb relate",
+		description: "Document an implicit relationship: columns that join two tables without a foreign key.",
+		promptSnippet: "Record a join between tables that has no foreign key",
+		promptGuidelines: [
+			"When you find tables joined without a foreign key (in code, queries or data), record it with heydb_relate and say how you know in the note.",
+			"When the referenced table is in another connection of the project (crm.clientes.cod_erp → erp's cus.cod), call heydb_relate from the referencing connection with to_connection.",
+		],
+		parameters: RELATE_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(async () => {
+				const opened = openSnapshot(ctx.cwd, params.connection);
+				const from = { table: resolveTable(opened.snapshot, params.from_table).name, columns: params.from_columns };
+				// The to side is resolved in its own connection's snapshot; a stored side names its connection only when it differs.
+				const target = params.to_connection === undefined ? opened : openSnapshot(ctx.cwd, params.to_connection);
+				const to = {
+					...(target.name !== opened.name && { connection: target.name }),
+					table: resolveTable(target.snapshot, params.to_table).name,
+					columns: params.to_columns,
+				};
+				const author = await agentAuthor(deps, ctx.cwd);
+				const link = relate(opened.root, opened.name, { from, to, note: params.note ?? "", author }, deps.knowledge);
+				const saved = `Saved relationship ${link.id}: ${side(link.from)} → ${side(link.to)} (author: ${link.author}).`;
+				return ok(saved + (await sharingWarning(opened.root, opened.name)), opened.name);
+			});
+		},
+	};
+}
+
+const EDIT_PARAMETERS = {
+	type: "object",
+	properties: {
+		id: { type: "string", description: "Note id, as shown by heydb_table or heydb_overview." },
+		text: { type: "string", description: "The new text, replacing the old one." },
+		connection: CONNECTION,
+	},
+	required: ["id", "text"],
+	additionalProperties: false,
+} as const;
+
+export function createEditNoteTool(deps: HeydbDeps): ToolDefinition<typeof EDIT_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_edit_note",
+		label: "heydb edit note",
+		description: "Replace the text of a heydb note by id; author and creation date are kept.",
+		promptSnippet: "Correct the text of an existing heydb note",
+		parameters: EDIT_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(() => {
+				const opened = openConnection(ctx.cwd, params.connection);
+				const note = editNote(opened.root, opened.name, { id: params.id, text: params.text }, deps.knowledge);
+				return ok(isProjectNote(note) ? `Updated project note ${note.id}.` : `Updated note ${note.id} on ${displayNameOf(note.target)}.`, opened.name);
+			});
+		},
+	};
+}
+
+const FORGET_PARAMETERS = {
+	type: "object",
+	properties: {
+		id: { type: "string", description: "Id of a note or relationship, as shown by heydb_table or heydb_overview." },
+		connection: CONNECTION,
+	},
+	required: ["id"],
+	additionalProperties: false,
+} as const;
+
+export function createForgetTool(): ToolDefinition<typeof FORGET_PARAMETERS, ToolDetails> {
+	return {
+		name: "heydb_forget",
+		label: "heydb forget",
+		description: "Delete a heydb note or implicit relationship by id.",
+		promptSnippet: "Delete a wrong or obsolete heydb note or relationship",
+		promptGuidelines: ["Use heydb_forget only for notes that are wrong or obsolete, and say which one you removed."],
+		parameters: FORGET_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return guarded(() => {
+				const opened = openConnection(ctx.cwd, params.connection);
+				const forgotten = forgetById(opened.root, opened.name, params.id);
+				const text =
+					forgotten.kind === "annotation"
+						? isProjectNote(forgotten.annotation)
+							? `Forgot project note ${forgotten.annotation.id}.`
+							: `Forgot note ${forgotten.annotation.id} on ${displayNameOf(forgotten.annotation.target)}.`
+						: `Forgot relationship ${forgotten.relationship.id}: ${side(forgotten.relationship.from)} → ${side(forgotten.relationship.to)}.`;
+				return ok(text, opened.name);
+			});
+		},
+	};
+}
+
+/**
+ * Said after saving only when git ignores the notes: the agent would
+ * otherwise tell the user the team has them. Saving already succeeded, so a
+ * failing git check adds nothing rather than turning it into an error.
+ */
+async function sharingWarning(root: string, connection: string): Promise<string> {
+	try {
+		const sharing = await knowledgeSharing(root, { connection });
+		if (sharing.state !== "ignored") return "";
+		return `\nNote saved locally; git ignores it (${sharing.rule}), so the team will not get it. ${SHARE_NOTES_HINT}`;
+	} catch {
+		return "";
+	}
+}
+
+/** What knowledgeSharing checks for project notes: .heydb/knowledge/_project.json. */
+const PROJECT_FILE_SHARING = "_project";
+
+/** An agent that writes target "project" for a project note gets told about scope when nothing is called project. */
+function resolveProjectHint<T>(target: string, resolve: () => T): T {
+	try {
+		return resolve();
+	} catch (error) {
+		if (target.trim().toLowerCase() !== PROJECT_TARGET || !(error instanceof Error)) throw error;
+		throw new Error(`${error.message}\nFor a note about the whole project, use scope: "project" without a target.`, { cause: error });
+	}
+}
+
+function isProjectNote(note: Annotation): boolean {
+	return note.target === PROJECT_TARGET;
+}
+
+async function agentAuthor(deps: HeydbDeps, cwd: string): Promise<string> {
+	return `${await deps.author(cwd)}${AGENT_AUTHOR_SUFFIX}`;
+}
+
+function side(value: RelationshipSide): string {
+	const connection = value.connection === undefined ? "" : `${value.connection}: `;
+	return `${connection}${displayNameOf(value.table)}(${value.columns.join(", ")})`;
+}
+
+function ok(text: string, connection: string | null): Result {
+	return { content: [{ type: "text", text }], details: { connection } };
+}
+
+async function guarded(work: () => Result | Promise<Result>): Promise<Result> {
+	try {
+		return await work();
+	} catch (error) {
+		return { content: [{ type: "text", text: forAgent(error) }], details: { connection: null }, isError: true };
+	}
+}
+
+// The agent cannot run slash commands; it has to ask the user to.
+function forAgent(error: unknown): string {
+	if (error instanceof ProjectError) {
+		switch (error.code) {
+			case "not_initialized":
+				return "No heydb project in this folder or above. Ask the user to run /heydb:init, then /heydb:connect and /heydb:sync.";
+			case "no_connections":
+				return "This heydb project has no connections yet. Ask the user to run /heydb:connect, then /heydb:sync.";
+			case "never_synced":
+				return `Connection "${error.connection}" was never synced, so there is no schema snapshot yet. Ask the user to run /heydb:sync ${error.connection}.`;
+		}
+	}
+	return error instanceof Error ? error.message : String(error);
+}

package/lib/about.ts

@@ -0,0 +1,7 @@
+import pkg from "../package.json" with { type: "json" };
+
+export const HEYDB_VERSION: string = pkg.version;
+
+export function aboutMessage(): string {
+	return `heydb ${HEYDB_VERSION} (v2 in development)`;
+}