@ecubelabs/mysql-mcp 1.0.0-next.5 → 1.0.0-next.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,3 @@
1
- import { executeQuery } from '../db/index.js';
2
1
  import { emptyTable, normalizeName, SYSTEM_SCHEMAS } from './types.js';
3
2
  function chainAfter(pending, run) {
4
3
  if (!pending) {
@@ -50,7 +49,7 @@ export class CatalogCollector {
50
49
  }
51
50
  async runInventory() {
52
51
  const placeholders = SYSTEM_SCHEMAS.map(() => '?').join(', ');
53
- const rows = await executeQuery(`SELECT
52
+ const rows = await this.options.query(`SELECT
54
53
  s.schema_name AS \`table_schema\`,
55
54
  t.table_name AS \`table_name\`,
56
55
  t.table_comment AS \`table_comment\`,
@@ -123,7 +122,7 @@ export class CatalogCollector {
123
122
  return promise;
124
123
  }
125
124
  async runTableDetail(schemaName, tableName) {
126
- const rows = await executeQuery(`SELECT
125
+ const rows = await this.options.query(`SELECT
127
126
  'column' AS kind,
128
127
  c.column_name AS name,
129
128
  c.data_type AS \`data_type\`,
@@ -0,0 +1,187 @@
1
+ import * as fs from 'fs';
2
+ import * as path from 'path';
3
+ import { loadedCodeBranches } from './branch.js';
4
+ import { normalizeDocumentPath, normalizeGithubRepo } from './docs.js';
5
+ import { acquireCatalogLock, LOCK_WAIT_MS } from './lock.js';
6
+ import { loadedSchemaOwner } from './owner.js';
7
+ import { emptyInstanceContext, emptySchemaContext } from './types.js';
8
+ export const CONTEXT_VERSION = 1;
9
+ const EPOCH = new Date(0).toISOString();
10
+ function emptyFile() {
11
+ return { version: CONTEXT_VERSION, environments: {} };
12
+ }
13
+ function isObject(value) {
14
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
15
+ }
16
+ function strings(value) {
17
+ return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
18
+ }
19
+ function loadedDocumentDecision(curated) {
20
+ if (!Object.prototype.hasOwnProperty.call(curated, 'doc')) {
21
+ return {};
22
+ }
23
+ const doc = curated.doc;
24
+ if (!isObject(doc)) {
25
+ return { doc: null };
26
+ }
27
+ try {
28
+ return {
29
+ doc: {
30
+ path: normalizeDocumentPath(String(doc.path ?? '')),
31
+ repo: normalizeGithubRepo(doc.repo),
32
+ linkedBy: doc.linkedBy === 'user' ? 'user' : 'model',
33
+ linkedAt: typeof doc.linkedAt === 'string' ? doc.linkedAt : EPOCH,
34
+ },
35
+ };
36
+ }
37
+ catch {
38
+ return {};
39
+ }
40
+ }
41
+ function loadedInstance(raw) {
42
+ const instance = emptyInstanceContext();
43
+ if (!isObject(raw)) {
44
+ return instance;
45
+ }
46
+ instance.codeBranches = loadedCodeBranches(raw.codeBranches);
47
+ for (const [schemaName, schemaRaw] of Object.entries(isObject(raw.schemas) ? raw.schemas : {})) {
48
+ if (!isObject(schemaRaw)) {
49
+ continue;
50
+ }
51
+ const schema = emptySchemaContext();
52
+ if (isObject(schemaRaw.owner)) {
53
+ const owner = loadedSchemaOwner(schemaRaw.owner);
54
+ if ('repo' in owner && 'app' in owner) {
55
+ schema.owner = { repo: owner.repo, app: owner.app };
56
+ }
57
+ }
58
+ schema.notes = strings(schemaRaw.notes);
59
+ for (const [tableName, tableRaw] of Object.entries(isObject(schemaRaw.tables) ? schemaRaw.tables : {})) {
60
+ if (!isObject(tableRaw)) {
61
+ continue;
62
+ }
63
+ schema.tables[tableName] = {
64
+ notes: strings(tableRaw.notes),
65
+ aliases: strings(tableRaw.aliases),
66
+ ...loadedDocumentDecision(tableRaw),
67
+ };
68
+ }
69
+ instance.schemas[schemaName] = schema;
70
+ }
71
+ return instance;
72
+ }
73
+ function parseContextFile(text, filePath) {
74
+ const parsed = JSON.parse(text);
75
+ if (!isObject(parsed) || parsed.version !== CONTEXT_VERSION) {
76
+ const version = isObject(parsed) ? JSON.stringify(parsed.version) : 'none';
77
+ throw new Error(`${filePath} has version ${version}; this build reads version ${CONTEXT_VERSION}. ` +
78
+ 'Update @ecubelabs/mysql-mcp, or move the file away to start over.');
79
+ }
80
+ const file = emptyFile();
81
+ for (const [envName, envRaw] of Object.entries(isObject(parsed.environments) ? parsed.environments : {})) {
82
+ const instances = {};
83
+ const rawInstances = isObject(envRaw) && isObject(envRaw.instances) ? envRaw.instances : {};
84
+ for (const [instanceName, instanceRaw] of Object.entries(rawInstances)) {
85
+ instances[instanceName] = loadedInstance(instanceRaw);
86
+ }
87
+ file.environments[envName] = { instances };
88
+ }
89
+ return file;
90
+ }
91
+ export class ContextStore {
92
+ filePath;
93
+ data = emptyFile();
94
+ stamp = null;
95
+ warned = false;
96
+ constructor(filePath) {
97
+ this.filePath = filePath;
98
+ }
99
+ read(envName, instanceName) {
100
+ this.reloadIfChanged();
101
+ return this.data.environments[envName]?.instances[instanceName] ?? emptyInstanceContext();
102
+ }
103
+ async update(envName, instanceName, mutator) {
104
+ if (this.filePath === null) {
105
+ const result = mutator(this.ensureInstance(this.data, envName, instanceName));
106
+ return result;
107
+ }
108
+ const filePath = this.filePath;
109
+ await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
110
+ const release = await acquireCatalogLock(filePath, LOCK_WAIT_MS);
111
+ try {
112
+ const latest = this.readForWrite(filePath);
113
+ const result = mutator(this.ensureInstance(latest, envName, instanceName));
114
+ const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
115
+ await fs.promises.writeFile(tempPath, `${JSON.stringify(latest, null, 2)}\n`, {
116
+ encoding: 'utf8',
117
+ mode: 0o600,
118
+ flag: 'wx',
119
+ });
120
+ await fs.promises.rename(tempPath, filePath);
121
+ await fs.promises.chmod(filePath, 0o600);
122
+ this.data = latest;
123
+ this.stamp = this.statFile(filePath);
124
+ return result;
125
+ }
126
+ finally {
127
+ await release();
128
+ }
129
+ }
130
+ ensureInstance(file, envName, instanceName) {
131
+ const env = (file.environments[envName] ??= { instances: {} });
132
+ return (env.instances[instanceName] ??= emptyInstanceContext());
133
+ }
134
+ statFile(filePath) {
135
+ try {
136
+ const stat = fs.statSync(filePath);
137
+ return { mtimeMs: stat.mtimeMs, size: stat.size };
138
+ }
139
+ catch {
140
+ return null;
141
+ }
142
+ }
143
+ readForWrite(filePath) {
144
+ let text;
145
+ try {
146
+ text = fs.readFileSync(filePath, 'utf8');
147
+ }
148
+ catch (error) {
149
+ if (error.code === 'ENOENT') {
150
+ return emptyFile();
151
+ }
152
+ throw error;
153
+ }
154
+ try {
155
+ return parseContextFile(text, filePath);
156
+ }
157
+ catch (error) {
158
+ throw new Error(`could not update ${filePath}: ${error instanceof Error ? error.message : String(error)}. ` +
159
+ 'Nothing was recorded.', { cause: error });
160
+ }
161
+ }
162
+ reloadIfChanged() {
163
+ if (this.filePath === null) {
164
+ return;
165
+ }
166
+ const stamp = this.statFile(this.filePath);
167
+ if (stamp?.mtimeMs === this.stamp?.mtimeMs && stamp?.size === this.stamp?.size) {
168
+ return;
169
+ }
170
+ this.stamp = stamp;
171
+ if (!stamp) {
172
+ this.data = emptyFile();
173
+ return;
174
+ }
175
+ try {
176
+ this.data = parseContextFile(fs.readFileSync(this.filePath, 'utf8'), this.filePath);
177
+ this.warned = false;
178
+ }
179
+ catch (error) {
180
+ this.data = emptyFile();
181
+ if (!this.warned) {
182
+ this.warned = true;
183
+ console.error(`[context] ignoring ${this.filePath} until it is fixed: ${error instanceof Error ? error.message : String(error)}`);
184
+ }
185
+ }
186
+ }
187
+ }
@@ -1,4 +1,5 @@
1
1
  import * as path from 'path';
2
+ import { tableContext } from './types.js';
2
3
  const GITHUB_REPO_FORMS = [
3
4
  /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i,
4
5
  /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i,
@@ -42,7 +43,7 @@ export class CatalogDocuments {
42
43
  constructor(store) {
43
44
  this.store = store;
44
45
  }
45
- link(links, guidanceFor = () => []) {
46
+ async link(links, guidanceFor = () => []) {
46
47
  const resolved = links.map((link) => ({
47
48
  ...link,
48
49
  doc: normalizeDocumentPath(link.doc),
@@ -55,17 +56,14 @@ export class CatalogDocuments {
55
56
  }
56
57
  }
57
58
  const now = new Date().toISOString();
58
- this.store.update((catalog) => {
59
+ await this.store.updateContext((context) => {
59
60
  for (const link of resolved) {
60
- const table = catalog.schemas[link.schema]?.tables[link.table];
61
- if (table) {
62
- table.curated.doc = {
63
- path: link.doc,
64
- repo: link.repo,
65
- linkedBy: 'model',
66
- linkedAt: now,
67
- };
68
- }
61
+ tableContext(context, link.schema, link.table).doc = {
62
+ path: link.doc,
63
+ repo: link.repo,
64
+ linkedBy: 'model',
65
+ linkedAt: now,
66
+ };
69
67
  }
70
68
  });
71
69
  const guidance = guidanceFor(resolved);
@@ -78,13 +76,13 @@ export class CatalogDocuments {
78
76
  ...(guidance.length > 0 ? { guidance } : {}),
79
77
  }, null, 2);
80
78
  }
81
- unlink(schemaName, tableName) {
79
+ async unlink(schemaName, tableName) {
82
80
  const snapshot = this.store.snapshot();
83
81
  if (!snapshot.schemas[schemaName]?.tables[tableName]) {
84
82
  throw new Error(`Unknown table "${schemaName}.${tableName}".`);
85
83
  }
86
- this.store.update((catalog) => {
87
- catalog.schemas[schemaName].tables[tableName].curated.doc = null;
84
+ await this.store.updateContext((context) => {
85
+ tableContext(context, schemaName, tableName).doc = null;
88
86
  });
89
87
  return JSON.stringify({
90
88
  table: `${schemaName}.${tableName}`,
@@ -1,5 +1,4 @@
1
1
  import { createHash } from 'crypto';
2
- import * as os from 'os';
3
2
  import * as path from 'path';
4
3
  import { CatalogCollector } from './collect.js';
5
4
  import { CatalogDocuments, normalizeGithubRepo } from './docs.js';
@@ -7,7 +6,7 @@ import { formatCodeBranches, normalizeBranchName } from './branch.js';
7
6
  import { normalizeSchemaOwner } from './owner.js';
8
7
  import { missingBranchNotice, missingOwnerNotice, renderDescribe, renderMap, renderToolDescriptionSuffix, searchCatalog, } from './render.js';
9
8
  import { CatalogStore } from './store.js';
10
- import { emptyUsage, normalizeName, pruneJoins, SYSTEM_SCHEMAS } from './types.js';
9
+ import { emptyUsage, normalizeName, pruneJoins, schemaContext, SYSTEM_SCHEMAS, tableContext } from './types.js';
11
10
  import { prepareCatalogQuery, resultColumnNames } from './usage.js';
12
11
  const UNKNOWN_REFERENCE_REFRESH_COOLDOWN_MS = 60_000;
13
12
  const UNKNOWN_REFERENCE_MEMORY_LIMIT = 256;
@@ -30,12 +29,14 @@ export function catalogIdentity(identity) {
30
29
  const profile = identity.profile || 'default';
31
30
  const safeProfile = profile.replace(/[^A-Za-z0-9_.-]/g, '_');
32
31
  const endpointHash = shortHash(`${identity.target}\u0000${identity.user}`);
33
- const directory = identity.customPath ?? path.join(os.homedir(), '.cache', 'mysql-mcp', 'catalog');
34
32
  return {
35
- filePath: path.join(directory, `${safeProfile}-${endpointHash}.json`),
33
+ filePath: path.join(identity.directory, `${safeProfile}-${endpointHash}.json`),
36
34
  fingerprint: endpointHash,
37
35
  };
38
36
  }
37
+ function isSchemaTarget(input) {
38
+ return !input.replace(/`/g, '').includes('.');
39
+ }
39
40
  function sameName(a, b) {
40
41
  return normalizeName(a) === normalizeName(b);
41
42
  }
@@ -55,9 +56,10 @@ export class SchemaCatalog {
55
56
  toolDescriptionAnnounced = false;
56
57
  constructor(options) {
57
58
  this.options = options;
58
- this.store = new CatalogStore(options);
59
+ this.store = new CatalogStore(options, options.context);
59
60
  this.collector = new CatalogCollector(this.store, {
60
61
  ttlHours: options.ttlHours,
62
+ query: options.query,
61
63
  });
62
64
  this.documents = new CatalogDocuments(this.store);
63
65
  }
@@ -70,7 +72,7 @@ export class SchemaCatalog {
70
72
  codeBranchSummary() {
71
73
  return this.isEnabled() ? formatCodeBranches(this.store.codeBranches()) || null : null;
72
74
  }
73
- setCodeBranch(repoInput, branchInput) {
75
+ async setCodeBranch(repoInput, branchInput) {
74
76
  if (!this.isEnabled()) {
75
77
  throw new Error('The schema catalog is disabled.');
76
78
  }
@@ -80,12 +82,9 @@ export class SchemaCatalog {
80
82
  if (previous === branch) {
81
83
  return JSON.stringify({ repo, branch, changed: false, status: `${repo}에는 이미 ${branch} 브랜치가 기록돼 있습니다.` }, null, 2);
82
84
  }
83
- this.store.update((catalog) => {
84
- catalog.codeBranches[repo] = branch;
85
+ await this.store.updateContext((context) => {
86
+ context.codeBranches[repo] = branch;
85
87
  });
86
- if (this.store.codeBranches()[repo] !== branch) {
87
- throw new Error('The catalog cache is disabled, so the branch was not recorded.');
88
- }
89
88
  return JSON.stringify({
90
89
  repo,
91
90
  branch,
@@ -94,7 +93,7 @@ export class SchemaCatalog {
94
93
  status: previous
95
94
  ? `${repo}의 브랜치를 바꿨습니다: ${previous} → ${branch}`
96
95
  : `${repo}에 ${branch} 브랜치를 기록했습니다. 다음 세션에도 이어 씁니다.`,
97
- note: 'banner와 describe는 바로 이 값을 씁니다. mysql_query 툴 설명의 CODE REVISION은 서버를 다시 띄우면 바뀝니다.',
96
+ note: 'banner와 describe는 바로 이 값을 씁니다. mysql_query 툴 설명의 CODE REVISION은 다음 도구 목록 요청부터 바뀝니다.',
98
97
  }, null, 2);
99
98
  }
100
99
  schemaOwners() {
@@ -120,22 +119,9 @@ export class SchemaCatalog {
120
119
  if (previous && previous.repo === owner.repo && previous.app === owner.app) {
121
120
  return JSON.stringify({ schema: name, ...owner, changed: false, status: `${name} schema의 owner는 이미 ${label}입니다.` }, null, 2);
122
121
  }
123
- let missing = false;
124
- this.store.update((catalog) => {
125
- const entry = catalog.schemas[name];
126
- if (!entry) {
127
- missing = true;
128
- return;
129
- }
130
- entry.repo = owner.repo;
131
- entry.app = owner.app;
122
+ await this.store.updateContext((context) => {
123
+ schemaContext(context, name).owner = owner;
132
124
  });
133
- if (missing) {
134
- throw new Error(`${name} is no longer in the catalog. Run mysql_catalog {action:"map"} to see what remains.`);
135
- }
136
- if (!this.isEnabled()) {
137
- throw new Error('The catalog cache is disabled, so the owner was not recorded.');
138
- }
139
125
  return JSON.stringify({
140
126
  schema: name,
141
127
  ...owner,
@@ -148,11 +134,17 @@ export class SchemaCatalog {
148
134
  }
149
135
  startInventory() {
150
136
  if (!this.isEnabled() || this.closing) {
151
- return;
137
+ return Promise.resolve();
152
138
  }
153
- this.trackBackgroundTask(this.collector.collectInventory(false).catch((error) => {
154
- console.error(`[catalog] inventory scan failed: ${error instanceof Error ? error.message : String(error)}`);
155
- }));
139
+ const task = this.collector.collectInventory(false).catch((error) => {
140
+ const where = this.options.connection ? ` for connection ${this.options.connection}` : '';
141
+ console.error(`[catalog] inventory scan failed${where}: ${error instanceof Error ? error.message : String(error)}`);
142
+ });
143
+ this.trackBackgroundTask(task);
144
+ return task;
145
+ }
146
+ schemaNames() {
147
+ return this.isEnabled() ? this.store.schemaNames() : [];
156
148
  }
157
149
  toolDescriptionSuffix(budget) {
158
150
  if (!this.isEnabled()) {
@@ -160,6 +152,9 @@ export class SchemaCatalog {
160
152
  }
161
153
  return renderToolDescriptionSuffix(this.store.snapshot(), budget);
162
154
  }
155
+ descriptionSnapshot() {
156
+ return this.isEnabled() ? this.store.snapshot() : null;
157
+ }
163
158
  onToolDescriptionFilled(listener) {
164
159
  this.toolDescriptionListener = listener;
165
160
  }
@@ -246,7 +241,7 @@ export class SchemaCatalog {
246
241
  if (!entry) {
247
242
  throw new Error(`Table disappeared during refresh: ${input}`);
248
243
  }
249
- return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.codeBranches(), this.store.readJoins(resolved.schema, resolved.table), this.options.profile, this.store.schemaOwners()[resolved.schema] ?? null);
244
+ return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.codeBranches(), this.store.readJoins(resolved.schema, resolved.table), this.options.profile, this.store.schemaOwners()[resolved.schema] ?? null, this.store.schemaNotes(resolved.schema));
250
245
  }
251
246
  async refresh(target) {
252
247
  if (!this.isEnabled()) {
@@ -357,46 +352,42 @@ export class SchemaCatalog {
357
352
  if (hasText === hasAlias) {
358
353
  throw new Error('mysql_catalog note requires exactly one of "text" or "alias".');
359
354
  }
360
- const resolved = await this.ensureKnownTable(input);
361
355
  const kind = hasText ? 'note' : 'alias';
362
356
  const content = (hasText ? value.text : value.alias)?.trim();
363
357
  const limit = hasText ? NOTE_MAX_LENGTH : ALIAS_MAX_LENGTH;
364
358
  if (content.length > limit) {
365
359
  throw new Error(`${kind} exceeds the ${limit}-character limit.`);
366
360
  }
367
- const qualified = `${resolved.schema}.${resolved.table}`;
368
- let full = false;
369
- let missing = false;
370
- this.store.update((catalog) => {
371
- const curated = catalog.schemas[resolved.schema]?.tables[resolved.table]?.curated;
372
- if (!curated) {
373
- missing = true;
374
- return;
361
+ if (isSchemaTarget(input)) {
362
+ if (!hasText) {
363
+ throw new Error('An alias names a table. Pass target as schema.table, or use text for a schema note.');
375
364
  }
365
+ return this.noteSchema(await this.ensureKnownSchema(input), content);
366
+ }
367
+ const resolved = await this.ensureKnownTable(input);
368
+ const qualified = `${resolved.schema}.${resolved.table}`;
369
+ const full = await this.store.updateContext((context) => {
370
+ const curated = tableContext(context, resolved.schema, resolved.table);
376
371
  if (hasText) {
377
372
  if (curated.notes.includes(content)) {
378
- return;
373
+ return false;
379
374
  }
380
375
  if (curated.notes.length >= NOTE_COUNT_LIMIT) {
381
- full = true;
382
- return;
376
+ return true;
383
377
  }
384
378
  curated.notes.push(content);
385
379
  }
386
380
  else {
387
381
  if (curated.aliases.some((alias) => normalizeName(alias) === normalizeName(content))) {
388
- return;
382
+ return false;
389
383
  }
390
384
  if (curated.aliases.length >= ALIAS_COUNT_LIMIT) {
391
- full = true;
392
- return;
385
+ return true;
393
386
  }
394
387
  curated.aliases.push(content);
395
388
  }
389
+ return false;
396
390
  });
397
- if (missing) {
398
- throw new Error(tableVanished(qualified));
399
- }
400
391
  if (full) {
401
392
  throw new Error(`${qualified} already holds the maximum of ${hasText ? NOTE_COUNT_LIMIT : ALIAS_COUNT_LIMIT} ${kind}s. Clear them with mysql_catalog {action:"forget", target:"${qualified}", scope:"${kind}s"} first.`);
402
393
  }
@@ -408,11 +399,68 @@ export class SchemaCatalog {
408
399
  aliases: table?.curated.aliases ?? [],
409
400
  }, null, 2);
410
401
  }
402
+ async noteSchema(schema, content) {
403
+ const full = await this.store.updateContext((context) => {
404
+ const notes = schemaContext(context, schema).notes;
405
+ if (notes.includes(content)) {
406
+ return false;
407
+ }
408
+ if (notes.length >= NOTE_COUNT_LIMIT) {
409
+ return true;
410
+ }
411
+ notes.push(content);
412
+ return false;
413
+ });
414
+ if (full) {
415
+ throw new Error(`${schema} already holds the maximum of ${NOTE_COUNT_LIMIT} notes. ` +
416
+ `Clear them with mysql_catalog {action:"forget", target:"${schema}", scope:"notes"} first.`);
417
+ }
418
+ return JSON.stringify({ target: schema, added: { note: content }, notes: this.store.schemaNotes(schema) }, null, 2);
419
+ }
420
+ async ensureKnownSchema(input) {
421
+ const requested = input.replace(/`/g, '').trim();
422
+ let schema = this.store.schemaName(requested);
423
+ if (!schema) {
424
+ await this.collector.collectInventory(false);
425
+ schema = this.store.schemaName(requested);
426
+ }
427
+ if (!schema) {
428
+ throw new Error(`Unknown schema "${requested}". Run mysql_catalog {action:"map"} to see the schemas.`);
429
+ }
430
+ return schema;
431
+ }
411
432
  async forget(input, scope) {
412
433
  if (!this.isEnabled()) {
413
434
  throw new Error('The schema catalog is disabled.');
414
435
  }
436
+ if (isSchemaTarget(input)) {
437
+ if (scope !== 'notes') {
438
+ throw new Error(`A schema holds only notes. Pass target as schema.table to forget ${scope}.`);
439
+ }
440
+ const schema = await this.ensureKnownSchema(input);
441
+ const removed = await this.store.updateContext((context) => {
442
+ const notes = context.schemas[schema]?.notes ?? [];
443
+ const count = notes.length;
444
+ if (context.schemas[schema]) {
445
+ context.schemas[schema].notes = [];
446
+ }
447
+ return count;
448
+ });
449
+ return JSON.stringify({ target: schema, scope, removed }, null, 2);
450
+ }
415
451
  const resolved = await this.ensureKnownTable(input);
452
+ if (scope === 'notes' || scope === 'aliases') {
453
+ const qualified = `${resolved.schema}.${resolved.table}`;
454
+ const removed = await this.store.updateContext((context) => {
455
+ const curated = context.schemas[resolved.schema]?.tables[resolved.table];
456
+ const count = curated?.[scope].length ?? 0;
457
+ if (curated) {
458
+ curated[scope] = [];
459
+ }
460
+ return count;
461
+ });
462
+ return JSON.stringify({ target: qualified, scope, removed }, null, 2);
463
+ }
416
464
  const qualified = `${resolved.schema}.${resolved.table}`;
417
465
  let removed = 0;
418
466
  let missing = false;
@@ -422,15 +470,7 @@ export class SchemaCatalog {
422
470
  missing = true;
423
471
  return;
424
472
  }
425
- if (scope === 'notes') {
426
- removed = table.curated.notes.length;
427
- table.curated.notes = [];
428
- }
429
- else if (scope === 'aliases') {
430
- removed = table.curated.aliases.length;
431
- table.curated.aliases = [];
432
- }
433
- else if (scope === 'usage') {
473
+ if (scope === 'usage') {
434
474
  removed = table.usage.count;
435
475
  table.usage = emptyUsage();
436
476
  }
@@ -0,0 +1,113 @@
1
+ import * as fs from 'fs';
2
+ const LOCK_RETRY_MS = 25;
3
+ export const LOCK_WAIT_MS = 15_000;
4
+ export const LOCK_CLOSE_WAIT_MS = 2_000;
5
+ const LOCK_STALE_MS = 30_000;
6
+ export class CatalogLockTimeoutError extends Error {
7
+ }
8
+ function errorCode(error) {
9
+ return error && typeof error === 'object' && 'code' in error ? String(error.code) : null;
10
+ }
11
+ function processIsAlive(pid) {
12
+ try {
13
+ process.kill(pid, 0);
14
+ return true;
15
+ }
16
+ catch (error) {
17
+ return errorCode(error) !== 'ESRCH';
18
+ }
19
+ }
20
+ function delay(ms) {
21
+ return new Promise((resolve) => setTimeout(resolve, ms));
22
+ }
23
+ export async function acquireCatalogLock(filePath, waitMs) {
24
+ const lockPath = `${filePath}.lock`;
25
+ const deadline = Date.now() + waitMs;
26
+ const record = {
27
+ pid: process.pid,
28
+ token: `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
29
+ createdAt: Date.now(),
30
+ };
31
+ while (true) {
32
+ try {
33
+ const handle = await fs.promises.open(lockPath, 'wx', 0o600);
34
+ try {
35
+ await handle.writeFile(JSON.stringify(record), 'utf8');
36
+ await handle.sync();
37
+ }
38
+ catch (error) {
39
+ await handle.close().catch(() => undefined);
40
+ await fs.promises.unlink(lockPath).catch(() => undefined);
41
+ throw error;
42
+ }
43
+ let released = false;
44
+ return async () => {
45
+ if (released) {
46
+ return;
47
+ }
48
+ released = true;
49
+ await handle.close();
50
+ try {
51
+ const current = JSON.parse(await fs.promises.readFile(lockPath, 'utf8'));
52
+ if (current.token === record.token) {
53
+ await fs.promises.unlink(lockPath);
54
+ }
55
+ }
56
+ catch (error) {
57
+ if (errorCode(error) !== 'ENOENT') {
58
+ throw error;
59
+ }
60
+ }
61
+ };
62
+ }
63
+ catch (error) {
64
+ if (errorCode(error) !== 'EEXIST') {
65
+ throw error;
66
+ }
67
+ let lockText = null;
68
+ let stale = false;
69
+ try {
70
+ const [text, stat] = await Promise.all([
71
+ fs.promises.readFile(lockPath, 'utf8'),
72
+ fs.promises.stat(lockPath),
73
+ ]);
74
+ lockText = text;
75
+ let owner = {};
76
+ try {
77
+ owner = JSON.parse(text);
78
+ }
79
+ catch {
80
+ }
81
+ stale =
82
+ typeof owner.pid === 'number'
83
+ ? !processIsAlive(owner.pid)
84
+ : Date.now() - stat.mtimeMs >= LOCK_STALE_MS;
85
+ }
86
+ catch (readError) {
87
+ if (errorCode(readError) === 'ENOENT') {
88
+ continue;
89
+ }
90
+ throw readError;
91
+ }
92
+ if (stale && lockText !== null) {
93
+ try {
94
+ if ((await fs.promises.readFile(lockPath, 'utf8')) === lockText) {
95
+ await fs.promises.unlink(lockPath);
96
+ console.error(`[catalog] removed stale lock ${lockPath}`);
97
+ continue;
98
+ }
99
+ }
100
+ catch (cleanupError) {
101
+ if (errorCode(cleanupError) === 'ENOENT') {
102
+ continue;
103
+ }
104
+ throw cleanupError;
105
+ }
106
+ }
107
+ if (Date.now() >= deadline) {
108
+ throw new CatalogLockTimeoutError(`timed out after ${waitMs}ms waiting for catalog lock ${lockPath}`);
109
+ }
110
+ await delay(LOCK_RETRY_MS + Math.floor(Math.random() * LOCK_RETRY_MS));
111
+ }
112
+ }
113
+ }