@ecubelabs/mysql-mcp 0.0.0-stage → 0.0.1

package/dist/src/catalog/collect.js

@@ -0,0 +1,220 @@
+import { executeQuery } from '../db/index.js';
+import { emptyTable, normalizeName } from './types.js';
+function chainAfter(pending, run) {
+    if (!pending) {
+        return run();
+    }
+    return pending.catch(() => undefined).then(run);
+}
+function isExpired(value, ttlHours) {
+    if (!value) {
+        return true;
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        return true;
+    }
+    return Date.now() - parsed >= ttlHours * 60 * 60 * 1_000;
+}
+export class CatalogCollector {
+    store;
+    options;
+    inventoryPromise = null;
+    detailPromises = new Map();
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+    }
+    inventoryNeedsRefresh() {
+        return this.options.schemas.some((name) => {
+            const state = this.store.schemaState(name);
+            return !state || isExpired(state.scannedAt, this.options.ttlHours);
+        });
+    }
+    async collectInventory(force = false) {
+        if (!this.store.isEnabled() || this.options.schemas.length === 0) {
+            return;
+        }
+        if (!force && !this.inventoryNeedsRefresh()) {
+            return;
+        }
+        const pending = this.inventoryPromise;
+        if (pending && !force) {
+            return pending;
+        }
+        const promise = chainAfter(pending, () => this.runInventory()).finally(() => {
+            if (this.inventoryPromise === promise) {
+                this.inventoryPromise = null;
+            }
+        });
+        this.inventoryPromise = promise;
+        return promise;
+    }
+    async runInventory() {
+        const placeholders = this.options.schemas.map(() => '?').join(', ');
+        const rows = await executeQuery(`SELECT
+         table_schema AS \`table_schema\`,
+         table_name AS \`table_name\`,
+         table_comment AS \`table_comment\`,
+         table_rows AS \`table_rows\`
+       FROM information_schema.tables
+       WHERE table_schema IN (${placeholders})
+       ORDER BY table_schema, table_name`, [...this.options.schemas]);
+        const declaredBySchema = new Map(this.options.schemas.map((name) => [normalizeName(name), name]));
+        const rowsBySchema = new Map();
+        for (const row of rows) {
+            const declared = declaredBySchema.get(normalizeName(String(row.table_schema)));
+            if (!declared) {
+                continue;
+            }
+            const bucket = rowsBySchema.get(declared);
+            if (bucket) {
+                bucket.push(row);
+            }
+            else {
+                rowsBySchema.set(declared, [row]);
+            }
+        }
+        const now = new Date().toISOString();
+        this.store.update((catalog) => {
+            for (const schemaName of this.options.schemas) {
+                const schema = catalog.schemas[schemaName];
+                if (!schema) {
+                    continue;
+                }
+                const nextTables = Object.fromEntries((rowsBySchema.get(schemaName) ?? []).map((row) => {
+                    const existing = schema.tables[row.table_name] ?? emptyTable();
+                    const numericRows = Number(row.table_rows);
+                    return [
+                        row.table_name,
+                        {
+                            ...existing,
+                            comment: row.table_comment ?? '',
+                            rowsEstimate: Number.isFinite(numericRows) ? numericRows : null,
+                        },
+                    ];
+                }));
+                schema.tables = nextTables;
+                schema.scannedAt = now;
+            }
+        });
+        for (const schemaName of this.options.schemas) {
+            if (!rowsBySchema.has(schemaName)) {
+                console.error(`[catalog] declared schema "${schemaName}" returned no tables; check MYSQL_APP_SCHEMAS and the account's grants.`);
+            }
+        }
+        console.error(`[catalog] inventory scan complete: ${this.options.schemas.length} schemas, ${rows.length} tables`);
+    }
+    detailNeedsRefresh(schemaName, tableName) {
+        const meta = this.store.tableMeta(schemaName, tableName);
+        return Boolean(meta && (meta.detailStale || isExpired(meta.detailScannedAt, this.options.ttlHours)));
+    }
+    async collectTableDetail(schemaName, tableName, force = false) {
+        if (!this.store.isEnabled()) {
+            return;
+        }
+        if (!force && !this.detailNeedsRefresh(schemaName, tableName)) {
+            return;
+        }
+        const key = `${schemaName}.${tableName}`;
+        const pending = this.detailPromises.get(key);
+        if (pending && !force) {
+            return pending;
+        }
+        const promise = chainAfter(pending, () => this.runTableDetail(schemaName, tableName)).finally(() => {
+            if (this.detailPromises.get(key) === promise) {
+                this.detailPromises.delete(key);
+            }
+        });
+        this.detailPromises.set(key, promise);
+        return promise;
+    }
+    async runTableDetail(schemaName, tableName) {
+        const rows = await executeQuery(`SELECT
+         'column' AS kind,
+         c.column_name AS name,
+         c.data_type AS \`data_type\`,
+         c.column_type AS \`column_type\`,
+         c.is_nullable AS \`is_nullable\`,
+         CAST(c.column_default AS CHAR) AS default_value,
+         c.extra AS \`extra\`,
+         c.column_comment AS comment,
+         c.ordinal_position AS position,
+         NULL AS index_column,
+         NULL AS non_unique,
+         NULL AS index_type,
+         NULL AS fk_column,
+         NULL AS ref_schema,
+         NULL AS ref_table,
+         NULL AS ref_column
+       FROM information_schema.columns c
+       WHERE c.table_schema = ? AND c.table_name = ?
+       UNION ALL
+       SELECT
+         'index', s.index_name, NULL, NULL, NULL, NULL, NULL, NULL,
+         s.seq_in_index, s.column_name, s.non_unique, s.index_type,
+         NULL, NULL, NULL, NULL
+       FROM information_schema.statistics s
+       WHERE s.table_schema = ? AND s.table_name = ?
+       UNION ALL
+       SELECT
+         'fk', k.constraint_name, NULL, NULL, NULL, NULL, NULL, NULL,
+         k.ordinal_position, NULL, NULL, NULL,
+         k.column_name, k.referenced_table_schema,
+         k.referenced_table_name, k.referenced_column_name
+       FROM information_schema.key_column_usage k
+       WHERE k.table_schema = ? AND k.table_name = ?
+         AND k.referenced_table_name IS NOT NULL
+       ORDER BY kind, position`, [schemaName, tableName, schemaName, tableName, schemaName, tableName]);
+        const columns = rows
+            .filter((row) => row.kind === 'column')
+            .map((row) => ({
+            name: row.name,
+            dataType: row.data_type ?? '',
+            columnType: row.column_type ?? '',
+            nullable: row.is_nullable === 'YES',
+            defaultValue: row.default_value,
+            extra: row.extra ?? '',
+            comment: row.comment ?? '',
+            ordinal: Number(row.position),
+        }));
+        const indexesByName = new Map();
+        for (const row of rows) {
+            if (row.kind !== 'index' || !row.index_column) {
+                continue;
+            }
+            const index = indexesByName.get(row.name) ?? {
+                name: row.name,
+                unique: Number(row.non_unique) === 0,
+                type: row.index_type ?? '',
+                columns: [],
+            };
+            index.columns.push(row.index_column);
+            indexesByName.set(row.name, index);
+        }
+        const indexes = [...indexesByName.values()];
+        const pk = indexes.find((index) => index.name === 'PRIMARY')?.columns ?? [];
+        const fks = rows
+            .filter((row) => row.kind === 'fk' && Boolean(row.fk_column && row.ref_schema && row.ref_table && row.ref_column))
+            .map((row) => ({
+            name: row.name,
+            column: row.fk_column,
+            referencedSchema: row.ref_schema,
+            referencedTable: row.ref_table,
+            referencedColumn: row.ref_column,
+        }));
+        this.store.update((catalog) => {
+            const table = catalog.schemas[schemaName]?.tables[tableName];
+            if (!table) {
+                return;
+            }
+            table.columns = columns;
+            table.pk = pk;
+            table.indexes = indexes;
+            table.fks = fks;
+            table.detailScannedAt = new Date().toISOString();
+            delete table.detailStale;
+        });
+        console.error(`[catalog] detail scan complete: ${schemaName}.${tableName} (${columns.length} columns)`);
+    }
+}

