@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.
- package/CHANGELOG.md +100 -0
- package/README.md +452 -26
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
- package/okf/okf-mcp/index.md +2 -1
- package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
- package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
- package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
- package/okf/okf-mcp/overview/okf-mcp.md +16 -6
- package/okf/okf-mcp/policies/authoring-safety.md +28 -5
- package/okf/okf-mcp/runtime/indexer.md +14 -1
- package/okf/okf-mcp/runtime/mcp-server.md +16 -8
- package/okf/okf-mcp/specs/producer-api.md +16 -2
- package/package.json +17 -5
- package/server.json +38 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +434 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +783 -0
- package/src/authoring/live.js +757 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +159 -0
- package/src/authoring/receipts.js +373 -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/commands.js +448 -0
- package/src/cli/http-options.js +193 -0
- package/src/cli/options.js +554 -0
- package/src/cli/usage.js +96 -0
- package/src/cli.js +18 -932
- 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/error-details.js +53 -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/auth.js +409 -0
- package/src/mcp/http.js +317 -0
- package/src/mcp/principal.js +59 -0
- package/src/mcp/registry.js +356 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +567 -0
- package/src/mcp/tools/catalog.js +247 -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 +225 -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 +202 -78
- package/src/producers.js +311 -103
- package/src/project.js +346 -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/tool-packs.js +346 -0
- package/src/v02.js +301 -105
- package/src/validation.js +24 -20
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
// Catalog text is data, never instructions (plan B-6, S-3). Diagnostic and
|
|
4
|
+
// error messages never echo vocabulary a concept used but nobody declared
|
|
5
|
+
// (an undeclared relation type, a repeated computation parameter name): any
|
|
6
|
+
// such value, however identifier-like, could carry text meant for an agent.
|
|
7
|
+
// The messages are constant apart from the concept path and an ordinal, so
|
|
8
|
+
// an operator can find the entry; the value itself stays in the structured
|
|
9
|
+
// fields beside the message (relationType, field).
|
|
10
|
+
|
|
11
|
+
function undeclaredRelationTypeMessage(conceptPath, position) {
|
|
12
|
+
return `Relation #${position + 1} of ${conceptPath} uses an undeclared type.`;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function repeatedParameterMessage(conceptPath, position) {
|
|
16
|
+
return `Computation parameter #${position + 1} of ${conceptPath || "this concept"} repeats an earlier name.`;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
module.exports = { repeatedParameterMessage, undeclaredRelationTypeMessage };
|
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
// Command handlers of the okf / okf-mcp binary, one function per command,
|
|
4
|
+
// dispatched by runCommand after src/cli.js has parsed the arguments and
|
|
5
|
+
// discovered the project. Split out of src/cli.js (Q-1).
|
|
6
|
+
|
|
7
|
+
const {
|
|
8
|
+
attachProject,
|
|
9
|
+
buildIndex,
|
|
10
|
+
conceptSummary,
|
|
11
|
+
loadProjectBundles,
|
|
12
|
+
resolveConcept,
|
|
13
|
+
validateIndex,
|
|
14
|
+
} = require("../indexer");
|
|
15
|
+
const { exportGraph, findPaths, getNeighbors, graphSummary } = require("../graph");
|
|
16
|
+
const { searchConcepts } = require("../search");
|
|
17
|
+
const { loadProjectConfig } = require("../project");
|
|
18
|
+
const { withSearchLanguages } = require("../search/cli-options");
|
|
19
|
+
const contextCli = require("../context/cli-options");
|
|
20
|
+
const { generateProject } = require("../plugins");
|
|
21
|
+
const { ProducerService, producerReceipt } = require("../producers");
|
|
22
|
+
const { FileConceptStore } = require("../store");
|
|
23
|
+
const { runStdioServer } = require("../mcp-server");
|
|
24
|
+
const { runMcpHttpServer } = require("../mcp/http");
|
|
25
|
+
const { fetchRemoteBundles } = require("../remote");
|
|
26
|
+
const { runHttpServer } = require("../http-server");
|
|
27
|
+
const {
|
|
28
|
+
checkComputationReceipt,
|
|
29
|
+
getProvenance,
|
|
30
|
+
inspectAttestedComputation,
|
|
31
|
+
prepareAttestedComputation,
|
|
32
|
+
readBundleAsset,
|
|
33
|
+
} = require("../computation");
|
|
34
|
+
const { buildV02MigrationPlan, checkV02Migration } = require("../migration");
|
|
35
|
+
const { describeConceptGitSources, readConceptGitSource } = require("../git-source");
|
|
36
|
+
const { httpServerOptions } = require("./http-options");
|
|
37
|
+
const {
|
|
38
|
+
COMMANDS,
|
|
39
|
+
PRODUCER_ACTIONS,
|
|
40
|
+
WRITE_COMMANDS,
|
|
41
|
+
parseJsonObject,
|
|
42
|
+
parseRemoteBundleArg,
|
|
43
|
+
parseRepositoryMappings,
|
|
44
|
+
readJsonObjectSource,
|
|
45
|
+
resolveLegacyBundles,
|
|
46
|
+
stdioServerOptions,
|
|
47
|
+
usageError,
|
|
48
|
+
writePolicyOption,
|
|
49
|
+
} = require("./options");
|
|
50
|
+
|
|
51
|
+
async function loadIndex(args) {
|
|
52
|
+
const remoteConfigs = args.remoteBundles.map(parseRemoteBundleArg);
|
|
53
|
+
if (args.project) {
|
|
54
|
+
const loaded = await loadProjectBundles(args.project);
|
|
55
|
+
const remoteBundles = await fetchRemoteBundles(remoteConfigs);
|
|
56
|
+
const index = buildIndex(loaded.bundles.concat(remoteBundles), {
|
|
57
|
+
relationTypes: loaded.project.relationTypes,
|
|
58
|
+
strictLinks: args.strictLinks || loaded.project.strictLinks,
|
|
59
|
+
});
|
|
60
|
+
return withSearchLanguages(
|
|
61
|
+
attachProject(index, loaded.project),
|
|
62
|
+
args.languages || loaded.project.languages,
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
const bundles = resolveLegacyBundles(args);
|
|
66
|
+
const fetchedRemoteBundles = await fetchRemoteBundles(remoteConfigs);
|
|
67
|
+
if (!bundles.length && !fetchedRemoteBundles.length) {
|
|
68
|
+
throw usageError("At least one --bundle root or --project config is required.");
|
|
69
|
+
}
|
|
70
|
+
return withSearchLanguages(
|
|
71
|
+
buildIndex(bundles.concat(fetchedRemoteBundles), {
|
|
72
|
+
strictLinks: args.strictLinks,
|
|
73
|
+
allowCustomRelationTypes: true,
|
|
74
|
+
}),
|
|
75
|
+
args.languages,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function printJson(value) {
|
|
80
|
+
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function requireValidConcept(index, locator) {
|
|
84
|
+
const doc = resolveConcept(index, locator);
|
|
85
|
+
if (!doc) {
|
|
86
|
+
throw new Error(`Unknown OKF concept URI or ID: ${locator || "<missing>"}`);
|
|
87
|
+
}
|
|
88
|
+
if (!doc.valid || doc.reserved) {
|
|
89
|
+
throw new Error(`Locator is not a valid OKF concept: ${locator}`);
|
|
90
|
+
}
|
|
91
|
+
return doc;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async function runMcp(args, runtime) {
|
|
95
|
+
const bundles = resolveLegacyBundles(args);
|
|
96
|
+
const http = httpServerOptions(args, usageError);
|
|
97
|
+
if (http) {
|
|
98
|
+
if (!args.project && !bundles.length && !args.remoteBundles.length) {
|
|
99
|
+
throw usageError("An OKF --root, --bundle, or --project source is required.");
|
|
100
|
+
}
|
|
101
|
+
const started = await (runtime?.runMcpHttpServer || runMcpHttpServer)(
|
|
102
|
+
args.project ? [] : bundles,
|
|
103
|
+
Object.assign(stdioServerOptions(args), { http }),
|
|
104
|
+
);
|
|
105
|
+
process.stderr.write(`OKF MCP HTTP server listening on ${started.url}\n`);
|
|
106
|
+
return;
|
|
107
|
+
}
|
|
108
|
+
if (args.project) {
|
|
109
|
+
await (runtime?.runStdioServer || runStdioServer)(
|
|
110
|
+
[],
|
|
111
|
+
process.stdin,
|
|
112
|
+
process.stdout,
|
|
113
|
+
stdioServerOptions(args),
|
|
114
|
+
);
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
if (!bundles.length && !args.remoteBundles.length) {
|
|
118
|
+
throw usageError("An OKF --root, --bundle, or --project source is required.");
|
|
119
|
+
}
|
|
120
|
+
await (runtime?.runStdioServer || runStdioServer)(
|
|
121
|
+
bundles,
|
|
122
|
+
process.stdin,
|
|
123
|
+
process.stdout,
|
|
124
|
+
stdioServerOptions(args),
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
async function runServe(args, runtime) {
|
|
129
|
+
if (!args.project && !args.root) {
|
|
130
|
+
throw usageError("serve requires --root or --project.");
|
|
131
|
+
}
|
|
132
|
+
const result = await (runtime?.runHttpServer || runHttpServer)({
|
|
133
|
+
projectPath: args.project,
|
|
134
|
+
rootPath: args.root,
|
|
135
|
+
host: args.host,
|
|
136
|
+
port: args.port,
|
|
137
|
+
writeToken: args.writeToken || process.env.OKF_WRITE_TOKEN || "",
|
|
138
|
+
proposalRoot: args.proposalRoot || "",
|
|
139
|
+
writePolicy: writePolicyOption(args),
|
|
140
|
+
});
|
|
141
|
+
process.stderr.write(`OKF HTTP server listening on ${result.url}\n`);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function runGenerate(args) {
|
|
145
|
+
if (!args.project) {
|
|
146
|
+
throw usageError("generate requires --project.");
|
|
147
|
+
}
|
|
148
|
+
const project = loadProjectConfig(args.project);
|
|
149
|
+
printJson(generateProject(project));
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
async function runProducer(args) {
|
|
153
|
+
if (!args.project) {
|
|
154
|
+
throw usageError("producer requires --project.");
|
|
155
|
+
}
|
|
156
|
+
const action = args.positional[1] || "list";
|
|
157
|
+
if (!PRODUCER_ACTIONS.has(action)) {
|
|
158
|
+
throw usageError("producer action must be list, preview, or run.");
|
|
159
|
+
}
|
|
160
|
+
const loaded = await loadProjectBundles(args.project);
|
|
161
|
+
const service = new ProducerService({
|
|
162
|
+
project: loaded.project,
|
|
163
|
+
store: FileConceptStore.fromProject(args.project, { proposalRoot: args.proposalRoot || "" }),
|
|
164
|
+
bundles: (loaded.bundles || []).filter((bundle) => !bundle.remote),
|
|
165
|
+
});
|
|
166
|
+
if (action === "list") {
|
|
167
|
+
printJson(service.list());
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
const name = args.positional[2];
|
|
171
|
+
if (!name) {
|
|
172
|
+
throw usageError(`producer ${action} requires a configured producer name.`);
|
|
173
|
+
}
|
|
174
|
+
if (action === "run" && !args.write) {
|
|
175
|
+
throw usageError("producer run requires --write --actor <human:id|process:id|provider/model>.");
|
|
176
|
+
}
|
|
177
|
+
const receipt = action === "run" ? await service.run(name) : await service.preview(name);
|
|
178
|
+
printJson(producerReceipt(receipt, "full"));
|
|
179
|
+
const succeeded = action === "run" ? receipt.applied === true : receipt.valid === true;
|
|
180
|
+
process.exitCode = succeeded ? 0 : 1;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
function runValidate(index) {
|
|
184
|
+
const result = validateIndex(index);
|
|
185
|
+
printJson(result);
|
|
186
|
+
process.exitCode = result.validForProject ? 0 : 1;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
function runGraph(index, args) {
|
|
190
|
+
process.stdout.write(
|
|
191
|
+
`${exportGraph(index, {
|
|
192
|
+
format: args.positional[1] || "json",
|
|
193
|
+
includeExternal: args.includeExternal,
|
|
194
|
+
includeAssets: args.includeAssets,
|
|
195
|
+
})}\n`,
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function runSearch(index, args) {
|
|
200
|
+
const filters = Object.assign({}, args.search, { query: args.positional.slice(1).join(" ") });
|
|
201
|
+
if (!Object.keys(filters.frontmatter || {}).length) {
|
|
202
|
+
delete filters.frontmatter;
|
|
203
|
+
}
|
|
204
|
+
printJson(searchConcepts(index, filters));
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
function runContext(index, args) {
|
|
208
|
+
printJson(contextCli.runContext(index, args, usageError));
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function runConcept(index, args, { repositoryMappings }) {
|
|
212
|
+
const locator = args.positional[1];
|
|
213
|
+
if (!locator) {
|
|
214
|
+
throw usageError("concept requires a Concept ID or locator.");
|
|
215
|
+
}
|
|
216
|
+
const doc = requireValidConcept(index, locator);
|
|
217
|
+
printJson(
|
|
218
|
+
Object.assign(conceptSummary(doc), {
|
|
219
|
+
frontmatter: doc.frontmatter,
|
|
220
|
+
body: doc.body,
|
|
221
|
+
links: doc.links,
|
|
222
|
+
referencedAssets: (index.assets || [])
|
|
223
|
+
.filter((asset) =>
|
|
224
|
+
(asset.referencedBy || []).some((reference) => reference.uri === doc.uri),
|
|
225
|
+
)
|
|
226
|
+
.map((asset) => ({
|
|
227
|
+
uri: asset.uri,
|
|
228
|
+
path: asset.path,
|
|
229
|
+
mimeType: asset.mimeType,
|
|
230
|
+
size: asset.size,
|
|
231
|
+
sha256: asset.sha256,
|
|
232
|
+
roles: asset.roles,
|
|
233
|
+
})),
|
|
234
|
+
gitSources: describeConceptGitSources(index, doc, repositoryMappings),
|
|
235
|
+
}),
|
|
236
|
+
);
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
function runNeighbors(index, args) {
|
|
240
|
+
if (!args.positional[1]) {
|
|
241
|
+
throw usageError("neighbors requires a URI.");
|
|
242
|
+
}
|
|
243
|
+
const doc = requireValidConcept(index, args.positional[1]);
|
|
244
|
+
printJson(
|
|
245
|
+
getNeighbors(index, doc.uri, {
|
|
246
|
+
includeAssets: args.includeAssets,
|
|
247
|
+
includeExternal: args.includeExternal,
|
|
248
|
+
}),
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function runPaths(index, args) {
|
|
253
|
+
if (!args.positional[1] || !args.positional[2]) {
|
|
254
|
+
throw usageError("paths requires <from> and <to> URIs.");
|
|
255
|
+
}
|
|
256
|
+
const source = requireValidConcept(index, args.positional[1]);
|
|
257
|
+
const target = requireValidConcept(index, args.positional[2]);
|
|
258
|
+
printJson(findPaths(index, source.uri, target.uri));
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
function runProvenance(index, args) {
|
|
262
|
+
if (!args.positional[1]) {
|
|
263
|
+
throw usageError("provenance requires a URI.");
|
|
264
|
+
}
|
|
265
|
+
printJson(getProvenance(index, args.positional[1], { includeExternal: args.includeExternal }));
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
function runEdgeKinds(index) {
|
|
269
|
+
const counts = {};
|
|
270
|
+
index.edges.forEach((edge) => {
|
|
271
|
+
if (!counts[edge.kind]) {
|
|
272
|
+
counts[edge.kind] = { total: 0, resolved: 0, broken: 0 };
|
|
273
|
+
}
|
|
274
|
+
counts[edge.kind].total += 1;
|
|
275
|
+
counts[edge.kind][edge.broken ? "broken" : "resolved"] += 1;
|
|
276
|
+
});
|
|
277
|
+
printJson(counts);
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
function runComputation(index, args, { runtime }) {
|
|
281
|
+
const operation = args.positional[1];
|
|
282
|
+
const uri = args.positional[2];
|
|
283
|
+
if (!operation || !uri) {
|
|
284
|
+
throw usageError("computation requires inspect|prepare|check-receipt and a URI.");
|
|
285
|
+
}
|
|
286
|
+
if (operation === "inspect") {
|
|
287
|
+
printJson(inspectAttestedComputation(index, uri, { asOf: args.search.asOf }));
|
|
288
|
+
return;
|
|
289
|
+
}
|
|
290
|
+
if (operation === "prepare") {
|
|
291
|
+
if (args.positional[3]) {
|
|
292
|
+
throw usageError(
|
|
293
|
+
"Raw computation parameters are not accepted in argv; use --parameters-file <path|->.",
|
|
294
|
+
);
|
|
295
|
+
}
|
|
296
|
+
const parameters = args.parametersFile
|
|
297
|
+
? readJsonObjectSource(args.parametersFile, "computation parameters", runtime)
|
|
298
|
+
: null;
|
|
299
|
+
if (!parameters) {
|
|
300
|
+
throw usageError("computation prepare requires --parameters-file <path|->.");
|
|
301
|
+
}
|
|
302
|
+
printJson(prepareAttestedComputation(index, uri, parameters, { asOf: args.search.asOf }));
|
|
303
|
+
return;
|
|
304
|
+
}
|
|
305
|
+
if (operation === "check-receipt") {
|
|
306
|
+
if (args.positional[3]) {
|
|
307
|
+
throw usageError(
|
|
308
|
+
"Raw computation receipts are not accepted in argv; use --receipt-file <path|->.",
|
|
309
|
+
);
|
|
310
|
+
}
|
|
311
|
+
const receipt = args.receiptFile
|
|
312
|
+
? readJsonObjectSource(args.receiptFile, "computation receipt", runtime)
|
|
313
|
+
: null;
|
|
314
|
+
if (!receipt) {
|
|
315
|
+
throw usageError("computation check-receipt requires --receipt-file <path|->.");
|
|
316
|
+
}
|
|
317
|
+
printJson(checkComputationReceipt(index, uri, receipt));
|
|
318
|
+
return;
|
|
319
|
+
}
|
|
320
|
+
throw usageError(`Unknown computation operation: ${operation}`);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function runAsset(index, args) {
|
|
324
|
+
if (!args.positional[1]) {
|
|
325
|
+
throw usageError("asset requires an okf-asset URI.");
|
|
326
|
+
}
|
|
327
|
+
printJson(
|
|
328
|
+
readBundleAsset(index, {
|
|
329
|
+
uri: args.positional[1],
|
|
330
|
+
maxContentBytes: args.maxContentBytes,
|
|
331
|
+
}),
|
|
332
|
+
);
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
function runSource(index, args, { repositoryMappings }) {
|
|
336
|
+
if (!args.positional[1] || !args.positional[2]) {
|
|
337
|
+
throw usageError("source requires <concept-id-or-locator> and <source-id>.");
|
|
338
|
+
}
|
|
339
|
+
printJson(
|
|
340
|
+
readConceptGitSource(index, args.positional[1], args.positional[2], repositoryMappings, {
|
|
341
|
+
maxBytes: args.maxContentBytes,
|
|
342
|
+
}),
|
|
343
|
+
);
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
function runMigrate(index, args) {
|
|
347
|
+
const operation = args.positional[1];
|
|
348
|
+
if (!["check", "preview"].includes(operation)) {
|
|
349
|
+
throw usageError("migrate requires check or preview.");
|
|
350
|
+
}
|
|
351
|
+
let bundleArgument = args.positional[2] || "";
|
|
352
|
+
let actorMappingsArgument = args.positional[3] || "";
|
|
353
|
+
if (
|
|
354
|
+
operation === "preview" &&
|
|
355
|
+
index.bundles.length === 1 &&
|
|
356
|
+
!actorMappingsArgument &&
|
|
357
|
+
bundleArgument.trim().startsWith("{")
|
|
358
|
+
) {
|
|
359
|
+
actorMappingsArgument = bundleArgument;
|
|
360
|
+
bundleArgument = "";
|
|
361
|
+
}
|
|
362
|
+
const bundle = bundleArgument || (index.bundles.length === 1 ? index.bundles[0].id : "");
|
|
363
|
+
if (!bundle) {
|
|
364
|
+
throw usageError("migrate requires a bundle id when multiple bundles are loaded.");
|
|
365
|
+
}
|
|
366
|
+
if (!index.bundles.some((entry) => entry.id === bundle)) {
|
|
367
|
+
throw usageError(`Unknown bundle id: ${bundle}`);
|
|
368
|
+
}
|
|
369
|
+
const actorMappings = actorMappingsArgument
|
|
370
|
+
? parseJsonObject(actorMappingsArgument, "actor mappings")
|
|
371
|
+
: {};
|
|
372
|
+
const result =
|
|
373
|
+
operation === "check"
|
|
374
|
+
? checkV02Migration(index, { bundle, actorMappings, generatedPaths: args.generatedPaths })
|
|
375
|
+
: buildV02MigrationPlan(index, {
|
|
376
|
+
bundle,
|
|
377
|
+
actorMappings,
|
|
378
|
+
generatedPaths: args.generatedPaths,
|
|
379
|
+
});
|
|
380
|
+
printJson(result);
|
|
381
|
+
const report = operation === "check" ? result : result.report;
|
|
382
|
+
process.exitCode = report.blockers.length ? 1 : 0;
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
// Commands that start a server or work from the project configuration.
|
|
386
|
+
const SOURCE_COMMANDS = {
|
|
387
|
+
mcp: runMcp,
|
|
388
|
+
serve: runServe,
|
|
389
|
+
generate: runGenerate,
|
|
390
|
+
producer: runProducer,
|
|
391
|
+
};
|
|
392
|
+
|
|
393
|
+
// Commands that read one loaded index: (index, args, { runtime, repositoryMappings }).
|
|
394
|
+
const INDEX_COMMANDS = {
|
|
395
|
+
validate: runValidate,
|
|
396
|
+
graph: runGraph,
|
|
397
|
+
search: runSearch,
|
|
398
|
+
context: runContext,
|
|
399
|
+
concept: runConcept,
|
|
400
|
+
neighbors: runNeighbors,
|
|
401
|
+
paths: runPaths,
|
|
402
|
+
provenance: runProvenance,
|
|
403
|
+
"edge-kinds": runEdgeKinds,
|
|
404
|
+
computation: runComputation,
|
|
405
|
+
asset: runAsset,
|
|
406
|
+
source: runSource,
|
|
407
|
+
migrate: runMigrate,
|
|
408
|
+
};
|
|
409
|
+
|
|
410
|
+
// Runs the command named by the parsed arguments (after --help, --version and
|
|
411
|
+
// project discovery have been handled by the entry point).
|
|
412
|
+
async function runCommand(args, runtime) {
|
|
413
|
+
if (args.inspect) {
|
|
414
|
+
printJson(graphSummary(await loadIndex(args)));
|
|
415
|
+
return;
|
|
416
|
+
}
|
|
417
|
+
const command = args.positional[0] || "mcp";
|
|
418
|
+
if (!COMMANDS.has(command)) {
|
|
419
|
+
throw usageError(`Unknown OKF command: ${command}`);
|
|
420
|
+
}
|
|
421
|
+
if (!WRITE_COMMANDS.has(command) && (args.write || args.actor || args.gitCommit)) {
|
|
422
|
+
throw usageError(
|
|
423
|
+
"--write, --actor, and --git-commit are available only with the mcp and producer commands.",
|
|
424
|
+
);
|
|
425
|
+
}
|
|
426
|
+
if (command === "producer" && args.gitCommit) {
|
|
427
|
+
throw usageError("--git-commit is available only with the mcp command.");
|
|
428
|
+
}
|
|
429
|
+
if (command === "producer" && args.policy) {
|
|
430
|
+
throw usageError("--policy is available only with the mcp command.");
|
|
431
|
+
}
|
|
432
|
+
if (command !== "mcp" && args.http.enabled) {
|
|
433
|
+
throw usageError("--http is available only with the mcp command.");
|
|
434
|
+
}
|
|
435
|
+
if (SOURCE_COMMANDS[command]) {
|
|
436
|
+
await SOURCE_COMMANDS[command](args, runtime);
|
|
437
|
+
return;
|
|
438
|
+
}
|
|
439
|
+
const index = await loadIndex(args);
|
|
440
|
+
const repositoryMappings = parseRepositoryMappings(args.repositories);
|
|
441
|
+
const handler = INDEX_COMMANDS[command];
|
|
442
|
+
if (!handler) {
|
|
443
|
+
throw usageError(`Unknown OKF command: ${command}`);
|
|
444
|
+
}
|
|
445
|
+
await handler(index, args, { runtime, repositoryMappings });
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
module.exports = { runCommand };
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
// Flags of `okf mcp --http` (plan WP6a, I-2): the main option parser hands
|
|
4
|
+
// each argument to parseHttpOption first; httpServerOptions then checks the
|
|
5
|
+
// combination and builds the options of runMcpHttpServer (src/mcp/http.js).
|
|
6
|
+
|
|
7
|
+
const DEFAULT_HTTP_PORT = 8766;
|
|
8
|
+
const DEFAULT_REFRESH_INTERVAL_MS = 2000;
|
|
9
|
+
|
|
10
|
+
function createHttpOptions() {
|
|
11
|
+
return {
|
|
12
|
+
enabled: false,
|
|
13
|
+
publicUrl: "",
|
|
14
|
+
allowedHosts: [],
|
|
15
|
+
allowedOrigins: [],
|
|
16
|
+
auth: "",
|
|
17
|
+
authorizationServer: "",
|
|
18
|
+
refreshInterval: "",
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
// Value flags: `repeat` ones collect every value, the others take one.
|
|
23
|
+
const VALUE_FLAGS = {
|
|
24
|
+
"--public-url": { key: "publicUrl" },
|
|
25
|
+
"--allowed-host": { key: "allowedHosts", repeat: true },
|
|
26
|
+
"--allowed-origin": { key: "allowedOrigins", repeat: true },
|
|
27
|
+
"--auth": { key: "auth" },
|
|
28
|
+
"--authorization-server": { key: "authorizationServer" },
|
|
29
|
+
"--refresh-interval": { key: "refreshInterval" },
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
// Consumes one HTTP flag at argv[index]: returns how many extra arguments
|
|
33
|
+
// it used, or -1 when `arg` is not an HTTP flag. `fail` builds a usage error.
|
|
34
|
+
function parseHttpOption(arg, argv, index, http, fail) {
|
|
35
|
+
if (arg === "--http") {
|
|
36
|
+
http.enabled = true;
|
|
37
|
+
return 0;
|
|
38
|
+
}
|
|
39
|
+
const equals = arg.indexOf("=");
|
|
40
|
+
const name = equals > 0 ? arg.slice(0, equals) : arg;
|
|
41
|
+
const flag = VALUE_FLAGS[name];
|
|
42
|
+
if (!flag) return -1;
|
|
43
|
+
const inline = equals > 0;
|
|
44
|
+
const value = inline ? arg.slice(equals + 1) : argv[index + 1];
|
|
45
|
+
if (!value || (!inline && String(value).startsWith("-"))) {
|
|
46
|
+
throw fail(`${name} requires a value.`);
|
|
47
|
+
}
|
|
48
|
+
if (flag.repeat) {
|
|
49
|
+
http[flag.key].push(value);
|
|
50
|
+
} else {
|
|
51
|
+
if (http[flag.key]) throw fail(`${name} may be supplied only once.`);
|
|
52
|
+
http[flag.key] = value;
|
|
53
|
+
}
|
|
54
|
+
return inline ? 0 : 1;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function isLoopback(host) {
|
|
58
|
+
return host === "localhost" || host === "::1" || /^127\.\d+\.\d+\.\d+$/.test(host);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// A hostname as the SDK's Host and Origin allowlists compare it (no scheme
|
|
62
|
+
// or port; IPv6 in brackets), from a hostname, host:port or origin URL.
|
|
63
|
+
function hostnameOf(value, name, fail) {
|
|
64
|
+
try {
|
|
65
|
+
const hostname = new URL(value.includes("://") ? value : `http://${value}`).hostname;
|
|
66
|
+
if (hostname) return hostname;
|
|
67
|
+
} catch {
|
|
68
|
+
// Reported below.
|
|
69
|
+
}
|
|
70
|
+
throw fail(`${name} must be a hostname or an origin URL.`);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// --auth tokens:<file> | introspect:<url> (plan I-2a). The introspection
|
|
74
|
+
// URL comes only from this flag (B-3): https, or http on a loopback host.
|
|
75
|
+
function authOf(http, publicUrl, fail) {
|
|
76
|
+
const issuerOnly = () => fail("--authorization-server requires --auth introspect:<url>.");
|
|
77
|
+
if (!http.auth) {
|
|
78
|
+
if (http.authorizationServer) throw issuerOnly();
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
const colon = http.auth.indexOf(":");
|
|
82
|
+
const mode = colon > 0 ? http.auth.slice(0, colon) : "";
|
|
83
|
+
const target = colon > 0 ? http.auth.slice(colon + 1) : "";
|
|
84
|
+
if (mode === "tokens" && target) {
|
|
85
|
+
if (http.authorizationServer) throw issuerOnly();
|
|
86
|
+
return { mode, file: target };
|
|
87
|
+
}
|
|
88
|
+
if (mode !== "introspect" || !target) {
|
|
89
|
+
throw fail("--auth must be tokens:<file> or introspect:<url>.");
|
|
90
|
+
}
|
|
91
|
+
let url;
|
|
92
|
+
try {
|
|
93
|
+
url = new URL(target);
|
|
94
|
+
} catch {
|
|
95
|
+
throw fail("--auth introspect:<url> needs an absolute URL.");
|
|
96
|
+
}
|
|
97
|
+
const loopback = url.protocol === "http:" && isLoopback(url.hostname.replace(/^\[|\]$/g, ""));
|
|
98
|
+
if (!(url.protocol === "https:" || loopback) || url.username || url.password) {
|
|
99
|
+
throw fail(
|
|
100
|
+
"--auth introspect:<url> must be https (or http on a loopback host), without credentials.",
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
if (url.search || url.hash) {
|
|
104
|
+
throw fail("--auth introspect:<url> must not carry a query or fragment.");
|
|
105
|
+
}
|
|
106
|
+
if (!http.authorizationServer) {
|
|
107
|
+
throw fail("--auth introspect:<url> requires --authorization-server <issuer>.");
|
|
108
|
+
}
|
|
109
|
+
if (!publicUrl) {
|
|
110
|
+
throw fail("--auth introspect:<url> requires --public-url, the token audience.");
|
|
111
|
+
}
|
|
112
|
+
return { mode, url: url.href, issuer: http.authorizationServer };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function publicUrlOf(value, fail) {
|
|
116
|
+
let url;
|
|
117
|
+
try {
|
|
118
|
+
url = new URL(value);
|
|
119
|
+
} catch {
|
|
120
|
+
throw fail("--public-url must be an absolute http or https URL.");
|
|
121
|
+
}
|
|
122
|
+
if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
|
|
123
|
+
throw fail("--public-url must be an http or https URL without credentials.");
|
|
124
|
+
}
|
|
125
|
+
if (url.search || url.hash) {
|
|
126
|
+
throw fail("--public-url must not carry a query or fragment.");
|
|
127
|
+
}
|
|
128
|
+
return url;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// The options of runMcpHttpServer, or null without --http.
|
|
132
|
+
function httpServerOptions(args, fail) {
|
|
133
|
+
const http = args.http;
|
|
134
|
+
if (!http.enabled) {
|
|
135
|
+
const given = [
|
|
136
|
+
http.publicUrl,
|
|
137
|
+
http.allowedHosts.length,
|
|
138
|
+
http.allowedOrigins.length,
|
|
139
|
+
http.auth,
|
|
140
|
+
http.authorizationServer,
|
|
141
|
+
http.refreshInterval,
|
|
142
|
+
];
|
|
143
|
+
if (given.some(Boolean)) {
|
|
144
|
+
throw fail(
|
|
145
|
+
"--public-url, --allowed-host, --allowed-origin, --auth, --authorization-server and --refresh-interval require --http.",
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
return null;
|
|
149
|
+
}
|
|
150
|
+
// Which scope may create and accept proposals over HTTP is not decided,
|
|
151
|
+
// so the proposal tools stay a stdio feature for now.
|
|
152
|
+
if (args.authoring) {
|
|
153
|
+
throw fail("--authoring is not available with --http.");
|
|
154
|
+
}
|
|
155
|
+
const publicUrl = http.publicUrl ? publicUrlOf(http.publicUrl, fail) : null;
|
|
156
|
+
const auth = authOf(http, publicUrl, fail);
|
|
157
|
+
if (args.write && !auth) {
|
|
158
|
+
throw fail("--write with --http requires --auth: an unauthenticated HTTP caller is read-only.");
|
|
159
|
+
}
|
|
160
|
+
if (!isLoopback(args.host) && !auth) {
|
|
161
|
+
throw fail("--http on a non-loopback --host requires --auth.");
|
|
162
|
+
}
|
|
163
|
+
const port = args.portGiven ? args.port : DEFAULT_HTTP_PORT;
|
|
164
|
+
if (!Number.isInteger(port) || port < 0 || port > 65535) {
|
|
165
|
+
throw fail("--port must be an integer from 0 through 65535.");
|
|
166
|
+
}
|
|
167
|
+
const refreshIntervalMs = http.refreshInterval
|
|
168
|
+
? Number(http.refreshInterval)
|
|
169
|
+
: DEFAULT_REFRESH_INTERVAL_MS;
|
|
170
|
+
if (!/^\d+$/.test(http.refreshInterval || "0") || refreshIntervalMs > 86400000) {
|
|
171
|
+
throw fail("--refresh-interval must be a number of milliseconds from 0 through 86400000.");
|
|
172
|
+
}
|
|
173
|
+
const mcpPath = publicUrl ? publicUrl.pathname.replace(/(.)\/+$/, "$1") : "/mcp";
|
|
174
|
+
return {
|
|
175
|
+
host: args.host,
|
|
176
|
+
port,
|
|
177
|
+
mcpPath,
|
|
178
|
+
publicUrl: publicUrl ? publicUrl.href : null,
|
|
179
|
+
allowedHosts: http.allowedHosts
|
|
180
|
+
.map((value) => hostnameOf(value, "--allowed-host", fail))
|
|
181
|
+
.concat(publicUrl ? [publicUrl.hostname] : []),
|
|
182
|
+
allowedOrigins: http.allowedOrigins.map((value) => hostnameOf(value, "--allowed-origin", fail)),
|
|
183
|
+
auth,
|
|
184
|
+
refreshIntervalMs,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
module.exports = {
|
|
189
|
+
DEFAULT_HTTP_PORT,
|
|
190
|
+
createHttpOptions,
|
|
191
|
+
httpServerOptions,
|
|
192
|
+
parseHttpOption,
|
|
193
|
+
};
|