@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/lsp/registry.js

@@ -0,0 +1,19 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cached = null;
+/** The generated entity registry, indexed once. Empty when generation has not run. */
+export function registryIndex() {
+    if (cached)
+        return cached;
+    let data = {};
+    try {
+        data = require("../generated/lexicon-sql.json");
+    }
+    catch {
+        // No src/generated/ yet (a fresh clone before `npm run generate`): nothing to complete.
+    }
+    cached = new LexiconIndex(data);
+    return cached;
+}

package/dist/lsp/template.js

@@ -0,0 +1,143 @@
+/**
+ * Finding where the cursor is inside a `database`, `table` or `view` template,
+ * and what the SQL before it says should come next. Shares the template finder
+ * with the lint rules, so the editor and `chant lint` agree on what a template
+ * is and which module's tags count.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+import { isTrivia, tokenize } from "../clickhouse/tokens.js";
+import { parseCreate } from "../clickhouse/parser.js";
+import { CLICKHOUSE_TEMPLATE_SOURCE, findTemplates } from "../lint/rules/templates.js";
+import { locateIn } from "../core/find-templates.js";
+export { offsetAt, wordAround } from "../core/find-templates.js";
+/** The ClickHouse template the source offset `at` is inside, and where in it. */
+export function locate(content, at, fileName = "file.ts") {
+    return locateIn(content, at, [CLICKHOUSE_TEMPLATE_SOURCE], fileName);
+}
+/** Significant tokens of the template up to `offset` in `part`; undefined when the text before it does not tokenize. */
+export function tokensBefore(found, part, offset) {
+    try {
+        const parts = [...found.parts.slice(0, part), found.parts[part].slice(0, offset)];
+        return tokenize(parts).filter((t) => !isTrivia(t));
+    }
+    catch {
+        return undefined;
+    }
+}
+const upper = (t) => (t?.kind === "ident" ? t.text.toUpperCase() : "");
+const isPunct = (t, text) => t?.kind === "punct" && t.text === text;
+/** Words that end a SETTINGS list, or start something that is not one. */
+const CLAUSE = new Set([
+    "ENGINE", "ORDER", "PARTITION", "PRIMARY", "SAMPLE", "TTL", "AS", "SELECT", "COMMENT", "FROM", "WHERE", "GROUP",
+    "HAVING", "LIMIT", "UNION", "TO", "POPULATE", "REFRESH", "WITH",
+]);
+/** Words after which an expression is written. */
+const EXPRESSION_AFTER = new Set(["DEFAULT", "MATERIALIZED", "ALIAS", "TTL", "BY", "CHECK", "ASSUME", "SELECT", "WHERE", "HAVING", "ON", "AND", "OR", "WHEN", "THEN", "ELSE"]);
+const TYPE_WRAPPERS = new Set(["NULLABLE", "ARRAY", "LOWCARDINALITY", "MAP", "TUPLE", "NESTED"]);
+const NOT_A_COLUMN = new Set(["INDEX", "PROJECTION", "CONSTRAINT", "PRIMARY"]);
+export function expectAfter(sig, tag) {
+    const last = sig[sig.length - 1];
+    if (!last)
+        return undefined;
+    const prev = sig[sig.length - 2];
+    if (upper(last) === "ENGINE" || (isPunct(last, "=") && upper(prev) === "ENGINE"))
+        return "engine";
+    if (upper(last) === "TYPE")
+        return "index-type";
+    // The innermost open parenthesis, and the word before it.
+    const open = [];
+    sig.forEach((t, i) => {
+        if (isPunct(t, "("))
+            open.push(i);
+        else if (isPunct(t, ")"))
+            open.pop();
+    });
+    const opener = open[open.length - 1];
+    const fn = opener === undefined ? undefined : sig[opener - 1];
+    const afterOpenOrComma = isPunct(last, "(") || isPunct(last, ",");
+    if (afterOpenOrComma && opener !== undefined && upper(fn) === "CODEC")
+        return "codec";
+    if (isPunct(last, "(") && TYPE_WRAPPERS.has(upper(fn)))
+        return "type";
+    // A column's type: `(name |` in the column list, which is the first parenthesis of a table or view.
+    if (tag !== "database" && open.length === 1 && (last.kind === "ident" || last.kind === "qident")) {
+        const inColumnList = !sig.some((t) => upper(t) === "ENGINE" || upper(t) === "AS") && opener === firstParen(sig);
+        if (inColumnList && (isPunct(prev, "(") || isPunct(prev, ",")) && !NOT_A_COLUMN.has(upper(last)))
+            return "type";
+    }
+    // SETTINGS name = value, name = value: a name goes first, or after a comma.
+    if (tag !== "database") {
+        let depth = 0;
+        for (let i = sig.length - 1; i >= 0; i--) {
+            const t = sig[i];
+            if (isPunct(t, ")"))
+                depth++;
+            else if (isPunct(t, "(")) {
+                if (depth === 0)
+                    break;
+                depth--;
+            }
+            else if (depth === 0) {
+                const w = upper(t);
+                if (w === "SETTINGS") {
+                    if (i === sig.length - 1 || isPunct(last, ",")) {
+                        return sig.slice(0, i).some((x) => upper(x) === "SELECT") ? "query-setting" : "merge-tree-setting";
+                    }
+                    break;
+                }
+                if (CLAUSE.has(w))
+                    break;
+            }
+        }
+    }
+    if (EXPRESSION_AFTER.has(upper(last)))
+        return "function";
+    if (sig.some((t) => upper(t) === "SELECT") && (afterOpenOrComma || last.kind === "op"))
+        return "function";
+    return undefined;
+}
+function firstParen(sig) {
+    return sig.findIndex((t) => isPunct(t, "("));
+}
+function spanText(found, tokens, span, source) {
+    if (!span || span.to <= span.from)
+        return undefined;
+    return tokens
+        .slice(span.from, span.to)
+        .map((t) => (t.kind === "ref" ? `\${${found.expressions[t.part]?.getText(source) ?? "..."}}` : t.text))
+        .join("")
+        .trim();
+}
+/** Every `const x = table\`...\`` in the content that parses, by const name. */
+export function declarations(content, fileName = "file.ts") {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+    const out = [];
+    for (const found of findTemplates(source)) {
+        const decl = found.node.parent;
+        if (!decl || !ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name))
+            continue;
+        try {
+            const tokens = tokenize(found.parts);
+            const node = parseCreate(tokens);
+            const columns = node.statement === "database" || node.statement === "function"
+                ? []
+                : (node.statement === "dictionary" ? node.attributes : node.columns).map((c) => ({
+                    name: c.name || spanText(found, tokens, c.nameSpan, source) || "",
+                    ...(spanText(found, tokens, c.type, source) ? { type: spanText(found, tokens, c.type, source) } : {}),
+                }));
+            const engine = node.statement === "dictionary" || node.statement === "function" ? undefined : node.engine?.name || spanText(found, tokens, node.engine?.nameSpan, source);
+            out.push({
+                name: decl.name.text,
+                tag: found.tag,
+                sqlName: spanText(found, tokens, node.name, source) ?? decl.name.text,
+                materialized: node.statement === "view" && node.materialized,
+                columns,
+                ...(engine ? { engine } : {}),
+            });
+        }
+        catch {
+            // A template that does not parse is SQLCH001's to report; it has no columns to offer.
+        }
+    }
+    return out;
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "sql",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "chantVersion": ">=0.1.0",
   "namespace": "SQL",
   "intrinsics": [],

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAwO/F,6CAA6C;AAC7C,wBAAgB,WAAW,IAAI,mBAAmB,EAAE,CAQnD;AAsBD,iDAAiD;AACjD,wBAAgB,eAAe,IAAI,uBAAuB,EAAE,CA+B3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAyO/F,6CAA6C;AAC7C,wBAAgB,WAAW,IAAI,mBAAmB,EAAE,CAQnD;AAsBD,iDAAiD;AACjD,wBAAgB,eAAe,IAAI,uBAAuB,EAAE,CAgC3D"}

