@mfdaves/okf-mcp 0.6.0 → 0.7.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 +17 -14
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +9 -3
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +8 -2
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +1 -1
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +2 -2
- package/okf/bundles/okf-mcp/specs/git-sources.md +1 -1
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/authoring.js +77 -11
- package/src/cli.js +1 -1
- package/src/git-source.js +13 -4
- package/src/live-authoring.js +1427 -123
- package/src/mcp-server.js +157 -35
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.
|
|
38
|
+
git clone --branch v0.7.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.
|
|
48
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
47
|
+
npx -y @mfdaves/okf-mcp@0.7.0 --version
|
|
48
|
+
npx -y @mfdaves/okf-mcp@0.7.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.
|
|
54
|
+
npm install --global @mfdaves/okf-mcp@0.7.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.
|
|
98
|
+
okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.7.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.
|
|
185
|
+
"@mfdaves/okf-mcp@0.7.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.
|
|
204
|
+
"@mfdaves/okf-mcp@0.7.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. For a smaller direct-write surface, add `--write --actor <actor>` to expose
|
|
214
|
+
Add `--authoring` to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add `--write --actor <actor>` to expose read-only `okf_validate_changes` and validated-batch `okf_apply_changes`; 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_validate_changes`
|
|
319
320
|
- `okf_apply_changes`
|
|
320
321
|
- `get_graph`
|
|
321
322
|
- `get_neighbors`
|
|
@@ -345,7 +346,7 @@ Tool discovery and direct invocation use the same capability checks:
|
|
|
345
346
|
| `--authoring --allow-computation-authoring` | enabled | disabled | enabled | disabled |
|
|
346
347
|
| `--allow-remote-tool` | disabled | disabled | disabled | enabled |
|
|
347
348
|
|
|
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
|
|
349
|
+
An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. Proposal mutation tools require `--authoring`. The direct live tools instead require `--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.
|
|
349
350
|
|
|
350
351
|
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.
|
|
351
352
|
|
|
@@ -357,7 +358,7 @@ Start the server with the direct-write capability only when the MCP client/user
|
|
|
357
358
|
okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp
|
|
358
359
|
```
|
|
359
360
|
|
|
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
|
+
The agent sees one read-only batch validator and one destructive apply 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
|
|
|
362
363
|
```json
|
|
363
364
|
{
|
|
@@ -381,11 +382,13 @@ The agent sees one destructive tool. It supplies structured concept fields rathe
|
|
|
381
382
|
}
|
|
382
383
|
```
|
|
383
384
|
|
|
384
|
-
Create paths are optional
|
|
385
|
+
Create paths are optional. The server first uses a strong dominant directory convention from existing concepts of the same type, then falls back to deterministic type/title slugs. `okf_suggest_concept_path` reports the strategy, evidence, availability, canonical URI, and absolute filename. 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. Paths and URIs are immutable during update: moving a concept changes its portable identity and remains a separate, intentionally unsupported operation.
|
|
385
386
|
|
|
386
|
-
Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another.
|
|
387
|
+
Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another. Call `okf_validate_changes` with the complete intended batch to receive a time-of-check preview without writing files. Validation and apply share the same planner; apply repeats every check under the writer queue because revisions and Git state can change after a preview. Results include compact semantic effects, canonical and absolute targets, source revisions, graph diagnostics, Git preconditions, and an explicit durability state without echoing full bodies.
|
|
387
388
|
|
|
388
|
-
|
|
389
|
+
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, hidden/control-plane paths such as `.git/**`, reserved files, and Attested Computation contracts are not live-write targets. Rollback checks revisions immediately before each restore and reports detected replacements as a partial `rollback_conflict`. That protection is best effort under the documented single-external-writer requirement; it is not a cross-process compare-and-swap guarantee.
|
|
390
|
+
|
|
391
|
+
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 publication. Active Git filter attributes and `assume-unchanged`/`skip-worktree` index flags block the operation so validation cannot execute configured filters or overlook hidden user changes; replace-object resolution is disabled so hidden replacement history cannot alter the parent tree. The server builds an isolated index from the validated Markdown bytes, creates that exact tree with `commit-tree`, publishes it with a compare-and-swap ref update, synchronizes only the affected ordinary-index paths afterward, and never pushes. Concurrent unrelated staged entries cannot enter the commit. A determinate commit failure leaves matching valid files as working-tree-only; an ambiguous ref-update timeout is reported as unknown unless the resulting commit tree can be proven. Non-Git catalogs are written normally. Every response makes the repository root, commit state, index state, target-byte state, and persistence boundary explicit.
|
|
389
392
|
|
|
390
393
|
## Authoring Concepts
|
|
391
394
|
|
|
@@ -437,7 +440,7 @@ Omitted frontmatter fields and an omitted body are preserved. The concept URI ca
|
|
|
437
440
|
|
|
438
441
|
Safety rules:
|
|
439
442
|
|
|
440
|
-
- concept paths must be safe relative `.md` paths inside a writable bundle
|
|
443
|
+
- concept paths must be safe, non-hidden relative `.md` paths inside a writable bundle
|
|
441
444
|
- concept writes cannot traverse symbolic links under a writable bundle
|
|
442
445
|
- missing subdirectories are created only when a proposal is accepted
|
|
443
446
|
- `index.md` and `log.md` cannot be authored as concepts
|
|
@@ -19,6 +19,10 @@ relations:
|
|
|
19
19
|
target: repo://test/mcp-hardening.test.js
|
|
20
20
|
- type: checked_by
|
|
21
21
|
target: repo://test/live-authoring.test.js
|
|
22
|
+
- type: checked_by
|
|
23
|
+
target: repo://test/live-mcp-contract.test.js
|
|
24
|
+
- type: checked_by
|
|
25
|
+
target: repo://test/live-agent-workflow.test.js
|
|
22
26
|
---
|
|
23
27
|
|
|
24
28
|
# MCP Tool Catalog
|
|
@@ -33,11 +37,13 @@ Validation tools inspect bundles, projects, and candidate concepts without writi
|
|
|
33
37
|
|
|
34
38
|
Static computation tools inspect contracts, read indexed assets, prepare parameter digests, and check receipt field names without execution, attestation, value echo, or persistence. Migration tools check or preview Stage A without writes.
|
|
35
39
|
|
|
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.
|
|
40
|
+
`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. Oversized content errors include the observed size, active limit, maximum supported limit, and whether a bounded retry can succeed.
|
|
41
|
+
|
|
42
|
+
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 read-only `okf_validate_changes` plus destructive `okf_apply_changes`, both accepting the same structured create/update batch grammar without requiring agents to compose YAML. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
|
|
37
43
|
|
|
38
|
-
|
|
44
|
+
`okf_validate_changes` and `okf_apply_changes` plan 1–100 operations as one future graph, including cross-batch and loaded-remote references. Validation returns a non-durable time-of-check receipt. Apply repeats planning under the process-local writer queue, stamps one server-owned `generated.at` with the configured `generated.by`, publishes the complete local batch, validates persisted state, and refreshes the index. Receipts expose bounded semantic effects, absolute targets, revisions, graph diagnostics, Git preconditions, and durability without echoing full bodies.
|
|
39
45
|
|
|
40
|
-
`
|
|
46
|
+
Optional `--git-commit` policy rejects filter declarations and hidden `assume-unchanged`/`skip-worktree` index flags, disables replace-object resolution, pins the checked-out symbolic branch, constructs an isolated index from validated bytes, and publishes its exact tree with a compare-and-swap ref update from a clean worktree. The shared index is not used to assemble the commit, so unrelated concurrently staged paths cannot enter it; only affected index paths are synchronized after publication. Determinate failures preserve matching valid working-tree files. Ambiguous outcomes, checkout changes, target replacements, and best-effort revision-checked rollback conflicts are reported explicitly; the tool never pushes.
|
|
41
47
|
|
|
42
48
|
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.
|
|
43
49
|
|
|
@@ -23,13 +23,17 @@ relations:
|
|
|
23
23
|
target: repo://test/mcp-hardening.test.js
|
|
24
24
|
- type: checked_by
|
|
25
25
|
target: repo://test/live-authoring.test.js
|
|
26
|
+
- type: checked_by
|
|
27
|
+
target: repo://test/live-authoring-correctness.test.js
|
|
28
|
+
- type: checked_by
|
|
29
|
+
target: repo://test/live-agent-workflow.test.js
|
|
26
30
|
---
|
|
27
31
|
|
|
28
32
|
# Authoring Safety
|
|
29
33
|
|
|
30
34
|
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.
|
|
31
35
|
|
|
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.
|
|
36
|
+
Concept paths must be safe relative `.md` paths inside the selected bundle. Absolute paths, parent traversal, hidden/control-plane segments such as `.git`, case-insensitive reserved `index.md` and `log.md` targets, Markdown-file ancestor segments, symbolic-link traversal, and non-directory parents are rejected.
|
|
33
37
|
|
|
34
38
|
New concepts cannot reuse a canonical Concept ID or compatibility alias. Updates are bound to the existing bundle and path and cannot change the custom-id alias.
|
|
35
39
|
|
|
@@ -37,7 +41,9 @@ Candidates must satisfy the concept format, configured relation vocabulary, and
|
|
|
37
41
|
|
|
38
42
|
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.
|
|
39
43
|
|
|
40
|
-
Direct authoring exposes one destructive
|
|
44
|
+
Direct authoring exposes a read-only batch validator and one destructive apply tool with the same structured grammar. They share the combined-future-graph planner, while apply repeats the plan under one process-local writer lock, stamps generation metadata at the server boundary, stages every file before publication, and validates persisted state. It rejects generated-file flags, `process:*` generation owners, configured generator outputs, and computation contracts.
|
|
45
|
+
|
|
46
|
+
Rollback revision-checks a published target immediately before restoring it. Detected external replacements are preserved and reported as rollback conflicts, but this is best-effort detection rather than a cross-process compare-and-swap primitive. Optional Git commits require a clean worktree before publication, reject active filter attributes and hidden `assume-unchanged`/`skip-worktree` index flags, and disable replace-object resolution. They build an isolated index directly from validated Markdown bytes, create the exact tree without mutating the shared index, publish it through a compare-and-swap ref update, synchronize only affected ordinary-index paths afterward, and never push. Commit, target, index, and durability states remain explicit when a timeout or concurrent replacement cannot be classified safely.
|
|
41
47
|
|
|
42
48
|
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.
|
|
43
49
|
|
|
@@ -27,7 +27,7 @@ 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
|
|
30
|
+
Proposal acceptance and direct live planning/apply share one process-local writer queue. Read-only batch validation returns a time-of-check preview without staging. Apply stages every candidate, checks revisions immediately before publication, validates the persisted graph, and revision-checks each published target immediately before restoring it after a failure. Ordinary failures remain all-or-none when the published bytes still belong to the batch; detected concurrent replacements are preserved and surfaced as rollback conflicts. The revision check and filesystem restore are not a cross-process compare-and-swap, so external single-writer coordination remains required. This is not crash durability or distributed coordination.
|
|
31
31
|
|
|
32
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.
|
|
33
33
|
|
|
@@ -29,9 +29,9 @@ The SDK serves the modern `2026-07-28` revision and its compatibility path for 2
|
|
|
29
29
|
|
|
30
30
|
The SDK validates protocol messages and tool arguments before application dispatch. Expected application failures return tool results with `isError: true`; unexpected implementation failures are masked. Stdout remains reserved for protocol messages.
|
|
31
31
|
|
|
32
|
-
Each indexed Markdown document is exposed as a `text/markdown` resource. The [MCP tool catalog](../interfaces/mcp-tools.md) exposes discovery, search, graph navigation, validation, remote loading,
|
|
32
|
+
Each indexed Markdown document is exposed as a `text/markdown` resource. The [MCP tool catalog](../interfaces/mcp-tools.md) exposes discovery, search, graph navigation, validation, remote loading, proposal-based authoring, and explicitly gated live batch validation/apply.
|
|
33
33
|
|
|
34
|
-
Root mode is the normal single-catalog interface and can supply the local store used by the [authoring workflow](../workflows/concept-authoring.md). Project mode remains an optional federation/configuration extension. Proposal mutation tools remain disabled unless the server starts with `--authoring`; runtime remote loading remains disabled unless it starts with `--allow-remote-tool`.
|
|
34
|
+
Root mode is the normal single-catalog interface and can supply the local store used by the [authoring workflow](../workflows/concept-authoring.md). Project mode remains an optional federation/configuration extension. Proposal mutation tools remain disabled unless the server starts with `--authoring`; live batch tools remain disabled unless it starts with `--write --actor <actor>`; runtime remote loading remains disabled unless it starts with `--allow-remote-tool`.
|
|
35
35
|
|
|
36
36
|
Remote GitHub bundles are fetched as Markdown and added to the in-memory index. They remain read only and never execute remote code. After an accepted local proposal, one reconstruction path rebuilds the index from configured local bundles, configured remote bundles, and runtime-loaded remote bundles, preserving remote concepts and relationships. The lexical search index is cached against that reconstructed OKF index, so the next query builds a fresh per-server BM25+ view without global or persisted state.
|
|
37
37
|
|
|
@@ -18,6 +18,6 @@ A standard `sources` entry may point at a bundle-local concept of type `Git Repo
|
|
|
18
18
|
|
|
19
19
|
The OKF content contains the repository's transport URL but never a machine-local checkout path or credential. The MCP host maps the repository Concept ID to an explicit checkout, bare repository, or mounted object store with `--repo <concept-id>=<path>`.
|
|
20
20
|
|
|
21
|
-
`read_git_source` resolves only declared source entries. It reads a regular blob from the pinned commit, verifies its Git object ID and SHA-256, enforces UTF-8 and byte limits, and rejects traversal, symbolic links, and submodules. It disables lazy fetches and never consults dirty working-tree bytes.
|
|
21
|
+
`read_git_source` resolves only declared source entries. It reads a regular blob from the pinned commit, verifies its Git object ID and SHA-256, enforces UTF-8 and byte limits, and rejects traversal, symbolic links, and submodules. It disables lazy fetches and never consults dirty working-tree bytes. When a blob exceeds the active limit, the structured error reports the actual size, the active and maximum limits, and whether retrying with a larger bounded request can succeed; line selection never bypasses the full-blob safety limit.
|
|
22
22
|
|
|
23
23
|
An unpinned source or missing host mapping remains discoverable but unavailable. No indexing, search, graph, or provenance operation triggers Git network access.
|
|
@@ -29,7 +29,7 @@ A reviewer then inspects the proposal and either accepts or rejects it. Acceptan
|
|
|
29
29
|
|
|
30
30
|
Invalid candidates never become proposals. A proposal that becomes invalid before acceptance remains inspectable and returns the current validation result.
|
|
31
31
|
|
|
32
|
-
For a trusted client approval boundary, `--write --actor <actor>` exposes
|
|
32
|
+
For a trusted client approval boundary, `--write --actor <actor>` exposes read-only `okf_validate_changes` and destructive `okf_apply_changes`. Agents submit structured concept fields rather than YAML. The server derives optional paths from strong same-type directory conventions or deterministic slugs, patches tags/sources/relations, stamps one generation actor and time, and validates the complete future graph. A validation receipt is a non-durable time-of-check preview; apply repeats the checks before publication. Optional Git policy pins the checked-out symbolic branch, builds one exact isolated tree from validated bytes, and compare-and-swap publishes it without pushing.
|
|
33
33
|
|
|
34
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
35
|
|
package/package.json
CHANGED
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.
|
|
11
|
+
"version": "0.7.0",
|
|
12
12
|
"packages": [
|
|
13
13
|
{
|
|
14
14
|
"registryType": "npm",
|
|
15
15
|
"identifier": "@mfdaves/okf-mcp",
|
|
16
|
-
"version": "0.
|
|
16
|
+
"version": "0.7.0",
|
|
17
17
|
"transport": {
|
|
18
18
|
"type": "stdio"
|
|
19
19
|
},
|
package/src/authoring.js
CHANGED
|
@@ -32,9 +32,16 @@ function normalizeConceptPath(value) {
|
|
|
32
32
|
if (!raw) {
|
|
33
33
|
throw new Error("Concept path is required.");
|
|
34
34
|
}
|
|
35
|
-
if (raw.startsWith("/") || raw
|
|
35
|
+
if (raw.startsWith("/") || /^[A-Za-z]:\//.test(raw) || /[\u0000-\u001f\u007f]/.test(raw)) {
|
|
36
36
|
throw new Error("Concept path must be a safe relative path.");
|
|
37
37
|
}
|
|
38
|
+
const rawParts = raw.split("/");
|
|
39
|
+
if (rawParts.some((part) => !part || part === "." || part === ".." || part.startsWith("."))) {
|
|
40
|
+
throw new Error("Concept path must be a safe relative path without empty, hidden, dot, or parent segments.");
|
|
41
|
+
}
|
|
42
|
+
if (rawParts.slice(0, -1).some((part) => part.toLowerCase().endsWith(".md"))) {
|
|
43
|
+
throw new Error("Concept path cannot place a Markdown file inside another Markdown path.");
|
|
44
|
+
}
|
|
38
45
|
const normalized = path.posix.normalize(raw);
|
|
39
46
|
if (!normalized || normalized === "." || normalized.startsWith("../") || normalized === "..") {
|
|
40
47
|
throw new Error("Concept path must stay inside the bundle.");
|
|
@@ -45,13 +52,72 @@ function normalizeConceptPath(value) {
|
|
|
45
52
|
if (!normalized.toLowerCase().endsWith(".md")) {
|
|
46
53
|
throw new Error("Concept path must end with .md.");
|
|
47
54
|
}
|
|
48
|
-
const base = path.posix.basename(normalized);
|
|
55
|
+
const base = path.posix.basename(normalized).toLowerCase();
|
|
49
56
|
if (base === "index.md" || base === "log.md") {
|
|
50
57
|
throw new Error("Concept path cannot be a reserved index.md or log.md file.");
|
|
51
58
|
}
|
|
52
59
|
return normalized;
|
|
53
60
|
}
|
|
54
61
|
|
|
62
|
+
function deriveConceptPathSuggestion(index, bundle, input) {
|
|
63
|
+
const rawPrefix = input && input.prefix
|
|
64
|
+
? normalizeSlashes(String(input.prefix).trim())
|
|
65
|
+
: "";
|
|
66
|
+
if (rawPrefix.startsWith("/") || /^[A-Za-z]:\//.test(rawPrefix)) {
|
|
67
|
+
throw new Error("Path prefix must be a safe relative path inside the bundle.");
|
|
68
|
+
}
|
|
69
|
+
const prefix = rawPrefix.replace(/\/+$/g, "");
|
|
70
|
+
if (prefix) {
|
|
71
|
+
normalizeConceptPath(`${prefix}/placeholder.md`);
|
|
72
|
+
}
|
|
73
|
+
const type = String((input && input.type) || "").trim();
|
|
74
|
+
const typePart = type === "Attested Computation"
|
|
75
|
+
? "computations"
|
|
76
|
+
: slug(type, "concept");
|
|
77
|
+
const titlePart = slug(input && input.title, typePart);
|
|
78
|
+
let parent = prefix ? `${prefix}/${typePart}` : typePart;
|
|
79
|
+
let strategy = prefix ? "explicit_prefix" : "type_slug";
|
|
80
|
+
let evidence = { matchingConcepts: 0, dominantDirectoryCount: 0, dominantDirectoryRatio: 0 };
|
|
81
|
+
|
|
82
|
+
if (!prefix && type !== "Attested Computation" && index && Array.isArray(index.documents)) {
|
|
83
|
+
const matching = index.documents.filter((document) => (
|
|
84
|
+
document
|
|
85
|
+
&& document.bundle === bundle.id
|
|
86
|
+
&& document.valid
|
|
87
|
+
&& !document.reserved
|
|
88
|
+
&& document.type === type
|
|
89
|
+
&& typeof document.path === "string"
|
|
90
|
+
));
|
|
91
|
+
const counts = new Map();
|
|
92
|
+
matching.forEach((document) => {
|
|
93
|
+
const directory = path.posix.dirname(document.path);
|
|
94
|
+
const normalizedDirectory = directory === "." ? "" : directory;
|
|
95
|
+
counts.set(normalizedDirectory, (counts.get(normalizedDirectory) || 0) + 1);
|
|
96
|
+
});
|
|
97
|
+
const dominant = Array.from(counts.entries()).sort((left, right) => (
|
|
98
|
+
right[1] - left[1] || left[0].localeCompare(right[0])
|
|
99
|
+
))[0];
|
|
100
|
+
const dominantCount = dominant ? dominant[1] : 0;
|
|
101
|
+
const ratio = matching.length ? dominantCount / matching.length : 0;
|
|
102
|
+
evidence = {
|
|
103
|
+
matchingConcepts: matching.length,
|
|
104
|
+
dominantDirectoryCount: dominantCount,
|
|
105
|
+
dominantDirectoryRatio: Number(ratio.toFixed(3)),
|
|
106
|
+
};
|
|
107
|
+
if (dominant && dominantCount >= 2 && ratio >= 0.6) {
|
|
108
|
+
parent = dominant[0];
|
|
109
|
+
strategy = "dominant_same_type_directory";
|
|
110
|
+
evidence.dominantDirectory = dominant[0] || ".";
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
return {
|
|
115
|
+
path: normalizeConceptPath([parent, `${titlePart}.md`].filter(Boolean).join("/")),
|
|
116
|
+
strategy,
|
|
117
|
+
evidence,
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
|
|
55
121
|
function renderFrontmatter(frontmatter) {
|
|
56
122
|
const values = Object.fromEntries(
|
|
57
123
|
Object.entries(frontmatter || {}).filter((entry) => entry[1] !== undefined),
|
|
@@ -119,17 +185,16 @@ class ConceptAuthoringService {
|
|
|
119
185
|
|
|
120
186
|
suggestConceptPath(input) {
|
|
121
187
|
const bundle = this.getBundle(input && input.bundle);
|
|
122
|
-
const
|
|
123
|
-
|
|
124
|
-
throw new Error("Path prefix must stay inside the bundle.");
|
|
125
|
-
}
|
|
126
|
-
const typePart = input && input.type === "Attested Computation"
|
|
127
|
-
? "computations"
|
|
128
|
-
: slug(input && input.type, "concept");
|
|
129
|
-
const titlePart = slug(input && input.title, typePart);
|
|
188
|
+
const suggestion = deriveConceptPathSuggestion(this.store.getIndex(), bundle, input || {});
|
|
189
|
+
const target = this.store.resolveConceptFile(bundle.id, suggestion.path);
|
|
130
190
|
return {
|
|
131
191
|
bundle: bundle.id,
|
|
132
|
-
path:
|
|
192
|
+
path: suggestion.path,
|
|
193
|
+
uri: `okf://${bundle.id}/${suggestion.path.replace(/\.md$/i, "")}`,
|
|
194
|
+
absolutePath: target.absolutePath,
|
|
195
|
+
available: !fs.existsSync(target.absolutePath),
|
|
196
|
+
strategy: suggestion.strategy,
|
|
197
|
+
evidence: suggestion.evidence,
|
|
133
198
|
};
|
|
134
199
|
}
|
|
135
200
|
|
|
@@ -802,6 +867,7 @@ class ConceptAuthoringService {
|
|
|
802
867
|
|
|
803
868
|
module.exports = {
|
|
804
869
|
ConceptAuthoringService,
|
|
870
|
+
deriveConceptPathSuggestion,
|
|
805
871
|
normalizeConceptPath,
|
|
806
872
|
renderConceptMarkdown,
|
|
807
873
|
renderFrontmatter,
|
package/src/cli.js
CHANGED
|
@@ -485,7 +485,7 @@ function usage() {
|
|
|
485
485
|
" --root, -r <directory> Load one official OKF bundle root.",
|
|
486
486
|
" --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
|
|
487
487
|
" --authoring Enable MCP proposal authoring tools.",
|
|
488
|
-
" --write Enable direct
|
|
488
|
+
" --write Enable direct validated-batch MCP concept writes (requires --actor).",
|
|
489
489
|
" --actor <actor> Stamp live writes with human:id, process:id, or provider/model.",
|
|
490
490
|
" --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
|
|
491
491
|
" --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
|
package/src/git-source.js
CHANGED
|
@@ -12,10 +12,13 @@ const DEFAULT_GIT_TIMEOUT_MS = 10000;
|
|
|
12
12
|
const MAX_GIT_TIMEOUT_MS = 60000;
|
|
13
13
|
|
|
14
14
|
class GitSourceError extends Error {
|
|
15
|
-
constructor(code, message) {
|
|
15
|
+
constructor(code, message, details) {
|
|
16
16
|
super(message);
|
|
17
17
|
this.name = "GitSourceError";
|
|
18
18
|
this.code = code;
|
|
19
|
+
if (details !== undefined) {
|
|
20
|
+
this.details = details;
|
|
21
|
+
}
|
|
19
22
|
}
|
|
20
23
|
}
|
|
21
24
|
|
|
@@ -27,8 +30,8 @@ function isPlainObject(value) {
|
|
|
27
30
|
return prototype === Object.prototype || prototype === null;
|
|
28
31
|
}
|
|
29
32
|
|
|
30
|
-
function sourceError(code, message) {
|
|
31
|
-
return new GitSourceError(code, message);
|
|
33
|
+
function sourceError(code, message, details) {
|
|
34
|
+
return new GitSourceError(code, message, details);
|
|
32
35
|
}
|
|
33
36
|
|
|
34
37
|
function normalizeLines(value) {
|
|
@@ -392,7 +395,13 @@ function readGitSource(source, repositoryMappings, options) {
|
|
|
392
395
|
if (size > maxBytes) {
|
|
393
396
|
throw sourceError(
|
|
394
397
|
"git_source_too_large",
|
|
395
|
-
`Git source exceeds the configured ${maxBytes} byte limit.`,
|
|
398
|
+
`Git source is ${size} bytes and exceeds the configured ${maxBytes} byte limit.`,
|
|
399
|
+
{
|
|
400
|
+
actualBytes: size,
|
|
401
|
+
limitBytes: maxBytes,
|
|
402
|
+
maxAllowedBytes: MAX_GIT_SOURCE_BYTES,
|
|
403
|
+
retryable: size <= MAX_GIT_SOURCE_BYTES,
|
|
404
|
+
},
|
|
396
405
|
);
|
|
397
406
|
}
|
|
398
407
|
|