mikser-io-mcp 2.0.0 → 2.1.0

package/README.md

@@ -7,7 +7,7 @@ MCP (Model Context Protocol) substrate and tools for [mikser-io](https://github.
 - **The MCP substrate** — `createMcpSubstrate`, per-session McpServer + transport via `mountMcpOnExpress`, the pino-to-MCP log bridge `wireLoggerToMcp`. Other plugins compose against `runtime.options.mcp` to register their own tools and resources.
 - **Built-in resources** — `mikser://config`, `mikser://lifecycle`, `mikser://logs`, `mikser://server`. Read-only introspection any MCP client can use.
 - **Built-in tools**
-  - *Catalog* — `mikser_query_entities`, `mikser_read_entity`, `mikser_update_entity`, `mikser_delete_entity`, `mikser_render`, over the engine's public catalog API.
+  - *Catalog* — `mikser_query_entities`, `mikser_read_entity`, `mikser_edit_entity`, `mikser_update_entity`, `mikser_delete_entity`, `mikser_render`, over the engine's public catalog API.
   - *Finding things* — `mikser_search` locates a string across entity meta, source files, and (with `in: ["output"]`) the BUILT files, reporting occurrences per page — and with `attribute: true`, which source emitted each hit. That is how you find content you can only describe by what it says, and how you size a change to anything shared before making it.
   - *Working backwards* — `mikser_which` takes a built destination and returns the source that produced it: the field path and line/column a value was written at, or the line in file content where it appears — each occurrence flagged by whether the string BEGINS its line, which separates a declaration from a use in any text format without a per-language grammar. Each answer is labelled by how it was reached — `meta-field` and `source-content` are RECORDED (the engine's own `refClosure` says this render consumed that entity, and the position comes from parsing its source), `scan` is not. It reaches values that appear nowhere in a page's own document, which is most of a shared nav or footer.
   - *References* — `mikser_refs_inbound` / `mikser_refs_outbound` / `mikser_refs_broken` / `mikser_refs_rename`, from `runtime.refs`.
@@ -40,8 +40,36 @@ piping into `jq` works; exit status is 0 / 1 (the tool reported an error) /
 
 ## Editing content
 
-`mikser_update_entity` writes the WHOLE file — there is no partial-edit or
-patch mode. Three fields make that safe to do without a shell on the box:
+Two tools write source files, and which one you reach for is the whole point.
+
+`mikser_edit_entity` changes PART of a file: you name the text to replace and
+everything else is left exactly as it is, byte for byte. Use it for any change
+to an existing file.
+
+```js
+await mikser_edit_entity({
+    id: '/documents/pricing.md',
+    find: 'price: 1200',        // must match exactly once
+    replace: 'price: 1400',
+})
+```
+
+`find` must appear exactly once, or the edit is refused and told how many times
+it appeared — extend it with the surrounding lines, or pass `all: true` for a
+rename that really should hit every one. An anchor that appears nowhere is
+refused too: the file is not what you read. And the RESULT must still parse in
+the file's format — a broken YAML block is caught before it lands, which is the
+check a whole-file write has no way to make. None of those come back as
+errors; each is a result carrying what the next attempt needs.
+
+This exists because rewriting a whole file to change one line means re-emitting
+every other line, and a line dropped on the way looks downstream exactly like a
+line someone deleted on purpose. `ifChecksum` catches a stale read; nothing
+catches a lossy write.
+
+`mikser_update_entity` writes the WHOLE file. Use it to CREATE a file, or when
+you are genuinely replacing most of one. Three fields make that safe to do
+without a shell on the box:
 
 ```js
 const page = await mikser_read_entity({ id: '/styles/tokens/buttons.css', include: ['content', 'positions'] })

package/index.js

@@ -50,7 +50,9 @@ import {
     cycleHistory,
     checksum as fileChecksumOf,
     writeEntitySource,
+    editEntitySource,
     withChangeSet,
+    withPrincipal,
     describeAuthority,
     inventory,
     actingRole,
@@ -237,7 +239,14 @@ function wrapMutatingHandler(handler) {
                 // more calls can join it, and only it knows when that stops.
                 closeOnReturn: !changeSet,
             },
-            () => handler(toolArgs, ...rest),
+            // The REAL principal, alongside the display string above. Those
+            // are two different things and the difference matters: the string
+            // is for the log, and asking `hasCapability` about it reads
+            // `undefined.capabilities`, takes the not-capability-scoped
+            // branch, and returns true for everything. Establishing the
+            // object is what lets the write primitives refuse.
+            () => withPrincipal(authContext.getStore()?.principal ?? null,
+                () => handler(toolArgs, ...rest)),
         )
         // Report the id back, whatever shape the tool's own result takes.
         //
@@ -2183,7 +2192,8 @@ export function mcp(options = {}) {
 
         mcp.simpleTool(
             'mikser_update_entity',
-            'Create or update a content file inside a mikser collection. Writes the WHOLE file — there is no partial-edit or patch mode, so send the complete intended contents. The file lands on disk and the next lifecycle cycle picks it up.\n\n'
+            'Create or update a content file inside a mikser collection. Writes the WHOLE file: send the complete intended contents, because anything you leave out is deleted.\n\n'
+            + 'Use this to CREATE a file, or when you are rewriting most of one. To change part of an existing file use mikser_edit_entity instead — it changes only the text you name, so a long file cannot lose a line you did not mean to touch.\n\n'
             + 'Pass `ifChecksum` with the checksum you got from mikser_read_entity to make the write conditional: if the file has changed since you read it the write is REFUSED and the response carries `currentChecksum`, so a blind whole-file rewrite cannot silently discard someone else\'s edit. Without it the write is unconditional.\n\n'
             + 'The response returns the resulting `checksum` (pass it as the next `ifChecksum`), the `cycleId` your write will be picked up by, and `siblingDestinations` when another file could render to the same place (e.g. index.md beside index.yml — whichever renders last wins and the other output is discarded).\n\n'
             + 'Pass `await: true` to block until that cycle finishes and get its build report back, so one call tells you what your edit invalidated instead of writing and guessing.',
@@ -2239,6 +2249,69 @@ export function mcp(options = {}) {
             { mutates: true },
         )
 
+        mcp.simpleTool(
+            'mikser_edit_entity',
+            'Change PART of an existing content file, by naming the text to change. Everything you do not name is '
+            + 'left exactly as it is — byte for byte, including whitespace, line endings and anything further down '
+            + 'the file you never read.\n\n'
+            + 'Prefer this over mikser_update_entity for any change to an existing file. A whole-file write makes you '
+            + 're-emit the entire document to change one line, and a line dropped on the way looks downstream exactly '
+            + 'like a line someone deleted on purpose.\n\n'
+            + '`find` must appear EXACTLY ONCE. If it appears more than once the edit is refused and the response '
+            + 'says how many times: extend `find` with the surrounding lines until it is unique, or pass `all: true` '
+            + 'to change every occurrence. If it appears nowhere the edit is refused too — the file is not what you '
+            + 'read, so re-read it rather than guessing.\n\n'
+            + 'The result must also still PARSE in the file\'s format (YAML frontmatter, a .yml data file, whatever '
+            + 'the site has registered). If it would not, nothing is written and the response carries the parser\'s '
+            + 'complaint. This is the check a whole-file write cannot offer.\n\n'
+            + 'Copy `find` from mikser_read_entity output verbatim, including indentation. An anchor assembled from '
+            + 'memory is the usual reason for a refusal.',
+            {
+                id:           z.string().optional().describe('Catalog id of the entity to edit (e.g. "/blog/launch.md"). Alternative to collection + relativePath.'),
+                collection:   z.string().optional().describe('Collection name (e.g. "documents"). Required unless `id` is given.'),
+                relativePath: z.string().optional().describe('Path relative to the collection folder. Required unless `id` is given.'),
+                find:         z.string().describe('The EXACT text to replace, copied from the file. Must match once (or pass `all`). Include enough surrounding lines to be unique — a bare word usually is not.'),
+                replace:      z.string().optional().describe('The text to put in its place. Omit or pass "" to DELETE the matched text. Match the surrounding indentation; nothing reindents it for you.'),
+                all:          z.boolean().optional().describe('Replace every occurrence instead of refusing an ambiguous one. Use for a rename that really should hit all of them; the response reports `replacements`.'),
+                ifChecksum:   z.string().optional().describe('Precondition: only edit if the file\'s current DISK checksum equals this. Use `diskChecksum` from mikser_read_entity. Optional here — the anchor is itself a check on the file being what you read.'),
+                await:        z.boolean().optional().describe('Block until the cycle that picks up this edit completes, and return its build report as `report`.'),
+                dryRun:       z.boolean().optional().describe('Write NOTHING, but still resolve the anchor: refusals are reported exactly as they would be. Returns `wouldAffect` — every destination that would re-render.'),
+            },
+            async ({ id, collection, relativePath, find, replace = '', all, ifChecksum, await: awaitCycle, dryRun }) => {
+                try {
+                    if (!dryRun) {
+                        const refusal = refuseIfExpiringWithin(
+                            awaitCycle ? 120 : 15,
+                            awaitCycle ? 'an edit that then waits for a build cycle' : 'an edit')
+                        if (refusal) return refusal
+                    }
+
+                    const result = await editEntitySource({
+                        id, collection, relativePath, find, replace, all, ifChecksum, dryRun, awaitCycle,
+                    })
+
+                    // The anchor refusals are NOT errors. Each one carries what
+                    // the next attempt needs — the occurrence count, the
+                    // parser's complaint, the current checksum — and an error
+                    // string is where that goes to die. A caller that gets
+                    // `refused: 'anchor-ambiguous'` with `occurrences: 4` can
+                    // fix its own anchor; one that gets a red failure retries
+                    // the same call or falls back to rewriting the whole file,
+                    // which is the outcome this tool exists to avoid.
+                    const recoverable = ['anchor-not-found', 'anchor-ambiguous',
+                                         'would-not-parse', 'checksum-mismatch']
+                    if (!result.ok && !recoverable.includes(result.refused)) {
+                        return fail(result.error ?? result.refused)
+                    }
+                    return ok(result)
+                } catch (err) {
+                    logger.error('MCP mikser_edit_entity error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+            { mutates: true },
+        )
+
         mcp.simpleTool(
             'mikser_delete_entity',
             'Remove a content file from a mikser collection. Deletes the source file; the next lifecycle cycle prunes its rendered outputs from the manifest.\n\n'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP (Model Context Protocol) substrate and tools for mikser-io. Extracted from core to iterate on its own release cadence.",
   "main": "index.js",
   "type": "module",
@@ -42,11 +42,11 @@
     "minimatch": "^10.0.3"
   },
   "peerDependencies": {
-    "mikser-io": "^10.0.0",
+    "mikser-io": "^10.14.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "mikser-io": "file:../mikser-io",
+    "mikser-io": "^10.14.0",
     "zod": "^4.0.0"
   }
 }