@mfdaves/okf-mcp 0.9.0 → 0.12.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.
- package/CHANGELOG.md +69 -0
- package/README.md +176 -19
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/policies/authoring-safety.md +11 -1
- package/package.json +17 -5
- package/server.json +2 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +391 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +776 -0
- package/src/authoring/live.js +789 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +137 -0
- package/src/authoring/receipts.js +329 -0
- package/src/authoring/render.js +38 -0
- package/src/authoring/shared.js +75 -0
- package/src/authoring/staging.js +216 -0
- package/src/authoring.js +386 -287
- package/src/cache/files.js +147 -0
- package/src/cache/lock.js +201 -0
- package/src/cache/paths.js +197 -0
- package/src/cache/store.js +703 -0
- package/src/catalog-text.js +19 -0
- package/src/cli.js +184 -151
- package/src/computation.js +99 -61
- package/src/context/assemble.js +567 -0
- package/src/context/cli-options.js +88 -0
- package/src/context/score.js +234 -0
- package/src/context/sections.js +274 -0
- package/src/embed/interface.js +160 -0
- package/src/embed/openai.js +715 -0
- package/src/embed/prepare.js +182 -0
- package/src/embed/units.js +96 -0
- package/src/git-source.js +112 -52
- package/src/graph.js +95 -37
- package/src/http-server.js +36 -17
- package/src/index.js +15 -0
- package/src/indexer/assemble.js +566 -0
- package/src/indexer/build.js +290 -0
- package/src/indexer/cache.js +81 -0
- package/src/indexer/edges.js +430 -0
- package/src/indexer/index.js +44 -0
- package/src/indexer/paths.js +178 -0
- package/src/indexer/resolve.js +282 -0
- package/src/indexer/update.js +720 -0
- package/src/indexer.js +3 -1068
- package/src/live-authoring.js +4 -2329
- package/src/markdown.js +21 -16
- package/src/mcp/registry.js +328 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +472 -0
- package/src/mcp/tools/catalog.js +244 -0
- package/src/mcp/tools/computation.js +83 -0
- package/src/mcp/tools/context.js +133 -0
- package/src/mcp/tools/graph.js +167 -0
- package/src/mcp/tools/live-authoring.js +316 -0
- package/src/mcp/tools/migration.js +86 -0
- package/src/mcp/tools/producers.js +79 -0
- package/src/mcp/tools/proposals.js +213 -0
- package/src/mcp/tools/provenance.js +87 -0
- package/src/mcp/tools/remote.js +79 -0
- package/src/mcp/tools/search.js +242 -0
- package/src/mcp-server.js +3 -1611
- package/src/migration.js +431 -253
- package/src/parser.js +245 -130
- package/src/plugins.js +71 -48
- package/src/policy/write-policy.js +713 -0
- package/src/producer-publisher.js +195 -77
- package/src/producers.js +265 -101
- package/src/project.js +277 -93
- package/src/remote.js +96 -61
- package/src/search/cli-options.js +107 -0
- package/src/search/confidence.js +61 -0
- package/src/search/dense.js +304 -0
- package/src/search/embedding-cli.js +57 -0
- package/src/search/embedding-config.js +217 -0
- package/src/search/fusion.js +249 -0
- package/src/search/hybrid.js +526 -0
- package/src/search/languages.js +200 -0
- package/src/search/lexical.js +695 -0
- package/src/search/query.js +620 -0
- package/src/search/stem/among.js +43 -0
- package/src/search/stem/base-stemmer.js +311 -0
- package/src/search/stem/en-regions.js +456 -0
- package/src/search/stem/en-suffixes.js +664 -0
- package/src/search/stem/en-tables.js +176 -0
- package/src/search/stem/en.js +238 -0
- package/src/search/stem/it-regions.js +459 -0
- package/src/search/stem/it-suffixes.js +471 -0
- package/src/search/stem/it-tables.js +257 -0
- package/src/search/stem/it.js +155 -0
- package/src/search-index.js +2 -81
- package/src/search.js +2 -252
- package/src/store.js +134 -81
- package/src/v02.js +301 -105
- package/src/validation.js +24 -20
|
@@ -0,0 +1,789 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("node:fs");
|
|
4
|
+
const path = require("node:path");
|
|
5
|
+
const { spawnSync: nodeSpawnSync } = require("node:child_process");
|
|
6
|
+
const { isDeepStrictEqual } = require("node:util");
|
|
7
|
+
|
|
8
|
+
const {
|
|
9
|
+
deriveConceptPathSuggestion,
|
|
10
|
+
isConfiguredGeneratorOutput,
|
|
11
|
+
normalizeConceptPath,
|
|
12
|
+
renderConceptMarkdown,
|
|
13
|
+
} = require("../authoring");
|
|
14
|
+
const {
|
|
15
|
+
IndexCache,
|
|
16
|
+
attachProject,
|
|
17
|
+
buildIndex,
|
|
18
|
+
bundleAllowsPath,
|
|
19
|
+
conceptMatchSummary,
|
|
20
|
+
refreshIndex,
|
|
21
|
+
resolveConcept,
|
|
22
|
+
updateIndex,
|
|
23
|
+
validateIndex,
|
|
24
|
+
} = require("../indexer");
|
|
25
|
+
const {
|
|
26
|
+
MANAGED_METADATA_KEYS,
|
|
27
|
+
actorValue,
|
|
28
|
+
applyRelationPatch,
|
|
29
|
+
applySourcePatch,
|
|
30
|
+
applyTagPatch,
|
|
31
|
+
conceptConflictDetails,
|
|
32
|
+
conceptIsManaged,
|
|
33
|
+
nonEmptyString,
|
|
34
|
+
normalizeBody,
|
|
35
|
+
normalizeRelation,
|
|
36
|
+
normalizeSource,
|
|
37
|
+
semanticConceptKey,
|
|
38
|
+
staleUpdateDetails,
|
|
39
|
+
uniqueStrings,
|
|
40
|
+
validateMetadata,
|
|
41
|
+
validateRemovalKeys,
|
|
42
|
+
} = require("./candidates");
|
|
43
|
+
const { GitPublisher } = require("./git-publish");
|
|
44
|
+
const { enforceWritePolicy, resolveWritePolicy, withPolicyViolations } = require("./policy-hook");
|
|
45
|
+
const {
|
|
46
|
+
candidateSummaries,
|
|
47
|
+
durabilityReceipt,
|
|
48
|
+
policyReceipt,
|
|
49
|
+
policyValidation,
|
|
50
|
+
preconditionsReceipt,
|
|
51
|
+
rollbackReceipt,
|
|
52
|
+
snapshotReceipt,
|
|
53
|
+
targetReceipt,
|
|
54
|
+
validationReceipt,
|
|
55
|
+
} = require("./receipts");
|
|
56
|
+
const {
|
|
57
|
+
AuthoringOperationalError,
|
|
58
|
+
AuthoringPolicyError,
|
|
59
|
+
byteLength,
|
|
60
|
+
hasOwn,
|
|
61
|
+
isPlainObject,
|
|
62
|
+
revisionFor,
|
|
63
|
+
} = require("./shared");
|
|
64
|
+
const { assertRevisions, rollback, stageCandidates } = require("./staging");
|
|
65
|
+
|
|
66
|
+
const MAX_CHANGES = 100;
|
|
67
|
+
const MAX_COMMIT_MESSAGE_BYTES = 1024;
|
|
68
|
+
|
|
69
|
+
// The candidate as an index upsert: its rendered Markdown before it is
|
|
70
|
+
// written, or a read-back of the target path once it is.
|
|
71
|
+
function candidateUpsert(candidate, persisted) {
|
|
72
|
+
const upsert = { bundleId: candidate.bundle, relativePath: candidate.path };
|
|
73
|
+
return persisted ? upsert : Object.assign(upsert, { text: candidate.markdown });
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
class LiveAuthoringService {
|
|
77
|
+
constructor(store, options) {
|
|
78
|
+
const config = options || {};
|
|
79
|
+
this.store = store;
|
|
80
|
+
this.actor = actorValue(config.actor);
|
|
81
|
+
this.gitCommit = Boolean(config.gitCommit);
|
|
82
|
+
this.spawnSync = config.spawnSync || nodeSpawnSync;
|
|
83
|
+
this.now = config.now || (() => new Date());
|
|
84
|
+
this.git = new GitPublisher({ gitCommit: this.gitCommit, spawnSync: this.spawnSync });
|
|
85
|
+
this.writePolicy = resolveWritePolicy(config, store);
|
|
86
|
+
// One index kept between batches and refreshed before each (W-6); a host
|
|
87
|
+
// hands one over through adoptIndex and takes it back via takePublication.
|
|
88
|
+
this.indexCache = new IndexCache({ now: this.now });
|
|
89
|
+
this.publication = null;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
adoptIndex(index, additionalBundles) {
|
|
93
|
+
this.indexCache.adopt(index, additionalBundles);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
takePublication() {
|
|
97
|
+
const publication = this.publication;
|
|
98
|
+
this.publication = null;
|
|
99
|
+
return publication;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// Under the writer lock like the rest of a batch; the once-a-day rebuild
|
|
103
|
+
// for a new calendar day (updateIndex) lands here: one build's latency.
|
|
104
|
+
currentIndex(additionalBundles) {
|
|
105
|
+
return this.indexCache.current(additionalBundles, () => this.buildIndex(additionalBundles));
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
// Called when the files on disk are no longer known to match any index the
|
|
109
|
+
// service holds (an incomplete rollback, a diverged worktree).
|
|
110
|
+
forgetIndex() {
|
|
111
|
+
this.indexCache.forget();
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
getBundle(id) {
|
|
115
|
+
const bundles = this.store.getBundles();
|
|
116
|
+
const bundle = id
|
|
117
|
+
? bundles.find((entry) => entry.id === id)
|
|
118
|
+
: bundles.length === 1
|
|
119
|
+
? bundles[0]
|
|
120
|
+
: null;
|
|
121
|
+
if (!bundle) {
|
|
122
|
+
throw new Error(
|
|
123
|
+
id
|
|
124
|
+
? `Unknown writable OKF bundle: ${id}`
|
|
125
|
+
: "A bundle id is required unless exactly one writable OKF root is configured.",
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
return bundle;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
buildIndex(additionalBundles, documentOverrides) {
|
|
132
|
+
const index = buildIndex(this.store.getBundles().concat(additionalBundles || []), {
|
|
133
|
+
relationTypes: this.store.getRelationTypes(),
|
|
134
|
+
strictLinks: this.store.strictLinks,
|
|
135
|
+
allowCustomRelationTypes: this.store.allowCustomRelationTypes,
|
|
136
|
+
documentOverrides,
|
|
137
|
+
});
|
|
138
|
+
return this.store.project ? attachProject(index, this.store.project) : index;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
assertWritableTarget(bundle, conceptPath, existing) {
|
|
142
|
+
const target = this.store.resolveConceptFile(bundle.id, conceptPath);
|
|
143
|
+
if (isConfiguredGeneratorOutput(this.store.project, target.absolutePath)) {
|
|
144
|
+
throw new Error(
|
|
145
|
+
`Concept is inside a configured generator output and must be changed through its generator: ${conceptPath}`,
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
if (existing && conceptIsManaged(existing, this.store.project)) {
|
|
149
|
+
throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
|
|
150
|
+
}
|
|
151
|
+
return target;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
createCandidate(change, bundle, currentIndex, generated) {
|
|
155
|
+
const type = nonEmptyString(change.type, "changes[].type");
|
|
156
|
+
if (type === "Attested Computation") {
|
|
157
|
+
throw new Error("Live concept authoring cannot create Attested Computation contracts.");
|
|
158
|
+
}
|
|
159
|
+
const title = nonEmptyString(change.title, "changes[].title");
|
|
160
|
+
const conceptPath = normalizeConceptPath(
|
|
161
|
+
change.path || deriveConceptPathSuggestion(currentIndex, bundle, { type, title }).path,
|
|
162
|
+
);
|
|
163
|
+
if (!bundleAllowsPath(bundle, conceptPath)) {
|
|
164
|
+
throw new Error(`Concept path is excluded by the bundle policy: ${conceptPath}`);
|
|
165
|
+
}
|
|
166
|
+
const target = this.assertWritableTarget(bundle, conceptPath, null);
|
|
167
|
+
if (fs.existsSync(target.absolutePath)) {
|
|
168
|
+
throw new Error(`Concept file already exists: ${conceptPath}`);
|
|
169
|
+
}
|
|
170
|
+
const metadata = validateMetadata(change.metadata, "changes[].metadata");
|
|
171
|
+
const frontmatter = Object.assign({ type, title }, metadata);
|
|
172
|
+
if (hasOwn(change, "description")) {
|
|
173
|
+
frontmatter.description = String(change.description);
|
|
174
|
+
}
|
|
175
|
+
const tags = uniqueStrings(change.tags, "changes[].tags");
|
|
176
|
+
if (change.sources !== undefined && !Array.isArray(change.sources)) {
|
|
177
|
+
throw new Error("changes[].sources must be an array.");
|
|
178
|
+
}
|
|
179
|
+
if (change.relations !== undefined && !Array.isArray(change.relations)) {
|
|
180
|
+
throw new Error("changes[].relations must be an array.");
|
|
181
|
+
}
|
|
182
|
+
const sources = (change.sources || []).map((source, index) =>
|
|
183
|
+
normalizeSource(source, `changes[].sources[${index}]`),
|
|
184
|
+
);
|
|
185
|
+
const relations = (change.relations || []).map((relation, index) =>
|
|
186
|
+
normalizeRelation(relation, `changes[].relations[${index}]`),
|
|
187
|
+
);
|
|
188
|
+
if (tags.length) frontmatter.tags = tags;
|
|
189
|
+
if (sources.length)
|
|
190
|
+
frontmatter.sources = applySourcePatch([], { add: sources }, "changes[].sources");
|
|
191
|
+
if (relations.length)
|
|
192
|
+
frontmatter.relations = applyRelationPatch([], { add: relations }, "changes[].relations");
|
|
193
|
+
frontmatter.generated = generated;
|
|
194
|
+
const body = hasOwn(change, "body") ? String(change.body || "") : `# ${title}`;
|
|
195
|
+
const markdown = renderConceptMarkdown({ path: conceptPath, frontmatter, body });
|
|
196
|
+
return {
|
|
197
|
+
op: "create",
|
|
198
|
+
bundle: bundle.id,
|
|
199
|
+
path: conceptPath,
|
|
200
|
+
uri: `okf://${bundle.id}/${conceptPath.replace(/\.md$/i, "")}`,
|
|
201
|
+
title,
|
|
202
|
+
frontmatter,
|
|
203
|
+
body,
|
|
204
|
+
markdown,
|
|
205
|
+
target,
|
|
206
|
+
baseRevision: null,
|
|
207
|
+
publishedRevision: revisionFor(markdown),
|
|
208
|
+
originalFrontmatter: {},
|
|
209
|
+
originalBody: "",
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
updateCandidate(change, bundle, currentIndex, generated) {
|
|
214
|
+
const uri = nonEmptyString(change.uri, "changes[].uri");
|
|
215
|
+
const existing = resolveConcept(currentIndex, uri);
|
|
216
|
+
if (!existing?.valid || existing.reserved) {
|
|
217
|
+
const details = staleUpdateDetails(currentIndex, uri, bundle.id, this.store.project);
|
|
218
|
+
throw new AuthoringPolicyError(
|
|
219
|
+
`Unknown valid OKF concept: ${uri}`,
|
|
220
|
+
details.recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
|
|
221
|
+
details,
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
if (existing.bundle !== bundle.id) {
|
|
225
|
+
throw new Error(`All changes must target writable bundle ${bundle.id}: ${uri}`);
|
|
226
|
+
}
|
|
227
|
+
if (existing.type === "Attested Computation") {
|
|
228
|
+
throw new Error(
|
|
229
|
+
"Live concept authoring cannot modify Attested Computation contracts or code.",
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
const target = this.assertWritableTarget(bundle, existing.path, existing);
|
|
233
|
+
const originalText = fs.readFileSync(target.absolutePath, "utf8");
|
|
234
|
+
const originalMode = fs.statSync(target.absolutePath).mode;
|
|
235
|
+
const indexedRevision = revisionFor(existing.text);
|
|
236
|
+
const diskRevision = revisionFor(originalText);
|
|
237
|
+
if (indexedRevision !== diskRevision) {
|
|
238
|
+
// planChanges re-reads the document and plans again once; a second
|
|
239
|
+
// mismatch is a conflict the caller sees with the revision now on disk.
|
|
240
|
+
throw new AuthoringPolicyError(
|
|
241
|
+
`Concept changed after it was indexed; retry the update: ${existing.uri}`,
|
|
242
|
+
"concept_changed",
|
|
243
|
+
{
|
|
244
|
+
uri: existing.uri,
|
|
245
|
+
bundleId: existing.bundle,
|
|
246
|
+
relativePath: existing.path,
|
|
247
|
+
indexedRevision,
|
|
248
|
+
revision: diskRevision,
|
|
249
|
+
},
|
|
250
|
+
);
|
|
251
|
+
}
|
|
252
|
+
const frontmatter = Object.assign({}, existing.frontmatter);
|
|
253
|
+
Object.assign(frontmatter, validateMetadata(change.metadata, "changes[].metadata"));
|
|
254
|
+
validateRemovalKeys(change.removeMetadataKeys, "changes[].removeMetadataKeys").forEach(
|
|
255
|
+
(key) => {
|
|
256
|
+
delete frontmatter[key];
|
|
257
|
+
},
|
|
258
|
+
);
|
|
259
|
+
if (hasOwn(change, "title")) {
|
|
260
|
+
frontmatter.title = nonEmptyString(change.title, "changes[].title");
|
|
261
|
+
}
|
|
262
|
+
if (hasOwn(change, "description")) {
|
|
263
|
+
frontmatter.description = String(change.description);
|
|
264
|
+
}
|
|
265
|
+
if (hasOwn(change, "tags")) {
|
|
266
|
+
frontmatter.tags = applyTagPatch(frontmatter.tags, change.tags, "changes[].tags");
|
|
267
|
+
}
|
|
268
|
+
if (hasOwn(change, "sources")) {
|
|
269
|
+
frontmatter.sources = applySourcePatch(
|
|
270
|
+
frontmatter.sources,
|
|
271
|
+
change.sources,
|
|
272
|
+
"changes[].sources",
|
|
273
|
+
);
|
|
274
|
+
}
|
|
275
|
+
if (hasOwn(change, "relations")) {
|
|
276
|
+
frontmatter.relations = applyRelationPatch(
|
|
277
|
+
frontmatter.relations,
|
|
278
|
+
change.relations,
|
|
279
|
+
"changes[].relations",
|
|
280
|
+
);
|
|
281
|
+
}
|
|
282
|
+
const body = hasOwn(change, "body") ? String(change.body || "") : existing.body;
|
|
283
|
+
if (
|
|
284
|
+
isDeepStrictEqual(frontmatter, existing.frontmatter) &&
|
|
285
|
+
normalizeBody(body) === normalizeBody(existing.body)
|
|
286
|
+
) {
|
|
287
|
+
throw new Error(`Update has no effective changes: ${existing.uri}`);
|
|
288
|
+
}
|
|
289
|
+
frontmatter.generated = Object.assign(
|
|
290
|
+
{},
|
|
291
|
+
isPlainObject(existing.frontmatter.generated) ? existing.frontmatter.generated : {},
|
|
292
|
+
generated,
|
|
293
|
+
);
|
|
294
|
+
const markdown = renderConceptMarkdown({ path: existing.path, frontmatter, body });
|
|
295
|
+
return {
|
|
296
|
+
op: "update",
|
|
297
|
+
bundle: bundle.id,
|
|
298
|
+
path: existing.path,
|
|
299
|
+
uri: existing.uri,
|
|
300
|
+
title: frontmatter.title || existing.title,
|
|
301
|
+
frontmatter,
|
|
302
|
+
body,
|
|
303
|
+
markdown,
|
|
304
|
+
target,
|
|
305
|
+
baseRevision: diskRevision,
|
|
306
|
+
publishedRevision: revisionFor(markdown),
|
|
307
|
+
originalText,
|
|
308
|
+
originalMode,
|
|
309
|
+
originalFrontmatter: Object.assign({}, existing.frontmatter),
|
|
310
|
+
originalBody: existing.body,
|
|
311
|
+
};
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
validationResult(index, candidates) {
|
|
315
|
+
const validation = validateIndex(index);
|
|
316
|
+
const candidateDiagnostics = [];
|
|
317
|
+
candidates.forEach((candidate) => {
|
|
318
|
+
const document = index.byPathUri.get(`okf://${candidate.bundle}/${candidate.path}`);
|
|
319
|
+
if (!document || document.reserved || !document.valid) {
|
|
320
|
+
candidateDiagnostics.push({
|
|
321
|
+
code: "candidate_not_indexed",
|
|
322
|
+
severity: "error",
|
|
323
|
+
layer: "project",
|
|
324
|
+
bundle: candidate.bundle,
|
|
325
|
+
path: candidate.path,
|
|
326
|
+
message: "Candidate did not become a valid concept in the future graph.",
|
|
327
|
+
});
|
|
328
|
+
return;
|
|
329
|
+
}
|
|
330
|
+
(document.warnings || [])
|
|
331
|
+
.filter((entry) => entry.layer === "v0.2")
|
|
332
|
+
.forEach((entry) => {
|
|
333
|
+
candidateDiagnostics.push(
|
|
334
|
+
Object.assign({}, entry, {
|
|
335
|
+
severity: "error",
|
|
336
|
+
bundle: candidate.bundle,
|
|
337
|
+
path: candidate.path,
|
|
338
|
+
}),
|
|
339
|
+
);
|
|
340
|
+
});
|
|
341
|
+
});
|
|
342
|
+
const diagnostics = validation.diagnostics.concat(candidateDiagnostics);
|
|
343
|
+
return {
|
|
344
|
+
valid: validation.valid && candidateDiagnostics.length === 0,
|
|
345
|
+
conformant: validation.conformant,
|
|
346
|
+
validForProject: validation.validForProject && candidateDiagnostics.length === 0,
|
|
347
|
+
diagnostics,
|
|
348
|
+
errors: validation.errors,
|
|
349
|
+
warnings: validation.warnings,
|
|
350
|
+
};
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
defaultMessage(candidates) {
|
|
354
|
+
if (candidates.length === 1) {
|
|
355
|
+
return `docs(okf): ${candidates[0].op === "create" ? "add" : "update"} ${candidates[0].title}`;
|
|
356
|
+
}
|
|
357
|
+
return `docs(okf): apply ${candidates.length} concept changes`;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
commitMessage(input, candidates) {
|
|
361
|
+
if (hasOwn(input, "message") && typeof input.message !== "string") {
|
|
362
|
+
throw new AuthoringPolicyError("Git commit message must be a string.");
|
|
363
|
+
}
|
|
364
|
+
const supplied = hasOwn(input, "message") ? input.message.trim() : "";
|
|
365
|
+
const message = supplied || this.defaultMessage(candidates);
|
|
366
|
+
if (message.includes("\0")) {
|
|
367
|
+
throw new AuthoringPolicyError("Git commit message cannot contain NUL characters.");
|
|
368
|
+
}
|
|
369
|
+
if (byteLength(message) > MAX_COMMIT_MESSAGE_BYTES) {
|
|
370
|
+
throw new AuthoringPolicyError(
|
|
371
|
+
`Git commit message must not exceed ${MAX_COMMIT_MESSAGE_BYTES} UTF-8 bytes.`,
|
|
372
|
+
);
|
|
373
|
+
}
|
|
374
|
+
return message;
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
// The staged publication steps stay overridable methods: tests subclass the
|
|
378
|
+
// service and hook them to inject races between staging and publication.
|
|
379
|
+
stageCandidates(candidates) {
|
|
380
|
+
return stageCandidates(this.store, candidates);
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
assertRevisions(staged) {
|
|
384
|
+
return assertRevisions(staged);
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
rollback(applied, staged, createdDirectories) {
|
|
388
|
+
return rollback(applied, staged, createdDirectories);
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
generatedStamp() {
|
|
392
|
+
const timestampValue = this.now();
|
|
393
|
+
return {
|
|
394
|
+
by: this.actor,
|
|
395
|
+
at:
|
|
396
|
+
timestampValue instanceof Date
|
|
397
|
+
? timestampValue.toISOString()
|
|
398
|
+
: new Date(timestampValue).toISOString(),
|
|
399
|
+
};
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
buildCandidates(changes, bundle, currentIndex, generated) {
|
|
403
|
+
return changes.map((change, index) => {
|
|
404
|
+
if (!isPlainObject(change)) {
|
|
405
|
+
throw new AuthoringPolicyError(`changes[${index}] must be an object.`);
|
|
406
|
+
}
|
|
407
|
+
try {
|
|
408
|
+
if (change.op === "create") {
|
|
409
|
+
return this.createCandidate(change, bundle, currentIndex, generated);
|
|
410
|
+
}
|
|
411
|
+
if (change.op === "update") {
|
|
412
|
+
return this.updateCandidate(change, bundle, currentIndex, generated);
|
|
413
|
+
}
|
|
414
|
+
throw new AuthoringPolicyError(`changes[${index}].op must be create or update.`);
|
|
415
|
+
} catch (error) {
|
|
416
|
+
if (error instanceof AuthoringPolicyError || error instanceof AuthoringOperationalError) {
|
|
417
|
+
throw error;
|
|
418
|
+
}
|
|
419
|
+
if (error?.code) throw error;
|
|
420
|
+
throw new AuthoringPolicyError(error?.message ? error.message : String(error));
|
|
421
|
+
}
|
|
422
|
+
});
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
planChanges(input, context) {
|
|
426
|
+
if (!isPlainObject(input)) {
|
|
427
|
+
throw new AuthoringPolicyError("okf_apply_changes requires an object argument.");
|
|
428
|
+
}
|
|
429
|
+
if (
|
|
430
|
+
!Array.isArray(input.changes) ||
|
|
431
|
+
input.changes.length < 1 ||
|
|
432
|
+
input.changes.length > MAX_CHANGES
|
|
433
|
+
) {
|
|
434
|
+
throw new AuthoringPolicyError(
|
|
435
|
+
`changes must contain from 1 through ${MAX_CHANGES} operations.`,
|
|
436
|
+
);
|
|
437
|
+
}
|
|
438
|
+
let bundle;
|
|
439
|
+
try {
|
|
440
|
+
bundle = this.getBundle(input.bundle);
|
|
441
|
+
} catch (error) {
|
|
442
|
+
if (error?.code) throw error;
|
|
443
|
+
throw new AuthoringPolicyError(error?.message ? error.message : String(error));
|
|
444
|
+
}
|
|
445
|
+
const generated = this.generatedStamp();
|
|
446
|
+
const additionalBundles =
|
|
447
|
+
context && Array.isArray(context.additionalBundles) ? context.additionalBundles : [];
|
|
448
|
+
let currentIndex = this.currentIndex(additionalBundles);
|
|
449
|
+
let candidates = null;
|
|
450
|
+
for (let attempt = 0; candidates === null; attempt += 1) {
|
|
451
|
+
try {
|
|
452
|
+
candidates = this.buildCandidates(input.changes, bundle, currentIndex, generated);
|
|
453
|
+
} catch (error) {
|
|
454
|
+
if (error?.code !== "concept_changed" || attempt > 0) throw error;
|
|
455
|
+
// The index missed an edit the refresh cannot see (same size and
|
|
456
|
+
// mtime): take that document from disk and plan again, once.
|
|
457
|
+
const { bundleId, relativePath } = error.details;
|
|
458
|
+
currentIndex = this.indexCache.update(currentIndex, {
|
|
459
|
+
upserts: [{ bundleId, relativePath }],
|
|
460
|
+
});
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
const policy = enforceWritePolicy(this.writePolicy, {
|
|
464
|
+
actor: this.actor,
|
|
465
|
+
candidates,
|
|
466
|
+
index: currentIndex,
|
|
467
|
+
});
|
|
468
|
+
const targetPaths = new Set();
|
|
469
|
+
candidates.forEach((candidate) => {
|
|
470
|
+
const key = path.resolve(candidate.target.absolutePath);
|
|
471
|
+
if (targetPaths.has(key)) {
|
|
472
|
+
throw new AuthoringPolicyError(
|
|
473
|
+
`A batch cannot target the same concept more than once: ${candidate.path}`,
|
|
474
|
+
);
|
|
475
|
+
}
|
|
476
|
+
targetPaths.add(key);
|
|
477
|
+
});
|
|
478
|
+
const absoluteTargets = Array.from(targetPaths);
|
|
479
|
+
for (let left = 0; left < absoluteTargets.length; left += 1) {
|
|
480
|
+
for (let right = left + 1; right < absoluteTargets.length; right += 1) {
|
|
481
|
+
if (
|
|
482
|
+
absoluteTargets[left].startsWith(`${absoluteTargets[right]}${path.sep}`) ||
|
|
483
|
+
absoluteTargets[right].startsWith(`${absoluteTargets[left]}${path.sep}`)
|
|
484
|
+
) {
|
|
485
|
+
throw new AuthoringPolicyError(
|
|
486
|
+
"A batch cannot place one concept path underneath another concept file path.",
|
|
487
|
+
);
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
const currentConcepts = currentIndex.concepts.filter((doc) => doc.bundle === bundle.id);
|
|
492
|
+
const replacedPaths = new Set(
|
|
493
|
+
candidates.filter((entry) => entry.op === "update").map((entry) => entry.path),
|
|
494
|
+
);
|
|
495
|
+
const finalConcepts = currentConcepts
|
|
496
|
+
.filter((doc) => !replacedPaths.has(doc.path))
|
|
497
|
+
.concat(candidates);
|
|
498
|
+
for (const candidate of candidates) {
|
|
499
|
+
const key = semanticConceptKey(candidate.frontmatter.type, candidate.title);
|
|
500
|
+
const before = currentConcepts.filter(
|
|
501
|
+
(doc) => semanticConceptKey(doc.type, doc.title) === key,
|
|
502
|
+
);
|
|
503
|
+
const after = finalConcepts.filter(
|
|
504
|
+
(doc) => semanticConceptKey(doc.type || doc.frontmatter.type, doc.title) === key,
|
|
505
|
+
);
|
|
506
|
+
if (after.length <= Math.max(1, before.length)) continue;
|
|
507
|
+
const existing = after.filter((doc) => !candidates.includes(doc));
|
|
508
|
+
const details =
|
|
509
|
+
candidate.op === "create" && existing.length === 1 && after.length === 2
|
|
510
|
+
? conceptConflictDetails(existing, this.store.project)
|
|
511
|
+
: {
|
|
512
|
+
reason: before.length ? "same_type_title" : "same_batch_type_title",
|
|
513
|
+
candidates: after.slice(0, 5).map((doc) => conceptMatchSummary(doc)),
|
|
514
|
+
omitted: Math.max(0, after.length - 5),
|
|
515
|
+
recommendedOperation: "merge_batch_changes",
|
|
516
|
+
};
|
|
517
|
+
throw new AuthoringPolicyError(
|
|
518
|
+
`The batch would leave more than one concept with the same type and title: ${candidate.uri}`,
|
|
519
|
+
"concept_already_exists",
|
|
520
|
+
details,
|
|
521
|
+
);
|
|
522
|
+
}
|
|
523
|
+
const message = this.commitMessage(input, candidates);
|
|
524
|
+
const validation = withPolicyViolations(
|
|
525
|
+
this.validationResult(
|
|
526
|
+
updateIndex(
|
|
527
|
+
currentIndex,
|
|
528
|
+
{ upserts: candidates.map((candidate) => candidateUpsert(candidate, false)) },
|
|
529
|
+
this.indexCache.options(),
|
|
530
|
+
),
|
|
531
|
+
candidates,
|
|
532
|
+
),
|
|
533
|
+
policy,
|
|
534
|
+
);
|
|
535
|
+
const gitPreflight = this.git.prepareGit(bundle, candidates);
|
|
536
|
+
return {
|
|
537
|
+
input,
|
|
538
|
+
bundle,
|
|
539
|
+
generated,
|
|
540
|
+
additionalBundles,
|
|
541
|
+
currentIndex,
|
|
542
|
+
candidates,
|
|
543
|
+
message,
|
|
544
|
+
validation,
|
|
545
|
+
policy,
|
|
546
|
+
gitPreflight,
|
|
547
|
+
target: targetReceipt(this.store, bundle, candidates, gitPreflight),
|
|
548
|
+
changes: candidateSummaries(candidates),
|
|
549
|
+
};
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
invalidValidationReceipt(error) {
|
|
553
|
+
const validation = policyValidation(error);
|
|
554
|
+
const generated = this.generatedStamp();
|
|
555
|
+
return {
|
|
556
|
+
valid: false,
|
|
557
|
+
readyToApply: false,
|
|
558
|
+
applied: false,
|
|
559
|
+
filesChanged: false,
|
|
560
|
+
status: "invalid",
|
|
561
|
+
snapshot: {
|
|
562
|
+
checkedAt: generated.at,
|
|
563
|
+
timeOfCheck: true,
|
|
564
|
+
generatedBy: generated.by,
|
|
565
|
+
graphValidation: "not_run",
|
|
566
|
+
},
|
|
567
|
+
preconditions: {
|
|
568
|
+
allSatisfied: false,
|
|
569
|
+
revisions: [],
|
|
570
|
+
git: {
|
|
571
|
+
enabled: this.gitCommit,
|
|
572
|
+
ready: false,
|
|
573
|
+
repositoryStatus: "not_inspected",
|
|
574
|
+
repositoryRoot: null,
|
|
575
|
+
diagnostics: [],
|
|
576
|
+
},
|
|
577
|
+
},
|
|
578
|
+
generated,
|
|
579
|
+
durability: durabilityReceipt(null, false),
|
|
580
|
+
changes: [],
|
|
581
|
+
validation,
|
|
582
|
+
...(error?.code ? { code: error.code } : {}),
|
|
583
|
+
...(error && error.details !== undefined ? { details: error.details } : {}),
|
|
584
|
+
git: {
|
|
585
|
+
enabled: this.gitCommit,
|
|
586
|
+
repository: false,
|
|
587
|
+
repositoryRoot: null,
|
|
588
|
+
repositoryStatus: "not_inspected",
|
|
589
|
+
commitState: "not_attempted",
|
|
590
|
+
persistence: "none",
|
|
591
|
+
},
|
|
592
|
+
};
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
async validateChanges(input, context) {
|
|
596
|
+
return this.store.withWriteLock(() => {
|
|
597
|
+
this.publication = null;
|
|
598
|
+
try {
|
|
599
|
+
return validationReceipt(this.planChanges(input, context));
|
|
600
|
+
} catch (error) {
|
|
601
|
+
if (!(error instanceof AuthoringPolicyError)) {
|
|
602
|
+
throw error;
|
|
603
|
+
}
|
|
604
|
+
return this.invalidValidationReceipt(error);
|
|
605
|
+
}
|
|
606
|
+
});
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
async applyChanges(input, context) {
|
|
610
|
+
return this.store.withWriteLock(() => this.applyChangesUnlocked(input, context));
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
async applyChangesUnlocked(input, context) {
|
|
614
|
+
this.publication = null;
|
|
615
|
+
const plan = this.planChanges(input, context);
|
|
616
|
+
if (!plan.validation.valid) {
|
|
617
|
+
return {
|
|
618
|
+
applied: false,
|
|
619
|
+
readyToApply: false,
|
|
620
|
+
filesChanged: false,
|
|
621
|
+
status: "rejected",
|
|
622
|
+
snapshot: snapshotReceipt(plan),
|
|
623
|
+
preconditions: preconditionsReceipt(plan),
|
|
624
|
+
generated: plan.generated,
|
|
625
|
+
target: plan.target,
|
|
626
|
+
durability: durabilityReceipt(null, false),
|
|
627
|
+
changes: plan.changes,
|
|
628
|
+
validation: plan.validation,
|
|
629
|
+
...policyReceipt(plan),
|
|
630
|
+
git: {
|
|
631
|
+
enabled: plan.gitPreflight.enabled,
|
|
632
|
+
repository: Boolean(plan.gitPreflight.repository),
|
|
633
|
+
repositoryRoot: plan.gitPreflight.repositoryRoot,
|
|
634
|
+
repositoryStatus: plan.gitPreflight.repositoryStatus,
|
|
635
|
+
commitState: "not_attempted",
|
|
636
|
+
persistence: "none",
|
|
637
|
+
},
|
|
638
|
+
};
|
|
639
|
+
}
|
|
640
|
+
if (!plan.gitPreflight.ready) {
|
|
641
|
+
const blocker = plan.gitPreflight.diagnostics[0];
|
|
642
|
+
throw new AuthoringPolicyError(
|
|
643
|
+
blocker
|
|
644
|
+
? blocker.message
|
|
645
|
+
: "Configured Git preconditions do not currently allow automatic apply.",
|
|
646
|
+
);
|
|
647
|
+
}
|
|
648
|
+
const transaction = this.stageCandidates(plan.candidates);
|
|
649
|
+
const staged = transaction.staged;
|
|
650
|
+
const applied = [];
|
|
651
|
+
try {
|
|
652
|
+
this.assertRevisions(staged);
|
|
653
|
+
staged.forEach((candidate) => {
|
|
654
|
+
if (candidate.op === "create") {
|
|
655
|
+
fs.linkSync(candidate.temporary, candidate.target.absolutePath);
|
|
656
|
+
applied.push(candidate);
|
|
657
|
+
fs.unlinkSync(candidate.temporary);
|
|
658
|
+
} else {
|
|
659
|
+
const currentRevision = revisionFor(fs.readFileSync(candidate.target.absolutePath));
|
|
660
|
+
if (currentRevision !== candidate.baseRevision) {
|
|
661
|
+
throw new Error(`Concept changed immediately before publication: ${candidate.path}`);
|
|
662
|
+
}
|
|
663
|
+
fs.renameSync(candidate.temporary, candidate.target.absolutePath);
|
|
664
|
+
applied.push(candidate);
|
|
665
|
+
}
|
|
666
|
+
});
|
|
667
|
+
} catch (error) {
|
|
668
|
+
const rollback = this.rollback(applied, staged, transaction.createdDirectories);
|
|
669
|
+
if (!rollback.complete) {
|
|
670
|
+
this.forgetIndex();
|
|
671
|
+
return rollbackReceipt(plan, rollback, error);
|
|
672
|
+
}
|
|
673
|
+
throw error;
|
|
674
|
+
}
|
|
675
|
+
let persistedValidation;
|
|
676
|
+
let persistedIndex;
|
|
677
|
+
try {
|
|
678
|
+
// Validate the bytes that landed on disk, read back from the targets,
|
|
679
|
+
// applied to the index the batch was planned against after a refresh,
|
|
680
|
+
// so a dependency that changed or vanished since planning counts too.
|
|
681
|
+
persistedIndex = updateIndex(
|
|
682
|
+
refreshIndex(plan.currentIndex, this.indexCache.options()),
|
|
683
|
+
{ upserts: plan.candidates.map((candidate) => candidateUpsert(candidate, true)) },
|
|
684
|
+
this.indexCache.options(),
|
|
685
|
+
);
|
|
686
|
+
persistedValidation = this.validationResult(persistedIndex, plan.candidates);
|
|
687
|
+
} catch (error) {
|
|
688
|
+
const rollback = this.rollback(applied, staged, transaction.createdDirectories);
|
|
689
|
+
if (!rollback.complete) {
|
|
690
|
+
this.forgetIndex();
|
|
691
|
+
return rollbackReceipt(plan, rollback, error);
|
|
692
|
+
}
|
|
693
|
+
throw error;
|
|
694
|
+
}
|
|
695
|
+
if (!persistedValidation.valid) {
|
|
696
|
+
const rollback = this.rollback(applied, staged, transaction.createdDirectories);
|
|
697
|
+
if (!rollback.complete) {
|
|
698
|
+
this.forgetIndex();
|
|
699
|
+
}
|
|
700
|
+
return Object.assign(rollbackReceipt(plan, rollback, null), {
|
|
701
|
+
validation: persistedValidation,
|
|
702
|
+
});
|
|
703
|
+
}
|
|
704
|
+
let git;
|
|
705
|
+
try {
|
|
706
|
+
git = this.git.commitGit(plan.gitPreflight, plan.candidates, plan.message);
|
|
707
|
+
} catch (error) {
|
|
708
|
+
git = {
|
|
709
|
+
enabled: plan.gitPreflight.enabled,
|
|
710
|
+
repository: Boolean(plan.gitPreflight.repository),
|
|
711
|
+
repositoryRoot: plan.gitPreflight.repositoryRoot,
|
|
712
|
+
committed: null,
|
|
713
|
+
commitState: "unknown",
|
|
714
|
+
persistence: "unknown",
|
|
715
|
+
error: error?.message ? error.message : String(error),
|
|
716
|
+
};
|
|
717
|
+
}
|
|
718
|
+
if (git.targetState === "conflict") {
|
|
719
|
+
// The worktree diverged from what was validated; nothing the service
|
|
720
|
+
// holds describes the files now, so re-read everything and let the host
|
|
721
|
+
// rebuild its own index.
|
|
722
|
+
this.forgetIndex();
|
|
723
|
+
let currentValidation = persistedValidation;
|
|
724
|
+
try {
|
|
725
|
+
currentValidation = this.validationResult(this.buildIndex(plan.additionalBundles), []);
|
|
726
|
+
} catch {
|
|
727
|
+
// Preserve the last complete validation receipt when the conflicting state is unreadable.
|
|
728
|
+
}
|
|
729
|
+
if (git.committed !== true) {
|
|
730
|
+
return {
|
|
731
|
+
applied: false,
|
|
732
|
+
readyToApply: false,
|
|
733
|
+
filesChanged: true,
|
|
734
|
+
status: "post_publication_conflict",
|
|
735
|
+
snapshot: snapshotReceipt(plan),
|
|
736
|
+
preconditions: preconditionsReceipt(plan),
|
|
737
|
+
generated: plan.generated,
|
|
738
|
+
target: plan.target,
|
|
739
|
+
durability: durabilityReceipt(git, true, "partial_filesystem_state"),
|
|
740
|
+
changes: plan.changes,
|
|
741
|
+
validation: currentValidation,
|
|
742
|
+
...policyReceipt(plan),
|
|
743
|
+
git,
|
|
744
|
+
error:
|
|
745
|
+
git.error || "Validated concept bytes were replaced before Git persistence completed.",
|
|
746
|
+
};
|
|
747
|
+
}
|
|
748
|
+
persistedValidation = currentValidation;
|
|
749
|
+
} else {
|
|
750
|
+
const shared = this.indexCache.index === plan.currentIndex;
|
|
751
|
+
this.indexCache.replace(plan.currentIndex, persistedIndex);
|
|
752
|
+
this.publication = {
|
|
753
|
+
index: persistedIndex,
|
|
754
|
+
hostOwned: Boolean(shared && this.indexCache.hostOwned),
|
|
755
|
+
changes: { upserts: plan.candidates.map((candidate) => candidateUpsert(candidate, true)) },
|
|
756
|
+
};
|
|
757
|
+
}
|
|
758
|
+
const status =
|
|
759
|
+
git.commitState === "unknown"
|
|
760
|
+
? "applied_commit_unknown"
|
|
761
|
+
: git.committed === true && git.targetState === "conflict"
|
|
762
|
+
? "applied_worktree_diverged"
|
|
763
|
+
: git.enabled && git.repository && !git.committed
|
|
764
|
+
? "applied_uncommitted"
|
|
765
|
+
: "applied";
|
|
766
|
+
return {
|
|
767
|
+
applied: true,
|
|
768
|
+
readyToApply: git.targetState !== "conflict",
|
|
769
|
+
filesChanged: true,
|
|
770
|
+
status,
|
|
771
|
+
snapshot: snapshotReceipt(plan),
|
|
772
|
+
preconditions: preconditionsReceipt(plan),
|
|
773
|
+
generated: plan.generated,
|
|
774
|
+
target: plan.target,
|
|
775
|
+
durability: durabilityReceipt(git, true),
|
|
776
|
+
changes: plan.changes,
|
|
777
|
+
validation: persistedValidation,
|
|
778
|
+
...policyReceipt(plan),
|
|
779
|
+
git,
|
|
780
|
+
};
|
|
781
|
+
}
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
module.exports = {
|
|
785
|
+
LiveAuthoringService,
|
|
786
|
+
MAX_CHANGES,
|
|
787
|
+
MAX_COMMIT_MESSAGE_BYTES,
|
|
788
|
+
MANAGED_METADATA_KEYS,
|
|
789
|
+
};
|