@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/lint/statements.js

@@ -0,0 +1,120 @@
+/**
+ * The statement rules: each step of a migration against the class chant's
+ * classifier gave it (`migration.json` records the rule and class of every
+ * statement, and the changes an Op or manual step makes). Pure.
+ *
+ * - `destructive`: a statement marked destructive (a table or column drop),
+ *   or an Op step one of whose changes is.
+ * - `ch-mutation`: a ClickHouse statement of class `rewrite`, or one that
+ *   waits for its mutation (a column type or TTL change).
+ * - `ch-rebuild`: a `ClickHouseRebuildOp` step.
+ * - `pg-rewrite`: a Postgres statement of class `rewrite` (ACCESS EXCLUSIVE
+ *   for a rewrite or a full scan).
+ * - `pg-lock`: a Postgres statement that blocks writes for a whole build or
+ *   scan: an index created or dropped on an existing table without
+ *   `CONCURRENTLY` (SQLPG240 to SQLPG243), a primary key or unique
+ *   constraint built in place rather than `USING INDEX` (SQLPG221), a
+ *   foreign key or domain constraint validated in place rather than added
+ *   `NOT VALID` (SQLPG219, SQLPG262).
+ *
+ * `COMMENT ON` statements are skipped: chant writes one after a `CREATE`
+ * with the same rule, and a comment is catalog only.
+ *
+ * A statement whose rule is not one of the lexicon's, or a step of a kind
+ * it does not know, is `unreadable-object`: lint cannot tell what it does,
+ * and never passes what it cannot read.
+ */
+import { CLASSIFIER_RULES } from "@intentius/chant-lexicon-sql/clickhouse/plan/rules";
+import { PG_CLASSIFIER_RULES } from "@intentius/chant-lexicon-sql/postgres/plan/rules";
+import { planStep, REBUILD_OP } from "../steps/kinds.js";
+const catalog = (dialect) => (dialect === "clickhouse" ? CLASSIFIER_RULES : PG_CLASSIFIER_RULES);
+/** The classifier rule's id and title, e.g. `SQLCH202 Drop a column`. */
+function titled(dialect, rule) {
+    const r = catalog(dialect)[rule];
+    return r ? `${rule} ${r.title}` : rule;
+}
+const COMMENT = /^\s*COMMENT\s+ON\b/i;
+const INDEX_DDL = /^\s*(?:CREATE\s+(?:UNIQUE\s+)?INDEX|DROP\s+INDEX|REINDEX)\b/i;
+const CONCURRENTLY = /\bCONCURRENTLY\b/i;
+const NOT_VALID = /\bNOT\s+VALID\b/i;
+const USING_INDEX = /\bUSING\s+INDEX\b/i;
+const ALTER_TABLE = /^\s*ALTER\s+TABLE\b/i;
+/** Why a Postgres statement blocks writes for a whole build or scan, or `undefined`. */
+function pgLock(step) {
+    const sql = step.sql;
+    if (step.class === "create")
+        return undefined; // an index on a table created in the same migration blocks nobody
+    if (["SQLPG221", "SQLPG240", "SQLPG241", "SQLPG242", "SQLPG243"].includes(step.rule) && INDEX_DDL.test(sql) && !CONCURRENTLY.test(sql)) {
+        return /^\s*DROP/i.test(sql)
+            ? "drops an index without CONCURRENTLY: ACCESS EXCLUSIVE on the table, blocking reads and writes behind it; use DROP INDEX CONCURRENTLY"
+            : "builds an index without CONCURRENTLY: SHARE on the table, blocking every write until the build ends; declare the index CONCURRENTLY";
+    }
+    if (step.rule === "SQLPG221" && ALTER_TABLE.test(sql) && !USING_INDEX.test(sql)) {
+        return "builds the constraint's index under ACCESS EXCLUSIVE; build a unique index CONCURRENTLY first, then ADD CONSTRAINT ... USING INDEX";
+    }
+    if (step.rule === "SQLPG219" && !NOT_VALID.test(sql)) {
+        return "reads every row under SHARE ROW EXCLUSIVE on both tables, blocking writes to them for the scan; add it NOT VALID and validate it in a later migration";
+    }
+    if (step.rule === "SQLPG262" && !NOT_VALID.test(sql)) {
+        return "checks every column of the domain's type in every table while it holds its lock; add it NOT VALID and validate it later";
+    }
+    return undefined;
+}
+/** What lint cannot read in a step, or `undefined`. */
+export function unreadableStep(dialect, step) {
+    const kind = step.kind;
+    if (kind !== "statement" && kind !== "op" && kind !== "manual")
+        return `a step of kind ${JSON.stringify(kind)}, which is not statement, op or manual`;
+    if (step.kind === "statement") {
+        if (typeof step.sql !== "string" || step.sql.trim() === "")
+            return "a statement step with no SQL";
+        const known = catalog(dialect)[step.rule];
+        return known ? undefined : `a statement whose rule ${JSON.stringify(step.rule)} is not one of the ${dialect} classifier's, so what it does cannot be checked`;
+    }
+    for (const c of step.changes) {
+        if (!catalog(dialect)[c.rule])
+            return `a ${step.kind} step whose change ${JSON.stringify(c.rule)} is not one of the ${dialect} classifier's rules`;
+    }
+    return undefined;
+}
+/** The statement-rule findings for one step, before levels and silences. */
+export function stepFindings(dialect, step) {
+    const out = [];
+    if (step.kind === "statement") {
+        if (COMMENT.test(step.sql))
+            return out;
+        const what = `${titled(dialect, step.rule)} on ${step.name}`;
+        if (step.destructive)
+            out.push({ rule: "destructive", message: `${what}: removes data that cannot be recovered` });
+        if (dialect === "clickhouse" && (step.class === "rewrite" || step.waitsForMutation === true)) {
+            out.push({ rule: "ch-mutation", message: `${what}: a mutation that rewrites existing parts in the background, with no rollback` });
+        }
+        if (dialect === "postgres") {
+            if (step.class === "rewrite") {
+                const r = catalog(dialect)[step.rule];
+                out.push({ rule: "pg-rewrite", message: `${what}: blocks reads and writes on the table while it runs${r ? ` (${r.restriction})` : ""}` });
+            }
+            const lock = pgLock(step);
+            if (lock)
+                out.push({ rule: "pg-lock", message: `${what}: ${lock}` });
+        }
+        return out;
+    }
+    if (step.kind === "op") {
+        const destructive = step.changes.filter((c) => c.destructive);
+        if (destructive.length > 0) {
+            out.push({ rule: "destructive", message: `${step.op} for ${step.name} removes data that cannot be recovered: ${destructive.map((c) => `${titled(dialect, c.rule)} (${c.field})`).join(", ")}` });
+        }
+        if (step.op === REBUILD_OP) {
+            const why = step.changes.filter((c) => c.class === "rebuild").map((c) => `${titled(dialect, c.rule)} (${c.field})`);
+            out.push({ rule: "ch-rebuild", message: `${REBUILD_OP} rebuilds ${step.name}: every row is copied into a new table and swapped in${why.length > 0 ? `, for ${why.join(", ")}` : ""}` });
+        }
+    }
+    return out;
+}
+/** Why yodel apply refuses a step, or `undefined` for one it runs. */
+export function refusedStep(step) {
+    const plan = planStep(step);
+    return plan.run === "refused" ? plan.reason : undefined;
+}
+//# sourceMappingURL=statements.js.map

