@ecubelabs/mysql-mcp 1.0.0-next.3 → 1.0.0-next.4
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.
- package/README.md +49 -25
- package/dist/index.js +24 -21
- package/dist/src/catalog/branch.js +35 -14
- package/dist/src/catalog/docs.js +6 -3
- package/dist/src/catalog/index.js +22 -17
- package/dist/src/catalog/render.js +16 -11
- package/dist/src/catalog/store.js +15 -5
- package/dist/src/catalog/types.js +1 -1
- package/dist/src/db/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,7 +17,8 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
|
|
|
17
17
|
무관하게 모든 쓰기를 거부합니다.
|
|
18
18
|
- **Map은 탐색이 아니라 선언.** 각 profile이 어떤 schema가 어떤 application의
|
|
19
19
|
것인지 명시하므로, 모델은 이를 뒤져서 알아내는 대신 툴 설명에서 읽습니다.
|
|
20
|
-
데이터가 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에
|
|
20
|
+
데이터가 저장소마다 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에
|
|
21
|
+
기록합니다.
|
|
21
22
|
- **로컬 schema catalog.** 선언된 schema의 table 목록을 저장해 두고 TTL이 지나면
|
|
22
23
|
다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
|
|
23
24
|
수집합니다.
|
|
@@ -137,9 +138,9 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
|
|
|
137
138
|
|
|
138
139
|
- 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
|
|
139
140
|
기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
|
|
140
|
-
-
|
|
141
|
-
`develop`, prod profile이면 `main`이 맞는지 확인합니다.
|
|
142
|
-
다음 세션에도 씁니다.
|
|
141
|
+
- Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
|
|
142
|
+
합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
|
|
143
|
+
답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
|
|
143
144
|
- 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
|
|
144
145
|
- `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
|
|
145
146
|
- `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
|
|
@@ -156,7 +157,7 @@ stage db에 Active Account가 몇 개 있는지 알려줘
|
|
|
156
157
|
```
|
|
157
158
|
|
|
158
159
|
```text
|
|
159
|
-
[profile: STAGE | read-only | database: multi-db | code: develop
|
|
160
|
+
[profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
|
|
160
161
|
[
|
|
161
162
|
{
|
|
162
163
|
"c": 4004
|
|
@@ -228,18 +229,34 @@ A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT
|
|
|
228
229
|
실패합니다. stage column을 `main` 기준으로 읽으면 branch가 잘못된 것이 아니라
|
|
229
230
|
migration이 빠진 것처럼 보이기 때문입니다.
|
|
230
231
|
|
|
231
|
-
- Branch는
|
|
232
|
-
|
|
233
|
-
-
|
|
234
|
-
`
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
232
|
+
- Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
|
|
233
|
+
쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
|
|
234
|
+
- 사용자가 확인한 값을
|
|
235
|
+
`mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
|
|
236
|
+
catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
|
|
237
|
+
있는지도 알아내지 않습니다.
|
|
238
|
+
- 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
|
|
239
|
+
- `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
|
|
240
|
+
`Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
|
|
241
|
+
셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
|
|
242
|
+
- `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
|
|
243
|
+
- `describe`의 문서 읽기 명령
|
|
244
|
+
- `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
|
|
245
|
+
`branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
|
|
246
|
+
다시 만듭니다.
|
|
238
247
|
- Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false` 또는 `MYSQL_APP_SCHEMAS` 없음)은
|
|
239
248
|
branch를 기록할 곳이 없어 표시하지 않습니다.
|
|
240
|
-
-
|
|
241
|
-
|
|
242
|
-
|
|
249
|
+
- 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
|
|
250
|
+
버립니다. 필요한 곳에서 다시 묻습니다.
|
|
251
|
+
- Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
|
|
252
|
+
않습니다.
|
|
253
|
+
- `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
|
|
254
|
+
- `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
|
|
255
|
+
물으라고 안내합니다.
|
|
256
|
+
- `mysql_catalog` 툴 설명: 세션의 저장소에 branch가 없고 문서를 연결하거나 코드와
|
|
257
|
+
데이터를 대조할 때 먼저 물으라고 지시합니다. 세션이 어느 저장소인지는 모델이
|
|
258
|
+
판단합니다.
|
|
259
|
+
- Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
|
|
243
260
|
|
|
244
261
|
| Profile | 제안하는 branch |
|
|
245
262
|
| --------------------------------------- | --------------- |
|
|
@@ -286,11 +303,18 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
286
303
|
`https://github.com/owner/name(.git)`, `git@github.com:owner/name(.git)`을 받아
|
|
287
304
|
`owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
|
|
288
305
|
`git remote get-url origin`으로 얻습니다.
|
|
289
|
-
- `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
306
|
+
- `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다. 툴 설명과
|
|
307
|
+
query 뒤 안내는 문서 저장소 안의 세션에서 찾아봤을 때만 기록하라고 지시합니다. 저장소
|
|
308
|
+
밖의 세션이 못 찾았다고 남긴 "문서 없음"은 이후 모든 세션이 그 table의 문서를 찾지
|
|
309
|
+
않게 만듭니다. 서버는 세션의 저장소를 모르므로 이 조건은 모델이 판단합니다.
|
|
310
|
+
- `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다. `repo`와 `branch`가
|
|
311
|
+
모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 저장소와 함께 무엇을
|
|
312
|
+
기록했는지 또는 `이전 → 새` 값을 알립니다.
|
|
313
|
+
- `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
|
|
314
|
+
- `branch`: `origin/` 접두어는 떼고 저장합니다. git으로 확인하지 않는 대신
|
|
315
|
+
`git check-ref-format --branch`에 준하는 형식만 받습니다.
|
|
316
|
+
공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
|
|
317
|
+
- 둘 중 하나라도 틀리면 아무것도 기록하지 않습니다.
|
|
294
318
|
|
|
295
319
|
**기록 관리**
|
|
296
320
|
|
|
@@ -314,11 +338,11 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
314
338
|
문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
|
|
315
339
|
- 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
|
|
316
340
|
"문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
|
|
317
|
-
- `describe`의 `docs`는 `path`, `repo`, `branch`(기록된 branch),
|
|
318
|
-
`remoteCommand`, `guidance`입니다.
|
|
341
|
+
- `describe`의 `docs`는 `path`, `repo`, `branch`(그 저장소에 기록된 branch),
|
|
342
|
+
`command`, `remoteCommand`, `guidance`입니다.
|
|
319
343
|
- 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
|
|
320
|
-
DB와 다를 수 있어서입니다. branch가 기록되지 않았으면
|
|
321
|
-
안내가 붙습니다.
|
|
344
|
+
DB와 다를 수 있어서입니다. 그 저장소에 branch가 기록되지 않았으면 두 명령은
|
|
345
|
+
`null`이고, 문서를 읽어야 할 때만 물어 기록하라는 안내가 붙습니다.
|
|
322
346
|
- `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
|
|
323
347
|
- 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
|
|
324
348
|
`link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
|
|
@@ -387,7 +411,7 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
|
|
|
387
411
|
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
388
412
|
| `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 선언된 schema의 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
|
|
389
413
|
| `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
|
|
390
|
-
| `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 `
|
|
414
|
+
| `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
|
|
391
415
|
|
|
392
416
|
## 환경 변수
|
|
393
417
|
|
package/dist/index.js
CHANGED
|
@@ -7,7 +7,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
|
|
|
7
7
|
import { log, sharedOnce, tableResourceUri } from './src/utils/index.js';
|
|
8
8
|
import { writeCapabilities } from './src/db/permissions.js';
|
|
9
9
|
import { SCHEMA_DELETE_PERMISSIONS, SCHEMA_DDL_PERMISSIONS, SCHEMA_INSERT_PERMISSIONS, SCHEMA_UPDATE_PERMISSIONS, isMultiDbMode, mcpConfig as config, MYSQL_PROFILE, PROFILE_LABEL, IS_WRITE_FORBIDDEN_PROFILE, APP_SCHEMAS, MYSQL_CATALOG_ENABLED, MYSQL_CATALOG_PATH, MYSQL_CATALOG_TTL_HOURS, MYSQL_DEFAULT_TIMEOUT_SECONDS, MYSQL_MAX_TIMEOUT_SECONDS, MAX_RESPONSE_ROWS, MYSQL_SSL_ENABLED, MYSQL_SSL_CA_PATH, MYSQL_SSL_CERT_PATH, MYSQL_SSL_KEY_PATH, PACKAGE_VERSION, SSH_ENABLED, } from './src/config/index.js';
|
|
10
|
-
import {
|
|
10
|
+
import { codeBranchToolInstruction, codeRevisionDescription } from './src/catalog/branch.js';
|
|
11
11
|
import { catalogIdentity, SchemaCatalog } from './src/catalog/index.js';
|
|
12
12
|
import { describeConnection, getPool, executeQuery, executeReadOnlyQuery, setQueryDiagnosticsSource, setCodeBranchSource, clampTimeoutSeconds, describeQueryError, poolPromise, profileBanner, } from './src/db/index.js';
|
|
13
13
|
import { describeTunnel, ensureTunnel, resolveTunnelConfig, stopTunnel } from './src/ssh/tunnel.js';
|
|
@@ -43,12 +43,6 @@ baseToolDescription +=
|
|
|
43
43
|
`${MAX_RESPONSE_ROWS.toLocaleString('en-US')} rows. Aggregate in SQL rather than pulling rows to count them. ` +
|
|
44
44
|
`USE and SET are rejected; write schema.table instead of USE. ` +
|
|
45
45
|
`Executable comments (/*! ... */) and MAX_EXECUTION_TIME or SET_VAR hints are rejected; use timeout_seconds instead.`;
|
|
46
|
-
function codeRevisionDescription(branch) {
|
|
47
|
-
return branch
|
|
48
|
-
? `\n\nCODE REVISION: this database matches the \`${branch}\` branch. ` +
|
|
49
|
-
`Read entities, migrations, and queries from that branch when correlating code with data.`
|
|
50
|
-
: '';
|
|
51
|
-
}
|
|
52
46
|
let appSchemaDescription = '';
|
|
53
47
|
if (APP_SCHEMAS.length > 0) {
|
|
54
48
|
appSchemaDescription +=
|
|
@@ -75,9 +69,10 @@ const mysqlCatalogTool = {
|
|
|
75
69
|
'Use map for the app/schema overview, search to find tables or known columns, ' +
|
|
76
70
|
'and describe before writing SQL. ' +
|
|
77
71
|
'Use link to record the repository-relative path of the domain document (model.md) ' +
|
|
78
|
-
'you found for a table, or unlink to record that none exists
|
|
79
|
-
'
|
|
80
|
-
'
|
|
72
|
+
'you found for a table, or unlink to record that none exists, only after searching for it ' +
|
|
73
|
+
'in a session inside the document repository; never unlink from a session outside it. ' +
|
|
74
|
+
'Use branch to record which branch of a GitHub repository matches this database, once ' +
|
|
75
|
+
'the user confirmed it. ' +
|
|
81
76
|
'Use note to save a table memo or alias, and forget to clear one catalog scope. ' +
|
|
82
77
|
'Use refresh when cached metadata contradicts what a query actually returned, ' +
|
|
83
78
|
'or right after a migration: added columns and indexes raise no error, so ' +
|
|
@@ -105,12 +100,17 @@ const mysqlCatalogTool = {
|
|
|
105
100
|
description: 'Qualified schema.table name for describe, or for unlink. note and ' +
|
|
106
101
|
'forget take the same name as target instead.',
|
|
107
102
|
},
|
|
103
|
+
repo: {
|
|
104
|
+
type: 'string',
|
|
105
|
+
description: 'GitHub repository for branch, as owner/name. Take it from `git remote get-url origin`; ' +
|
|
106
|
+
'https and git@ URLs are accepted.',
|
|
107
|
+
},
|
|
108
108
|
branch: {
|
|
109
109
|
type: 'string',
|
|
110
110
|
maxLength: 100,
|
|
111
|
-
description: 'Branch name for branch, e.g. develop: the branch whose code matches this ' +
|
|
112
|
-
"database's data. Pass it only after the user confirmed it; it replaces the " +
|
|
113
|
-
'recorded
|
|
111
|
+
description: 'Branch name for branch, e.g. develop: the branch of repo whose code matches this ' +
|
|
112
|
+
"database's data. Pass it only after the user confirmed it; it replaces the branch " +
|
|
113
|
+
'recorded for that repo.',
|
|
114
114
|
},
|
|
115
115
|
target: {
|
|
116
116
|
type: 'string',
|
|
@@ -240,8 +240,8 @@ export default function createMcpServer() {
|
|
|
240
240
|
setQueryDiagnosticsSource({
|
|
241
241
|
indexFacts: (reference) => catalog.indexFacts(reference),
|
|
242
242
|
});
|
|
243
|
-
setCodeBranchSource(() => catalog.
|
|
244
|
-
const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.
|
|
243
|
+
setCodeBranchSource(() => catalog.codeBranchSummary());
|
|
244
|
+
const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.codeBranches()) + appSchemaDescription;
|
|
245
245
|
if (queryBaseDescription.length > TOOL_DESCRIPTION_LIMIT) {
|
|
246
246
|
console.error(`[warn] tool description is ${queryBaseDescription.length} characters before the ` +
|
|
247
247
|
`catalog tail; clients keep ${TOOL_DESCRIPTION_LIMIT} and silently drop the rest. ` +
|
|
@@ -327,7 +327,7 @@ export default function createMcpServer() {
|
|
|
327
327
|
try {
|
|
328
328
|
log('info', 'Handling ReadResourceRequest:', request.params.uri);
|
|
329
329
|
if (request.params.uri === 'mysql://schemas') {
|
|
330
|
-
const
|
|
330
|
+
const codeBranches = catalog.codeBranches();
|
|
331
331
|
return {
|
|
332
332
|
contents: [
|
|
333
333
|
{
|
|
@@ -335,7 +335,7 @@ export default function createMcpServer() {
|
|
|
335
335
|
mimeType: 'application/json',
|
|
336
336
|
text: JSON.stringify({
|
|
337
337
|
profile: PROFILE_LABEL,
|
|
338
|
-
...(
|
|
338
|
+
...(Object.keys(codeBranches).length > 0 ? { codeBranches } : {}),
|
|
339
339
|
apps: APP_SCHEMAS,
|
|
340
340
|
}, null, 2),
|
|
341
341
|
},
|
|
@@ -473,10 +473,13 @@ export default function createMcpServer() {
|
|
|
473
473
|
text = await catalog.forget(args.target, args.scope);
|
|
474
474
|
}
|
|
475
475
|
else if (action === 'branch') {
|
|
476
|
-
if (typeof args.
|
|
477
|
-
|
|
476
|
+
if (typeof args.repo !== 'string' ||
|
|
477
|
+
!args.repo.trim() ||
|
|
478
|
+
typeof args.branch !== 'string' ||
|
|
479
|
+
!args.branch.trim()) {
|
|
480
|
+
throw new Error('mysql_catalog branch requires "repo" and "branch", e.g. {repo: "owner/name", branch: "develop"}.');
|
|
478
481
|
}
|
|
479
|
-
text = catalog.setCodeBranch(args.branch);
|
|
482
|
+
text = catalog.setCodeBranch(args.repo, args.branch);
|
|
480
483
|
}
|
|
481
484
|
else if (action === 'refresh') {
|
|
482
485
|
if (args.target !== undefined && typeof args.target !== 'string') {
|
|
@@ -557,7 +560,7 @@ export default function createMcpServer() {
|
|
|
557
560
|
? [
|
|
558
561
|
{
|
|
559
562
|
...mysqlCatalogTool,
|
|
560
|
-
description: mysqlCatalogTool.description +
|
|
563
|
+
description: mysqlCatalogTool.description + codeBranchToolInstruction(catalog.codeBranches()),
|
|
561
564
|
},
|
|
562
565
|
]
|
|
563
566
|
: []),
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { normalizeGithubRepo } from './docs.js';
|
|
1
2
|
const REMOTE_PREFIX = 'origin/';
|
|
2
3
|
const BRANCH_MAX_LENGTH = 100;
|
|
3
4
|
const SUGGESTED_BRANCH = {
|
|
@@ -45,21 +46,41 @@ export function normalizeBranchName(input) {
|
|
|
45
46
|
}
|
|
46
47
|
return branch;
|
|
47
48
|
}
|
|
48
|
-
export function
|
|
49
|
-
return
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
'and record it with branch.';
|
|
49
|
+
export function formatCodeBranches(branches) {
|
|
50
|
+
return Object.keys(branches)
|
|
51
|
+
.sort()
|
|
52
|
+
.map((repo) => `${repo}@${branches[repo]}`)
|
|
53
|
+
.join(', ');
|
|
54
54
|
}
|
|
55
|
-
export function
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
55
|
+
export function codeBranchToolInstruction(branches) {
|
|
56
|
+
const recorded = formatCodeBranches(branches);
|
|
57
|
+
return ((recorded ? ` Recorded code branches: ${recorded}.` : '') +
|
|
58
|
+
' If this session is inside a GitHub repository whose branch is not recorded (response banners ' +
|
|
59
|
+
'list recorded ones after "code:"), and you will link its documents or correlate its code with ' +
|
|
60
|
+
'data, first ask the user which branch of that repository matches this database and record it ' +
|
|
61
|
+
'with branch {repo, branch}.');
|
|
62
|
+
}
|
|
63
|
+
export function codeRevisionDescription(branches) {
|
|
64
|
+
const recorded = formatCodeBranches(branches);
|
|
65
|
+
return recorded
|
|
66
|
+
? `\n\nCODE REVISION: this database matches ${recorded} (repository@branch). ` +
|
|
67
|
+
`Read entities, migrations, and queries from that branch of each repository when correlating code with data.`
|
|
68
|
+
: '';
|
|
69
|
+
}
|
|
70
|
+
export function loadedCodeBranches(value) {
|
|
71
|
+
const branches = {};
|
|
72
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) {
|
|
73
|
+
return branches;
|
|
61
74
|
}
|
|
62
|
-
|
|
63
|
-
|
|
75
|
+
for (const [repo, branch] of Object.entries(value)) {
|
|
76
|
+
try {
|
|
77
|
+
if (normalizeGithubRepo(repo) !== repo || typeof branch !== 'string') {
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
branches[repo] = normalizeBranchName(branch);
|
|
81
|
+
}
|
|
82
|
+
catch {
|
|
83
|
+
}
|
|
64
84
|
}
|
|
85
|
+
return branches;
|
|
65
86
|
}
|
package/dist/src/catalog/docs.js
CHANGED
|
@@ -16,7 +16,7 @@ export function normalizeGithubRepo(input) {
|
|
|
16
16
|
return `${owner}/${name}`;
|
|
17
17
|
}
|
|
18
18
|
}
|
|
19
|
-
throw new Error(`
|
|
19
|
+
throw new Error(`repo must be a GitHub repository as owner/name, https://github.com/owner/name, ` +
|
|
20
20
|
`or git@github.com:owner/name: "${input}".`);
|
|
21
21
|
}
|
|
22
22
|
export function normalizeDocumentPath(input) {
|
|
@@ -42,7 +42,7 @@ export class CatalogDocuments {
|
|
|
42
42
|
constructor(store) {
|
|
43
43
|
this.store = store;
|
|
44
44
|
}
|
|
45
|
-
link(links,
|
|
45
|
+
link(links, guidanceFor = () => null) {
|
|
46
46
|
const resolved = links.map((link) => ({
|
|
47
47
|
...link,
|
|
48
48
|
doc: normalizeDocumentPath(link.doc),
|
|
@@ -68,13 +68,16 @@ export class CatalogDocuments {
|
|
|
68
68
|
}
|
|
69
69
|
}
|
|
70
70
|
});
|
|
71
|
+
const guidance = [...new Set(resolved.map((link) => link.repo))]
|
|
72
|
+
.map(guidanceFor)
|
|
73
|
+
.filter((entry) => entry !== null);
|
|
71
74
|
return JSON.stringify({
|
|
72
75
|
linked: resolved.map((link) => ({
|
|
73
76
|
table: `${link.schema}.${link.table}`,
|
|
74
77
|
doc: link.doc,
|
|
75
78
|
repo: link.repo,
|
|
76
79
|
})),
|
|
77
|
-
...(guidance ? { guidance } : {}),
|
|
80
|
+
...(guidance.length > 0 ? { guidance } : {}),
|
|
78
81
|
}, null, 2);
|
|
79
82
|
}
|
|
80
83
|
unlink(schemaName, tableName) {
|
|
@@ -2,8 +2,8 @@ import { createHash } from 'crypto';
|
|
|
2
2
|
import * as os from 'os';
|
|
3
3
|
import * as path from 'path';
|
|
4
4
|
import { CatalogCollector } from './collect.js';
|
|
5
|
-
import { CatalogDocuments } from './docs.js';
|
|
6
|
-
import { normalizeBranchName } from './branch.js';
|
|
5
|
+
import { CatalogDocuments, normalizeGithubRepo } from './docs.js';
|
|
6
|
+
import { formatCodeBranches, normalizeBranchName } from './branch.js';
|
|
7
7
|
import { missingBranchNotice, renderDescribe, renderMap, renderToolDescriptionSuffix, searchCatalog, } from './render.js';
|
|
8
8
|
import { CatalogStore } from './store.js';
|
|
9
9
|
import { emptyUsage, normalizeName, pruneJoins } from './types.js';
|
|
@@ -64,31 +64,36 @@ export class SchemaCatalog {
|
|
|
64
64
|
isEnabled() {
|
|
65
65
|
return this.store.isEnabled();
|
|
66
66
|
}
|
|
67
|
-
|
|
68
|
-
return this.isEnabled() ? this.store.
|
|
67
|
+
codeBranches() {
|
|
68
|
+
return this.isEnabled() ? { ...this.store.codeBranches() } : {};
|
|
69
69
|
}
|
|
70
|
-
|
|
70
|
+
codeBranchSummary() {
|
|
71
|
+
return this.isEnabled() ? formatCodeBranches(this.store.codeBranches()) || null : null;
|
|
72
|
+
}
|
|
73
|
+
setCodeBranch(repoInput, branchInput) {
|
|
71
74
|
if (!this.isEnabled()) {
|
|
72
75
|
throw new Error('The schema catalog is disabled.');
|
|
73
76
|
}
|
|
74
|
-
const
|
|
75
|
-
const
|
|
77
|
+
const repo = normalizeGithubRepo(repoInput);
|
|
78
|
+
const branch = normalizeBranchName(branchInput);
|
|
79
|
+
const previous = this.store.codeBranches()[repo] ?? null;
|
|
76
80
|
if (previous === branch) {
|
|
77
|
-
return JSON.stringify({ branch, changed: false, status:
|
|
81
|
+
return JSON.stringify({ repo, branch, changed: false, status: `${repo}에는 이미 ${branch} 브랜치가 기록돼 있습니다.` }, null, 2);
|
|
78
82
|
}
|
|
79
83
|
this.store.update((catalog) => {
|
|
80
|
-
catalog.
|
|
84
|
+
catalog.codeBranches[repo] = branch;
|
|
81
85
|
});
|
|
82
|
-
if (this.store.
|
|
86
|
+
if (this.store.codeBranches()[repo] !== branch) {
|
|
83
87
|
throw new Error('The catalog cache is disabled, so the branch was not recorded.');
|
|
84
88
|
}
|
|
85
89
|
return JSON.stringify({
|
|
90
|
+
repo,
|
|
86
91
|
branch,
|
|
87
92
|
...(previous ? { previous } : {}),
|
|
88
93
|
changed: true,
|
|
89
94
|
status: previous
|
|
90
|
-
?
|
|
91
|
-
: `${branch} 브랜치를 기록했습니다. 다음 세션에도 이어 씁니다.`,
|
|
95
|
+
? `${repo}의 브랜치를 바꿨습니다: ${previous} → ${branch}`
|
|
96
|
+
: `${repo}에 ${branch} 브랜치를 기록했습니다. 다음 세션에도 이어 씁니다.`,
|
|
92
97
|
note: 'banner와 describe는 바로 이 값을 씁니다. mysql_query 툴 설명의 CODE REVISION은 서버를 다시 띄우면 바뀝니다.',
|
|
93
98
|
}, null, 2);
|
|
94
99
|
}
|
|
@@ -193,7 +198,7 @@ export class SchemaCatalog {
|
|
|
193
198
|
if (!entry) {
|
|
194
199
|
throw new Error(`Table disappeared during refresh: ${input}`);
|
|
195
200
|
}
|
|
196
|
-
return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.
|
|
201
|
+
return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.codeBranches(), this.store.readJoins(resolved.schema, resolved.table), this.options.profile);
|
|
197
202
|
}
|
|
198
203
|
async refresh(target) {
|
|
199
204
|
if (!this.isEnabled()) {
|
|
@@ -270,7 +275,7 @@ export class SchemaCatalog {
|
|
|
270
275
|
repo: link.repo,
|
|
271
276
|
});
|
|
272
277
|
}
|
|
273
|
-
return this.documents.link(resolvedLinks, this.store.
|
|
278
|
+
return this.documents.link(resolvedLinks, (repo) => this.store.codeBranches()[repo] ? null : missingBranchNotice(this.options.profile, repo));
|
|
274
279
|
}
|
|
275
280
|
async unlink(input) {
|
|
276
281
|
if (!this.isEnabled()) {
|
|
@@ -409,9 +414,9 @@ export class SchemaCatalog {
|
|
|
409
414
|
return null;
|
|
410
415
|
}
|
|
411
416
|
return (`[카탈로그] ${[...unreviewed].join(', ')} 에 연결된 문서가 없습니다.\n` +
|
|
412
|
-
`도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${first}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로
|
|
413
|
-
|
|
414
|
-
|
|
417
|
+
`도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${first}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로 연결하세요.\n` +
|
|
418
|
+
`문서 저장소 안의 세션에서 찾아봤는데 없을 때만 mysql_catalog {action:"unlink", table:"${first}"} 로 기록하세요. ` +
|
|
419
|
+
'그 저장소 밖의 세션이면 unlink하지 마세요.');
|
|
415
420
|
}
|
|
416
421
|
indexFacts(reference) {
|
|
417
422
|
if (!this.isEnabled()) {
|
|
@@ -137,13 +137,16 @@ export function searchCatalog(catalog, query, limit) {
|
|
|
137
137
|
}
|
|
138
138
|
return results.sort((a, b) => b.score - a.score || a.table.localeCompare(b.table)).slice(0, limit);
|
|
139
139
|
}
|
|
140
|
-
|
|
140
|
+
function branchQuestion(profile, repo) {
|
|
141
141
|
const suggestion = suggestedBranch(profile);
|
|
142
142
|
const question = suggestion
|
|
143
|
-
? `${profile} profile은 보통 ${suggestion} 브랜치에 대응합니다. ${suggestion}이 맞는지 사용자에게 물으세요.`
|
|
144
|
-
: `이 profile(${profile})이 어느 브랜치에 대응하는지 사용자에게 물으세요.`;
|
|
145
|
-
return (
|
|
146
|
-
|
|
143
|
+
? `${profile} profile은 보통 ${suggestion} 브랜치에 대응합니다. ${repo}의 ${suggestion}이 맞는지 사용자에게 물으세요.`
|
|
144
|
+
: `이 profile(${profile})이 ${repo}의 어느 브랜치에 대응하는지 사용자에게 물으세요.`;
|
|
145
|
+
return (`${question}\n` +
|
|
146
|
+
`확인받은 값을 mysql_catalog {action:"branch", repo:"${repo}", branch:"<브랜치 이름>"} 로 기록하세요.`);
|
|
147
|
+
}
|
|
148
|
+
export function missingBranchNotice(profile, repo) {
|
|
149
|
+
return (`[카탈로그] ${repo}에서 이 DB에 대응하는 코드 브랜치가 기록되지 않았습니다. ` + branchQuestion(profile, repo));
|
|
147
150
|
}
|
|
148
151
|
function shellQuote(value) {
|
|
149
152
|
if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) {
|
|
@@ -151,7 +154,7 @@ function shellQuote(value) {
|
|
|
151
154
|
}
|
|
152
155
|
return `'${value.replace(/'/g, `'"'"'`)}'`;
|
|
153
156
|
}
|
|
154
|
-
export function renderDescribe(qualifiedName, table,
|
|
157
|
+
export function renderDescribe(qualifiedName, table, codeBranches, observedJoins, profile) {
|
|
155
158
|
let docs;
|
|
156
159
|
const hasDocumentDecision = Object.prototype.hasOwnProperty.call(table.curated, 'doc');
|
|
157
160
|
const documentLink = table.curated.doc;
|
|
@@ -159,14 +162,14 @@ export function renderDescribe(qualifiedName, table, codeBranch, observedJoins,
|
|
|
159
162
|
docs =
|
|
160
163
|
'연결 안 됨\n' +
|
|
161
164
|
`도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${qualifiedName}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로 연결하세요.\n` +
|
|
162
|
-
'status 같은 코드 컬럼의 의미는 도메인 문서에만 있습니다.'
|
|
163
|
-
(codeBranch ? '' : `\n${missingBranchNotice(profile)}`);
|
|
165
|
+
'status 같은 코드 컬럼의 의미는 도메인 문서에만 있습니다.';
|
|
164
166
|
}
|
|
165
167
|
else if (documentLink == null) {
|
|
166
168
|
docs = '문서 없음 확인됨';
|
|
167
169
|
}
|
|
168
170
|
else {
|
|
169
171
|
const { repo } = documentLink;
|
|
172
|
+
const codeBranch = Object.prototype.hasOwnProperty.call(codeBranches, repo) ? codeBranches[repo] : null;
|
|
170
173
|
docs = {
|
|
171
174
|
path: documentLink.path,
|
|
172
175
|
repo,
|
|
@@ -178,9 +181,11 @@ export function renderDescribe(qualifiedName, table, codeBranch, observedJoins,
|
|
|
178
181
|
.map(encodeURIComponent)
|
|
179
182
|
.join('/')}?ref=${encodeURIComponent(codeBranch)}`)}`
|
|
180
183
|
: null,
|
|
181
|
-
guidance: '상태 코드·도메인 규칙은 이 문서를 먼저 읽어라.
|
|
182
|
-
|
|
183
|
-
|
|
184
|
+
guidance: '상태 코드·도메인 규칙은 이 문서를 먼저 읽어라.' +
|
|
185
|
+
(codeBranch
|
|
186
|
+
? ' command는 문서가 있는 저장소 안에서, remoteCommand는 어디서든(gh 인증 필요) 실행한다.'
|
|
187
|
+
: `\n${repo}의 브랜치가 기록되지 않아 읽기 명령이 없습니다. 이 문서를 읽어야 할 때만 ` +
|
|
188
|
+
`아래대로 하세요.\n${branchQuestion(profile, repo)}`),
|
|
184
189
|
};
|
|
185
190
|
}
|
|
186
191
|
return JSON.stringify({
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as fs from 'fs';
|
|
2
2
|
import * as path from 'path';
|
|
3
|
-
import {
|
|
3
|
+
import { loadedCodeBranches } from './branch.js';
|
|
4
4
|
import { normalizeDocumentPath, normalizeGithubRepo } from './docs.js';
|
|
5
5
|
import { CATALOG_VERSION, emptyCatalog, emptyTable, normalizeName, pruneJoins } from './types.js';
|
|
6
6
|
const FLUSH_DELAY_MS = 2_000;
|
|
@@ -211,6 +211,16 @@ function mergeSchema(external, local, base) {
|
|
|
211
211
|
}
|
|
212
212
|
return { ...newerInventory, tables };
|
|
213
213
|
}
|
|
214
|
+
function mergeCodeBranches(external, local, base) {
|
|
215
|
+
const merged = {};
|
|
216
|
+
for (const repo of new Set([...Object.keys(external), ...Object.keys(local), ...Object.keys(base)])) {
|
|
217
|
+
const branch = local[repo] !== base[repo] ? local[repo] : external[repo];
|
|
218
|
+
if (branch !== undefined) {
|
|
219
|
+
merged[repo] = branch;
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
return merged;
|
|
223
|
+
}
|
|
214
224
|
function mergeCatalog(external, local, base) {
|
|
215
225
|
const schemas = {};
|
|
216
226
|
for (const name of new Set([...Object.keys(external.schemas), ...Object.keys(local.schemas)])) {
|
|
@@ -246,7 +256,7 @@ function mergeCatalog(external, local, base) {
|
|
|
246
256
|
}
|
|
247
257
|
return {
|
|
248
258
|
...local,
|
|
249
|
-
|
|
259
|
+
codeBranches: mergeCodeBranches(external.codeBranches, local.codeBranches, base.codeBranches),
|
|
250
260
|
schemas,
|
|
251
261
|
joins: pruneJoins([...joins.values()]),
|
|
252
262
|
};
|
|
@@ -332,7 +342,7 @@ export class CatalogStore {
|
|
|
332
342
|
}
|
|
333
343
|
sanitizeLoaded(loaded) {
|
|
334
344
|
const fresh = emptyCatalog(this.options);
|
|
335
|
-
fresh.
|
|
345
|
+
fresh.codeBranches = loadedCodeBranches(loaded.codeBranches);
|
|
336
346
|
for (const [schemaName, schema] of Object.entries(fresh.schemas)) {
|
|
337
347
|
const cached = loaded.schemas?.[schemaName];
|
|
338
348
|
if (!cached) {
|
|
@@ -400,8 +410,8 @@ export class CatalogStore {
|
|
|
400
410
|
snapshot() {
|
|
401
411
|
return structuredClone(this.data);
|
|
402
412
|
}
|
|
403
|
-
|
|
404
|
-
return this.data.
|
|
413
|
+
codeBranches() {
|
|
414
|
+
return this.data.codeBranches;
|
|
405
415
|
}
|
|
406
416
|
lookup(schemaHint, table) {
|
|
407
417
|
const index = this.ensureNameIndex();
|
package/dist/src/db/index.js
CHANGED
|
@@ -122,7 +122,7 @@ function profileBanner() {
|
|
|
122
122
|
parts.push(`database: ${db}`);
|
|
123
123
|
const branch = codeBranchSource?.();
|
|
124
124
|
if (branch) {
|
|
125
|
-
parts.push(`code: ${branch}
|
|
125
|
+
parts.push(`code: ${branch}`);
|
|
126
126
|
}
|
|
127
127
|
const tunnel = describeTunnel();
|
|
128
128
|
if (tunnel) {
|
package/package.json
CHANGED