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

package/lib/usecases/resolve.ts

@@ -0,0 +1,186 @@
+import { displayNameOf, formatName, parseSegments } from "../model/names.ts";
+import type { Column, Snapshot, Table } from "../model/snapshot.ts";
+
+// Agents and people rarely type canonical names. They write "orders",
+// "shop.orders" (how MySQL names a table) or the full "shop.shop.orders".
+// These functions turn what they typed into exactly one object, or explain
+// why they cannot.
+//
+// Error messages stay small whatever the size of the schema: at most 10
+// candidates for an ambiguous name and 5 suggestions for an unknown one.
+// They name objects by display name ("shop.orders"), which is shorter and
+// typed back exactly like the canonical one.
+// heydb v1 listed every table when one was not found (bug #7): with 3,000
+// tables, each typo cost the agent thousands of tokens.
+
+const MAX_CANDIDATES = 10;
+const MAX_SUGGESTIONS = 5;
+
+export interface ResolvedTable {
+	/** Canonical name: database.schema.table. */
+	readonly name: string;
+	readonly database: string;
+	readonly schema: string;
+	readonly table: Table;
+}
+
+export interface ResolvedColumn {
+	/** Canonical name: database.schema.table.column. */
+	readonly name: string;
+	readonly table: ResolvedTable;
+	readonly column: Column;
+}
+
+// Every addressable object once, with its segments from database to itself.
+interface Entry<T> {
+	readonly name: string;
+	readonly segments: readonly string[];
+	readonly value: T;
+}
+
+/** Accepts "table", "database.table" (or "schema.table") and "database.schema.table". */
+export function resolveTable(snapshot: Snapshot, input: string): ResolvedTable {
+	const segments = parseSegments(input);
+	if (segments.length > 3) {
+		throw new Error(`expected a table name (table, database.table or database.schema.table): got "${input}"`);
+	}
+	return pickOne(tableEntries(snapshot), segments, input, "table").value;
+}
+
+/** Accepts "column", "table.column", "database.table.column" and the canonical name. */
+export function resolveColumn(snapshot: Snapshot, input: string): ResolvedColumn {
+	const segments = parseSegments(input);
+	if (segments.length > 4) {
+		throw new Error(`expected a column name (column, table.column … database.schema.table.column): got "${input}"`);
+	}
+	const columns = tableEntries(snapshot).flatMap(({ segments: tableSegments, value: table }) =>
+		table.table.columns.map((column): Entry<ResolvedColumn> => {
+			const name = formatName({ database: table.database, schema: table.schema, table: table.table.name, column: column.name });
+			return { name, segments: [...tableSegments, column.name], value: { name, table, column } };
+		}),
+	);
+	return pickOne(columns, segments, input, "column").value;
+}
+
+function tableEntries(snapshot: Snapshot): Entry<ResolvedTable>[] {
+	const entries: Entry<ResolvedTable>[] = [];
+	for (const database of snapshot.databases) {
+		for (const schema of database.schemas) {
+			for (const table of schema.tables) {
+				const name = formatName({ database: database.name, schema: schema.name, table: table.name });
+				entries.push({
+					name,
+					segments: [database.name, schema.name, table.name],
+					value: { name, database: database.name, schema: schema.name, table },
+				});
+			}
+		}
+	}
+	return entries;
+}
+
+// Exact spelling first; only when nothing matches exactly is case ignored,
+// so "Orders" and "orders" in the same database stay distinguishable.
+function pickOne<T>(entries: readonly Entry<T>[], input: readonly string[], text: string, kind: string): Entry<T> {
+	let matches = entries.filter((entry) => matchesTail(entry.segments, input, same));
+	if (matches.length === 0) matches = entries.filter((entry) => matchesTail(entry.segments, input, sameIgnoringCase));
+
+	const [first] = matches;
+	if (first !== undefined && matches.length === 1) return first;
+	if (matches.length > 1) throw ambiguous(text, kind, matches.map((entry) => entry.name).sort(compareText).map(displayNameOf));
+	throw notFound(text, kind, suggestions(entries, input));
+}
+
+/**
+ * Whether what was typed names this object. `segments` is [database, schema,
+ * table] or [database, schema, table, column]. The typed text ends with the
+ * object part ("orders", "orders.total", or just "total" for a column), and
+ * may start with a prefix: one segment is the database or the schema
+ * ("shop.orders": in MySQL both are "shop"; in PostgreSQL it would be
+ * "public.orders"), two are both, in order.
+ */
+function matchesTail(
+	segments: readonly string[],
+	input: readonly string[],
+	equal: (a: string, b: string) => boolean,
+): boolean {
+	const objectDepth = segments.length - 2; // 1 for a table, 2 for a column
+	const prefixLength = Math.max(0, input.length - objectDepth);
+	const typedObject = input.slice(prefixLength);
+	const object = segments.slice(segments.length - typedObject.length);
+	if (!typedObject.every((part, index) => equal(part, object[index] as string))) return false;
+
+	const [database, schema] = segments as [string, string];
+	const [first, second] = input;
+	if (prefixLength === 0) return true;
+	if (prefixLength === 1) return equal(first as string, database) || equal(first as string, schema);
+	return prefixLength === 2 && equal(first as string, database) && equal(second as string, schema);
+}
+
+function same(a: string, b: string): boolean {
+	return a === b;
+}
+
+function sameIgnoringCase(a: string, b: string): boolean {
+	return a.toLowerCase() === b.toLowerCase();
+}
+
+/**
+ * Up to 5 names close to what was typed. The last segment is compared, so a
+ * wrong database or table prefix still finds "orders"; close means a small
+ * edit distance (a typo) or one name containing the other.
+ */
+function suggestions<T>(entries: readonly Entry<T>[], input: readonly string[]): string[] {
+	const typed = (input[input.length - 1] ?? "").toLowerCase();
+	const limit = Math.min(3, Math.max(1, Math.floor(typed.length / 4)));
+	const scored: { name: string; distance: number }[] = [];
+	for (const entry of entries) {
+		const candidate = (entry.segments[entry.segments.length - 1] ?? "").toLowerCase();
+		const distance = editDistance(typed, candidate, limit);
+		const contains = typed.length >= 3 && (candidate.includes(typed) || typed.includes(candidate));
+		if (distance <= limit || contains) scored.push({ name: entry.name, distance });
+	}
+	return scored
+		.sort((a, b) => a.distance - b.distance || compareText(a.name, b.name))
+		.slice(0, MAX_SUGGESTIONS)
+		.map((item) => displayNameOf(item.name));
+}
+
+/**
+ * Levenshtein distance: how many single-character insertions, deletions or
+ * substitutions turn `a` into `b`. Stops early and returns limit + 1 once the
+ * answer is known to exceed `limit`, so 3,000 tables cost almost nothing.
+ */
+function editDistance(a: string, b: string, limit: number): number {
+	if (Math.abs(a.length - b.length) > limit) return limit + 1;
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+		let best = i;
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const value = Math.min((previous[j] as number) + 1, (current[j - 1] as number) + 1, (previous[j - 1] as number) + cost);
+			current.push(value);
+			best = Math.min(best, value);
+		}
+		if (best > limit) return limit + 1;
+		previous = current;
+	}
+	return previous[b.length] as number;
+}
+
+function ambiguous(text: string, kind: string, names: readonly string[]): Error {
+	const shown = names.slice(0, MAX_CANDIDATES).map((name) => `- ${name}`);
+	const more = names.length > MAX_CANDIDATES ? [`… and ${names.length - MAX_CANDIDATES} more`] : [];
+	return new Error([`"${text}" matches ${names.length} ${kind}s; use the full name:`, ...shown, ...more].join("\n"));
+}
+
+function notFound(text: string, kind: string, similar: readonly string[]): Error {
+	const hint = similar.length === 0 ? "" : `. Did you mean: ${similar.join(", ")}?`;
+	return new Error(`no ${kind} matches "${text}"${hint}`);
+}
+
+// Plain code-unit comparison, like the rest of heydb: never locale-dependent.
+function compareText(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}

