@mfdaves/okf-mcp 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -35,7 +35,7 @@ Node 22 or newer is required.
35
35
  Install from the GitHub release:
36
36
 
37
37
  ```bash
38
- git clone --branch v0.5.1 https://github.com/mfdaves/okf-mcp.git
38
+ git clone --branch v0.6.0 https://github.com/mfdaves/okf-mcp.git
39
39
  cd okf-mcp
40
40
  npm ci
41
41
  node bin/okf-mcp.js --root ./path/to/okf validate
@@ -44,14 +44,14 @@ node bin/okf-mcp.js --root ./path/to/okf validate
44
44
  Pin the published version for reproducible use:
45
45
 
46
46
  ```bash
47
- npx -y @mfdaves/okf-mcp@0.5.1 --version
48
- npx -y @mfdaves/okf-mcp@0.5.1 --root ./path/to/okf validate
47
+ npx -y @mfdaves/okf-mcp@0.6.0 --version
48
+ npx -y @mfdaves/okf-mcp@0.6.0 --root ./path/to/okf validate
49
49
  ```
50
50
 
51
51
  For a persistent installation:
52
52
 
53
53
  ```bash
54
- npm install --global @mfdaves/okf-mcp@0.5.1
54
+ npm install --global @mfdaves/okf-mcp@0.6.0
55
55
 
56
56
  okf --version
57
57
  okf --root ./path/to/okf validate
@@ -95,7 +95,7 @@ okf --root okf/bundles/okf-mcp concept overview/okf-mcp
95
95
  Load the reference bundle directly from this release:
96
96
 
97
97
  ```bash
98
- okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.5.1/okf/bundles/okf-mcp --inspect
98
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.6.0/okf/bundles/okf-mcp --inspect
99
99
  ```
100
100
 
101
101
  The `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
@@ -182,7 +182,7 @@ Example client configuration:
182
182
  "command": "npx",
183
183
  "args": [
184
184
  "-y",
185
- "@mfdaves/okf-mcp@0.5.1",
185
+ "@mfdaves/okf-mcp@0.6.0",
186
186
  "--root",
187
187
  "/absolute/path/to/okf",
188
188
  "mcp"
@@ -201,7 +201,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
201
201
  "command": "npx",
202
202
  "args": [
203
203
  "-y",
204
- "@mfdaves/okf-mcp@0.5.1",
204
+ "@mfdaves/okf-mcp@0.6.0",
205
205
  "--project",
206
206
  "/absolute/path/to/repo/okf.project.yaml",
207
207
  "mcp"
@@ -211,7 +211,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
211
211
  }
212
212
  ```
213
213
 
214
- Add `--authoring` to enable proposal creation, acceptance, and rejection. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.
214
+ Add `--authoring` to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add `--write --actor <actor>` to expose one transactional `okf_apply_changes` tool; add `--git-commit` to commit each successful batch when the catalog is in a clean Git worktree. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.
215
215
 
216
216
  The stdio server uses `@modelcontextprotocol/server` v2. It serves the modern
217
217
  `2026-07-28` MCP revision and the SDK's compatibility path for 2025-era
@@ -316,6 +316,7 @@ okf --root /path/to/catalog \
316
316
  - `okf_get_proposal`
317
317
  - `okf_accept_proposal`
318
318
  - `okf_reject_proposal`
319
+ - `okf_apply_changes`
319
320
  - `get_graph`
320
321
  - `get_neighbors`
321
322
  - `get_subgraph`
@@ -336,20 +337,59 @@ disabled tool names remain protocol-level invalid-parameter errors.
336
337
 
337
338
  Tool discovery and direct invocation use the same capability checks:
338
339
 
339
- | Mode | Normal proposals | Computation proposal | Runtime remote load |
340
- | --- | --- | --- | --- |
341
- | default | disabled | disabled | disabled |
342
- | `--authoring` | enabled | disabled | disabled |
343
- | `--authoring --allow-computation-authoring` | enabled | enabled | disabled |
344
- | `--allow-remote-tool` | disabled | disabled | enabled |
340
+ | Mode | Normal proposals | Direct live write | Computation proposal | Runtime remote load |
341
+ | --- | --- | --- | --- | --- |
342
+ | default | disabled | disabled | disabled | disabled |
343
+ | `--authoring` | enabled | disabled | disabled | disabled |
344
+ | `--write --actor openai/gpt-5.6` | disabled | enabled | disabled | disabled |
345
+ | `--authoring --allow-computation-authoring` | enabled | disabled | enabled | disabled |
346
+ | `--allow-remote-tool` | disabled | disabled | disabled | enabled |
345
347
 
