@mfdaves/okf-mcp 0.7.0 → 0.9.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.
- package/README.md +79 -18
- package/okf/{bundles/okf-mcp → okf-mcp}/distribution/reference-bundle.md +1 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/index.md +3 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/mcp-tools.md +13 -5
- package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
- package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +9 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/runtime/file-concept-store.md +1 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/runtime/mcp-server.md +6 -2
- package/okf/okf-mcp/runtime/producer-host.md +28 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/specs/concept-format.md +1 -1
- package/okf/okf-mcp/specs/producer-api.md +26 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-authoring.md +1 -1
- package/okf/okf-mcp/workflows/producer-publication.md +28 -0
- package/okf.project.yaml +1 -1
- package/package.json +2 -2
- package/server.json +11 -3
- package/src/authoring.js +47 -11
- package/src/cli.js +46 -4
- package/src/graph.js +2 -2
- package/src/index.js +2 -0
- package/src/indexer.js +166 -8
- package/src/live-authoring.js +132 -50
- package/src/mcp-server.js +189 -13
- package/src/producer-publisher.js +462 -0
- package/src/producers.js +507 -0
- package/src/project.js +65 -0
- package/src/search.js +19 -0
- package/src/store.js +1 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/http-authoring-api.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/runtime/indexer.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/specs/attested-computation.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/specs/git-sources.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-update.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/v02-migration.md +0 -0
package/src/live-authoring.js
CHANGED
|
@@ -8,6 +8,7 @@ const { isDeepStrictEqual } = require("node:util");
|
|
|
8
8
|
|
|
9
9
|
const {
|
|
10
10
|
deriveConceptPathSuggestion,
|
|
11
|
+
isConfiguredGeneratorOutput,
|
|
11
12
|
normalizeConceptPath,
|
|
12
13
|
renderConceptMarkdown,
|
|
13
14
|
} = require("./authoring");
|
|
@@ -15,6 +16,10 @@ const {
|
|
|
15
16
|
attachProject,
|
|
16
17
|
buildIndex,
|
|
17
18
|
bundleAllowsPath,
|
|
19
|
+
conceptIsGeneratedFile,
|
|
20
|
+
conceptMatchSummary,
|
|
21
|
+
normalizeConceptTitle,
|
|
22
|
+
recoverConceptLocator,
|
|
18
23
|
resolveConcept,
|
|
19
24
|
validateIndex,
|
|
20
25
|
} = require("./indexer");
|
|
@@ -43,9 +48,11 @@ const MANAGED_METADATA_KEYS = new Set([
|
|
|
43
48
|
]);
|
|
44
49
|
|
|
45
50
|
class AuthoringPolicyError extends Error {
|
|
46
|
-
constructor(message) {
|
|
51
|
+
constructor(message, code, details) {
|
|
47
52
|
super(message);
|
|
48
53
|
this.name = "AuthoringPolicyError";
|
|
54
|
+
if (code) this.code = code;
|
|
55
|
+
if (details !== undefined) this.details = details;
|
|
49
56
|
}
|
|
50
57
|
}
|
|
51
58
|
|
|
@@ -339,11 +346,6 @@ function actorValue(value) {
|
|
|
339
346
|
return actor;
|
|
340
347
|
}
|
|
341
348
|
|
|
342
|
-
function isInside(root, candidate) {
|
|
343
|
-
const relative = path.relative(path.resolve(root), path.resolve(candidate));
|
|
344
|
-
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
|
|
345
|
-
}
|
|
346
|
-
|
|
347
349
|
function generatedOwners(document) {
|
|
348
350
|
const owners = [];
|
|
349
351
|
const generated = document && document.frontmatter && document.frontmatter.generated;
|
|
@@ -383,18 +385,37 @@ function sortedUnique(values) {
|
|
|
383
385
|
return Array.from(new Set(values)).sort();
|
|
384
386
|
}
|
|
385
387
|
|
|
386
|
-
function boundedEffectList(values) {
|
|
387
|
-
const normalized =
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
});
|
|
388
|
+
function boundedEffectList(values, project) {
|
|
389
|
+
const normalized = project
|
|
390
|
+
? values.map(project)
|
|
391
|
+
: sortedUnique(values).map(boundedEffectText);
|
|
391
392
|
return {
|
|
392
393
|
values: normalized.slice(0, MAX_EFFECT_ITEMS),
|
|
393
394
|
omitted: Math.max(0, normalized.length - MAX_EFFECT_ITEMS),
|
|
394
395
|
};
|
|
395
396
|
}
|
|
396
397
|
|
|
397
|
-
function
|
|
398
|
+
function boundedEffectText(value) {
|
|
399
|
+
const text = String(value || "");
|
|
400
|
+
return text.length > MAX_EFFECT_TEXT ? `${text.slice(0, MAX_EFFECT_TEXT - 1)}…` : text;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
function relationEffectValue(value) {
|
|
404
|
+
const parts = relationParts(value);
|
|
405
|
+
const result = {
|
|
406
|
+
type: boundedEffectText(parts.type),
|
|
407
|
+
target: boundedEffectText(parts.target),
|
|
408
|
+
};
|
|
409
|
+
if (isPlainObject(value) && hasOwn(value, "label")) {
|
|
410
|
+
result.label = boundedEffectText(value.label);
|
|
411
|
+
}
|
|
412
|
+
if (isPlainObject(value) && hasOwn(value, "description")) {
|
|
413
|
+
result.description = boundedEffectText(value.description);
|
|
414
|
+
}
|
|
415
|
+
return result;
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
function collectionEffects(before, after, identity, project) {
|
|
398
419
|
const previous = new Map((before || []).map((value) => [identity(value), value]));
|
|
399
420
|
const next = new Map((after || []).map((value) => [identity(value), value]));
|
|
400
421
|
const added = Array.from(next.keys()).filter((key) => !previous.has(key)).sort();
|
|
@@ -402,10 +423,14 @@ function collectionEffects(before, after, identity) {
|
|
|
402
423
|
const updated = Array.from(next.keys()).filter((key) => (
|
|
403
424
|
previous.has(key) && !isDeepStrictEqual(previous.get(key), next.get(key))
|
|
404
425
|
)).sort();
|
|
426
|
+
const effectList = (keys, values) => boundedEffectList(
|
|
427
|
+
project ? keys.map((key) => values.get(key)) : keys,
|
|
428
|
+
project,
|
|
429
|
+
);
|
|
405
430
|
return {
|
|
406
|
-
added:
|
|
407
|
-
removed:
|
|
408
|
-
updated:
|
|
431
|
+
added: effectList(added, next),
|
|
432
|
+
removed: effectList(removed, previous),
|
|
433
|
+
updated: effectList(updated, next),
|
|
409
434
|
};
|
|
410
435
|
}
|
|
411
436
|
|
|
@@ -424,7 +449,7 @@ function effectsForCandidate(candidate) {
|
|
|
424
449
|
const after = candidate.frontmatter;
|
|
425
450
|
const tags = collectionEffects(before.tags, after.tags, (value) => String(value));
|
|
426
451
|
const sources = collectionEffects(before.sources, after.sources, sourceIdentity);
|
|
427
|
-
const relations = collectionEffects(before.relations, after.relations, relationKey);
|
|
452
|
+
const relations = collectionEffects(before.relations, after.relations, relationKey, relationEffectValue);
|
|
428
453
|
const metadata = metadataEffects(before, after);
|
|
429
454
|
const bodyChanged = candidate.op === "create"
|
|
430
455
|
? true
|
|
@@ -436,7 +461,6 @@ function effectsForCandidate(candidate) {
|
|
|
436
461
|
if (hasEffect(sources.added) || hasEffect(sources.removed) || hasEffect(sources.updated)) changedFields.push("sources");
|
|
437
462
|
if (hasEffect(relations.added) || hasEffect(relations.removed) || hasEffect(relations.updated)) changedFields.push("relations");
|
|
438
463
|
if (hasEffect(metadata.set) || hasEffect(metadata.removed)) changedFields.push("metadata");
|
|
439
|
-
if (!isDeepStrictEqual(before.generated, after.generated)) changedFields.push("generated");
|
|
440
464
|
return {
|
|
441
465
|
changedFields,
|
|
442
466
|
bodyChanged,
|
|
@@ -451,6 +475,47 @@ function effectsForCandidate(candidate) {
|
|
|
451
475
|
};
|
|
452
476
|
}
|
|
453
477
|
|
|
478
|
+
function semanticConceptKey(type, title) {
|
|
479
|
+
return `${String(type || "")}\u0000${normalizeConceptTitle(title)}`;
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
function conceptIsManaged(doc, project) {
|
|
483
|
+
return conceptIsGeneratedFile(doc)
|
|
484
|
+
|| generatedOwners(doc).some((owner) => owner.startsWith("process:"))
|
|
485
|
+
|| isConfiguredGeneratorOutput(project, doc && doc.absolutePath);
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
function conceptConflictDetails(matches, project) {
|
|
489
|
+
const candidates = matches.slice(0, 5).map((doc) => conceptMatchSummary(doc));
|
|
490
|
+
const only = candidates.length === 1 ? candidates[0] : null;
|
|
491
|
+
const generated = matches.length === 1 && conceptIsManaged(matches[0], project);
|
|
492
|
+
const updateable = only && !generated && only.type !== "Attested Computation";
|
|
493
|
+
return {
|
|
494
|
+
reason: "same_type_title",
|
|
495
|
+
candidates,
|
|
496
|
+
omitted: Math.max(0, matches.length - candidates.length),
|
|
497
|
+
recommendedOperation: updateable ? "update" : generated ? "change_generator" : "review",
|
|
498
|
+
...(updateable ? { retryWith: { op: "update", uri: only.uri } } : {}),
|
|
499
|
+
};
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
function staleUpdateDetails(index, uri, bundle, project) {
|
|
503
|
+
const recovery = recoverConceptLocator(index, uri, { bundle, limit: 5 });
|
|
504
|
+
const only = recovery.candidates.length === 1 ? recovery.candidates[0] : null;
|
|
505
|
+
const matched = only && resolveConcept(index, only.uri);
|
|
506
|
+
if (only && (conceptIsManaged(matched, project)
|
|
507
|
+
|| only.type === "Attested Computation")) {
|
|
508
|
+
delete recovery.retryWith;
|
|
509
|
+
recovery.recommendedOperation = only.type === "Attested Computation"
|
|
510
|
+
? "review_computation_owner"
|
|
511
|
+
: "change_generator";
|
|
512
|
+
} else if (recovery.retryWith) {
|
|
513
|
+
recovery.retryWith.op = "update";
|
|
514
|
+
recovery.recommendedOperation = "update";
|
|
515
|
+
}
|
|
516
|
+
return { recovery };
|
|
517
|
+
}
|
|
518
|
+
|
|
454
519
|
function policyCode(message) {
|
|
455
520
|
const text = String(message || "");
|
|
456
521
|
if (/generated|generator/i.test(text)) return "generated_owner_protected";
|
|
@@ -473,19 +538,23 @@ function policyCode(message) {
|
|
|
473
538
|
return "authoring_policy_rejected";
|
|
474
539
|
}
|
|
475
540
|
|
|
476
|
-
function policyValidation(
|
|
477
|
-
const
|
|
541
|
+
function policyValidation(error) {
|
|
542
|
+
const message = error && error.message ? error.message : String(error);
|
|
543
|
+
const code = error && error.code || policyCode(message);
|
|
544
|
+
const details = error && error.details;
|
|
545
|
+
const diagnostic = {
|
|
546
|
+
code,
|
|
547
|
+
severity: "error",
|
|
548
|
+
layer: "authoring",
|
|
549
|
+
message,
|
|
550
|
+
...(details !== undefined ? { details } : {}),
|
|
551
|
+
};
|
|
478
552
|
return {
|
|
479
553
|
valid: false,
|
|
480
554
|
conformant: false,
|
|
481
555
|
validForProject: false,
|
|
482
|
-
diagnostics: [
|
|
483
|
-
|
|
484
|
-
severity: "error",
|
|
485
|
-
layer: "authoring",
|
|
486
|
-
message,
|
|
487
|
-
}],
|
|
488
|
-
errors: [{ code, message }],
|
|
556
|
+
diagnostics: [diagnostic],
|
|
557
|
+
errors: [{ code, message, ...(details !== undefined ? { details } : {}) }],
|
|
489
558
|
warnings: [],
|
|
490
559
|
};
|
|
491
560
|
}
|
|
@@ -547,32 +616,13 @@ class LiveAuthoringService {
|
|
|
547
616
|
return this.store.project ? attachProject(index, this.store.project) : index;
|
|
548
617
|
}
|
|
549
618
|
|
|
550
|
-
generatedOutputDirectories() {
|
|
551
|
-
const project = this.store.project;
|
|
552
|
-
if (!project || !project.root) {
|
|
553
|
-
return [];
|
|
554
|
-
}
|
|
555
|
-
return (project.plugins || [])
|
|
556
|
-
.filter((plugin) => plugin && plugin.output)
|
|
557
|
-
.map((plugin) => path.resolve(project.root, String(plugin.output)));
|
|
558
|
-
}
|
|
559
|
-
|
|
560
619
|
assertWritableTarget(bundle, conceptPath, existing) {
|
|
561
620
|
const target = this.store.resolveConceptFile(bundle.id, conceptPath);
|
|
562
|
-
if (this.
|
|
621
|
+
if (isConfiguredGeneratorOutput(this.store.project, target.absolutePath)) {
|
|
563
622
|
throw new Error(`Concept is inside a configured generator output and must be changed through its generator: ${conceptPath}`);
|
|
564
623
|
}
|
|
565
|
-
if (existing) {
|
|
566
|
-
|
|
567
|
-
if (existing.generatedFile === true
|
|
568
|
-
|| existing.isGenerated === true
|
|
569
|
-
|| frontmatter.generated_file === true
|
|
570
|
-
|| frontmatter.generatedFile === true) {
|
|
571
|
-
throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
|
|
572
|
-
}
|
|
573
|
-
if (generatedOwners(existing).some((owner) => owner.startsWith("process:"))) {
|
|
574
|
-
throw new Error(`Process-generated concept must be changed through its generator: ${existing.uri}`);
|
|
575
|
-
}
|
|
624
|
+
if (existing && conceptIsManaged(existing, this.store.project)) {
|
|
625
|
+
throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
|
|
576
626
|
}
|
|
577
627
|
return target;
|
|
578
628
|
}
|
|
@@ -636,7 +686,12 @@ class LiveAuthoringService {
|
|
|
636
686
|
const uri = nonEmptyString(change.uri, "changes[].uri");
|
|
637
687
|
const existing = resolveConcept(currentIndex, uri);
|
|
638
688
|
if (!existing || !existing.valid || existing.reserved) {
|
|
639
|
-
|
|
689
|
+
const details = staleUpdateDetails(currentIndex, uri, bundle.id, this.store.project);
|
|
690
|
+
throw new AuthoringPolicyError(
|
|
691
|
+
`Unknown valid OKF concept: ${uri}`,
|
|
692
|
+
details.recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
|
|
693
|
+
details,
|
|
694
|
+
);
|
|
640
695
|
}
|
|
641
696
|
if (existing.bundle !== bundle.id) {
|
|
642
697
|
throw new Error(`All changes must target writable bundle ${bundle.id}: ${uri}`);
|
|
@@ -1940,6 +1995,31 @@ class LiveAuthoringService {
|
|
|
1940
1995
|
}
|
|
1941
1996
|
}
|
|
1942
1997
|
}
|
|
1998
|
+
const currentConcepts = currentIndex.concepts.filter((doc) => doc.bundle === bundle.id);
|
|
1999
|
+
const replacedPaths = new Set(candidates.filter((entry) => entry.op === "update").map((entry) => entry.path));
|
|
2000
|
+
const finalConcepts = currentConcepts.filter((doc) => !replacedPaths.has(doc.path)).concat(candidates);
|
|
2001
|
+
for (const candidate of candidates) {
|
|
2002
|
+
const key = semanticConceptKey(candidate.frontmatter.type, candidate.title);
|
|
2003
|
+
const before = currentConcepts.filter((doc) => semanticConceptKey(doc.type, doc.title) === key);
|
|
2004
|
+
const after = finalConcepts.filter((doc) => (
|
|
2005
|
+
semanticConceptKey(doc.type || doc.frontmatter.type, doc.title) === key
|
|
2006
|
+
));
|
|
2007
|
+
if (after.length <= Math.max(1, before.length)) continue;
|
|
2008
|
+
const existing = after.filter((doc) => !candidates.includes(doc));
|
|
2009
|
+
const details = candidate.op === "create" && existing.length === 1 && after.length === 2
|
|
2010
|
+
? conceptConflictDetails(existing, this.store.project)
|
|
2011
|
+
: {
|
|
2012
|
+
reason: before.length ? "same_type_title" : "same_batch_type_title",
|
|
2013
|
+
candidates: after.slice(0, 5).map((doc) => conceptMatchSummary(doc)),
|
|
2014
|
+
omitted: Math.max(0, after.length - 5),
|
|
2015
|
+
recommendedOperation: "merge_batch_changes",
|
|
2016
|
+
};
|
|
2017
|
+
throw new AuthoringPolicyError(
|
|
2018
|
+
`The batch would leave more than one ${candidate.frontmatter.type} titled "${candidate.title}".`,
|
|
2019
|
+
"concept_already_exists",
|
|
2020
|
+
details,
|
|
2021
|
+
);
|
|
2022
|
+
}
|
|
1943
2023
|
const message = this.commitMessage(input, candidates);
|
|
1944
2024
|
const overrides = new Map(candidates.map((candidate) => [
|
|
1945
2025
|
`${candidate.bundle}\u0000${candidate.path}`,
|
|
@@ -1998,7 +2078,7 @@ class LiveAuthoringService {
|
|
|
1998
2078
|
}
|
|
1999
2079
|
|
|
2000
2080
|
invalidValidationReceipt(error) {
|
|
2001
|
-
const validation = policyValidation(error
|
|
2081
|
+
const validation = policyValidation(error);
|
|
2002
2082
|
const generated = this.generatedStamp();
|
|
2003
2083
|
return {
|
|
2004
2084
|
valid: false,
|
|
@@ -2027,6 +2107,8 @@ class LiveAuthoringService {
|
|
|
2027
2107
|
durability: this.durabilityReceipt(null, false),
|
|
2028
2108
|
changes: [],
|
|
2029
2109
|
validation,
|
|
2110
|
+
...(error && error.code ? { code: error.code } : {}),
|
|
2111
|
+
...(error && error.details !== undefined ? { details: error.details } : {}),
|
|
2030
2112
|
git: {
|
|
2031
2113
|
enabled: this.gitCommit,
|
|
2032
2114
|
repository: false,
|