@mfdaves/okf-mcp 0.3.3-rc.1 → 0.5.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.
Files changed (40) hide show
  1. package/.agents/skills/okf-v02-migration/SKILL.md +37 -0
  2. package/.agents/skills/okf-v02-migration/agents/openai.yaml +6 -0
  3. package/.agents/skills/okf-v02-migration/references/field-mapping.md +26 -0
  4. package/README.md +192 -78
  5. package/okf/bundles/okf-mcp/distribution/reference-bundle.md +2 -2
  6. package/okf/bundles/okf-mcp/index.md +7 -0
  7. package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +2 -2
  8. package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +8 -4
  9. package/okf/bundles/okf-mcp/overview/okf-mcp.md +2 -2
  10. package/okf/bundles/okf-mcp/policies/authoring-safety.md +5 -3
  11. package/okf/bundles/okf-mcp/runtime/file-concept-store.md +7 -5
  12. package/okf/bundles/okf-mcp/runtime/indexer.md +6 -4
  13. package/okf/bundles/okf-mcp/runtime/mcp-server.md +6 -6
  14. package/okf/bundles/okf-mcp/specs/attested-computation.md +24 -0
  15. package/okf/bundles/okf-mcp/specs/concept-format.md +5 -3
  16. package/okf/bundles/okf-mcp/specs/git-sources.md +23 -0
  17. package/okf/bundles/okf-mcp/workflows/v02-migration.md +24 -0
  18. package/package.json +9 -3
  19. package/server.json +5 -5
  20. package/src/assets.js +469 -0
  21. package/src/authoring.js +492 -20
  22. package/src/cli.js +467 -37
  23. package/src/computation.js +366 -0
  24. package/src/git-source.js +551 -0
  25. package/src/graph.js +71 -18
  26. package/src/http-server.js +8 -1
  27. package/src/index.js +5 -0
  28. package/src/indexer.js +428 -24
  29. package/src/markdown.js +129 -0
  30. package/src/mcp-server.js +447 -313
  31. package/src/migration.js +687 -0
  32. package/src/parser.js +135 -54
  33. package/src/plugins.js +30 -50
  34. package/src/project.js +74 -17
  35. package/src/remote.js +232 -17
  36. package/src/search.js +69 -6
  37. package/src/store.js +421 -25
  38. package/src/v02.js +545 -0
  39. package/src/validation.js +13 -2
  40. package/src/mcp-protocol.js +0 -283
package/src/cli.js CHANGED
@@ -1,23 +1,38 @@
1
1
  "use strict";
2
2
 
3
+ const fs = require("fs");
4
+
3
5
  const {
4
6
  attachProject,
5
7
  buildIndex,
6
8
  buildProjectIndexAsync,
7
9
  loadProjectBundles,
10
+ resolveConcept,
8
11
  validateIndex,
9
12
  } = require("./indexer");
10
13
  const { exportGraph, findPaths, getNeighbors, graphSummary } = require("./graph");
11
14
  const { searchConcepts } = require("./search");
12
15
  const { conceptSummary } = require("./indexer");
13
- const { findProjectConfig, loadProjectConfig } = require("./project");
16
+ const { findOkfRoot, findProjectConfig, loadProjectConfig } = require("./project");
14
17
  const { generateProject } = require("./plugins");
15
18
  const { runStdioServer } = require("./mcp-server");
16
19
  const { fetchRemoteBundles } = require("./remote");
17
20
  const { runHttpServer } = require("./http-server");
21
+ const {
22
+ checkComputationReceipt,
23
+ getProvenance,
24
+ inspectAttestedComputation,
25
+ prepareAttestedComputation,
26
+ readBundleAsset,
27
+ } = require("./computation");
28
+ const { buildV02MigrationPlan, checkV02Migration } = require("./migration");
29
+ const { describeConceptGitSources, readConceptGitSource } = require("./git-source");
18
30
  const packageMetadata = require("../package.json");
19
31
 
20
- const COMMANDS = new Set(["mcp", "validate", "graph", "search", "concept", "neighbors", "paths", "generate", "serve"]);
32
+ const COMMANDS = new Set([
33
+ "mcp", "validate", "graph", "search", "concept", "neighbors", "paths", "generate", "serve",
34
+ "provenance", "edge-kinds", "computation", "asset", "source", "migrate",
35
+ ]);
21
36
 