346
- An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. The `okf_*` mutation tools are proposal-first and require `--authoring`. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Proposing a concept or update writes only a proposal record. Acceptance writes Markdown inside the selected local root and rebuilds the index; remote roots remain read only.
348
+ An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. Proposal mutation tools require `--authoring`. The direct live tool instead requires `--write` plus a truthful actor using `human:<id>`, `process:<id>`, or `provider/model` syntax. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Remote roots remain read only.
347
349
 
348
350
  Generic concept tools cannot create or change an Attested Computation contract. `okf_propose_attested_computation` additionally requires `--allow-computation-authoring` and creates one coordinated review proposal for the concept plus an optional external computation file.
349
351
 
352
+ ## Live Concept Authoring
353
+
354
+ Start the server with the direct-write capability only when the MCP client/user approval boundary is sufficient review:
355
+
356
+ ```bash
357
+ okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp
358
+ ```
359
+
360
+ The agent sees one destructive tool. It supplies structured concept fields rather than YAML; OKF serializes compatible Markdown frontmatter and stamps the configured `generated.by` plus one `generated.at` timestamp for the whole batch.
361
+
362
+ ```json
363
+ {
364
+ "name": "okf_apply_changes",
365
+ "arguments": {
366
+ "message": "docs(okf): document order creation",
367
+ "changes": [
368
+ {
369
+ "op": "create",
370
+ "type": "MCP Tool",
371
+ "title": "Create Order",
372
+ "body": "# Create Order\n\nCreates a validated order.",
373
+ "tags": ["orders", "mcp"],
374
+ "sources": ["/repositories/orders-service.md"],
375
+ "relations": [
376
+ { "type": "related_to", "target": "/workflows/order-creation.md" }
377
+ ]
378
+ }
379
+ ]
380
+ }
381
+ }
382
+ ```
383
+
384
+ Create paths are optional and derive deterministically from type and title. Updates identify an existing `uri`; scalar fields replace existing values, while `tags`, `sources`, and `relations` use explicit `add`/`remove` patches. `metadata` carries extension frontmatter but cannot override identity, generation, collection, or computation fields.
385
+
386
+ Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another. The server writes nothing unless every candidate is valid, revision checks still match, and every target stays inside one writable bundle. Process-generated documents, generator output directories, reserved files, and Attested Computation contracts are not live-write targets.
387
+
388
+ Add `--git-commit` as server policy to create one commit per successful batch. A detected Git worktree must be completely clean and have a configured identity before any file is staged. The tool never pushes. Non-Git catalogs are written normally; if staging or commit fails after valid files were written, the result is `applied_uncommitted` and includes the Git error so the work remains recoverable.
389
+
350
390
  ## Authoring Concepts
351
391
 
352
- Concept authoring is available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
392
+ The reviewable proposal workflow remains available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
353
393
 
354
394
  MCP proposal flow:
355
395
 
@@ -405,6 +445,8 @@ Safety rules:
405
445
  - updates cannot change concept identity and reject detected changes made after proposal creation
406
446
  - invalid IDs, invalid relation types, and broken internal OKF relations fail validation
407
447
  - external relation targets such as `repo://...` are allowed
448
+ - direct batches are serialized within one process and validate the combined future graph before publication
449
+ - independent processes still require external single-writer coordination
408
450
 
409
451
  ## HTTP API
410
452
 
@@ -17,6 +17,8 @@ relations:
17
17
  target: repo://test/okf-mcp.test.js
18
18
  - type: checked_by
19
19
  target: repo://test/mcp-hardening.test.js
20
+ - type: checked_by
21
+ target: repo://test/live-authoring.test.js
20
22
  ---
21
23
 
22
24
  # MCP Tool Catalog
@@ -33,7 +35,9 @@ Static computation tools inspect contracts, read indexed assets, prepare paramet
33
35
 
34
36
  `read_git_source` reads one pinned `sources[].git` entry from a checkout or bare repository explicitly mapped by the MCP host. It reads the Git object database rather than the working tree and never fetches.
35
37
 
