@brainbox-labs/cli 0.0.0-stage → 0.14.2

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.
Files changed (3) hide show
  1. package/README.md +264 -2
  2. package/dist/cli.js +3922 -0
  3. package/package.json +59 -4
package/dist/cli.js ADDED
@@ -0,0 +1,3922 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/cli.ts
4
+ import "dotenv/config";
5
+ import { Command as Command7 } from "commander";
6
+ import { createRequire } from "module";
7
+
8
+ // src/commands/meta.ts
9
+ import { Command } from "commander";
10
+ import * as fs5 from "fs/promises";
11
+ import * as nodePath3 from "path";
12
+
13
+ // src/sql-parser.ts
14
+ import { parse } from "pgsql-ast-parser";
15
+ import * as fs from "fs/promises";
16
+ import * as path from "path";
17
+ function extractQueryName(filename, sql) {
18
+ const lines = sql.split("\n");
19
+ for (const line of lines) {
20
+ const trimmed = line.trim();
21
+ if (!trimmed.startsWith("--")) break;
22
+ const nameMatch = trimmed.match(/^--\s*name:\s*(\S+)/i);
23
+ if (nameMatch !== null && nameMatch[1] !== void 0) {
24
+ return nameMatch[1];
25
+ }
26
+ const singleWordMatch = trimmed.match(/^--\s+([A-Za-z][A-Za-z0-9_]+)\s*$/);
27
+ if (singleWordMatch !== null && singleWordMatch[1] !== void 0) {
28
+ return singleWordMatch[1];
29
+ }
30
+ }
31
+ return path.basename(filename, path.extname(filename));
32
+ }
33
+ function extractComments(sql) {
34
+ const comments = [];
35
+ for (const line of sql.split("\n")) {
36
+ const trimmed = line.trim();
37
+ if (trimmed.startsWith("--")) {
38
+ comments.push(trimmed);
39
+ }
40
+ }
41
+ return comments;
42
+ }
43
+ function inferParameterName(sql, position) {
44
+ const paramToken = `$${position}`;
45
+ const pattern = /(\w+)\s*(?:=|>|<|>=|<=|LIKE|ILIKE|!=|<>)\s*\$(\d+)/gi;
46
+ let match;
47
+ while ((match = pattern.exec(sql)) !== null) {
48
+ if (match[2] === String(position)) {
49
+ return match[1] ?? paramToken;
50
+ }
51
+ }
52
+ return paramToken;
53
+ }
54
+ function extractParameters(sql) {
55
+ const paramRegex = /\$(\d+)/g;
56
+ const seen = /* @__PURE__ */ new Set();
57
+ const params = [];
58
+ let match;
59
+ while ((match = paramRegex.exec(sql)) !== null) {
60
+ const pos = parseInt(match[1] ?? "0", 10);
61
+ if (!seen.has(pos)) {
62
+ seen.add(pos);
63
+ params.push({
64
+ position: pos,
65
+ inferredName: inferParameterName(sql, pos)
66
+ });
67
+ }
68
+ }
69
+ params.sort((a, b) => a.position - b.position);
70
+ return params;
71
+ }
72
+ function collectTablesFromFrom(froms, tables) {
73
+ if (!froms) return;
74
+ for (const from of froms) {
75
+ if (from.type === "table") {
76
+ const ft = from;
77
+ tables.add(ft.name.name.toLowerCase());
78
+ } else if (from.type === "statement") {
79
+ walkStatementForTables(from.statement, tables);
80
+ }
81
+ }
82
+ }
83
+ function walkStatementForTables(stmt, tables) {
84
+ if (stmt.type === "select") {
85
+ const sel = stmt;
86
+ collectTablesFromFrom(sel.from ?? null, tables);
87
+ } else if (stmt.type === "with" || stmt.type === "with recursive") {
88
+ if ("bind" in stmt && Array.isArray(stmt.bind)) {
89
+ for (const binding of stmt.bind) {
90
+ if ("statement" in binding) {
91
+ walkStatementForTables(binding.statement, tables);
92
+ }
93
+ }
94
+ }
95
+ if ("in" in stmt) {
96
+ walkStatementForTables(stmt.in, tables);
97
+ }
98
+ } else if (stmt.type === "union" || stmt.type === "union all") {
99
+ walkStatementForTables(stmt.left, tables);
100
+ walkStatementForTables(stmt.right, tables);
101
+ }
102
+ }
103
+ function collectColumnsFromSelect(columns, selected) {
104
+ if (!columns) return;
105
+ for (const col of columns) {
106
+ const expr = col.expr;
107
+ if (expr && "type" in expr && expr.type === "ref") {
108
+ const ref = expr;
109
+ if (ref.name !== "*") {
110
+ selected.push(ref.name.toLowerCase());
111
+ }
112
+ }
113
+ }
114
+ }
115
+ function collectColumnsFromWhere(where, filtered) {
116
+ if (!where) return;
117
+ if ("type" in where) {
118
+ if (where.type === "binary") {
119
+ const bin = where;
120
+ if ("type" in bin.left && bin.left.type === "ref") {
121
+ const ref = bin.left;
122
+ if (ref.name !== "*") {
123
+ filtered.push(ref.name.toLowerCase());
124
+ }
125
+ }
126
+ collectColumnsFromWhere(bin.left, filtered);
127
+ collectColumnsFromWhere(bin.right, filtered);
128
+ }
129
+ }
130
+ }
131
+ function buildJoinPatterns(froms) {
132
+ if (!froms) return [];
133
+ const patterns = [];
134
+ for (const from of froms) {
135
+ if (from.type === "table") {
136
+ const ft = from;
137
+ if (ft.join) {
138
+ const joinType = ft.join.type;
139
+ const tableName = ft.name.name;
140
+ let onClause = "";
141
+ if (ft.join.on && "type" in ft.join.on && ft.join.on.type === "binary") {
142
+ const bin = ft.join.on;
143
+ const left = formatExprRef(bin.left);
144
+ const right = formatExprRef(bin.right);
145
+ if (left && right) {
146
+ onClause = ` ON ${left} = ${right}`;
147
+ }
148
+ }
149
+ patterns.push(`${joinType} ${tableName}${onClause}`);
150
+ }
151
+ }
152
+ }
153
+ return patterns;
154
+ }
155
+ function formatExprRef(expr) {
156
+ if (!expr || !("type" in expr)) return null;
157
+ if (expr.type === "ref") {
158
+ const ref = expr;
159
+ if (ref.table) {
160
+ return `${ref.table.name}.${ref.name}`;
161
+ }
162
+ return ref.name;
163
+ }
164
+ return null;
165
+ }
166
+ function parseSqlFile(filename, sql) {
167
+ const name = extractQueryName(filename, sql);
168
+ const comments = extractComments(sql);
169
+ const parameters = extractParameters(sql);
170
+ const tablesReferenced = [];
171
+ const columnsSelected = [];
172
+ const columnsFiltered = [];
173
+ const joinPatterns = [];
174
+ try {
175
+ const statements = parse(sql);
176
+ for (const stmt of statements) {
177
+ const tableSet = /* @__PURE__ */ new Set();
178
+ walkStatementForTables(stmt, tableSet);
179
+ for (const t of tableSet) {
180
+ if (!tablesReferenced.includes(t)) {
181
+ tablesReferenced.push(t);
182
+ }
183
+ }
184
+ if (stmt.type === "select") {
185
+ const sel = stmt;
186
+ collectColumnsFromSelect(sel.columns ?? null, columnsSelected);
187
+ collectColumnsFromWhere(sel.where ?? null, columnsFiltered);
188
+ const patterns = buildJoinPatterns(sel.from ?? null);
189
+ joinPatterns.push(...patterns);
190
+ }
191
+ }
192
+ } catch (_err) {
193
+ }
194
+ return {
195
+ name,
196
+ filename,
197
+ sql,
198
+ tablesReferenced,
199
+ columnsSelected: [...new Set(columnsSelected)],
200
+ columnsFiltered: [...new Set(columnsFiltered)],
201
+ joinPatterns,
202
+ parameters,
203
+ comments
204
+ };
205
+ }
206
+ async function parseSqlDirectory(dirPath) {
207
+ const entries = await fs.readdir(dirPath);
208
+ const sqlFiles = entries.filter((f) => f.endsWith(".sql"));
209
+ const results = [];
210
+ for (const file of sqlFiles) {
211
+ const filePath = path.join(dirPath, file);
212
+ const content = await fs.readFile(filePath, "utf-8");
213
+ results.push(parseSqlFile(file, content));
214
+ }
215
+ return results;
216
+ }
217
+
218
+ // src/mcp-introspect.ts
219
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
220
+ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
221
+ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
222
+ var BRAINBOX_SERVER_NAME = "brainbox-mcp";
223
+ var BrainboxServerError = class extends Error {
224
+ constructor() {
225
+ super(
226
+ "This is a Brainbox-powered MCP server. Ingesting its tools back into Brainbox would create circular definitions."
227
+ );
228
+ this.name = "BrainboxServerError";
229
+ }
230
+ };
231
+ async function introspectMcpServer(serverUrl) {
232
+ const client = new Client({ name: "brainbox-cli", version: "1.0.0" });
233
+ const url = new URL(serverUrl);
234
+ let connected = false;
235
+ let streamableHttpError;
236
+ try {
237
+ await client.connect(new StreamableHTTPClientTransport(url));
238
+ connected = true;
239
+ } catch (err) {
240
+ streamableHttpError = err;
241
+ }
242
+ if (!connected) {
243
+ try {
244
+ await client.connect(new SSEClientTransport(url));
245
+ } catch (err) {
246
+ const sseMsg = err instanceof Error ? err.message : String(err);
247
+ const streamableMsg = streamableHttpError instanceof Error ? streamableHttpError.message : "";
248
+ const detail = streamableMsg ? `SSE: ${sseMsg}; StreamableHTTP: ${streamableMsg}` : sseMsg;
249
+ throw new Error(`Could not connect to MCP server at ${serverUrl}: ${detail}`);
250
+ }
251
+ }
252
+ try {
253
+ const serverInfo = client.getServerVersion();
254
+ if (serverInfo?.name === BRAINBOX_SERVER_NAME) {
255
+ throw new BrainboxServerError();
256
+ }
257
+ const { tools } = await client.listTools();
258
+ return tools.map((t) => {
259
+ const rawProps = t.inputSchema.type === "object" && t.inputSchema.properties ? t.inputSchema.properties : {};
260
+ const properties = Object.fromEntries(
261
+ Object.entries(rawProps).map(([key, val]) => {
262
+ const v = val;
263
+ return [key, {
264
+ type: typeof v?.["type"] === "string" ? v["type"] : "string",
265
+ description: typeof v?.["description"] === "string" ? v["description"] : ""
266
+ }];
267
+ })
268
+ );
269
+ const required = Array.isArray(t.inputSchema.required) ? t.inputSchema.required : void 0;
270
+ return {
271
+ name: t.name,
272
+ description: t.description ?? "",
273
+ inputSchema: {
274
+ type: "object",
275
+ properties,
276
+ ...required ? { required } : {}
277
+ }
278
+ };
279
+ });
280
+ } finally {
281
+ await client.close();
282
+ }
283
+ }
284
+
285
+ // src/logger.ts
286
+ import * as fs2 from "fs/promises";
287
+ import * as path2 from "path";
288
+ import * as os from "os";
289
+ function timestamp() {
290
+ return (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
291
+ }
292
+ function createLogger(verbose2, format = "text") {
293
+ const isVerbose = verbose2 || process.env["DEBUG"]?.split(",").some((s) => s.trim() === "brainbox") === true;
294
+ if (format === "json") {
295
+ return {
296
+ isVerbose,
297
+ info(msg) {
298
+ console.log(JSON.stringify({ level: "info", ts: (/* @__PURE__ */ new Date()).toISOString(), msg }));
299
+ },
300
+ debug(msg, data) {
301
+ if (!isVerbose) return;
302
+ console.log(JSON.stringify({ level: "debug", ts: (/* @__PURE__ */ new Date()).toISOString(), msg, ...data !== void 0 ? { data } : {} }));
303
+ },
304
+ warn(msg) {
305
+ console.warn(JSON.stringify({ level: "warn", ts: (/* @__PURE__ */ new Date()).toISOString(), msg }));
306
+ },
307
+ error(msg) {
308
+ console.error(JSON.stringify({ level: "error", ts: (/* @__PURE__ */ new Date()).toISOString(), msg }));
309
+ }
310
+ };
311
+ }
312
+ return {
313
+ isVerbose,
314
+ info(msg) {
315
+ console.log(`${timestamp()} ${msg}`);
316
+ },
317
+ debug(msg, data) {
318
+ if (!isVerbose) return;
319
+ const prefix = "\x1B[36m[debug]\x1B[0m";
320
+ console.log(`${timestamp()} ${prefix} ${msg}`);
321
+ if (data !== void 0) {
322
+ console.log(JSON.stringify(data, null, 2));
323
+ }
324
+ },
325
+ warn(msg) {
326
+ console.warn(`${timestamp()} \x1B[33mWarning:\x1B[0m ${msg}`);
327
+ },
328
+ error(msg) {
329
+ console.error(`${timestamp()} ${msg}`);
330
+ }
331
+ };
332
+ }
333
+ async function writeAuditLog(entry) {
334
+ const dir = path2.join(os.homedir(), ".brainbox");
335
+ const file = path2.join(dir, "audit.log");
336
+ await fs2.mkdir(dir, { recursive: true });
337
+ await fs2.appendFile(file, JSON.stringify(entry) + "\n", "utf-8");
338
+ }
339
+
340
+ // src/local-state.ts
341
+ import * as fs3 from "fs/promises";
342
+ import * as nodePath from "path";
343
+ import * as crypto from "crypto";
344
+ function brainboxDir(cwd = process.cwd()) {
345
+ return nodePath.posix.join(cwd, ".brainbox");
346
+ }
347
+ function configPath(cwd) {
348
+ return nodePath.posix.join(brainboxDir(cwd), "config.json");
349
+ }
350
+ function stagingDir(cwd) {
351
+ return nodePath.posix.join(brainboxDir(cwd), "staging");
352
+ }
353
+ function stagingManifestPath(cwd) {
354
+ return nodePath.posix.join(stagingDir(cwd), "manifest.json");
355
+ }
356
+ function commitsDir(cwd) {
357
+ return nodePath.posix.join(brainboxDir(cwd), "commits");
358
+ }
359
+ function headPath(cwd) {
360
+ return nodePath.posix.join(brainboxDir(cwd), "HEAD");
361
+ }
362
+ function pushStatePath(cwd) {
363
+ return nodePath.posix.join(brainboxDir(cwd), "push-state.json");
364
+ }
365
+ function activeLayerPath(cwd) {
366
+ return nodePath.posix.join(brainboxDir(cwd), "active-layer.json");
367
+ }
368
+ function devPidPath(cwd) {
369
+ return nodePath.posix.join(brainboxDir(cwd), "dev.pid");
370
+ }
371
+ function collectedDir(collector, runId, cwd) {
372
+ return nodePath.posix.join(brainboxDir(cwd), "collected", collector, runId);
373
+ }
374
+ async function initBrainboxDir(config, cwd) {
375
+ const dir = brainboxDir(cwd);
376
+ await fs3.mkdir(dir, { recursive: true });
377
+ await fs3.mkdir(stagingDir(cwd), { recursive: true });
378
+ await fs3.mkdir(commitsDir(cwd), { recursive: true });
379
+ await fs3.mkdir(nodePath.posix.join(stagingDir(cwd), "files"), { recursive: true });
380
+ await writeConfig(config, cwd);
381
+ const gitignorePath = nodePath.posix.join(dir, ".gitignore");
382
+ const gitignoreContent = [
383
+ "# Generated by brainbox CLI \u2014 do not edit",
384
+ "staging/",
385
+ "collected/",
386
+ "commits/",
387
+ "HEAD",
388
+ "active-layer.json",
389
+ "push-state.json",
390
+ "dev.pid",
391
+ ""
392
+ ].join("\n");
393
+ await fs3.writeFile(gitignorePath, gitignoreContent, "utf-8");
394
+ try {
395
+ await fs3.access(stagingManifestPath(cwd));
396
+ } catch {
397
+ const emptyManifest = { sources: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
398
+ await fs3.writeFile(stagingManifestPath(cwd), JSON.stringify(emptyManifest, null, 2), "utf-8");
399
+ }
400
+ }
401
+ async function brainboxDirExists(cwd) {
402
+ try {
403
+ await fs3.access(brainboxDir(cwd));
404
+ return true;
405
+ } catch {
406
+ return false;
407
+ }
408
+ }
409
+ async function readConfig(cwd) {
410
+ const raw = await fs3.readFile(configPath(cwd), "utf-8");
411
+ return JSON.parse(raw);
412
+ }
413
+ async function writeConfig(config, cwd) {
414
+ await fs3.writeFile(configPath(cwd), JSON.stringify(config, null, 2), "utf-8");
415
+ }
416
+ async function readStagingManifest(cwd) {
417
+ try {
418
+ const raw = await fs3.readFile(stagingManifestPath(cwd), "utf-8");
419
+ return JSON.parse(raw);
420
+ } catch {
421
+ return { sources: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
422
+ }
423
+ }
424
+ async function writeStagingManifest(manifest, cwd) {
425
+ await fs3.mkdir(stagingDir(cwd), { recursive: true });
426
+ await fs3.writeFile(stagingManifestPath(cwd), JSON.stringify(manifest, null, 2), "utf-8");
427
+ }
428
+ async function clearStagingManifest(cwd) {
429
+ await writeStagingManifest({ sources: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, cwd);
430
+ }
431
+ async function upsertStagedSource(source, cwd) {
432
+ const manifest = await readStagingManifest(cwd);
433
+ const idx = manifest.sources.findIndex((s) => s.type === source.type && s.path === source.path);
434
+ if (idx >= 0) {
435
+ manifest.sources[idx] = source;
436
+ } else {
437
+ manifest.sources.push(source);
438
+ }
439
+ manifest.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
440
+ await writeStagingManifest(manifest, cwd);
441
+ }
442
+ function dbStagingPath(cwd) {
443
+ return nodePath.posix.join(stagingDir(cwd), "db.json");
444
+ }
445
+ function mcpStagingPath(cwd) {
446
+ return nodePath.posix.join(stagingDir(cwd), "mcp.json");
447
+ }
448
+ function nosqlStagingPath(cwd) {
449
+ return nodePath.posix.join(stagingDir(cwd), "nosql.json");
450
+ }
451
+ function docStagingDir(cwd) {
452
+ return nodePath.posix.join(stagingDir(cwd), "files");
453
+ }
454
+ async function computeStagingSha(cwd) {
455
+ const hash = crypto.createHash("sha256");
456
+ const manifest = await readStagingManifest(cwd);
457
+ const normalised = manifest.sources.map(({ type, path: path4, analysisDepth }) => ({ type, path: path4, ...analysisDepth && { analysisDepth } })).sort((a, b) => `${a.type}:${a.path}`.localeCompare(`${b.type}:${b.path}`));
458
+ hash.update(JSON.stringify(normalised));
459
+ for (const { path: relPath } of normalised) {
460
+ const absPath = nodePath.posix.join(brainboxDir(cwd), relPath);
461
+ try {
462
+ const content = await fs3.readFile(absPath);
463
+ hash.update(relPath);
464
+ hash.update(content);
465
+ } catch {
466
+ }
467
+ }
468
+ return hash.digest("hex").slice(0, 12);
469
+ }
470
+ async function writeCommit(commit, cwd) {
471
+ await fs3.mkdir(commitsDir(cwd), { recursive: true });
472
+ const commitFile = nodePath.posix.join(commitsDir(cwd), `${commit.sha}.json`);
473
+ await fs3.writeFile(commitFile, JSON.stringify(commit, null, 2), "utf-8");
474
+ await fs3.writeFile(headPath(cwd), commit.sha, "utf-8");
475
+ }
476
+ async function readHead(cwd) {
477
+ try {
478
+ const sha = await fs3.readFile(headPath(cwd), "utf-8");
479
+ return sha.trim() || null;
480
+ } catch {
481
+ return null;
482
+ }
483
+ }
484
+ async function readCommit(sha, cwd) {
485
+ try {
486
+ const raw = await fs3.readFile(nodePath.posix.join(commitsDir(cwd), `${sha}.json`), "utf-8");
487
+ return JSON.parse(raw);
488
+ } catch {
489
+ return null;
490
+ }
491
+ }
492
+ async function listLocalCommits(cwd) {
493
+ try {
494
+ const files = await fs3.readdir(commitsDir(cwd));
495
+ const commits = [];
496
+ for (const file of files) {
497
+ if (!file.endsWith(".json")) continue;
498
+ const raw = await fs3.readFile(nodePath.posix.join(commitsDir(cwd), file), "utf-8");
499
+ commits.push(JSON.parse(raw));
500
+ }
501
+ return commits.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
502
+ } catch {
503
+ return [];
504
+ }
505
+ }
506
+ async function readPushState(cwd) {
507
+ try {
508
+ const raw = await fs3.readFile(pushStatePath(cwd), "utf-8");
509
+ return JSON.parse(raw);
510
+ } catch {
511
+ return null;
512
+ }
513
+ }
514
+ async function writePushState(state, cwd) {
515
+ await fs3.writeFile(pushStatePath(cwd), JSON.stringify(state, null, 2), "utf-8");
516
+ }
517
+
518
+ // src/api-client.ts
519
+ import { BrainBoxApiClient } from "@brainbox-labs/api";
520
+
521
+ // src/commands/common.ts
522
+ var DEFAULT_API_URL = process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app";
523
+ function addCommonOptions(cmd) {
524
+ return cmd.option("--org <name>", "Organization name (or BRAINBOX_ORG)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Any org project \u2014 auto-creates if missing (or BRAINBOX_PROJECT). Mutually exclusive with --tenant.").option("--tenant <name>", "Existing tenant overlay \u2014 never auto-creates, errors if not found (or BRAINBOX_TENANT). Mutually exclusive with --project.").option("--api-url <url>", "API base URL (or BRAINBOX_API_URL)", DEFAULT_API_URL).option("--api-key <key>", "API key (or BRAINBOX_API_KEY)", process.env["BRAINBOX_API_KEY"]).option("--verbose", "Print debug details").option("--log-format <format>", "Log format: text or json", "text");
525
+ }
526
+ function addLogOptions(cmd) {
527
+ return cmd.option("--verbose", "Print debug details").option("--log-format <format>", "Log format: text or json", "text");
528
+ }
529
+ function isNotFoundError(err) {
530
+ return err instanceof Error && /\bAPI 404\b/.test(err.message);
531
+ }
532
+ var TENANT_PROJECT_MUTEX_MESSAGE = "error: --tenant and --project are mutually exclusive \u2014 use --tenant to target an existing tenant overlay (never auto-creates), or --project to target a plain project (auto-creates if missing)";
533
+ function resolveTenantOrProject(options, logger) {
534
+ if (options.tenant && options.project) {
535
+ logger.error(TENANT_PROJECT_MUTEX_MESSAGE);
536
+ process.exit(1);
537
+ }
538
+ if (options.tenant) return { tenant: options.tenant };
539
+ if (options.project) return { project: options.project };
540
+ const envTenant = process.env["BRAINBOX_TENANT"];
541
+ const envProject = process.env["BRAINBOX_PROJECT"];
542
+ if (envTenant && envProject) {
543
+ logger.error(
544
+ "error: BRAINBOX_TENANT and BRAINBOX_PROJECT are both set \u2014 mutually exclusive. Unset one, or pass --tenant/--project explicitly to override."
545
+ );
546
+ process.exit(1);
547
+ }
548
+ if (envTenant) return { tenant: envTenant };
549
+ return { project: envProject };
550
+ }
551
+ async function resolveConfig(options) {
552
+ let base = { org: "", project: "", apiUrl: DEFAULT_API_URL };
553
+ if (await brainboxDirExists()) {
554
+ try {
555
+ base = await readConfig();
556
+ } catch {
557
+ }
558
+ }
559
+ return {
560
+ org: options.org ?? base.org,
561
+ project: options.project ?? base.project,
562
+ apiUrl: options.apiUrl !== DEFAULT_API_URL ? options.apiUrl : base.apiUrl || DEFAULT_API_URL
563
+ };
564
+ }
565
+ async function resolveOrgAndProject(options, logger) {
566
+ const target = resolveTenantOrProject(options, logger);
567
+ const cfg = await resolveConfig({ ...options, project: target.project });
568
+ if (!cfg.org) {
569
+ logger.error("error: --org is required (or set BRAINBOX_ORG, or run bb repo init)");
570
+ process.exit(1);
571
+ }
572
+ if (!target.tenant && !cfg.project) {
573
+ logger.error("error: --project is required (or set BRAINBOX_PROJECT, or pass --tenant, or run bb repo init)");
574
+ process.exit(1);
575
+ }
576
+ const api = new BrainBoxApiClient(cfg.apiUrl, options.apiKey, logger);
577
+ let orgId;
578
+ let projectId;
579
+ try {
580
+ const org = await api.getOrCreateOrg(cfg.org);
581
+ orgId = org.id;
582
+ } catch (err) {
583
+ logger.error(`Failed to resolve org "${cfg.org}": ${err instanceof Error ? err.message : String(err)}`);
584
+ process.exit(1);
585
+ }
586
+ if (target.tenant) {
587
+ let tenant;
588
+ try {
589
+ tenant = await api.resolveTenant(orgId, target.tenant);
590
+ } catch (err) {
591
+ logger.error(`Failed to resolve tenant "${target.tenant}": ${err instanceof Error ? err.message : String(err)}`);
592
+ process.exit(1);
593
+ }
594
+ if (!tenant) {
595
+ logger.error(
596
+ `error: no tenant named "${target.tenant}" in this org \u2014 check the tenant name (not the project name), or omit --tenant to target a plain project`
597
+ );
598
+ process.exit(1);
599
+ }
600
+ projectId = tenant.projectId;
601
+ } else {
602
+ try {
603
+ const project = await api.getOrCreateProject(orgId, cfg.project);
604
+ projectId = project.id;
605
+ } catch (err) {
606
+ logger.error(`Failed to resolve project "${cfg.project}": ${err instanceof Error ? err.message : String(err)}`);
607
+ process.exit(1);
608
+ }
609
+ }
610
+ return { api, orgId, projectId, apiUrl: cfg.apiUrl };
611
+ }
612
+
613
+ // src/dbt-parser.ts
614
+ import * as fs4 from "fs/promises";
615
+ import * as nodePath2 from "path";
616
+ async function readOptionalJsonFile(filePath) {
617
+ let raw;
618
+ try {
619
+ raw = await fs4.readFile(filePath, "utf-8");
620
+ } catch (err) {
621
+ if (err.code === "ENOENT") return void 0;
622
+ throw err;
623
+ }
624
+ try {
625
+ return JSON.parse(raw);
626
+ } catch {
627
+ throw new Error(`${nodePath2.basename(filePath)} is not valid JSON \u2014 check the file at ${filePath}`);
628
+ }
629
+ }
630
+ async function readRequiredJsonFile(filePath) {
631
+ let raw;
632
+ try {
633
+ raw = await fs4.readFile(filePath, "utf-8");
634
+ } catch (err) {
635
+ if (err.code === "ENOENT") {
636
+ throw new Error(`manifest.json not found in ${nodePath2.dirname(filePath)} \u2014 run \`dbt docs generate\` first`);
637
+ }
638
+ throw err;
639
+ }
640
+ try {
641
+ return JSON.parse(raw);
642
+ } catch {
643
+ throw new Error(`${nodePath2.basename(filePath)} is not valid JSON \u2014 check the file at ${filePath}`);
644
+ }
645
+ }
646
+ async function readDbtArtifacts(dir) {
647
+ const resolved = nodePath2.resolve(dir);
648
+ const manifest = await readRequiredJsonFile(nodePath2.join(resolved, "manifest.json"));
649
+ const catalog = await readOptionalJsonFile(nodePath2.join(resolved, "catalog.json"));
650
+ const semanticManifest = await readOptionalJsonFile(nodePath2.join(resolved, "semantic_manifest.json"));
651
+ const result = { manifest };
652
+ if (catalog !== void 0) result.catalog = catalog;
653
+ if (semanticManifest !== void 0) result.semanticManifest = semanticManifest;
654
+ return result;
655
+ }
656
+ function countByResourceType(nodes, type) {
657
+ if (!nodes) return 0;
658
+ return Object.values(nodes).filter((n) => n.resource_type === type).length;
659
+ }
660
+ function objectSize(obj) {
661
+ if (!obj || typeof obj !== "object" || Array.isArray(obj)) return 0;
662
+ return Object.keys(obj).length;
663
+ }
664
+ function countMetrics(manifest, semanticManifest) {
665
+ let count = 0;
666
+ const m = manifest;
667
+ if (!m) return 0;
668
+ if (m["metrics"]) {
669
+ if (Array.isArray(m["metrics"])) {
670
+ count += m["metrics"].length;
671
+ } else {
672
+ count += objectSize(m["metrics"]);
673
+ }
674
+ }
675
+ if (m["semantic_models"] && typeof m["semantic_models"] === "object") {
676
+ for (const sm2 of Object.values(m["semantic_models"])) {
677
+ const measures = sm2["measures"];
678
+ if (Array.isArray(measures)) count += measures.length;
679
+ }
680
+ }
681
+ const sm = semanticManifest;
682
+ if (sm?.["metrics"] && Array.isArray(sm["metrics"])) {
683
+ count += sm["metrics"].length;
684
+ }
685
+ return count;
686
+ }
687
+ function summarizeDbtArtifacts(artifacts) {
688
+ if (!artifacts.manifest || typeof artifacts.manifest !== "object" || Array.isArray(artifacts.manifest)) {
689
+ return { models: 0, sources: 0, tests: 0, exposures: 0, metrics: 0, hasCatalog: false, hasSemanticManifest: false };
690
+ }
691
+ const m = artifacts.manifest;
692
+ const nodes = m["nodes"];
693
+ return {
694
+ models: countByResourceType(nodes, "model"),
695
+ sources: objectSize(m["sources"]),
696
+ tests: countByResourceType(nodes, "test"),
697
+ exposures: objectSize(m["exposures"]),
698
+ metrics: countMetrics(artifacts.manifest, artifacts.semanticManifest),
699
+ hasCatalog: artifacts.catalog !== void 0,
700
+ hasSemanticManifest: artifacts.semanticManifest !== void 0
701
+ };
702
+ }
703
+
704
+ // src/commands/meta.ts
705
+ import {
706
+ needsConversion,
707
+ convertToMarkdown,
708
+ convertedName,
709
+ connectAndProfile,
710
+ introspectDatabaseSchema,
711
+ parseProfileMode,
712
+ parseSkipColumns,
713
+ expandDocPatterns
714
+ } from "@brainbox-labs/sdk/ingest";
715
+ function inferDocType(filePath) {
716
+ const ext = nodePath3.extname(filePath).toLowerCase();
717
+ if (ext === ".md" || ext === ".markdown") return "markdown";
718
+ const binaryExtensions = /* @__PURE__ */ new Set([
719
+ ".png",
720
+ ".jpg",
721
+ ".jpeg",
722
+ ".gif",
723
+ ".bmp",
724
+ ".zip",
725
+ ".tar",
726
+ ".gz",
727
+ ".bz2",
728
+ ".7z",
729
+ ".exe",
730
+ ".dll",
731
+ ".so",
732
+ ".bin"
733
+ ]);
734
+ if (binaryExtensions.has(ext)) {
735
+ throw new Error(
736
+ `Unsupported binary file type "${ext}" for path "${filePath}". Convert to a text format or exclude from ingest.`
737
+ );
738
+ }
739
+ return "text";
740
+ }
741
+ function collect(value, previous) {
742
+ return [...previous ?? [], value];
743
+ }
744
+ async function loadMappings(patterns) {
745
+ const sources = [];
746
+ const seen = /* @__PURE__ */ new Map();
747
+ for (const pattern of patterns) {
748
+ let matched;
749
+ try {
750
+ matched = await expandDocPatterns([pattern]);
751
+ } catch (err) {
752
+ throw new Error(`Could not read mapping "${pattern}": ${err instanceof Error ? err.message : String(err)}`);
753
+ }
754
+ if (matched.length === 0) {
755
+ throw new Error(`No mapping file matched "${pattern}".`);
756
+ }
757
+ for (const source of matched) {
758
+ const previous = seen.get(source.name);
759
+ if (previous !== void 0) {
760
+ if (previous === source.content) continue;
761
+ throw new Error(
762
+ `Two different mapping files are both named "${source.name}" (matched via "${pattern}"). Mapping documents are identified by filename \u2014 rename one so both can be uploaded.`
763
+ );
764
+ }
765
+ seen.set(source.name, source.content);
766
+ sources.push(source);
767
+ }
768
+ }
769
+ return sources;
770
+ }
771
+ function detectDialectFromUrl(url) {
772
+ const lower = url.toLowerCase();
773
+ if (lower.startsWith("postgres://") || lower.startsWith("postgresql://")) return "postgres";
774
+ if (lower.startsWith("mysql://") || lower.startsWith("mysql2://")) return "mysql";
775
+ if (lower.startsWith("sqlite:") || lower.startsWith("sqlite3:")) return "sqlite";
776
+ if (lower.startsWith("bigquery://")) return "bigquery";
777
+ if (lower.startsWith("snowflake://")) return "snowflake";
778
+ if (lower.startsWith("duckdb://")) return "duckdb";
779
+ if (lower.startsWith("trino://") || lower.startsWith("trino+http")) return "trino";
780
+ if (lower.startsWith("presto://")) return "presto";
781
+ if (lower.startsWith("athena://") || lower.startsWith("awsathena://") || lower.startsWith("jdbc:awsathena")) return "athena";
782
+ return void 0;
783
+ }
784
+ async function requireBrainboxDir() {
785
+ if (!await brainboxDirExists()) {
786
+ console.error("error: no .brainbox/ directory found. Run `brainbox repo init` first.");
787
+ process.exit(1);
788
+ }
789
+ }
790
+ function createMetaCommand() {
791
+ const meta = new Command("meta").description("Stage data sources locally for context layer generation");
792
+ const ingest = new Command("ingest").description("Ingest a data source into .brainbox/staging/");
793
+ const ingestDb = addLogOptions(new Command("db")).description("Ingest a database schema (and optionally SQL files)").argument("<url>", "Postgres (postgres://) or Trino (trino://user[:password]@host[:port]/catalog[/schema]) connection string. Column profiling also accepts mysql://, sqlite:, or duckdb:// when --profile-data is set.").option("--sql <dir>", "Directory containing .sql query files").option("--sql-file <file>", "Single .sql file to parse").option("--tables <names>", "Comma-separated list of tables to include (default: all)").option("--mapping <path>", "ETL/column-mapping document describing how this schema was produced (repeatable; globs allowed). Sent with the schema so the server can derive column lineage.", collect).option("--profile-data [mode]", "Profile column data. Omit value for cardinality-only; use 'full' for enum values + JSON shapes").option("--skip-profile-columns <list>", "Comma-separated table.column pairs excluded from profiling (applies to both modes)").option("--profile-sample-rows <n>", "Max rows to sample per table during profiling (default: 10000)", "10000").option("--dialect <name>", "SQL dialect tag sent to the server (postgres, mysql, sqlite, bigquery, snowflake, duckdb, trino, athena, presto). Schema introspection supports Postgres and Trino; for other dialects this flag is a runtime hint when the schema came in via another path. When omitted, it is auto-detected from the URL scheme.").action(async (url, options) => {
794
+ await requireBrainboxDir();
795
+ const logger = createLogger(options.verbose, options.logFormat);
796
+ logger.info("Introspecting database schema...");
797
+ let schema;
798
+ try {
799
+ schema = await introspectDatabaseSchema(url);
800
+ } catch (err) {
801
+ logger.error(`Failed to introspect database: ${err instanceof Error ? err.message : String(err)}`);
802
+ process.exit(1);
803
+ }
804
+ if (options.tables !== void 0) {
805
+ const allowed = new Set(options.tables.split(",").map((t) => t.trim()));
806
+ schema.tables = schema.tables.filter((t) => allowed.has(t.name));
807
+ }
808
+ logger.info(`\u2713 Schema: ${schema.tables.length} table(s), ${schema.tables.reduce((n, t) => n + t.columns.length, 0)} column(s)`);
809
+ const profileMode = parseProfileMode(options.profileData);
810
+ if (profileMode !== null) {
811
+ const skipColumns = parseSkipColumns(options.skipProfileColumns);
812
+ const sampleRows = Math.max(1, parseInt(options.profileSampleRows, 10) || 1e4);
813
+ logger.info(`Profiling columns (mode=${profileMode}, sampleRows=${sampleRows})...`);
814
+ try {
815
+ schema = await connectAndProfile(url, schema, { mode: profileMode, sampleRows, skipColumns });
816
+ const profiledCount = schema.tables.reduce(
817
+ (n, t) => n + t.columns.filter((c) => c.profile !== void 0).length,
818
+ 0
819
+ );
820
+ logger.info(`\u2713 Profile: ${profiledCount} column(s) profiled`);
821
+ } catch (err) {
822
+ logger.warn(`Column profiling failed (proceeding without profiles): ${err instanceof Error ? err.message : String(err)}`);
823
+ }
824
+ }
825
+ let queries = [];
826
+ if (options.sql) {
827
+ try {
828
+ queries = await parseSqlDirectory(options.sql);
829
+ logger.info(`\u2713 SQL: ${queries.length} quer(ies) parsed from ${options.sql}`);
830
+ } catch (err) {
831
+ logger.warn(`Could not parse SQL directory: ${err instanceof Error ? err.message : String(err)}`);
832
+ }
833
+ } else if (options.sqlFile) {
834
+ try {
835
+ const content = await fs5.readFile(options.sqlFile, "utf-8");
836
+ const q = parseSqlFile(options.sqlFile, content);
837
+ queries = [q];
838
+ logger.info(`\u2713 SQL: 1 query parsed from ${options.sqlFile}`);
839
+ } catch (err) {
840
+ logger.warn(`Could not parse SQL file: ${err instanceof Error ? err.message : String(err)}`);
841
+ }
842
+ }
843
+ const rawDialect = options.dialect ?? detectDialectFromUrl(url);
844
+ const dialect = rawDialect?.trim().toLowerCase();
845
+ if (dialect) logger.info(`\u2713 Dialect: ${dialect}`);
846
+ let mappings = [];
847
+ const mappingPatterns = options.mapping ?? [];
848
+ if (mappingPatterns.length > 0) {
849
+ try {
850
+ mappings = await loadMappings(mappingPatterns);
851
+ } catch (err) {
852
+ logger.error(err instanceof Error ? err.message : String(err));
853
+ process.exit(1);
854
+ }
855
+ logger.info(`\u2713 Mappings: ${mappings.length} file(s) \u2014 ${mappings.map((m) => m.name).join(", ")}`);
856
+ }
857
+ const payload = {
858
+ schema,
859
+ queries,
860
+ ...dialect ? { dialect } : {},
861
+ ...mappings.length > 0 ? { mappings } : {}
862
+ };
863
+ await fs5.mkdir(nodePath3.dirname(dbStagingPath()), { recursive: true });
864
+ await fs5.writeFile(dbStagingPath(), JSON.stringify(payload, null, 2), "utf-8");
865
+ await upsertStagedSource({
866
+ type: "db",
867
+ path: "staging/db.json",
868
+ addedAt: (/* @__PURE__ */ new Date()).toISOString()
869
+ });
870
+ logger.info("\u2713 Staged to .brainbox/staging/db.json");
871
+ logger.info(" Run `brainbox repo commit` to snapshot, then `brainbox repo push` to upload.");
872
+ });
873
+ const ingestMcp = addLogOptions(new Command("mcp")).description("Ingest tools from an MCP server").argument("<url>", "MCP server URL").action(async (url, options) => {
874
+ await requireBrainboxDir();
875
+ const logger = createLogger(options.verbose, options.logFormat);
876
+ logger.info(`Introspecting MCP server at ${url}...`);
877
+ let tools;
878
+ try {
879
+ tools = await introspectMcpServer(url);
880
+ } catch (err) {
881
+ if (err instanceof BrainboxServerError) {
882
+ logger.error(`Cannot ingest a BrainBox-powered MCP server (circular definition).`);
883
+ process.exit(1);
884
+ }
885
+ logger.error(`Failed to introspect MCP server: ${err instanceof Error ? err.message : String(err)}`);
886
+ process.exit(1);
887
+ }
888
+ logger.info(`\u2713 MCP: ${tools.length} tool(s) found`);
889
+ await fs5.mkdir(nodePath3.dirname(mcpStagingPath()), { recursive: true });
890
+ await fs5.writeFile(mcpStagingPath(), JSON.stringify({ tools, serverUrl: url }, null, 2), "utf-8");
891
+ await upsertStagedSource({
892
+ type: "mcp",
893
+ path: "staging/mcp.json",
894
+ addedAt: (/* @__PURE__ */ new Date()).toISOString()
895
+ });
896
+ logger.info("\u2713 Staged to .brainbox/staging/mcp.json");
897
+ logger.info(" Run `brainbox repo commit` to snapshot, then `brainbox repo push` to upload.");
898
+ });
899
+ const ANALYSIS_DEPTHS = ["none", "shallow", "deep"];
900
+ const ingestDoc = addLogOptions(new Command("doc")).description("Ingest documents (md, txt, html, pdf, docx \u2014 pdf/docx/html auto-converted to markdown)").argument("<files...>", "Files to ingest").option(
901
+ "--analysis-depth <depth>",
902
+ `How deeply to analyse these documents (${ANALYSIS_DEPTHS.join("|")}). Falls back to 'shallow' when unset.`
903
+ ).action(async (files, options) => {
904
+ await requireBrainboxDir();
905
+ const logger = createLogger(options.verbose, options.logFormat);
906
+ let analysisDepth;
907
+ if (options.analysisDepth !== void 0) {
908
+ if (!ANALYSIS_DEPTHS.includes(options.analysisDepth)) {
909
+ logger.error(`Error: --analysis-depth must be one of: ${ANALYSIS_DEPTHS.join(", ")}`);
910
+ process.exit(1);
911
+ }
912
+ analysisDepth = options.analysisDepth;
913
+ }
914
+ const destDir = docStagingDir();
915
+ await fs5.mkdir(destDir, { recursive: true });
916
+ let copied = 0;
917
+ for (const file of files) {
918
+ const absPath = nodePath3.resolve(file);
919
+ try {
920
+ if (needsConversion(absPath)) {
921
+ logger.info(`Converting ${nodePath3.basename(absPath)} to markdown\u2026`);
922
+ const markdown = await convertToMarkdown(absPath);
923
+ const destName = convertedName(absPath);
924
+ const dest = nodePath3.join(destDir, destName);
925
+ await fs5.writeFile(dest, markdown, "utf-8");
926
+ await upsertStagedSource({
927
+ type: "doc",
928
+ path: `staging/files/${destName}`,
929
+ addedAt: (/* @__PURE__ */ new Date()).toISOString(),
930
+ ...analysisDepth && { analysisDepth }
931
+ });
932
+ logger.info(`\u2713 Staged: ${destName} (converted from ${nodePath3.basename(absPath)})`);
933
+ } else {
934
+ inferDocType(absPath);
935
+ const dest = nodePath3.join(destDir, nodePath3.basename(absPath));
936
+ await fs5.copyFile(absPath, dest);
937
+ await upsertStagedSource({
938
+ type: "doc",
939
+ path: `staging/files/${nodePath3.basename(absPath)}`,
940
+ addedAt: (/* @__PURE__ */ new Date()).toISOString(),
941
+ ...analysisDepth && { analysisDepth }
942
+ });
943
+ logger.info(`\u2713 Staged: ${nodePath3.basename(absPath)}`);
944
+ }
945
+ copied++;
946
+ } catch (err) {
947
+ logger.warn(`Skipping ${file}: ${err instanceof Error ? err.message : String(err)}`);
948
+ }
949
+ }
950
+ logger.info(`\u2713 ${copied} document(s) staged to .brainbox/staging/files/`);
951
+ logger.info(" Run `brainbox repo commit` to snapshot, then `brainbox repo push` to upload.");
952
+ });
953
+ const ingestNosql = addLogOptions(new Command("nosql")).description("Stage a NoSQL schema from a JSON file").argument("<file>", "Path to JSON file with { collections: NoSqlCollection[] }").action(async (file, options) => {
954
+ await requireBrainboxDir();
955
+ const logger = createLogger(options.verbose, options.logFormat);
956
+ let raw;
957
+ try {
958
+ raw = await fs5.readFile(file, "utf-8");
959
+ } catch {
960
+ logger.error(`Cannot read file: ${file}`);
961
+ process.exit(1);
962
+ }
963
+ let parsed;
964
+ try {
965
+ parsed = JSON.parse(raw);
966
+ } catch {
967
+ logger.error("File is not valid JSON.");
968
+ process.exit(1);
969
+ }
970
+ if (!Array.isArray(parsed.collections)) {
971
+ logger.error('JSON must have a top-level "collections" array.');
972
+ process.exit(1);
973
+ }
974
+ await fs5.mkdir(nodePath3.dirname(nosqlStagingPath()), { recursive: true });
975
+ await fs5.writeFile(nosqlStagingPath(), JSON.stringify(parsed, null, 2), "utf-8");
976
+ await upsertStagedSource({
977
+ type: "nosql",
978
+ path: "staging/nosql.json",
979
+ addedAt: (/* @__PURE__ */ new Date()).toISOString()
980
+ });
981
+ logger.info(`\u2713 ${parsed.collections.length} collection(s) staged to .brainbox/staging/nosql.json`);
982
+ logger.info(" Run `brainbox repo commit` then `brainbox repo push` to upload.");
983
+ });
984
+ const ingestDbt = addCommonOptions(new Command("dbt")).description("Upload a dbt connector draft directly to the API from pre-generated artifacts (manifest.json + optional catalog / semantic_manifest) \u2014 does not stage to .brainbox/staging/").option("--artifacts <dir>", "Directory containing manifest.json (+ optional catalog.json, semantic_manifest.json)").option("--git <url>", "Git URL \u2014 coming soon in v1.1").option("--underlying <connectorId>", "SQL connector ID to merge entity bindings with").option("--dry-run", "Summarise what would be uploaded without POSTing").action(async (options) => {
985
+ const logger = createLogger(options.verbose, options.logFormat);
986
+ if (options.git) {
987
+ logger.error("--git (server-side compile) is coming in v1.1 \u2014 use --artifacts with pre-generated artifacts for now.");
988
+ process.exit(1);
989
+ }
990
+ if (!options.artifacts) {
991
+ logger.error("error: --artifacts <dir> is required (run `dbt docs generate` first, then pass the target/ directory)");
992
+ process.exit(1);
993
+ }
994
+ logger.info(`Reading dbt artifacts from ${options.artifacts}...`);
995
+ let artifacts;
996
+ try {
997
+ artifacts = await readDbtArtifacts(options.artifacts);
998
+ } catch (err) {
999
+ logger.error(`Failed to read dbt artifacts: ${err instanceof Error ? err.message : String(err)}`);
1000
+ process.exit(1);
1001
+ }
1002
+ const summary = summarizeDbtArtifacts(artifacts);
1003
+ logger.info("dbt artifacts summary:");
1004
+ logger.info(` models: ${summary.models}`);
1005
+ logger.info(` sources: ${summary.sources}`);
1006
+ logger.info(` tests: ${summary.tests}`);
1007
+ logger.info(` exposures: ${summary.exposures}`);
1008
+ logger.info(` metrics: ${summary.metrics}`);
1009
+ if (summary.hasCatalog) logger.info(" catalog: \u2713");
1010
+ if (summary.hasSemanticManifest) logger.info(" semantic_manifest: \u2713");
1011
+ if (options.dryRun) {
1012
+ logger.info("\n--dry-run: nothing uploaded.");
1013
+ return;
1014
+ }
1015
+ const { api, orgId, projectId, apiUrl } = await resolveOrgAndProject(options, logger);
1016
+ const source = {
1017
+ kind: "artifacts",
1018
+ manifest: artifacts.manifest,
1019
+ ...artifacts.catalog !== void 0 ? { catalog: artifacts.catalog } : {},
1020
+ ...artifacts.semanticManifest !== void 0 ? { semanticManifest: artifacts.semanticManifest } : {}
1021
+ };
1022
+ logger.info(`Uploading dbt artifacts to ${apiUrl}...`);
1023
+ let result;
1024
+ try {
1025
+ result = await api.createDbtConnector(orgId, projectId, source, options.underlying);
1026
+ } catch (err) {
1027
+ logger.error(`Failed to create dbt connector: ${err instanceof Error ? err.message : String(err)}`);
1028
+ process.exit(1);
1029
+ }
1030
+ const uiBase = apiUrl.replace(/\/$/, "");
1031
+ logger.info(`\u2713 dbt connector created (id: ${result.id})`);
1032
+ logger.info(` Review at: ${uiBase}/orgs/${orgId}/projects/${projectId}/connectors/${result.id}`);
1033
+ });
1034
+ const ingestSkill = addCommonOptions(new Command("skill")).description("Merge one or more files into an Agent Skill and upload it directly (text, markdown, html, pdf, docx) \u2014 does not stage to .brainbox/staging/").argument("<name>", "Skill name").argument("<files...>", "Files to merge into the skill").requiredOption("--description <text>", "Skill description (used for skill discovery/routing)").action(async (name, files, options) => {
1035
+ const logger = createLogger(options.verbose, options.logFormat);
1036
+ logger.info(`Reading ${files.length} file(s) for skill "${name}"...`);
1037
+ let sources;
1038
+ try {
1039
+ sources = await expandDocPatterns(files);
1040
+ } catch (err) {
1041
+ logger.error(`Failed to read skill sources: ${err instanceof Error ? err.message : String(err)}`);
1042
+ process.exit(1);
1043
+ }
1044
+ const { api, orgId, projectId, apiUrl } = await resolveOrgAndProject(options, logger);
1045
+ logger.info(`Uploading skill "${name}" (${sources.length} source(s)) to ${apiUrl}...`);
1046
+ let result;
1047
+ try {
1048
+ result = await api.createSkillConnector(orgId, projectId, name, options.description, sources);
1049
+ } catch (err) {
1050
+ logger.error(`Failed to create skill connector: ${err instanceof Error ? err.message : String(err)}`);
1051
+ process.exit(1);
1052
+ }
1053
+ logger.info(`\u2713 Skill "${name}" created (connector: ${result.connectorDraftId})`);
1054
+ logger.info(" Skill connectors resolve synchronously \u2014 no `repo meta create`/`approve` step is needed.");
1055
+ });
1056
+ ingest.addCommand(ingestDb);
1057
+ ingest.addCommand(ingestMcp);
1058
+ ingest.addCommand(ingestNosql);
1059
+ ingest.addCommand(ingestDoc);
1060
+ ingest.addCommand(ingestDbt);
1061
+ ingest.addCommand(ingestSkill);
1062
+ meta.addCommand(ingest);
1063
+ return meta;
1064
+ }
1065
+
1066
+ // src/commands/repo.ts
1067
+ import { Command as Command2 } from "commander";
1068
+ import * as readline from "readline";
1069
+
1070
+ // src/commands/repo-service.ts
1071
+ import * as fs6 from "fs/promises";
1072
+ import * as nodePath4 from "path";
1073
+ import * as os2 from "os";
1074
+ import { spawn } from "child_process";
1075
+ async function commitStaged(message, logger) {
1076
+ const manifest = await readStagingManifest();
1077
+ if (manifest.sources.length === 0) {
1078
+ logger.error("Nothing staged. Run `brainbox meta ingest` first.");
1079
+ process.exit(1);
1080
+ }
1081
+ const sha = await computeStagingSha();
1082
+ const commit = {
1083
+ sha,
1084
+ message,
1085
+ timestamp: (/* @__PURE__ */ new Date()).toISOString(),
1086
+ sources: manifest.sources,
1087
+ contentHash: sha
1088
+ };
1089
+ await writeCommit(commit);
1090
+ return commit;
1091
+ }
1092
+ async function pushCommit(api, orgId, projectId, logger, defaultAnalysisDepth) {
1093
+ const sha = await readHead();
1094
+ if (!sha) {
1095
+ logger.error("Nothing committed. Run `brainbox repo commit` first.");
1096
+ process.exit(1);
1097
+ }
1098
+ const commit = await readCommit(sha);
1099
+ if (!commit) {
1100
+ logger.error(`Commit ${sha} not found in .brainbox/commits/`);
1101
+ process.exit(1);
1102
+ }
1103
+ const pushState = await readPushState();
1104
+ if (pushState?.sha === sha && pushState?.connectorDraftId) {
1105
+ logger.info(`Already pushed (connector draft: ${pushState.connectorDraftId}). Use --force on meta create to re-run LLM.`);
1106
+ return { connectorDraftId: pushState.connectorDraftId, sha };
1107
+ }
1108
+ const currentSha = await computeStagingSha();
1109
+ if (currentSha !== commit.contentHash) {
1110
+ logger.error(
1111
+ `Staging has changed since last commit (committed ${commit.contentHash}, current ${currentSha}). Run \`brainbox repo commit\` to snapshot the new state before pushing.`
1112
+ );
1113
+ process.exit(1);
1114
+ }
1115
+ let connectorDraftId;
1116
+ const hasDb = commit.sources.some((s) => s.type === "db");
1117
+ const hasMcp = commit.sources.some((s) => s.type === "mcp");
1118
+ const hasNosql = commit.sources.some((s) => s.type === "nosql");
1119
+ const hasDocs = commit.sources.some((s) => s.type === "doc");
1120
+ if (hasDb) {
1121
+ logger.info(" Uploading database schema...");
1122
+ const raw = await fs6.readFile(dbStagingPath(), "utf-8");
1123
+ const { schema, queries, dialect, mappings } = JSON.parse(raw);
1124
+ if (mappings?.length) logger.info(` Including ${mappings.length} mapping document(s)...`);
1125
+ const connector = await api.createSqlConnector(orgId, projectId, schema, queries, dialect, mappings);
1126
+ connectorDraftId = connector.id;
1127
+ logger.info(` \u2713 SQL connector draft: ${connector.id}${dialect ? ` (dialect: ${dialect})` : ""}`);
1128
+ }
1129
+ if (hasMcp) {
1130
+ logger.info(" Uploading MCP tools...");
1131
+ const raw = await fs6.readFile(mcpStagingPath(), "utf-8");
1132
+ const { tools, serverUrl } = JSON.parse(raw);
1133
+ const connector = await api.createMcpConnector(orgId, projectId, tools, serverUrl);
1134
+ connectorDraftId = connector.id;
1135
+ logger.info(` \u2713 MCP connector draft: ${connector.id}`);
1136
+ }
1137
+ if (hasNosql) {
1138
+ logger.info(" Uploading NoSQL schema...");
1139
+ const raw = await fs6.readFile(nosqlStagingPath(), "utf-8");
1140
+ const { collections } = JSON.parse(raw);
1141
+ const connector = await api.createNoSqlConnector(orgId, projectId, collections);
1142
+ connectorDraftId = connector.id;
1143
+ logger.info(` \u2713 NoSQL connector draft: ${connector.id}`);
1144
+ }
1145
+ if (hasDocs) {
1146
+ logger.info(" Uploading documents...");
1147
+ const docSources = commit.sources.filter((s) => s.type === "doc");
1148
+ const sources = [];
1149
+ for (const staged of docSources) {
1150
+ const absPath = nodePath4.join(brainboxDir(), staged.path);
1151
+ const content = await fs6.readFile(absPath, "utf-8");
1152
+ const file = nodePath4.basename(staged.path);
1153
+ const ext = nodePath4.extname(file).toLowerCase();
1154
+ const type = ext === ".md" || ext === ".markdown" ? "markdown" : ext === ".html" || ext === ".htm" ? "html" : "text";
1155
+ sources.push({ id: file, name: file, content, type, ...staged.analysisDepth && { analysisDepth: staged.analysisDepth } });
1156
+ }
1157
+ const connector = await api.createDocsConnector(orgId, projectId, sources, void 0, defaultAnalysisDepth);
1158
+ connectorDraftId = connector.id;
1159
+ logger.info(` \u2713 Docs connector draft: ${connector.id}`);
1160
+ }
1161
+ if (!connectorDraftId) {
1162
+ logger.error("No supported source types in commit (db, mcp, nosql, doc).");
1163
+ process.exit(1);
1164
+ }
1165
+ await writePushState({ sha, connectorDraftId, pushedAt: (/* @__PURE__ */ new Date()).toISOString() });
1166
+ try {
1167
+ await clearStagingManifest();
1168
+ } catch {
1169
+ logger.info(" Warning: push succeeded but could not clear staging manifest (disk issue?).");
1170
+ }
1171
+ return { connectorDraftId, sha };
1172
+ }
1173
+ async function pullActiveLayer(api, orgId, projectId, outPath, logger) {
1174
+ let layer;
1175
+ let isV2 = false;
1176
+ try {
1177
+ layer = await api.getActiveLayer(orgId, projectId);
1178
+ } catch (err) {
1179
+ if (!isNotFoundError(err)) throw err;
1180
+ try {
1181
+ layer = await api.getDomainModel(orgId, projectId);
1182
+ isV2 = true;
1183
+ } catch (dmErr) {
1184
+ const isDomainModel404 = isNotFoundError(dmErr);
1185
+ if (!isDomainModel404) throw dmErr;
1186
+ const pushState = await readPushState();
1187
+ if (!pushState?.contextId) {
1188
+ throw new Error(
1189
+ "No active layer found. Run `brainbox repo meta create` and `brainbox repo meta approve` first."
1190
+ );
1191
+ }
1192
+ layer = await api.getContext(orgId, projectId, pushState.contextId);
1193
+ }
1194
+ }
1195
+ const dest = outPath ?? activeLayerPath();
1196
+ await fs6.writeFile(dest, JSON.stringify(layer, null, 2), "utf-8");
1197
+ if (isV2) {
1198
+ logger?.info(`\u2713 Domain Model saved to ${dest}`);
1199
+ } else {
1200
+ logger?.info(`\u2713 Active layer saved to ${dest}`);
1201
+ }
1202
+ return dest;
1203
+ }
1204
+ async function buildLog(api, orgId, projectId) {
1205
+ const entries = [];
1206
+ const localCommits = await listLocalCommits();
1207
+ const head = await readHead();
1208
+ for (const c of localCommits) {
1209
+ entries.push({
1210
+ sha: c.sha,
1211
+ timestamp: c.timestamp,
1212
+ message: c.message,
1213
+ isHead: c.sha === head,
1214
+ source: "local"
1215
+ });
1216
+ }
1217
+ const layers = await api.listLayers(orgId, projectId);
1218
+ let activeVersion;
1219
+ try {
1220
+ const active = await api.getActiveLayer(orgId, projectId);
1221
+ activeVersion = active.version;
1222
+ } catch {
1223
+ }
1224
+ for (const layer of layers) {
1225
+ entries.push({
1226
+ version: layer.version,
1227
+ timestamp: layer.createdAt ?? "",
1228
+ origin: layer.origin,
1229
+ isActive: layer.version === activeVersion,
1230
+ source: "remote"
1231
+ });
1232
+ }
1233
+ return entries;
1234
+ }
1235
+ async function metaCreate(api, orgId, projectId, logger, modelVersion = "v2", force = false, draftId) {
1236
+ const pushState = await readPushState();
1237
+ const connectorDraftId = draftId ?? pushState?.connectorDraftId;
1238
+ if (!connectorDraftId) {
1239
+ logger.error("No pushed draft found. Run `brainbox repo push` first, or pass --draft-id.");
1240
+ process.exit(1);
1241
+ }
1242
+ const isOverride = !!draftId && draftId !== pushState?.connectorDraftId;
1243
+ if (!isOverride && pushState?.contextId && !force) {
1244
+ logger.error(
1245
+ `A context was already created from this draft (${pushState.contextId}). Run \`brainbox repo meta approve\` to publish it, or pass --force to create a new one.`
1246
+ );
1247
+ process.exit(1);
1248
+ }
1249
+ if (isOverride) {
1250
+ logger.info(`Using specified draft: ${connectorDraftId}`);
1251
+ }
1252
+ const body = { connectorDraftId, modelVersion, ...force && { force } };
1253
+ const ctx = await api.createContext(orgId, projectId, body);
1254
+ if (!isOverride) {
1255
+ await writePushState({ ...pushState, contextId: ctx.contextId, metaCreatedAt: (/* @__PURE__ */ new Date()).toISOString() });
1256
+ } else {
1257
+ logger.warn(
1258
+ `push-state.json was not updated (--draft-id override). To publish, run: brainbox repo meta approve ${ctx.contextId}` + (pushState?.contextId ? ` (not ${pushState.contextId})` : "")
1259
+ );
1260
+ }
1261
+ return { contextId: ctx.contextId };
1262
+ }
1263
+ async function metaApprove(api, orgId, projectId, contextId, logger) {
1264
+ let resolvedId = contextId;
1265
+ if (!resolvedId) {
1266
+ const pushState = await readPushState();
1267
+ resolvedId = pushState?.contextId;
1268
+ }
1269
+ if (!resolvedId) {
1270
+ logger.error("No context ID found. Run `brainbox repo meta create` first, or pass a context ID.");
1271
+ process.exit(1);
1272
+ }
1273
+ const ctx = await api.getContext(orgId, projectId, resolvedId);
1274
+ const rawVersion = ctx.modelVersion;
1275
+ const modelVersion = rawVersion === "v2" ? "v2" : "v1";
1276
+ if (ctx.status === "active") {
1277
+ return { id: ctx.layerId ?? ctx.id, version: ctx.version, modelVersion, alreadyActive: true };
1278
+ }
1279
+ const result = await api.activateContext(orgId, projectId, resolvedId);
1280
+ return { ...result, modelVersion };
1281
+ }
1282
+ async function repoStatus() {
1283
+ const cfg = await readConfig();
1284
+ const manifest = await readStagingManifest();
1285
+ const head = await readHead();
1286
+ const headCommit = head ? await readCommit(head) : null;
1287
+ const pushState = await readPushState();
1288
+ const pushed = !!(pushState && head && pushState.sha === head);
1289
+ return {
1290
+ org: cfg.org,
1291
+ project: cfg.project,
1292
+ stagedSources: manifest.sources,
1293
+ head,
1294
+ headCommit,
1295
+ pushed,
1296
+ pushedAt: pushState?.pushedAt,
1297
+ connectorDraftId: pushState?.connectorDraftId,
1298
+ contextId: pushState?.contextId,
1299
+ metaCreatedAt: pushState?.metaCreatedAt
1300
+ };
1301
+ }
1302
+ async function metaStatus(api, orgId, projectId, contextId, logger) {
1303
+ let resolvedId = contextId;
1304
+ if (!resolvedId) {
1305
+ const pushState = await readPushState();
1306
+ resolvedId = pushState?.contextId;
1307
+ }
1308
+ if (!resolvedId) {
1309
+ logger.error("No context ID found. Run `brainbox repo meta create` first, or pass a context ID.");
1310
+ process.exit(1);
1311
+ }
1312
+ const ctx = await api.getContext(orgId, projectId, resolvedId);
1313
+ const modelVersion = ctx.modelVersion === "v2" ? "v2" : "v1";
1314
+ return { contextId: resolvedId, status: ctx.status, version: ctx.version, modelVersion };
1315
+ }
1316
+ async function metaCurate(api, orgId, projectId, contextId, filePath, logger) {
1317
+ let resolvedId = contextId;
1318
+ if (!resolvedId) {
1319
+ const pushState = await readPushState();
1320
+ resolvedId = pushState?.contextId;
1321
+ }
1322
+ if (!resolvedId) {
1323
+ logger.error("No context ID found. Run `brainbox repo meta create` first, or pass a context ID.");
1324
+ process.exit(1);
1325
+ }
1326
+ const ctx = await api.getContext(orgId, projectId, resolvedId);
1327
+ const isV2 = ctx.modelVersion === "v2";
1328
+ const currentValue = isV2 ? ctx.proposal ?? {} : ctx.generated ?? {};
1329
+ let editedValue;
1330
+ if (filePath) {
1331
+ let raw;
1332
+ try {
1333
+ raw = await fs6.readFile(filePath, "utf-8");
1334
+ } catch {
1335
+ logger.error(`Cannot read file: ${filePath}`);
1336
+ process.exit(1);
1337
+ }
1338
+ try {
1339
+ editedValue = JSON.parse(raw);
1340
+ } catch {
1341
+ logger.error("File is not valid JSON.");
1342
+ process.exit(1);
1343
+ }
1344
+ } else {
1345
+ const safeId = resolvedId.replace(/[^a-zA-Z0-9_-]/g, "_");
1346
+ const tmpFile = nodePath4.join(os2.tmpdir(), `brainbox-curate-${safeId}.json`);
1347
+ await fs6.writeFile(tmpFile, JSON.stringify(currentValue, null, 2), "utf-8");
1348
+ try {
1349
+ await openInEditor(tmpFile, logger);
1350
+ const raw = await fs6.readFile(tmpFile, "utf-8");
1351
+ try {
1352
+ editedValue = JSON.parse(raw);
1353
+ } catch {
1354
+ logger.error("Editor output is not valid JSON. Aborting.");
1355
+ process.exit(1);
1356
+ }
1357
+ } finally {
1358
+ await fs6.unlink(tmpFile).catch(() => {
1359
+ });
1360
+ }
1361
+ }
1362
+ const patch = isV2 ? { proposal: editedValue } : { generated: editedValue };
1363
+ await api.curateContext(orgId, projectId, resolvedId, patch);
1364
+ }
1365
+ async function openInEditor(filePath, logger) {
1366
+ const editorEnv = process.env["EDITOR"] ?? process.env["VISUAL"] ?? "vi";
1367
+ const [bin, ...editorArgs] = editorEnv.split(/\s+/);
1368
+ logger.info(`Opening ${filePath} in ${editorEnv}\u2026`);
1369
+ await new Promise((resolve4, reject) => {
1370
+ const child = spawn(bin, [...editorArgs, filePath], { stdio: "inherit" });
1371
+ child.on(
1372
+ "exit",
1373
+ (code) => code === 0 ? resolve4() : reject(new Error(`Editor exited with code ${code}`))
1374
+ );
1375
+ child.on("error", reject);
1376
+ });
1377
+ }
1378
+
1379
+ // src/commands/repo.ts
1380
+ async function requireBrainboxDir2() {
1381
+ if (!await brainboxDirExists()) {
1382
+ console.error("error: no .brainbox/ directory found. Run `brainbox repo init` first.");
1383
+ process.exit(1);
1384
+ }
1385
+ }
1386
+ function prompt(question) {
1387
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
1388
+ return new Promise((resolve4) => {
1389
+ rl.question(question, (answer) => {
1390
+ rl.close();
1391
+ resolve4(answer);
1392
+ });
1393
+ });
1394
+ }
1395
+ function createRepoCommand() {
1396
+ const repo = new Command2("repo").description("Manage context layer versions (git-inspired)");
1397
+ repo.addCommand(
1398
+ addCommonOptions(new Command2("init")).description("Create .brainbox/ config in the current directory").action(async (options) => {
1399
+ const logger = createLogger(options.verbose, options.logFormat);
1400
+ if (await brainboxDirExists()) logger.info(".brainbox/ already exists \u2014 updating config.");
1401
+ let org = options.org ?? "";
1402
+ let project = options.project ?? "";
1403
+ if (!org) org = await prompt("Organization name: ");
1404
+ if (!project) project = await prompt("Project name: ");
1405
+ if (!org || !project) {
1406
+ logger.error("Organization and project are required.");
1407
+ process.exit(1);
1408
+ }
1409
+ await initBrainboxDir({ org, project, apiUrl: options.apiUrl });
1410
+ logger.info("\u2713 .brainbox/ initialised");
1411
+ logger.info(" config.json is safe to commit. All other .brainbox/ files are gitignored.");
1412
+ })
1413
+ );
1414
+ repo.addCommand(
1415
+ addCommonOptions(new Command2("clone")).description("Fetch project config from API into .brainbox/").argument("<project>", "Project name").action(async (projectArg, options) => {
1416
+ const logger = createLogger(options.verbose, options.logFormat);
1417
+ if (!options.org) {
1418
+ logger.error("error: --org is required (or set BRAINBOX_ORG)");
1419
+ process.exit(1);
1420
+ }
1421
+ const api = new BrainBoxApiClient(options.apiUrl, options.apiKey, logger);
1422
+ let orgObj;
1423
+ try {
1424
+ orgObj = await api.getOrg(options.org);
1425
+ } catch (err) {
1426
+ logger.error(`Org not found: ${err instanceof Error ? err.message : String(err)}`);
1427
+ process.exit(1);
1428
+ }
1429
+ let projectObj;
1430
+ try {
1431
+ projectObj = await api.getProject(orgObj.id, projectArg);
1432
+ } catch (err) {
1433
+ logger.error(`Project not found: ${err instanceof Error ? err.message : String(err)}`);
1434
+ process.exit(1);
1435
+ }
1436
+ await initBrainboxDir({ org: orgObj.name, project: projectObj.name, apiUrl: options.apiUrl });
1437
+ logger.info(`\u2713 Cloned project "${projectObj.name}" from org "${orgObj.name}"`);
1438
+ logger.info(" Run `brainbox repo pull` to download the active layer.");
1439
+ })
1440
+ );
1441
+ repo.addCommand(
1442
+ addLogOptions(new Command2("commit")).description("Snapshot staged sources as a local commit").option("-m, --message <message>", "Commit message").action(async (options) => {
1443
+ await requireBrainboxDir2();
1444
+ const logger = createLogger(options.verbose, options.logFormat);
1445
+ const message = options.message ?? `snapshot ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
1446
+ const commit = await commitStaged(message, logger);
1447
+ logger.info(`\u2713 Committed [${commit.sha}] ${commit.message}`);
1448
+ logger.info(` ${commit.sources.length} source(s): ${commit.sources.map((s) => s.type).join(", ")}`);
1449
+ logger.info(" Run `brainbox repo push` to upload to the server.");
1450
+ })
1451
+ );
1452
+ const ANALYSIS_DEPTHS = ["none", "shallow", "deep"];
1453
+ repo.addCommand(
1454
+ addCommonOptions(new Command2("push")).description("Upload the latest commit to the server (data sync \u2014 no LLM triggered)").option(
1455
+ "--default-analysis-depth <depth>",
1456
+ `Default doc analysis depth for staged docs that didn't set their own (${ANALYSIS_DEPTHS.join("|")})`
1457
+ ).action(async (options) => {
1458
+ await requireBrainboxDir2();
1459
+ const logger = createLogger(options.verbose, options.logFormat);
1460
+ let defaultAnalysisDepth;
1461
+ if (options.defaultAnalysisDepth !== void 0) {
1462
+ if (!ANALYSIS_DEPTHS.includes(options.defaultAnalysisDepth)) {
1463
+ logger.error(`Error: --default-analysis-depth must be one of: ${ANALYSIS_DEPTHS.join(", ")}`);
1464
+ process.exit(1);
1465
+ }
1466
+ defaultAnalysisDepth = options.defaultAnalysisDepth;
1467
+ }
1468
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1469
+ const result = await pushCommit(api, orgId, projectId, logger, defaultAnalysisDepth);
1470
+ logger.info(`\u2713 Pushed \u2014 connector draft: ${result.connectorDraftId}`);
1471
+ logger.info(" Run `brainbox repo meta create` to trigger LLM generation and create a review.");
1472
+ })
1473
+ );
1474
+ repo.addCommand(
1475
+ addCommonOptions(new Command2("pull")).description("Download the current active layer locally").option("--out <file>", "Output file path (default: .brainbox/active-layer.json)").action(async (options) => {
1476
+ await requireBrainboxDir2();
1477
+ const logger = createLogger(options.verbose, options.logFormat);
1478
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1479
+ await pullActiveLayer(api, orgId, projectId, options.out, logger);
1480
+ logger.info(" Run `brainbox dev start` to serve it locally as an MCP server.");
1481
+ })
1482
+ );
1483
+ repo.addCommand(
1484
+ addCommonOptions(new Command2("log")).description("Show local commit history and remote version history").action(async (options) => {
1485
+ const logger = createLogger(options.verbose, options.logFormat);
1486
+ if (await brainboxDirExists()) {
1487
+ const commits = await listLocalCommits();
1488
+ const head = await readHead();
1489
+ if (commits.length > 0) {
1490
+ console.log("\nLocal commits:");
1491
+ for (const c of commits) {
1492
+ const marker = c.sha === head ? " \u2190 HEAD" : "";
1493
+ console.log(` [${c.sha}] ${c.timestamp.slice(0, 16)} ${c.message}${marker}`);
1494
+ }
1495
+ } else {
1496
+ console.log("\nNo local commits yet.");
1497
+ }
1498
+ }
1499
+ const cfg = await resolveConfig(options);
1500
+ if (!cfg.org || !cfg.project) {
1501
+ console.log("\n(Pass --org and --project to see remote version history)");
1502
+ return;
1503
+ }
1504
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1505
+ try {
1506
+ const entries = await buildLog(api, orgId, projectId);
1507
+ const remoteEntries = entries.filter((e) => e.source === "remote");
1508
+ console.log("\nRemote versions:");
1509
+ if (remoteEntries.length === 0) {
1510
+ console.log(" (none)");
1511
+ } else {
1512
+ for (const e of remoteEntries) {
1513
+ const activeMarker = e.isActive ? " \u2190 active" : "";
1514
+ const origin = e.origin ? ` [${e.origin}]` : "";
1515
+ console.log(` v${e.version} ${e.timestamp.slice(0, 16)}${origin}${activeMarker}`);
1516
+ }
1517
+ }
1518
+ } catch (err) {
1519
+ logger.warn(`Could not fetch remote history: ${err instanceof Error ? err.message : String(err)}`);
1520
+ }
1521
+ console.log("");
1522
+ })
1523
+ );
1524
+ repo.addCommand(
1525
+ addLogOptions(new Command2("status")).description("Show local staging, commit, and push state").action(async (options) => {
1526
+ createLogger(options.verbose, options.logFormat);
1527
+ if (!await brainboxDirExists()) {
1528
+ console.log("Not initialised. Run `brainbox repo init` first.");
1529
+ process.exit(1);
1530
+ }
1531
+ let status;
1532
+ try {
1533
+ status = await repoStatus();
1534
+ } catch {
1535
+ console.log("No config found. Run `brainbox repo init` to set up org and project.");
1536
+ process.exit(1);
1537
+ }
1538
+ console.log(`
1539
+ Project: ${status.org} / ${status.project}`);
1540
+ if (status.stagedSources.length === 0) {
1541
+ console.log("\nStaged sources:\n (none \u2014 run `brainbox meta ingest` to add sources)");
1542
+ } else {
1543
+ console.log("\nStaged sources:");
1544
+ for (const s of status.stagedSources) {
1545
+ console.log(` ${s.type.padEnd(4)} ${s.path}`);
1546
+ }
1547
+ }
1548
+ if (!status.head) {
1549
+ console.log("\nNo local commits yet. Run `brainbox repo commit` to snapshot staged sources.");
1550
+ } else {
1551
+ if (status.headCommit) {
1552
+ console.log(`
1553
+ Last commit: [${status.headCommit.sha}] ${status.headCommit.timestamp.slice(0, 16)} ${status.headCommit.message}`);
1554
+ }
1555
+ if (!status.pushed) {
1556
+ console.log(" Not yet pushed. Run `brainbox repo push` to upload to the server.");
1557
+ } else {
1558
+ console.log(` Pushed at ${(status.pushedAt ?? "").slice(0, 16)} connector draft: ${status.connectorDraftId ?? "(none)"}`);
1559
+ if (status.contextId) {
1560
+ console.log(` Context: ${status.contextId}${status.metaCreatedAt ? ` (created ${status.metaCreatedAt.slice(0, 16)})` : ""}`);
1561
+ } else {
1562
+ console.log(" No context yet. Run `brainbox repo meta create` to trigger generation.");
1563
+ }
1564
+ }
1565
+ }
1566
+ console.log("");
1567
+ })
1568
+ );
1569
+ const metaSub = new Command2("meta").description("Manage context layer review requests (PR equivalent)");
1570
+ metaSub.addCommand(
1571
+ addCommonOptions(new Command2("create")).description("Trigger LLM generation from the pushed draft \u2014 creates a Domain Model review request").option("-m, --message <message>", "Description for this context layer").option("--v1", "Use the legacy semantic/knowledge layer (v1) instead of Domain Model (v2)").option("--force", "Create a new context even if one already exists for this draft").option("--draft-id <id>", "Connector draft ID to regenerate from (overrides the last pushed draft)").action(async (options) => {
1572
+ await requireBrainboxDir2();
1573
+ const logger = createLogger(options.verbose, options.logFormat);
1574
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1575
+ const modelVersion = options.v1 ? "v1" : "v2";
1576
+ const { contextId } = await metaCreate(api, orgId, projectId, logger, modelVersion, options.force, options.draftId);
1577
+ const cfg = await resolveConfig(options);
1578
+ const uiBase = cfg.apiUrl.replace(/\/$/, "");
1579
+ logger.info(`\u2713 Context generation started (id: ${contextId})`);
1580
+ if (modelVersion === "v2") {
1581
+ logger.info(" Building Domain Model (v2) \u2014 entities, relationships, vocabulary, rules, processes.");
1582
+ }
1583
+ logger.info(` Review at: ${uiBase}/orgs/${orgId}/projects/${projectId}/curate`);
1584
+ if (options.draftId) {
1585
+ logger.info(` Once reviewed, run \`brainbox repo meta approve ${contextId}\` to publish.`);
1586
+ } else {
1587
+ logger.info(" Once reviewed, run `brainbox repo meta approve` to publish.");
1588
+ }
1589
+ })
1590
+ );
1591
+ metaSub.addCommand(
1592
+ addCommonOptions(new Command2("status")).description("Show the status of a context generation request").argument("[contextId]", "Context ID to check (default: last created)").action(async (contextId, options) => {
1593
+ await requireBrainboxDir2();
1594
+ const logger = createLogger(options.verbose, options.logFormat);
1595
+ const { api, orgId, projectId, apiUrl } = await resolveOrgAndProject(options, logger);
1596
+ let result;
1597
+ try {
1598
+ result = await metaStatus(api, orgId, projectId, contextId, logger);
1599
+ } catch (err) {
1600
+ const msg = err instanceof Error ? err.message : String(err);
1601
+ if (isNotFoundError(err)) {
1602
+ logger.error("Context not found on server. It may have expired or been deleted.");
1603
+ } else {
1604
+ logger.error(`Failed to fetch context status: ${msg}`);
1605
+ }
1606
+ process.exit(1);
1607
+ }
1608
+ const reviewUrl = `${apiUrl.replace(/\/$/, "")}/orgs/${orgId}/projects/${projectId}/curate`;
1609
+ console.log(`
1610
+ Context: ${result.contextId}`);
1611
+ const isV2 = result.modelVersion === "v2";
1612
+ switch (result.status) {
1613
+ case "ready":
1614
+ if (isV2) {
1615
+ console.log("Status: ready (Domain Model proposal ready for review)");
1616
+ console.log(` Review at: ${reviewUrl}`);
1617
+ console.log(" Run `brainbox repo meta approve` to merge into the Domain Model.");
1618
+ } else {
1619
+ console.log("Status: ready (review complete \u2014 awaiting approval)");
1620
+ console.log(` Review at: ${reviewUrl}`);
1621
+ console.log(" Run `brainbox repo meta approve` to publish.");
1622
+ }
1623
+ break;
1624
+ case "active":
1625
+ if (isV2) {
1626
+ console.log(`Status: active \u2192 Domain Model updated${result.version != null ? ` (v${result.version})` : ""}`);
1627
+ } else {
1628
+ console.log(`Status: active \u2192 published${result.version != null ? ` as v${result.version}` : ""}`);
1629
+ console.log(" Run `brainbox repo pull` to download the active layer.");
1630
+ }
1631
+ break;
1632
+ case "failed":
1633
+ console.log("Status: failed");
1634
+ console.log(` Review at: ${reviewUrl}`);
1635
+ break;
1636
+ default:
1637
+ if (isV2) {
1638
+ console.log(`Status: ${result.status} (Domain Model proposal in progress\u2026)`);
1639
+ } else {
1640
+ console.log(`Status: ${result.status} (LLM generation in progress\u2026)`);
1641
+ }
1642
+ console.log(" Run this command again to check for updates.");
1643
+ }
1644
+ console.log("");
1645
+ })
1646
+ );
1647
+ metaSub.addCommand(
1648
+ addCommonOptions(new Command2("curate")).description("Edit the generated output (v1) or Domain Model proposal (v2) before approving").argument("[contextId]", "Context ID to edit (default: last created)").option("--file <path>", "JSON file to apply as the curated output (skips interactive editor; edits generated for v1, proposal for v2)").action(async (contextId, options) => {
1649
+ await requireBrainboxDir2();
1650
+ const logger = createLogger(options.verbose, options.logFormat);
1651
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1652
+ try {
1653
+ await metaCurate(api, orgId, projectId, contextId, options.file, logger);
1654
+ } catch (err) {
1655
+ logger.error(`Curate failed: ${err instanceof Error ? err.message : String(err)}`);
1656
+ process.exit(1);
1657
+ }
1658
+ logger.info("\u2713 Context updated.");
1659
+ logger.info(" Run `brainbox repo meta approve` to publish.");
1660
+ })
1661
+ );
1662
+ metaSub.addCommand(
1663
+ addCommonOptions(new Command2("approve")).description("Approve a context review request \u2192 publishes as a new versioned layer (v1) or merges into the Domain Model (v2)").argument("[contextId]", "Context ID to approve (default: last created)").action(async (contextId, options) => {
1664
+ await requireBrainboxDir2();
1665
+ const logger = createLogger(options.verbose, options.logFormat);
1666
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
1667
+ const result = await metaApprove(api, orgId, projectId, contextId, logger);
1668
+ const versionSuffix = result.version != null ? ` (v${result.version})` : "";
1669
+ if (result.alreadyActive) {
1670
+ logger.info(`\u2713 Already active${versionSuffix} \u2014 nothing to do.`);
1671
+ } else if (result.modelVersion === "v2") {
1672
+ logger.info(`\u2713 Domain Model updated${versionSuffix}`);
1673
+ logger.info(" Entities, relationships, vocabulary, rules, and processes are now live.");
1674
+ } else {
1675
+ logger.info(`\u2713 Published${versionSuffix} (layer id: ${result.id})`);
1676
+ logger.info(" Run `brainbox repo pull` to download the active layer locally.");
1677
+ }
1678
+ })
1679
+ );
1680
+ repo.addCommand(metaSub);
1681
+ return repo;
1682
+ }
1683
+
1684
+ // src/commands/dev.ts
1685
+ import { Command as Command3 } from "commander";
1686
+ import * as fs7 from "fs/promises";
1687
+ import { spawn as spawn2 } from "child_process";
1688
+ function createDevCommand() {
1689
+ const dev = new Command3("dev").description("Run a local MCP server serving the active context layer");
1690
+ dev.addCommand(
1691
+ addCommonOptions(new Command3("start")).description("Start brainbox-mcp as a background dev server").option("--port <port>", "Port to listen on", "3100").option("--db <url>", "Database connection URL (enables SQL tool execution)").option("--no-brain", "Exclude brain (domain model) tools").action(async (options) => {
1692
+ if (!await brainboxDirExists()) {
1693
+ console.error("error: no .brainbox/ directory found. Run `brainbox repo init` first.");
1694
+ process.exit(1);
1695
+ }
1696
+ const logger = createLogger(options.verbose, options.logFormat);
1697
+ try {
1698
+ const pidStr = await fs7.readFile(devPidPath(), "utf-8");
1699
+ const pid = parseInt(pidStr.trim(), 10);
1700
+ if (!isNaN(pid)) {
1701
+ try {
1702
+ process.kill(pid, 0);
1703
+ logger.error(`Dev server already running (PID ${pid}). Run \`brainbox dev stop\` first.`);
1704
+ process.exit(1);
1705
+ } catch {
1706
+ }
1707
+ }
1708
+ } catch {
1709
+ }
1710
+ const { projectId } = await resolveOrgAndProject(options, logger);
1711
+ const cfg = await resolveConfig(options);
1712
+ const port = parseInt(options.port, 10);
1713
+ const env = {
1714
+ ...process.env,
1715
+ BRAINBOX_PROJECT: projectId,
1716
+ BRAINBOX_API_URL: cfg.apiUrl,
1717
+ PORT: String(port)
1718
+ };
1719
+ if (options.apiKey) env["BRAINBOX_API_KEY"] = options.apiKey;
1720
+ if (options.db) env["DATABASE_URL"] = options.db;
1721
+ env["BRAINBOX_NO_BRAIN"] = options.brain ? "false" : "true";
1722
+ logger.info(`Starting BrainBox dev server on port ${port}...`);
1723
+ const child = spawn2("npx", ["brainbox-mcp"], {
1724
+ env,
1725
+ detached: true,
1726
+ stdio: ["ignore", "inherit", "inherit"]
1727
+ });
1728
+ await new Promise((resolve4, reject) => {
1729
+ child.on("spawn", resolve4);
1730
+ child.on("error", reject);
1731
+ }).catch((err) => {
1732
+ logger.error(`Failed to start dev server: ${err.message}`);
1733
+ process.exit(1);
1734
+ });
1735
+ child.unref();
1736
+ await fs7.writeFile(devPidPath(), String(child.pid), "utf-8");
1737
+ logger.info(`\u2713 MCP server started (PID ${child.pid}) on http://localhost:${port}`);
1738
+ logger.info(" Run `brainbox dev stop` to stop it.");
1739
+ })
1740
+ );
1741
+ dev.addCommand(
1742
+ new Command3("stop").description("Stop the running dev server").option("--verbose", "Print debug details").option("--log-format <format>", "Log format: text or json", "text").action(async (options) => {
1743
+ const logger = createLogger(options.verbose, options.logFormat);
1744
+ let pidStr;
1745
+ try {
1746
+ pidStr = await fs7.readFile(devPidPath(), "utf-8");
1747
+ } catch {
1748
+ logger.error("No dev server is running (no .brainbox/dev.pid found).");
1749
+ process.exit(1);
1750
+ }
1751
+ const pid = parseInt(pidStr.trim(), 10);
1752
+ if (isNaN(pid)) {
1753
+ logger.error("Invalid PID in .brainbox/dev.pid");
1754
+ process.exit(1);
1755
+ }
1756
+ try {
1757
+ process.kill(pid, "SIGTERM");
1758
+ await fs7.unlink(devPidPath());
1759
+ logger.info(`\u2713 Dev server stopped (PID ${pid})`);
1760
+ } catch (err) {
1761
+ const errno = err.code;
1762
+ if (errno === "ESRCH") {
1763
+ await fs7.unlink(devPidPath()).catch(() => void 0);
1764
+ logger.info("Dev server was not running (stale PID). Cleaned up.");
1765
+ } else {
1766
+ logger.error(`Failed to stop dev server: ${err instanceof Error ? err.message : String(err)}`);
1767
+ process.exit(1);
1768
+ }
1769
+ }
1770
+ })
1771
+ );
1772
+ return dev;
1773
+ }
1774
+
1775
+ // src/commands/profile.ts
1776
+ import { Command as Command4 } from "commander";
1777
+ import {
1778
+ connectAndProfile as connectAndProfile2,
1779
+ introspectDatabaseSchema as introspectDatabaseSchema2,
1780
+ parseProfileMode as parseProfileMode2,
1781
+ parseSkipColumns as parseSkipColumns2
1782
+ } from "@brainbox-labs/sdk/ingest";
1783
+ function createProfileCommand() {
1784
+ const profile = new Command4("profile").description("Profile utilities (compute and preview what would be uploaded)");
1785
+ const preview = addLogOptions(new Command4("preview")).description("Compute a column profile locally and print what would be uploaded. No API call.").argument("<url>", "Postgres (postgres://) or Trino (trino://user@host:port/catalog[/schema]) connection string for schema introspection. Column profiling also accepts mysql://, sqlite:, or duckdb://.").option("--profile-data [mode]", "Profile mode: omit for cardinality-only, 'full' for enum values + JSON shapes").option("--skip-profile-columns <list>", "Comma-separated table.column pairs to exclude").option("--profile-sample-rows <n>", "Max rows to sample per table (default: 10000)", "10000").option("--tables <names>", "Comma-separated table filter (default: all)").action(async (url, options) => {
1786
+ const logger = createLogger(options.verbose, options.logFormat);
1787
+ const mode = parseProfileMode2(options.profileData);
1788
+ if (mode === null) {
1789
+ logger.info("No profile mode selected. Use --profile-data or --profile-data=full.");
1790
+ logger.info(" --profile-data cardinality-only (distinctCount, nullRate, min/max/p50/p95, formatHint)");
1791
+ logger.info(" --profile-data=full + enumValues (when distinctCount <= 50) and jsonShape");
1792
+ process.exit(0);
1793
+ }
1794
+ const skipColumns = parseSkipColumns2(options.skipProfileColumns);
1795
+ const sampleRows = Math.max(1, parseInt(options.profileSampleRows, 10) || 1e4);
1796
+ logger.info("Introspecting database schema...");
1797
+ let schema;
1798
+ try {
1799
+ schema = await introspectDatabaseSchema2(url);
1800
+ } catch (err) {
1801
+ logger.error(`Failed to introspect: ${err instanceof Error ? err.message : String(err)}`);
1802
+ process.exit(1);
1803
+ }
1804
+ if (options.tables) {
1805
+ const allowed = new Set(options.tables.split(",").map((t) => t.trim()));
1806
+ schema.tables = schema.tables.filter((t) => allowed.has(t.name));
1807
+ }
1808
+ logger.info(`Schema: ${schema.tables.length} table(s)`);
1809
+ logger.info(`Profiling (mode=${mode}, sampleRows=${sampleRows})...`);
1810
+ let profiled;
1811
+ try {
1812
+ profiled = await connectAndProfile2(url, schema, { mode, sampleRows, skipColumns });
1813
+ } catch (err) {
1814
+ logger.error(`Profiling failed: ${err instanceof Error ? err.message : String(err)}`);
1815
+ process.exit(1);
1816
+ }
1817
+ console.log("\n\u2500\u2500 Profile preview (what would be uploaded) \u2500\u2500\n");
1818
+ for (const table of profiled.tables) {
1819
+ const cols = table.columns.filter((c) => c.profile !== void 0);
1820
+ if (cols.length === 0) continue;
1821
+ console.log(`Table: ${table.schema}.${table.name}`);
1822
+ for (const col of cols) {
1823
+ const p = col.profile;
1824
+ const parts = [` ${col.name} (${col.type})`];
1825
+ if (p.rowsScanned !== void 0) parts.push(`rows=${p.rowsScanned}`);
1826
+ if (p.distinctCount !== void 0) parts.push(`distinct=${p.distinctCount}`);
1827
+ if (p.nullRate !== void 0) parts.push(`nullRate=${(p.nullRate * 100).toFixed(1)}%`);
1828
+ if (p.min !== void 0) parts.push(`min=${p.min}`);
1829
+ if (p.max !== void 0) parts.push(`max=${p.max}`);
1830
+ if (p.p50 !== void 0) parts.push(`p50=${p.p50}`);
1831
+ if (p.p95 !== void 0) parts.push(`p95=${p.p95}`);
1832
+ if (p.avgLength !== void 0) parts.push(`avgLen=${p.avgLength.toFixed(1)}`);
1833
+ if (p.formatHint) parts.push(`hint=${p.formatHint}`);
1834
+ if (p.enumValues) parts.push(`enum=[${p.enumValues.join(", ")}]`);
1835
+ if (p.jsonShape) parts.push(`jsonKeys=${p.jsonShape.map((k) => k.path).join(", ")}`);
1836
+ console.log(parts.join(" "));
1837
+ }
1838
+ console.log();
1839
+ }
1840
+ const skippedCount = skipColumns.size;
1841
+ if (skippedCount > 0) {
1842
+ console.log(`Note: ${skippedCount} column(s) excluded by --skip-profile-columns.`);
1843
+ }
1844
+ });
1845
+ profile.addCommand(preview);
1846
+ return profile;
1847
+ }
1848
+
1849
+ // src/commands/collect.ts
1850
+ import { Command as Command5 } from "commander";
1851
+
1852
+ // src/collectors/manifest.ts
1853
+ import * as fs8 from "fs/promises";
1854
+ import * as nodePath5 from "path";
1855
+ import { randomUUID } from "crypto";
1856
+ var COLLECTOR_VERSION = "1";
1857
+ function newRunId() {
1858
+ const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "");
1859
+ return `${stamp}-${randomUUID().slice(0, 8)}`;
1860
+ }
1861
+ async function beginCollect(collector, outDir, runId, target) {
1862
+ await fs8.mkdir(outDir, { recursive: true });
1863
+ return { collector, runId, outDir, target, startedAt: (/* @__PURE__ */ new Date()).toISOString(), items: [] };
1864
+ }
1865
+ async function writeItem(ctx, file, markdown, item) {
1866
+ await fs8.writeFile(nodePath5.join(ctx.outDir, file), markdown, "utf-8");
1867
+ ctx.items.push({ file, ...item });
1868
+ }
1869
+ async function finishCollect(ctx) {
1870
+ const manifest = {
1871
+ collector: ctx.collector,
1872
+ collectorVersion: COLLECTOR_VERSION,
1873
+ runId: ctx.runId,
1874
+ target: ctx.target,
1875
+ startedAt: ctx.startedAt,
1876
+ completedAt: (/* @__PURE__ */ new Date()).toISOString(),
1877
+ itemCount: ctx.items.length,
1878
+ items: ctx.items
1879
+ };
1880
+ await fs8.writeFile(
1881
+ nodePath5.join(ctx.outDir, "manifest.json"),
1882
+ JSON.stringify(manifest, null, 2),
1883
+ "utf-8"
1884
+ );
1885
+ return manifest;
1886
+ }
1887
+ function slugify(input) {
1888
+ return input.replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "item";
1889
+ }
1890
+
1891
+ // src/collectors/web.ts
1892
+ import * as nodePath6 from "path";
1893
+ import { minimatch } from "minimatch";
1894
+ import robotsParser from "robots-parser";
1895
+ import { htmlToMarkdown } from "@brainbox-labs/sdk/ingest";
1896
+ var DEFAULT_UA = "brainbox-cli-collector";
1897
+ function extractLinks(html, baseUrl) {
1898
+ const out = [];
1899
+ const re = /<a\s[^>]*href\s*=\s*["']([^"'#\s]+)/gi;
1900
+ let m;
1901
+ while ((m = re.exec(html)) !== null) {
1902
+ try {
1903
+ out.push(new URL(m[1], baseUrl).toString());
1904
+ } catch {
1905
+ }
1906
+ }
1907
+ return out;
1908
+ }
1909
+ async function collectWeb(target, options, logger) {
1910
+ const doFetch = options.fetchImpl ?? fetch;
1911
+ const ua = options.userAgent ?? DEFAULT_UA;
1912
+ const start = new URL(target);
1913
+ const ctx = await beginCollect("web", options.outDir, options.runId, target);
1914
+ const robotsByOrigin = /* @__PURE__ */ new Map();
1915
+ const isDisallowed = async (u) => {
1916
+ if (!robotsByOrigin.has(u.origin)) {
1917
+ const robotsUrl = `${u.origin}/robots.txt`;
1918
+ let parsed = null;
1919
+ try {
1920
+ const robotsRes = await doFetch(robotsUrl, { headers: { "user-agent": ua } });
1921
+ if (robotsRes.ok) parsed = robotsParser(robotsUrl, await robotsRes.text());
1922
+ } catch {
1923
+ logger.debug(`robots.txt unreachable for ${u.origin} - no crawl restrictions`);
1924
+ }
1925
+ robotsByOrigin.set(u.origin, parsed);
1926
+ }
1927
+ return robotsByOrigin.get(u.origin)?.isDisallowed(u.toString(), ua) === true;
1928
+ };
1929
+ const inScope = (u) => u.origin === start.origin || options.allow.some((pattern) => minimatch(u.toString(), pattern));
1930
+ const queue = [{ url: start.toString(), depth: 0 }];
1931
+ const visited = /* @__PURE__ */ new Set();
1932
+ let pageNo = 0;
1933
+ let fetched = 0;
1934
+ while (queue.length > 0 && fetched < options.maxPages) {
1935
+ const { url, depth } = queue.shift();
1936
+ const canon = url.split("#")[0];
1937
+ if (visited.has(canon)) continue;
1938
+ visited.add(canon);
1939
+ if (await isDisallowed(new URL(canon))) {
1940
+ logger.debug(`robots.txt disallows ${canon} - skipping`);
1941
+ continue;
1942
+ }
1943
+ fetched += 1;
1944
+ let res;
1945
+ try {
1946
+ res = await doFetch(canon, { headers: { "user-agent": ua } });
1947
+ } catch (err) {
1948
+ logger.warn(`Failed to fetch ${canon}: ${err instanceof Error ? err.message : String(err)}`);
1949
+ continue;
1950
+ }
1951
+ if (!res.ok) {
1952
+ logger.warn(`Skipping ${canon} - HTTP ${res.status}`);
1953
+ continue;
1954
+ }
1955
+ const finalUrl = res.url ? new URL(res.url).toString().split("#")[0] : canon;
1956
+ const parsed = new URL(finalUrl);
1957
+ if (finalUrl !== canon) {
1958
+ visited.add(finalUrl);
1959
+ if (!inScope(parsed) || await isDisallowed(parsed)) {
1960
+ logger.debug(`Skipping ${canon} - redirected out of scope to ${finalUrl}`);
1961
+ continue;
1962
+ }
1963
+ }
1964
+ const contentType = res.headers.get("content-type") ?? "";
1965
+ if (!contentType.includes("html")) {
1966
+ logger.debug(`Skipping ${finalUrl} - not HTML (${contentType || "unknown"})`);
1967
+ continue;
1968
+ }
1969
+ const html = await res.text();
1970
+ const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
1971
+ const markdown = await htmlToMarkdown(html);
1972
+ const titleMatch = html.match(/<title[^>]*>([^<]*)<\/title>/i);
1973
+ const title = titleMatch ? titleMatch[1].trim() : parsed.pathname;
1974
+ pageNo += 1;
1975
+ const rel = parsed.pathname.replace(/\/+$/, "") + parsed.search;
1976
+ const stem = rel ? slugify(rel) : "index";
1977
+ const file = `${String(pageNo).padStart(3, "0")}-${stem}.md`;
1978
+ const frontmatter = [
1979
+ "---",
1980
+ `source_url: ${finalUrl}`,
1981
+ `title: ${JSON.stringify(title)}`,
1982
+ `fetched_at: ${fetchedAt}`,
1983
+ `depth: ${depth}`,
1984
+ "---",
1985
+ ""
1986
+ ].join("\n");
1987
+ await writeItem(ctx, file, frontmatter + markdown, {
1988
+ source: finalUrl,
1989
+ fetchedAt,
1990
+ title,
1991
+ depth,
1992
+ contentType
1993
+ });
1994
+ logger.info(` \u2713 ${file} (${finalUrl})`);
1995
+ if (depth < options.depth) {
1996
+ for (const link of extractLinks(html, finalUrl)) {
1997
+ const linkUrl = new URL(link);
1998
+ const linkCanon = linkUrl.toString().split("#")[0];
1999
+ if (!visited.has(linkCanon) && inScope(linkUrl)) {
2000
+ queue.push({ url: linkCanon, depth: depth + 1 });
2001
+ }
2002
+ }
2003
+ }
2004
+ }
2005
+ const manifest = await finishCollect(ctx);
2006
+ logger.info(`\u2713 ${manifest.itemCount} page(s) \u2192 ${nodePath6.relative(process.cwd(), ctx.outDir)}`);
2007
+ return manifest;
2008
+ }
2009
+
2010
+ // src/collectors/openapi.ts
2011
+ import * as fs9 from "fs/promises";
2012
+ import * as nodePath7 from "path";
2013
+ import YAML from "yaml";
2014
+ var HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
2015
+ async function loadSource(target) {
2016
+ if (/^https?:\/\//i.test(target)) {
2017
+ const res = await fetch(target);
2018
+ if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${target}`);
2019
+ return res.text();
2020
+ }
2021
+ return fs9.readFile(target, "utf-8");
2022
+ }
2023
+ function asRecord(v) {
2024
+ return v && typeof v === "object" ? v : {};
2025
+ }
2026
+ function renderSchema(schema) {
2027
+ if (schema === void 0 || schema === null) return "_none_";
2028
+ return "```json\n" + JSON.stringify(schema, null, 2) + "\n```";
2029
+ }
2030
+ async function collectOpenApi(target, outDir, runId, logger) {
2031
+ const raw = await loadSource(target);
2032
+ let doc;
2033
+ try {
2034
+ doc = YAML.parse(raw);
2035
+ } catch (err) {
2036
+ throw new Error(`Could not parse OpenAPI document: ${err instanceof Error ? err.message : String(err)}`);
2037
+ }
2038
+ if (!doc || !doc.openapi && !doc.swagger) {
2039
+ throw new Error("Not an OpenAPI/Swagger document (missing `openapi` or `swagger` field).");
2040
+ }
2041
+ const ctx = await beginCollect("openapi", outDir, runId, target);
2042
+ const specVersion = doc.openapi ?? doc.swagger ?? "unknown";
2043
+ const title = doc.info?.title ?? "API";
2044
+ const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
2045
+ const paths = doc.paths ?? {};
2046
+ const operations = [];
2047
+ const usedFiles = /* @__PURE__ */ new Set();
2048
+ const uniqueFile = (base) => {
2049
+ let name = `${base}.md`;
2050
+ for (let n = 2; usedFiles.has(name); n++) name = `${base}-${n}.md`;
2051
+ usedFiles.add(name);
2052
+ return name;
2053
+ };
2054
+ for (const [path4, pathItem] of Object.entries(paths)) {
2055
+ const item = asRecord(pathItem);
2056
+ const sharedParams = Array.isArray(item["parameters"]) ? item["parameters"] : [];
2057
+ for (const method of HTTP_METHODS) {
2058
+ if (!(method in item)) continue;
2059
+ const op = asRecord(item[method]);
2060
+ const opId = typeof op["operationId"] === "string" ? op["operationId"] : `${method}_${slugify(path4)}`;
2061
+ const summary = typeof op["summary"] === "string" ? op["summary"] : "";
2062
+ const description = typeof op["description"] === "string" ? op["description"] : "";
2063
+ const opParams = Array.isArray(op["parameters"]) ? op["parameters"] : [];
2064
+ const byKey = /* @__PURE__ */ new Map();
2065
+ for (const p of [...sharedParams, ...opParams]) {
2066
+ const pr = asRecord(p);
2067
+ byKey.set(JSON.stringify([pr["name"] ?? "", pr["in"] ?? ""]), p);
2068
+ }
2069
+ const params = [...byKey.values()];
2070
+ const lines = [];
2071
+ lines.push("---");
2072
+ lines.push(`operation_id: ${JSON.stringify(opId)}`);
2073
+ lines.push(`method: ${method.toUpperCase()}`);
2074
+ lines.push(`path: ${JSON.stringify(path4)}`);
2075
+ lines.push(`source: ${JSON.stringify(target)}`);
2076
+ lines.push(`fetched_at: ${fetchedAt}`);
2077
+ lines.push("---");
2078
+ lines.push("");
2079
+ lines.push(`# ${method.toUpperCase()} ${path4}`);
2080
+ lines.push("");
2081
+ if (summary) lines.push(`**${summary}**`, "");
2082
+ if (description) lines.push(description, "");
2083
+ lines.push("## Parameters", "");
2084
+ if (params.length === 0) {
2085
+ lines.push("_none_", "");
2086
+ } else {
2087
+ lines.push("| Name | In | Required | Description | Schema |", "|---|---|---|---|---|");
2088
+ for (const p of params) {
2089
+ const pr = asRecord(p);
2090
+ const schema = pr["schema"] ?? { type: pr["type"] };
2091
+ lines.push(
2092
+ `| ${pr["name"] ?? ""} | ${pr["in"] ?? ""} | ${pr["required"] === true ? "yes" : "no"} | ${String(pr["description"] ?? "").replace(/\n/g, " ")} | \`${JSON.stringify(schema)}\` |`
2093
+ );
2094
+ }
2095
+ lines.push("");
2096
+ }
2097
+ const requestBody = op["requestBody"];
2098
+ lines.push("## Request body", "");
2099
+ lines.push(renderSchema(requestBody), "");
2100
+ lines.push("## Responses", "");
2101
+ const responses = asRecord(op["responses"]);
2102
+ if (Object.keys(responses).length === 0) {
2103
+ lines.push("_none_", "");
2104
+ } else {
2105
+ for (const [status, body] of Object.entries(responses)) {
2106
+ const br = asRecord(body);
2107
+ lines.push(`### ${status}${br["description"] ? ` \u2014 ${br["description"]}` : ""}`, "");
2108
+ lines.push(renderSchema(br["content"] ?? br["schema"] ?? body), "");
2109
+ }
2110
+ }
2111
+ const file = uniqueFile(slugify(`${method}-${path4}`));
2112
+ await writeItem(ctx, file, lines.join("\n"), {
2113
+ source: `${method.toUpperCase()} ${path4}`,
2114
+ fetchedAt,
2115
+ operationId: opId,
2116
+ method: method.toUpperCase(),
2117
+ path: path4
2118
+ });
2119
+ operations.push({ path: path4, method: method.toUpperCase(), opId, summary });
2120
+ }
2121
+ }
2122
+ const schemas = doc.components?.schemas ?? doc.definitions;
2123
+ if (schemas && Object.keys(schemas).length > 0) {
2124
+ const lines = [
2125
+ "---",
2126
+ `source: ${JSON.stringify(target)}`,
2127
+ `fetched_at: ${fetchedAt}`,
2128
+ "---",
2129
+ "",
2130
+ "# Schemas",
2131
+ "",
2132
+ "```json",
2133
+ JSON.stringify(schemas, null, 2),
2134
+ "```",
2135
+ ""
2136
+ ];
2137
+ await writeItem(ctx, "_schemas.md", lines.join("\n"), {
2138
+ source: "components/schemas",
2139
+ fetchedAt,
2140
+ schemaCount: Object.keys(schemas).length
2141
+ });
2142
+ }
2143
+ const indexLines = [
2144
+ `# ${title}`,
2145
+ "",
2146
+ `- Spec: ${doc.openapi ? "OpenAPI" : "Swagger"} ${specVersion}`,
2147
+ `- Version: ${doc.info?.version ?? "unknown"}`,
2148
+ `- Source: ${target}`,
2149
+ `- Operations: ${operations.length}`,
2150
+ "",
2151
+ ...doc.info?.description ? [doc.info.description, ""] : [],
2152
+ "## Operations",
2153
+ "",
2154
+ "| Method | Path | Operation ID | Summary |",
2155
+ "|---|---|---|---|",
2156
+ ...operations.map((o) => `| ${o.method} | ${o.path} | ${o.opId} | ${o.summary.replace(/\n/g, " ")} |`),
2157
+ ""
2158
+ ];
2159
+ await writeItem(ctx, "_index.md", indexLines.join("\n"), {
2160
+ source: target,
2161
+ fetchedAt,
2162
+ operationCount: operations.length
2163
+ });
2164
+ const manifest = await finishCollect(ctx);
2165
+ logger.info(`\u2713 ${operations.length} operation(s) \u2192 ${nodePath7.relative(process.cwd(), outDir)}`);
2166
+ return manifest;
2167
+ }
2168
+
2169
+ // src/collectors/proto.ts
2170
+ import * as fs10 from "fs/promises";
2171
+ import { existsSync } from "fs";
2172
+ import * as nodePath8 from "path";
2173
+ import protobuf from "protobufjs";
2174
+ async function findProtoFiles(target) {
2175
+ const stat2 = await fs10.stat(target);
2176
+ if (stat2.isFile()) return [nodePath8.resolve(target)];
2177
+ const out = [];
2178
+ async function walk(dir) {
2179
+ for (const entry of await fs10.readdir(dir, { withFileTypes: true })) {
2180
+ const full = nodePath8.join(dir, entry.name);
2181
+ if (entry.isDirectory()) await walk(full);
2182
+ else if (entry.name.endsWith(".proto")) out.push(full);
2183
+ }
2184
+ }
2185
+ await walk(nodePath8.resolve(target));
2186
+ return out.sort();
2187
+ }
2188
+ function fieldRows(type) {
2189
+ return type.fieldsArray.slice().sort((a, b) => a.id - b.id).map((f) => ({
2190
+ name: f.name,
2191
+ type: f.repeated ? `repeated ${f.type}` : f.map ? `map<${f.keyType}, ${f.type}>` : f.type,
2192
+ id: f.id,
2193
+ // protobufjs sets `optional = !required` for every proto3 field, so only
2194
+ // report it for genuine scalar singular fields (repeated/map carry their
2195
+ // own cardinality in the type column).
2196
+ rule: f.required ? "required" : f.repeated || f.map ? "" : f.optional ? "optional" : ""
2197
+ }));
2198
+ }
2199
+ function collectTypes(ns, messages, enums, services) {
2200
+ for (const obj of ns.nestedArray) {
2201
+ if (obj instanceof protobuf.Type) {
2202
+ messages.push(obj);
2203
+ collectTypes(obj, messages, enums, services);
2204
+ } else if (obj instanceof protobuf.Enum) {
2205
+ enums.push(obj);
2206
+ } else if (obj instanceof protobuf.Service) {
2207
+ services.push(obj);
2208
+ } else if (obj instanceof protobuf.Namespace) {
2209
+ collectTypes(obj, messages, enums, services);
2210
+ }
2211
+ }
2212
+ }
2213
+ async function collectProto(target, outDir, runId, logger) {
2214
+ const files = await findProtoFiles(target);
2215
+ if (files.length === 0) throw new Error(`No .proto files found at ${target}`);
2216
+ const root = new protobuf.Root();
2217
+ const searchDirs = [...new Set(files.map((f) => nodePath8.dirname(f)))];
2218
+ const originalResolve = root.resolvePath.bind(root);
2219
+ root.resolvePath = (origin, importPath) => {
2220
+ const direct = originalResolve(origin, importPath);
2221
+ if (direct && existsSync(direct)) return direct;
2222
+ for (const dir of searchDirs) {
2223
+ const candidate = nodePath8.join(dir, importPath);
2224
+ if (existsSync(candidate)) return candidate;
2225
+ }
2226
+ return direct;
2227
+ };
2228
+ root.loadSync(files, { keepCase: true, alternateCommentMode: true });
2229
+ root.resolveAll();
2230
+ const ctx = await beginCollect("proto", outDir, runId, target);
2231
+ const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
2232
+ const messages = [];
2233
+ const enums = [];
2234
+ const services = [];
2235
+ collectTypes(root, messages, enums, services);
2236
+ for (const svc of services) {
2237
+ const lines = ["---", `kind: service`, `name: ${JSON.stringify(svc.fullName.replace(/^\./, ""))}`, `source: ${JSON.stringify(target)}`, `fetched_at: ${fetchedAt}`, "---", "", `# service ${svc.fullName.replace(/^\./, "")}`, ""];
2238
+ if (svc.comment) lines.push(svc.comment, "");
2239
+ lines.push("| RPC | Request | Response | Streaming |", "|---|---|---|---|");
2240
+ for (const m of svc.methodsArray) {
2241
+ const streaming = [m.requestStream ? "client" : "", m.responseStream ? "server" : ""].filter(Boolean).join("+") || "unary";
2242
+ lines.push(`| ${m.name} | ${m.requestType} | ${m.responseType} | ${streaming} |`);
2243
+ }
2244
+ lines.push("");
2245
+ const file = `service-${slugify(svc.fullName.replace(/^\./, ""))}.md`;
2246
+ await writeItem(ctx, file, lines.join("\n"), { source: svc.fullName.replace(/^\./, ""), fetchedAt, kind: "service", rpcs: svc.methodsArray.length });
2247
+ }
2248
+ for (const type of messages) {
2249
+ const name = type.fullName.replace(/^\./, "");
2250
+ const rows = fieldRows(type);
2251
+ const lines = ["---", `kind: message`, `name: ${JSON.stringify(name)}`, `source: ${JSON.stringify(target)}`, `fetched_at: ${fetchedAt}`, "---", "", `# message ${name}`, ""];
2252
+ if (type.comment) lines.push(type.comment, "");
2253
+ lines.push("| Field | Type | Number | Rule |", "|---|---|---|---|");
2254
+ for (const r of rows) lines.push(`| ${r.name} | \`${r.type}\` | ${r.id} | ${r.rule} |`);
2255
+ lines.push("");
2256
+ const file = `message-${slugify(name)}.md`;
2257
+ await writeItem(ctx, file, lines.join("\n"), { source: name, fetchedAt, kind: "message", fields: rows.length });
2258
+ }
2259
+ for (const en of enums) {
2260
+ const name = en.fullName.replace(/^\./, "");
2261
+ const lines = ["---", `kind: enum`, `name: ${JSON.stringify(name)}`, `source: ${JSON.stringify(target)}`, `fetched_at: ${fetchedAt}`, "---", "", `# enum ${name}`, "", "| Name | Number |", "|---|---|"];
2262
+ for (const [k, v] of Object.entries(en.values)) lines.push(`| ${k} | ${v} |`);
2263
+ lines.push("");
2264
+ const file = `enum-${slugify(name)}.md`;
2265
+ await writeItem(ctx, file, lines.join("\n"), { source: name, fetchedAt, kind: "enum", values: Object.keys(en.values).length });
2266
+ }
2267
+ const indexLines = [
2268
+ `# Protobuf definitions`,
2269
+ "",
2270
+ `- Source: ${target}`,
2271
+ `- Files: ${files.length}`,
2272
+ `- Services: ${services.length}, Messages: ${messages.length}, Enums: ${enums.length}`,
2273
+ "",
2274
+ "## Files",
2275
+ "",
2276
+ ...files.map((f) => `- ${nodePath8.relative(process.cwd(), f)}`),
2277
+ ""
2278
+ ];
2279
+ await writeItem(ctx, "_index.md", indexLines.join("\n"), {
2280
+ source: target,
2281
+ fetchedAt,
2282
+ fileCount: files.length
2283
+ });
2284
+ const manifest = await finishCollect(ctx);
2285
+ logger.info(
2286
+ `\u2713 ${services.length} service(s), ${messages.length} message(s), ${enums.length} enum(s) \u2192 ${nodePath8.relative(process.cwd(), outDir)}`
2287
+ );
2288
+ return manifest;
2289
+ }
2290
+
2291
+ // src/collectors/files.ts
2292
+ import * as fs11 from "fs/promises";
2293
+ import * as nodePath9 from "path";
2294
+ import { glob } from "glob";
2295
+ import { needsConversion as needsConversion2, convertToMarkdown as convertToMarkdown2, convertedName as convertedName2 } from "@brainbox-labs/sdk/ingest";
2296
+ var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
2297
+ ".png",
2298
+ ".jpg",
2299
+ ".jpeg",
2300
+ ".gif",
2301
+ ".bmp",
2302
+ ".zip",
2303
+ ".tar",
2304
+ ".gz",
2305
+ ".bz2",
2306
+ ".7z",
2307
+ ".exe",
2308
+ ".dll",
2309
+ ".so",
2310
+ ".bin"
2311
+ ]);
2312
+ async function collectFiles(patterns, outDir, runId, logger) {
2313
+ const matched = [];
2314
+ const seen = /* @__PURE__ */ new Set();
2315
+ for (const pattern of patterns) {
2316
+ const hits = await glob(pattern, { nodir: true, absolute: true });
2317
+ if (hits.length === 0) throw new Error(`No file matched "${pattern}".`);
2318
+ for (const h of hits) {
2319
+ if (!seen.has(h)) {
2320
+ seen.add(h);
2321
+ matched.push(h);
2322
+ }
2323
+ }
2324
+ }
2325
+ const ctx = await beginCollect("files", outDir, runId, patterns.join(" "));
2326
+ const usedNames = /* @__PURE__ */ new Set();
2327
+ for (const absPath of matched) {
2328
+ const ext = nodePath9.extname(absPath).toLowerCase();
2329
+ if (BINARY_EXTENSIONS.has(ext)) {
2330
+ logger.warn(`Skipping ${absPath}: unsupported binary file type "${ext}"`);
2331
+ continue;
2332
+ }
2333
+ const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
2334
+ let markdown;
2335
+ let outName;
2336
+ try {
2337
+ if (needsConversion2(absPath)) {
2338
+ logger.info(` Converting ${nodePath9.basename(absPath)}\u2026`);
2339
+ markdown = await convertToMarkdown2(absPath);
2340
+ outName = convertedName2(absPath);
2341
+ } else {
2342
+ markdown = await fs11.readFile(absPath, "utf-8");
2343
+ outName = nodePath9.basename(absPath).replace(/\.(md|markdown)$/i, "") + ".md";
2344
+ }
2345
+ } catch (err) {
2346
+ logger.warn(`Skipping ${absPath}: ${err instanceof Error ? err.message : String(err)}`);
2347
+ continue;
2348
+ }
2349
+ const outExt = nodePath9.extname(outName);
2350
+ const outStem = outName.slice(0, outName.length - outExt.length);
2351
+ let unique = outName;
2352
+ let n = 2;
2353
+ while (usedNames.has(unique)) unique = `${outStem}-${n++}${outExt}`;
2354
+ usedNames.add(unique);
2355
+ await writeItem(ctx, unique, markdown, {
2356
+ source: absPath,
2357
+ fetchedAt,
2358
+ originalName: nodePath9.basename(absPath),
2359
+ converted: needsConversion2(absPath)
2360
+ });
2361
+ logger.info(` \u2713 ${unique}`);
2362
+ }
2363
+ const manifest = await finishCollect(ctx);
2364
+ logger.info(`\u2713 ${manifest.itemCount} file(s) \u2192 ${nodePath9.relative(process.cwd(), outDir)}`);
2365
+ return manifest;
2366
+ }
2367
+
2368
+ // src/commands/collect.ts
2369
+ async function requireBrainboxDir3() {
2370
+ if (!await brainboxDirExists()) {
2371
+ console.error("error: no .brainbox/ directory found. Run `brainbox repo init` first.");
2372
+ process.exit(1);
2373
+ }
2374
+ }
2375
+ function createCollectCommand() {
2376
+ const collect2 = new Command5("collect").description("Collect a locked source into a local markdown bundle (no upload, no LLM)");
2377
+ collect2.addCommand(
2378
+ addLogOptions(new Command5("web")).description("Crawl a website (same-origin) and convert each page to markdown").argument("<url>", "Start URL").option("--depth <n>", "Link-follow depth from the start URL", "0").option("--max-pages <n>", "Hard cap on pages fetched", "50").option("--allow <glob>", "Extra URL glob to crawl beyond the start origin (repeatable)", (v, p = []) => [...p, v]).action(async (url, options) => {
2379
+ await requireBrainboxDir3();
2380
+ const logger = createLogger(options.verbose, options.logFormat);
2381
+ const runId = newRunId();
2382
+ const outDir = collectedDir("web", runId);
2383
+ logger.info(`Collecting web \u2192 ${url}`);
2384
+ await collectWeb(
2385
+ url,
2386
+ {
2387
+ depth: Math.max(0, parseInt(options.depth, 10) || 0),
2388
+ maxPages: Math.max(1, parseInt(options.maxPages, 10) || 50),
2389
+ allow: options.allow ?? [],
2390
+ outDir,
2391
+ runId
2392
+ },
2393
+ logger
2394
+ );
2395
+ })
2396
+ );
2397
+ collect2.addCommand(
2398
+ addLogOptions(new Command5("openapi")).description("Normalize an OpenAPI/Swagger document into a per-operation markdown bundle").argument("<source>", "Path or URL to an OpenAPI/Swagger file (JSON or YAML)").action(async (source, options) => {
2399
+ await requireBrainboxDir3();
2400
+ const logger = createLogger(options.verbose, options.logFormat);
2401
+ const runId = newRunId();
2402
+ logger.info(`Collecting openapi \u2192 ${source}`);
2403
+ await collectOpenApi(source, collectedDir("openapi", runId), runId, logger);
2404
+ })
2405
+ );
2406
+ collect2.addCommand(
2407
+ addLogOptions(new Command5("proto")).description("Normalize .proto files into a markdown message/service/enum list").argument("<source>", "Path to a .proto file or a directory of them").action(async (source, options) => {
2408
+ await requireBrainboxDir3();
2409
+ const logger = createLogger(options.verbose, options.logFormat);
2410
+ const runId = newRunId();
2411
+ logger.info(`Collecting proto \u2192 ${source}`);
2412
+ await collectProto(source, collectedDir("proto", runId), runId, logger);
2413
+ })
2414
+ );
2415
+ collect2.addCommand(
2416
+ addLogOptions(new Command5("files")).description("Convert PDF/DOCX/HTML/MD files to markdown (same conversion as `meta ingest doc`)").argument("<paths...>", "Files or globs to convert").action(async (paths, options) => {
2417
+ await requireBrainboxDir3();
2418
+ const logger = createLogger(options.verbose, options.logFormat);
2419
+ const runId = newRunId();
2420
+ logger.info(`Collecting files \u2192 ${paths.join(", ")}`);
2421
+ await collectFiles(paths, collectedDir("files", runId), runId, logger);
2422
+ })
2423
+ );
2424
+ return collect2;
2425
+ }
2426
+
2427
+ // src/commands/recipe.ts
2428
+ import { Command as Command6 } from "commander";
2429
+ import * as fs12 from "fs/promises";
2430
+
2431
+ // src/recipe-check.ts
2432
+ import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
2433
+ import { StreamableHTTPClientTransport as StreamableHTTPClientTransport2 } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
2434
+ function isCheckResult(v) {
2435
+ if (typeof v !== "object" || v === null) return false;
2436
+ const r = v;
2437
+ return typeof r.recipe === "string" && typeof r.passed === "number" && typeof r.total === "number" && r.advisory === true && typeof r.instruction === "string" && Array.isArray(r.checks);
2438
+ }
2439
+ async function checkContextDraft(apiUrl, apiKey, args) {
2440
+ const url = new URL(`${apiUrl.replace(/\/+$/, "")}/api/mcp`);
2441
+ const client = new Client2({ name: "brainbox-cli", version: "1.0.0" });
2442
+ const transport = new StreamableHTTPClientTransport2(url, {
2443
+ requestInit: apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : void 0
2444
+ });
2445
+ await client.connect(transport);
2446
+ try {
2447
+ const res = await client.callTool({
2448
+ name: "check_context_draft",
2449
+ arguments: args
2450
+ });
2451
+ const textParts = Array.isArray(res.content) ? res.content.filter((c) => c.type === "text").map((c) => c.text ?? "") : [];
2452
+ if (res.isError) {
2453
+ throw new Error(textParts.join("\n") || "check_context_draft returned an error");
2454
+ }
2455
+ if (isCheckResult(res.structuredContent)) {
2456
+ return res.structuredContent;
2457
+ }
2458
+ if (textParts.length > 0) {
2459
+ const parsed = JSON.parse(textParts.join(""));
2460
+ if (isCheckResult(parsed)) return parsed;
2461
+ }
2462
+ throw new Error(
2463
+ "check_context_draft returned an unrecognized response shape:\n" + JSON.stringify(res.structuredContent ?? textParts.join("") ?? null)
2464
+ );
2465
+ } finally {
2466
+ await client.close();
2467
+ }
2468
+ }
2469
+
2470
+ // src/commands/recipe.ts
2471
+ function cliMeetsRequirement(range, current) {
2472
+ const min = range.replace(/^[^\d]*/, "").trim();
2473
+ const parse2 = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
2474
+ const [a = 0, b = 0, c = 0] = parse2(min);
2475
+ const [x = 0, y = 0, z = 0] = parse2(current);
2476
+ const ok = x > a || x === a && (y > b || y === b && z >= c);
2477
+ return { ok, min };
2478
+ }
2479
+ function parseFrontmatterKey(content, key) {
2480
+ const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
2481
+ if (!m) return void 0;
2482
+ for (const line of m[1].split(/\r?\n/)) {
2483
+ const kv = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.+?)\s*$/);
2484
+ if (kv && kv[1] === key) return kv[2].replace(/^["']|["']$/g, "");
2485
+ }
2486
+ return void 0;
2487
+ }
2488
+ function createRecipeCommand(cliVersion) {
2489
+ const CLI_VERSION = cliVersion;
2490
+ const recipe = new Command6("recipe").description("Browse, install, and check context recipes");
2491
+ recipe.addCommand(
2492
+ addCommonOptions(new Command6("list")).description("List the recipe catalog published by the BrainBox server").action(async (options) => {
2493
+ const logger = createLogger(options.verbose, options.logFormat);
2494
+ const cfg = await resolveConfig(options);
2495
+ const api = new BrainBoxApiClient(cfg.apiUrl, options.apiKey, logger);
2496
+ let systemSkills;
2497
+ try {
2498
+ ({ systemSkills } = await api.listSystemSkills());
2499
+ } catch (err) {
2500
+ logger.error(`Failed to fetch recipe catalog: ${err instanceof Error ? err.message : String(err)}`);
2501
+ process.exit(1);
2502
+ }
2503
+ const recipes = systemSkills.filter((s) => s.category === "context-recipe");
2504
+ if (recipes.length === 0) {
2505
+ logger.info("No context recipes are published yet.");
2506
+ logger.info("The catalog is seeded server-side \u2014 check back after the next BrainBox release,");
2507
+ logger.info("or run `brainbox recipe list --api-url <emulator>` against a locally seeded server.");
2508
+ return;
2509
+ }
2510
+ logger.info(`${recipes.length} recipe(s):
2511
+ `);
2512
+ for (const r of recipes) {
2513
+ const collectors = r.recipeSchema?.collectors ?? [];
2514
+ logger.info(` ${r.slug} (v${r.latestVersion})`);
2515
+ logger.info(` ${r.description}`);
2516
+ logger.info(` collectors: ${collectors.length > 0 ? collectors.join(", ") : "none"}`);
2517
+ if (r.requires?.cli) logger.info(` requires: CLI ${r.requires.cli}`);
2518
+ logger.info("");
2519
+ }
2520
+ })
2521
+ );
2522
+ recipe.addCommand(
2523
+ addCommonOptions(new Command6("install")).description("Install a recipe into the resolved project").argument("<slug>", "Recipe slug (see `brainbox recipe list`)").action(async (slug, options) => {
2524
+ const logger = createLogger(options.verbose, options.logFormat);
2525
+ const { api, orgId, projectId } = await resolveOrgAndProject(options, logger);
2526
+ let summary;
2527
+ try {
2528
+ summary = await api.getSystemSkill(slug);
2529
+ } catch (err) {
2530
+ logger.error(`Recipe "${slug}" not found: ${err instanceof Error ? err.message : String(err)}`);
2531
+ process.exit(1);
2532
+ }
2533
+ if (summary.requires?.cli) {
2534
+ const { ok, min } = cliMeetsRequirement(summary.requires.cli, CLI_VERSION);
2535
+ if (!ok) {
2536
+ logger.error(
2537
+ `this recipe needs CLI >= ${min} \u2014 run npm i -g @brainbox-labs/cli (current: ${CLI_VERSION})`
2538
+ );
2539
+ process.exit(1);
2540
+ }
2541
+ }
2542
+ let outcome;
2543
+ try {
2544
+ outcome = await api.installSystemSkill(orgId, projectId, slug);
2545
+ } catch (err) {
2546
+ logger.error(`Failed to install recipe "${slug}": ${err instanceof Error ? err.message : String(err)}`);
2547
+ process.exit(1);
2548
+ }
2549
+ if (outcome.alreadyInstalled) {
2550
+ logger.info(`already installed (skill ${outcome.conflictingId})`);
2551
+ return;
2552
+ }
2553
+ const result = outcome.result;
2554
+ logger.info(`\u2713 Installed "${result.name}" (v${result.installedVersion})`);
2555
+ logger.info(` Your agent runs this recipe by calling get_skill with "${result.name}".`);
2556
+ })
2557
+ );
2558
+ recipe.addCommand(
2559
+ addCommonOptions(new Command6("check")).description("Advisory readiness report on a drafted markdown file (never fails the build)").argument("<file>", "Path to the drafted markdown file").option("--recipe <slug>", "Recipe slug to check against (defaults to the `recipe:` frontmatter key)").action(async (file, options) => {
2560
+ const logger = createLogger(options.verbose, options.logFormat);
2561
+ let content;
2562
+ try {
2563
+ content = await fs12.readFile(file, "utf-8");
2564
+ } catch {
2565
+ logger.error(`Cannot read file: ${file}`);
2566
+ process.exit(1);
2567
+ }
2568
+ const slug = options.recipe ?? parseFrontmatterKey(content, "recipe");
2569
+ if (!slug) {
2570
+ logger.error(
2571
+ "No recipe specified \u2014 add a `recipe: <slug>` key to the file's frontmatter, or pass --recipe <slug>."
2572
+ );
2573
+ process.exit(1);
2574
+ }
2575
+ const cfg = await resolveConfig(options);
2576
+ let report;
2577
+ try {
2578
+ report = await checkContextDraft(cfg.apiUrl, options.apiKey, { recipe: slug, content });
2579
+ } catch (err) {
2580
+ logger.error(`Readiness check failed: ${err instanceof Error ? err.message : String(err)}`);
2581
+ process.exit(1);
2582
+ }
2583
+ logger.info(`Recipe: ${report.recipe} ${report.passed}/${report.total} checks passed (advisory)
2584
+ `);
2585
+ for (const c of report.checks) {
2586
+ logger.info(` ${c.ok ? "\u2713" : "\u2717"} ${c.requirement}`);
2587
+ if (!c.ok && c.detail) logger.info(` ${c.detail}`);
2588
+ if (!c.ok && c.fix) logger.info(` fix: ${c.fix}`);
2589
+ }
2590
+ logger.info("");
2591
+ if (report.instruction) logger.info(report.instruction);
2592
+ process.exit(0);
2593
+ })
2594
+ );
2595
+ return recipe;
2596
+ }
2597
+
2598
+ // src/commands/kb.ts
2599
+ import * as nodePath10 from "path";
2600
+ import * as fs13 from "fs/promises";
2601
+ function inferDocType2(filePath) {
2602
+ const ext = nodePath10.extname(filePath).toLowerCase();
2603
+ if (ext === ".md" || ext === ".markdown") return "markdown";
2604
+ if (ext === ".html" || ext === ".htm") return "html";
2605
+ const binaryExtensions = /* @__PURE__ */ new Set([
2606
+ ".pdf",
2607
+ ".png",
2608
+ ".jpg",
2609
+ ".jpeg",
2610
+ ".gif",
2611
+ ".bmp",
2612
+ ".zip",
2613
+ ".tar",
2614
+ ".gz",
2615
+ ".bz2",
2616
+ ".7z",
2617
+ ".exe",
2618
+ ".dll",
2619
+ ".so",
2620
+ ".bin"
2621
+ ]);
2622
+ if (binaryExtensions.has(ext)) {
2623
+ throw new Error(
2624
+ `Unsupported binary file type "${ext}" for path "${filePath}". Binary files (e.g., PDFs, images, archives) cannot be safely read as UTF-8 text. Please convert them to a text format or exclude them from kb-submit.`
2625
+ );
2626
+ }
2627
+ return "text";
2628
+ }
2629
+ function registerKbCommands(program2) {
2630
+ program2.command("kb-submit").description("Submit documents / text files to the Knowledge Base for LLM analysis").argument("<files...>", "Paths to document files (.sql, .txt, .eml, .md, .html, etc.)").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Any org project \u2014 auto-creates if missing (or set BRAINBOX_PROJECT env var). Mutually exclusive with --tenant.").option("--tenant <name>", "Existing tenant overlay \u2014 never auto-creates, errors if not found (or set BRAINBOX_TENANT env var). Mutually exclusive with --project.").option("--rules <json>", `JSON array of extraction rules, e.g. '[{"name":"revenue","description":"Revenue figures"}]'`).option("--no-wait", "Submit and return immediately without polling for completion").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--ui-url <url>", "BrainBox web UI base URL", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--verbose", "Print full request/response details").action(async (files, options) => {
2631
+ const logger = createLogger(options.verbose);
2632
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
2633
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
2634
+ if (!options.org) {
2635
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
2636
+ process.exit(1);
2637
+ }
2638
+ const target = resolveTenantOrProject(options, logger);
2639
+ if (!target.tenant && !target.project) {
2640
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT, or pass --tenant)");
2641
+ process.exit(1);
2642
+ }
2643
+ try {
2644
+ logger.info(`Reading ${files.length} file(s)...`);
2645
+ const sources = [];
2646
+ for (const filePath of files) {
2647
+ let content;
2648
+ try {
2649
+ content = await fs13.readFile(filePath, "utf-8");
2650
+ } catch (err) {
2651
+ logger.error(`Error reading "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
2652
+ process.exit(1);
2653
+ }
2654
+ const name = nodePath10.basename(filePath);
2655
+ const type = inferDocType2(filePath);
2656
+ sources.push({ id: name, name, type, content });
2657
+ logger.debug(` ${name} (${type}, ${content.length} chars)`);
2658
+ }
2659
+ let extractionRules;
2660
+ if (options.rules) {
2661
+ try {
2662
+ extractionRules = JSON.parse(options.rules);
2663
+ } catch {
2664
+ logger.error("Error: --rules must be valid JSON array");
2665
+ process.exit(1);
2666
+ }
2667
+ }
2668
+ logger.info("Ensuring org exists...");
2669
+ let org;
2670
+ try {
2671
+ org = await api.getOrCreateOrg(options.org);
2672
+ } catch (err) {
2673
+ logger.error(`Error communicating with API: ${err instanceof Error ? err.message : String(err)}`);
2674
+ process.exit(1);
2675
+ }
2676
+ let projectId;
2677
+ if (target.tenant) {
2678
+ logger.info(`Resolving tenant "${target.tenant}"...`);
2679
+ let tenant;
2680
+ try {
2681
+ tenant = await api.resolveTenant(org.id, target.tenant);
2682
+ } catch (err) {
2683
+ logger.error(`Error resolving tenant: ${err instanceof Error ? err.message : String(err)}`);
2684
+ process.exit(1);
2685
+ }
2686
+ if (!tenant) {
2687
+ logger.error(
2688
+ `error: no tenant named "${target.tenant}" in this org \u2014 check the tenant name (not the project name), or omit --tenant to target a plain project`
2689
+ );
2690
+ process.exit(1);
2691
+ }
2692
+ projectId = tenant.projectId;
2693
+ } else {
2694
+ logger.info("Ensuring project exists...");
2695
+ let project;
2696
+ try {
2697
+ project = await api.getOrCreateProject(org.id, target.project);
2698
+ } catch (err) {
2699
+ logger.error(`Error ensuring project: ${err instanceof Error ? err.message : String(err)}`);
2700
+ process.exit(1);
2701
+ }
2702
+ projectId = project.id;
2703
+ }
2704
+ logger.info("Submitting documents to Knowledge Base...");
2705
+ let draft;
2706
+ try {
2707
+ draft = await api.submitKnowledgeDraft(org.id, projectId, sources, extractionRules);
2708
+ logger.debug("Knowledge draft response", draft);
2709
+ } catch (err) {
2710
+ logger.error(`Error submitting knowledge draft: ${err instanceof Error ? err.message : String(err)}`);
2711
+ process.exit(1);
2712
+ }
2713
+ logger.info(`
2714
+ \u2713 Knowledge draft created (id: ${draft.draftId}, ${draft.documentCount} doc(s)).`);
2715
+ logger.info("Starting context generation...");
2716
+ let ctx;
2717
+ try {
2718
+ ctx = await api.createContext(org.id, projectId, { type: "knowledge", draftId: draft.draftId });
2719
+ logger.info(`\u2713 Context generation started (id: ${ctx.contextId}).`);
2720
+ } catch (err) {
2721
+ logger.warn(`Warning: could not start context generation: ${err instanceof Error ? err.message : String(err)}`);
2722
+ logger.info(`
2723
+ Review at: ${options.uiUrl}/orgs/${org.id}/projects/${projectId}/kb-drafts/${draft.draftId}
2724
+ `);
2725
+ return;
2726
+ }
2727
+ if (options.wait) {
2728
+ logger.info("Processing... (polling every 3s, timeout 5m)");
2729
+ let ready;
2730
+ try {
2731
+ ready = await api.pollContextUntilReady(org.id, projectId, ctx.contextId);
2732
+ } catch (err) {
2733
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2734
+ process.exit(1);
2735
+ }
2736
+ const generated = ready.generated;
2737
+ if (generated) {
2738
+ logger.info(`
2739
+ \u2713 Analysis complete:`);
2740
+ logger.info(` Documents annotated : ${generated.documents?.length ?? 0}`);
2741
+ logger.info(` Entities extracted : ${generated.entities?.length ?? 0}`);
2742
+ logger.info(` Relationships : ${generated.relationships?.length ?? 0}`);
2743
+ logger.info(` Suggested KB tools : ${generated.suggestedTools?.length ?? 0}`);
2744
+ }
2745
+ logger.info(`
2746
+ Review at: ${options.uiUrl}/orgs/${org.id}/projects/${projectId}/kb-drafts/${draft.draftId}
2747
+ `);
2748
+ } else {
2749
+ logger.info(` (skipping wait \u2014 check status via kb-layers or the review UI)`);
2750
+ logger.info(`
2751
+ Review at: ${options.uiUrl}/orgs/${org.id}/projects/${projectId}/kb-drafts/${draft.draftId}
2752
+ `);
2753
+ }
2754
+ } catch (err) {
2755
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
2756
+ process.exit(1);
2757
+ }
2758
+ });
2759
+ program2.command("kb-layers").description("List approved Knowledge Base layers for a project").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details").action(async (options) => {
2760
+ const logger = createLogger(options.verbose);
2761
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
2762
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
2763
+ if (!options.org) {
2764
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
2765
+ process.exit(1);
2766
+ }
2767
+ if (!options.project) {
2768
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
2769
+ process.exit(1);
2770
+ }
2771
+ try {
2772
+ let org;
2773
+ try {
2774
+ org = await api.getOrg(options.org);
2775
+ } catch (err) {
2776
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2777
+ process.exit(1);
2778
+ }
2779
+ let project;
2780
+ try {
2781
+ project = await api.getProject(org.id, options.project);
2782
+ } catch (err) {
2783
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2784
+ process.exit(1);
2785
+ }
2786
+ let result;
2787
+ try {
2788
+ result = await api.listKnowledgeLayers(org.id, project.id);
2789
+ } catch (err) {
2790
+ logger.error(`Error fetching knowledge layers: ${err instanceof Error ? err.message : String(err)}`);
2791
+ process.exit(1);
2792
+ }
2793
+ const { layers } = result;
2794
+ if (layers.length === 0) {
2795
+ logger.info("No approved Knowledge Base layers found for this project.");
2796
+ return;
2797
+ }
2798
+ logger.info(`
2799
+ Knowledge Base layers for "${options.project}":
2800
+ `);
2801
+ for (const l of layers) {
2802
+ const date = new Date(l.createdAt).toLocaleDateString();
2803
+ logger.info(
2804
+ ` v${l.version} entities: ${String(l.entities?.length ?? 0).padEnd(4)} tools: ${String(l.tools?.length ?? 0).padEnd(3)} ${l.approvedBy.padEnd(20)} ${date}`
2805
+ );
2806
+ }
2807
+ logger.info("");
2808
+ } catch (err) {
2809
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
2810
+ process.exit(1);
2811
+ }
2812
+ });
2813
+ program2.command("kb-status").description("Check the status of a Knowledge Base draft").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--draft-id <id>", "Knowledge draft ID to inspect").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details").action(async (options) => {
2814
+ const logger = createLogger(options.verbose);
2815
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
2816
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
2817
+ if (!options.org) {
2818
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
2819
+ process.exit(1);
2820
+ }
2821
+ if (!options.project) {
2822
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
2823
+ process.exit(1);
2824
+ }
2825
+ try {
2826
+ let org;
2827
+ try {
2828
+ org = await api.getOrg(options.org);
2829
+ } catch (err) {
2830
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2831
+ process.exit(1);
2832
+ }
2833
+ let project;
2834
+ try {
2835
+ project = await api.getProject(org.id, options.project);
2836
+ } catch (err) {
2837
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2838
+ process.exit(1);
2839
+ }
2840
+ let draft;
2841
+ try {
2842
+ draft = await api.getKnowledgeDraft(org.id, project.id, options.draftId);
2843
+ } catch (err) {
2844
+ logger.error(`Error fetching draft: ${err instanceof Error ? err.message : String(err)}`);
2845
+ process.exit(1);
2846
+ }
2847
+ logger.info(`
2848
+ Knowledge draft ${draft.id}`);
2849
+ logger.info(` Status : ${draft.status}`);
2850
+ logger.info(` Documents: ${draft.sources.length}`);
2851
+ logger.info(` Created : ${new Date(draft.createdAt).toLocaleString()}`);
2852
+ if (draft.generated) {
2853
+ const g = draft.generated;
2854
+ logger.info(`
2855
+ Analysis results:`);
2856
+ logger.info(` Documents annotated : ${g.documents.length}`);
2857
+ logger.info(` Entities extracted : ${g.entities.length}`);
2858
+ logger.info(` Relationships : ${g.relationships.length}`);
2859
+ logger.info(` Suggested KB tools : ${g.suggestedTools.length}`);
2860
+ } else if (draft.status === "processing") {
2861
+ logger.info(`
2862
+ Still processing \u2014 run again to check progress.`);
2863
+ }
2864
+ logger.info("");
2865
+ } catch (err) {
2866
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
2867
+ process.exit(1);
2868
+ }
2869
+ });
2870
+ program2.command("kb-approve").description("Approve a ready Knowledge Base draft and publish it as a new layer version").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--draft-id <id>", "Knowledge draft ID to approve").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details").action(async (options) => {
2871
+ const logger = createLogger(options.verbose);
2872
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
2873
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
2874
+ if (!options.org) {
2875
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
2876
+ process.exit(1);
2877
+ }
2878
+ if (!options.project) {
2879
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
2880
+ process.exit(1);
2881
+ }
2882
+ try {
2883
+ let org;
2884
+ try {
2885
+ org = await api.getOrg(options.org);
2886
+ } catch (err) {
2887
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2888
+ process.exit(1);
2889
+ }
2890
+ let project;
2891
+ try {
2892
+ project = await api.getProject(org.id, options.project);
2893
+ } catch (err) {
2894
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2895
+ process.exit(1);
2896
+ }
2897
+ logger.info("Fetching draft...");
2898
+ let draft;
2899
+ try {
2900
+ draft = await api.getKnowledgeDraft(org.id, project.id, options.draftId);
2901
+ } catch (err) {
2902
+ logger.error(`Error fetching draft: ${err instanceof Error ? err.message : String(err)}`);
2903
+ process.exit(1);
2904
+ }
2905
+ if (draft.status === "processing") {
2906
+ logger.error("Error: Draft is still processing. Wait for it to finish or poll with kb-status.");
2907
+ process.exit(1);
2908
+ }
2909
+ if (draft.status === "failed") {
2910
+ logger.error("Error: Draft processing failed \u2014 cannot approve a failed draft.");
2911
+ process.exit(1);
2912
+ }
2913
+ if (draft.status === "approved") {
2914
+ logger.error("Error: Draft is already approved.");
2915
+ process.exit(1);
2916
+ }
2917
+ if (!draft.generated) {
2918
+ logger.error("Error: Draft has no generated content to approve.");
2919
+ process.exit(1);
2920
+ }
2921
+ logger.info("Approving draft...");
2922
+ let result;
2923
+ try {
2924
+ result = await api.approveKnowledgeDraft(org.id, project.id, draft.id, draft.generated);
2925
+ } catch (err) {
2926
+ logger.error(`Error approving draft: ${err instanceof Error ? err.message : String(err)}`);
2927
+ process.exit(1);
2928
+ }
2929
+ logger.info(`
2930
+ \u2713 Knowledge layer published as version ${result.version} (id: ${result.id})
2931
+ `);
2932
+ logger.info(` Entities : ${draft.generated.entities.length}`);
2933
+ logger.info(` Relationships: ${draft.generated.relationships.length}`);
2934
+ logger.info(` KB tools : ${draft.generated.suggestedTools.length}
2935
+ `);
2936
+ } catch (err) {
2937
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
2938
+ process.exit(1);
2939
+ }
2940
+ });
2941
+ }
2942
+
2943
+ // src/commands/extract.ts
2944
+ import * as fs15 from "fs/promises";
2945
+
2946
+ // src/extract-api-client.ts
2947
+ import * as fs14 from "fs/promises";
2948
+ import * as path3 from "path";
2949
+ var ExtractApiClient = class {
2950
+ baseUrl;
2951
+ apiKey;
2952
+ logger;
2953
+ constructor(baseUrl, logger, apiKey) {
2954
+ this.baseUrl = baseUrl;
2955
+ this.apiKey = apiKey;
2956
+ this.logger = logger;
2957
+ }
2958
+ // TODO(K): add unit tests for ExtractApiClient methods
2959
+ authHeaders() {
2960
+ return this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {};
2961
+ }
2962
+ async request(method, url, options = {}) {
2963
+ let response;
2964
+ try {
2965
+ response = await fetch(url, {
2966
+ method,
2967
+ headers: { ...this.authHeaders(), ...options.headers },
2968
+ body: options.body
2969
+ });
2970
+ } catch (err) {
2971
+ const message = err instanceof Error ? err.message : String(err);
2972
+ if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
2973
+ throw new Error(`Connection refused to ${this.baseUrl}. Check your BRAINBOX_API_URL.`);
2974
+ }
2975
+ throw err;
2976
+ }
2977
+ if (!response.ok) {
2978
+ const text = await response.text().catch(() => "");
2979
+ this.logger.debug(`${method} ${url}: ${response.status} ${text}`);
2980
+ throw new Error(`API error ${response.status}: ${text}`);
2981
+ }
2982
+ return response.json();
2983
+ }
2984
+ async getOrCreateProject(name) {
2985
+ const url = `${this.baseUrl}/extract/projects`;
2986
+ this.logger.debug(`getOrCreateProject: POST ${url} { name: "${name}" }`);
2987
+ const project = await this.request("POST", url, {
2988
+ headers: { "Content-Type": "application/json", Accept: "application/json" },
2989
+ body: JSON.stringify({ name })
2990
+ });
2991
+ this.logger.debug(`getOrCreateProject: resolved project`, project);
2992
+ return project;
2993
+ }
2994
+ async createExtraction(projectId, filePath, templateName) {
2995
+ const url = `${this.baseUrl}/extract/projects/${projectId}/extractions`;
2996
+ this.logger.debug(`createExtraction: POST ${url} file="${filePath}" template="${templateName ?? "auto-classify"}"`);
2997
+ const fileBuffer = await fs14.readFile(filePath);
2998
+ const fileName = path3.basename(filePath);
2999
+ const blob = new Blob([fileBuffer]);
3000
+ const formData = new FormData();
3001
+ formData.append("file", blob, fileName);
3002
+ if (templateName !== void 0) {
3003
+ formData.append("template", templateName);
3004
+ }
3005
+ let response;
3006
+ try {
3007
+ response = await fetch(url, { method: "POST", body: formData, headers: this.authHeaders() });
3008
+ } catch (err) {
3009
+ const message = err instanceof Error ? err.message : String(err);
3010
+ if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
3011
+ throw new Error(`Connection refused to ${this.baseUrl}. Check your BRAINBOX_API_URL.`);
3012
+ }
3013
+ throw err;
3014
+ }
3015
+ if (!response.ok) {
3016
+ const text = await response.text().catch(() => "");
3017
+ this.logger.debug(`createExtraction: ${response.status} ${text}`);
3018
+ if (response.status === 404 && text.toLowerCase().includes("template")) {
3019
+ throw new Error(`Template not found: "${templateName ?? "auto-classify"}". Run \`brainbox connect\` first to set up your project, or check the template name.`);
3020
+ }
3021
+ throw new Error(`API error ${response.status}: ${text}`);
3022
+ }
3023
+ const extraction = await response.json();
3024
+ this.logger.debug(`createExtraction: created`, extraction);
3025
+ return extraction;
3026
+ }
3027
+ async getExtraction(projectId, extractionId) {
3028
+ const url = `${this.baseUrl}/extract/projects/${projectId}/extractions/${extractionId}`;
3029
+ this.logger.debug(`getExtraction: GET ${url}`);
3030
+ const extraction = await this.request("GET", url, {
3031
+ headers: { Accept: "application/json" }
3032
+ });
3033
+ this.logger.debug(`getExtraction: status=${extraction.status}`);
3034
+ return extraction;
3035
+ }
3036
+ async listTemplates() {
3037
+ const url = `${this.baseUrl}/extract/templates`;
3038
+ this.logger.debug(`listTemplates: GET ${url}`);
3039
+ return this.request("GET", url, {
3040
+ headers: { Accept: "application/json" }
3041
+ });
3042
+ }
3043
+ async updateExtraction(projectId, extractionId, patch) {
3044
+ const url = `${this.baseUrl}/extract/projects/${projectId}/extractions/${extractionId}`;
3045
+ this.logger.debug(`updateExtraction: PATCH ${url}`, patch);
3046
+ return this.request("PATCH", url, {
3047
+ headers: { "Content-Type": "application/json", Accept: "application/json" },
3048
+ body: JSON.stringify(patch)
3049
+ });
3050
+ }
3051
+ async listDataset(projectId, templateName) {
3052
+ const url = `${this.baseUrl}/extract/projects/${projectId}/datasets/${encodeURIComponent(templateName)}`;
3053
+ this.logger.debug(`listDataset: GET ${url}`);
3054
+ return this.request("GET", url, {
3055
+ headers: { Accept: "application/json" }
3056
+ });
3057
+ }
3058
+ async pollUntilReady(projectId, extractionId, intervalMs = 2e3, maxWaitMs = 12e4) {
3059
+ const deadline = Date.now() + maxWaitMs;
3060
+ while (Date.now() < deadline) {
3061
+ const extraction = await this.getExtraction(projectId, extractionId);
3062
+ if (extraction.status !== "processing") {
3063
+ if (extraction.status === "failed") {
3064
+ const notes = extraction.extractionNotes ?? "Unknown extraction error.";
3065
+ throw new Error(`Extraction failed: ${notes}`);
3066
+ }
3067
+ return extraction;
3068
+ }
3069
+ const remaining = deadline - Date.now();
3070
+ if (remaining <= 0) break;
3071
+ await new Promise((resolve4) => setTimeout(resolve4, Math.min(intervalMs, remaining)));
3072
+ }
3073
+ throw new Error(`Extraction timed out after ${maxWaitMs / 1e3}s. The extract-api may still be processing \u2014 check the review UI.`);
3074
+ }
3075
+ };
3076
+
3077
+ // src/commands/extract.ts
3078
+ function registerExtractCommands(program2) {
3079
+ program2.command("extract").description("Extract structured data from a document using a known template").argument("<file>", "Path to the document to extract from (.pdf, .eml, .txt, etc.)").option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--template <name>", "Template name to use for extraction (if not specified, LLM will classify)").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print verbose output").action(async (file, options) => {
3080
+ const logger = createLogger(options.verbose);
3081
+ if (!options.project) {
3082
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3083
+ process.exit(1);
3084
+ }
3085
+ try {
3086
+ await fs15.access(file);
3087
+ } catch {
3088
+ logger.error(`Error: File not found: "${file}"`);
3089
+ process.exit(1);
3090
+ }
3091
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3092
+ const api = new ExtractApiClient(options.apiUrl, logger, apiKey);
3093
+ let project;
3094
+ try {
3095
+ project = await api.getOrCreateProject(options.project);
3096
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3097
+ } catch (err) {
3098
+ const message = err instanceof Error ? err.message : String(err);
3099
+ if (message.includes("Is the extract-api running")) {
3100
+ logger.error(`Error: Could not connect to extract-api. Check your BRAINBOX_API_URL.`);
3101
+ } else {
3102
+ logger.error(`Error communicating with extract-api: ${message}`);
3103
+ }
3104
+ process.exit(1);
3105
+ }
3106
+ const templateLabel = options.template ?? "auto-classify";
3107
+ logger.info(`Submitting ${file} for extraction (template: ${templateLabel})...`);
3108
+ let extractionResponse;
3109
+ try {
3110
+ extractionResponse = await api.createExtraction(project.id, file, options.template);
3111
+ logger.debug(`Extraction created: id=${extractionResponse.extractionId} template=${extractionResponse.templateName}`);
3112
+ } catch (err) {
3113
+ const message = err instanceof Error ? err.message : String(err);
3114
+ if (message.includes("Is the extract-api running")) {
3115
+ logger.error(`Error: Could not connect to extract-api. Check your BRAINBOX_API_URL.`);
3116
+ } else if (message.includes("Template not found")) {
3117
+ logger.error(`Error: ${message}`);
3118
+ } else {
3119
+ logger.error(`Error submitting extraction: ${message}`);
3120
+ }
3121
+ process.exit(1);
3122
+ }
3123
+ logger.info("Extracting...");
3124
+ let extraction;
3125
+ try {
3126
+ extraction = await api.pollUntilReady(project.id, extractionResponse.extractionId);
3127
+ } catch (err) {
3128
+ const message = err instanceof Error ? err.message : String(err);
3129
+ if (message.startsWith("Extraction failed:")) {
3130
+ logger.error(message);
3131
+ } else {
3132
+ logger.error(`Error during extraction: ${message}`);
3133
+ }
3134
+ process.exit(1);
3135
+ }
3136
+ const fieldCount = extraction.extractedData !== null ? Object.keys(extraction.extractedData).length : 0;
3137
+ const scores = extraction.confidenceScores !== null ? Object.values(extraction.confidenceScores) : [];
3138
+ const avgConfidence = scores.length > 0 ? (scores.reduce((sum, s) => sum + s, 0) / scores.length).toFixed(2) : "n/a";
3139
+ const flagged = extraction.flaggedFields.length > 0 ? extraction.flaggedFields.join(", ") : "none";
3140
+ logger.info(`
3141
+ Extracted ${extraction.templateName} from ${extraction.documentName} (${fieldCount} fields, confidence avg: ${avgConfidence}).`);
3142
+ logger.info(`Flagged fields (low confidence): ${flagged}`);
3143
+ const reviewUrl = `${options.apiUrl}/extract/projects/${encodeURIComponent(project.id)}/extractions/${encodeURIComponent(extractionResponse.extractionId)}/review`;
3144
+ logger.info(`Review: ${reviewUrl}`);
3145
+ });
3146
+ program2.command("extract-templates").description("List available extraction templates").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print verbose output").action(async (options) => {
3147
+ const logger = createLogger(options.verbose);
3148
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3149
+ const api = new ExtractApiClient(options.apiUrl, logger, apiKey);
3150
+ let templates;
3151
+ try {
3152
+ templates = await api.listTemplates();
3153
+ } catch (err) {
3154
+ logger.error(`Error fetching templates: ${err instanceof Error ? err.message : String(err)}`);
3155
+ process.exit(1);
3156
+ }
3157
+ logger.info(`
3158
+ Available extraction templates:
3159
+ `);
3160
+ for (const t of templates) {
3161
+ const tag = t.isBuiltIn ? " (built-in)" : "";
3162
+ logger.info(` ${t.name.padEnd(20)} ${t.description}${tag}`);
3163
+ }
3164
+ logger.info("");
3165
+ });
3166
+ program2.command("extract-approve").description("Approve an extraction and add it to the dataset").option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--extraction-id <id>", "Extraction ID to approve").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print verbose output").action(async (options) => {
3167
+ const logger = createLogger(options.verbose);
3168
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3169
+ const api = new ExtractApiClient(options.apiUrl, logger, apiKey);
3170
+ if (!options.project) {
3171
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3172
+ process.exit(1);
3173
+ }
3174
+ let project;
3175
+ try {
3176
+ project = await api.getOrCreateProject(options.project);
3177
+ } catch (err) {
3178
+ logger.error(`Error resolving project: ${err instanceof Error ? err.message : String(err)}`);
3179
+ process.exit(1);
3180
+ }
3181
+ let extraction;
3182
+ try {
3183
+ extraction = await api.updateExtraction(project.id, options.extractionId, { status: "approved" });
3184
+ } catch (err) {
3185
+ logger.error(`Error approving extraction: ${err instanceof Error ? err.message : String(err)}`);
3186
+ process.exit(1);
3187
+ }
3188
+ logger.info(`
3189
+ \u2713 Extraction ${extraction.id} approved (template: ${extraction.templateName}).
3190
+ `);
3191
+ });
3192
+ program2.command("extract-reject").description("Reject an extraction").option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--extraction-id <id>", "Extraction ID to reject").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print verbose output").action(async (options) => {
3193
+ const logger = createLogger(options.verbose);
3194
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3195
+ const api = new ExtractApiClient(options.apiUrl, logger, apiKey);
3196
+ if (!options.project) {
3197
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3198
+ process.exit(1);
3199
+ }
3200
+ let project;
3201
+ try {
3202
+ project = await api.getOrCreateProject(options.project);
3203
+ } catch (err) {
3204
+ logger.error(`Error resolving project: ${err instanceof Error ? err.message : String(err)}`);
3205
+ process.exit(1);
3206
+ }
3207
+ let extraction;
3208
+ try {
3209
+ extraction = await api.updateExtraction(project.id, options.extractionId, { status: "rejected" });
3210
+ } catch (err) {
3211
+ logger.error(`Error rejecting extraction: ${err instanceof Error ? err.message : String(err)}`);
3212
+ process.exit(1);
3213
+ }
3214
+ logger.info(`
3215
+ \u2713 Extraction ${extraction.id} rejected.
3216
+ `);
3217
+ });
3218
+ }
3219
+
3220
+ // src/commands/structured.ts
3221
+ import * as fs16 from "fs/promises";
3222
+
3223
+ // src/schema-reader.ts
3224
+ import pg from "pg";
3225
+ var { Client: Client3 } = pg;
3226
+ async function introspectSchema(connectionString) {
3227
+ const client = new Client3({ connectionString });
3228
+ await client.connect();
3229
+ try {
3230
+ const tablesResult = await client.query(`
3231
+ SELECT table_name, table_schema
3232
+ FROM information_schema.tables
3233
+ WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
3234
+ AND table_type = 'BASE TABLE'
3235
+ ORDER BY table_name
3236
+ `);
3237
+ const tables = [];
3238
+ for (const tableRow of tablesResult.rows) {
3239
+ const tableName = tableRow.table_name;
3240
+ const tableSchema = tableRow.table_schema;
3241
+ const columnsResult = await client.query(
3242
+ `SELECT column_name, data_type, is_nullable, column_default
3243
+ FROM information_schema.columns
3244
+ WHERE table_schema = $1 AND table_name = $2
3245
+ ORDER BY ordinal_position`,
3246
+ [tableSchema, tableName]
3247
+ );
3248
+ const pkResult = await client.query(
3249
+ `SELECT kcu.column_name
3250
+ FROM information_schema.table_constraints tc
3251
+ JOIN information_schema.key_column_usage kcu
3252
+ ON tc.constraint_name = kcu.constraint_name
3253
+ WHERE tc.constraint_type = 'PRIMARY KEY'
3254
+ AND tc.table_schema = $1
3255
+ AND tc.table_name = $2`,
3256
+ [tableSchema, tableName]
3257
+ );
3258
+ const primaryKeyColumns = new Set(pkResult.rows.map((r) => r.column_name));
3259
+ const fkResult = await client.query(
3260
+ `SELECT kcu.column_name, ccu.table_name AS foreign_table_name, ccu.column_name AS foreign_column_name
3261
+ FROM information_schema.table_constraints tc
3262
+ JOIN information_schema.key_column_usage kcu
3263
+ ON tc.constraint_name = kcu.constraint_name
3264
+ JOIN information_schema.constraint_column_usage ccu
3265
+ ON tc.constraint_name = ccu.constraint_name
3266
+ WHERE tc.constraint_type = 'FOREIGN KEY'
3267
+ AND tc.table_schema = $1
3268
+ AND tc.table_name = $2`,
3269
+ [tableSchema, tableName]
3270
+ );
3271
+ const fkMap = /* @__PURE__ */ new Map();
3272
+ for (const fk of fkResult.rows) {
3273
+ fkMap.set(fk.column_name, {
3274
+ table: fk.foreign_table_name,
3275
+ column: fk.foreign_column_name
3276
+ });
3277
+ }
3278
+ const columns = columnsResult.rows.map((col) => {
3279
+ const fkRef = fkMap.get(col.column_name);
3280
+ const column = {
3281
+ name: col.column_name,
3282
+ type: col.data_type,
3283
+ nullable: col.is_nullable === "YES",
3284
+ isPrimaryKey: primaryKeyColumns.has(col.column_name),
3285
+ isForeignKey: fkMap.has(col.column_name)
3286
+ };
3287
+ if (fkRef !== void 0) {
3288
+ column.references = fkRef;
3289
+ }
3290
+ if (col.column_default !== null) {
3291
+ column.defaultValue = col.column_default;
3292
+ }
3293
+ return column;
3294
+ });
3295
+ const indexResult = await client.query(
3296
+ `SELECT i.relname AS index_name, a.attname AS column_name, ix.indisunique AS is_unique
3297
+ FROM pg_class t
3298
+ JOIN pg_index ix ON t.oid = ix.indrelid
3299
+ JOIN pg_class i ON i.oid = ix.indexrelid
3300
+ JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
3301
+ WHERE t.relkind = 'r' AND t.relname = $1
3302
+ ORDER BY i.relname`,
3303
+ [tableName]
3304
+ );
3305
+ const indexMap = /* @__PURE__ */ new Map();
3306
+ for (const idxRow of indexResult.rows) {
3307
+ const existing = indexMap.get(idxRow.index_name);
3308
+ if (existing !== void 0) {
3309
+ existing.columns.push(idxRow.column_name);
3310
+ } else {
3311
+ indexMap.set(idxRow.index_name, {
3312
+ columns: [idxRow.column_name],
3313
+ isUnique: idxRow.is_unique
3314
+ });
3315
+ }
3316
+ }
3317
+ const indexes = Array.from(indexMap.entries()).map(([name, val]) => ({
3318
+ name,
3319
+ columns: val.columns,
3320
+ isUnique: val.isUnique
3321
+ }));
3322
+ const constraintResult = await client.query(
3323
+ `SELECT tc.constraint_name, tc.constraint_type, kcu.column_name
3324
+ FROM information_schema.table_constraints tc
3325
+ JOIN information_schema.key_column_usage kcu
3326
+ ON tc.constraint_name = kcu.constraint_name
3327
+ WHERE tc.table_schema = $1 AND tc.table_name = $2`,
3328
+ [tableSchema, tableName]
3329
+ );
3330
+ const constraintMap = /* @__PURE__ */ new Map();
3331
+ for (const cRow of constraintResult.rows) {
3332
+ const existing = constraintMap.get(cRow.constraint_name);
3333
+ if (existing !== void 0) {
3334
+ existing.columns.push(cRow.column_name);
3335
+ } else {
3336
+ constraintMap.set(cRow.constraint_name, {
3337
+ type: cRow.constraint_type,
3338
+ columns: [cRow.column_name]
3339
+ });
3340
+ }
3341
+ }
3342
+ const constraints = Array.from(constraintMap.entries()).map(([name, val]) => {
3343
+ const type = val.type;
3344
+ const constraint = {
3345
+ name,
3346
+ type,
3347
+ columns: val.columns
3348
+ };
3349
+ if (type === "FOREIGN KEY") {
3350
+ const firstCol = val.columns[0];
3351
+ if (firstCol !== void 0) {
3352
+ const fkRef = fkMap.get(firstCol);
3353
+ if (fkRef !== void 0) {
3354
+ constraint.referencedTable = fkRef.table;
3355
+ constraint.referencedColumns = [fkRef.column];
3356
+ }
3357
+ }
3358
+ }
3359
+ return constraint;
3360
+ }).filter(
3361
+ (c) => c.type === "PRIMARY KEY" || c.type === "FOREIGN KEY" || c.type === "UNIQUE" || c.type === "CHECK"
3362
+ );
3363
+ tables.push({
3364
+ name: tableName,
3365
+ schema: tableSchema,
3366
+ columns,
3367
+ indexes,
3368
+ constraints
3369
+ });
3370
+ }
3371
+ return {
3372
+ tables,
3373
+ extractedAt: (/* @__PURE__ */ new Date()).toISOString()
3374
+ };
3375
+ } finally {
3376
+ await client.end();
3377
+ }
3378
+ }
3379
+
3380
+ // src/commands/structured.ts
3381
+ function registerStructuredCommands(program2) {
3382
+ program2.command("connect").description("Introspect a Postgres database and submit a semantic layer draft").requiredOption("--db <url>", "Postgres connection string").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--queries <dir>", "Directory containing .sql files").option("--query-file <file>", "Single SQL file to parse").option("--tables <names>", "Comma-separated list of tables to include (default: all)").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--ui-url <url>", "BrainBox web UI base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--log-format <format>", "Log output format: text or json", "text").option("--verbose", "Print full request/response details sent to the BrainBox API (also enabled by DEBUG=brainbox)").action(async (options) => {
3383
+ const startTime = Date.now();
3384
+ const logger = createLogger(options.verbose, options.logFormat);
3385
+ if (!options.org) {
3386
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3387
+ process.exit(1);
3388
+ }
3389
+ if (!options.project) {
3390
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3391
+ process.exit(1);
3392
+ }
3393
+ if (logger.isVerbose) {
3394
+ logger.debug("CLI options", {
3395
+ org: options.org,
3396
+ project: options.project,
3397
+ apiUrl: options.apiUrl,
3398
+ uiUrl: options.uiUrl,
3399
+ queries: options.queries,
3400
+ queryFile: options.queryFile,
3401
+ apiKey: options.apiKey ? `...${options.apiKey.slice(-4)}` : "(none)"
3402
+ // db intentionally omitted — contains credentials
3403
+ });
3404
+ }
3405
+ try {
3406
+ logger.info("Introspecting schema...");
3407
+ let schema;
3408
+ try {
3409
+ schema = await introspectSchema(options.db);
3410
+ if (options.tables !== void 0) {
3411
+ const allowed = new Set(options.tables.split(",").map((t) => t.trim()));
3412
+ schema.tables = schema.tables.filter((t) => allowed.has(t.name));
3413
+ }
3414
+ logger.debug(
3415
+ `Schema introspected: ${schema.tables.length} tables, extractedAt=${schema.extractedAt}`,
3416
+ logger.isVerbose ? schema : void 0
3417
+ );
3418
+ } catch (err) {
3419
+ const message = err instanceof Error ? err.message : String(err);
3420
+ if (message.includes("password authentication failed") || message.includes("auth")) {
3421
+ logger.error("Error: Check your Postgres credentials.");
3422
+ } else if (message.includes("ECONNREFUSED") || message.includes("connect")) {
3423
+ logger.error("Error: Could not connect to Postgres. Check your connection string.");
3424
+ } else {
3425
+ logger.error(`Error introspecting schema: ${message}`);
3426
+ }
3427
+ process.exit(1);
3428
+ }
3429
+ logger.info("Parsing SQL files...");
3430
+ const queries = [];
3431
+ if (options.queries !== void 0) {
3432
+ try {
3433
+ const parsed = await parseSqlDirectory(options.queries);
3434
+ queries.push(...parsed);
3435
+ logger.debug(`Parsed ${parsed.length} queries from directory "${options.queries}"`);
3436
+ } catch (err) {
3437
+ logger.warn(
3438
+ `Could not read SQL directory "${options.queries}": ${err instanceof Error ? err.message : String(err)}`
3439
+ );
3440
+ }
3441
+ }
3442
+ if (options.queryFile !== void 0) {
3443
+ try {
3444
+ const content = await fs16.readFile(options.queryFile, "utf-8");
3445
+ const parsed = parseSqlFile(options.queryFile, content);
3446
+ queries.push(parsed);
3447
+ logger.debug(`Parsed query "${parsed.name}" from file "${options.queryFile}"`);
3448
+ } catch (err) {
3449
+ logger.warn(
3450
+ `Could not read SQL file "${options.queryFile}": ${err instanceof Error ? err.message : String(err)}`
3451
+ );
3452
+ }
3453
+ }
3454
+ if (logger.isVerbose && queries.length > 0) {
3455
+ logger.debug("Parsed queries summary", queries.map((q) => ({
3456
+ name: q.name,
3457
+ tables: q.tablesReferenced,
3458
+ params: q.parameters.length
3459
+ })));
3460
+ }
3461
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3462
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3463
+ logger.info("Ensuring org exists...");
3464
+ let org;
3465
+ try {
3466
+ org = await api.getOrCreateOrg(options.org);
3467
+ logger.debug(`Org resolved: id=${org.id} name="${org.name}"`);
3468
+ } catch (err) {
3469
+ const message = err instanceof Error ? err.message : String(err);
3470
+ if (message.includes("Connection refused") || message.includes("ECONNREFUSED")) {
3471
+ logger.error("Error: Is the BrainBox API running?");
3472
+ } else {
3473
+ logger.error(`Error communicating with API: ${message}`);
3474
+ }
3475
+ process.exit(1);
3476
+ }
3477
+ logger.info("Ensuring project exists...");
3478
+ let project;
3479
+ try {
3480
+ project = await api.getOrCreateProject(org.id, options.project);
3481
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3482
+ } catch (err) {
3483
+ logger.error(
3484
+ `Error ensuring project: ${err instanceof Error ? err.message : String(err)}`
3485
+ );
3486
+ process.exit(1);
3487
+ }
3488
+ logger.info("Submitting schema + queries...");
3489
+ let draft;
3490
+ try {
3491
+ draft = await api.submitDraft(org.id, project.id, schema, queries);
3492
+ logger.debug("Draft submission response", draft);
3493
+ } catch (err) {
3494
+ logger.error(
3495
+ `Error submitting draft: ${err instanceof Error ? err.message : String(err)}`
3496
+ );
3497
+ process.exit(1);
3498
+ }
3499
+ logger.info(
3500
+ `
3501
+ \u2713 Draft submitted (id: ${draft.draftId}, ${draft.tableCount} tables, ${draft.columnCount} columns, ${draft.queryCount} queries).`
3502
+ );
3503
+ logger.info("Starting context generation...");
3504
+ let ctx;
3505
+ try {
3506
+ ctx = await api.createContext(org.id, project.id, { type: "semantic", draftId: draft.draftId });
3507
+ logger.info(`\u2713 Context generation started (id: ${ctx.contextId}).`);
3508
+ } catch (err) {
3509
+ logger.warn(`Warning: could not start context generation: ${err instanceof Error ? err.message : String(err)}`);
3510
+ logger.info(` Draft is saved. To generate later, use the review UI.`);
3511
+ }
3512
+ logger.info(`
3513
+ Review at: ${options.uiUrl}/orgs/${org.id}/projects/${project.id}/drafts/${draft.draftId}
3514
+ `);
3515
+ await writeAuditLog({
3516
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
3517
+ command: "connect",
3518
+ org: options.org,
3519
+ project: options.project,
3520
+ apiUrl: options.apiUrl,
3521
+ payload: { tables: draft.tableCount, columns: draft.columnCount, queries: draft.queryCount },
3522
+ draftId: draft.draftId,
3523
+ durationMs: Date.now() - startTime
3524
+ });
3525
+ } catch (err) {
3526
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3527
+ process.exit(1);
3528
+ }
3529
+ });
3530
+ program2.command("push").description("Submit a semantic layer from a JSON file (bypasses LLM pipeline)").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--layer <file>", "Path to layer JSON file ({ tables, queries, tools })").option("--publish", "Publish immediately instead of submitting for review", false).option("--source-layer-id <id>", "ID of the layer this is forked from (for lineage tracking)").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--ui-url <url>", "BrainBox web UI base URL (or set BRAINBOX_API_URL env var)", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--log-format <format>", "Log output format: text or json", "text").option("--verbose", "Print full request/response details sent to the BrainBox API (also enabled by DEBUG=brainbox)").action(async (options) => {
3531
+ const startTime = Date.now();
3532
+ const logger = createLogger(options.verbose, options.logFormat);
3533
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3534
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3535
+ if (!options.org) {
3536
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3537
+ process.exit(1);
3538
+ }
3539
+ if (!options.project) {
3540
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3541
+ process.exit(1);
3542
+ }
3543
+ try {
3544
+ let layerContent;
3545
+ try {
3546
+ layerContent = await fs16.readFile(options.layer, "utf-8");
3547
+ } catch (err) {
3548
+ logger.error(`Error reading layer file "${options.layer}": ${err instanceof Error ? err.message : String(err)}`);
3549
+ process.exit(1);
3550
+ }
3551
+ let layerBody;
3552
+ try {
3553
+ layerBody = JSON.parse(layerContent);
3554
+ } catch {
3555
+ logger.error(`Error: "${options.layer}" is not valid JSON`);
3556
+ process.exit(1);
3557
+ }
3558
+ if (!Array.isArray(layerBody.tables) || !Array.isArray(layerBody.queries) || !Array.isArray(layerBody.tools)) {
3559
+ logger.error('Error: layer file must contain "tables", "queries", and "tools" arrays');
3560
+ process.exit(1);
3561
+ }
3562
+ logger.info("Ensuring org exists...");
3563
+ let org;
3564
+ try {
3565
+ org = await api.getOrCreateOrg(options.org);
3566
+ logger.debug(`Org resolved: id=${org.id} name="${org.name}"`);
3567
+ } catch (err) {
3568
+ logger.error(`Error communicating with API: ${err instanceof Error ? err.message : String(err)}`);
3569
+ process.exit(1);
3570
+ }
3571
+ logger.info("Ensuring project exists...");
3572
+ let project;
3573
+ try {
3574
+ project = await api.getOrCreateProject(org.id, options.project);
3575
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3576
+ } catch (err) {
3577
+ logger.error(`Error ensuring project: ${err instanceof Error ? err.message : String(err)}`);
3578
+ process.exit(1);
3579
+ }
3580
+ const publish = options.publish;
3581
+ logger.info(publish ? "Publishing layer..." : "Submitting layer for review...");
3582
+ logger.info(` Payload: ${layerBody.tables.length} tables, ${layerBody.queries.length} queries, ${layerBody.tools.length} tools`);
3583
+ let result;
3584
+ try {
3585
+ result = await api.submitLayer(org.id, project.id, {
3586
+ tables: layerBody.tables,
3587
+ queries: layerBody.queries,
3588
+ tools: layerBody.tools,
3589
+ publish,
3590
+ ...options.sourceLayerId ? { sourceLayerId: options.sourceLayerId } : {}
3591
+ });
3592
+ } catch (err) {
3593
+ logger.error(`Error submitting layer: ${err instanceof Error ? err.message : String(err)}`);
3594
+ process.exit(1);
3595
+ }
3596
+ if (publish && result.version !== void 0) {
3597
+ logger.info(`
3598
+ \u2713 Layer published as version ${result.version} (id: ${result.id})
3599
+ `);
3600
+ await writeAuditLog({
3601
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
3602
+ command: "push",
3603
+ org: options.org,
3604
+ project: options.project,
3605
+ apiUrl: options.apiUrl,
3606
+ payload: { tables: layerBody.tables.length, queries: layerBody.queries.length },
3607
+ layerId: result.id,
3608
+ version: result.version,
3609
+ durationMs: Date.now() - startTime
3610
+ });
3611
+ } else if (!publish && result.draftId !== void 0) {
3612
+ logger.info(`
3613
+ \u2713 Layer submitted for review (draftId: ${result.draftId})
3614
+ `);
3615
+ logger.info(`Open to review: ${options.uiUrl}/orgs/${org.id}/projects/${project.id}/drafts/${result.draftId}`);
3616
+ await writeAuditLog({
3617
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
3618
+ command: "push",
3619
+ org: options.org,
3620
+ project: options.project,
3621
+ apiUrl: options.apiUrl,
3622
+ payload: { tables: layerBody.tables.length, queries: layerBody.queries.length },
3623
+ draftId: result.draftId,
3624
+ durationMs: Date.now() - startTime
3625
+ });
3626
+ } else {
3627
+ logger.info("\n\u2713 Done\n");
3628
+ }
3629
+ } catch (err) {
3630
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3631
+ process.exit(1);
3632
+ }
3633
+ });
3634
+ program2.command("pull").description("Download the active semantic layer to a local JSON file").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--out <file>", "Output file path", "layer.json").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details sent to the BrainBox API (also enabled by DEBUG=brainbox)").action(async (options) => {
3635
+ const logger = createLogger(options.verbose);
3636
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3637
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3638
+ if (!options.org) {
3639
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3640
+ process.exit(1);
3641
+ }
3642
+ if (!options.project) {
3643
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3644
+ process.exit(1);
3645
+ }
3646
+ try {
3647
+ let org;
3648
+ try {
3649
+ org = await api.getOrg(options.org);
3650
+ logger.debug(`Org resolved: id=${org.id} name="${org.name}"`);
3651
+ } catch (err) {
3652
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3653
+ process.exit(1);
3654
+ }
3655
+ let project;
3656
+ try {
3657
+ project = await api.getProject(org.id, options.project);
3658
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3659
+ } catch (err) {
3660
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3661
+ process.exit(1);
3662
+ }
3663
+ logger.info("Fetching active layer...");
3664
+ let layer;
3665
+ try {
3666
+ layer = await api.getActiveLayer(org.id, project.id);
3667
+ } catch (err) {
3668
+ const message = err instanceof Error ? err.message : String(err);
3669
+ if (isNotFoundError(err)) {
3670
+ logger.error("Error: No active semantic layer found for this project.");
3671
+ } else {
3672
+ logger.error(`Error fetching layer: ${message}`);
3673
+ }
3674
+ process.exit(1);
3675
+ }
3676
+ try {
3677
+ await fs16.writeFile(options.out, JSON.stringify(layer, null, 2), "utf-8");
3678
+ } catch (err) {
3679
+ logger.error(`Error writing file "${options.out}": ${err instanceof Error ? err.message : String(err)}`);
3680
+ process.exit(1);
3681
+ }
3682
+ logger.info(`
3683
+ \u2713 Active layer (version ${layer.version}, origin: ${layer.origin}) saved to ${options.out}
3684
+ `);
3685
+ logger.info(` Tables: ${layer.tables.length}, Queries: ${layer.queries.length}, Tools: ${layer.tools.length}`);
3686
+ } catch (err) {
3687
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3688
+ process.exit(1);
3689
+ }
3690
+ });
3691
+ program2.command("versions").description("List all semantic layer versions for a project").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details sent to the BrainBox API (also enabled by DEBUG=brainbox)").action(async (options) => {
3692
+ const logger = createLogger(options.verbose);
3693
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3694
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3695
+ if (!options.org) {
3696
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3697
+ process.exit(1);
3698
+ }
3699
+ if (!options.project) {
3700
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3701
+ process.exit(1);
3702
+ }
3703
+ try {
3704
+ let org;
3705
+ try {
3706
+ org = await api.getOrg(options.org);
3707
+ logger.debug(`Org resolved: id=${org.id} name="${org.name}"`);
3708
+ } catch (err) {
3709
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3710
+ process.exit(1);
3711
+ }
3712
+ let project;
3713
+ try {
3714
+ project = await api.getProject(org.id, options.project);
3715
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3716
+ } catch (err) {
3717
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3718
+ process.exit(1);
3719
+ }
3720
+ let layers;
3721
+ try {
3722
+ layers = await api.listLayers(org.id, project.id);
3723
+ } catch (err) {
3724
+ logger.error(`Error fetching versions: ${err instanceof Error ? err.message : String(err)}`);
3725
+ process.exit(1);
3726
+ }
3727
+ if (layers.length === 0) {
3728
+ logger.info("No semantic layer versions found for this project.");
3729
+ return;
3730
+ }
3731
+ logger.info(`
3732
+ Semantic layer versions for "${options.project}":
3733
+ `);
3734
+ const originLabels = { llm: "LLM", developer: "Developer", ui_edit: "UI Edit" };
3735
+ for (const layer of layers) {
3736
+ const origin = originLabels[layer.origin] ?? layer.origin;
3737
+ const date = new Date(layer.createdAt).toLocaleDateString();
3738
+ logger.info(` v${layer.version} ${origin.padEnd(10)} ${(layer.createdBy || "\u2014").padEnd(20)} ${date}`);
3739
+ }
3740
+ logger.info("");
3741
+ } catch (err) {
3742
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3743
+ process.exit(1);
3744
+ }
3745
+ });
3746
+ program2.command("activate").description("Set a specific semantic layer version as active").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).requiredOption("--version <number>", "Version number to activate", parseInt).option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--verbose", "Print full request/response details sent to the BrainBox API (also enabled by DEBUG=brainbox)").action(async (options) => {
3747
+ const logger = createLogger(options.verbose);
3748
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3749
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3750
+ if (!options.org) {
3751
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3752
+ process.exit(1);
3753
+ }
3754
+ if (!options.project) {
3755
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3756
+ process.exit(1);
3757
+ }
3758
+ try {
3759
+ if (isNaN(options.version) || options.version < 1) {
3760
+ logger.error("Error: --version must be a positive integer");
3761
+ process.exit(1);
3762
+ }
3763
+ let org;
3764
+ try {
3765
+ org = await api.getOrg(options.org);
3766
+ logger.debug(`Org resolved: id=${org.id} name="${org.name}"`);
3767
+ } catch (err) {
3768
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3769
+ process.exit(1);
3770
+ }
3771
+ let project;
3772
+ try {
3773
+ project = await api.getProject(org.id, options.project);
3774
+ logger.debug(`Project resolved: id=${project.id} name="${project.name}"`);
3775
+ } catch (err) {
3776
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3777
+ process.exit(1);
3778
+ }
3779
+ logger.info(`Activating version ${options.version}...`);
3780
+ let result;
3781
+ try {
3782
+ result = await api.activateVersion(org.id, project.id, options.version);
3783
+ } catch (err) {
3784
+ const message = err instanceof Error ? err.message : String(err);
3785
+ if (isNotFoundError(err)) {
3786
+ logger.error(`Error: Version ${options.version} not found.`);
3787
+ } else {
3788
+ logger.error(`Error activating version: ${message}`);
3789
+ }
3790
+ process.exit(1);
3791
+ }
3792
+ logger.info(`
3793
+ \u2713 Active version set to ${result.activeVersion}
3794
+ `);
3795
+ } catch (err) {
3796
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3797
+ process.exit(1);
3798
+ }
3799
+ });
3800
+ }
3801
+
3802
+ // src/commands/mcp.ts
3803
+ function registerMcpCommands(program2) {
3804
+ program2.command("mcp-connect").description("Ingest tools from an existing MCP server into Brainbox as a connector draft").requiredOption("--server <url>", "MCP server URL to introspect").option("--org <name>", "Organization name (or set BRAINBOX_ORG env var)", process.env["BRAINBOX_ORG"]).option("--project <name>", "Project name (or set BRAINBOX_PROJECT env var)", process.env["BRAINBOX_PROJECT"]).option("--wait", "Poll until context generation is complete before exiting").option("--activate", "Activate the context immediately after generation completes (implies --wait)").option("--api-url <url>", "BrainBox API base URL (or set BRAINBOX_API_URL env var)", process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").option("--api-key <key>", "BrainBox API key (or set BRAINBOX_API_KEY env var)").option("--ui-url <url>", "BrainBox web UI base URL", (process.env["BRAINBOX_API_URL"] ?? "https://ctx.brainbox-ai.app").replace(/\/$/, "")).option("--verbose", "Print full request/response details").action(async (options) => {
3805
+ const logger = createLogger(options.verbose);
3806
+ const apiKey = options.apiKey || process.env["BRAINBOX_API_KEY"];
3807
+ const api = new BrainBoxApiClient(options.apiUrl, apiKey, logger);
3808
+ if (!options.org) {
3809
+ console.error("error: required option '--org <name>' not specified (or set BRAINBOX_ORG)");
3810
+ process.exit(1);
3811
+ }
3812
+ if (!options.project) {
3813
+ console.error("error: required option '--project <name>' not specified (or set BRAINBOX_PROJECT)");
3814
+ process.exit(1);
3815
+ }
3816
+ try {
3817
+ logger.info(`Connecting to MCP server at ${options.server}...`);
3818
+ let tools;
3819
+ try {
3820
+ tools = await introspectMcpServer(options.server);
3821
+ } catch (err) {
3822
+ if (err instanceof BrainboxServerError) {
3823
+ logger.error(`Error: ${err.message}`);
3824
+ } else {
3825
+ logger.error(`Error connecting to MCP server: ${err instanceof Error ? err.message : String(err)}`);
3826
+ }
3827
+ process.exit(1);
3828
+ }
3829
+ logger.info(`\u2713 Found ${tools.length} tool(s): ${tools.map((t) => t.name).join(", ")}`);
3830
+ let org;
3831
+ let project;
3832
+ try {
3833
+ org = await api.getOrCreateOrg(options.org);
3834
+ project = await api.getOrCreateProject(org.id, options.project);
3835
+ } catch (err) {
3836
+ logger.error(`Error resolving org/project: ${err instanceof Error ? err.message : String(err)}`);
3837
+ process.exit(1);
3838
+ }
3839
+ logger.info("Submitting MCP connector draft...");
3840
+ let connector;
3841
+ try {
3842
+ connector = await api.createMcpConnector(org.id, project.id, tools, options.server);
3843
+ } catch (err) {
3844
+ logger.error(`Error creating MCP connector draft: ${err instanceof Error ? err.message : String(err)}`);
3845
+ process.exit(1);
3846
+ }
3847
+ logger.info(`\u2713 Connector draft created (id: ${connector.id})`);
3848
+ logger.info("Starting context generation...");
3849
+ let ctx;
3850
+ try {
3851
+ ctx = await api.createContext(org.id, project.id, { connectorDraftId: connector.id });
3852
+ } catch (err) {
3853
+ logger.error(`Error starting context generation: ${err instanceof Error ? err.message : String(err)}`);
3854
+ process.exit(1);
3855
+ }
3856
+ logger.info(`\u2713 Context generation started (id: ${ctx.contextId})`);
3857
+ const shouldWait = options.wait || options.activate;
3858
+ if (shouldWait) {
3859
+ logger.info("Processing... (polling every 3s, timeout 5m)");
3860
+ let ready;
3861
+ try {
3862
+ ready = await api.pollContextUntilReady(org.id, project.id, ctx.contextId);
3863
+ } catch (err) {
3864
+ logger.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
3865
+ process.exit(1);
3866
+ }
3867
+ logger.info(`\u2713 Context ready \u2014 ${ready.generated?.suggestedTools?.length ?? 0} tool(s) processed`);
3868
+ if (options.activate) {
3869
+ let activated;
3870
+ try {
3871
+ activated = await api.activateContext(org.id, project.id, ctx.contextId);
3872
+ } catch (err) {
3873
+ logger.error(`Error activating context: ${err instanceof Error ? err.message : String(err)}`);
3874
+ process.exit(1);
3875
+ }
3876
+ logger.info(`\u2713 Activated as semantic layer version ${activated.version} (id: ${activated.id})`);
3877
+ logger.info(` Run mcp-connect again to refresh tool definitions (creates a new version)
3878
+ `);
3879
+ }
3880
+ }
3881
+ logger.info(`
3882
+ Review at: ${options.uiUrl}/orgs/${org.id}/projects/${project.id}/curate
3883
+ `);
3884
+ } catch (err) {
3885
+ console.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
3886
+ process.exit(1);
3887
+ }
3888
+ });
3889
+ }
3890
+
3891
+ // src/cli.ts
3892
+ var require2 = createRequire(import.meta.url);
3893
+ var { version } = require2("../package.json");
3894
+ var verbose = process.argv.includes("--verbose") || process.env["DEBUG"]?.split(",").some((s) => s.trim() === "brainbox") === true;
3895
+ function reportFatal(err) {
3896
+ const message = err instanceof Error ? err.message : String(err);
3897
+ console.error(`error: ${message.replace(/^\[BrainBox\]\s*/, "")}`);
3898
+ if (verbose && err instanceof Error && err.stack) console.error(err.stack);
3899
+ process.exit(1);
3900
+ }
3901
+ process.on("unhandledRejection", reportFatal);
3902
+ process.on("uncaughtException", reportFatal);
3903
+ var program = new Command7();
3904
+ program.name("brainbox").description("BrainBox Context Layer CLI").version(version);
3905
+ program.addCommand(createMetaCommand());
3906
+ program.addCommand(createRepoCommand());
3907
+ program.addCommand(createDevCommand());
3908
+ program.addCommand(createProfileCommand());
3909
+ program.addCommand(createCollectCommand());
3910
+ program.addCommand(createRecipeCommand(version));
3911
+ function registerHidden(program2, register) {
3912
+ const before = new Set(program2.commands.map((c) => c.name()));
3913
+ register(program2);
3914
+ for (const cmd of program2.commands) {
3915
+ if (!before.has(cmd.name())) cmd._hidden = true;
3916
+ }
3917
+ }
3918
+ registerHidden(program, registerStructuredCommands);
3919
+ registerHidden(program, registerMcpCommands);
3920
+ registerHidden(program, registerKbCommands);
3921
+ registerHidden(program, registerExtractCommands);
3922
+ program.parse(process.argv);