@mfdaves/okf-mcp 0.3.3 → 0.5.1

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 (41) 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 +217 -79
  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 +9 -5
  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 +7 -7
  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 +10 -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 +468 -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 +450 -315
  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-index.js +83 -0
  37. package/src/search.js +103 -47
  38. package/src/store.js +421 -25
  39. package/src/v02.js +545 -0
  40. package/src/validation.js +13 -2
  41. 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,46 @@ 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.",
451
+ " Text search requires all terms and accepts at most 512 characters and 16 terms.",
224
452
  " --version, -v Print the package version.",
225
453
  " --help, -h Print this help.",
226
454
  " --debug Include stack traces in error output.",
227
455
  "",
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.",
456
+ "When no source is passed, a nearest version-declaring OKF root is preferred;",
457
+ "the nearest okf.project.yaml remains a legacy compatibility fallback.",
230
458
  "",
231
459
  "Examples:",
460
+ " node bin/okf-mcp.js --root ./okf/bundles/app validate",
232
461
  " node bin/okf-mcp.js --bundle ./okf/bundles/app --inspect",
233
462
  " node bin/okf-mcp.js --bundle app=./okf/bundles/app",
234
463
  " node bin/okf-mcp.js --remote-bundle docs=https://github.com/org/repo/tree/main/okf/bundles/docs --inspect",
@@ -238,6 +467,9 @@ function usage() {
238
467
  }
239
468
 