36
- An explicit local root or project workspace exposes candidate validation, path suggestion, and proposal inspection. Normal proposal mutations require `--authoring`; the coordinated computation proposal additionally requires `--allow-computation-authoring`. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
38
+ An explicit local root or project workspace exposes candidate validation, path suggestion, and proposal inspection. Normal proposal mutations require `--authoring`; the coordinated computation proposal additionally requires `--allow-computation-authoring`. `--write --actor <actor>` exposes only `okf_apply_changes`, which accepts structured create/update batches without requiring agents to compose YAML. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
39
+
40
+ `okf_apply_changes` validates 1–100 operations as one future graph, stamps one server-owned `generated.at` with the configured `generated.by`, then publishes the complete local batch and refreshes the index. Optional `--git-commit` policy creates one scoped commit from a clean worktree. Commit failure leaves valid files applied and reports `applied_uncommitted`; the tool never pushes.
37
41
 
38
42
  Every tool supplies a purpose-specific description, descriptions for all input parameters, and MCP annotations for read behavior, destructive behavior, idempotency, and external access. Tool discovery and direct invocation use the same capability checks, so a hidden tool also fails when called by name. Annotations remain hints to clients; server-side validation is authoritative.
39
43
 
@@ -15,15 +15,19 @@ relations:
15
15
  target: repo://src/authoring.js
16
16
  - type: configured_by
17
17
  target: repo://src/store.js
18
+ - type: configured_by
19
+ target: repo://src/live-authoring.js
18
20
  - type: checked_by
19
21
  target: repo://test/okf-mcp.test.js
20
22
  - type: checked_by
21
23
  target: repo://test/mcp-hardening.test.js
24
+ - type: checked_by
25
+ target: repo://test/live-authoring.test.js
22
26
  ---
23
27
 
24
28
  # Authoring Safety
25
29
 
26
- Authoring is allowed for an explicit local `--root` or local roots declared by `okf.project.yaml`. MCP proposal mutations require `--authoring`; coordinated computation proposals also require `--allow-computation-authoring`. Remote roots are read only.
30
+ Authoring is allowed for an explicit local `--root` or local roots declared by `okf.project.yaml`. MCP proposal mutations require `--authoring`; coordinated computation proposals also require `--allow-computation-authoring`. Direct authoring requires `--write` and a configured actor. Remote roots are read only.
27
31
 
28
32
  Concept paths must be safe relative `.md` paths inside the selected bundle. Absolute paths, parent traversal, reserved `index.md` and `log.md` targets, symbolic-link traversal, and non-directory parents are rejected.
29
33
 
@@ -33,6 +37,8 @@ Candidates must satisfy the concept format, configured relation vocabulary, and
33
37
 
34
38
  Proposal creation never writes a concept file. Acceptance repeats validation. Updates also compare the source revision immediately before replacement and return conflicts for detected concurrent changes. After acceptance, the MCP index is rebuilt without discarding configured or runtime-loaded remote bundle state.
35
39
 
40
+ Direct authoring exposes one destructive batch tool. It validates the combined future graph, stamps generation metadata at the server boundary, serializes batches under one process-local writer lock, stages every file before publication, and rolls back its published files on write or post-write validation failure. It rejects generated-file flags, `process:*` generation owners, configured generator outputs, and computation contracts. Optional Git commits require a clean worktree before any write and never push; a commit failure leaves the valid batch visible as applied but uncommitted.
41
+
36
42
  Computation, executor, and attester artifacts are always inert. Inspection and preflight never execute them, fetch external contract URIs, echo parameter or receipt values, persist receipts, or claim attestation. Migration adds no unverifiable provenance or trust claims and never accepts its own proposals.
37
43
 
38
44
  HTTP mutations require bearer authorization. Filesystem safeguards still apply after authentication.
@@ -2,8 +2,8 @@
2
2
  id: okf://okf-mcp/runtime/file-concept-store
3
3
  type: OKF Runtime Component
4
4
  title: File Concept Store
5
- description: Local proposal and concept persistence boundary used by root and project authoring.
6
- tags: [storage, proposals, authoring, filesystem]
5
+ description: Local proposal, direct-batch, and concept persistence boundary used by root and project authoring.
6
+ tags: [storage, proposals, authoring, filesystem, batch]
7
7
  relations:
8
8
  - type: consumes
9
9
  target: okf://okf-mcp/specs/concept-format
@@ -27,6 +27,8 @@ New concepts use exclusive creation. Updates retain a SHA256 revision and check
27
27
 
28
28
  The store rolls back published files when an ordinary acceptance call fails, but a multi-file acceptance is not crash-transactional across process or power loss. Operators must inspect and repair an interrupted acceptance before restarting authoring; the store does not claim database transaction semantics.
