@mfdaves/okf-mcp 0.8.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 +70 -12
- 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 +9 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
- package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +8 -0
- 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/okf-mcp/specs/producer-api.md +26 -0
- 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 +10 -2
- package/src/cli.js +46 -4
- package/src/index.js +2 -0
- package/src/indexer.js +8 -1
- package/src/mcp-server.js +95 -0
- package/src/producer-publisher.js +462 -0
- package/src/producers.js +507 -0
- package/src/project.js +65 -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/concept-format.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-authoring.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/indexer.js
CHANGED
|
@@ -472,6 +472,9 @@ function buildIndex(bundleArgs, options) {
|
|
|
472
472
|
const documentOverrides = config.documentOverrides instanceof Map
|
|
473
473
|
? config.documentOverrides
|
|
474
474
|
: new Map();
|
|
475
|
+
const documentDeletions = config.documentDeletions instanceof Set
|
|
476
|
+
? config.documentDeletions
|
|
477
|
+
: new Set();
|
|
475
478
|
const strictLinks = Boolean(config.strictLinks);
|
|
476
479
|
const requestedBundles = uniqueBundleIds((bundleArgs || []).map(parseBundleArg));
|
|
477
480
|
const allowedRelationTypes = new Set((config.relationTypes || DEFAULT_RELATION_TYPES).map(String));
|
|
@@ -560,6 +563,9 @@ function buildIndex(bundleArgs, options) {
|
|
|
560
563
|
return;
|
|
561
564
|
}
|
|
562
565
|
const key = documentOverrideKey(bundle.id, relativePath);
|
|
566
|
+
if (documentDeletions.has(key)) {
|
|
567
|
+
return;
|
|
568
|
+
}
|
|
563
569
|
indexLocalDocument(
|
|
564
570
|
relativePath,
|
|
565
571
|
documentOverrides.has(key) ? String(documentOverrides.get(key)) : undefined,
|
|
@@ -572,7 +578,7 @@ function buildIndex(bundleArgs, options) {
|
|
|
572
578
|
return;
|
|
573
579
|
}
|
|
574
580
|
const relativePath = normalizeSlashes(String(key).slice(prefix.length));
|
|
575
|
-
if (indexedPaths.has(relativePath) || !bundleAllowsPath(bundle, relativePath)) {
|
|
581
|
+
if (documentDeletions.has(key) || indexedPaths.has(relativePath) || !bundleAllowsPath(bundle, relativePath)) {
|
|
576
582
|
return;
|
|
577
583
|
}
|
|
578
584
|
indexLocalDocument(
|
|
@@ -971,6 +977,7 @@ function attachProject(index, project) {
|
|
|
971
977
|
path: project.path,
|
|
972
978
|
root: project.root,
|
|
973
979
|
plugins: project.plugins,
|
|
980
|
+
producers: project.producers,
|
|
974
981
|
remoteBundles: project.remoteBundles,
|
|
975
982
|
strictLinks: project.strictLinks,
|
|
976
983
|
};
|
package/src/mcp-server.js
CHANGED
|
@@ -31,6 +31,7 @@ const {
|
|
|
31
31
|
} = require("./live-authoring");
|
|
32
32
|
const { FileConceptStore } = require("./store");
|
|
33
33
|
const { loadProjectConfig } = require("./project");
|
|
34
|
+
const { ProducerService, producerReceipt } = require("./producers");
|
|
34
35
|
const {
|
|
35
36
|
checkComputationReceipt,
|
|
36
37
|
getProvenance,
|
|
@@ -81,6 +82,18 @@ const REMOTE_LOAD = {
|
|
|
81
82
|
idempotentHint: false,
|
|
82
83
|
openWorldHint: true,
|
|
83
84
|
};
|
|
85
|
+
const PRODUCER_PREVIEW = {
|
|
86
|
+
readOnlyHint: true,
|
|
87
|
+
destructiveHint: false,
|
|
88
|
+
idempotentHint: true,
|
|
89
|
+
openWorldHint: true,
|
|
90
|
+
};
|
|
91
|
+
const PRODUCER_RUN = {
|
|
92
|
+
readOnlyHint: false,
|
|
93
|
+
destructiveHint: true,
|
|
94
|
+
idempotentHint: false,
|
|
95
|
+
openWorldHint: true,
|
|
96
|
+
};
|
|
84
97
|
|
|
85
98
|
function stringParameter(description, extra) {
|
|
86
99
|
return Object.assign({ type: "string", description }, extra || {});
|
|
@@ -631,6 +644,28 @@ const TOOL_DEFINITIONS = {
|
|
|
631
644
|
undefined,
|
|
632
645
|
LIVE_APPLY_OUTPUT,
|
|
633
646
|
),
|
|
647
|
+
okf_list_producers: defineTool(
|
|
648
|
+
"List configured producer instances without loading or executing their packages.",
|
|
649
|
+
READ_ONLY,
|
|
650
|
+
),
|
|
651
|
+
okf_preview_producer: defineTool(
|
|
652
|
+
"Read source metadata, generate a candidate OKF 0.2 bundle, and validate its publication diff without writing files.",
|
|
653
|
+
PRODUCER_PREVIEW,
|
|
654
|
+
{
|
|
655
|
+
producer: nonEmptyStringParameter("Configured producer instance name."),
|
|
656
|
+
detail: detailParameter("Receipt detail level; full includes bounded bundle-relative changed paths."),
|
|
657
|
+
},
|
|
658
|
+
["producer"],
|
|
659
|
+
),
|
|
660
|
+
okf_run_producer: defineTool(
|
|
661
|
+
"Regenerate, strictly validate, safely publish, and reindex one configured OKF producer.",
|
|
662
|
+
PRODUCER_RUN,
|
|
663
|
+
{
|
|
664
|
+
producer: nonEmptyStringParameter("Configured producer instance name."),
|
|
665
|
+
detail: detailParameter("Receipt detail level; full includes bounded bundle-relative changed paths."),
|
|
666
|
+
},
|
|
667
|
+
["producer"],
|
|
668
|
+
),
|
|
634
669
|
get_graph: defineTool(
|
|
635
670
|
"Return a bounded set of OKF graph nodes and edges with optional concept filters.",
|
|
636
671
|
READ_ONLY,
|
|
@@ -739,6 +774,13 @@ const LIVE_WRITE_TOOL_NAMES = new Set([
|
|
|
739
774
|
const RUNTIME_REMOTE_TOOL_NAMES = new Set([
|
|
740
775
|
"load_remote_bundle",
|
|
741
776
|
]);
|
|
777
|
+
const PRODUCER_TOOL_NAMES = new Set([
|
|
778
|
+
"okf_list_producers",
|
|
779
|
+
"okf_preview_producer",
|
|
780
|
+
]);
|
|
781
|
+
const PRODUCER_WRITE_TOOL_NAMES = new Set([
|
|
782
|
+
"okf_run_producer",
|
|
783
|
+
]);
|
|
742
784
|
|
|
743
785
|
function jsonContent(value, options) {
|
|
744
786
|
const result = {
|
|
@@ -797,7 +839,14 @@ function projectLiveReceipt(receipt, detail) {
|
|
|
797
839
|
return compact;
|
|
798
840
|
}
|
|
799
841
|
|
|
842
|
+
|
|
800
843
|
function toolEnabled(state, name) {
|
|
844
|
+
if (PRODUCER_TOOL_NAMES.has(name)) {
|
|
845
|
+
return Boolean(state && state.producerService);
|
|
846
|
+
}
|
|
847
|
+
if (PRODUCER_WRITE_TOOL_NAMES.has(name)) {
|
|
848
|
+
return Boolean(state && state.producerService && state.allowWrite && state.actor);
|
|
849
|
+
}
|
|
801
850
|
if (PROJECT_HELPER_TOOL_NAMES.has(name)) {
|
|
802
851
|
return Boolean(state && state.authoringService);
|
|
803
852
|
}
|
|
@@ -1252,6 +1301,30 @@ async function callTool(state, name, args) {
|
|
|
1252
1301
|
isError: result.applied === false,
|
|
1253
1302
|
});
|
|
1254
1303
|
}
|
|
1304
|
+
case "okf_list_producers":
|
|
1305
|
+
return jsonContent(state.producerService.list(), { structured: true });
|
|
1306
|
+
case "okf_preview_producer": {
|
|
1307
|
+
const result = await expectedToolOperation(
|
|
1308
|
+
() => state.producerService.preview(args.producer, {
|
|
1309
|
+
additionalBundles: state.remoteBundles,
|
|
1310
|
+
}),
|
|
1311
|
+
{ translateTypeError: true },
|
|
1312
|
+
);
|
|
1313
|
+
return jsonContent(producerReceipt(result, args.detail || "compact"), { structured: true });
|
|
1314
|
+
}
|
|
1315
|
+
case "okf_run_producer": {
|
|
1316
|
+
const result = await expectedToolOperation(
|
|
1317
|
+
() => state.producerService.run(args.producer, {
|
|
1318
|
+
additionalBundles: state.remoteBundles,
|
|
1319
|
+
}),
|
|
1320
|
+
{ translateTypeError: true },
|
|
1321
|
+
);
|
|
1322
|
+
if (result.applied) rebuildStateIndex(state);
|
|
1323
|
+
return jsonContent(producerReceipt(result, args.detail || "compact"), {
|
|
1324
|
+
structured: true,
|
|
1325
|
+
isError: result.applied === false,
|
|
1326
|
+
});
|
|
1327
|
+
}
|
|
1255
1328
|
case "get_graph":
|
|
1256
1329
|
return jsonContent(getGraph(index, args));
|
|
1257
1330
|
case "get_neighbors":
|
|
@@ -1338,7 +1411,9 @@ function createState(bundleArgs, options) {
|
|
|
1338
1411
|
project,
|
|
1339
1412
|
authoringService,
|
|
1340
1413
|
liveAuthoringService: options && options.liveAuthoringService,
|
|
1414
|
+
producerService: options && options.producerService,
|
|
1341
1415
|
allowWrite: Boolean(options && options.allowWrite),
|
|
1416
|
+
actor: options && options.actor,
|
|
1342
1417
|
allowAuthoring: Boolean(options && options.allowAuthoring),
|
|
1343
1418
|
allowRuntimeRemoteLoad: Boolean(options && options.allowRuntimeRemoteLoad),
|
|
1344
1419
|
allowComputationAuthoring: Boolean(options && options.allowComputationAuthoring),
|
|
@@ -1346,6 +1421,17 @@ function createState(bundleArgs, options) {
|
|
|
1346
1421
|
allowCustomRelationTypes,
|
|
1347
1422
|
repositoryMappings: (options && options.repositoryMappings) || new Map(),
|
|
1348
1423
|
};
|
|
1424
|
+
if (!state.producerService && project && (project.producers || []).length
|
|
1425
|
+
&& authoringService && authoringService.store) {
|
|
1426
|
+
state.producerService = new ProducerService({
|
|
1427
|
+
project,
|
|
1428
|
+
store: authoringService.store,
|
|
1429
|
+
bundles: localBundleArgs,
|
|
1430
|
+
loader: options && options.producerLoader,
|
|
1431
|
+
env: options && options.producerEnv,
|
|
1432
|
+
now: options && options.producerNow,
|
|
1433
|
+
});
|
|
1434
|
+
}
|
|
1349
1435
|
return state;
|
|
1350
1436
|
}
|
|
1351
1437
|
|
|
@@ -1373,7 +1459,12 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1373
1459
|
relationTypes: loaded.project.relationTypes,
|
|
1374
1460
|
authoringService,
|
|
1375
1461
|
liveAuthoringService,
|
|
1462
|
+
producerService: options.producerService,
|
|
1463
|
+
producerLoader: options.producerLoader,
|
|
1464
|
+
producerEnv: options.producerEnv,
|
|
1465
|
+
producerNow: options.producerNow,
|
|
1376
1466
|
allowWrite: options.allowWrite,
|
|
1467
|
+
actor: options.actor,
|
|
1377
1468
|
allowAuthoring: options.allowAuthoring,
|
|
1378
1469
|
allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
|
|
1379
1470
|
allowComputationAuthoring: options.allowComputationAuthoring,
|
|
@@ -1403,7 +1494,9 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1403
1494
|
relationTypes: store.getRelationTypes(),
|
|
1404
1495
|
authoringService,
|
|
1405
1496
|
liveAuthoringService,
|
|
1497
|
+
producerService: options.producerService,
|
|
1406
1498
|
allowWrite: options.allowWrite,
|
|
1499
|
+
actor: options.actor,
|
|
1407
1500
|
allowAuthoring: options.allowAuthoring,
|
|
1408
1501
|
allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
|
|
1409
1502
|
allowComputationAuthoring: options.allowComputationAuthoring,
|
|
@@ -1433,7 +1526,9 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1433
1526
|
initialRemoteBundles: remoteBundles,
|
|
1434
1527
|
authoringService: options && options.authoringService,
|
|
1435
1528
|
liveAuthoringService,
|
|
1529
|
+
producerService: options && options.producerService,
|
|
1436
1530
|
allowWrite: options && options.allowWrite,
|
|
1531
|
+
actor: options && options.actor,
|
|
1437
1532
|
allowAuthoring: options && options.allowAuthoring,
|
|
1438
1533
|
allowRuntimeRemoteLoad: options && options.allowRuntimeRemoteLoad,
|
|
1439
1534
|
allowComputationAuthoring: options && options.allowComputationAuthoring,
|
|
@@ -0,0 +1,462 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const crypto = require("node:crypto");
|
|
4
|
+
const fs = require("node:fs");
|
|
5
|
+
const path = require("node:path");
|
|
6
|
+
|
|
7
|
+
const { splitFrontmatter } = require("./parser");
|
|
8
|
+
|
|
9
|
+
const MANIFEST_NAME = ".okf-producer.json";
|
|
10
|
+
|
|
11
|
+
class ProducerPublicationError extends Error {
|
|
12
|
+
constructor(message, code, details) {
|
|
13
|
+
super(message);
|
|
14
|
+
this.name = "ProducerPublicationError";
|
|
15
|
+
this.code = code;
|
|
16
|
+
if (details !== undefined) this.details = details;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function sha256(content) {
|
|
21
|
+
return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
function canonical(value) {
|
|
25
|
+
if (value instanceof Date) return JSON.stringify(value.toISOString());
|
|
26
|
+
if (value === null || typeof value !== "object") {
|
|
27
|
+
const encoded = JSON.stringify(value);
|
|
28
|
+
return encoded === undefined ? "null" : encoded;
|
|
29
|
+
}
|
|
30
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
|
|
31
|
+
return `{${Object.keys(value).sort()
|
|
32
|
+
.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
|
|
33
|
+
.join(",")}}`;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function generatedMapping(content) {
|
|
37
|
+
let split;
|
|
38
|
+
try {
|
|
39
|
+
split = splitFrontmatter(content);
|
|
40
|
+
} catch {
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
const generated = split.frontmatter && split.frontmatter.generated;
|
|
44
|
+
if (!generated || typeof generated !== "object" || Array.isArray(generated)) {
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
return { split, generated };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// A producer restamps generated.at on every run. Digesting the concept without
|
|
51
|
+
// that stamp lets an unchanged source stay unchanged on disk instead of
|
|
52
|
+
// rewriting every managed file, which keeps the publication diff truthful.
|
|
53
|
+
function stableDigest(content) {
|
|
54
|
+
const parsed = generatedMapping(content);
|
|
55
|
+
if (!parsed || parsed.generated.at === undefined) return sha256(content);
|
|
56
|
+
const stable = Object.assign({}, parsed.split.frontmatter, {
|
|
57
|
+
generated: Object.fromEntries(
|
|
58
|
+
Object.entries(parsed.generated).filter(([key]) => key !== "at"),
|
|
59
|
+
),
|
|
60
|
+
});
|
|
61
|
+
return sha256(`${canonical(stable)}\u0000${parsed.split.body}`);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
// Only concepts that carry their own generation provenance may be rewritten or
|
|
65
|
+
// removed on a manifest claim. A hand-authored file that a damaged or forged
|
|
66
|
+
// manifest lists stays on disk.
|
|
67
|
+
function hasGeneratedProvenance(content) {
|
|
68
|
+
const parsed = generatedMapping(content);
|
|
69
|
+
return Boolean(parsed && (parsed.generated.by !== undefined || parsed.generated.at !== undefined));
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function isInside(root, target) {
|
|
73
|
+
const relative = path.relative(root, target);
|
|
74
|
+
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function normalizeProducedPath(value) {
|
|
78
|
+
const raw = String(value || "").trim().replace(/\\/g, "/");
|
|
79
|
+
if (!raw || raw.startsWith("/") || /^[A-Za-z]:\//.test(raw) || /[\u0000-\u001f\u007f]/.test(raw)) {
|
|
80
|
+
throw new ProducerPublicationError("Producer paths must be safe bundle-relative Markdown paths.", "invalid_producer_path");
|
|
81
|
+
}
|
|
82
|
+
const parts = raw.split("/");
|
|
83
|
+
if (parts.some((part) => !part || part === "." || part === ".." || part.startsWith("."))) {
|
|
84
|
+
throw new ProducerPublicationError("Producer paths cannot contain empty, hidden, dot, or parent segments.", "invalid_producer_path");
|
|
85
|
+
}
|
|
86
|
+
const normalized = path.posix.normalize(raw);
|
|
87
|
+
if (!normalized.toLowerCase().endsWith(".md")) {
|
|
88
|
+
throw new ProducerPublicationError("Producer output files must be Markdown documents.", "invalid_producer_path");
|
|
89
|
+
}
|
|
90
|
+
return normalized;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function normalizeProducedFiles(files) {
|
|
94
|
+
if (!Array.isArray(files) || files.length === 0) {
|
|
95
|
+
throw new ProducerPublicationError("Producer generate() must return a non-empty files array.", "invalid_producer_output");
|
|
96
|
+
}
|
|
97
|
+
const seen = new Set();
|
|
98
|
+
return files.map((file) => {
|
|
99
|
+
if (!file || typeof file !== "object" || Array.isArray(file)) {
|
|
100
|
+
throw new ProducerPublicationError("Each producer file must be an object.", "invalid_producer_output");
|
|
101
|
+
}
|
|
102
|
+
const relativePath = normalizeProducedPath(file.path);
|
|
103
|
+
if (seen.has(relativePath)) {
|
|
104
|
+
throw new ProducerPublicationError("Producer output paths must be unique.", "duplicate_producer_path", { path: relativePath });
|
|
105
|
+
}
|
|
106
|
+
seen.add(relativePath);
|
|
107
|
+
if (typeof file.content !== "string") {
|
|
108
|
+
throw new ProducerPublicationError("Producer file content must be a string.", "invalid_producer_content", { path: relativePath });
|
|
109
|
+
}
|
|
110
|
+
return { path: relativePath, content: file.content, sha256: sha256(file.content) };
|
|
111
|
+
}).sort((left, right) => left.path.localeCompare(right.path));
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function assertRegularPath(root, relativePath) {
|
|
115
|
+
let current = root;
|
|
116
|
+
const parts = relativePath.split("/");
|
|
117
|
+
parts.forEach((part, index) => {
|
|
118
|
+
current = path.join(current, part);
|
|
119
|
+
let stat;
|
|
120
|
+
try {
|
|
121
|
+
stat = fs.lstatSync(current);
|
|
122
|
+
} catch (error) {
|
|
123
|
+
if (error && error.code === "ENOENT") return;
|
|
124
|
+
throw error;
|
|
125
|
+
}
|
|
126
|
+
if (stat.isSymbolicLink()) {
|
|
127
|
+
throw new ProducerPublicationError("Producer-managed paths cannot traverse symbolic links.", "producer_path_symlink", { path: parts.slice(0, index + 1).join("/") });
|
|
128
|
+
}
|
|
129
|
+
if (index < parts.length - 1 && !stat.isDirectory()) {
|
|
130
|
+
throw new ProducerPublicationError("A producer-managed path parent is not a directory.", "producer_path_parent_not_directory", { path: parts.slice(0, index + 1).join("/") });
|
|
131
|
+
}
|
|
132
|
+
if (index === parts.length - 1 && !stat.isFile()) {
|
|
133
|
+
throw new ProducerPublicationError("Producer-managed files must be regular files.", "producer_path_not_file", { path: relativePath });
|
|
134
|
+
}
|
|
135
|
+
});
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function readManifest(root, producer) {
|
|
139
|
+
const manifestPath = path.join(root, MANIFEST_NAME);
|
|
140
|
+
if (!fs.existsSync(manifestPath)) return null;
|
|
141
|
+
assertRegularPath(root, MANIFEST_NAME);
|
|
142
|
+
let manifest;
|
|
143
|
+
let content;
|
|
144
|
+
try {
|
|
145
|
+
content = fs.readFileSync(manifestPath);
|
|
146
|
+
manifest = JSON.parse(content.toString("utf8"));
|
|
147
|
+
} catch {
|
|
148
|
+
throw new ProducerPublicationError("The producer ownership manifest is invalid.", "invalid_producer_manifest");
|
|
149
|
+
}
|
|
150
|
+
if (!manifest || manifest.version !== 1 || manifest.producer !== producer.type
|
|
151
|
+
|| manifest.bundle !== producer.bundle || !Array.isArray(manifest.files)) {
|
|
152
|
+
throw new ProducerPublicationError("The producer ownership manifest does not match this configured producer.", "invalid_producer_manifest");
|
|
153
|
+
}
|
|
154
|
+
const owned = new Map();
|
|
155
|
+
manifest.files.forEach((entry) => {
|
|
156
|
+
const relativePath = normalizeProducedPath(entry && entry.path);
|
|
157
|
+
if (owned.has(relativePath) || !entry || !/^sha256:[a-f0-9]{64}$/.test(String(entry.sha256 || ""))) {
|
|
158
|
+
throw new ProducerPublicationError("The producer ownership manifest contains an invalid file entry.", "invalid_producer_manifest");
|
|
159
|
+
}
|
|
160
|
+
owned.set(relativePath, String(entry.sha256));
|
|
161
|
+
});
|
|
162
|
+
return { manifest, owned, sha256: sha256(content) };
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function verifyOwnedFiles(root, owned) {
|
|
166
|
+
const contents = new Map();
|
|
167
|
+
owned.forEach((expected, relativePath) => {
|
|
168
|
+
assertRegularPath(root, relativePath);
|
|
169
|
+
const absolutePath = path.join(root, ...relativePath.split("/"));
|
|
170
|
+
if (!fs.existsSync(absolutePath)) {
|
|
171
|
+
throw new ProducerPublicationError("A producer-owned file changed outside the producer.", "producer_owned_file_modified", { path: relativePath });
|
|
172
|
+
}
|
|
173
|
+
const content = fs.readFileSync(absolutePath);
|
|
174
|
+
if (sha256(content) !== expected) {
|
|
175
|
+
throw new ProducerPublicationError("A producer-owned file changed outside the producer.", "producer_owned_file_modified", { path: relativePath });
|
|
176
|
+
}
|
|
177
|
+
contents.set(relativePath, content);
|
|
178
|
+
});
|
|
179
|
+
return contents;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
function inspectPublication(root, producer, files) {
|
|
183
|
+
const manifestState = readManifest(root, producer);
|
|
184
|
+
const owned = manifestState ? manifestState.owned : new Map();
|
|
185
|
+
const ownedContents = verifyOwnedFiles(root, owned);
|
|
186
|
+
const generated = new Map(files.map((file) => [file.path, file]));
|
|
187
|
+
const changes = { create: [], update: [], delete: [], unchanged: [] };
|
|
188
|
+
// What each managed path will hold once publication finishes. A retained
|
|
189
|
+
// entry keeps the bytes already on disk, so the manifest stays truthful.
|
|
190
|
+
const effective = new Map();
|
|
191
|
+
files.forEach((file) => {
|
|
192
|
+
assertRegularPath(root, file.path);
|
|
193
|
+
const absolutePath = path.join(root, ...file.path.split("/"));
|
|
194
|
+
if (fs.existsSync(absolutePath) && !owned.has(file.path)) {
|
|
195
|
+
throw new ProducerPublicationError("Producer output collides with an unowned file.", "producer_unowned_collision", { path: file.path });
|
|
196
|
+
}
|
|
197
|
+
if (!owned.has(file.path)) {
|
|
198
|
+
changes.create.push(file.path);
|
|
199
|
+
effective.set(file.path, { path: file.path, sha256: file.sha256, content: file.content });
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
202
|
+
const current = ownedContents.get(file.path);
|
|
203
|
+
if (owned.get(file.path) === file.sha256) {
|
|
204
|
+
changes.unchanged.push(file.path);
|
|
205
|
+
effective.set(file.path, { path: file.path, sha256: owned.get(file.path), content: file.content });
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
if (current && stableDigest(current.toString("utf8")) === stableDigest(file.content)) {
|
|
209
|
+
changes.unchanged.push(file.path);
|
|
210
|
+
effective.set(file.path, {
|
|
211
|
+
path: file.path,
|
|
212
|
+
sha256: owned.get(file.path),
|
|
213
|
+
content: current.toString("utf8"),
|
|
214
|
+
});
|
|
215
|
+
return;
|
|
216
|
+
}
|
|
217
|
+
changes.update.push(file.path);
|
|
218
|
+
effective.set(file.path, { path: file.path, sha256: file.sha256, content: file.content });
|
|
219
|
+
});
|
|
220
|
+
owned.forEach((_digest, relativePath) => {
|
|
221
|
+
if (!generated.has(relativePath)) changes.delete.push(relativePath);
|
|
222
|
+
});
|
|
223
|
+
changes.update.concat(changes.delete).forEach((relativePath) => {
|
|
224
|
+
const current = ownedContents.get(relativePath);
|
|
225
|
+
if (!current || !hasGeneratedProvenance(current.toString("utf8"))) {
|
|
226
|
+
throw new ProducerPublicationError(
|
|
227
|
+
"The ownership manifest claims a file that carries no generation provenance.",
|
|
228
|
+
"producer_manifest_claims_unmanaged_file",
|
|
229
|
+
{ path: relativePath },
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
});
|
|
233
|
+
Object.values(changes).forEach((entries) => entries.sort());
|
|
234
|
+
return {
|
|
235
|
+
changes,
|
|
236
|
+
owned,
|
|
237
|
+
effective: files.map((file) => effective.get(file.path)),
|
|
238
|
+
previousManifest: manifestState && manifestState.manifest,
|
|
239
|
+
previousManifestSha256: manifestState && manifestState.sha256,
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function manifestFor(producer, files) {
|
|
244
|
+
return {
|
|
245
|
+
version: 1,
|
|
246
|
+
producer: producer.type,
|
|
247
|
+
producerVersion: producer.version,
|
|
248
|
+
bundle: producer.bundle,
|
|
249
|
+
files: files.map((file) => ({ path: file.path, sha256: file.sha256 })),
|
|
250
|
+
};
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
function snapshotFile(absolutePath) {
|
|
254
|
+
if (!fs.existsSync(absolutePath)) return { exists: false };
|
|
255
|
+
const stat = fs.lstatSync(absolutePath);
|
|
256
|
+
if (stat.isSymbolicLink() || !stat.isFile()) {
|
|
257
|
+
throw new ProducerPublicationError("Producer-managed files must be regular files.", "producer_path_not_file");
|
|
258
|
+
}
|
|
259
|
+
return { exists: true, content: fs.readFileSync(absolutePath), mode: stat.mode & 0o777 };
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
function snapshotMatches(absolutePath, expected) {
|
|
263
|
+
try {
|
|
264
|
+
const current = snapshotFile(absolutePath);
|
|
265
|
+
if (current.exists !== expected.exists) return false;
|
|
266
|
+
return !current.exists || current.content.equals(expected.content);
|
|
267
|
+
} catch {
|
|
268
|
+
return false;
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
function assertSnapshotMatches(absolutePath, expected, relativePath) {
|
|
273
|
+
if (!snapshotMatches(absolutePath, expected)) {
|
|
274
|
+
throw new ProducerPublicationError(
|
|
275
|
+
"A producer target changed during publication.",
|
|
276
|
+
"producer_publication_conflict",
|
|
277
|
+
{ path: relativePath },
|
|
278
|
+
);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
function ensureParent(root, absolutePath, createdDirectories) {
|
|
283
|
+
const relative = path.relative(root, path.dirname(absolutePath));
|
|
284
|
+
let current = root;
|
|
285
|
+
relative.split(path.sep).filter(Boolean).forEach((part) => {
|
|
286
|
+
current = path.join(current, part);
|
|
287
|
+
if (!fs.existsSync(current)) {
|
|
288
|
+
fs.mkdirSync(current);
|
|
289
|
+
createdDirectories.push(current);
|
|
290
|
+
} else if (fs.lstatSync(current).isSymbolicLink() || !fs.statSync(current).isDirectory()) {
|
|
291
|
+
throw new ProducerPublicationError("Producer output parents must be ordinary directories.", "producer_path_parent_not_directory");
|
|
292
|
+
}
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
function atomicWrite(root, absolutePath, content, createdDirectories) {
|
|
297
|
+
ensureParent(root, absolutePath, createdDirectories);
|
|
298
|
+
const temporaryPath = path.join(path.dirname(absolutePath), `.${path.basename(absolutePath)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
|
|
299
|
+
try {
|
|
300
|
+
fs.writeFileSync(temporaryPath, content, { flag: "wx" });
|
|
301
|
+
fs.renameSync(temporaryPath, absolutePath);
|
|
302
|
+
} finally {
|
|
303
|
+
if (fs.existsSync(temporaryPath)) fs.unlinkSync(temporaryPath);
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
function restoreFiles(root, snapshots, published, createdDirectories) {
|
|
308
|
+
const conflicts = [];
|
|
309
|
+
Array.from(published.entries()).reverse().forEach(([absolutePath, expected]) => {
|
|
310
|
+
const snapshot = snapshots.get(absolutePath);
|
|
311
|
+
if (!snapshotMatches(absolutePath, expected)) {
|
|
312
|
+
conflicts.push(path.relative(root, absolutePath).replace(/\\/g, "/"));
|
|
313
|
+
return;
|
|
314
|
+
}
|
|
315
|
+
if (snapshot.exists) {
|
|
316
|
+
atomicWrite(root, absolutePath, snapshot.content, []);
|
|
317
|
+
fs.chmodSync(absolutePath, snapshot.mode);
|
|
318
|
+
} else if (fs.existsSync(absolutePath) && fs.lstatSync(absolutePath).isFile()) {
|
|
319
|
+
fs.unlinkSync(absolutePath);
|
|
320
|
+
}
|
|
321
|
+
});
|
|
322
|
+
createdDirectories.reverse().forEach((directory) => {
|
|
323
|
+
try {
|
|
324
|
+
fs.rmdirSync(directory);
|
|
325
|
+
} catch {
|
|
326
|
+
// Preserve a directory if another file appeared while publication was in progress.
|
|
327
|
+
}
|
|
328
|
+
});
|
|
329
|
+
if (conflicts.length) {
|
|
330
|
+
throw new ProducerPublicationError(
|
|
331
|
+
"Producer publication failed and concurrent replacements were preserved.",
|
|
332
|
+
"producer_rollback_conflict",
|
|
333
|
+
{ paths: conflicts.sort().slice(0, 100) },
|
|
334
|
+
);
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
function pruneEmptyDirectories(root, relativePaths) {
|
|
339
|
+
const visited = new Set();
|
|
340
|
+
relativePaths.forEach((relativePath) => {
|
|
341
|
+
let current = path.dirname(path.join(root, ...relativePath.split("/")));
|
|
342
|
+
while (isInside(root, current)
|
|
343
|
+
&& path.resolve(current) !== path.resolve(root)
|
|
344
|
+
&& !visited.has(current)) {
|
|
345
|
+
visited.add(current);
|
|
346
|
+
try {
|
|
347
|
+
if (fs.readdirSync(current).length > 0) break;
|
|
348
|
+
fs.rmdirSync(current);
|
|
349
|
+
} catch {
|
|
350
|
+
break;
|
|
351
|
+
}
|
|
352
|
+
current = path.dirname(current);
|
|
353
|
+
}
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
class ProducerPublisher {
|
|
358
|
+
constructor(project, store) {
|
|
359
|
+
this.project = project;
|
|
360
|
+
this.store = store;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
bundleRoot(bundleId) {
|
|
364
|
+
const bundle = this.project.bundles.find((entry) => entry.id === bundleId && !entry.remote);
|
|
365
|
+
if (!bundle) throw new ProducerPublicationError("Configured producer bundle is unavailable.", "unknown_producer_bundle");
|
|
366
|
+
return this.store.resolveWritableBundleRoot(bundle);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
inspect(producer, files) {
|
|
370
|
+
const root = this.bundleRoot(producer.bundle);
|
|
371
|
+
return Object.assign({ root }, inspectPublication(root, producer, files));
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
async publish(producer, files, validatePersisted) {
|
|
375
|
+
const inspection = this.inspect(producer, files);
|
|
376
|
+
const root = inspection.root;
|
|
377
|
+
const manifestPath = path.join(root, MANIFEST_NAME);
|
|
378
|
+
const manifestContent = `${JSON.stringify(manifestFor(producer, inspection.effective), null, 2)}\n`;
|
|
379
|
+
const changedPaths = inspection.changes.create
|
|
380
|
+
.concat(inspection.changes.update, inspection.changes.delete);
|
|
381
|
+
if (changedPaths.length === 0 && inspection.previousManifestSha256 === sha256(manifestContent)) {
|
|
382
|
+
if (validatePersisted) await validatePersisted();
|
|
383
|
+
return inspection.changes;
|
|
384
|
+
}
|
|
385
|
+
const touched = new Set(changedPaths.concat(MANIFEST_NAME));
|
|
386
|
+
const snapshots = new Map();
|
|
387
|
+
touched.forEach((relativePath) => snapshots.set(
|
|
388
|
+
path.join(root, ...relativePath.split("/")),
|
|
389
|
+
snapshotFile(path.join(root, ...relativePath.split("/"))),
|
|
390
|
+
));
|
|
391
|
+
inspection.changes.create.forEach((relativePath) => {
|
|
392
|
+
assertSnapshotMatches(
|
|
393
|
+
path.join(root, ...relativePath.split("/")),
|
|
394
|
+
{ exists: false },
|
|
395
|
+
relativePath,
|
|
396
|
+
);
|
|
397
|
+
});
|
|
398
|
+
inspection.changes.update.concat(inspection.changes.delete).forEach((relativePath) => {
|
|
399
|
+
const expectedDigest = inspection.owned.get(relativePath);
|
|
400
|
+
const snapshot = snapshots.get(path.join(root, ...relativePath.split("/")));
|
|
401
|
+
if (!snapshot.exists || sha256(snapshot.content) !== expectedDigest) {
|
|
402
|
+
throw new ProducerPublicationError(
|
|
403
|
+
"A producer-owned file changed during publication.",
|
|
404
|
+
"producer_publication_conflict",
|
|
405
|
+
{ path: relativePath },
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
});
|
|
409
|
+
const manifestSnapshot = snapshots.get(manifestPath);
|
|
410
|
+
if (inspection.previousManifestSha256) {
|
|
411
|
+
if (!manifestSnapshot.exists || sha256(manifestSnapshot.content) !== inspection.previousManifestSha256) {
|
|
412
|
+
throw new ProducerPublicationError("The producer ownership manifest changed during publication.", "producer_publication_conflict");
|
|
413
|
+
}
|
|
414
|
+
} else if (manifestSnapshot.exists) {
|
|
415
|
+
throw new ProducerPublicationError("The producer ownership manifest changed during publication.", "producer_publication_conflict");
|
|
416
|
+
}
|
|
417
|
+
const createdDirectories = [];
|
|
418
|
+
const published = new Map();
|
|
419
|
+
try {
|
|
420
|
+
inspection.changes.delete.forEach((relativePath) => {
|
|
421
|
+
const absolutePath = path.join(root, ...relativePath.split("/"));
|
|
422
|
+
assertSnapshotMatches(absolutePath, snapshots.get(absolutePath), relativePath);
|
|
423
|
+
fs.unlinkSync(absolutePath);
|
|
424
|
+
published.set(absolutePath, { exists: false });
|
|
425
|
+
});
|
|
426
|
+
const filesByPath = new Map(files.map((file) => [file.path, file]));
|
|
427
|
+
inspection.changes.create.concat(inspection.changes.update).forEach((relativePath) => {
|
|
428
|
+
const file = filesByPath.get(relativePath);
|
|
429
|
+
const absolutePath = path.join(root, ...relativePath.split("/"));
|
|
430
|
+
assertSnapshotMatches(absolutePath, snapshots.get(absolutePath), relativePath);
|
|
431
|
+
atomicWrite(root, absolutePath, file.content, createdDirectories);
|
|
432
|
+
published.set(absolutePath, { exists: true, content: Buffer.from(file.content) });
|
|
433
|
+
});
|
|
434
|
+
assertSnapshotMatches(manifestPath, manifestSnapshot, MANIFEST_NAME);
|
|
435
|
+
atomicWrite(root, manifestPath, manifestContent, createdDirectories);
|
|
436
|
+
published.set(manifestPath, { exists: true, content: Buffer.from(manifestContent) });
|
|
437
|
+
if (validatePersisted) await validatePersisted();
|
|
438
|
+
pruneEmptyDirectories(root, inspection.changes.delete);
|
|
439
|
+
return inspection.changes;
|
|
440
|
+
} catch (error) {
|
|
441
|
+
try {
|
|
442
|
+
restoreFiles(root, snapshots, published, createdDirectories);
|
|
443
|
+
} catch (rollbackError) {
|
|
444
|
+
if (rollbackError instanceof ProducerPublicationError) throw rollbackError;
|
|
445
|
+
throw new ProducerPublicationError("Producer publication failed and rollback could not be completed.", "producer_rollback_failed");
|
|
446
|
+
}
|
|
447
|
+
throw error;
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
module.exports = {
|
|
453
|
+
MANIFEST_NAME,
|
|
454
|
+
hasGeneratedProvenance,
|
|
455
|
+
stableDigest,
|
|
456
|
+
ProducerPublicationError,
|
|
457
|
+
ProducerPublisher,
|
|
458
|
+
manifestFor,
|
|
459
|
+
normalizeProducedFiles,
|
|
460
|
+
normalizeProducedPath,
|
|
461
|
+
sha256,
|
|
462
|
+
};
|