240
469
  function resolveLegacyBundles(args) {
470
+ if (args.root) {
471
+ return [args.root];
472
+ }
241
473
  if (args.bundles.length) {
242
474
  return args.bundles;
243
475
  }
@@ -248,6 +480,24 @@ function resolveLegacyBundles(args) {
248
480
  return COMMANDS.has(first) ? [] : args.positional;
249
481
  }
250
482
 
483
+ function parseRepositoryMappings(values) {
484
+ const mappings = new Map();
485
+ (values || []).forEach((value) => {
486
+ const text = String(value || "");
487
+ const separator = text.indexOf("=");
488
+ const conceptId = separator > 0 ? text.slice(0, separator).replace(/^\/+/, "").replace(/\.md$/i, "") : "";
489
+ const repositoryPath = separator > 0 ? text.slice(separator + 1) : "";
490
+ if (!conceptId || !repositoryPath) {
491
+ throw usageError("--repo requires repository-concept-id=checkout-or-bare-repository-path.");
492
+ }
493
+ if (mappings.has(conceptId)) {
494
+ throw usageError(`Duplicate --repo mapping: ${conceptId}`);
495
+ }
496
+ mappings.set(conceptId, repositoryPath);
497
+ });
498
+ return mappings;
499
+ }
500
+
251
501
  function parseRemoteBundleArg(value, index) {
252
502
  const text = String(value || "");
253
503
  const eq = text.indexOf("=");
@@ -262,20 +512,38 @@ function parseRemoteBundleArg(value, index) {
262
512
  }
263
513
 
264
514
  function discoverProject(args, startDir) {
265
- if (!args.project && !args.bundles.length && !args.remoteBundles.length && !resolveLegacyBundles(args).length) {
266
- args.project = findProjectConfig(startDir);
515
+ if (!args.project && !args.root && !args.bundles.length && !args.remoteBundles.length && !resolveLegacyBundles(args).length) {
516
+ args.root = findOkfRoot(startDir);
517
+ if (!args.root) {
518
+ args.project = findProjectConfig(startDir);
519
+ }
267
520
  }
268
521
  return args;
269
522
  }
270
523
 
271
524
  function stdioServerOptions(args) {
525
+ const repositoryMappings = parseRepositoryMappings(args.repositories);
272
526
  const options = {
273
527
  remoteBundles: args.remoteBundles.map(parseRemoteBundleArg),
274
528
  allowAuthoring: Boolean(args.authoring),
275
529
  allowRuntimeRemoteLoad: Boolean(args.allowRemoteTool),
276
530
  };
531
+ if (repositoryMappings.size) {
532
+ options.repositoryMappings = repositoryMappings;
533
+ }
534
+ if (args.authoring && args.allowComputationAuthoring) {
535
+ options.allowComputationAuthoring = true;
536
+ }
537
+ if (args.strictLinks) {
538
+ options.strictLinks = true;
539
+ }
540
+ if (args.proposalRoot) {
541
+ options.proposalRoot = args.proposalRoot;
542
+ }
277
543
  if (args.project) {
278
544
  options.projectPath = args.project;
545
+ } else if (args.root) {
546
+ options.rootPath = args.root;
279
547
  }
280
548
  return options;
281
549
  }
@@ -284,11 +552,14 @@ async function loadIndex(args) {
284
552
  const remoteConfigs = args.remoteBundles.map(parseRemoteBundleArg);
285
553
  if (args.project) {
286
554
  if (!remoteConfigs.length) {
287
- return buildProjectIndexAsync(args.project);
555
+ return buildProjectIndexAsync(args.project, { strictLinks: args.strictLinks || undefined });
288
556
  }
289
557
  const loaded = await loadProjectBundles(args.project);
290
558
  const remoteBundles = await fetchRemoteBundles(remoteConfigs);
291
- const index = buildIndex(loaded.bundles.concat(remoteBundles), { relationTypes: loaded.project.relationTypes });
559
+ const index = buildIndex(loaded.bundles.concat(remoteBundles), {
560
+ relationTypes: loaded.project.relationTypes,
561
+ strictLinks: args.strictLinks || loaded.project.strictLinks,
562
+ });
292
563
  return attachProject(index, loaded.project);
293
564
  }
294
565
  const bundles = resolveLegacyBundles(args);
@@ -296,13 +567,27 @@ async function loadIndex(args) {
296
567
  if (!bundles.length && !fetchedRemoteBundles.length) {
297
568
  throw usageError("At least one --bundle root or --project config is required.");
298
569
  }
299
- return buildIndex(bundles.concat(fetchedRemoteBundles));
570
+ return buildIndex(bundles.concat(fetchedRemoteBundles), {
571
+ strictLinks: args.strictLinks,
572
+ allowCustomRelationTypes: true,
573
+ });
300
574
  }
301
575
 
302
576
  function printJson(value) {
303
577
  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
304
578
  }
305
579
 
580
+ function requireValidConcept(index, locator) {
581
+ const doc = resolveConcept(index, locator);
582
+ if (!doc) {
583
+ throw new Error(`Unknown OKF concept URI or ID: ${locator || "<missing>"}`);
584
+ }
585
+ if (!doc.valid || doc.reserved) {
586
+ throw new Error(`Locator is not a valid OKF concept: ${locator}`);
587
+ }
588
+ return doc;
589
+ }
590
+
306
591
  async function main(argv, runtime) {
307
592
  const args = parseArgs(argv || []);
308
593
  if (args.help) {
@@ -313,6 +598,9 @@ async function main(argv, runtime) {
313
598
  process.stdout.write(`${packageMetadata.version}\n`);
314
599
  return;
315
600
  }
601
+ if (args.root && (args.project || args.bundles.length)) {
602
+ throw usageError("--root cannot be combined with --project or --bundle.");
603
+ }
316
604
  discoverProject(args, (runtime && runtime.cwd) || process.cwd());
317
605
  if (args.inspect) {
318
606
  printJson(graphSummary(await loadIndex(args)));
@@ -325,37 +613,32 @@ async function main(argv, runtime) {
325
613
  if (command === "mcp") {
326
614
  const bundles = resolveLegacyBundles(args);
327
615
  if (args.project) {
328
- const server = await ((runtime && runtime.runStdioServer) || runStdioServer)(
616
+ await ((runtime && runtime.runStdioServer) || runStdioServer)(
329
617
  [],
330
618
  process.stdin,
331
619
  process.stdout,
332
620
  stdioServerOptions(args),
333
621
  );
334
- if (server && server.closed) {
335
- await server.closed;
336
- }
337
622
  return;
338
623
  }
339
624
  if (!bundles.length && !args.remoteBundles.length) {
340
- throw usageError("At least one --bundle root or --project config is required.");
625
+ throw usageError("An OKF --root, --bundle, or --project source is required.");
341
626
  }
342
- const server = await ((runtime && runtime.runStdioServer) || runStdioServer)(
627
+ await ((runtime && runtime.runStdioServer) || runStdioServer)(
343
628
  bundles,
344
629
  process.stdin,
345
630
  process.stdout,
346
631
  stdioServerOptions(args),
347
632
  );
348
- if (server && server.closed) {
349
- await server.closed;
350
- }
351
633
  return;
352
634
  }
353
635
  if (command === "serve") {
354
- if (!args.project) {
355
- throw usageError("serve requires --project.");
636
+ if (!args.project && !args.root) {
637
+ throw usageError("serve requires --root or --project.");
356
638
  }
357
639
  const result = await runHttpServer({
358
640
  projectPath: args.project,
641
+ rootPath: args.root,
359
642
  host: args.host,
360
643
  port: args.port,
361
644
  writeToken: args.writeToken || process.env.OKF_WRITE_TOKEN || "",
@@ -373,6 +656,7 @@ async function main(argv, runtime) {
373
656
  return;
374
657
  }
375
658
  const index = await loadIndex(args);
659
+ const repositoryMappings = parseRepositoryMappings(args.repositories);
376
660
  if (command === "validate") {
377
661
  const result = validateIndex(index);
378
662
  printJson(result);
@@ -380,37 +664,184 @@ async function main(argv, runtime) {
380
664
  return;
381
665
  }
382
666
  if (command === "graph") {
383
- process.stdout.write(exportGraph(index, { format: args.positional[1] || "json", includeExternal: true }) + "\n");
667
+ process.stdout.write(exportGraph(index, {
668
+ format: args.positional[1] || "json",
669
+ includeExternal: args.includeExternal,
670
+ includeAssets: args.includeAssets,
671
+ }) + "\n");
384
672
  return;
385
673
  }
386
674
  if (command === "search") {
387
- printJson(searchConcepts(index, { query: args.positional.slice(1).join(" ") }));
675
+ const filters = Object.assign({}, args.search, { query: args.positional.slice(1).join(" ") });
676
+ if (!Object.keys(filters.frontmatter || {}).length) {
677
+ delete filters.frontmatter;
678
+ }
679
+ printJson(searchConcepts(index, filters));
388
680
  return;
389
681
  }
390
682
  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 }));
683
+ const locator = args.positional[1];
684
+ if (!locator) {
685
+ throw usageError("concept requires a Concept ID or locator.");
686
+ }
687
+ const doc = requireValidConcept(index, locator);
688
+ printJson(Object.assign(conceptSummary(doc), {
689
+ frontmatter: doc.frontmatter,
690
+ body: doc.body,
691
+ links: doc.links,
692
+ referencedAssets: (index.assets || []).filter((asset) => (
693
+ (asset.referencedBy || []).some((reference) => reference.uri === doc.uri)
694
+ )).map((asset) => ({
695
+ uri: asset.uri,
696
+ path: asset.path,
697
+ mimeType: asset.mimeType,
698
+ size: asset.size,
699
+ sha256: asset.sha256,
700
+ roles: asset.roles,
701
+ })),
702
+ gitSources: describeConceptGitSources(index, doc, repositoryMappings),
703
+ }));
400
704
  return;
401
705
  }
402
706
  if (command === "neighbors") {
403
707
  if (!args.positional[1]) {
404
708
  throw usageError("neighbors requires a URI.");
405
709
  }
406
- printJson(getNeighbors(index, args.positional[1]));
710
+ const doc = requireValidConcept(index, args.positional[1]);
711
+ printJson(getNeighbors(index, doc.uri, {
712
+ includeAssets: args.includeAssets,
713
+ includeExternal: args.includeExternal,
714
+ }));
407
715
  return;
408
716
  }
409
717
  if (command === "paths") {
410
718
  if (!args.positional[1] || !args.positional[2]) {
411
719
  throw usageError("paths requires <from> and <to> URIs.");
412
720
  }
413
- printJson(findPaths(index, args.positional[1], args.positional[2]));
721
+ const source = requireValidConcept(index, args.positional[1]);
722
+ const target = requireValidConcept(index, args.positional[2]);
723
+ printJson(findPaths(index, source.uri, target.uri));
724
+ return;
725
+ }
726
+ if (command === "provenance") {
727
+ if (!args.positional[1]) {
728
+ throw usageError("provenance requires a URI.");
729
+ }
730
+ printJson(getProvenance(index, args.positional[1], { includeExternal: args.includeExternal }));
731
+ return;
732
+ }
733
+ if (command === "edge-kinds") {
734
+ const counts = {};
735
+ index.edges.forEach((edge) => {
736
+ if (!counts[edge.kind]) {
737
+ counts[edge.kind] = { total: 0, resolved: 0, broken: 0 };
738
+ }
739
+ counts[edge.kind].total += 1;
740
+ counts[edge.kind][edge.broken ? "broken" : "resolved"] += 1;
741
+ });
742
+ printJson(counts);
743
+ return;
744
+ }
745
+ if (command === "computation") {
746
+ const operation = args.positional[1];
747
+ const uri = args.positional[2];
748
+ if (!operation || !uri) {
749
+ throw usageError("computation requires inspect|prepare|check-receipt and a URI.");
750
+ }
751
+ if (operation === "inspect") {
752
+ printJson(inspectAttestedComputation(index, uri, { asOf: args.search.asOf }));
753
+ return;
754
+ }
755
+ if (operation === "prepare") {
756
+ if (args.positional[3]) {
757
+ throw usageError("Raw computation parameters are not accepted in argv; use --parameters-file <path|->.");
758
+ }
759
+ const parameters = args.parametersFile
760
+ ? readJsonObjectSource(args.parametersFile, "computation parameters", runtime)
761
+ : null;
762
+ if (!parameters) {
763
+ throw usageError("computation prepare requires --parameters-file <path|->.");
764
+ }
765
+ printJson(prepareAttestedComputation(
766
+ index,
767
+ uri,
768
+ parameters,
769
+ { asOf: args.search.asOf },
770
+ ));
771
+ return;
772
+ }
773
+ if (operation === "check-receipt") {
774
+ if (args.positional[3]) {
775
+ throw usageError("Raw computation receipts are not accepted in argv; use --receipt-file <path|->.");
776
+ }
777
+ const receipt = args.receiptFile
778
+ ? readJsonObjectSource(args.receiptFile, "computation receipt", runtime)
779
+ : null;
780
+ if (!receipt) {
781
+ throw usageError("computation check-receipt requires --receipt-file <path|->.");
782
+ }
783
+ printJson(checkComputationReceipt(
784
+ index,
785
+ uri,
786
+ receipt,
787
+ ));
788
+ return;
789
+ }
790
+ throw usageError(`Unknown computation operation: ${operation}`);
791
+ }
792
+ if (command === "asset") {
793
+ if (!args.positional[1]) {
794
+ throw usageError("asset requires an okf-asset URI.");
795
+ }
796
+ printJson(readBundleAsset(index, {
797
+ uri: args.positional[1],
798
+ maxContentBytes: args.maxContentBytes,
799
+ }));
800
+ return;
801
+ }
802
+ if (command === "source") {
803
+ if (!args.positional[1] || !args.positional[2]) {
804
+ throw usageError("source requires <concept-id-or-locator> and <source-id>.");
805
+ }
806
+ printJson(readConceptGitSource(
807
+ index,
808
+ args.positional[1],
809
+ args.positional[2],
810
+ repositoryMappings,
811
+ { maxBytes: args.maxContentBytes },
812
+ ));
813
+ return;
814
+ }
815
+ if (command === "migrate") {
816
+ const operation = args.positional[1];
817
+ if (!["check", "preview"].includes(operation)) {
818
+ throw usageError("migrate requires check or preview.");
819
+ }
820
+ let bundleArgument = args.positional[2] || "";
821
+ let actorMappingsArgument = args.positional[3] || "";
822
+ if (operation === "preview"
823
+ && index.bundles.length === 1
824
+ && !actorMappingsArgument
825
+ && bundleArgument.trim().startsWith("{")) {
826
+ actorMappingsArgument = bundleArgument;
827
+ bundleArgument = "";
828
+ }
829
+ const bundle = bundleArgument || (index.bundles.length === 1 ? index.bundles[0].id : "");
830
+ if (!bundle) {
831
+ throw usageError("migrate requires a bundle id when multiple bundles are loaded.");
832
+ }
833
+ if (!index.bundles.some((entry) => entry.id === bundle)) {
834
+ throw usageError(`Unknown bundle id: ${bundle}`);
835
+ }
836
+ const actorMappings = actorMappingsArgument
837
+ ? parseJsonObject(actorMappingsArgument, "actor mappings")
838
+ : {};
839
+ const result = operation === "check"
840
+ ? checkV02Migration(index, { bundle, actorMappings, generatedPaths: args.generatedPaths })
841
+ : buildV02MigrationPlan(index, { bundle, actorMappings, generatedPaths: args.generatedPaths });
842
+ printJson(result);
843
+ const report = operation === "check" ? result : result.report;
844
+ process.exitCode = report.blockers.length ? 1 : 0;
414
845
  return;
415
846
  }
416
847
  throw usageError(`Unknown OKF command: ${command}`);