@mfdaves/okf-mcp 0.8.0 → 0.9.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 (31) hide show
  1. package/README.md +74 -14
  2. package/okf/{bundles/okf-mcp → okf-mcp}/distribution/reference-bundle.md +1 -1
  3. package/okf/{bundles/okf-mcp → okf-mcp}/index.md +3 -0
  4. package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/mcp-tools.md +9 -1
  5. package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
  6. package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +8 -0
  7. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/file-concept-store.md +1 -1
  8. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/mcp-server.md +6 -2
  9. package/okf/okf-mcp/runtime/producer-host.md +28 -0
  10. package/okf/okf-mcp/specs/producer-api.md +26 -0
  11. package/okf/okf-mcp/workflows/producer-publication.md +28 -0
  12. package/okf.project.yaml +1 -1
  13. package/package.json +2 -2
  14. package/server.json +11 -3
  15. package/src/authoring.js +10 -2
  16. package/src/cli.js +46 -4
  17. package/src/index.js +2 -0
  18. package/src/indexer.js +8 -1
  19. package/src/mcp-server.js +95 -0
  20. package/src/producer-publisher.js +462 -0
  21. package/src/producers.js +507 -0
  22. package/src/project.js +65 -0
  23. package/src/store.js +1 -0
  24. /package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/http-authoring-api.md +0 -0
  25. /package/okf/{bundles/okf-mcp → okf-mcp}/runtime/indexer.md +0 -0
  26. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/attested-computation.md +0 -0
  27. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/concept-format.md +0 -0
  28. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/git-sources.md +0 -0
  29. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-authoring.md +0 -0
  30. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-update.md +0 -0
  31. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/v02-migration.md +0 -0
package/src/index.js CHANGED
@@ -9,6 +9,8 @@ module.exports = {
9
9
  ...require("./graph"),
10
10
  ...require("./project"),
11
11
  ...require("./plugins"),
12
+ ...require("./producers"),
13
+ ...require("./producer-publisher"),
12
14
  ...require("./remote"),
13
15
  ...require("./computation"),
14
16
  ...require("./git-source"),
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
+ };