22
37
  class UsageError extends Error {
23
38
  constructor(message) {
@@ -32,6 +47,30 @@ function usageError(message) {
32
47
  return new UsageError(message);
33
48
  }
34
49
 
50
+ function parseJsonObject(value, label) {
51
+ let parsed;
52
+ try {
53
+ parsed = JSON.parse(value);
54
+ } catch (error) {
55
+ throw usageError(`${label} must be valid JSON.`);
56
+ }
57
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
58
+ throw usageError(`${label} must be a JSON object.`);
59
+ }
60
+ return parsed;
61
+ }
62
+
63
+ function readJsonObjectSource(source, label, runtime) {
64
+ let text;
65
+ try {
66
+ const readFileSync = runtime && runtime.readFileSync ? runtime.readFileSync : fs.readFileSync;
67
+ text = readFileSync(source === "-" ? 0 : source, "utf8");
68
+ } catch (error) {
69
+ throw usageError(`${label} could not be read from ${source === "-" ? "stdin" : source}.`);
70
+ }
71
+ return parseJsonObject(String(text), label);
72
+ }
73
+
35
74
  function exitCodeForError(error) {
36
75
  return error && error.exitCode === 2 ? 2 : 1;
37
76
  }
@@ -39,8 +78,10 @@ function exitCodeForError(error) {
39
78
  function parseArgs(argv) {
40
79
  const bundles = [];
41
80
  const remoteBundles = [];
81
+ const repositories = [];
42
82
  const positional = [];
43
83
  let project = null;
84
+ let root = null;
44
85
  let inspect = false;
45
86
  let help = false;
46
87
  let host = "127.0.0.1";
@@ -50,8 +91,45 @@ function parseArgs(argv) {
50
91
  let version = false;
51
92
  let authoring = false;
52
93
  let allowRemoteTool = false;
94
+ let strictLinks = false;
95
+ let allowComputationAuthoring = false;
96
+ let includeAssets = false;
97
+ let includeExternal = false;
98
+ let parametersFile = "";
99
+ let receiptFile = "";
100
+ let maxContentBytes = 65536;
101
+ const generatedPaths = [];
102
+ const search = {
103
+ types: [],
104
+ tagsAny: [],
105
+ statuses: [],
106
+ trustTiers: [],
107
+ freshness: [],
108
+ frontmatter: {},
109
+ };
53
110
  for (let index = 0; index < argv.length; index += 1) {
54
111
  const arg = argv[index];
112
+ if (arg === "--root" || arg === "-r") {
113
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
114
+ throw usageError(`${arg} requires a value.`);
115
+ }
116
+ if (root) {
117
+ throw usageError("--root may be supplied only once.");
118
+ }
119
+ root = argv[index + 1];
120
+ index += 1;
121
+ continue;
122
+ }
123
+ if (arg.startsWith("--root=")) {
124
+ if (root) {
125
+ throw usageError("--root may be supplied only once.");
126
+ }
127
+ root = arg.slice("--root=".length);
128
+ if (!root) {
129
+ throw usageError("--root requires a value.");
130
+ }
131
+ continue;
132
+ }
55
133
  if (arg === "--bundle" || arg === "-b") {
56
134
  if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
57
135
  throw usageError(`${arg} requires a value.`);
@@ -99,6 +177,22 @@ function parseArgs(argv) {
99
177
  }
100
178
  continue;
101
179
  }
180
+ if (arg === "--repo") {
181
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
182
+ throw usageError("--repo requires concept-id=path.");
183
+ }
184
+ repositories.push(argv[index + 1]);
185
+ index += 1;
186
+ continue;
187
+ }
188
+ if (arg.startsWith("--repo=")) {
189
+ const value = arg.slice("--repo=".length);
190
+ if (!value) {
191
+ throw usageError("--repo requires concept-id=path.");
192
+ }
193
+ repositories.push(value);
194
+ continue;
195
+ }
102
196
  if (arg === "--inspect") {
103
197
  inspect = true;
104
198
  continue;
@@ -111,6 +205,105 @@ function parseArgs(argv) {
111
205
  allowRemoteTool = true;
112
206
  continue;
113
207
  }
208
+ if (arg === "--allow-computation-authoring") {
209
+ allowComputationAuthoring = true;
210
+ continue;
211
+ }
212
+ if (arg === "--strict-links") {
213
+ strictLinks = true;
214
+ continue;
215
+ }
216
+ if (arg === "--include-assets") {
217
+ includeAssets = true;
218
+ continue;
219
+ }
220
+ if (arg === "--include-external") {
221
+ includeExternal = true;
222
+ continue;
223
+ }
224
+ if (arg === "--generated-path") {
225
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
226
+ throw usageError(`${arg} requires a value.`);
227
+ }
228
+ generatedPaths.push(argv[index + 1]);
229
+ index += 1;
230
+ continue;
231
+ }
232
+ if (arg === "--parameters-file" || arg === "--receipt-file") {
233
+ const value = argv[index + 1];
234
+ if (!value || (String(value).startsWith("-") && value !== "-")) {
235
+ throw usageError(`${arg} requires a file path or - for stdin.`);
236
+ }
237
+ if (arg === "--parameters-file") {
238
+ parametersFile = value;
239
+ } else {
240
+ receiptFile = value;
241
+ }
242
+ index += 1;
243
+ continue;
244
+ }
245
+ if (arg === "--max-content-bytes") {
246
+ const value = Number(argv[index + 1]);
247
+ if (!Number.isSafeInteger(value) || value < 1 || value > 1048576) {
248
+ throw usageError("--max-content-bytes requires an integer from 1 through 1048576.");
249
+ }
250
+ maxContentBytes = value;
251
+ index += 1;
252
+ continue;
253
+ }
254
+ const searchValueOptions = {
255
+ "--type": "types",
256
+ "--tag": "tagsAny",
257
+ "--status": "statuses",
258
+ "--trust-tier": "trustTiers",
259
+ "--freshness": "freshness",
260
+ };
261
+ if (Object.prototype.hasOwnProperty.call(searchValueOptions, arg)) {
262
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
263
+ throw usageError(`${arg} requires a value.`);
264
+ }
265
+ search[searchValueOptions[arg]].push(argv[index + 1]);
266
+ index += 1;
267
+ continue;
268
+ }
269
+ const scalarSearchOptions = {
270
+ "--as-of": "asOf",
271
+ "--runtime": "runtime",
272
+ "--linked-to": "linkedTo",
273
+ "--linked-from": "linkedFrom",
274
+ "--relation-type": "relationType",
275
+ "--path-prefix": "pathPrefix",
276
+ };
277
+ if (Object.prototype.hasOwnProperty.call(scalarSearchOptions, arg)) {
278
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
279
+ throw usageError(`${arg} requires a value.`);
280
+ }
281
+ search[scalarSearchOptions[arg]] = argv[index + 1];
282
+ index += 1;
283
+ continue;
284
+ }
285
+ if (arg === "--frontmatter") {
286
+ const value = argv[index + 1];
287
+ const separator = value && value.indexOf("=");
288
+ if (!value || separator <= 0) {
289
+ throw usageError("--frontmatter requires key=value.");
290
+ }
291
+ search.frontmatter[value.slice(0, separator)] = value.slice(separator + 1);
292
+ index += 1;
293
+ continue;
294
+ }
295
+ if (arg === "--has-sources" || arg === "--no-sources") {
296
+ search.hasSources = arg === "--has-sources";
297
+ continue;
298
+ }
299
+ if (arg === "--attestation-ready") {
300
+ search.attestationReady = true;
301
+ continue;
302
+ }
303
+ if (arg === "--orphan-only") {
304
+ search.orphanOnly = true;
305
+ continue;
306
+ }
114
307
  if (arg === "--host") {
115
308
  if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
116
309
  throw usageError(`${arg} requires a value.`);
@@ -181,17 +374,28 @@ function parseArgs(argv) {
181
374
  return {
182
375
  bundles,
183
376
  remoteBundles,
377
+ repositories,
184
378
  positional,
185
379
  project,
380
+ root,
186
381
  inspect,
187
382
  help,
188
383
  version,
189
384
  authoring,
190
385
  allowRemoteTool,
386
+ allowComputationAuthoring,
387
+ strictLinks,
388
+ includeAssets,
389
+ includeExternal,
390
+ parametersFile,
391
+ receiptFile,
392
+ maxContentBytes,
393
+ generatedPaths,
191
394
  host,
192
395
  port,
193
396
  writeToken,
194
397
  proposalRoot,
398
+ search,
195
399
  };
196
400
  }
197
401
 
@@ -200,10 +404,12 @@ function usage() {
200
404
  "okf-mcp / okf",
201
405
  "",
202
406
  "Usage:",
407
+ " okf-mcp --root <okf-directory> <command>",
408
+ " okf-mcp --root <okf-directory> [--repo <repository-concept-id=path>] mcp",
203
409
  " okf-mcp --bundle <path-or-id=path> [--bundle <path>] [--inspect]",
204
410
  " okf-mcp --remote-bundle <id=github-tree-url> [--inspect]",
205
411
  " okf-mcp --project <okf.project.yaml> <command>",
206
- " okf-mcp [--project <okf.project.yaml>] [--authoring] [--allow-remote-tool] mcp",
412
+ " okf-mcp [--project <okf.project.yaml>] [--authoring] [--allow-computation-authoring] [--allow-remote-tool] mcp",
207
413
  " okf-mcp --project <okf.project.yaml> serve [--host 127.0.0.1] [--port 8765]",
208
414
  " okf-mcp <command> --bundle <path-or-id=path>",
209
415
  "",
@@ -212,23 +418,45 @@ function usage() {
212
418
  " validate Validate project or bundles.",
213
419
  " graph [json|dot|mermaid] Export graph.",
214
420
  " search <query> Search concepts.",
215
- " concept <uri> Print one concept.",
216
- " neighbors <uri> Print inbound/outbound neighbors.",
217
- " paths <from> <to> Find directed paths.",
421
+ " concept <id-or-locator> Print one concept.",
422
+ " neighbors <id-or-locator> Print inbound/outbound neighbors.",
423
+ " paths <from> <to> Find directed paths between concept locators.",
424
+ " provenance <id-or-locator> Trace source provenance without external fetches.",
425
+ " edge-kinds Count graph edge kinds.",
426
+ " computation inspect <uri> Inspect a static computation contract.",
427
+ " computation prepare <uri> --parameters-file <path|->",
428
+ " computation check-receipt <uri> --receipt-file <path|->",
429
+ " asset <okf-asset-uri> Read one indexed referenced asset.",
430
+ " source <concept> <source-id> Read one pinned Git source from a mapped repository.",
431
+ " migrate check [bundle] Check staged v0.2 migration readiness.",
432
+ " migrate preview [bundle] [actor-mappings-json]",
218
433
  " generate Run configured generator plugins.",
219
434
  " serve Start the HTTP OKF API server.",
220
435
  "",
221
436
  "Options:",
437
+ " --root, -r <directory> Load one official OKF bundle root.",
438
+ " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
222
439
  " --authoring Enable MCP proposal authoring tools.",
223
440
  " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
441
+ " --allow-computation-authoring Enable coordinated computation proposals (also requires --authoring).",
442
+ " --strict-links Treat broken internal Markdown links as project-invalid.",
443
+ " --include-assets Include referenced asset nodes where supported.",
444
+ " --include-external Include external provenance or graph leaves.",
445
+ " --generated-path <path> Mark a generated migration target; repeat as needed.",
446
+ " --parameters-file <path|-> Read computation parameters from a file or stdin.",
447
+ " --receipt-file <path|-> Read a computation receipt from a file or stdin.",
448
+ " --max-content-bytes <n> Bound asset reads to 1..1048576 bytes (default 65536).",
449
+ " Search filters: --status, --trust-tier, --freshness, --as-of, --has-sources,",
450
+ " --runtime, --attestation-ready, --frontmatter key=value.",
224
451
  " --version, -v Print the package version.",
225
452
  " --help, -h Print this help.",
226
453
  " --debug Include stack traces in error output.",
227
454
  "",
228
- "When no project or bundle source is passed, the nearest okf.project.yaml",
229
- "or okf.project.json is discovered from the current directory.",
455
+ "When no source is passed, a nearest version-declaring OKF root is preferred;",
456
+ "the nearest okf.project.yaml remains a legacy compatibility fallback.",
230
457
  "",
231
458
  "Examples:",
459
+ " node bin/okf-mcp.js --root ./okf/bundles/app validate",
232
460
  " node bin/okf-mcp.js --bundle ./okf/bundles/app --inspect",
233
461
  " node bin/okf-mcp.js --bundle app=./okf/bundles/app",
234
462
  " node bin/okf-mcp.js --remote-bundle docs=https://github.com/org/repo/tree/main/okf/bundles/docs --inspect",
@@ -238,6 +466,9 @@ function usage() {
238
466
  }
239
467
 
240
468
  function resolveLegacyBundles(args) {
469
+ if (args.root) {
470
+ return [args.root];
471
+ }
241
472
  if (args.bundles.length) {
242
473
  return args.bundles;
243
474
  }
@@ -248,6 +479,24 @@ function resolveLegacyBundles(args) {
248
479
  return COMMANDS.has(first) ? [] : args.positional;
249
480
  }
250
481
 
482
+ function parseRepositoryMappings(values) {
483
+ const mappings = new Map();
484
+ (values || []).forEach((value) => {
485
+ const text = String(value || "");
486
+ const separator = text.indexOf("=");
487
+ const conceptId = separator > 0 ? text.slice(0, separator).replace(/^\/+/, "").replace(/\.md$/i, "") : "";
488
+ const repositoryPath = separator > 0 ? text.slice(separator + 1) : "";
489
+ if (!conceptId || !repositoryPath) {
490
+ throw usageError("--repo requires repository-concept-id=checkout-or-bare-repository-path.");
491
+ }
492
+ if (mappings.has(conceptId)) {
493
+ throw usageError(`Duplicate --repo mapping: ${conceptId}`);
494
+ }
495
+ mappings.set(conceptId, repositoryPath);
496
+ });
497
+ return mappings;
498
+ }
499
+
251
500
  function parseRemoteBundleArg(value, index) {
252
501
  const text = String(value || "");
253
502
  const eq = text.indexOf("=");
@@ -262,20 +511,38 @@ function parseRemoteBundleArg(value, index) {
262
511
  }
263
512
 
264
513
  function discoverProject(args, startDir) {
265
- if (!args.project && !args.bundles.length && !args.remoteBundles.length && !resolveLegacyBundles(args).length) {
266
- args.project = findProjectConfig(startDir);
514
+ if (!args.project && !args.root && !args.bundles.length && !args.remoteBundles.length && !resolveLegacyBundles(args).length) {
515
+ args.root = findOkfRoot(startDir);
516
+ if (!args.root) {
517
+ args.project = findProjectConfig(startDir);
518
+ }
267
519
  }
268
520
  return args;
269
521
  }
270
522
 
271
523
  function stdioServerOptions(args) {
524
+ const repositoryMappings = parseRepositoryMappings(args.repositories);
272
525
  const options = {
273
526
  remoteBundles: args.remoteBundles.map(parseRemoteBundleArg),
274
527
  allowAuthoring: Boolean(args.authoring),
275
528
  allowRuntimeRemoteLoad: Boolean(args.allowRemoteTool),
276
529
  };
530
+ if (repositoryMappings.size) {
531
+ options.repositoryMappings = repositoryMappings;
532
+ }
533
+ if (args.authoring && args.allowComputationAuthoring) {
534
+ options.allowComputationAuthoring = true;
535
+ }
536
+ if (args.strictLinks) {
537
+ options.strictLinks = true;
538
+ }
539
+ if (args.proposalRoot) {
540
+ options.proposalRoot = args.proposalRoot;
541
+ }
277
542
  if (args.project) {
278
543
  options.projectPath = args.project;
544
+ } else if (args.root) {
545
+ options.rootPath = args.root;
279
546
  }
280
547
  return options;
281
548
  }
@@ -284,11 +551,14 @@ async function loadIndex(args) {
284
551
  const remoteConfigs = args.remoteBundles.map(parseRemoteBundleArg);
285
552
  if (args.project) {
286
553
  if (!remoteConfigs.length) {
287
- return buildProjectIndexAsync(args.project);
554
+ return buildProjectIndexAsync(args.project, { strictLinks: args.strictLinks || undefined });
288
555
  }
289
556
  const loaded = await loadProjectBundles(args.project);
290
557
  const remoteBundles = await fetchRemoteBundles(remoteConfigs);
291
- const index = buildIndex(loaded.bundles.concat(remoteBundles), { relationTypes: loaded.project.relationTypes });
558
+ const index = buildIndex(loaded.bundles.concat(remoteBundles), {
559
+ relationTypes: loaded.project.relationTypes,
560
+ strictLinks: args.strictLinks || loaded.project.strictLinks,
561
+ });
292
562
  return attachProject(index, loaded.project);
293
563
  }
294
564
  const bundles = resolveLegacyBundles(args);
@@ -296,13 +566,27 @@ async function loadIndex(args) {
296
566
  if (!bundles.length && !fetchedRemoteBundles.length) {
297
567
  throw usageError("At least one --bundle root or --project config is required.");
298
568
  }
299
- return buildIndex(bundles.concat(fetchedRemoteBundles));
569
+ return buildIndex(bundles.concat(fetchedRemoteBundles), {
570
+ strictLinks: args.strictLinks,
571
+ allowCustomRelationTypes: true,
572
+ });
300
573
  }
301
574
 
302
575
  function printJson(value) {
303
576
  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
304
577
  }
305
578
 
579
+ function requireValidConcept(index, locator) {
580
+ const doc = resolveConcept(index, locator);
581
+ if (!doc) {
582
+ throw new Error(`Unknown OKF concept URI or ID: ${locator || "<missing>"}`);
583
+ }
584
+ if (!doc.valid || doc.reserved) {
585
+ throw new Error(`Locator is not a valid OKF concept: ${locator}`);
586
+ }
587
+ return doc;
588
+ }
589
+
306
590
  async function main(argv, runtime) {
307
591
  const args = parseArgs(argv || []);
308
592
  if (args.help) {
@@ -313,6 +597,9 @@ async function main(argv, runtime) {
313
597
  process.stdout.write(`${packageMetadata.version}\n`);
314
598
  return;
315
599
  }
600
+ if (args.root && (args.project || args.bundles.length)) {
601
+ throw usageError("--root cannot be combined with --project or --bundle.");
602
+ }
316
603
  discoverProject(args, (runtime && runtime.cwd) || process.cwd());
317
604
  if (args.inspect) {
318
605
  printJson(graphSummary(await loadIndex(args)));
@@ -325,37 +612,32 @@ async function main(argv, runtime) {
325
612
  if (command === "mcp") {
326
613
  const bundles = resolveLegacyBundles(args);
327
614
  if (args.project) {
328
- const server = await ((runtime && runtime.runStdioServer) || runStdioServer)(
615
+ await ((runtime && runtime.runStdioServer) || runStdioServer)(
329
616
  [],
330
617
  process.stdin,
331
618
  process.stdout,
332
619
  stdioServerOptions(args),
333
620
  );
334
- if (server && server.closed) {
335
- await server.closed;
336
- }
337
621
  return;
338
622
  }
339
623
  if (!bundles.length && !args.remoteBundles.length) {
340
- throw usageError("At least one --bundle root or --project config is required.");
624
+ throw usageError("An OKF --root, --bundle, or --project source is required.");
341
625
  }
342
- const server = await ((runtime && runtime.runStdioServer) || runStdioServer)(
626
+ await ((runtime && runtime.runStdioServer) || runStdioServer)(
343
627
  bundles,
344
628
  process.stdin,
345
629
  process.stdout,
346
630
  stdioServerOptions(args),
347
631
  );
348
- if (server && server.closed) {
349
- await server.closed;
350
- }
351
632
  return;
352
633
  }
353
634
  if (command === "serve") {
354
- if (!args.project) {
355
- throw usageError("serve requires --project.");
635
+ if (!args.project && !args.root) {
636
+ throw usageError("serve requires --root or --project.");
356
637
  }
357
638
  const result = await runHttpServer({
358
639
  projectPath: args.project,
640
+ rootPath: args.root,
359
641
  host: args.host,
360
642
  port: args.port,
361
643
  writeToken: args.writeToken || process.env.OKF_WRITE_TOKEN || "",
@@ -373,6 +655,7 @@ async function main(argv, runtime) {
373
655
  return;
374
656
  }
375
657
  const index = await loadIndex(args);
658
+ const repositoryMappings = parseRepositoryMappings(args.repositories);
376
659
  if (command === "validate") {
377
660
  const result = validateIndex(index);
378
661
  printJson(result);
@@ -380,37 +663,184 @@ async function main(argv, runtime) {
380
663
  return;
381
664
  }
382
665
  if (command === "graph") {
383
- process.stdout.write(exportGraph(index, { format: args.positional[1] || "json", includeExternal: true }) + "\n");
666
+ process.stdout.write(exportGraph(index, {
667
+ format: args.positional[1] || "json",
668
+ includeExternal: args.includeExternal,
669
+ includeAssets: args.includeAssets,
670
+ }) + "\n");
384
671
  return;
385
672
  }
386
673
  if (command === "search") {
387
- printJson(searchConcepts(index, { query: args.positional.slice(1).join(" ") }));
674
+ const filters = Object.assign({}, args.search, { query: args.positional.slice(1).join(" ") });
675
+ if (!Object.keys(filters.frontmatter || {}).length) {
676
+ delete filters.frontmatter;
677
+ }
678
+ printJson(searchConcepts(index, filters));
388
679
  return;
389
680
  }
390
681
  if (command === "concept") {
391
- const uri = args.positional[1];
392
- if (!uri) {
393
- throw usageError("concept requires a URI.");
394
- }
395
- const doc = index.byUri.get(uri);
396
- if (!doc) {
397
- throw new Error(`Unknown OKF concept URI: ${uri || "<missing>"}`);
398
- }
399
- printJson(Object.assign(conceptSummary(doc), { frontmatter: doc.frontmatter, body: doc.body, links: doc.links }));
682
+ const locator = args.positional[1];
683
+ if (!locator) {
684
+ throw usageError("concept requires a Concept ID or locator.");
685
+ }
686
+ const doc = requireValidConcept(index, locator);
687
+ printJson(Object.assign(conceptSummary(doc), {
688
+ frontmatter: doc.frontmatter,
689
+ body: doc.body,
690
+ links: doc.links,
691
+ referencedAssets: (index.assets || []).filter((asset) => (
692
+ (asset.referencedBy || []).some((reference) => reference.uri === doc.uri)
693
+ )).map((asset) => ({
694
+ uri: asset.uri,
695
+ path: asset.path,
696
+ mimeType: asset.mimeType,
697
+ size: asset.size,
698
+ sha256: asset.sha256,
699
+ roles: asset.roles,
700
+ })),
701
+ gitSources: describeConceptGitSources(index, doc, repositoryMappings),
702
+ }));
400
703
  return;
401
704
  }
402
705
  if (command === "neighbors") {
403
706
  if (!args.positional[1]) {
404
707
  throw usageError("neighbors requires a URI.");
405
708
  }
406
- printJson(getNeighbors(index, args.positional[1]));
709
+ const doc = requireValidConcept(index, args.positional[1]);
710
+ printJson(getNeighbors(index, doc.uri, {
711
+ includeAssets: args.includeAssets,
712
+ includeExternal: args.includeExternal,
713
+ }));
407
714
  return;
408
715
  }
409
716
  if (command === "paths") {
410
717
  if (!args.positional[1] || !args.positional[2]) {
411
718
  throw usageError("paths requires <from> and <to> URIs.");
412
719
  }
413
- printJson(findPaths(index, args.positional[1], args.positional[2]));
720
+ const source = requireValidConcept(index, args.positional[1]);
721
+ const target = requireValidConcept(index, args.positional[2]);
722
+ printJson(findPaths(index, source.uri, target.uri));
723
+ return;
724
+ }
725
+ if (command === "provenance") {
726
+ if (!args.positional[1]) {
727
+ throw usageError("provenance requires a URI.");
728
+ }
729
+ printJson(getProvenance(index, args.positional[1], { includeExternal: args.includeExternal }));
730
+ return;
731
+ }
732
+ if (command === "edge-kinds") {
733
+ const counts = {};
734
+ index.edges.forEach((edge) => {
735
+ if (!counts[edge.kind]) {
736
+ counts[edge.kind] = { total: 0, resolved: 0, broken: 0 };
737
+ }
738
+ counts[edge.kind].total += 1;
739
+ counts[edge.kind][edge.broken ? "broken" : "resolved"] += 1;
740
+ });
741
+ printJson(counts);
742
+ return;
743
+ }
744
+ if (command === "computation") {
745
+ const operation = args.positional[1];
746
+ const uri = args.positional[2];
747
+ if (!operation || !uri) {
748
+ throw usageError("computation requires inspect|prepare|check-receipt and a URI.");
749
+ }
750
+ if (operation === "inspect") {
751
+ printJson(inspectAttestedComputation(index, uri, { asOf: args.search.asOf }));
752
+ return;
753
+ }
754
+ if (operation === "prepare") {
755
+ if (args.positional[3]) {
756
+ throw usageError("Raw computation parameters are not accepted in argv; use --parameters-file <path|->.");
757
+ }
758
+ const parameters = args.parametersFile
759
+ ? readJsonObjectSource(args.parametersFile, "computation parameters", runtime)
760
+ : null;
761
+ if (!parameters) {
762
+ throw usageError("computation prepare requires --parameters-file <path|->.");
763
+ }
764
+ printJson(prepareAttestedComputation(
765
+ index,
766
+ uri,
767
+ parameters,
768
+ { asOf: args.search.asOf },
769
+ ));
770
+ return;
771
+ }
772
+ if (operation === "check-receipt") {
773
+ if (args.positional[3]) {
774
+ throw usageError("Raw computation receipts are not accepted in argv; use --receipt-file <path|->.");
775
+ }
776
+ const receipt = args.receiptFile
777
+ ? readJsonObjectSource(args.receiptFile, "computation receipt", runtime)
778
+ : null;
779
+ if (!receipt) {
780
+ throw usageError("computation check-receipt requires --receipt-file <path|->.");
781
+ }
782
+ printJson(checkComputationReceipt(
783
+ index,
784
+ uri,
785
+ receipt,
786
+ ));
787
+ return;
788
+ }
789
+ throw usageError(`Unknown computation operation: ${operation}`);
790
+ }
791
+ if (command === "asset") {
792
+ if (!args.positional[1]) {
793
+ throw usageError("asset requires an okf-asset URI.");
794
+ }
795
+ printJson(readBundleAsset(index, {
796
+ uri: args.positional[1],
797
+ maxContentBytes: args.maxContentBytes,
798
+ }));
799
+ return;
800
+ }
801
+ if (command === "source") {
802
+ if (!args.positional[1] || !args.positional[2]) {
803
+ throw usageError("source requires <concept-id-or-locator> and <source-id>.");
804
+ }
805
+ printJson(readConceptGitSource(
806
+ index,
807
+ args.positional[1],
808
+ args.positional[2],
809
+ repositoryMappings,
810
+ { maxBytes: args.maxContentBytes },
811
+ ));
812
+ return;
813
+ }
814
+ if (command === "migrate") {
815
+ const operation = args.positional[1];
816
+ if (!["check", "preview"].includes(operation)) {
817
+ throw usageError("migrate requires check or preview.");
818
+ }
819
+ let bundleArgument = args.positional[2] || "";
820
+ let actorMappingsArgument = args.positional[3] || "";
821
+ if (operation === "preview"
822
+ && index.bundles.length === 1
823
+ && !actorMappingsArgument
824
+ && bundleArgument.trim().startsWith("{")) {
825
+ actorMappingsArgument = bundleArgument;
826
+ bundleArgument = "";
827
+ }
828
+ const bundle = bundleArgument || (index.bundles.length === 1 ? index.bundles[0].id : "");
829
+ if (!bundle) {
830
+ throw usageError("migrate requires a bundle id when multiple bundles are loaded.");
831
+ }
832
+ if (!index.bundles.some((entry) => entry.id === bundle)) {
833
+ throw usageError(`Unknown bundle id: ${bundle}`);
834
+ }
835
+ const actorMappings = actorMappingsArgument
836
+ ? parseJsonObject(actorMappingsArgument, "actor mappings")
837
+ : {};
838
+ const result = operation === "check"
839
+ ? checkV02Migration(index, { bundle, actorMappings, generatedPaths: args.generatedPaths })
840
+ : buildV02MigrationPlan(index, { bundle, actorMappings, generatedPaths: args.generatedPaths });
841
+ printJson(result);
842
+ const report = operation === "check" ? result : result.report;
843
+ process.exitCode = report.blockers.length ? 1 : 0;
414
844
  return;
415
845
  }
416
846
  throw usageError(`Unknown OKF command: ${command}`);