@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.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 (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
package/src/producers.js CHANGED
@@ -4,6 +4,8 @@ const fs = require("node:fs");
4
4
  const path = require("node:path");
5
5
  const { createRequire } = require("node:module");
6
6
 
7
+ const { evaluateProducerFiles, policyDiagnostics } = require("./authoring/policy-hook");
8
+ const { boundedErrorDetails, publicErrorCode } = require("./error-details");
7
9
  const { attachProject, buildIndex } = require("./indexer");
8
10
  const { splitFrontmatter } = require("./parser");
9
11
  const {
@@ -46,21 +48,54 @@ class ProducerHostError extends Error {
46
48
  }
47
49
  }
48
50
 
51
+ // A bundle-relative path an error names in its details, kept when it is a
52
+ // plain relative path (no absolute path, traversal or control character).
53
+ function detailPath(details) {
54
+ const value = details && typeof details.path === "string" ? details.path : "";
55
+ const safe =
56
+ value.length > 0 &&
57
+ value.length <= 512 &&
58
+ !/[\p{Cc}]/u.test(value) &&
59
+ !/^([/\\]|[A-Za-z]:)/.test(value) &&
60
+ !value.split(/[/\\]/).includes("..");
61
+ return safe ? value : undefined;
62
+ }
63
+
49
64
  function publicDiagnostic(entry) {
50
65
  const source = entry || {};
51
66
  const rawCode = typeof source.code === "string" ? source.code : "";
52
67
  const rawField = typeof source.field === "string" ? source.field : "";
53
- return Object.fromEntries([
54
- ["code", /^[a-z][a-z0-9_]{0,63}$/.test(rawCode) ? rawCode : "producer_invalid"],
55
- ["severity", source.severity || "error"],
56
- ["layer", source.layer || "producer"],
57
- ["path", source.path],
58
- ["field", /^[A-Za-z0-9_.[\]-]{1,128}$/.test(rawField) ? rawField : undefined],
59
- ].filter(([, value]) => value !== undefined));
68
+ const offending = detailPath(source.details);
69
+ return Object.fromEntries(
70
+ [
71
+ ["code", /^[a-z][a-z0-9_]{0,63}$/.test(rawCode) ? rawCode : "producer_invalid"],
72
+ ["severity", source.severity || "error"],
73
+ ["layer", source.layer || "producer"],
74
+ ["path", source.path],
75
+ ["field", /^[A-Za-z0-9_.[\]-]{1,128}$/.test(rawField) ? rawField : undefined],
76
+ // The file a publication error is about, so an operator can find it.
77
+ ["details", offending ? { path: offending } : undefined],
78
+ ].filter(([, value]) => value !== undefined),
79
+ );
60
80
  }
61
81
 
62
82
  function diagnostic(code, extra) {
63
- return publicDiagnostic(Object.assign({ code, severity: "error", layer: "producer" }, extra || {}));
83
+ return publicDiagnostic(
84
+ Object.assign({ code, severity: "error", layer: "producer" }, extra || {}),
85
+ );
86
+ }
87
+
88
+ // A producer that cannot generate may throw an error carrying its own code
89
+ // (for example access_denied) and a `details` object of scalar values (for
90
+ // example the section it could not read). The receipt reports both as one
91
+ // diagnostic, details bounded by boundedErrorDetails (src/error-details.js)
92
+ // and stripped of any secret the producer read; the error's message is
93
+ // never forwarded (B-6). Null when the error carries no usable code.
94
+ function producerErrorDiagnostic(error, secrets) {
95
+ const code = publicErrorCode(error);
96
+ if (!code) return null;
97
+ const details = boundedErrorDetails(error, secrets);
98
+ return Object.assign(diagnostic(code), details ? { details } : {});
64
99
  }
65
100
 
66
101
  function isInside(root, target) {
@@ -87,8 +122,7 @@ function moduleDirectories(projectRoot) {
87
122
  // node_modules directories. Node resolves symbolic links away, so the install
88
123
  // location is located lexically first and then tied back to the resolved entry.
89
124
  function locateInstalledPackage(projectRoot, projectPath, packageName) {
90
- const roots = moduleDirectories(projectRoot)
91
- .concat(moduleDirectories(path.dirname(projectPath)));
125
+ const roots = moduleDirectories(projectRoot).concat(moduleDirectories(path.dirname(projectPath)));
92
126
  const seen = new Set();
93
127
  for (const directory of roots) {
94
128
  if (seen.has(directory)) continue;
@@ -99,15 +133,26 @@ function locateInstalledPackage(projectRoot, projectPath, packageName) {
99
133
  return null;
100
134
  }
101
135
 
102
- function loadInstalledProducer(project, packageName) {
136
+ // Loads the exact bare package `packageName` installed under the project's
137
+ // node_modules. `kind` ("producer" or "tool pack") names it in messages and
138
+ // prefixes the error codes, so producer codes stay as they were.
139
+ function loadInstalledPackage(project, packageName, kind) {
140
+ const label = kind || "producer";
141
+ const code = label.replace(/ /g, "_");
103
142
  let resolved;
104
143
  try {
105
144
  resolved = createRequire(project.path).resolve(packageName);
106
145
  } catch {
107
- throw new ProducerHostError("The configured producer package is not installed in the project.", "producer_package_not_installed");
146
+ throw new ProducerHostError(
147
+ `The configured ${label} package is not installed in the project.`,
148
+ `${code}_package_not_installed`,
149
+ );
108
150
  }
109
151
  if (!path.isAbsolute(resolved)) {
110
- throw new ProducerHostError("The configured producer package must resolve to an installed npm package.", "invalid_producer_package");
152
+ throw new ProducerHostError(
153
+ `The configured ${label} package must resolve to an installed npm package.`,
154
+ `invalid_${code}_package`,
155
+ );
111
156
  }
112
157
  let projectRoot;
113
158
  try {
@@ -118,7 +163,10 @@ function loadInstalledProducer(project, packageName) {
118
163
  const projectPath = path.resolve(project.path);
119
164
  const installDirectory = locateInstalledPackage(projectRoot, projectPath, packageName);
120
165
  if (!installDirectory) {
121
- throw new ProducerHostError("The configured producer package must be installed under a project node_modules directory.", "invalid_producer_package");
166
+ throw new ProducerHostError(
167
+ `The configured ${label} package must be installed under a project node_modules directory.`,
168
+ `invalid_${code}_package`,
169
+ );
122
170
  }
123
171
  let realInstall;
124
172
  let realResolved;
@@ -126,28 +174,46 @@ function loadInstalledProducer(project, packageName) {
126
174
  realInstall = fs.realpathSync(installDirectory);
127
175
  realResolved = fs.realpathSync(resolved);
128
176
  } catch {
129
- throw new ProducerHostError("The configured producer package could not be resolved safely.", "invalid_producer_package");
177
+ throw new ProducerHostError(
178
+ `The configured ${label} package could not be resolved safely.`,
179
+ `invalid_${code}_package`,
180
+ );
130
181
  }
131
182
  // A workspace or linked install points out of node_modules; that is an
132
183
  // install-tool detail, and anything able to write there can already run
133
184
  // install scripts. What must hold is that the entry node resolved belongs to
134
185
  // the package the project installed under that exact bare name.
135
186
  if (!isInside(realInstall, realResolved)) {
136
- throw new ProducerHostError("The configured producer package must resolve inside its installed package directory.", "invalid_producer_package");
187
+ throw new ProducerHostError(
188
+ `The configured ${label} package must resolve inside its installed package directory.`,
189
+ `invalid_${code}_package`,
190
+ );
137
191
  }
138
192
  return require(realResolved);
139
193
  }
140
194
 
195
+ function loadInstalledProducer(project, packageName) {
196
+ return loadInstalledPackage(project, packageName, "producer");
197
+ }
198
+
141
199
  function inspectConfig(value, envNames, pathParts) {
142
200
  if (!value || typeof value !== "object") return;
143
201
  Object.entries(value).forEach(([key, child]) => {
144
202
  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
145
203
  if (UNSAFE_CONFIG_KEYS.has(normalized)) {
146
- throw new ProducerHostError("Producer config contains a host-controlled or unsafe field.", "unsafe_producer_config", { field: pathParts.concat(key).join(".") });
204
+ throw new ProducerHostError(
205
+ "Producer config contains a host-controlled or unsafe field.",
206
+ "unsafe_producer_config",
207
+ { field: pathParts.concat(key).join(".") },
208
+ );
147
209
  }
148
210
  if (/env$/i.test(key)) {
149
211
  if (typeof child !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(child)) {
150
- throw new ProducerHostError("Producer secret references must be valid environment variable names.", "invalid_producer_secret_reference", { field: pathParts.concat(key).join(".") });
212
+ throw new ProducerHostError(
213
+ "Producer secret references must be valid environment variable names.",
214
+ "invalid_producer_secret_reference",
215
+ { field: pathParts.concat(key).join(".") },
216
+ );
151
217
  }
152
218
  envNames.add(child);
153
219
  }
@@ -158,19 +224,33 @@ function inspectConfig(value, envNames, pathParts) {
158
224
  function validateDescriptor(instance, moduleValue, allowedRelationTypes) {
159
225
  const descriptor = moduleValue && moduleValue.okfProducer;
160
226
  if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
161
- throw new ProducerHostError("Producer package must export okfProducer.", "invalid_producer_descriptor");
227
+ throw new ProducerHostError(
228
+ "Producer package must export okfProducer.",
229
+ "invalid_producer_descriptor",
230
+ );
162
231
  }
163
- if (String(descriptor.apiVersion || "") !== "1"
164
- || String(descriptor.okfVersion || "") !== "0.2"
165
- || descriptor.id !== instance.type
166
- || typeof descriptor.version !== "string" || !descriptor.version.trim()
167
- || typeof descriptor.validateConfig !== "function"
168
- || typeof descriptor.generate !== "function") {
169
- throw new ProducerHostError("Producer descriptor is incompatible with this host.", "incompatible_producer_descriptor");
232
+ if (
233
+ String(descriptor.apiVersion || "") !== "1" ||
234
+ String(descriptor.okfVersion || "") !== "0.2" ||
235
+ descriptor.id !== instance.type ||
236
+ typeof descriptor.version !== "string" ||
237
+ !descriptor.version.trim() ||
238
+ typeof descriptor.validateConfig !== "function" ||
239
+ typeof descriptor.generate !== "function"
240
+ ) {
241
+ throw new ProducerHostError(
242
+ "Producer descriptor is incompatible with this host.",
243
+ "incompatible_producer_descriptor",
244
+ );
170
245
  }
171
- const relationTypes = Array.isArray(descriptor.relationTypes) ? descriptor.relationTypes.map(String) : [];
246
+ const relationTypes = Array.isArray(descriptor.relationTypes)
247
+ ? descriptor.relationTypes.map(String)
248
+ : [];
172
249
  if (relationTypes.some((type) => !allowedRelationTypes.has(type))) {
173
- throw new ProducerHostError("Producer declares a relation type that the project does not allow.", "producer_relation_type_not_allowed");
250
+ throw new ProducerHostError(
251
+ "Producer declares a relation type that the project does not allow.",
252
+ "producer_relation_type_not_allowed",
253
+ );
174
254
  }
175
255
  return descriptor;
176
256
  }
@@ -179,12 +259,15 @@ function buildCandidate(project, bundles, remoteBundles, files, stalePaths) {
179
259
  const overrides = new Map();
180
260
  files.forEach((file) => overrides.set(`${file.bundle}\u0000${file.path}`, file.content));
181
261
  const deletions = new Set(stalePaths.map((entry) => `${entry.bundle}\u0000${entry.path}`));
182
- return attachProject(buildIndex(bundles.concat(remoteBundles || []), {
183
- relationTypes: project.relationTypes,
184
- strictLinks: project.strictLinks,
185
- documentOverrides: overrides,
186
- documentDeletions: deletions,
187
- }), project);
262
+ return attachProject(
263
+ buildIndex(bundles.concat(remoteBundles || []), {
264
+ relationTypes: project.relationTypes,
265
+ strictLinks: project.strictLinks,
266
+ documentOverrides: overrides,
267
+ documentDeletions: deletions,
268
+ }),
269
+ project,
270
+ );
188
271
  }
189
272
 
190
273
  function validateCandidate(index, instance, outputPaths) {
@@ -193,24 +276,28 @@ function validateCandidate(index, instance, outputPaths) {
193
276
  if (!bundle || bundle.okfVersion !== "0.2") {
194
277
  diagnostics.push(diagnostic("producer_bundle_requires_okf_0_2", { path: "index.md" }));
195
278
  }
196
- const root = index.documents.find((doc) => doc.bundle === instance.bundle && doc.path === "index.md");
279
+ const root = index.documents.find(
280
+ (doc) => doc.bundle === instance.bundle && doc.path === "index.md",
281
+ );
197
282
  if (!root) {
198
283
  diagnostics.push(diagnostic("producer_missing_root_index", { path: "index.md" }));
199
284
  } else {
200
285
  try {
201
286
  const split = splitFrontmatter(root.text);
202
- if (!split.frontmatter
203
- || Object.keys(split.frontmatter).length !== 1
204
- || split.frontmatter.okf_version !== "0.2") {
287
+ if (
288
+ !split.frontmatter ||
289
+ Object.keys(split.frontmatter).length !== 1 ||
290
+ split.frontmatter.okf_version !== "0.2"
291
+ ) {
205
292
  diagnostics.push(diagnostic("producer_invalid_root_index", { path: "index.md" }));
206
293
  }
207
294
  } catch {
208
295
  diagnostics.push(diagnostic("producer_invalid_root_index", { path: "index.md" }));
209
296
  }
210
297
  }
211
- const documents = new Map(index.documents
212
- .filter((doc) => doc.bundle === instance.bundle)
213
- .map((doc) => [doc.path, doc]));
298
+ const documents = new Map(
299
+ index.documents.filter((doc) => doc.bundle === instance.bundle).map((doc) => [doc.path, doc]),
300
+ );
214
301
  outputPaths.forEach((relativePath) => {
215
302
  const doc = documents.get(relativePath);
216
303
  if (!doc) {
@@ -224,28 +311,44 @@ function validateCandidate(index, instance, outputPaths) {
224
311
  diagnostics.push(diagnostic(`producer_missing_${field}`, { path: relativePath, field }));
225
312
  }
226
313
  }
227
- if (doc.signals.generatedOrigin !== "native"
228
- || !doc.signals.generated || doc.signals.generated.valid !== true) {
229
- diagnostics.push(diagnostic("producer_invalid_generated", { path: relativePath, field: "generated" }));
314
+ if (
315
+ doc.signals.generatedOrigin !== "native" ||
316
+ !doc.signals.generated ||
317
+ doc.signals.generated.valid !== true
318
+ ) {
319
+ diagnostics.push(
320
+ diagnostic("producer_invalid_generated", { path: relativePath, field: "generated" }),
321
+ );
230
322
  }
231
- if (doc.signals.sourcesOrigin !== "native"
232
- || !Array.isArray(doc.signals.sources) || doc.signals.sources.length === 0
233
- || doc.signals.sources.some((source) => source.valid !== true)) {
234
- diagnostics.push(diagnostic("producer_invalid_sources", { path: relativePath, field: "sources" }));
323
+ if (
324
+ doc.signals.sourcesOrigin !== "native" ||
325
+ !Array.isArray(doc.signals.sources) ||
326
+ doc.signals.sources.length === 0 ||
327
+ doc.signals.sources.some((source) => source.valid !== true)
328
+ ) {
329
+ diagnostics.push(
330
+ diagnostic("producer_invalid_sources", { path: relativePath, field: "sources" }),
331
+ );
235
332
  }
236
333
  (doc.v02Diagnostics || []).forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
237
334
  });
238
335
  const generatedPaths = new Set(outputPaths);
239
- (index.errors || []).filter((entry) => (
240
- entry.bundle === instance.bundle
241
- && generatedPaths.has(entry.path)
242
- && ["broken_relation", "missing_relation_target", "parse_error"].includes(entry.code)
243
- )).forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
244
- (index.warnings || []).filter((entry) => (
245
- entry.bundle === instance.bundle
246
- && generatedPaths.has(entry.path)
247
- && ["broken_link", "link_outside_root", "broken_semantic_reference"].includes(entry.code)
248
- )).forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
336
+ (index.errors || [])
337
+ .filter(
338
+ (entry) =>
339
+ entry.bundle === instance.bundle &&
340
+ generatedPaths.has(entry.path) &&
341
+ ["broken_relation", "missing_relation_target", "parse_error"].includes(entry.code),
342
+ )
343
+ .forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
344
+ (index.warnings || [])
345
+ .filter(
346
+ (entry) =>
347
+ entry.bundle === instance.bundle &&
348
+ generatedPaths.has(entry.path) &&
349
+ ["broken_link", "link_outside_root", "broken_semantic_reference"].includes(entry.code),
350
+ )
351
+ .forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
249
352
  const projectValidation = index.validation || require("./validation").validateIndex(index);
250
353
  if (!index.conformant || !index.validForProject) {
251
354
  projectValidation.diagnostics.forEach((entry) => diagnostics.push(publicDiagnostic(entry)));
@@ -266,15 +369,23 @@ function countsFor(changes) {
266
369
 
267
370
  function normalizeSummary(value) {
268
371
  if (!value || typeof value !== "object" || Array.isArray(value)) {
269
- throw new ProducerHostError("Producer generate() must return a numeric summary.", "invalid_producer_summary");
372
+ throw new ProducerHostError(
373
+ "Producer generate() must return a numeric summary.",
374
+ "invalid_producer_summary",
375
+ );
270
376
  }
271
377
  const entries = Object.entries(value);
272
- if (entries.length > 50 || entries.some(([key, count]) => (
273
- !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key)
274
- || !Number.isSafeInteger(count)
275
- || count < 0
276
- ))) {
277
- throw new ProducerHostError("Producer summary entries must be bounded non-negative integers.", "invalid_producer_summary");
378
+ if (
379
+ entries.length > 50 ||
380
+ entries.some(
381
+ ([key, count]) =>
382
+ !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || !Number.isSafeInteger(count) || count < 0,
383
+ )
384
+ ) {
385
+ throw new ProducerHostError(
386
+ "Producer summary entries must be bounded non-negative integers.",
387
+ "invalid_producer_summary",
388
+ );
278
389
  }
279
390
  return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right)));
280
391
  }
@@ -290,11 +401,16 @@ function producerReceipt(receipt, detail) {
290
401
  readyToApply: receipt.readyToApply === true,
291
402
  ...(receipt.applied !== undefined ? { applied: receipt.applied === true } : {}),
292
403
  ...(receipt.conformant !== undefined ? { conformant: receipt.conformant === true } : {}),
293
- ...(receipt.validForProject !== undefined ? { validForProject: receipt.validForProject === true } : {}),
404
+ ...(receipt.validForProject !== undefined
405
+ ? { validForProject: receipt.validForProject === true }
406
+ : {}),
294
407
  ...(receipt.generatedAt ? { generatedAt: receipt.generatedAt } : {}),
295
408
  counts: receipt.counts || { create: 0, update: 0, delete: 0, unchanged: 0 },
296
409
  summary: receipt.summary || {},
297
410
  diagnostics: Array.isArray(receipt.diagnostics) ? receipt.diagnostics.slice(0, 100) : [],
411
+ ...(Array.isArray(receipt.policyViolations)
412
+ ? { policyViolations: receipt.policyViolations.slice(0, 100) }
413
+ : {}),
298
414
  };
299
415
  if (detail === "full" && receipt.changes) {
300
416
  result.changes = {};
@@ -329,9 +445,15 @@ class ProducerService {
329
445
 
330
446
  getInstance(name) {
331
447
  const instance = (this.project.producers || []).find((entry) => entry.name === name);
332
- if (!instance) throw new ProducerHostError("Unknown configured producer.", "producer_not_found");
333
- if ((this.project.errors || []).some((entry) => String(entry.code || "").includes("producer"))) {
334
- throw new ProducerHostError("Project producer configuration is invalid.", "invalid_producer_configuration");
448
+ if (!instance)
449
+ throw new ProducerHostError("Unknown configured producer.", "producer_not_found");
450
+ if (
451
+ (this.project.errors || []).some((entry) => String(entry.code || "").includes("producer"))
452
+ ) {
453
+ throw new ProducerHostError(
454
+ "Project producer configuration is invalid.",
455
+ "invalid_producer_configuration",
456
+ );
335
457
  }
336
458
  return instance;
337
459
  }
@@ -347,7 +469,10 @@ class ProducerService {
347
469
  );
348
470
  } catch (error) {
349
471
  if (error instanceof ProducerHostError) throw error;
350
- throw new ProducerHostError("The configured producer package could not be loaded.", "producer_load_failed");
472
+ throw new ProducerHostError(
473
+ "The configured producer package could not be loaded.",
474
+ "producer_load_failed",
475
+ );
351
476
  }
352
477
  const envNames = new Set();
353
478
  inspectConfig(instance.config, envNames, ["config"]);
@@ -355,28 +480,42 @@ class ProducerService {
355
480
  try {
356
481
  configValidation = await descriptor.validateConfig(structuredClone(instance.config));
357
482
  } catch {
358
- throw new ProducerHostError("Producer configuration validation failed unexpectedly.", "producer_config_validation_failed");
483
+ throw new ProducerHostError(
484
+ "Producer configuration validation failed unexpectedly.",
485
+ "producer_config_validation_failed",
486
+ );
359
487
  }
360
488
  if (!configValidation || configValidation.valid !== true) {
361
489
  const entries = Array.isArray(configValidation && configValidation.diagnostics)
362
- ? configValidation.diagnostics.slice(0, 100).map((entry) => diagnostic(
363
- typeof entry.code === "string" ? entry.code : "producer_config_invalid",
364
- typeof entry.field === "string" ? { field: entry.field } : undefined,
365
- ))
490
+ ? configValidation.diagnostics
491
+ .slice(0, 100)
492
+ .map((entry) =>
493
+ diagnostic(
494
+ typeof entry.code === "string" ? entry.code : "producer_config_invalid",
495
+ typeof entry.field === "string" ? { field: entry.field } : undefined,
496
+ ),
497
+ )
366
498
  : [diagnostic("producer_config_invalid")];
367
499
  return { instance, descriptor, valid: false, readyToApply: false, diagnostics: entries };
368
500
  }
369
- const normalizedConfig = configValidation.config === undefined
370
- ? structuredClone(instance.config)
371
- : configValidation.config;
501
+ const normalizedConfig =
502
+ configValidation.config === undefined
503
+ ? structuredClone(instance.config)
504
+ : configValidation.config;
372
505
  const accessedSecrets = [];
373
506
  const getSecret = (secretName) => {
374
507
  if (!envNames.has(secretName)) {
375
- throw new ProducerHostError("Producer requested a secret not referenced by its configuration.", "producer_secret_not_allowed");
508
+ throw new ProducerHostError(
509
+ "Producer requested a secret not referenced by its configuration.",
510
+ "producer_secret_not_allowed",
511
+ );
376
512
  }
377
513
  const value = this.env[secretName];
378
514
  if (typeof value !== "string" || value.length === 0) {
379
- throw new ProducerHostError("A configured producer secret is unavailable.", "producer_secret_unavailable");
515
+ throw new ProducerHostError(
516
+ "A configured producer secret is unavailable.",
517
+ "producer_secret_unavailable",
518
+ );
380
519
  }
381
520
  accessedSecrets.push(value);
382
521
  return value;
@@ -389,11 +528,15 @@ class ProducerService {
389
528
  config: structuredClone(normalizedConfig),
390
529
  generatedAt,
391
530
  getSecret,
392
- signal: options && options.signal || new AbortController().signal,
531
+ signal: (options && options.signal) || new AbortController().signal,
393
532
  });
394
533
  } catch (error) {
395
534
  if (error instanceof ProducerHostError) throw error;
396
- throw new ProducerHostError("Producer execution failed.", "producer_execution_failed");
535
+ const reported = producerErrorDiagnostic(error, accessedSecrets);
536
+ if (!reported) {
537
+ throw new ProducerHostError("Producer execution failed.", "producer_execution_failed");
538
+ }
539
+ return { instance, descriptor, valid: false, readyToApply: false, diagnostics: [reported] };
397
540
  }
398
541
  let files;
399
542
  let summary;
@@ -402,48 +545,103 @@ class ProducerService {
402
545
  summary = normalizeSummary(generated && generated.summary);
403
546
  } catch (error) {
404
547
  if (error instanceof ProducerPublicationError || error instanceof ProducerHostError) {
405
- return { instance, descriptor, valid: false, readyToApply: false, diagnostics: [publicDiagnostic(error)] };
548
+ return {
549
+ instance,
550
+ descriptor,
551
+ valid: false,
552
+ readyToApply: false,
553
+ diagnostics: [publicDiagnostic(error)],
554
+ };
406
555
  }
407
556
  throw error;
408
557
  }
409
- if (files.length > MAX_PRODUCER_FILES
410
- || files.reduce((total, file) => total + Buffer.byteLength(file.content), 0) > MAX_PRODUCER_BYTES) {
411
- return { instance, descriptor, valid: false, readyToApply: false, diagnostics: [diagnostic("producer_output_too_large")] };
558
+ if (
559
+ files.length > MAX_PRODUCER_FILES ||
560
+ files.reduce((total, file) => total + Buffer.byteLength(file.content), 0) > MAX_PRODUCER_BYTES
561
+ ) {
562
+ return {
563
+ instance,
564
+ descriptor,
565
+ valid: false,
566
+ readyToApply: false,
567
+ diagnostics: [diagnostic("producer_output_too_large")],
568
+ };
412
569
  }
413
- if (accessedSecrets.some((secret) => files.some((file) => secret && file.content.includes(secret)))) {
414
- return { instance, descriptor, valid: false, readyToApply: false, diagnostics: [diagnostic("producer_secret_leak")] };
570
+ if (
571
+ accessedSecrets.some((secret) =>
572
+ files.some((file) => secret && file.content.includes(secret)),
573
+ )
574
+ ) {
575
+ return {
576
+ instance,
577
+ descriptor,
578
+ valid: false,
579
+ readyToApply: false,
580
+ diagnostics: [diagnostic("producer_secret_leak")],
581
+ };
415
582
  }
416
583
  let inspection;
417
584
  try {
418
- inspection = this.publisher.inspect(Object.assign({}, instance, { version: descriptor.version }), files);
585
+ inspection = this.publisher.inspect(
586
+ Object.assign({}, instance, { version: descriptor.version }),
587
+ files,
588
+ );
419
589
  } catch (error) {
420
590
  if (error instanceof ProducerPublicationError) {
421
- return { instance, descriptor, files, valid: false, readyToApply: false, diagnostics: [publicDiagnostic(error)] };
591
+ return {
592
+ instance,
593
+ descriptor,
594
+ files,
595
+ valid: false,
596
+ readyToApply: false,
597
+ diagnostics: [publicDiagnostic(error)],
598
+ };
422
599
  }
423
- throw new ProducerHostError("Producer publication preflight failed.", "producer_publication_preflight_failed");
600
+ throw new ProducerHostError(
601
+ "Producer publication preflight failed.",
602
+ "producer_publication_preflight_failed",
603
+ );
424
604
  }
425
- const candidateFiles = (inspection.effective || files)
426
- .map((file) => Object.assign({ bundle: instance.bundle }, file));
427
- const stalePaths = inspection.changes.delete.map((relativePath) => ({ bundle: instance.bundle, path: relativePath }));
605
+ const candidateFiles = (inspection.effective || files).map((file) =>
606
+ Object.assign({ bundle: instance.bundle }, file),
607
+ );
608
+ const stalePaths = inspection.changes.delete.map((relativePath) => ({
609
+ bundle: instance.bundle,
610
+ path: relativePath,
611
+ }));
428
612
  const candidate = buildCandidate(
429
613
  this.project,
430
614
  this.bundles,
431
- options && options.additionalBundles || [],
615
+ (options && options.additionalBundles) || [],
432
616
  candidateFiles,
433
617
  stalePaths,
434
618
  );
435
- const validation = validateCandidate(candidate, instance, files.map((file) => file.path));
619
+ const validation = validateCandidate(
620
+ candidate,
621
+ instance,
622
+ files.map((file) => file.path),
623
+ );
624
+ // Opt-in only (writePolicy.applyToProducers): preview reports the
625
+ // violations read-only and run refuses before publication.
626
+ const policyViolations = evaluateProducerFiles(
627
+ this.project.writePolicy,
628
+ instance,
629
+ files,
630
+ inspection.changes,
631
+ );
632
+ const allowed = !policyViolations?.length;
436
633
  return {
437
634
  instance,
438
635
  descriptor,
439
636
  files,
440
637
  changes: inspection.changes,
441
638
  counts: countsFor(inspection.changes),
442
- valid: validation.valid,
443
- readyToApply: validation.valid,
639
+ valid: validation.valid && allowed,
640
+ readyToApply: validation.valid && allowed,
444
641
  conformant: validation.conformant,
445
642
  validForProject: validation.validForProject,
446
- diagnostics: validation.diagnostics,
643
+ diagnostics: validation.diagnostics.concat(policyDiagnostics(policyViolations || [])),
644
+ ...(policyViolations ? { policyViolations } : {}),
447
645
  summary,
448
646
  generatedAt,
449
647
  };
@@ -457,20 +655,29 @@ class ProducerService {
457
655
  return this.store.withWriteLock(async () => {
458
656
  const prepared = await this.prepare(name, options);
459
657
  if (!prepared.readyToApply) return Object.assign({}, prepared, { applied: false });
460
- const producer = Object.assign({}, prepared.instance, { version: prepared.descriptor.version });
658
+ const producer = Object.assign({}, prepared.instance, {
659
+ version: prepared.descriptor.version,
660
+ });
461
661
  let changes;
462
662
  try {
463
663
  changes = await this.publisher.publish(producer, prepared.files, async () => {
464
664
  const persisted = buildCandidate(
465
665
  this.project,
466
666
  this.bundles,
467
- options && options.additionalBundles || [],
667
+ (options && options.additionalBundles) || [],
468
668
  [],
469
669
  [],
470
670
  );
471
- const validation = validateCandidate(persisted, prepared.instance, prepared.files.map((file) => file.path));
671
+ const validation = validateCandidate(
672
+ persisted,
673
+ prepared.instance,
674
+ prepared.files.map((file) => file.path),
675
+ );
472
676
  if (!validation.valid) {
473
- throw new ProducerHostError("Persisted producer output failed validation.", "persisted_producer_validation_failed");
677
+ throw new ProducerHostError(
678
+ "Persisted producer output failed validation.",
679
+ "persisted_producer_validation_failed",
680
+ );
474
681
  }
475
682
  });
476
683
  } catch (error) {
@@ -498,6 +705,7 @@ module.exports = {
498
705
  ProducerHostError,
499
706
  ProducerService,
500
707
  buildCandidate,
708
+ loadInstalledPackage,
501
709
  loadInstalledProducer,
502
710
  normalizeSummary,
503
711
  producerReceipt,