agent-rag-mcp 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,677 @@
1
+ import * as fs from "node:fs/promises";
2
+ import { DatabaseSync } from "node:sqlite";
3
+ import { createHash } from "node:crypto";
4
+ import { homedir } from "node:os";
5
+ import * as path from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ import { discoverConfig, NamespaceRequiredError, resolveCommandNamespace } from "../config/discovery.mjs";
8
+ import { IngestError, ingestFile } from "../ingest/pipeline.mjs";
9
+ import { importDirectory } from "../ingest/import.mjs";
10
+ import { clientDbPath, openDatabase, validateClientName } from "../store/db.mjs";
11
+ import { backupRoot, reindexRoot, restoreRoot, writeRootManifest } from "../store/backup.mjs";
12
+ import { readObject } from "../store/objects.mjs";
13
+ import { getActiveLimits } from "../limits.mjs";
14
+ import {
15
+ linkReviewVersions,
16
+ listReviewCandidates,
17
+ relabelDocument,
18
+ renameEntity,
19
+ retireDocument
20
+ } from "../store/lifecycle.mjs";
21
+ const USAGE = `Usage: rag <command> [options]
22
+
23
+ Commands:
24
+ init Initialize the namespace database and object store
25
+ add <path> Ingest a file
26
+ import <dir> Ingest files from a directory
27
+ ls List current documents
28
+ rm <document-id> Retire a document without deleting its history
29
+ relabel <document-id> --label <text> Repair a document label
30
+ entity rename <from> <to> Correct an entity key within the project
31
+ review list List human review candidates
32
+ review link <from> <to> --type <conflicts_with|same_entity>
33
+ Record a human relation between document versions
34
+ status Show namespace counts
35
+ doctor Verify recorded objects and report orphan blobs/temporaries
36
+ backup --to <dir> Back up the manifest and object store
37
+ restore --from <dir> Restore a backup into this root
38
+ reindex Rebuild the database from manifest and objects
39
+
40
+ Options:
41
+ --root <path> Knowledge-base root
42
+ --client <name> Client namespace
43
+ --project <name> Project namespace
44
+ --to <dir> Backup destination
45
+ --from <dir> Backup source
46
+ --type <type> Human relation type for rag review link
47
+ --label <text> Replacement label for rag relabel
48
+ --help Show this help`;
49
+ const NAMED_ERROR_CODES = /* @__PURE__ */ new Set([
50
+ "usage",
51
+ "ingest_failed",
52
+ "extraction_empty",
53
+ "import_failed",
54
+ "source_not_a_file",
55
+ "source_not_found",
56
+ "io_error",
57
+ "database_not_found",
58
+ "config_invalid",
59
+ "config_unreadable",
60
+ "namespace_required",
61
+ "unsupported_media_type",
62
+ "invalid_media_hint",
63
+ "media_mismatch",
64
+ "source_changed_during_copy",
65
+ "source_too_large",
66
+ "too_many_pages",
67
+ "archive_too_large",
68
+ "image_too_large",
69
+ "sheet_too_large",
70
+ "object_store_write_failed",
71
+ "manifest_invalid",
72
+ "object_missing",
73
+ "object_corrupt",
74
+ "object_read_failed",
75
+ "object_copy_failed",
76
+ "manifest_missing",
77
+ "manifest_read_failed",
78
+ "manifest_write_failed",
79
+ "invalid_client_name",
80
+ "backup_failed",
81
+ "destination_exists",
82
+ "namespace_mismatch",
83
+ "restore_destination_not_empty",
84
+ "restore_failed",
85
+ "foreign_client_in_manifest",
86
+ "database_exists",
87
+ "reindex_failed",
88
+ "document_not_found",
89
+ "entity_not_found",
90
+ "entity_key_conflict",
91
+ "project_not_found",
92
+ "doc_version_not_found",
93
+ "invalid_relation",
94
+ "invalid_label"
95
+ ]);
96
+ const USAGE_ERROR_CODES = /* @__PURE__ */ new Set(["usage", "invalid_label"]);
97
+ function stripErrorPrefix(message) {
98
+ return message.replace(/^(?:(?:ENOENT|EACCES|EPERM|EBUSY):|UNIQUE constraint failed:)\s*/, "");
99
+ }
100
+ function publicErrorMessage(error) {
101
+ return stripErrorPrefix(error instanceof Error ? error.message : String(error));
102
+ }
103
+ function errorOutput(namespace, error, exitCode) {
104
+ const rawCode = error !== null && typeof error === "object" ? error.code : void 0;
105
+ const code = error instanceof IngestError ? "ingest_failed" : rawCode && NAMED_ERROR_CODES.has(rawCode) ? rawCode : rawCode && /^E[A-Z0-9]+$/.test(rawCode) ? "io_error" : "internal_error";
106
+ const isUsageError = USAGE_ERROR_CODES.has(code);
107
+ return {
108
+ exitCode: exitCode ?? (isUsageError ? 2 : 1),
109
+ output: {
110
+ namespace,
111
+ error: {
112
+ code,
113
+ message: publicErrorMessage(error),
114
+ ...isUsageError ? { usage: USAGE } : {}
115
+ }
116
+ }
117
+ };
118
+ }
119
+ function commandErrorOutput(namespace, error) {
120
+ return errorOutput(namespace, error);
121
+ }
122
+ function usageError(message, code = "usage") {
123
+ return Object.assign(new Error(message), { code });
124
+ }
125
+ function codedError(code, message) {
126
+ return Object.assign(new Error(message), { code });
127
+ }
128
+ async function ingestSource(sourcePath, ingest) {
129
+ try {
130
+ if ((await fs.stat(sourcePath)).isDirectory()) {
131
+ throw codedError("source_not_a_file", `Source is not a file: ${sourcePath}`);
132
+ }
133
+ } catch (error) {
134
+ if (error instanceof Error && "code" in error && error.code === "source_not_a_file") throw error;
135
+ const fileError = error;
136
+ if (fileError.code === "ENOENT") {
137
+ throw codedError("source_not_found", `Source file not found: ${sourcePath}`);
138
+ }
139
+ if (fileError.code === "EISDIR") {
140
+ throw codedError("source_not_a_file", `Source is not a file: ${sourcePath}`);
141
+ }
142
+ if (typeof fileError.syscall === "string" || /^E[A-Z0-9]+$/.test(fileError.code ?? "")) {
143
+ throw codedError("io_error", publicErrorMessage(error));
144
+ }
145
+ throw error;
146
+ }
147
+ return ingest();
148
+ }
149
+ function parseArgs(argv) {
150
+ const positional = [];
151
+ const values = {};
152
+ let help = false;
153
+ for (let index = 0; index < argv.length; index += 1) {
154
+ const argument = argv[index];
155
+ if (argument === "--help") {
156
+ help = true;
157
+ continue;
158
+ }
159
+ const assignment = /^--(to|from|type|label)=(.*)$/.exec(argument);
160
+ if (assignment) {
161
+ values[assignment[1]] = assignment[2];
162
+ continue;
163
+ }
164
+ if (/^--(root|client|project)=/.test(argument)) continue;
165
+ if (["--to", "--from", "--type", "--label"].includes(argument)) {
166
+ if (argv[index + 1] === void 0 || argv[index + 1].startsWith("--")) {
167
+ const code = argument === "--label" ? "invalid_label" : "usage";
168
+ const message = argument === "--label" ? "Option --label requires a non-blank value." : `Option ${argument} requires a value.`;
169
+ throw usageError(message, code);
170
+ }
171
+ values[argument.slice(2)] = argv[index + 1];
172
+ index += 1;
173
+ continue;
174
+ }
175
+ if (["--root", "--client", "--project"].includes(argument)) {
176
+ if (argv[index + 1] === void 0 || argv[index + 1].startsWith("--")) {
177
+ throw usageError(`Option ${argument} requires a value.`);
178
+ }
179
+ index += 1;
180
+ continue;
181
+ }
182
+ if (argument.startsWith("--")) throw usageError(`Unknown option: ${argument}`);
183
+ positional.push(argument);
184
+ }
185
+ return { command: positional[0] ?? null, positional: positional.slice(1), help, values };
186
+ }
187
+ function requireNamespace(config, mode) {
188
+ const { namespace } = resolveCommandNamespace(config, mode);
189
+ if (namespace === null) {
190
+ if (mode === "write") throw new NamespaceRequiredError();
191
+ return null;
192
+ }
193
+ if (namespace.client !== null) validateClientName(namespace.client);
194
+ if (!namespace.client || !namespace.project) throw new NamespaceRequiredError();
195
+ return { client: namespace.client, project: namespace.project };
196
+ }
197
+ async function initialize(root, config) {
198
+ const namespace = requireNamespace(config, "write");
199
+ if (!namespace) throw new NamespaceRequiredError();
200
+ const dbPath = clientDbPath(root, namespace.client);
201
+ const db = openDatabase(dbPath);
202
+ const objectStorePath = path.join(root, "objects");
203
+ try {
204
+ await fs.mkdir(objectStorePath, { recursive: true });
205
+ await writeRootManifest(root, db);
206
+ } finally {
207
+ db.close();
208
+ }
209
+ return { namespace, result: { dbPath, objectStorePath } };
210
+ }
211
+ function projectIdForNamespace(db, namespace) {
212
+ const project = db.prepare(`SELECT p.project_id FROM project AS p
213
+ JOIN client AS c ON c.client_id = p.client_id WHERE c.name = ? AND p.slug = ?`).get(namespace.client, namespace.project);
214
+ if (!project) throw codedError("project_not_found", `Project not found: ${namespace.client}/${namespace.project}.`);
215
+ return project.project_id;
216
+ }
217
+ function isHumanRelationType(value) {
218
+ return value === "conflicts_with" || value === "same_entity";
219
+ }
220
+ function queryDocuments(root, namespace) {
221
+ if (namespace === null) return { namespace: null, result: { documents: [] } };
222
+ const db = openDatabase(clientDbPath(root, namespace.client));
223
+ try {
224
+ const project = db.prepare(`SELECT p.project_id FROM project AS p
225
+ JOIN client AS c ON c.client_id = p.client_id WHERE c.name = ? AND p.slug = ?`).get(namespace.client, namespace.project);
226
+ const rows = project ? db.prepare(`SELECT e.entity_key AS entityKey, d.label AS label, dv.version_label AS versionLabel
227
+ FROM document AS d JOIN entity AS e ON e.entity_id = d.entity_id
228
+ JOIN doc_version AS dv ON dv.document_id = d.document_id AND dv.is_current = 1
229
+ WHERE d.project_id = ? AND d.deleted_at IS NULL ORDER BY e.entity_key, d.label`).all(project.project_id) : [];
230
+ const documents = rows.map((row) => ({ entityKey: row.entityKey, label: row.label, versionLabel: row.versionLabel }));
231
+ return { namespace, result: { documents } };
232
+ } finally {
233
+ db.close();
234
+ }
235
+ }
236
+ async function countObjectStoreArtifacts(root) {
237
+ const referenced = /* @__PURE__ */ new Set();
238
+ const clientsRoot = path.join(root, "clients");
239
+ let clientDirectories;
240
+ try {
241
+ clientDirectories = await fs.readdir(clientsRoot, { withFileTypes: true });
242
+ } catch (error) {
243
+ if (error.code !== "ENOENT") throw error;
244
+ clientDirectories = [];
245
+ }
246
+ for (const directory of clientDirectories) {
247
+ if (!directory.isDirectory()) continue;
248
+ const dbPath = path.join(clientsRoot, directory.name, "rag.db");
249
+ try {
250
+ await fs.access(dbPath);
251
+ } catch (error) {
252
+ if (error.code === "ENOENT") continue;
253
+ throw error;
254
+ }
255
+ const referenceDb = new DatabaseSync(dbPath, { readOnly: true });
256
+ try {
257
+ const rows = referenceDb.prepare("SELECT sha256 FROM object").all();
258
+ for (const row of rows) referenced.add(row.sha256);
259
+ } finally {
260
+ referenceDb.close();
261
+ }
262
+ }
263
+ let unreferencedObjects = 0;
264
+ let leftoverTemporaries = 0;
265
+ const objectsRoot = path.join(root, "objects");
266
+ const inspectDirectory = async (directoryPath) => {
267
+ let entries;
268
+ try {
269
+ entries = await fs.readdir(directoryPath, { withFileTypes: true });
270
+ } catch (error) {
271
+ if (error.code === "ENOENT") return;
272
+ throw error;
273
+ }
274
+ for (const entry of entries) {
275
+ const entryPath = path.join(directoryPath, entry.name);
276
+ if (entry.isDirectory()) {
277
+ await inspectDirectory(entryPath);
278
+ } else if (entry.isFile() && entry.name.endsWith(".tmp")) {
279
+ leftoverTemporaries += 1;
280
+ } else if (entry.isFile() && /^[0-9a-f]{64}$/.test(entry.name) && !referenced.has(entry.name)) {
281
+ unreferencedObjects += 1;
282
+ }
283
+ }
284
+ };
285
+ await inspectDirectory(objectsRoot);
286
+ return { unreferencedObjects, leftoverTemporaries };
287
+ }
288
+ async function verifyNamespaceObjects(root, namespace) {
289
+ if (namespace === null) return errorOutput(null, new NamespaceRequiredError());
290
+ const dbPath = clientDbPath(root, namespace.client);
291
+ try {
292
+ await fs.access(dbPath);
293
+ } catch (error) {
294
+ if (error.code === "ENOENT") {
295
+ throw codedError("database_not_found", `Client database not found: ${dbPath}`);
296
+ }
297
+ throw error;
298
+ }
299
+ const db = openDatabase(dbPath);
300
+ let objects;
301
+ let chunks;
302
+ let indexedChunks;
303
+ try {
304
+ objects = db.prepare("SELECT sha256, byte_size FROM object ORDER BY sha256").all();
305
+ chunks = Number(db.prepare("SELECT COUNT(*) AS count FROM chunk").get()?.count ?? 0);
306
+ indexedChunks = Number(db.prepare("SELECT COUNT(*) AS count FROM chunk_fts_docsize").get()?.count ?? 0);
307
+ } finally {
308
+ db.close();
309
+ }
310
+ const missing = [];
311
+ const corrupt = [];
312
+ for (const object of objects) {
313
+ let bytes;
314
+ try {
315
+ bytes = await readObject(root, object.sha256);
316
+ } catch (error) {
317
+ if (error.code === "ENOENT") missing.push(object.sha256);
318
+ else corrupt.push(object.sha256);
319
+ continue;
320
+ }
321
+ if (bytes.byteLength !== object.byte_size || createHash("sha256").update(bytes).digest("hex") !== object.sha256) {
322
+ corrupt.push(object.sha256);
323
+ }
324
+ }
325
+ const indexHealthy = chunks === indexedChunks;
326
+ const ok = missing.length === 0 && corrupt.length === 0 && indexHealthy;
327
+ const artifacts = await countObjectStoreArtifacts(root);
328
+ return {
329
+ exitCode: ok ? 0 : 1,
330
+ output: {
331
+ namespace,
332
+ result: {
333
+ ok,
334
+ dbPath,
335
+ checked: objects.length,
336
+ missing,
337
+ corrupt,
338
+ limits: await getActiveLimits(),
339
+ ...indexHealthy ? {} : { chunks, indexedChunks },
340
+ // Keep healthy doctor envelopes stable; surface counts whenever artifacts need attention.
341
+ ...artifacts.unreferencedObjects === 0 && artifacts.leftoverTemporaries === 0 ? {} : artifacts
342
+ }
343
+ }
344
+ };
345
+ }
346
+ function queryStatus(root, namespace) {
347
+ if (namespace === null) return { namespace: null, result: { documents: 0, versions: 0, objects: 0 } };
348
+ const db = openDatabase(clientDbPath(root, namespace.client));
349
+ try {
350
+ const project = db.prepare(`SELECT p.project_id FROM project AS p
351
+ JOIN client AS c ON c.client_id = p.client_id WHERE c.name = ? AND p.slug = ?`).get(namespace.client, namespace.project);
352
+ if (!project) return { namespace, result: { documents: 0, versions: 0, objects: 0 } };
353
+ const documents = db.prepare("SELECT COUNT(*) AS count FROM document WHERE project_id = ? AND deleted_at IS NULL").get(project.project_id)?.count;
354
+ const versions = db.prepare(`SELECT COUNT(*) AS count FROM doc_version AS dv
355
+ JOIN document AS d ON d.document_id = dv.document_id WHERE d.project_id = ? AND d.deleted_at IS NULL`).get(project.project_id)?.count;
356
+ const objects = db.prepare(`SELECT COUNT(DISTINCT dv.sha256) AS count FROM doc_version AS dv
357
+ JOIN document AS d ON d.document_id = dv.document_id WHERE d.project_id = ? AND d.deleted_at IS NULL`).get(project.project_id)?.count;
358
+ return { namespace, result: { documents, versions, objects } };
359
+ } finally {
360
+ db.close();
361
+ }
362
+ }
363
+ async function runCli(options) {
364
+ const homeDir = options.homeDir ?? options.env.RAG_HOME ?? homedir();
365
+ let config;
366
+ try {
367
+ config = discoverConfig({
368
+ argv: options.argv,
369
+ env: options.env,
370
+ cwd: options.cwd,
371
+ homeDir
372
+ });
373
+ } catch (error) {
374
+ return errorOutput(null, error);
375
+ }
376
+ let parsed;
377
+ try {
378
+ parsed = parseArgs(options.argv);
379
+ } catch (error) {
380
+ return errorOutput(config.namespace, error);
381
+ }
382
+ if (parsed.values.type !== void 0 && (parsed.command !== "review" || parsed.positional[0] !== "link")) {
383
+ return errorOutput(config.namespace, usageError('Option --type is only accepted by "rag review link".'));
384
+ }
385
+ if (parsed.values.label !== void 0 && parsed.command !== "relabel") {
386
+ return errorOutput(config.namespace, usageError('Option --label is only accepted by "rag relabel".'));
387
+ }
388
+ if (parsed.command === "relabel" && parsed.values.label === void 0) {
389
+ return errorOutput(config.namespace, usageError("Option --label requires a non-blank value.", "invalid_label"));
390
+ }
391
+ if (parsed.help) return { exitCode: 0, output: { namespace: config.namespace, result: USAGE } };
392
+ if (parsed.command === "init") {
393
+ if (parsed.positional.length !== 0) return errorOutput(config.namespace, usageError("init does not accept positional arguments."));
394
+ try {
395
+ const output = await initialize(path.resolve(options.cwd, config.root), config);
396
+ return { exitCode: 0, output };
397
+ } catch (error) {
398
+ return errorOutput(config.namespace, error);
399
+ }
400
+ }
401
+ if (parsed.command === "add") {
402
+ if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("add requires exactly one file path."));
403
+ try {
404
+ const namespace = requireNamespace(config, "write");
405
+ if (!namespace) throw new NamespaceRequiredError();
406
+ const sourcePath = path.resolve(options.cwd, parsed.positional[0]);
407
+ const output = await ingestSource(sourcePath, () => (options.dependencies?.ingestFile ?? ingestFile)({
408
+ root: path.resolve(options.cwd, config.root),
409
+ client: namespace.client,
410
+ project: namespace.project,
411
+ sourcePath
412
+ }));
413
+ return { exitCode: 0, output: { namespace, result: output } };
414
+ } catch (error) {
415
+ return errorOutput(config.namespace, error);
416
+ }
417
+ }
418
+ if (parsed.command === "import") {
419
+ if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("import requires exactly one directory path."));
420
+ try {
421
+ const namespace = requireNamespace(config, "write");
422
+ if (!namespace) throw new NamespaceRequiredError();
423
+ const directoryPath = path.resolve(options.cwd, parsed.positional[0]);
424
+ try {
425
+ const sourceStat = await fs.stat(directoryPath);
426
+ if (!sourceStat.isDirectory()) throw codedError("source_not_a_file", `Import source is not a directory: ${directoryPath}`);
427
+ } catch (error) {
428
+ if (error instanceof Error && "code" in error && error.code === "source_not_a_file") throw error;
429
+ const fileError = error;
430
+ if (fileError.code === "ENOENT") throw codedError("source_not_found", `Import directory not found: ${directoryPath}`);
431
+ if (fileError.code === "ENOTDIR") throw codedError("source_not_a_file", `Import source is not a directory: ${directoryPath}`);
432
+ throw codedError("io_error", "Unable to inspect import directory.");
433
+ }
434
+ const result = await importDirectory({
435
+ directoryPath,
436
+ root: path.resolve(options.cwd, config.root),
437
+ client: namespace.client,
438
+ project: namespace.project,
439
+ ingestFile: options.dependencies?.ingestFile
440
+ });
441
+ if (result.summary.failed > 0) {
442
+ return {
443
+ exitCode: 1,
444
+ output: {
445
+ namespace,
446
+ error: {
447
+ code: "import_failed",
448
+ message: `Import failed for ${result.summary.failed} of ${result.summary.total} files.`,
449
+ files: result.files.map((file) => file.status === "failed" ? { ...file, message: stripErrorPrefix(file.message) } : file),
450
+ summary: result.summary
451
+ }
452
+ }
453
+ };
454
+ }
455
+ return { exitCode: 0, output: { namespace, result } };
456
+ } catch (error) {
457
+ return errorOutput(config.namespace, error);
458
+ }
459
+ }
460
+ if (parsed.command === "relabel") {
461
+ if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("relabel requires exactly one document ID."));
462
+ const label = parsed.values.label;
463
+ if (label === void 0 || label.trim().length === 0) {
464
+ return errorOutput(config.namespace, usageError("Option --label requires a non-blank value.", "invalid_label"));
465
+ }
466
+ try {
467
+ const namespace = requireNamespace(config, "write");
468
+ if (!namespace) throw new NamespaceRequiredError();
469
+ const root = path.resolve(options.cwd, config.root);
470
+ const db = openDatabase(clientDbPath(root, namespace.client));
471
+ try {
472
+ const result = relabelDocument(db, projectIdForNamespace(db, namespace), parsed.positional[0], label);
473
+ await writeRootManifest(root, db);
474
+ return { exitCode: 0, output: { namespace, result } };
475
+ } finally {
476
+ db.close();
477
+ }
478
+ } catch (error) {
479
+ return commandErrorOutput(config.namespace, error);
480
+ }
481
+ }
482
+ if (parsed.command === "rm") {
483
+ if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("rm requires exactly one document ID."));
484
+ try {
485
+ const namespace = requireNamespace(config, "write");
486
+ if (!namespace) throw new NamespaceRequiredError();
487
+ const root = path.resolve(options.cwd, config.root);
488
+ const db = openDatabase(clientDbPath(root, namespace.client));
489
+ try {
490
+ const result = retireDocument(db, projectIdForNamespace(db, namespace), parsed.positional[0]);
491
+ await writeRootManifest(root, db);
492
+ return { exitCode: 0, output: { namespace, result } };
493
+ } finally {
494
+ db.close();
495
+ }
496
+ } catch (error) {
497
+ return commandErrorOutput(config.namespace, error);
498
+ }
499
+ }
500
+ if (parsed.command === "entity") {
501
+ if (parsed.positional[0] !== "rename" || parsed.positional.length !== 3) {
502
+ return errorOutput(config.namespace, usageError("entity rename requires <from> <to>."));
503
+ }
504
+ try {
505
+ const namespace = requireNamespace(config, "write");
506
+ if (!namespace) throw new NamespaceRequiredError();
507
+ const root = path.resolve(options.cwd, config.root);
508
+ const db = openDatabase(clientDbPath(root, namespace.client));
509
+ try {
510
+ const result = renameEntity(db, projectIdForNamespace(db, namespace), parsed.positional[1], parsed.positional[2]);
511
+ await writeRootManifest(root, db);
512
+ return { exitCode: 0, output: { namespace, result } };
513
+ } finally {
514
+ db.close();
515
+ }
516
+ } catch (error) {
517
+ return commandErrorOutput(config.namespace, error);
518
+ }
519
+ }
520
+ if (parsed.command === "review") {
521
+ if (parsed.positional[0] === "list" && parsed.positional.length === 1) {
522
+ try {
523
+ const namespace = requireNamespace(config, "read");
524
+ if (!namespace) throw new NamespaceRequiredError();
525
+ const db = openDatabase(clientDbPath(path.resolve(options.cwd, config.root), namespace.client));
526
+ try {
527
+ const candidates = listReviewCandidates(db, projectIdForNamespace(db, namespace));
528
+ return { exitCode: 0, output: { namespace, result: { candidates } } };
529
+ } finally {
530
+ db.close();
531
+ }
532
+ } catch (error) {
533
+ return commandErrorOutput(config.namespace, error);
534
+ }
535
+ }
536
+ if (parsed.positional[0] === "link") {
537
+ if (parsed.positional.length !== 3) {
538
+ return errorOutput(config.namespace, usageError("review link requires <from> <to> --type <conflicts_with|same_entity>."));
539
+ }
540
+ if (!isHumanRelationType(parsed.values.type)) {
541
+ const message = parsed.values.type === void 0 ? "review link requires --type <conflicts_with|same_entity>." : 'Review link type must be "conflicts_with" or "same_entity".';
542
+ return errorOutput(config.namespace, usageError(message));
543
+ }
544
+ try {
545
+ const namespace = requireNamespace(config, "write");
546
+ if (!namespace) throw new NamespaceRequiredError();
547
+ const root = path.resolve(options.cwd, config.root);
548
+ const db = openDatabase(clientDbPath(root, namespace.client));
549
+ try {
550
+ const result = linkReviewVersions(
551
+ db,
552
+ projectIdForNamespace(db, namespace),
553
+ parsed.positional[1],
554
+ parsed.positional[2],
555
+ parsed.values.type
556
+ );
557
+ await writeRootManifest(root, db);
558
+ return { exitCode: 0, output: { namespace, result } };
559
+ } finally {
560
+ db.close();
561
+ }
562
+ } catch (error) {
563
+ return commandErrorOutput(config.namespace, error);
564
+ }
565
+ }
566
+ return errorOutput(config.namespace, usageError("review accepts list or link."));
567
+ }
568
+ if (parsed.command === "ls") {
569
+ if (parsed.positional.length !== 0) return errorOutput(config.namespace, usageError("ls does not accept positional arguments."));
570
+ try {
571
+ const namespace = requireNamespace(config, "read");
572
+ return { exitCode: 0, output: queryDocuments(path.resolve(options.cwd, config.root), namespace) };
573
+ } catch (error) {
574
+ return errorOutput(config.namespace, error);
575
+ }
576
+ }
577
+ if (parsed.command === "doctor") {
578
+ if (parsed.positional.length !== 0) return errorOutput(config.namespace, usageError("doctor does not accept positional arguments."));
579
+ try {
580
+ const namespace = requireNamespace(config, "read");
581
+ return await verifyNamespaceObjects(path.resolve(options.cwd, config.root), namespace);
582
+ } catch (error) {
583
+ return errorOutput(config.namespace, error);
584
+ }
585
+ }
586
+ if (parsed.command === "status") {
587
+ if (parsed.positional.length !== 0) return errorOutput(config.namespace, usageError("status does not accept positional arguments."));
588
+ try {
589
+ const namespace = requireNamespace(config, "read");
590
+ return { exitCode: 0, output: queryStatus(path.resolve(options.cwd, config.root), namespace) };
591
+ } catch (error) {
592
+ return errorOutput(config.namespace, error);
593
+ }
594
+ }
595
+ if (parsed.command === "backup") {
596
+ if (parsed.positional.length !== 0 || parsed.values.to === void 0 || parsed.values.to.length === 0) {
597
+ return commandErrorOutput(config.namespace, usageError("backup requires --to <dir> and accepts no positional arguments."));
598
+ }
599
+ try {
600
+ const namespace = requireNamespace(config, "write");
601
+ if (!namespace) throw new NamespaceRequiredError();
602
+ const root = path.resolve(options.cwd, config.root);
603
+ const dbPath = clientDbPath(root, namespace.client);
604
+ try {
605
+ await fs.access(dbPath);
606
+ } catch (error) {
607
+ if (error.code === "ENOENT") throw codedError("database_not_found", `Client database not found: ${dbPath}`);
608
+ throw codedError("backup_failed", "Unable to inspect client database.");
609
+ }
610
+ const db = openDatabase(dbPath);
611
+ try {
612
+ const result = await backupRoot(root, db, path.resolve(options.cwd, parsed.values.to));
613
+ return { exitCode: 0, output: { namespace, result } };
614
+ } finally {
615
+ db.close();
616
+ }
617
+ } catch (error) {
618
+ return commandErrorOutput(config.namespace, error);
619
+ }
620
+ }
621
+ if (parsed.command === "restore") {
622
+ if (parsed.positional.length !== 0 || parsed.values.from === void 0 || parsed.values.from.length === 0) {
623
+ return commandErrorOutput(config.namespace, usageError("restore requires --from <dir> and accepts no positional arguments."));
624
+ }
625
+ try {
626
+ const namespace = requireNamespace(config, "write");
627
+ if (!namespace) throw new NamespaceRequiredError();
628
+ const root = path.resolve(options.cwd, config.root);
629
+ const result = await restoreRoot(path.resolve(options.cwd, parsed.values.from), root, namespace.client);
630
+ return { exitCode: 0, output: { namespace, result } };
631
+ } catch (error) {
632
+ return commandErrorOutput(config.namespace, error);
633
+ }
634
+ }
635
+ if (parsed.command === "reindex") {
636
+ if (parsed.positional.length !== 0) return commandErrorOutput(config.namespace, usageError("reindex does not accept positional arguments."));
637
+ try {
638
+ const namespace = requireNamespace(config, "write");
639
+ if (!namespace) throw new NamespaceRequiredError();
640
+ const result = await reindexRoot(path.resolve(options.cwd, config.root), namespace.client);
641
+ return { exitCode: 0, output: { namespace, result } };
642
+ } catch (error) {
643
+ return commandErrorOutput(config.namespace, error);
644
+ }
645
+ }
646
+ return errorOutput(config.namespace, usageError(parsed.command === null ? "Command is required." : `Unknown command: ${parsed.command}`));
647
+ }
648
+ async function main(dependencies = {}) {
649
+ const writeStdout = dependencies.writeStdout ?? ((line) => process.stdout.write(line));
650
+ const setExitCode = dependencies.setExitCode ?? ((exitCode) => {
651
+ process.exitCode = exitCode;
652
+ });
653
+ try {
654
+ const result = await (dependencies.runCli ?? runCli)({
655
+ argv: process.argv.slice(2),
656
+ env: process.env,
657
+ cwd: process.cwd(),
658
+ homeDir: process.env.RAG_HOME ?? homedir()
659
+ });
660
+ writeStdout(`${JSON.stringify(result.output)}
661
+ `);
662
+ setExitCode(result.exitCode);
663
+ } catch (error) {
664
+ const message = publicErrorMessage(error);
665
+ writeStdout(`${JSON.stringify({ namespace: null, error: { code: "internal_error", message } })}
666
+ `);
667
+ setExitCode(1);
668
+ }
669
+ }
670
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
671
+ await main();
672
+ }
673
+ export {
674
+ USAGE,
675
+ main,
676
+ runCli
677
+ };