mikser-io 9.44.0 → 9.46.0

package/docs/api-reference.md

@@ -538,6 +538,27 @@ write back a whole file built from a copy that is now stale.
 catalog's, which lags between builds — pass `diskChecksum`, or the
 `currentChecksum` a refusal hands back.
 
+### `deleteEntitySource(options)`
+
+Removes a source file with the same guards, plus the one only removal needs.
+
+```js
+const preview = await deleteEntitySource({ id: '/documents/old.md', dryRun: true })
+// preview.referencedBy → [{ id: '/documents/page.md', field: 'hero' }]
+```
+
+Takes the same addressing, `ifChecksum` and `dryRun` as the write. `referencedBy`
+reports everything still pointing at the entity — asked of the reference index
+through `lookupKeys`, so a ref by served path counts exactly as invalidation
+counts it, not just a ref by id. A delete is the one write with no content to
+inspect afterwards, which makes the preview the only chance to see its cost.
+
+### Change sets
+
+Both take `changeSet` and `summary`, grouping several writes into one unit a
+consumer can commit together and later take back together. See
+[Change sets](#change-sets-1) below.
+
 ### Advisories
 
 `contentAdvisories(entity, content)` names files a caller must not edit blind,
@@ -556,6 +577,75 @@ extension, which may render to the same destination.
 or `{ error }` — taken from the entity rather than by splitting the id, since the
 prefix is configurable and the extension may have been stripped.
 
+## Change sets
+
+Which writes belong together, and who asked for them.
+
+The engine does not otherwise care who wrote a file — a write is a write. That
+holds until something wants to undo one request without touching everything
+around it, and then it is the wrong resolution: an agent's three edits and a
+document created through the API a second later are indistinguishable, so
+removing one removes the other.
+
+```js
+await writeEntitySource({ id, content, changeSet: 'req-42', summary: 'Rewrite the hero copy' })
+await deleteEntitySource({ id: other, changeSet: 'req-42' })
+
+pendingChangeSets()
+// [{ id: 'req-42', summary: 'Rewrite the hero copy', paths: [...], deletions: [...] }]
+clearChangeSets(['req-42'])
+```
+
+| Export | Does |
+| --- | --- |
+| `withChangeSet({ changeSet, summary, principal }, fn)` | run `fn` with a set in effect |
+| `currentChangeSet()` | the set in effect, or null |
+| `recordChangeSetWrite({ changeSet, summary, principal, uri, operation, undoOf })` | attach one path to a set |
+| `pendingChangeSets()` | sets with unconsumed writes, oldest first |
+| `clearChangeSets(ids)` | drop what a consumer has committed |
+
+### Ambient, not threaded
+
+Passing an id through every write is fine for one API and hopeless across a
+plugin ecosystem — `mikser-io-drive` writes with `fs.writeFile`, a rename
+cascade goes through `writeEntity`, and every new mutating tool would have to
+remember. `withChangeSet` puts one in scope instead, and the write primitives
+attribute themselves:
+
+```js
+await withChangeSet({ changeSet: 'req-42', summary: 'Rewrite the hero copy' }, async () => {
+    await useCollection(runtime, 'documents').write('hero.md', text)   // attributed
+    await writeEntity({ uri }, { title })                             // attributed
+})
+```
+
+`useCollection().write` / `.remove` and `writeEntity` record automatically, so
+code that has never heard of change sets still produces undoable work. A plugin
+writing with raw `fs` calls `recordChangeSetWrite({ uri })` with no id and
+picks up whatever is in effect. An explicit id always wins over the ambient
+one, and a write with neither stays unclaimed.
+
+In `mikser-io-mcp`, a tool registered with `mutates: true` gets `changeSet` and
+`summary` added to its schema and its handler wrapped in `withChangeSet`
+automatically — declared once per tool rather than threaded through each write,
+because a new mutating tool that forgets the plumbing is one whose edits
+silently cannot be undone.
+
+Paths come back repo-relative and POSIX-separated, ready for a git pathspec.
+
+**Not a transaction.** Nothing is held back, nothing rolls back on failure, and
+a half-finished set is a real set containing what actually landed. It is a
+label on work that already happened, which is what makes it safe on a write
+path that must never block. A path is claimed only after the write succeeds —
+claiming on intent would make a write that never happened undoable, and undoing
+it would delete whatever is actually at that path.
+
+**Unclaimed writes stay unclaimed.** A consumer must still handle them; they
+happened, and losing them would be worse than not attributing them.
+`mikser-io-git` commits claimed sets to their own scoped commits and sweeps the
+rest into unattributed ones, which is what lets it offer undo for the first and
+not the second.
+
 ## Search
 
 `queryEntities` sifts **meta**. `searchEntities` answers the other question —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.44.0",
+  "version": "9.46.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/changeset.js

@@ -21,8 +21,35 @@
 // attribute them.
 
 import path from 'node:path'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import runtime from './runtime.js'
 
+// The change set in effect for the current call.
+//
+// Threading an id through every write is fine for one API and hopeless across
+// a plugin ecosystem: mikser-io-drive writes with fs.writeFile, forms writes
+// its own entities, and each new mutating tool would have to remember. An
+// ambient context means a caller declares the set ONCE and everything written
+// underneath is attributed, including by code that has never heard of change
+// sets.
+const changeSetContext = new AsyncLocalStorage()
+
+// Run `fn` with a change set in effect. Writes inside it are attributed to
+// that set unless they name a different one explicitly.
+export function withChangeSet(set, fn) {
+    if (!set?.changeSet) return fn()
+    return changeSetContext.run({
+        changeSet: set.changeSet,
+        summary: set.summary ?? null,
+        principal: set.principal ?? null,
+        undoOf: set.undoOf ?? null,
+    }, fn)
+}
+
+export function currentChangeSet() {
+    return changeSetContext.getStore() ?? null
+}
+
 function store() {
     runtime.changeSets ??= new Map()
     return runtime.changeSets
@@ -45,6 +72,14 @@ function relativeToWorkingFolder(uri) {
 // undo needs "changed the hero text on the devices page", not a file count.
 // First one wins: later writes in the same set are the same request.
 export function recordChangeSetWrite({ changeSet, summary, principal, uri, operation = 'write', undoOf } = {}) {
+    // An explicit id always wins; otherwise take whatever set is in effect.
+    // A write with neither stays unclaimed, which is the correct outcome for
+    // an API or human write that no request owns.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+    undoOf ??= ambient?.undoOf
     if (!changeSet || !uri) return null
     const rel = relativeToWorkingFolder(uri)
     // Outside the working folder there is nothing a repo-scoped consumer can

package/src/utils.js

@@ -11,6 +11,7 @@ import yaml from 'yaml'
 import { contentType } from 'mime-types'
 import runtime from './runtime.js'
 import { trackedInfo, untrack, recordReads } from './track.js'
+import { recordChangeSetWrite } from './changeset.js'
 
 // Stable content fingerprint for entities — used by manifest snapshots,
 // engine mutation tracking, and the layouts dispatcher's hash-aware
@@ -790,6 +791,10 @@ export async function writeEntity(entity, patch = {}) {
 
     await mkdir(path.dirname(entity.uri), { recursive: true })
     await writeFile(entity.uri, newContent, 'utf8')
+    // The other file-writing primitive. A rename cascade rewrites every
+    // referring file through here, which is the largest fan-out any single
+    // request has and therefore the one most worth being able to take back.
+    recordChangeSetWrite({ uri: entity.uri })
 
     return entity.uri
 }
@@ -1104,11 +1109,19 @@ export function useCollection(runtime, name) {
             const uri = resolveWithin(relativePath)
             await mkdir(path.dirname(uri), { recursive: true })
             await writeFile(uri, content, 'utf8')
+            // Attributed to whatever change set is in effect, if any. Hooked
+            // at the lowest write primitive so a plugin that has never heard
+            // of change sets still produces undoable work — the alternative is
+            // every writer remembering, and the one that forgets is the one
+            // whose edit cannot be taken back.
+            recordChangeSetWrite({ uri })
             return uri
         },
 
         async remove(relativePath) {
-            await unlink(resolveWithin(relativePath))
+            const uri = resolveWithin(relativePath)
+            await unlink(uri)
+            recordChangeSetWrite({ uri, operation: 'delete' })
         },
     }
 }

package/src/write.js

@@ -22,9 +22,9 @@ import { readdir } from 'node:fs/promises'
 
 import runtime from './runtime.js'
 import { readEntity, findEntities } from './catalog.js'
-import { useCollection, checksum, readEntityContent } from './utils.js'
+import { useCollection, checksum, readEntityContent, lookupKeys } from './utils.js'
 import { nextCycleId, whenCycleCompletes } from './report.js'
-import { recordChangeSetWrite } from './changeset.js'
+import { recordChangeSetWrite, currentChangeSet } from './changeset.js'
 
 // How far into a file to look for a marker. A header nobody reads is not a
 // header; one buried 200 lines down is not either.
@@ -172,6 +172,14 @@ export async function writeEntitySource({
     summary,
     principal,
 } = {}) {
+    // An explicit id wins; otherwise inherit whatever set is in effect, so the
+    // response can name the set a caller would undo even when the caller never
+    // passed one.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+
     if (id) {
         const located = await locateEntityFile(id)
         if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }
@@ -287,3 +295,139 @@ export async function writeEntitySource({
     if (awaitCycle) result.report = await whenCycleCompletes(cycleId)
     return result
 }
+
+// Remove a source file, with the same checks the write has plus the one that
+// only matters for removal: what still points at it.
+//
+// Delete is the more destructive operation and had the fewest guards — no
+// precondition, no preview, no advisory, and nothing at all about the
+// references that break when an entity other documents point at disappears.
+//
+// Same contract as writeEntitySource: never throws for an expected outcome.
+export async function deleteEntitySource({
+    id,
+    collection,
+    relativePath,
+    ifChecksum,
+    dryRun = false,
+    changeSet,
+    summary,
+    principal,
+} = {}) {
+    // An explicit id wins; otherwise inherit whatever set is in effect, so the
+    // response can name the set a caller would undo even when the caller never
+    // passed one.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+
+    if (id) {
+        const located = await locateEntityFile(id)
+        if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }
+        if (collection && collection !== located.collection) {
+            return {
+                ok: false,
+                refused: 'collection-mismatch',
+                error: `id ${id} is in collection ${located.collection}, not ${collection}. Pass one or the other.`,
+            }
+        }
+        collection ??= located.collection
+        relativePath ??= located.relativePath
+    }
+    if (!collection || !relativePath) {
+        return {
+            ok: false,
+            refused: 'incomplete-target',
+            error: 'Pass either `id` (for an existing entity) or both `collection` and `relativePath`.',
+        }
+    }
+
+    let handle
+    let uri
+    try {
+        handle = useCollection(runtime, collection)
+        uri = handle.resolveWithin(relativePath)
+    } catch (err) {
+        return { ok: false, refused: 'invalid-target', collection, relativePath, error: err.message }
+    }
+
+    const existing = id ? await readEntity({ id }) : await findEntityAtUri(uri)
+    const currentChecksum = await fileChecksum(uri)
+    if (currentChecksum === null) {
+        return {
+            ok: false, refused: 'not-found', collection, relativePath,
+            error: 'Nothing on disk at that path.',
+        }
+    }
+
+    // Everything that would be left pointing at nothing. Asked of the
+    // reference index rather than of the text, so it sees a `$`-ref by served
+    // path exactly the way invalidation does.
+    const referencedBy = existing ? referrersOf(existing) : []
+    const wouldAffect = existing?.id ? (runtime.manifest?.affectedBy?.(existing) ?? []) : []
+
+    if (dryRun) {
+        return {
+            ok: true, dryRun: true, collection, relativePath,
+            id: existing?.id ?? null,
+            exists: true,
+            currentChecksum,
+            referencedBy,
+            wouldAffect,
+            wouldAffectCount: wouldAffect.length,
+            ...(referencedBy.length ? {
+                warning: `${referencedBy.length} entit${referencedBy.length === 1 ? 'y' : 'ies'} reference this. `
+                    + 'Deleting it leaves those references pointing at nothing.',
+            } : {}),
+        }
+    }
+
+    if (ifChecksum !== undefined && ifChecksum !== currentChecksum) {
+        return {
+            ok: false,
+            refused: 'checksum-mismatch',
+            collection, relativePath,
+            expectedChecksum: ifChecksum,
+            currentChecksum,
+            hint: 'The file changed since you read it. Re-read it before deciding to delete it, and retry with '
+                + '`currentChecksum` from THIS response.',
+        }
+    }
+
+    await handle.remove(relativePath)
+    if (changeSet) recordChangeSetWrite({ changeSet, summary, principal, uri, operation: 'delete' })
+
+    return {
+        ok: true, collection, relativePath,
+        id: existing?.id ?? null,
+        deletedChecksum: currentChecksum,
+        cycleId: nextCycleId(),
+        ...(changeSet ? { changeSet } : {}),
+        referencedBy,
+        ...(referencedBy.length ? {
+            warning: `${referencedBy.length} entit${referencedBy.length === 1 ? 'y' : 'ies'} still reference this.`,
+        } : {}),
+    }
+}
+
+// Who points at this entity, by any of the keys it can be referenced by.
+//
+// `lookupKeys` rather than the id alone: content refers to served paths far
+// more often than to catalog ids, and asking only about the id would report a
+// widely-linked image as unreferenced.
+function referrersOf(entity) {
+    const refs = runtime.refs
+    if (!refs?.inboundFor) return []
+    const found = new Map()
+    for (const key of [entity.id, ...(lookupKeys(entity) ?? [])]) {
+        if (!key) continue
+        let inbound = []
+        try { inbound = refs.inboundFor(key) ?? [] } catch { continue }
+        for (const ref of inbound) {
+            if (!ref?.id || ref.id === entity.id) continue
+            found.set(ref.id, { id: ref.id, ...(ref.field ? { field: ref.field } : {}) })
+        }
+    }
+    return [...found.values()]
+}