package/dist/lint/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../src/lint/statements.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `yodel mcp`: a Model Context Protocol server on stdio, newline-delimited
+ * JSON-RPC 2.0. It answers `initialize`, `ping`, `tools/list` and
+ * `tools/call`, and serves only the read-only tools of ./tools.ts; the
+ * constructor refuses any other list ({@link assertReadOnly}).
+ */
+import { type YodelTool } from "./tools.js";
+/** Protocol revisions this server answers with, newest first; a client asking for another gets the newest. */
+export declare const PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const INSTRUCTIONS: string;
+interface Request {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: unknown;
+    params?: Record<string, unknown>;
+}
+type Response = {
+    jsonrpc: "2.0";
+    id: string | number | null;
+} & ({
+    result: unknown;
+} | {
+    error: {
+        code: number;
+        message: string;
+    };
+});
+export declare class YodelMcpServer {
+    private readonly tools;
+    constructor(tools: readonly YodelTool[]);
+    /** What `tools/list` answers: name, description, input schema and annotations. */
+    list(): Array<Pick<YodelTool, "name" | "description" | "inputSchema" | "annotations">>;
+    /** Answers one message; `null` for a notification (no id), which gets no response. */
+    handle(message: Request): Promise<Response | null>;
+    private dispatch;
+    private call;
+    /** Serves stdin and stdout until stdin closes. Anything else the process logs goes to stderr. */
+    serve(input?: NodeJS.ReadableStream, write?: (line: string) => void): Promise<void>;
+}
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,106 @@
+/**
+ * `yodel mcp`: a Model Context Protocol server on stdio, newline-delimited
+ * JSON-RPC 2.0. It answers `initialize`, `ping`, `tools/list` and
+ * `tools/call`, and serves only the read-only tools of ./tools.ts; the
+ * constructor refuses any other list ({@link assertReadOnly}).
+ */
+import { createInterface } from "node:readline";
+import { version } from "../version.js";
+import { assertReadOnly } from "./tools.js";
+/** Protocol revisions this server answers with, newest first; a client asking for another gets the newest. */
+export const PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export const INSTRUCTIONS = "Read-only tools over a SQL Yodeler project: status, plan, lint, drift, history and explain. Each result is an envelope whose results follow the JSON Schema named in resultsSchema. " +
+    "Nothing here applies, approves, overrides a policy rule, repairs, rebases or writes a migration. A plan carries the commands that are a person's (approve, override) in forPerson: show them to the person, and never run them. " +
+    "Never run `yodel apply` against a shared environment, never run `chant approve` or `yodel approve`, never edit the `chant/lifecycle` branch, never merge; approvals and applies belong to people.";
+export class YodelMcpServer {
+    tools;
+    constructor(tools) {
+        assertReadOnly(tools);
+        this.tools = new Map(tools.map((t) => [t.name, t]));
+    }
+    /** What `tools/list` answers: name, description, input schema and annotations. */
+    list() {
+        return [...this.tools.values()].map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations }));
+    }
+    /** Answers one message; `null` for a notification (no id), which gets no response. */
+    async handle(message) {
+        if (message.id === undefined)
+            return null;
+        const id = message.id;
+        try {
+            return { jsonrpc: "2.0", id, result: await this.dispatch(message.method, message.params ?? {}) };
+        }
+        catch (e) {
+            const code = e instanceof MethodNotFound ? -32601 : e instanceof InvalidParams ? -32602 : -32603;
+            return { jsonrpc: "2.0", id, error: { code, message: e instanceof Error ? e.message : String(e) } };
+        }
+    }
+    async dispatch(method, params) {
+        switch (method) {
+            case "initialize": {
+                const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : undefined;
+                return {
+                    protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: "yodel", version: version() },
+                    instructions: INSTRUCTIONS,
+                };
+            }
+            case "ping":
+                return {};
+            case "tools/list":
+                return { tools: this.list() };
+            case "tools/call":
+                return this.call(params);
+            default:
+                throw new MethodNotFound(`unknown method ${JSON.stringify(method)}`);
+        }
+    }
+    async call(params) {
+        const name = params.name;
+        const tool = typeof name === "string" ? this.tools.get(name) : undefined;
+        if (!tool)
+            throw new InvalidParams(`unknown tool ${JSON.stringify(name)}; yodel mcp serves ${[...this.tools.keys()].join(", ")}`);
+        const args = (params.arguments ?? {});
+        try {
+            const envelope = await tool.handler(args);
+            return { content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }], structuredContent: envelope, isError: envelope.results === null };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }], isError: true };
+        }
+    }
+    /** Serves stdin and stdout until stdin closes. Anything else the process logs goes to stderr. */
+    serve(input = process.stdin, write = (l) => process.stdout.write(l)) {
+        // stdout carries the protocol only: a project's config or Op printing with console.log would break it.
+        console.log = console.info = (...a) => {
+            process.stderr.write(`${a.map(String).join(" ")}\n`);
+        };
+        const rl = createInterface({ input, terminal: false });
+        let queue = Promise.resolve();
+        rl.on("line", (line) => {
+            if (line.trim() === "")
+                return;
+            // One request at a time, in order: the tools run commands in this process.
+            queue = queue.then(async () => {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } })}\n`);
+                    return;
+                }
+                const response = await this.handle(message);
+                if (response)
+                    write(`${JSON.stringify(response)}\n`);
+            });
+        });
+        return new Promise((resolve) => rl.on("close", () => void queue.then(resolve)));
+    }
+}
+class MethodNotFound extends Error {
+}
+class InvalidParams extends Error {
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `yodel mcp`'s tools. Each runs read-only `yodel` commands in this process
+ * with `--json` and returns what they print, in one envelope
+ * (schemas/mcp.schema.json). There is no tool that applies, approves,
+ * repairs, rebases, writes a migration or overrides a policy, and
+ * {@link assertReadOnly} refuses a tool list that has one, so the server does
+ * not start with it.
+ */
+import type { Command } from "../command.js";
+import { SCHEMA_VERSION } from "../schemas.js";
+/** The only verbs a tool may run, and only with the flags {@link runVerb} allows. */
+export declare const READ_VERBS: Readonly<Record<string, Command>>;
+/** Never a tool, and never run by one: each writes to a database, a history, the migrations directory or the gate ledger. */
+export declare const WRITE_VERBS: readonly ["apply", "approve", "override", "repair", "rebase", "new", "init"];
+export interface ToolEnvelope {
+    schema: typeof SCHEMA_VERSION;
+    tool: string;
+    /** The command line the tool ran. */
+    command: string;
+    /** Its exit code: the same as on a terminal. */
+    exit: number;
+    /** What it printed with --json; null when it printed nothing to parse. */
+    results: unknown;
+    /** The `$id` of the schema `results` follows. */
+    resultsSchema: string;
+    /** What it wrote to stderr: why it failed, when `results` is null, else notices. */
+    error?: string;
+    /** Steps that are a person's, with the command they run. An agent shows them and never runs them. */
+    forPerson?: Array<{
+        action: string;
+        command: string;
+    }>;
+}
+export interface YodelTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /** The yodel verbs the tool runs. */
+    verbs: readonly string[];
+    handler: (args: Record<string, unknown>) => Promise<ToolEnvelope>;
+}
+/** Throws when any tool could write: a write verb by name, a verb outside {@link READ_VERBS}, or no read-only annotation. */
+export declare function assertReadOnly(tools: readonly YodelTool[]): void;
+/** Runs a read verb in this process with `--json` and captures what it prints. */
+export declare function runVerb(verb: string, args: readonly string[]): Promise<{
+    code: number;
+    out: string;
+    err: string;
+}>;
+interface PlanResults {
+    approve?: unknown;
+    policy?: Array<{
+        id: string;
+        outcome: string;
+    }>;
+}
+/** A plan's steps that are a person's: overriding each policy rule that denies it (when it should not stand), and approving it. */
+export declare function personSteps(env: string, plan: PlanResults | null): NonNullable<ToolEnvelope["forPerson"]>;
+/** The tools, for the project in `dir`. */
+export declare function yodelTools(dir: string): YodelTool[];
+export {};

package/dist/mcp/tools.js

@@ -0,0 +1,178 @@
+/**
+ * `yodel mcp`'s tools. Each runs read-only `yodel` commands in this process
+ * with `--json` and returns what they print, in one envelope
+ * (schemas/mcp.schema.json). There is no tool that applies, approves,
+ * repairs, rebases, writes a migration or overrides a policy, and
+ * {@link assertReadOnly} refuses a tool list that has one, so the server does
+ * not start with it.
+ */
+import { DOCS_URL } from "../cli.js";
+import { EXIT_CODES } from "../exit.js";
+import { YodelError } from "../project.js";
+import { COMMAND_SCHEMAS, SCHEMA_VERSION, schemaId } from "../schemas.js";
+import { drift } from "../commands/drift.js";
+import { lint } from "../commands/lint.js";
+import { plan } from "../commands/plan.js";
+import { status } from "../commands/status.js";
+/** The only verbs a tool may run, and only with the flags {@link runVerb} allows. */
+export const READ_VERBS = { status, plan, lint, drift };
+/** Never a tool, and never run by one: each writes to a database, a history, the migrations directory or the gate ledger. */
+export const WRITE_VERBS = ["apply", "approve", "override", "repair", "rebase", "new", "init"];
+/** Flags that make a read verb write: a replay database, a checksum, a forge comment, the Op's Apply step. */
+const WRITE_FLAGS = ["--replay", "--reset", "--reset-shared", "--keep", "--update-checksum", "--comment", "--execute"];
+/** Throws when any tool could write: a write verb by name, a verb outside {@link READ_VERBS}, or no read-only annotation. */
+export function assertReadOnly(tools) {
+    const problems = [];
+    for (const t of tools) {
+        const named = WRITE_VERBS.find((v) => t.name === v || t.name.startsWith(`${v}_`) || t.name.endsWith(`_${v}`));
+        if (named)
+            problems.push(`tool ${t.name} is named for yodel ${named}, which writes`);
+        for (const v of t.verbs)
+            if (!Object.hasOwn(READ_VERBS, v))
+                problems.push(`tool ${t.name} runs yodel ${v}, which is not one of the read verbs (${Object.keys(READ_VERBS).join(", ")})`);
+        if (!t.annotations.readOnlyHint || t.annotations.destructiveHint === true)
+            problems.push(`tool ${t.name} is not annotated read-only`);
+    }
+    if (problems.length > 0)
+        throw new YodelError(`refused to start: yodel mcp serves read-only tools only, and ${problems.join("; ")}`);
+}
+/** Runs a read verb in this process with `--json` and captures what it prints. */
+export async function runVerb(verb, args) {
+    const command = Object.hasOwn(READ_VERBS, verb) ? READ_VERBS[verb] : undefined;
+    if (!command)
+        throw new YodelError(`yodel mcp runs only ${Object.keys(READ_VERBS).join(", ")}; not ${verb}`);
+    const flag = args.map((a) => a.split("=")[0] ?? a).find((a) => WRITE_FLAGS.includes(a));
+    if (flag)
+        throw new YodelError(`yodel mcp does not run yodel ${verb} ${flag}: it writes`);
+    let out = "";
+    let err = "";
+    const io = { out: (t) => (out += t), err: (t) => (err += t) };
+    const code = await command.run([...args, "--json"], io);
+    return { code, out, err };
+}
+const parse = (text) => {
+    try {
+        return text.trim() === "" ? null : JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+};
+/** `--dir` when the server was started for a project elsewhere. */
+const dirArgs = (dir) => ["--dir", dir];
+const envArg = (args, required) => {
+    const env = args.env;
+    if (env === undefined && !required)
+        return undefined;
+    if (typeof env !== "string" || !/^[\w.-]+$/.test(env))
+        throw new YodelError("env: expected the name of an environment in chant.config.ts");
+    return env;
+};
+async function envelope(tool, verb, args, schema, shape = (r) => r) {
+    const ran = await runVerb(verb, args);
+    const parsed = parse(ran.out);
+    const results = parsed === null ? null : shape(parsed);
+    return {
+        schema: SCHEMA_VERSION,
+        tool,
+        command: ["yodel", verb, ...args.filter((a, i) => a !== "--dir" && args[i - 1] !== "--dir"), "--json"].join(" "),
+        exit: ran.code,
+        results,
+        resultsSchema: schema,
+        ...(ran.err.trim() !== "" ? { error: ran.err.trim() } : {}),
+    };
+}
+const envInput = (required, what) => ({
+    type: "object",
+    properties: { env: { type: "string", description: what } },
+    ...(required ? { required: ["env"] } : {}),
+    additionalProperties: false,
+});
+/** A plan's steps that are a person's: overriding each policy rule that denies it (when it should not stand), and approving it. */
+export function personSteps(env, plan) {
+    const steps = (plan?.policy ?? [])
+        .filter((r) => r.outcome === "denied")
+        .map((r) => ({ action: `override policy rule ${r.id}, if a person on policy.overriders decides it should not stand`, command: `yodel override ${env} --rule ${r.id} --reason "<why>"` }));
+    if (typeof plan?.approve === "string")
+        steps.push({ action: "approve this plan, after reading it", command: plan.approve });
+    return steps;
+}
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const ENV = "The environment, as chant.config.ts names it.";
+/** The tools, for the project in `dir`. */
+export function yodelTools(dir) {
+    return [
+        {
+            name: "status",
+            description: `yodel status <env> --json: applied, pending, out-of-order and part-way migrations, checksum mismatches, and the plan digest apply would ask approval for. Exit 3 when migrations are pending, 4 when apply would refuse. results: ${schemaId(COMMAND_SCHEMAS.status)}`,
+            inputSchema: envInput(true, ENV),
+            annotations: READ_ONLY,
+            verbs: ["status"],
+            handler: (a) => envelope("status", "status", [envArg(a, true), ...dirArgs(dir)], schemaId(COMMAND_SCHEMAS.status)),
+        },
+        {
+            name: "plan",
+            description: `yodel plan <env> --json: what yodel apply would run and the plan digest. When a person must approve the plan, or may override a policy rule that denies it, forPerson has the command they run. Never run those commands: approvals and overrides belong to people. results: ${schemaId(COMMAND_SCHEMAS.plan)}`,
+            inputSchema: envInput(true, ENV),
+            annotations: READ_ONLY,
+            verbs: ["plan"],
+            handler: async (a) => {
+                const env = envArg(a, true);
+                const e = await envelope("plan", "plan", [env, ...dirArgs(dir)], schemaId(COMMAND_SCHEMAS.plan));
+                const forPerson = personSteps(env, e.results);
+                return forPerson.length > 0 ? { ...e, forPerson } : e;
+            },
+        },
+        {
+            name: "lint",
+            description: `yodel lint [--env <env>] --json: the lint findings and silences; with env, also against that environment's history. Exit 3 on an error finding. The replay check is not offered: it writes to a database. results: ${schemaId(COMMAND_SCHEMAS.lint)}`,
+            inputSchema: envInput(false, `${ENV} Optional: compare the migrations with its history.`),
+            annotations: READ_ONLY,
+            verbs: ["lint"],
+            handler: (a) => {
+                const env = envArg(a, false);
+                return envelope("lint", "lint", [...(env ? ["--env", env] : []), ...dirArgs(dir)], schemaId(COMMAND_SCHEMAS.lint));
+            },
+        },
+        {
+            name: "drift",
+            description: `yodel drift <env> --json: the declared objects changed out of band or gone. Exit 2 on drift. results: ${schemaId(COMMAND_SCHEMAS.drift)}`,
+            inputSchema: envInput(true, ENV),
+            annotations: READ_ONLY,
+            verbs: ["drift"],
+            handler: (a) => envelope("drift", "drift", [envArg(a, true), ...dirArgs(dir)], schemaId(COMMAND_SCHEMAS.drift)),
+        },
+        {
+            name: "history",
+            description: `The migrations an environment's history records applied: who applied each, when, under which plan digest, and any repairs. From yodel status <env> --json. results: ${schemaId("mcp")}#/$defs/history`,
+            inputSchema: envInput(true, ENV),
+            annotations: READ_ONLY,
+            verbs: ["status"],
+            handler: (a) => envelope("history", "status", [envArg(a, true), ...dirArgs(dir)], `${schemaId("mcp")}#/$defs/history`, (r) => {
+                const s = r;
+                return { environment: s.environment, ...(s.server ? { server: s.server } : {}), history: s.history, applied: s.applied };
+            }),
+        },
+        {
+            name: "explain",
+            description: `What a lint rule checks and whether it can be silenced (topic: the rule's id, as a finding names it), or what an exit code means (topic: 0 to 5). results: ${schemaId("mcp")}#/$defs/explain`,
+            inputSchema: { type: "object", properties: { topic: { type: "string", description: "A lint rule id (pg-lock, checksum, ...) or an exit code (0 to 5)." } }, required: ["topic"], additionalProperties: false },
+            annotations: READ_ONLY,
+            verbs: ["lint"],
+            handler: async (a) => {
+                const topic = typeof a.topic === "string" ? a.topic.trim() : "";
+                const schema = `${schemaId("mcp")}#/$defs/explain`;
+                const exit = EXIT_CODES.find(([code]) => String(code) === topic);
+                if (exit) {
+                    return { schema: SCHEMA_VERSION, tool: "explain", command: "yodel --help", exit: 0, resultsSchema: schema, results: { topic, kind: "exit-code", code: exit[0], meaning: exit[1], docs: `${DOCS_URL}#the-commands` } };
+                }
+                const e = await envelope("explain", "lint", ["--rules", ...dirArgs(dir)], schema, (r) => {
+                    const rule = r.find((x) => x.id === topic);
+                    return rule ? { topic, kind: "lint-rule", rule, docs: `${DOCS_URL}lint/` } : null;
+                });
+                return e.results === null && e.exit === 0 ? { ...e, exit: 1, error: `no lint rule or exit code ${JSON.stringify(topic)}; yodel lint --rules lists the rules` } : e;
+            },
+        },
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}