package/dist/mcp/index.js

@@ -0,0 +1,293 @@
+/**
+ * MCP contributions for the sql lexicon (chant #3210). Tools answer from the
+ * committed ClickHouse catalog and the tag parser, so an agent can look up an
+ * engine, a type or a setting, and check a statement, without a server.
+ *
+ * Tools register as `sql:<verb>` and resources as `chant://sql/<path>`.
+ */
+import { createCatalogResource, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { sqlSerializer } from "../serializer.js";
+import { catalogIndex } from "../lsp/catalog.js";
+import { database, dictionary, func, grant, policy, quota, role, settingsProfile, table, user, view } from "../clickhouse/entities.js";
+import { SqlSyntaxError } from "../clickhouse/tokens.js";
+import { existsSync, readFileSync } from "fs";
+import { diffSchemas } from "../clickhouse/plan/diff.js";
+import { renderDiff } from "../clickhouse/plan/report.js";
+import { rebuildOpSuggestions } from "../clickhouse/plan/rebuild-handoff.js";
+import { CLASSIFIER_RULES } from "../clickhouse/plan/rules.js";
+import { schemaFromBuildFile, schemaFromBuildOutput } from "../clickhouse/plan/schema.js";
+import { asMajor, POSTGRES_KINDS, POSTGRES_TAGS, postgresLookup, postgresMcpResources, postgresParse, postgresSearch } from "./postgres.js";
+import { diffPgSchemas } from "../postgres/plan/diff.js";
+import { renderPgDiff } from "../postgres/plan/report.js";
+import { PG_CLASSIFIER_RULES } from "../postgres/plan/rules.js";
+import { pgSchemaFromBuildFile, pgSchemaFromBuildOutput } from "../postgres/plan/schema.js";
+import { migrationOpSuggestions } from "../postgres/migrate/handoff.js";
+import { CLICKHOUSE_IMAGE_DIGEST, CLICKHOUSE_VERSION, clickhouseImage } from "../spec/pin.js";
+const KINDS = ["engine", "database-engine", "type", "codec", "index-type", "setting", "function", "format"];
+const kindProp = {
+    type: "string",
+    enum: [...new Set([...KINDS, ...POSTGRES_KINDS])],
+    description: `Which part of the catalog. ClickHouse: ${KINDS.join(", ")}. Postgres: ${POSTGRES_KINDS.join(", ")}`,
+};
+const dialectProp = { type: "string", enum: ["clickhouse", "postgres"], description: "The dialect to answer for (default clickhouse)" };
+const majorProp = { type: "number", description: "Postgres only: answer for this major (14 to 18; for classify-change, the server's major); omitted, every major, with since/until on names not in all" };
+function asDialect(value) {
+    if (value === undefined || value === "clickhouse")
+        return "clickhouse";
+    if (value === "postgres")
+        return "postgres";
+    throw new Error("dialect must be clickhouse or postgres");
+}
+function rows(kind) {
+    const index = catalogIndex();
+    if (!index)
+        throw new Error("the ClickHouse catalog snapshot could not be read");
+    const { catalog } = index;
+    switch (kind) {
+        case "engine":
+            return catalog.tableEngines;
+        case "database-engine":
+            return catalog.databaseEngines;
+        case "type":
+            return catalog.typeFamilies;
+        case "codec":
+            return catalog.codecs;
+        case "index-type":
+            return catalog.skipIndexTypes;
+        case "setting":
+            return [
+                ...catalog.mergeTreeSettings.map((s) => ({ ...s, scope: "merge-tree" })),
+                ...catalog.querySettings.map((s) => ({ ...s, scope: "query" })),
+            ];
+        case "function":
+            return catalog.functions;
+        case "format":
+            return catalog.formats;
+    }
+}
+function asKind(value) {
+    if (!KINDS.includes(value))
+        throw new Error(`kind must be one of: ${KINDS.join(", ")}`);
+    return value;
+}
+const lookupTool = {
+    name: "lookup",
+    description: "Look up a catalog entry by name. ClickHouse (default): engine, type family, codec, skip index type, setting, function or format, from the pinned server (" +
+        CLICKHOUSE_VERSION +
+        "). Postgres (dialect postgres): type or alias, index or table access method, storage parameter, setting, function, key word or extension, from the pinned servers of majors 14 to 18, with since/until. Returns every catalog row with that name, or the closest names when there is none.",
+    inputSchema: { type: "object", properties: { dialect: dialectProp, kind: kindProp, name: { type: "string" }, major: majorProp }, required: ["kind", "name"] },
+    async handler(params) {
+        if (asDialect(params.dialect) === "postgres")
+            return postgresLookup(params);
+        const kind = asKind(params.kind);
+        const name = String(params.name ?? "");
+        const all = rows(kind);
+        const exact = all.filter((r) => r.name === name);
+        const found = exact.length ? exact : all.filter((r) => r.name.toLowerCase() === name.toLowerCase());
+        if (found.length)
+            return { kind, version: CLICKHOUSE_VERSION, matches: found };
+        const near = all.filter((r) => r.name.toLowerCase().includes(name.toLowerCase())).slice(0, 10).map((r) => r.name);
+        return { kind, version: CLICKHOUSE_VERSION, matches: [], closest: near };
+    },
+};
+const searchTool = {
+    name: "search",
+    description: "Search one part of a dialect's catalog by a name substring. Returns names with the first line of their description.",
+    inputSchema: {
+        type: "object",
+        properties: { dialect: dialectProp, kind: kindProp, query: { type: "string" }, major: majorProp, limit: { type: "number", description: "At most this many results (default 25)" } },
+        required: ["kind", "query"],
+    },
+    async handler(params) {
+        if (asDialect(params.dialect) === "postgres")
+            return postgresSearch(params);
+        const kind = asKind(params.kind);
+        const query = String(params.query ?? "").toLowerCase();
+        const limit = Math.max(1, Math.min(200, Number(params.limit ?? 25)));
+        const hits = rows(kind).filter((r) => r.name.toLowerCase().includes(query));
+        return {
+            kind,
+            total: hits.length,
+            results: hits.slice(0, limit).map((r) => ({ name: r.name, ...(typeof r.summary === "string" ? { summary: r.summary } : {}) })),
+        };
+    },
+};
+const parseTool = {
+    name: "parse-ddl",
+    description: "Parse one CREATE statement the way its tag does (dialect clickhouse, the default: table, view, database, dictionary, func, user, role, policy, quota, settingsProfile, grant; dialect postgres: schema, table, index, view, sequence, type, domain, extension), and return the entity it builds (columns, engine, keys, settings, and for a view its lineage). A statement that does not parse comes back as the error with its line and column, the same one SQLCH001 (ClickHouse) or SQLPG001 (Postgres) reports. The statement is plain DDL: there are no interpolations.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            dialect: dialectProp,
+            tag: { type: "string", enum: [...new Set(["table", "view", "database", "dictionary", "func", "user", "role", "policy", "quota", "settingsProfile", "grant", ...POSTGRES_TAGS])], description: "The tag the statement belongs in (ClickHouse: table, view, database, dictionary, func, user, role, policy, quota, settingsProfile, grant; Postgres: " + POSTGRES_TAGS.join(", ") + ")" },
+            ddl: { type: "string", description: "The CREATE statement" },
+        },
+        required: ["tag", "ddl"],
+    },
+    async handler(params) {
+        const ddl = String(params.ddl ?? "");
+        const tag = String(params.tag);
+        if (asDialect(params.dialect) === "postgres")
+            return postgresParse(tag, ddl, position);
+        const build = tag === "table" ? table : tag === "view" ? view : tag === "database" ? database : tag === "dictionary" ? dictionary : tag === "func" ? func : tag === "user" ? user : tag === "role" ? role : tag === "policy" ? policy : tag === "quota" ? quota : tag === "settingsProfile" ? settingsProfile : tag === "grant" ? grant : undefined;
+        if (!build)
+            throw new Error("tag must be table, view, database, dictionary, func, user, role, policy, quota, settingsProfile or grant");
+        const strings = Object.assign([ddl], { raw: [ddl] });
+        try {
+            const entity = build(strings);
+            return { ok: true, entityType: entity.entityType, name: entity.sqlName, props: JSON.parse(JSON.stringify(entity.props)) };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const offset = err.offset;
+            const where = typeof offset === "number" ? position(ddl, offset) : undefined;
+            const syntax = err instanceof SqlSyntaxError || err.name === "SqlTemplateError";
+            return { ok: false, rule: syntax ? "SQLCH001" : undefined, message, ...(where ?? {}) };
+        }
+    },
+};
+const classifyTool = {
+    name: "classify-change",
+    description: "Classify the schema change between two revisions of a sql lexicon build, offline. Each side is a `chant build` output (a path to the file, or its JSON text); the dialect is the one the output names, or `dialect`. ClickHouse: every change with its class (create, drop, metadata, rewrite, rebuild), the SQLCH2xx rule and the ClickHouse restriction behind it with its documentation link, the rebuilds a plan must refuse in place with the ClickHouseRebuildOp declaration to run each one as, rename hints, and a rendered report. Postgres: every change with its class by the lock it takes (create, metadata, validate, concurrently, rewrite, expand, drop), the SQLPG2xx rule and its restriction with its Postgres documentation link, the `refused` changes that can only be made as expand and contract with the PostgresMigrationOp declaration to run each column rename or type change across kinds as (`migrationOps`), rename hints and a rendered report; `major` is the server's major (default the newest pinned).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            before: { type: "string", description: "The earlier build output: a file path or the JSON text" },
+            after: { type: "string", description: "The later build output: a file path or the JSON text" },
+            dialect: dialectProp,
+            major: majorProp,
+        },
+        required: ["before", "after"],
+    },
+    async handler(params) {
+        if (buildDialect(params) === "postgres")
+            return classifyPostgres(params);
+        const side = (v) => {
+            const text = String(v ?? "");
+            return !text.trimStart().startsWith("{") && existsSync(text) ? schemaFromBuildFile(text) : schemaFromBuildOutput(text);
+        };
+        const after = side(params.after);
+        const plain = diffSchemas(side(params.before), after);
+        const rebuildOps = rebuildOpSuggestions(plain, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+        const diff = rebuildOps.length > 0 ? { ...plain, rebuildOps } : plain;
+        const classes = {};
+        for (const c of diff.changes)
+            classes[c.class] = (classes[c.class] ?? 0) + 1;
+        return {
+            summary: classes,
+            changes: diff.changes.map((c) => ({ ...c, restriction: CLASSIFIER_RULES[c.rule].restriction, cite: CLASSIFIER_RULES[c.rule].cite })),
+            rebuilds: diff.rebuilds,
+            rebuildOps,
+            hints: diff.hints,
+            report: renderDiff(diff),
+        };
+    },
+};
+/** The dialect a classify call is for: `dialect`, else the one either build output names, else ClickHouse. */
+function buildDialect(params) {
+    if (params.dialect !== undefined)
+        return asDialect(params.dialect);
+    for (const v of [params.after, params.before]) {
+        const text = String(v ?? "");
+        try {
+            const json = text.trimStart().startsWith("{") ? text : existsSync(text) ? readFileSync(text, "utf-8") : "";
+            const d = JSON.parse(json).dialect;
+            if (d === "postgres")
+                return "postgres";
+            if (d === "clickhouse")
+                return "clickhouse";
+        }
+        catch {
+            // Not JSON we can read: the schema reader reports it.
+        }
+    }
+    return "clickhouse";
+}
+function classifyPostgres(params) {
+    const side = (v) => {
+        const text = String(v ?? "");
+        return !text.trimStart().startsWith("{") && existsSync(text) ? pgSchemaFromBuildFile(text) : pgSchemaFromBuildOutput(text);
+    };
+    const after = side(params.after);
+    const plain = diffPgSchemas(side(params.before), after, { major: asMajor(params.major) });
+    const migrationOps = migrationOpSuggestions(plain.refused, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+    const diff = migrationOps.length > 0 ? { ...plain, migrationOps } : plain;
+    const classes = {};
+    for (const c of diff.changes)
+        classes[c.class] = (classes[c.class] ?? 0) + 1;
+    return {
+        dialect: "postgres",
+        summary: classes,
+        changes: diff.changes.map((c) => ({ ...c, restriction: PG_CLASSIFIER_RULES[c.rule].restriction, cite: PG_CLASSIFIER_RULES[c.rule].cite })),
+        refused: diff.refused.map((c) => ({
+            object: c.object,
+            field: c.field,
+            rule: c.rule,
+            advice: "No in-place change keeps old readers working: run it as expand and contract (add the new, write both, backfill, move readers, drop the old), as a migration Op.",
+        })),
+        migrationOps,
+        hints: diff.hints,
+        report: renderPgDiff(diff),
+    };
+}
+function position(text, offset) {
+    const before = text.slice(0, offset).split("\n");
+    return { line: before.length, column: before[before.length - 1].length + 1 };
+}
+/** The tools the sql lexicon contributes. */
+export function sqlMcpTools() {
+    return [
+        lookupTool,
+        searchTool,
+        parseTool,
+        classifyTool,
+        createDiffTool(sqlSerializer, "Compare current sql build output against the previous build", "sql"),
+    ];
+}
+const json = (value) => JSON.stringify(value, null, 2);
+function catalogResource(uri, name, description, read) {
+    return {
+        uri,
+        name,
+        description,
+        mimeType: "application/json",
+        async handler() {
+            return json(read());
+        },
+    };
+}
+const need = () => {
+    const index = catalogIndex();
+    if (!index)
+        throw new Error("the ClickHouse catalog snapshot could not be read");
+    return index.catalog;
+};
+/** The resources the sql lexicon contributes. */
+export function sqlMcpResources() {
+    return [
+        // `generated/` sits beside plugin.ts, which is where the helper looks. The
+        // source URL, so a compiled module names src/plugin.ts too (#3981).
+        createCatalogResource(new URL("../plugin.ts", moduleSourceUrl(import.meta.url)).href, "SQL Entity Catalog", "The entity kinds the sql lexicon declares (database, table, view, materialized view, dictionary, function, user, role, row policy, grant)", "lexicon-sql.json", "sql"),
+        ...postgresMcpResources(),
+        catalogResource("clickhouse-pin", "ClickHouse Pin", "The pinned ClickHouse server the catalog was read from", () => ({
+            version: CLICKHOUSE_VERSION,
+            image: clickhouseImage(),
+            digest: CLICKHOUSE_IMAGE_DIGEST,
+        })),
+        catalogResource("clickhouse-engines", "ClickHouse Engines", "Table and database engines with their usage line, summary and capabilities", () => ({
+            tableEngines: need().tableEngines,
+            databaseEngines: need().databaseEngines,
+        })),
+        catalogResource("clickhouse-types", "ClickHouse Types", "Column type families, with aliases and case sensitivity", () => need().typeFamilies),
+        catalogResource("clickhouse-codecs", "ClickHouse Codecs", "Column codecs and skip index types", () => ({
+            codecs: need().codecs,
+            skipIndexTypes: need().skipIndexTypes,
+        })),
+        catalogResource("clickhouse-settings", "ClickHouse Settings", "MergeTree and query settings with type, default and tier", () => ({
+            mergeTreeSettings: need().mergeTreeSettings,
+            querySettings: need().querySettings,
+        })),
+        catalogResource("clickhouse-functions", "ClickHouse Functions", "Function names, with which are aggregate and which are aliases", () => need().functions),
+    ];
+}

package/dist/mcp/postgres.js

@@ -0,0 +1,117 @@
+/**
+ * The Postgres side of the sql MCP tools and resources (chant #3283). Rows
+ * come from the committed catalogs of the pinned servers, one per major; a
+ * name present in only some majors carries `since` and `until`, as the
+ * generated types' `@since` / `@until` do.
+ */
+import { POSTGRES_LATEST_MAJOR, POSTGRES_MAJORS, POSTGRES_PINS, postgresImage } from "../spec/postgres-pin.js";
+import { section } from "../lsp/postgres-catalog.js";
+import * as pg from "../postgres/entities.js";
+import { SqlSyntaxError } from "../postgres/tokens.js";
+export const POSTGRES_KINDS = ["type", "index-method", "table-method", "storage-parameter", "setting", "function", "keyword", "extension"];
+const SECTION = {
+    type: "types",
+    "index-method": "accessMethods",
+    "table-method": "accessMethods",
+    "storage-parameter": "storageParameters",
+    setting: "settings",
+    function: "functions",
+    keyword: "keywords",
+    extension: "extensions",
+};
+export function asPostgresKind(value) {
+    if (!POSTGRES_KINDS.includes(value))
+        throw new Error(`kind must be one of: ${POSTGRES_KINDS.join(", ")}`);
+    return value;
+}
+/** The major a tool call is about: `major` when given, else every major (undefined). */
+export function asMajor(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const n = Number(value);
+    if (!POSTGRES_MAJORS.includes(n))
+        throw new Error(`major must be one of: ${POSTGRES_MAJORS.join(", ")}`);
+    return n;
+}
+/** The rows of a kind, each with its range; only those at `major` when one is given. */
+export function postgresRows(kind, major) {
+    const s = section(SECTION[kind]);
+    if (!s)
+        throw new Error("the Postgres catalog snapshots could not be read");
+    const wantType = kind === "index-method" ? "index" : kind === "table-method" ? "table" : undefined;
+    const out = [];
+    for (const e of s.values()) {
+        if (major !== undefined && !e.majors.includes(major))
+            continue;
+        if (wantType && e.row.type !== wantType)
+            continue;
+        const summary = typeof e.row.description === "string" ? e.row.description : e.detail;
+        out.push({ ...e.row, name: e.name, ...(summary ? { summary } : {}), ...e.range });
+    }
+    return out;
+}
+export function postgresLookup(params) {
+    const kind = asPostgresKind(params.kind);
+    const major = asMajor(params.major);
+    const name = String(params.name ?? "");
+    const all = postgresRows(kind, major);
+    const exact = all.filter((r) => r.name === name);
+    const found = exact.length ? exact : all.filter((r) => r.name.toLowerCase() === name.toLowerCase());
+    const base = { dialect: "postgres", kind, majors: major !== undefined ? [major] : POSTGRES_MAJORS };
+    if (found.length)
+        return { ...base, matches: found };
+    const near = all.filter((r) => r.name.toLowerCase().includes(name.toLowerCase())).slice(0, 10).map((r) => r.name);
+    return { ...base, matches: [], closest: near };
+}
+export function postgresSearch(params) {
+    const kind = asPostgresKind(params.kind);
+    const query = String(params.query ?? "").toLowerCase();
+    const limit = Math.max(1, Math.min(200, Number(params.limit ?? 25)));
+    const hits = postgresRows(kind, asMajor(params.major)).filter((r) => r.name.toLowerCase().includes(query));
+    return {
+        dialect: "postgres",
+        kind,
+        total: hits.length,
+        results: hits.slice(0, limit).map((r) => ({ name: r.name, ...(r.summary ? { summary: r.summary } : {}), ...(r.since ? { since: r.since } : {}), ...(r.until ? { until: r.until } : {}) })),
+    };
+}
+const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, aggregate: pg.aggregate, trigger: pg.trigger, eventTrigger: pg.eventTrigger, collation: pg.collation, cast: pg.cast, policy: pg.policy, role: pg.role, grant: pg.grant };
+export const POSTGRES_TAGS = Object.keys(TAGS);
+/** Parse one statement with the Postgres tag; an error comes back as SQLPG001 with its line and column. */
+export function postgresParse(tag, ddl, position) {
+    const build = TAGS[tag];
+    if (!build)
+        throw new Error(`tag must be one of: ${POSTGRES_TAGS.join(", ")}`);
+    const strings = Object.assign([ddl], { raw: [ddl] });
+    try {
+        const entity = build(strings);
+        return { ok: true, dialect: "postgres", entityType: entity.entityType, name: entity.sqlName, props: JSON.parse(JSON.stringify(entity.props)) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const offset = err.offset;
+        const where = typeof offset === "number" ? position(ddl, offset) : undefined;
+        const syntax = err instanceof SqlSyntaxError || err.name === "SqlTemplateError";
+        return { ok: false, dialect: "postgres", rule: syntax ? "SQLPG001" : undefined, message, ...(where ?? {}) };
+    }
+}
+const json = (value) => JSON.stringify(value, null, 2);
+function resource(uri, name, description, read) {
+    return { uri, name, description, mimeType: "application/json", async handler() { return json(read()); } };
+}
+/** The Postgres resources: every supported major's names in one list, each with `since` / `until` when not in all. */
+export function postgresMcpResources() {
+    const all = (...kinds) => Object.fromEntries(kinds.map((k) => [k, postgresRows(k)]));
+    return [
+        resource("postgres-pin", "Postgres Pins", "The pinned server for each supported major the catalogs were read from", () => ({
+            latest: POSTGRES_LATEST_MAJOR,
+            pins: POSTGRES_PINS.map((p) => ({ ...p, image: postgresImage(p.major) })),
+        })),
+        resource("postgres-types", "Postgres Types", "Column types and their aliases, with since/until majors", () => postgresRows("type")),
+        resource("postgres-access-methods", "Postgres Access Methods", "Index access methods (btree, gin...) and table access methods", () => all("index-method", "table-method")),
+        resource("postgres-storage-parameters", "Postgres Storage Parameters", "WITH (...) parameters, the relation kinds that accept each, and their types", () => postgresRows("storage-parameter")),
+        resource("postgres-functions", "Postgres Functions", "Built-in function names with since/until majors", () => postgresRows("function")),
+        resource("postgres-keywords", "Postgres Keywords", "Key words and their categories", () => postgresRows("keyword")),
+        resource("postgres-settings", "Postgres Settings", "Server settings with type, default and range", () => postgresRows("setting")),
+    ];
+}