package/lib/usecases/sharing.ts

@@ -0,0 +1,83 @@
+import { execFile } from "node:child_process";
+
+import { HEYDB_DIR } from "../store/project.ts";
+
+// Whether the team gets the notes. heydb keeps them in .heydb/knowledge/ and
+// git shares them when the project commits that folder; but heydb v1 told
+// projects to ignore .heydb/ entirely, and a project that still does keeps
+// every note on one machine while the tool says it was saved. Nobody notices
+// until a colleague asks why the notes are missing.
+//
+// Only git knows whether a path is ignored: rules come from every .gitignore
+// on the way, .git/info/exclude and the global excludes file, and a later
+// "!pattern" can re-include a path. So heydb asks `git check-ignore -v`,
+// which also names the rule, and never edits any ignore file itself: what
+// the project shares is the team's decision.
+
+export type KnowledgeSharing =
+	| { readonly state: "shared" }
+	/** `rule` is "<source>:<line>: <pattern>", e.g. ".gitignore:26: .heydb/". */
+	| { readonly state: "ignored"; readonly rule: string }
+	| { readonly state: "no-git" };
+
+export interface GitRun {
+	readonly exitCode: number;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+/** Runs git with `args` in `cwd`; "missing" when git is not installed. */
+export type RunGit = (args: readonly string[], cwd: string) => Promise<GitRun | "missing">;
+
+export interface SharingOptions {
+	/** The connection whose notes file is checked; without one, the knowledge folder. */
+	readonly connection?: string;
+	/** Replaced in tests; the default runs the real git. */
+	readonly runGit?: RunGit;
+}
+
+export const SHARE_NOTES_HINT = `To share notes, commit ${HEYDB_DIR}/config.json, ${HEYDB_DIR}/snapshots/ and ${HEYDB_DIR}/knowledge/ (never ${HEYDB_DIR}/.env).`;
+
+const GIT_TIMEOUT_MS = 2000;
+
+/**
+ * Whether git would share the notes of the project at `projectRoot`:
+ * "shared" when git tracks them or does not ignore them, "ignored" with the
+ * rule that ignores them, "no-git" without git or outside a repository. Any
+ * other git failure is an error, so a broken repository is not reported as
+ * fine.
+ */
+export async function knowledgeSharing(projectRoot: string, options: SharingOptions = {}): Promise<KnowledgeSharing> {
+	const { connection, runGit = runRealGit } = options;
+	const path = `${HEYDB_DIR}/knowledge/${connection === undefined ? "" : `${connection}.json`}`;
+	// Tracked files are never reported as ignored, so tracked notes come back as shared.
+	const run = await runGit(["check-ignore", "-v", "--", path], projectRoot);
+	if (run === "missing") return { state: "no-git" };
+	if (run.exitCode === 1) return { state: "shared" };
+	if (run.exitCode === 0) {
+		// "<source>:<line>:<pattern>\t<path>"; a pattern starting with "!" re-includes the path.
+		const match = /^(.*):(\d+):([^\t]*)\t/.exec(run.stdout);
+		if (match === null) throw new Error(`could not read git check-ignore's answer for ${path}: ${firstLine(run.stdout)}`);
+		const [, source, line, pattern] = match as unknown as [string, string, string, string];
+		return pattern.startsWith("!") ? { state: "shared" } : { state: "ignored", rule: `${source}:${line}: ${pattern}` };
+	}
+	if (/not a git repository/i.test(run.stderr)) return { state: "no-git" };
+	throw new Error(`could not ask git whether it ignores ${path}: ${firstLine(run.stderr) || `exit code ${run.exitCode}`}`);
+}
+
+// An argument list and no shell: nothing in a path is ever interpreted.
+function runRealGit(args: readonly string[], cwd: string): Promise<GitRun | "missing"> {
+	return new Promise((resolve, reject) => {
+		execFile("git", [...args], { cwd, timeout: GIT_TIMEOUT_MS, shell: false, windowsHide: true, encoding: "utf8" }, (error, stdout, stderr) => {
+			if (error === null) return resolve({ exitCode: 0, stdout, stderr });
+			const failure = error as NodeJS.ErrnoException & { code?: unknown; killed?: boolean };
+			if (failure.code === "ENOENT") return resolve("missing");
+			if (typeof failure.code === "number" && !failure.killed) return resolve({ exitCode: failure.code, stdout, stderr });
+			reject(new Error(`git ${args[0]} failed: ${failure.killed ? `no answer within ${GIT_TIMEOUT_MS} ms` : error.message}`, { cause: error }));
+		});
+	});
+}
+
+function firstLine(text: string): string {
+	return text.trim().split("\n")[0] ?? "";
+}

package/lib/usecases/status.ts

@@ -0,0 +1,37 @@
+import { type Change, diffSnapshots } from "../model/diff.ts";
+import { schemaHash } from "../model/hash.ts";
+import type { Snapshot } from "../model/snapshot.ts";
+import { loadSnapshot } from "../store/snapshots.ts";
+
+// Use cases combine the store and the model into one answer for a user
+// question. The engine is not called here: the caller captures the live
+// snapshot (with introspectMysql today, other engines later) and passes it in,
+// so these functions are tested with plain snapshots and no server, and lib/
+// stays free of any particular entry point (Pi, a CLI, an MCP server).
+
+/**
+ * Exactly one of three states. `state` tells them apart, and TypeScript only
+ * lets callers read `changes` after checking that the state is "drifted".
+ */
+export type StatusResult =
+	| { readonly state: "never_synced" }
+	| { readonly state: "up_to_date"; readonly hash: string }
+	| {
+			readonly state: "drifted";
+			readonly storedHash: string;
+			readonly liveHash: string;
+			readonly changes: readonly Change[];
+	  };
+
+/** Compares the live database with the stored snapshot of `connection`. */
+export function checkStatus(projectRoot: string, connection: string, live: Snapshot): StatusResult {
+	const stored = loadSnapshot(projectRoot, connection);
+	if (stored === null) return { state: "never_synced" };
+
+	// The hash answers "did anything change?"; only when it did is the diff
+	// worth computing to answer "what?".
+	const storedHash = schemaHash(stored);
+	const liveHash = schemaHash(live);
+	if (storedHash === liveHash) return { state: "up_to_date", hash: liveHash };
+	return { state: "drifted", storedHash, liveHash, changes: diffSnapshots(stored, live) };
+}

package/lib/usecases/sync.ts

@@ -0,0 +1,33 @@
+import { type Change, diffSnapshots } from "../model/diff.ts";
+import { schemaHash } from "../model/hash.ts";
+import type { Snapshot } from "../model/snapshot.ts";
+import { saveSnapshot } from "../store/snapshots.ts";
+import { checkStatus } from "./status.ts";
+
+export interface SyncResult {
+	/** false when the stored snapshot already had the same structure. */
+	readonly written: boolean;
+	readonly hash: string;
+	/** What the new file changed; every database counts as added on the first sync. */
+	readonly changes: readonly Change[];
+}
+
+/**
+ * Stores the live snapshot of `connection`, but only when its structure
+ * differs from the stored one. Snapshot files are committed: rewriting them
+ * because the capture time, a row estimate or a warning changed would create
+ * a git change on every sync with nothing real to review.
+ */
+export function syncSnapshot(projectRoot: string, connection: string, live: Snapshot): SyncResult {
+	const status = checkStatus(projectRoot, connection, live);
+	switch (status.state) {
+		case "up_to_date":
+			return { written: false, hash: status.hash, changes: [] };
+		case "never_synced":
+			saveSnapshot(projectRoot, connection, live);
+			return { written: true, hash: schemaHash(live), changes: diffSnapshots({ ...live, databases: [] }, live) };
+		case "drifted":
+			saveSnapshot(projectRoot, connection, live);
+			return { written: true, hash: status.liveHash, changes: status.changes };
+	}
+}

package/package.json

@@ -1,6 +1,70 @@
 {
-  "name": "@pvidaal07/heydb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@pvidaal07/heydb",
+	"version": "2.0.0-beta.1",
+	"description": "Database schema context for AI agents: introspect MySQL, MariaDB and PostgreSQL, keep a local snapshot, and share annotated knowledge through git.",
+	"license": "MIT",
+	"author": "pvidaal07",
+	"homepage": "https://github.com/pvidaal07/heydb#readme",
+	"bugs": {
+		"url": "https://github.com/pvidaal07/heydb/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pvidaal07/heydb.git"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"database",
+		"schema",
+		"mysql",
+		"mariadb",
+		"postgresql",
+		"ai-agent",
+		"legacy"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"packageManager": "pnpm@11.0.9",
+	"pi": {
+		"extensions": [
+			"./extensions/heydb.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"files": [
+		"extensions",
+		"lib",
+		"skills",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "node --test \"tests/**/*.test.ts\"",
+		"typecheck": "tsc --noEmit",
+		"check": "tsc --noEmit && node --run test",
+		"db:up": "docker compose -f tests/integration/compose.yaml up -d --wait",
+		"db:down": "docker compose -f tests/integration/compose.yaml down",
+		"test:integration": "node --test --test-timeout=60000 \"tests/integration/**/*.integration.ts\""
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^1.5.0",
+		"@earendil-works/pi-tui": "^1.5.0",
+		"@types/node": "^22.19.0",
+		"@types/pg": "^8.23.1",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"mysql2": "^3.24.6",
+		"pg": "^8.23.1"
+	}
+}

package/skills/heydb/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: heydb
+description: Consult and enrich the database schema of a heydb project (.heydb/ folder) with the heydb_* tools. Use before writing, reviewing or debugging SQL, queries, migrations or ORM models; when asked what a table or column means or how tables join; and when you learn business meaning (valid values, units, legacy quirks) or a join without a foreign key that the team should keep.
+---
+
+# heydb
+
+heydb keeps a snapshot of the project's database structure (`.heydb/snapshots/`) and the team's notes about it (`.heydb/knowledge/`). The team shares them only if the project commits `.heydb/`; some projects ignore it, so do not promise that a note reaches anyone else. The tools read those files; they never connect to the database.
+
+## Read before you write SQL
+
+1. Unknown schema: `heydb_overview` once. It shows, per database, how many tables have comments and which tables the rest point to (the core).
+2. Looking for a concept ("invoices", "fecha de baja"): `heydb_search`. It ignores case, accents and simple plurals, lists tables (with their matching columns) before anything else, and can keep to one `database`. Results also include tables whose meaning is inferred from the columns that reference them, marked `(inferred)`: `cus` has no comment, but columns pointing to it say "Cliente Habitual". Present those as inferences, never as facts.
+3. Before using a table: `heydb_table`. Use the real column names, types and joins it shows, including implicit relationships and notes. On wide tables it lists the 60 most telling columns; ask for `columns: "all"` or a `column_filter` when you need the rest.
+
+Never guess table or column names from memory when heydb can answer.
+
+## Never guess a meaning from a table name
+
+Legacy names lie. A table named `art` looks like artwork; it holds the articles. Before you say what a table is, read the `heydb_table` header, strongest evidence first:
+
+1. Team notes and the table comment.
+2. Who points to it ("Referenced by"): foreign keys, documented relationships and the comments of columns like `ref_art`, `cod_art`. `Referencing columns are commented as: "Artículo" ×12` is strong evidence. Name-pattern guesses are not enforced; treat them as clues.
+3. Its own columns.
+
+When the meaning comes from 2 or 3, say it is an inference and ask the user to confirm. Once confirmed, save it with `heydb_annotate` so nobody has to guess again. When the overview says most tables have no comment, do not infer anything from names alone.
+
+## Warnings mean the picture is incomplete
+
+The overview lists warnings from the last sync. Take them literally:
+
+- hidden triggers or routines: the user that synced could not see them. Writes may fire logic you cannot see; say so before relying on "nothing else happens".
+- a view whose definition is not visible: do not assume what it selects.
+- a stale snapshot: if a table or column you need is missing, the database may have changed. Ask the user to run `/heydb:sync`.
+
+## Save what you learn
+
+When the conversation or the code teaches you something the schema does not say, save it so the next person (or agent) does not have to rediscover it.
+
+- `heydb_annotate` for meaning: valid values, units, encodings, who writes the column, legacy quirks.
+- `heydb_relate` for joins without a foreign key: `orders.customer_id → customers.id`. Say how you know in `note`.
+- `heydb_annotate` with `scope: "project"` and no `target` for facts above any one database: "the ERP uses one database per client; the central one is acme". `heydb_overview` shows them first. A table called `project` is still `target: "project"`.
+- `heydb_relate` with `to_connection` when the referenced table is in another connection of the project (`crm.clientes.cod_erp → erp`'s `cus.cod`). Call it from the referencing connection; `heydb_table` on the other side shows it too, prefixed with the connection.
+- A name without a dot is a table: `heydb_annotate` with `art` notes the table even if some column is also called `art`; write `pos.art` for the column.
+- If the save result says git ignores the notes, tell the user: the note stays on their machine until the project shares `.heydb/knowledge/`.
+- End every note with its source: `(code: src/Models/Order.php)` when code shows it, `(told by the user)` when the user said it. An inference is saved only after the user confirms it.
+- After `/heydb:sync` (or `/heydb:learn-code`) the user may ask you to read the project's code: follow the rules in that message and stop after about 20 notes.
+- Read the existing notes first (`heydb_table`). Fix a wrong note with `heydb_edit_note`; remove an obsolete one with `heydb_forget`. Do not add a second note that contradicts the first.
+
+Good notes are short, factual and verifiable:
+
+| Good | Bad |
+|---|---|
+| `status: 0 draft, 1 paid, 2 refunded (code: src/OrderStatus.php)` | `Status of the order.` (the name already says it) |
+| `Amount in cents, VAT included.` | `Probably the price.` (a guess) |
+| `Legacy: 0000-00-00 means "never". Filter it out.` | A paragraph retelling the conversation |
+| `Joined to customers.id by app code; no FK because the table is MyISAM.` | `I think this links to users.` |
+
+Never invent. If you are not sure, ask the user or leave it unsaved. Notes you write are signed `<author> (via agent)` so readers know a person did not type them.
+
+## Setup is the user's job
+
+If a tool says the project is not initialized, has no connections or was never synced, tell the user which command to run: `/heydb:init`, `/heydb:connect`, `/heydb:sync`. You cannot run them.
+
+A project may have several connections (say `dev` and `prod`), each with its own snapshot and notes. Tools use the default one; pass `connection` to read another, and save a note on the connection it is true for. `/heydb:connections` (the user's) lists them and changes the default.
+
+Never ask for, repeat or store database passwords, not in notes, files, commands or chat. If one is missing, tell the user to run `/heydb:password <connection>`: it asks for it hidden and keeps it in `.heydb/.env`, which is never committed.