29
29
 
30
+ Proposal acceptance and direct live batches share one process-local writer queue. A direct batch stages every candidate, checks revisions immediately before publication, validates the persisted graph, and restores its own changed files when publication or validation fails. This provides all-or-nothing behavior for ordinary process errors, not crash durability or distributed coordination.
31
+
30
32
  Write paths remain bundle-relative, bundle boundaries are enforced, and symbolic-link traversal is blocked. Generic tools cannot alter computation contracts. Migration manifests live under `.okf-proposals/migrations`; their child proposals are never auto-accepted, and the reserved version proposal depends on accepted Stage-A children.
31
33
 
32
34
  This is a local file-backed store intended for a trusted root or project workspace. It is not a distributed transaction system or multi-writer database. Its invariants are defined by the [authoring safety policy](../policies/authoring-safety.md).
@@ -2,8 +2,8 @@
2
2
  id: okf://okf-mcp/workflows/concept-authoring
3
3
  type: OKF Workflow
4
4
  title: Concept Authoring
5
- description: Proposal-first workflow for validating, reviewing, and accepting new OKF concepts.
6
- tags: [workflow, authoring, proposals, review]
5
+ description: Reviewable and direct workflows for validating and persisting structured OKF concept changes.
6
+ tags: [workflow, authoring, proposals, review, batch]
7
7
  relations:
8
8
  - type: depends_on
9
9
  target: okf://okf-mcp/runtime/file-concept-store
@@ -15,11 +15,13 @@ relations:
15
15
  target: okf://okf-mcp/workflows/concept-update
16
16
  - type: configured_by
17
17
  target: repo://src/authoring.js
18
+ - type: configured_by
19
+ target: repo://src/live-authoring.js
18
20
  ---
19
21
 
20
22
  # Concept Authoring
21
23
 
22
- Concept authoring separates proposal from persistence.
24
+ Concept authoring has two explicitly gated persistence paths.
23
25
 
24
26
  First, the candidate bundle, path, frontmatter, body, links, relations, and identity are validated. A valid proposal stores the candidate Markdown and its validation result as a proposal record. It does not create the concept file.
25
27
 
@@ -27,4 +29,8 @@ A reviewer then inspects the proposal and either accepts or rejects it. Acceptan
27
29
 
28
30
  Invalid candidates never become proposals. A proposal that becomes invalid before acceptance remains inspectable and returns the current validation result.
29
31
 
