mikser-io-git 2.2.0 → 2.3.0

package/README.md

@@ -37,6 +37,59 @@ mikser's API and MCP endpoints can write to **any registered collection**, not j
 
 **This is meant for a deployment target this plugin (and mikser) exclusively manages — not a developer's actively-edited local checkout.** Bootstrap checks out and holds the write branch for the ENTIRE working folder, not just the collections in `paths`. Point this at a developer's own local clone of the project and it will switch their currently-checked-out branch out from under them — same risk that existed before, just now at the scope of the whole project directory instead of one subfolder. A server deployment where nobody manually runs `git` in that checkout is the intended shape.
 
+## Undo (MCP only)
+
+An agent's request is one **change set**: however many files it wrote, committed
+together, stamped with a `Mikser-Change-Set` trailer and the agent's own summary
+as the subject. `mikser_changes` lists them; `mikser_undo` takes one back.
+
+```
+mikser_changes                     → recent change sets, newest first
+mikser_undo({ id, dryRun: true })  → what it would do, touching nothing
+mikser_undo({ id, dryRun: false }) → apply it
+```
+
+**Only agent writes are undoable.** API writes and human edits are committed
+too — the durable log never drops anything — but into unattributed sweep
+commits with no trailer, and the trailer is the permission boundary. Those
+callers have git; an undo they could reach would be an undo able to remove work
+it never made.
+
+**It removes a contribution, it does not restore a snapshot.** Documents added
+through the API since, and edits made by hand, are kept. The undo lands as an
+ordinary forward commit, so history is never rewritten, the deploy branch is
+never force-pushed, and the undo is itself an undoable change set.
+
+Two independent things stop an undo, and they need different answers:
+
+| | means |
+| --- | --- |
+| `conflict` | a later change edited the same content — it cannot be applied automatically, and no `force` overrides it |
+| `dangling` | something added since references what this undo would REMOVE |
+
+The second is the dangerous one. Git applies it perfectly cleanly and the site
+breaks anyway, because the new document points at a layout that no longer
+exists — so the check runs against the engine's reference index rather than
+against the patch. `force: true` proceeds regardless; nothing bypasses a
+conflict.
+
+A dry run and a refusal never touch the working folder. The patch is tested
+with `git apply --check` against a copy in the system temp dir, because a
+half-applied revert in a deployed checkout means the build stops — an undo that
+takes the site down is worse than the change it was undoing.
+
+### Why the commit scope matters
+
+Staging by folder is what the durable-log sweep does, and it is wrong for a
+change set. If an agent edits one document while a second is created through
+the API a moment later, a folder-scoped `git add` puts both in the agent's
+commit — and undoing the agent then deletes the API's document. Change-set
+commits stage exactly the paths that set wrote, so the commit's contents match
+its label.
+
+Requires the `mcp` plugin. Without it the tools are not registered and the
+plugin behaves exactly as before.
+
 ## Install
 
 ```bash

package/index.js

@@ -71,6 +71,9 @@ function withGuard(logger, what, fn) {
 }
 
 
+import { pendingChangeSets, clearChangeSets } from 'mikser-io'
+import { registerUndoTools } from './lib/mcp.js'
+
 export function git(options = {}) {
     const {
         url, paths, forge, targetBranch, writeBranch,
@@ -95,7 +98,17 @@ export function git(options = {}) {
         async function runSyncPass(logger) {
             debounceState = IDLE_DEBOUNCE_STATE
             try {
-                const { committed } = await commitAndPushWriteBranch(folder, { paths, writeBranch, message, author, token })
+                // Claimed sets are drained only once their paths are actually
+                // committed. A set whose commit throws stays pending and is
+                // retried next pass rather than silently losing attribution.
+                const claimed = pendingChangeSets()
+                const consumed = []
+                const { committed } = await commitAndPushWriteBranch(folder, {
+                    paths, writeBranch, message, author, token,
+                    changeSets: claimed,
+                    onCommitted: (id) => consumed.push(id),
+                })
+                clearChangeSets(consumed)
                 if (!committed) return
                 logger.info('git: committed + pushed to %s', writeBranch)
 
@@ -160,6 +173,18 @@ export function git(options = {}) {
                 targetBranch, forge,
             )
 
+            // Undo is an MCP-only surface. API and human writes are not
+            // attributed and are deliberately not undoable — those callers
+            // have git, and an undo they could reach would be an undo that
+            // could remove someone else's work.
+            if (runtime.options.mcp) {
+                registerUndoTools(runtime.options.mcp, {
+                    folder, writeBranch, runtime, useLogger,
+                    isInert: () => inert,
+                    sync: () => enqueueGit(() => runSyncPass(useLogger())),
+                })
+            }
+
             // Inbound polling — watch mode only; a one-shot build has no
             // "later" to pull into. Webhook delivery is not implemented
             // (see README); poll is the only supported inbound trigger.

package/lib/changeset-commit.js

@@ -0,0 +1,59 @@
+// The trailer format that makes a commit undoable.
+//
+// Trailers rather than tags or notes: a tag per change set means thousands of
+// refs, and notes are not fetched by default so they vanish on the next clone.
+// Trailers are ordinary commit-message lines, they survive every normal git
+// operation, and `git log --grep` finds them.
+//
+// The change-set id is also the PERMISSION boundary, not only the grouping
+// key. Undo reverts commits carrying one and never touches the unattributed
+// sweep commits, so a human's hand edit or an API write cannot be removed by
+// an agent that did not make it.
+
+export const CHANGE_SET_TRAILER = 'Mikser-Change-Set'
+export const PRINCIPAL_TRAILER  = 'Mikser-Principal'
+export const UNDO_TRAILER       = 'Mikser-Undo-Of'
+
+export function changeSetTrailers(set) {
+    const lines = [`${CHANGE_SET_TRAILER}: ${set.id}`]
+    if (set.principal) lines.push(`${PRINCIPAL_TRAILER}: ${set.principal}`)
+    if (set.undoOf)    lines.push(`${UNDO_TRAILER}: ${set.undoOf}`)
+    return lines.join('\n')
+}
+
+// Parse `git log` output into change sets, newest first.
+//
+// One record per SET rather than per commit: a set can span several commits
+// when writes arrive across cycles, and undo has to remove all of them or it
+// removes half a request.
+export function parseChangeSetLog(raw) {
+    const sets = new Map()
+    for (const block of String(raw ?? '').split('\x1e').filter(b => b.trim())) {
+        const [sha, at, subject, ...bodyLines] = block.split('\x1f')
+        const body = bodyLines.join('\x1f')
+        const id = matchTrailer(body, CHANGE_SET_TRAILER)
+        if (!id) continue
+        let set = sets.get(id)
+        if (!set) {
+            set = {
+                id,
+                summary: subject?.trim() || null,
+                principal: matchTrailer(body, PRINCIPAL_TRAILER),
+                undoOf: matchTrailer(body, UNDO_TRAILER),
+                at: Number(at) * 1000,
+                commits: [],
+            }
+            sets.set(id, set)
+        }
+        // Log order is newest-first; a set's commits are recorded oldest-first
+        // so a revert can walk them newest-first without re-sorting.
+        set.commits.unshift(sha)
+        set.at = Math.max(set.at, Number(at) * 1000)
+    }
+    return [...sets.values()]
+}
+
+function matchTrailer(body, name) {
+    const m = new RegExp(`^${name}:\\s*(.+)$`, 'm').exec(body ?? '')
+    return m ? m[1].trim() : null
+}

package/lib/git.js

@@ -10,6 +10,9 @@
 
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
 
 const execFileAsync = promisify(execFile)
 
@@ -144,6 +147,73 @@ export async function addAll(folder, paths) {
     await run(folder, ['add', '-A', ...pathspecArgs(paths)])
 }
 
+// Stage an explicit list of files — the change-set path. Distinct from
+// addAll's folder pathspec on purpose: this stages what a request wrote and
+// nothing that merely happened to be dirty beside it.
+//
+// `--` separates paths from revisions so a file named like a branch cannot be
+// reinterpreted, and `-A` keeps deletions staged as deletions.
+export async function addPaths(folder, files) {
+    if (!files?.length) return
+    await run(folder, ['add', '-A', '--', ...files])
+}
+
+// The reverse patch for a commit: the diff from it back to its parent.
+//
+// This is what makes a dry run possible at all. `git revert` has no
+// --dry-run, so the choice is to attempt it in the live working folder and
+// deal with a conflicted tree — which for a deployed site means the build
+// stops — or to compute the patch and ask `git apply --check` whether it
+// would land. The second never touches the tree.
+export async function reversePatch(folder, sha, files) {
+    const args = ['diff', '--binary', sha, `${sha}^`]
+    if (files?.length) args.push('--', ...files)
+    return await run(folder, args)
+}
+
+// Would this patch apply cleanly? Changes nothing either way.
+export async function patchApplies(folder, patch) {
+    if (!patch?.trim()) return true
+    return await withPatchFile(patch, async (file) => {
+        try {
+            await run(folder, ['apply', '--check', '--binary', file])
+            return true
+        } catch {
+            return false
+        }
+    })
+}
+
+export async function applyPatch(folder, patch) {
+    if (!patch?.trim()) return
+    await withPatchFile(patch, (file) => run(folder, ['apply', '--binary', file]))
+}
+
+// The patch goes to the system temp dir, never inside the repo: a stray file
+// in the working folder is one the plugin's own sweep would commit.
+async function withPatchFile(patch, fn) {
+    const dir = await mkdtemp(path.join(tmpdir(), 'mikser-git-patch-'))
+    const file = path.join(dir, 'undo.patch')
+    try {
+        await writeFile(file, patch.endsWith('\n') ? patch : `${patch}\n`, 'utf8')
+        return await fn(file)
+    } finally {
+        await rm(dir, { recursive: true, force: true })
+    }
+}
+
+// Commits carrying a change-set trailer, newest first, with unit separators
+// that cannot occur in a commit message.
+export async function logChangeSets(folder, { branch, limit = 50, id } = {}) {
+    const args = [
+        'log', branch ?? 'HEAD',
+        `--max-count=${Math.max(1, Math.min(limit, 500))}`,
+        '--format=%H%x1f%at%x1f%s%x1f%b%x1e',
+        '--grep', id ? `^Mikser-Change-Set: ${id}$` : '^Mikser-Change-Set: ',
+    ]
+    return await run(folder, args)
+}
+
 export async function commit(folder, message, { author } = {}) {
     const args = ['commit', '-m', message]
     if (author?.name)  args.push('--author', `${author.name} <${author.email ?? ''}>`)

package/lib/mcp.js

@@ -0,0 +1,141 @@
+// The undo surface, deliberately MCP-only.
+//
+// API and human writes are not attributed and are not undoable here. That is
+// the scope, not a limitation to fix later: those callers have git, and an
+// undo they could reach would be an undo able to remove work it never made.
+// The change-set trailer is the permission boundary — nothing without one is
+// reachable from these tools.
+
+import { z } from 'zod'
+import { recordChangeSetWrite } from 'mikser-io'
+
+import { listChangeSets, previewUndo } from './undo.js'
+import * as git from './git.js'
+
+const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] })
+const fail = (message) => ({ content: [{ type: 'text', text: message }], isError: true })
+
+export function registerUndoTools(mcp, { folder, writeBranch, runtime, useLogger, isInert, sync }) {
+    if (!mcp) return
+    const logger = useLogger?.()
+
+    mcp.simpleTool(
+        'mikser_changes',
+        'List recent change sets — the units of work an agent can undo. Each is one request, however many files '
+        + 'it wrote, with the summary given when it was made.\n\n'
+        + 'Only agent writes appear. Documents created through the API and files edited by hand are committed too, '
+        + 'but unattributed and deliberately not undoable from here — reverting them would remove work this tool '
+        + 'has no claim on.',
+        {
+            limit: z.number().int().positive().max(50).optional()
+                .describe('How many change sets to list, newest first. Default 20.'),
+        },
+        async ({ limit = 20 } = {}) => {
+            if (isInert?.()) return fail('git: plugin is inert after a bootstrap refusal — no history to read.')
+            try {
+                const sets = await listChangeSets(folder, { branch: writeBranch, limit })
+                return ok({
+                    count: sets.length,
+                    changes: sets.map(set => ({
+                        id: set.id,
+                        summary: set.summary,
+                        at: new Date(set.at).toISOString(),
+                        files: set.commits.length,
+                        ...(set.principal ? { by: set.principal } : {}),
+                        ...(set.undoOf ? { undoOf: set.undoOf } : {}),
+                    })),
+                    next: 'Pass an `id` to mikser_undo with dryRun first — it reports whether the undo applies '
+                        + 'cleanly and whether anything added since depends on what it would remove.',
+                })
+            } catch (err) {
+                logger?.error('git: mikser_changes failed — %s', err.stderr || err.message)
+                return fail(err.stderr || err.message)
+            }
+        },
+    )
+
+    mcp.simpleTool(
+        'mikser_undo',
+        'Take back one change set, keeping everything that happened after it.\n\n'
+        + 'This is not a restore to a previous state: documents added through the API since, and edits made by '
+        + 'hand, are kept. Only the named change set\'s contribution is removed, as an ordinary forward commit — '
+        + 'so history is never rewritten, the deploy branch never has to be force-pushed, and the undo is itself '
+        + 'an undoable change set.\n\n'
+        + 'ALWAYS dryRun first. Two independent things can stop an undo, and they need different answers: a later '
+        + 'edit to the same content makes it inapplicable (`conflict`), and a document added since that references '
+        + 'something this undo REMOVES makes it destructive (`dangling`). The second is the dangerous one — git '
+        + 'applies it cleanly and the site breaks anyway, which is why the reference graph is consulted rather '
+        + 'than just the patch.',
+        {
+            id:     z.string().describe('Change set id, from mikser_changes.'),
+            dryRun: z.boolean().optional().describe('Report what the undo would do and change nothing. Default true — pass false to actually apply it.'),
+            force:  z.boolean().optional().describe('Apply even when the undo would leave references dangling. Never bypasses a conflict, which cannot be applied at all.'),
+        },
+        async ({ id, dryRun = true, force = false } = {}) => {
+            if (isInert?.()) return fail('git: plugin is inert after a bootstrap refusal — refusing to touch the folder.')
+            if (!id) return fail('id is required')
+            try {
+                const preview = await previewUndo(folder, { id, branch: writeBranch, runtime })
+                if (!preview.ok) return ok(preview)
+
+                const { patch, ...report } = preview
+                if (dryRun) {
+                    return ok({
+                        ...report, dryRun: true,
+                        wouldApply: preview.applies && (!preview.dangling.length || force),
+                        next: preview.applies
+                            ? 'Call again with dryRun: false to apply.'
+                            : 'This one cannot be applied automatically. Say so plainly rather than trying '
+                                + 'variations — the content it touched has moved on.',
+                    })
+                }
+
+                // A patch that does not apply is refused outright. Attempting
+                // it would leave the working folder half-changed, and for a
+                // deployed site that means the build stops — an undo that
+                // takes the site down is worse than the change it undoes.
+                if (!preview.applies) {
+                    return ok({ ...report, ok: false, refused: 'conflict' })
+                }
+                if (preview.dangling.length && !force) {
+                    return ok({
+                        ...report, ok: false, refused: 'would-dangle',
+                        next: 'Pass force: true only if removing those references is intended.',
+                    })
+                }
+
+                await git.applyPatch(folder, patch)
+
+                // Recorded as its own change set so the commit carries a
+                // trailer and the undo can itself be undone.
+                const undoId = `undo-${id}-${preview.set.commits}-${Math.round(preview.set.at)}`
+                for (const rel of preview.touched) {
+                    recordChangeSetWrite({
+                        changeSet: undoId,
+                        summary: `Undo: ${preview.set.summary ?? id}`,
+                        principal: 'agent',
+                        undoOf: id,
+                        uri: `${runtime.options.workingFolder}/${rel}`,
+                    })
+                }
+
+                // The files are on disk now; the engine's watcher will pick
+                // them up. Nudging the sync pass means the undo reaches the
+                // remote without waiting for the next debounce window.
+                sync?.()
+
+                return ok({
+                    ok: true, undone: id, changeSet: undoId,
+                    summary: preview.set.summary,
+                    touched: preview.touched,
+                    removed: preview.removes,
+                    next: 'The files are back to their pre-change state and will rebuild on the next cycle. '
+                        + `Undo this undo with mikser_undo({ id: '${undoId}' }).`,
+                })
+            } catch (err) {
+                logger?.error('git: mikser_undo failed — %s', err.stderr || err.message)
+                return fail(err.stderr || err.message)
+            }
+        },
+    )
+}

package/lib/sync.js

@@ -13,6 +13,7 @@
 //     stays queued on the write branch until a human intervenes.
 
 import * as git from './git.js'
+import { changeSetTrailers } from './changeset-commit.js'
 import * as github from './forge/github.js'
 import * as gitea from './forge/gitea.js'
 
@@ -38,10 +39,42 @@ const ADAPTERS = { github, gitea }
 // returning a string — a count rather than a file list, since a full
 // list of paths in a commit message gets unwieldy past a handful of
 // files and git status is cheap to re-derive if anyone needs detail.
-export async function commitAndPushWriteBranch(folder, { paths, writeBranch, message, author, token }) {
+export async function commitAndPushWriteBranch(
+    folder, { paths, writeBranch, message, author, token, changeSets = [], onCommitted },
+) {
     const porcelain = await git.statusPorcelain(folder, paths)
     if (!porcelain) return { committed: false, pushed: false }
-    const fileCount = porcelain.split('\n').filter(Boolean).length
+
+    let committedAny = false
+
+    // Claimed writes first, each set its own commit staged to exactly the
+    // paths that set wrote.
+    //
+    // Staging by FOLDER instead would sweep in whatever else happened to be
+    // dirty — a document created through the API a second earlier lands in the
+    // agent's commit, and undoing the agent then deletes that document. The
+    // commit's contents have to match its label, or the label is a lie that
+    // only shows up at undo time.
+    for (const set of changeSets) {
+        const scoped = withinPaths(set.paths, paths)
+        if (!scoped.length) continue
+        await git.addPaths(folder, scoped)
+        if (!(await git.hasStagedChanges(folder, scoped))) continue
+        await git.commit(folder, changeSetMessage(set, scoped), { author })
+        committedAny = true
+        onCommitted?.(set.id)
+    }
+
+    // Then everything still dirty and unclaimed: API writes, human edits, a
+    // set whose attribution was lost to a crash. Unattributed and therefore
+    // not undoable, but never dropped.
+    const remaining = await git.statusPorcelain(folder, paths)
+    if (!remaining) {
+        return committedAny
+            ? { committed: true, pushed: await pushWriteBranch(folder, { writeBranch, token }) }
+            : { committed: false, pushed: false }
+    }
+    const fileCount = remaining.split('\n').filter(Boolean).length
 
     await git.addAll(folder, paths)
     if (!(await git.hasStagedChanges(folder, paths))) {
@@ -49,14 +82,36 @@ export async function commitAndPushWriteBranch(folder, { paths, writeBranch, mes
         // end up staging as a diff from HEAD in edge cases (e.g. a
         // file that matches .gitignore was force-added) — defensive,
         // should not normally happen.
-        return { committed: false, pushed: false }
+        return committedAny
+            ? { committed: true, pushed: await pushWriteBranch(folder, { writeBranch, token }) }
+            : { committed: false, pushed: false }
     }
     const resolvedMessage = typeof message === 'function' ? message({ fileCount }) : message
     await git.commit(folder, resolvedMessage, { author })
 
+    return { committed: true, pushed: await pushWriteBranch(folder, { writeBranch, token }) }
+}
+
+// Only the paths this instance is scoped to. A change set can span
+// collections this git instance does not manage; those stay for whichever
+// instance does own them, rather than being committed here.
+function withinPaths(candidates, paths) {
+    if (!paths?.length) return candidates
+    return candidates.filter(rel => paths.some(p => rel === p || rel.startsWith(`${p.replace(/\/$/, '')}/`)))
+}
+
+// Subject is the caller's own summary, so `git log --oneline` reads as a list
+// of what was asked for. Trailers carry the machine-readable half.
+function changeSetMessage(set, scoped) {
+    const subject = set.summary?.trim().split('\n')[0]
+        || `content: ${scoped.length} file(s) via mikser`
+    return `${subject}\n\n${changeSetTrailers(set)}`
+}
+
+async function pushWriteBranch(folder, { writeBranch, token }) {
     try {
         await git.push(folder, writeBranch, { token })
-        return { committed: true, pushed: true }
+        return true
     } catch (err) {
         if (!git.isNonFastForwardError(err)) throw err
         // The remote write branch moved (an inbound pull landed
@@ -69,7 +124,7 @@ export async function commitAndPushWriteBranch(folder, { paths, writeBranch, mes
         await git.fetch(folder, { token })
         await git.run(folder, ['rebase', `origin/${writeBranch}`])
         await git.push(folder, writeBranch, { token })
-        return { committed: true, pushed: true }
+        return true
     }
 }
 

package/lib/undo.js

@@ -0,0 +1,147 @@
+// Remove one change set's contribution from the current state.
+//
+// Not "restore a previous state". The site has moved on — documents were added
+// through the API, a human edited something — and the request is to take back
+// ONE change while keeping everything that came after. That is a merge-shaped
+// operation, which is exactly what `git revert` is for and exactly what a
+// snapshot restore is not.
+//
+// Git handles the textual half. It cannot handle the other half: a document
+// added after the change set may DEPEND on what the change set created, so a
+// revert that applies with no conflict at all can still leave the site
+// referencing a layout that no longer exists. Git reports success; the site is
+// broken. That check needs the reference graph, so it happens here.
+
+import { findEntities, lookupKeys } from 'mikser-io'
+
+import * as git from './git.js'
+import { parseChangeSetLog } from './changeset-commit.js'
+
+// Change sets in the branch's history, newest first.
+export async function listChangeSets(folder, { branch, limit = 20 } = {}) {
+    const raw = await git.logChangeSets(folder, { branch, limit: limit * 3 })
+    return parseChangeSetLog(raw).sort((a, b) => b.at - a.at).slice(0, limit)
+}
+
+export async function findChangeSet(folder, id, { branch } = {}) {
+    const raw = await git.logChangeSets(folder, { branch, limit: 500, id })
+    return parseChangeSetLog(raw).find(set => set.id === id) ?? null
+}
+
+// The reverse patch for a whole set: every commit undone, newest first.
+//
+// Newest-first because the commits stack — undoing the oldest edit to a file
+// before the newest one would be applying a patch to content that has moved
+// on since.
+export async function reversePatchFor(folder, set) {
+    const parts = []
+    for (const sha of [...set.commits].reverse()) {
+        const patch = await git.reversePatch(folder, sha)
+        if (patch?.trim()) parts.push(patch)
+    }
+    return parts.join('\n')
+}
+
+// Paths the undo would touch, and which of them it would REMOVE.
+//
+// A removal is where the danger is: reverting a create deletes a file, and
+// anything that came to depend on it since is what breaks.
+export function pathsInPatch(patch) {
+    const touched = new Set()
+    const deleted = new Set()
+    let current = null
+    for (const line of String(patch ?? '').split('\n')) {
+        const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(line)
+        if (m) { current = m[2]; touched.add(current); continue }
+        // In a REVERSE patch, "new file mode" means the forward commit
+        // deleted it and undoing restores it; "deleted file mode" means the
+        // forward commit created it and undoing removes it.
+        if (line.startsWith('deleted file mode') && current) deleted.add(current)
+    }
+    return { touched: [...touched], deleted: [...deleted] }
+}
+
+// What would still point at the things this undo removes.
+//
+// Uses the engine's own inverse reference index rather than a text search, so
+// it sees a `$`-ref exactly the way invalidation does — and asks about every
+// key the entity can be referenced BY (`lookupKeys`), not just its id, since
+// content refers to served paths far more often than to catalog ids.
+//
+// Referrers belonging to the change set itself are excluded: undoing a
+// document together with the layout only it used is coherent, and counting
+// that as breakage would make every complete undo look dangerous.
+export async function danglingAfterUndo({ runtime, deletedPaths, setPaths }) {
+    const refs = runtime?.refs
+    const workingFolder = runtime?.options?.workingFolder
+    if (!refs?.inboundFor || !workingFolder || !deletedPaths.length) return []
+
+    const own = new Set(setPaths)
+    const relOf = (uri) => (uri && uri.startsWith(`${workingFolder}/`)
+        ? uri.slice(workingFolder.length + 1)
+        : null)
+
+    const broken = []
+    for (const rel of deletedPaths) {
+        const [entity] = await findEntities({ uri: `${workingFolder}/${rel}` }) ?? []
+        if (!entity) continue
+
+        const referrers = 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
+                referrers.set(ref.id, ref.field ?? null)
+            }
+        }
+
+        const outside = []
+        for (const [sourceId, field] of referrers) {
+            const [source] = await findEntities({ id: sourceId }) ?? []
+            const sourceRel = relOf(source?.uri)
+            if (sourceRel && own.has(sourceRel)) continue
+            outside.push({ id: sourceId, ...(field ? { field } : {}) })
+        }
+        if (outside.length) broken.push({ removes: rel, id: entity.id, referencedBy: outside })
+    }
+    return broken
+}
+
+// Everything a caller needs to decide, computed without touching the tree.
+export async function previewUndo(folder, { id, branch, runtime } = {}) {
+    const set = await findChangeSet(folder, id, { branch })
+    if (!set) {
+        return { ok: false, refused: 'unknown-change-set',
+                 error: `No change set ${id} in this branch's history.` }
+    }
+    const patch = await reversePatchFor(folder, set)
+    if (!patch.trim()) {
+        return { ok: false, refused: 'nothing-to-undo', set,
+                 error: 'That change set left nothing to reverse.' }
+    }
+    const { touched, deleted } = pathsInPatch(patch)
+    const applies = await git.patchApplies(folder, patch)
+    const dangling = await danglingAfterUndo({ runtime, deletedPaths: deleted, setPaths: touched })
+
+    return {
+        ok: true,
+        set: { id: set.id, summary: set.summary, at: set.at, principal: set.principal, commits: set.commits.length },
+        touched,
+        removes: deleted,
+        applies,
+        dangling,
+        patch,
+        // Two independent reasons to stop, reported separately because the
+        // answers differ: a conflict means "not automatically", dangling refs
+        // mean "this will break something that arrived later".
+        ...(applies ? {} : {
+            conflict: 'A later change edited the same content, so this undo cannot be applied automatically.',
+        }),
+        ...(dangling.length ? {
+            warning: `Undoing this removes ${dangling.length} entit${dangling.length === 1 ? 'y' : 'ies'} that `
+                + 'something added since still references.',
+        } : {}),
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-git",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Two-way git sync for mikser-io. The working folder itself is the checkout, on a dedicated `mikser` branch (durable write log for API/MCP/agent edits). `paths` (optional) scopes auto-commits to specific collection folders (documents, layouts, files, ...) as a hard pathspec; omit it and the whole working folder is committed, subject to .gitignore. Every green cycle commits + pushes whatever's in scope and attempts to merge into the target branch (`main`) via a pull request; a red cycle (any render/postprocess failure) holds the merge and leaves the PR open for a human to resolve. Inbound changes on the target branch merge back into the working copy via poll. Forge-portable: GitHub and Gitea adapters, plus a no-forge fast-forward-only floor for any bare remote.",
   "main": "index.js",
   "files": [
@@ -24,6 +24,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-git#readme",
   "peerDependencies": {
-    "mikser-io": "^9.0.0"
+    "mikser-io": "^9.44.0",
+    "zod": "^4.0.0"
   }
 }