package/dist/migrations/checks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pre-migration checks (#52): what `checks` in `migration.json` may hold,
+ * and whether a query's rows pass one. Pure; `../versioned/checks.ts` runs
+ * them against a server.
+ *
+ * A check is part of `migration.json`, so of the migration's checksum and of
+ * the plan digest: editing, adding or removing one moves the digest, and an
+ * approval given before does not carry over.
+ */
+import type { MigrationCheck } from "./document.js";
+export type { MigrationCheck };
+/** What is wrong with a `checks` value read from `migration.json`, or `undefined` when it is well formed. */
+export declare function checksProblem(value: unknown): string | undefined;
+/** What a check expects, in words. */
+export declare function describeExpect(check: MigrationCheck): string;
+export interface CheckOutcome {
+    name: string;
+    passed: boolean;
+    /** What the query returned, in a few words. */
+    detail: string;
+}
+/** Whether `rows`, what the check's query returned, pass it. */
+export declare function judgeCheck(check: MigrationCheck, rows: ReadonlyArray<Record<string, unknown>>): CheckOutcome;
+/**
+ * A `--check` argument: `<sql>`, or `<name>: <sql>`; the name defaults to
+ * `check-<n>`, n counting from 1. The check expects no rows.
+ */
+export declare function parseCheckArg(arg: string, n: number): MigrationCheck;