32
+ For a trusted client approval boundary, `--write --actor <actor>` exposes one direct `okf_apply_changes` tool. Agents submit structured concept fields rather than YAML. The server derives optional paths, patches tags/sources/relations, stamps one generation actor and time, validates the complete future graph, and publishes all files or none. Optional Git policy creates one commit for the batch without pushing.
33
+
34
+ Direct writes do not replace generator ownership or computation review. Process-generated concepts, configured generator outputs, and Attested Computation contracts remain outside this workflow.
35
+
30
36
  Corrections to existing concepts follow the related [concept update workflow](concept-update.md). Both paths are governed by the [authoring safety policy](../policies/authoring-safety.md) and persist through the [file concept store](../runtime/file-concept-store.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mfdaves/okf-mcp",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Local-first Open Knowledge Format validator, graph index, CLI, and MCP stdio server.",
5
5
  "homepage": "https://github.com/mfdaves/okf-mcp#readme",
6
6
  "repository": {
package/server.json CHANGED
@@ -8,12 +8,12 @@
8
8
  "source": "github"
9
9
  },
10
10
  "websiteUrl": "https://github.com/mfdaves/okf-mcp#readme",
11
- "version": "0.5.1",
11
+ "version": "0.6.0",
12
12
  "packages": [
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "@mfdaves/okf-mcp",
16
- "version": "0.5.1",
16
+ "version": "0.6.0",
17
17
  "transport": {
18
18
  "type": "stdio"
19
19
  },
package/src/cli.js CHANGED
@@ -27,6 +27,7 @@ const {
27
27
  } = require("./computation");
28
28
  const { buildV02MigrationPlan, checkV02Migration } = require("./migration");
29
29
  const { describeConceptGitSources, readConceptGitSource } = require("./git-source");
30
+ const { validActor } = require("./v02");
30
31
  const packageMetadata = require("../package.json");
31
32
 
32
33
  const COMMANDS = new Set([
@@ -90,6 +91,9 @@ function parseArgs(argv) {
90
91
  let proposalRoot = "";
91
92
  let version = false;
92
93
  let authoring = false;
94
+ let write = false;
95
+ let actor = "";
96
+ let gitCommit = false;
93
97
  let allowRemoteTool = false;
94
98
  let strictLinks = false;
95
99
  let allowComputationAuthoring = false;
@@ -201,6 +205,35 @@ function parseArgs(argv) {
201
205
  authoring = true;
202
206
  continue;
203
207
  }
208
+ if (arg === "--write") {
209
+ write = true;
210
+ continue;
211
+ }
212
+ if (arg === "--actor") {
213
+ if (actor) {
214
+ throw usageError("--actor may be supplied only once.");
215
+ }
216
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
217
+ throw usageError("--actor requires a value.");
218
+ }
219
+ actor = argv[index + 1];
220
+ index += 1;
221
+ continue;
222
+ }
223
+ if (arg.startsWith("--actor=")) {
224
+ if (actor) {
225
+ throw usageError("--actor may be supplied only once.");
226
+ }
227
+ actor = arg.slice("--actor=".length);
228
+ if (!actor) {
229
+ throw usageError("--actor requires a value.");
230
+ }
231
+ continue;
232
+ }
233
+ if (arg === "--git-commit") {
234
+ gitCommit = true;
235
+ continue;
236
+ }
204
237
  if (arg === "--allow-remote-tool") {
205
238
  allowRemoteTool = true;
206
239
  continue;
@@ -371,6 +404,18 @@ function parseArgs(argv) {
371
404
  positional.push(arg);
372
405
  }
373
406
  }
407
+ if (write && !actor) {
408
+ throw usageError("--write requires --actor <human:id|process:id|provider/model>.");
409
+ }
410
+ if (write && !validActor(actor)) {
411
+ throw usageError("--actor must use human:<id>, process:<id>, or provider/model syntax.");
412
+ }
413
+ if (actor && !write) {
414
+ throw usageError("--actor requires --write.");
415
+ }
416
+ if (gitCommit && !write) {
417
+ throw usageError("--git-commit requires --write.");
418
+ }
374
419
  return {
375
420
  bundles,
376
421
  remoteBundles,
@@ -382,6 +427,9 @@ function parseArgs(argv) {
382
427
  help,
383
428
  version,
384
429
  authoring,
430
+ write,
431
+ actor,
432
+ gitCommit,
385
433
  allowRemoteTool,
386
434
  allowComputationAuthoring,
387
435
  strictLinks,
@@ -409,7 +457,7 @@ function usage() {
409
457
  " okf-mcp --bundle <path-or-id=path> [--bundle <path>] [--inspect]",
410
458
  " okf-mcp --remote-bundle <id=github-tree-url> [--inspect]",
411
459
  " okf-mcp --project <okf.project.yaml> <command>",
412
- " okf-mcp [--project <okf.project.yaml>] [--authoring] [--allow-computation-authoring] [--allow-remote-tool] mcp",
460
+ " okf-mcp [--project <okf.project.yaml>] [--authoring] [--write --actor <actor>] [--git-commit] mcp",
413
461
  " okf-mcp --project <okf.project.yaml> serve [--host 127.0.0.1] [--port 8765]",
414
462
  " okf-mcp <command> --bundle <path-or-id=path>",
415
463
  "",
@@ -437,6 +485,9 @@ function usage() {
437
485
  " --root, -r <directory> Load one official OKF bundle root.",
438
486
  " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
439
487
  " --authoring Enable MCP proposal authoring tools.",
488
+ " --write Enable direct atomic MCP concept writes (requires --actor).",
489
+ " --actor <actor> Stamp live writes with human:id, process:id, or provider/model.",
490
+ " --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
440
491
  " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
441
492
  " --allow-computation-authoring Enable coordinated computation proposals (also requires --authoring).",
442
493
  " --strict-links Treat broken internal Markdown links as project-invalid.",
@@ -534,6 +585,13 @@ function stdioServerOptions(args) {
534
585
  if (args.authoring && args.allowComputationAuthoring) {
535
586
  options.allowComputationAuthoring = true;
536
587
  }
588
+ if (args.write) {
589
+ options.allowWrite = true;
590
+ options.actor = args.actor;
591
+ if (args.gitCommit) {
592
+ options.gitCommit = true;
593
+ }
594
+ }
537
595
  if (args.strictLinks) {
538
596
  options.strictLinks = true;
539
597
  }
@@ -610,6 +668,9 @@ async function main(argv, runtime) {
610
668
  if (!COMMANDS.has(command)) {
611
669
  throw usageError(`Unknown OKF command: ${command}`);
612
670
  }
671
+ if (command !== "mcp" && (args.write || args.actor || args.gitCommit)) {
672
+ throw usageError("--write, --actor, and --git-commit are available only with the mcp command.");
673
+ }
613
674
  if (command === "mcp") {
614
675
  const bundles = resolveLegacyBundles(args);
615
676
  if (args.project) {
package/src/index.js CHANGED
@@ -14,6 +14,7 @@ module.exports = {
14
14
  ...require("./git-source"),
15
15
  ...require("./migration"),
16
16
  ...require("./authoring"),
17
+ ...require("./live-authoring"),
17
18
  ...require("./store"),
18
19
  ...require("./http-server"),
19
20
  ...require("./mcp-server"),
package/src/indexer.js CHANGED
@@ -47,6 +47,10 @@ function parseBundleArg(arg, index) {
47
47
  };
48
48
  }
49
49
 
50
+ function documentOverrideKey(bundleId, relativePath) {
51
+ return `${bundleId}\u0000${normalizeSlashes(relativePath)}`;
52
+ }
53
+
50
54
  function uniqueBundleIds(bundles) {
51
55
  return bundles.map((bundle) => {
52
56
  const base = sanitizeBundleId(bundle.id);
@@ -319,6 +323,9 @@ function semanticReferences(doc) {
319
323
 
320
324
  function buildIndex(bundleArgs, options) {
321
325
  const config = options || {};
326
+ const documentOverrides = config.documentOverrides instanceof Map
327
+ ? config.documentOverrides
328
+ : new Map();
322
329
  const strictLinks = Boolean(config.strictLinks);
323
330
  const requestedBundles = uniqueBundleIds((bundleArgs || []).map(parseBundleArg));
324
331
  const allowedRelationTypes = new Set((config.relationTypes || DEFAULT_RELATION_TYPES).map(String));
@@ -378,13 +385,13 @@ function buildIndex(bundleArgs, options) {
378
385
  errors.push({ code: "missing_bundle_root", bundle: bundle.id, path: bundle.root, message: "Bundle root does not exist." });
379
386
  return;
380
387
  }
381
- walkMarkdown(bundle.root).forEach((filePath) => {
382
- const relativePath = safeRelativePath(bundle.root, filePath) || normalizeSlashes(filePath);
383
- if (!bundleAllowsPath(bundle, relativePath)) {
384
- return;
385
- }
388
+ const indexedPaths = new Set();
389
+ const indexLocalDocument = (relativePath, text, source) => {
390
+ indexedPaths.add(relativePath);
386
391
  try {
387
- const doc = parseMarkdownFile(bundle, filePath, { asOf: config.asOf });
392
+ const doc = text === undefined
393
+ ? parseMarkdownFile(bundle, source, { asOf: config.asOf })
394
+ : parseMarkdownText(bundle, relativePath, text, source, { asOf: config.asOf });
388
395
  documents.push(doc);
389
396
  if (doc.reserved) {
390
397
  reserved.push(doc);
@@ -400,6 +407,33 @@ function buildIndex(bundleArgs, options) {
400
407
  message: error.message,
401
408
  });
402
409
  }
410
+ };
411
+ walkMarkdown(bundle.root).forEach((filePath) => {
412
+ const relativePath = safeRelativePath(bundle.root, filePath) || normalizeSlashes(filePath);
413
+ if (!bundleAllowsPath(bundle, relativePath)) {
414
+ return;
415
+ }
416
+ const key = documentOverrideKey(bundle.id, relativePath);
417
+ indexLocalDocument(
418
+ relativePath,
419
+ documentOverrides.has(key) ? String(documentOverrides.get(key)) : undefined,
420
+ filePath,
421
+ );
422
+ });
423
+ const prefix = `${bundle.id}\u0000`;
424
+ documentOverrides.forEach((text, key) => {
425
+ if (!String(key).startsWith(prefix)) {
426
+ return;
427
+ }
428
+ const relativePath = normalizeSlashes(String(key).slice(prefix.length));
429
+ if (indexedPaths.has(relativePath) || !bundleAllowsPath(bundle, relativePath)) {
430
+ return;
431
+ }
432
+ indexLocalDocument(
433
+ relativePath,
434
+ String(text),
435
+ path.join(bundle.root, ...relativePath.split("/")),
436
+ );
403
437
  });
404
438
  });
405
439