package/dist/src/catalog/docs.js

@@ -0,0 +1,328 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1_000;
+const GIT_TIMEOUT_MS = 10_000;
+export function modelPaths(output) {
+    return output.split('\0').filter((path) => path.endsWith('model.md'));
+}
+export function parseDiff(output) {
+    const entries = [];
+    const fields = output.split('\0');
+    let index = 0;
+    while (index < fields.length) {
+        const kind = fields[index]?.[0];
+        if (kind === 'R' || kind === 'C') {
+            const oldPath = fields[index + 1];
+            const path = fields[index + 2];
+            if (kind === 'R' && oldPath && path) {
+                entries.push({ status: 'R', oldPath, path });
+            }
+            index += 3;
+        }
+        else if (kind) {
+            const path = fields[index + 1];
+            if ((kind === 'A' || kind === 'D' || kind === 'M') && path) {
+                entries.push({ status: kind, path });
+            }
+            index += 2;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return entries;
+}
+function linkedDocumentPaths(catalog) {
+    const linked = new Set();
+    for (const schema of Object.values(catalog.schemas)) {
+        for (const table of Object.values(schema.tables)) {
+            if (table.curated.doc) {
+                linked.add(table.curated.doc.path);
+            }
+        }
+    }
+    return linked;
+}
+function refreshUnlinked(catalog) {
+    const linked = linkedDocumentPaths(catalog);
+    catalog.docs.unlinked = catalog.docs.paths.filter((path) => !linked.has(path));
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export class CatalogDocuments {
+    store;
+    options;
+    attempted = false;
+    wakePromise = null;
+    wakeSpent = false;
+    disabledReason = null;
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+    }
+    isConfigured() {
+        return Boolean(this.options.repo && this.options.ref);
+    }
+    isAvailable() {
+        return this.isConfigured() && this.disabledReason === null;
+    }
+    error() {
+        return this.disabledReason;
+    }
+    resetWake() {
+        this.attempted = false;
+        this.disabledReason = null;
+        this.wakeSpent = this.wakePromise !== null;
+    }
+    async git(args) {
+        if (!this.options.repo) {
+            throw new Error('MYSQL_DOCS_REPO is not configured.');
+        }
+        console.error(`[catalog] git -C ${this.options.repo} ${args.join(' ')}`);
+        const { stdout } = await execFileAsync('git', ['-C', this.options.repo, ...args], {
+            encoding: 'utf8',
+            maxBuffer: 5 * 1024 * 1024,
+            timeout: GIT_TIMEOUT_MS,
+        });
+        return stdout;
+    }
+    async ensureAwake() {
+        if (!this.isConfigured()) {
+            throw new Error('The document catalog is disabled because MYSQL_DOCS_REPO or MYSQL_CODE_BRANCH is not configured.');
+        }
+        if (this.disabledReason) {
+            throw new Error(this.disabledReason);
+        }
+        if (this.attempted && !this.wakePromise) {
+            return;
+        }
+        let promise = this.wakePromise;
+        if (!promise || this.wakeSpent) {
+            this.attempted = true;
+            const previous = promise && this.wakeSpent ? promise.catch(() => undefined) : null;
+            this.wakeSpent = false;
+            promise = (previous ?? Promise.resolve())
+                .then(() => this.wake())
+                .catch((error) => {
+                this.disabledReason = `The document catalog is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+                console.error(`[catalog] document axis disabled: ${this.disabledReason}`);
+                throw new Error(this.disabledReason);
+            });
+            this.wakePromise = promise;
+        }
+        try {
+            await promise;
+        }
+        finally {
+            if (this.wakePromise === promise) {
+                this.wakePromise = null;
+            }
+        }
+    }
+    async wake() {
+        const ref = this.options.ref;
+        const commit = (await this.git(['rev-parse', '--verify', `${ref}^{commit}`])).trim();
+        const cached = this.store.docsView();
+        if (cached.refCommit === commit) {
+            return;
+        }
+        let entries = null;
+        if (cached.refCommit) {
+            try {
+                entries = parseDiff(await this.git(['diff', '--name-status', '-z', cached.refCommit, commit, '--', '*model.md']));
+            }
+            catch (error) {
+                console.error(`[catalog] cached document commit is unavailable; rebuilding path list: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (entries === null) {
+            const paths = modelPaths(await this.git(['ls-tree', '-r', '-z', '--name-only', commit]));
+            this.store.update((catalog) => {
+                catalog.docs.paths = paths;
+                for (const schema of Object.values(catalog.schemas)) {
+                    for (const table of Object.values(schema.tables)) {
+                        if (table.curated.doc && !paths.includes(table.curated.doc.path)) {
+                            delete table.curated.doc;
+                        }
+                    }
+                }
+                refreshUnlinked(catalog);
+            });
+        }
+        else {
+            this.store.update((catalog) => {
+                for (const entry of entries) {
+                    if (entry.status === 'M') {
+                        continue;
+                    }
+                    if (entry.status === 'A') {
+                        if (!catalog.docs.paths.includes(entry.path)) {
+                            catalog.docs.paths.push(entry.path);
+                        }
+                        continue;
+                    }
+                    if (entry.status === 'D') {
+                        catalog.docs.paths = catalog.docs.paths.filter((path) => path !== entry.path);
+                        for (const schema of Object.values(catalog.schemas)) {
+                            for (const table of Object.values(schema.tables)) {
+                                if (table.curated.doc?.path === entry.path) {
+                                    delete table.curated.doc;
+                                }
+                            }
+                        }
+                        continue;
+                    }
+                    const oldPath = entry.oldPath;
+                    catalog.docs.paths = catalog.docs.paths.map((path) => (path === oldPath ? entry.path : path));
+                    if (!catalog.docs.paths.includes(entry.path)) {
+                        catalog.docs.paths.push(entry.path);
+                    }
+                    for (const schema of Object.values(catalog.schemas)) {
+                        for (const table of Object.values(schema.tables)) {
+                            if (table.curated.doc?.path === oldPath) {
+                                table.curated.doc.path = entry.path;
+                            }
+                        }
+                    }
+                }
+                catalog.docs.paths = [...new Set(catalog.docs.paths)].sort();
+                refreshUnlinked(catalog);
+            });
+        }
+        let refUpdatedAt = null;
+        try {
+            const seconds = Number((await this.git(['show', '-s', '--format=%ct', commit])).trim());
+            if (Number.isFinite(seconds)) {
+                refUpdatedAt = new Date(seconds * 1_000).toISOString();
+            }
+        }
+        catch (error) {
+            console.error(`[catalog] could not read document ref timestamp: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.store.update((catalog) => {
+            catalog.docs.repo = this.options.repo;
+            catalog.docs.ref = this.options.ref;
+            catalog.docs.refCommit = commit;
+            catalog.docs.refUpdatedAt = refUpdatedAt;
+        });
+        console.error(`[catalog] document paths refreshed: ${this.store.docsView().paths.length} files at ${ref}`);
+    }
+    async list(schemaName) {
+        await this.ensureAwake();
+        const mapping = this.options.appSchemas.find((entry) => entry.schema.toLowerCase() === schemaName.toLowerCase());
+        if (!mapping) {
+            throw new Error(`Schema "${schemaName}" is not declared in MYSQL_APP_SCHEMAS.`);
+        }
+        const catalog = this.store.snapshot();
+        const prefix = `apps/${mapping.app}/`;
+        const inPrefix = catalog.docs.paths.filter((path) => path.startsWith(prefix));
+        const scoped = inPrefix.length > 0;
+        const selected = scoped ? inPrefix : catalog.docs.paths;
+        const linkedTablesFor = (path) => Object.entries(catalog.schemas).flatMap(([knownSchema, schema]) => Object.entries(schema.tables)
+            .filter(([, table]) => table.curated.doc?.path === path)
+            .map(([table]) => `${knownSchema}.${table}`));
+        const paths = selected.map((path) => ({
+            path,
+            linkedTables: linkedTablesFor(path),
+        }));
+        const outsidePrefix = catalog.docs.paths.length - inPrefix.length;
+        const notice = scoped
+            ? outsidePrefix > 0
+                ? `${outsidePrefix}개 문서는 "${prefix}" 밖에 있어 제외했습니다. ` +
+                    'map의 unlinkedDocuments에 전체 목록이 있고, docs_read는 카탈로그에 ' +
+                    '있는 어떤 경로든 읽습니다.'
+                : null
+            : `"${prefix}" 로 시작하는 문서가 없어 카탈로그의 모든 문서를 반환했습니다. ` +
+                `MYSQL_APP_SCHEMAS의 앱 이름("${mapping.app}")이 저장소 디렉토리와 다를 수 있습니다.`;
+        const warning = this.staleWarning();
+        return JSON.stringify({
+            schema: schemaName,
+            app: mapping.app,
+            ref: catalog.docs.ref,
+            scopedToApp: scoped,
+            paths,
+            ...(notice ? { notice } : {}),
+            ...(warning ? { warning } : {}),
+        }, null, 2);
+    }
+    async read(documentPath) {
+        await this.ensureAwake();
+        const catalog = this.store.snapshot();
+        if (!catalog.docs.paths.includes(documentPath)) {
+            throw new Error(`Document "${documentPath}" is not present at ${catalog.docs.ref}. Use docs_list or map to choose a cataloged path.`);
+        }
+        const content = await this.git(['show', `${catalog.docs.ref}:${documentPath}`]);
+        const warning = this.staleWarning();
+        return warning ? `${warning}\n\n${content}` : content;
+    }
+    async link(links) {
+        await this.ensureAwake();
+        const snapshot = this.store.snapshot();
+        for (const link of links) {
+            if (!snapshot.docs.paths.includes(link.doc)) {
+                throw new Error(`Document "${link.doc}" is not present at ${snapshot.docs.ref}.`);
+            }
+            if (!snapshot.schemas[link.schema]?.tables[link.table]) {
+                throw new Error(`Unknown table "${link.schema}.${link.table}".`);
+            }
+        }
+        const now = new Date().toISOString();
+        this.store.update((catalog) => {
+            for (const link of links) {
+                catalog.schemas[link.schema].tables[link.table].curated.doc = {
+                    path: link.doc,
+                    linkedBy: 'model',
+                    linkedAt: now,
+                    linkedAtCommit: catalog.docs.refCommit,
+                };
+            }
+            refreshUnlinked(catalog);
+        });
+        return JSON.stringify({
+            linked: links.map((link) => ({
+                table: `${link.schema}.${link.table}`,
+                doc: link.doc,
+            })),
+            ...(this.staleWarning() ? { warning: this.staleWarning() } : {}),
+        }, null, 2);
+    }
+    unlink(schemaName, tableName) {
+        const snapshot = this.store.snapshot();
+        if (!snapshot.schemas[schemaName]?.tables[tableName]) {
+            throw new Error(`Unknown table "${schemaName}.${tableName}".`);
+        }
+        this.store.update((catalog) => {
+            catalog.schemas[schemaName].tables[tableName].curated.doc = null;
+            refreshUnlinked(catalog);
+        });
+        return JSON.stringify({
+            table: `${schemaName}.${tableName}`,
+            doc: null,
+            status: '문서 없음 또는 연결 해제를 확인했습니다.',
+            ...(this.staleWarning() ? { warning: this.staleWarning() } : {}),
+        }, null, 2);
+    }
+    staleWarning() {
+        const updatedAt = this.store.docsView().refUpdatedAt;
+        if (!updatedAt) {
+            return null;
+        }
+        const age = Date.now() - Date.parse(updatedAt);
+        if (!Number.isFinite(age) || age <= THIRTY_DAYS_MS) {
+            return null;
+        }
+        return (`[카탈로그 경고] ${this.options.ref}의 마지막 커밋이 30일 이상 지났습니다. ` +
+            '필요하면 사용자가 문서 저장소에서 git fetch를 실행해야 합니다.');
+    }
+    documentCommand(documentPath) {
+        if (!this.options.repo || !this.options.ref) {
+            return null;
+        }
+        return `git -C ${shellQuote(this.options.repo)} show ${shellQuote(`${this.options.ref}:${documentPath}`)}`;
+    }
+}