dsh-message-rewind 0.0.0-stage → 1.1.2

package/client.test.js

@@ -0,0 +1,294 @@
+/**
+ * Headless smoke test for the client half: it installs against a stubbed Cordis
+ * context, then renders the message actions and the confirmation dialog with a
+ * minimal React stand-in. No browser and no real React are involved.
+ */
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+
+const source = await readFile(new URL('./client.js', import.meta.url), 'utf8');
+
+/** React stand-in that keeps hook state per component slot across renders. */
+function makeReact() {
+  const states = new Map();
+  const refs = new Map();
+  let slot = 'none';
+  let index = 0;
+  return {
+    Fragment: 'Fragment',
+    createElement: (type, props, ...children) => ({ type, props: props ?? {}, children }),
+    __enter(name) { slot = name; index = 0; },
+    useState(initial) {
+      const key = `${slot}:${index++}`;
+      if (!states.has(key)) states.set(key, typeof initial === 'function' ? initial() : initial);
+      return [states.get(key), (next) => { states.set(key, next); }];
+    },
+    useRef(value) {
+      const key = `${slot}:${index++}`;
+      if (!refs.has(key)) refs.set(key, { current: value });
+      return refs.get(key);
+    },
+    useMemo: (factory) => { index++; return factory(); },
+    useCallback: (fn) => { index++; return fn; },
+    useEffect: (effect) => { index++; effect(); },
+    useSyncExternalStore: (_subscribe, getSnapshot) => { index++; return getSnapshot(); },
+    useId: () => `id${index++}`,
+  };
+}
+
+const react = makeReact();
+
+function makeElement(name) {
+  return { dataset: {}, style: {}, textContent: '', remove() {}, setAttribute() {}, tagName: name };
+}
+
+function queryAll(root, predicate, found = []) {
+  if (root === null || root === undefined) return found;
+  if (Array.isArray(root)) { for (const item of root) queryAll(item, predicate, found); return found; }
+  if (typeof root !== 'object') return found;
+  if (predicate(root)) found.push(root);
+  queryAll(root.children, predicate, found);
+  return found;
+}
+
+const styleTags = [];
+const calls = [];
+const registrations = [];
+globalThis.document = {
+  head: { appendChild: (node) => styleTags.push(node) },
+  createElement: (name) => makeElement(name),
+  activeElement: null,
+  addEventListener() {},
+  removeEventListener() {},
+};
+globalThis.window = {
+  setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+  clearTimeout: (id) => globalThis.clearTimeout(id),
+  __ModuleLoader__: { load: (definition) => { globalThis.__definition = definition; } },
+};
+Object.defineProperty(globalThis, 'navigator', { value: { clipboard: { writeText: () => Promise.resolve() } }, configurable: true });
+// The Host's `inspect` answer; the dialog tests below change it to exercise the
+// recorded-file and lost-snapshot branches.
+let inspectResult = { files: [], incomplete: false, unfinished: false };
+const ctx = {
+  effect: (fn) => { fn(); return () => {}; },
+  locale: {
+    register: (ns, locale, dict) => { calls.push(['locale.register', ns, locale, dict]); return () => {}; },
+    bind: (ns) => (key) => `${ns}:${key}`,
+  },
+  connection: {
+    rpc: {
+      call: (channel, endpoint, payload) => {
+        calls.push(['rpc.call', channel, endpoint, payload]);
+        const value = endpoint === 'execute'
+          ? { sessionId: 'child-1', restored: 0, sourceSessionId: payload.sessionId }
+          : endpoint === 'purge'
+            ? { removed: true, archivedOnly: false }
+            : inspectResult;
+        return Promise.resolve({ ok: true, value });
+      },
+    },
+  },
+  uiWorkspace: {
+    openSession: (id) => calls.push(['openSession', id]),
+  },
+  slots: {
+    inject: (name, callback) => { callback(); return () => {}; },
+    register: (options, component) => { registrations.push({ options, component }); return () => {}; },
+  },
+};
+
+const originalError = globalThis.console.error;
+globalThis.console.error = (...args) => { throw args[0]; };
+new Function('window', source)(globalThis.window);
+const definition = globalThis.__definition;
+assert.equal(definition.id, 'dsh-message-rewind');
+const plugin = definition.factory((id) => {
+  if (id === 'react') return react;
+  throw new Error(`unexpected require: ${id}`);
+});
+assert.equal(plugin.name, 'dsh-message-rewind');
+assert.deepEqual(plugin.inject, ['slots', 'uiWorkspace', 'locale', 'connection']);
+plugin.apply(ctx);
+globalThis.console.error = originalError;
+
+assert.equal(styleTags.length, 1, 'one stylesheet is inserted');
+assert.deepEqual(calls.filter((call) => call[0] === 'locale.register').map((call) => call[2]), ['zh', 'en']);
+const nodeRegistration = registrations.find((entry) => entry.options.key === 'user');
+const overlayRegistration = registrations.find((entry) => entry.options.id === 'message-rewind.dialog');
+assert.ok(nodeRegistration, 'the user chat node renderer is registered');
+assert.ok(overlayRegistration, 'the overlay dialog is registered');
+
+// --- render the user message row -------------------------------------------
+const rendered = [];
+const renderUser = (data, running = false) => {
+  react.__enter('user');
+  return nodeRegistration.component({
+    node: { data },
+    sessionId: 'session-1',
+    renderFactorySlot: (name, props) => { rendered.push([name, props]); return { type: 'bubble' }; },
+    loadImage: () => {},
+    useSession: (selector) => selector({ running }),
+  });
+};
+const data = { seq: 7, time: Date.now(), content: [{ type: 'text', text: 'hello' }] };
+const tree = renderUser(data);
+assert.equal(tree.type, 'div');
+assert.equal(tree.props.className, 'dmr-row');
+assert.equal(rendered[0][0], 'conversation.chat.user.content');
+assert.deepEqual(rendered[0][1].content, { text: 'hello', attachments: [], extraBlocks: [] });
+assert.equal(rendered[0][1].interactive, true);
+const actions = tree.children[1];
+assert.equal(actions.props.className, 'dmr-actions');
+const buttons = actions.children.filter(Boolean);
+assert.equal(buttons.length, 4, 'clock plus edit, delete and copy');
+const inner = buttons.slice(1);
+const [editButton, deleteButton] = inner;
+assert.equal(inner.length, 3, 'edit, delete and copy');
+assert.equal(editButton.props.className, 'dmr-action');
+assert.match(deleteButton.props.className, /dmr-danger/);
+assert.match(actions.children[0].children[0], /^\d{2}:\d{2}$/, 'today shows a 24h clock only');
+
+// an older message carries the localized date prefix, like the shipped row
+const oldTree = renderUser({ seq: 9, time: Date.now() - 400 * 24 * 60 * 60 * 1000, content: [{ type: 'text', text: 'old' }] });
+assert.match(oldTree.children[1].children[0].children[0], /^message-rewind:clock\.ymd \d{2}:\d{2}$/);
+assert.ok(renderUser(data, true).children[1].children[1].props.disabled, 'a running turn disables edit');
+
+// --- an attachment message disables edit just like the host does -----------
+const imageTicket = { attachmentId: 'img-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1 };
+const imageTree = renderUser({ seq: 8, time: Date.now(), content: [{ type: 'image', attachment: imageTicket }] });
+const imageButtons = imageTree.children[1].children.filter(Boolean).slice(1);
+assert.equal(imageButtons[0].props.disabled, true, 'attachment messages disable edit');
+assert.equal(imageButtons[1].props.disabled, undefined, 'attachment messages stay deletable');
+
+// --- edit flow --------------------------------------------------------------
+const renderDialog = () => { react.__enter('dialog'); return overlayRegistration.component({}); };
+editButton.props.onClick();
+renderDialog();
+let dialog = renderDialog();
+assert.ok(dialog, 'edit opens the dialog');
+assert.equal(queryAll(dialog, (element) => element.type === 'textarea').at(0).props.value, 'hello');
+await new Promise((resolve) => setImmediate(resolve));
+assert.equal(calls.filter((call) => call[0] === 'rpc.call').at(0)[2], 'inspect', 'opening edit inspects file changes');
+assert.deepEqual(calls.filter((call) => call[0] === 'rpc.call').at(0)[3], { sessionId: 'session-1', seq: 7 });
+const footer = () => queryAll(renderDialog(), (element) => element.props?.className === 'dmr-footer').at(-1);
+footer().children.filter(Boolean).at(-1).props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+assert.ok(!renderDialog(), 'a clean edit closes the dialog after forking');
+assert.deepEqual(calls.filter((call) => call[0] === 'openSession'), [['openSession', 'child-1']], 'the branch is opened');
+await new Promise((resolve) => setTimeout(resolve, 400));
+const purged = calls.filter((call) => call[0] === 'rpc.call' && call[2] === 'purge').at(-1);
+assert.deepEqual(purged[3], { sessionId: 'session-1' }, 'the untouched source is retired');
+
+// --- an edit that recorded file changes offers both rollback scopes ---------
+inspectResult = { files: ['test.txt', 'src/app.js'], incomplete: false, unfinished: false };
+editButton.props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+dialog = renderDialog();
+assert.deepEqual(
+  queryAll(dialog, (element) => element.type === 'li').map((item) => item.children.join('')),
+  ['test.txt', 'src/app.js'],
+  'the edit dialog lists the recorded files');
+const scopeInputs = queryAll(dialog, (element) => element.type === 'input');
+assert.equal(scopeInputs.length, 2, 'edit offers the shared scope control');
+assert.equal(scopeInputs[0].props.checked, true, 'messages-only is the default');
+assert.equal(scopeInputs[1].props.disabled, false, 'recorded files can be rolled back');
+scopeInputs[1].props.onChange();
+const scopeButtons = queryAll(renderDialog(), (element) => element.props?.className === 'dmr-footer').at(-1).children.filter(Boolean);
+assert.deepEqual(scopeButtons.map((button) => button.children.join('')), [
+  'message-rewind:cancel',
+  'message-rewind:save',
+], 'one primary action, with the scope chosen above it');
+scopeButtons.at(-1).props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+assert.deepEqual(
+  calls.filter((call) => call[0] === 'rpc.call' && call[2] === 'execute').at(-1)[3],
+  { sessionId: 'session-1', seq: 7, action: 'edit', text: 'hello', rewindFiles: true },
+  'the edited text is resent after the files roll back');
+assert.ok(!renderDialog(), 'the dialog closes after rolling back and resending');
+await new Promise((resolve) => setTimeout(resolve, 400));
+
+// --- a lost snapshot keeps the control, but file rollback is unavailable ----
+inspectResult = { files: [], incomplete: true, unfinished: false };
+editButton.props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+dialog = renderDialog();
+assert.equal(queryAll(dialog, (element) => element.props?.className === 'dmr-warning').at(0).children[0], 'message-rewind:incomplete');
+const staleInputs = queryAll(dialog, (element) => element.type === 'input');
+assert.equal(staleInputs.length, 2, 'the scope control stays visible');
+assert.equal(staleInputs[1].props.disabled, true, 'file rollback is unavailable');
+const staleButtons = queryAll(renderDialog(), (element) => element.props?.className === 'dmr-footer').at(-1).children.filter(Boolean);
+assert.equal(staleButtons.length, 2, 'cancel plus the messages-only action');
+staleButtons[0].props.onClick();
+assert.ok(!renderDialog(), 'cancel closes the stale-snapshot dialog');
+inspectResult = { files: [], incomplete: false, unfinished: false };
+
+// --- delete flow ------------------------------------------------------------
+deleteButton.props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+dialog = renderDialog();
+assert.ok(dialog, 'delete opens the dialog');
+const deleteFooter = queryAll(dialog, (element) => element.props?.className === 'dmr-footer').at(-1);
+const deleteButtons = deleteFooter.children.filter(Boolean);
+assert.equal(deleteButtons.length, 2, 'cancel plus delete');
+deleteButtons.at(-1).props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+const execute = calls.filter((call) => call[0] === 'rpc.call' && call[2] === 'execute').at(-1);
+assert.deepEqual(execute[3], { sessionId: 'session-1', seq: 7, action: 'delete', text: '', rewindFiles: false });
+await new Promise((resolve) => setImmediate(resolve));
+assert.deepEqual(calls.filter((call) => call[0] === 'openSession').at(-1), ['openSession', 'child-1']);
+
+// --- delete asks the same question, so it renders the same control ----------
+inspectResult = { files: ['test.txt'], incomplete: false, unfinished: false };
+deleteButton.props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+dialog = renderDialog();
+const deleteScope = queryAll(dialog, (element) => element.type === 'input');
+assert.equal(deleteScope.length, 2, 'delete offers the same scope control');
+assert.equal(deleteScope[0].props.checked, true, 'messages-only is the default');
+deleteScope[1].props.onChange();
+const deleteActions = queryAll(renderDialog(), (element) => element.props?.className === 'dmr-footer').at(-1).children.filter(Boolean);
+assert.deepEqual(deleteActions.map((button) => button.children.join('')), [
+  'message-rewind:cancel',
+  'message-rewind:deleteConfirm',
+], 'the delete action follows the chosen scope');
+deleteActions.at(-1).props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+assert.deepEqual(
+  calls.filter((call) => call[0] === 'rpc.call' && call[2] === 'execute').at(-1)[3],
+  { sessionId: 'session-1', seq: 7, action: 'delete', text: '', rewindFiles: true },
+  'the chosen file scope reaches the Host');
+inspectResult = { files: [], incomplete: false, unfinished: false };
+
+// let the delayed purge settle before the failure-path test swaps the RPC stub
+await new Promise((resolve) => setTimeout(resolve, 400));
+
+// --- host failure codes are localized --------------------------------------
+ctx.connection.rpc.call = () => Promise.resolve({
+  ok: false,
+  error: { message: '请先停止当前运行', details: { rewindCode: 'open-turn' } },
+});
+deleteButton.props.onClick();
+await new Promise((resolve) => setImmediate(resolve));
+const failed = queryAll(renderDialog(), (element) => element.props?.className === 'dmr-error').at(0);
+assert.equal(failed.children[0], 'message-rewind:error.open-turn');
+
+// --- a late response cannot resurrect a closed dialog -----------------------
+ctx.connection.rpc.call = (channel, endpoint, payload) => {
+  calls.push(['rpc.call', channel, endpoint, payload]);
+  return new Promise((resolve) => {
+    globalThis.setTimeout(() => resolve({ ok: true, value: { files: [], incomplete: false, unfinished: false } }), 20);
+  });
+};
+deleteButton.props.onClick();
+const loadingDialog = renderDialog();
+assert.ok(loadingDialog, 'delete opens in the loading phase');
+const loadingFooter = queryAll(loadingDialog, (element) => element.props?.className === 'dmr-footer').at(0);
+loadingFooter.children[0].props.onClick();
+assert.ok(!renderDialog(), 'the loading phase can be cancelled');
+await new Promise((resolve) => setTimeout(resolve, 60));
+assert.ok(!renderDialog(), 'the late inspect response does not reopen the dialog');
+
+console.log('client self-check passed');
+
+

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: message-rewind
+      name: 'dsh-message-rewind'

package/files.js

@@ -0,0 +1,160 @@
+/**
+ * File rewind: turn one recorded change list back into the pre-cut file state.
+ *
+ * The recorder compares each file at turn start and turn end, so a deletion is
+ * representable — `before: true, after: false` — and restoring it means writing
+ * the pre-turn text back. This module keeps that math independent of Cordis so
+ * it can be tested against a real directory.
+ */
+import { promises as fsp } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { inversePatch, terminated, textSide, userError } from './rewind.js';
+
+const MAX_TEXT_BYTES = 4 * 1024 * 1024;
+
+const text = (error) => (error instanceof Error ? error.message : String(error));
+
+export function insideRoot(root, path) {
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  return path !== root && path.startsWith(prefix);
+}
+
+/** Read one file as UTF-8 text, reporting absence instead of failing. */
+export async function readFileState(path, display) {
+  let info;
+  try {
+    info = await fsp.stat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, text: null };
+    throw userError('file-unreadable', `无法读取 ${display}：${text(error)}`);
+  }
+  if (!info.isFile()) throw userError('file-unreadable', `${display} 不是普通文件，未回滚任何文件。`);
+  if (info.size > MAX_TEXT_BYTES) throw userError('file-too-large', `${display} 超过文本回滚上限，未回滚任何文件。`);
+  const bytes = await fsp.readFile(path);
+  try {
+    // The recorder reads text with `readFile(…, 'utf8')`, which keeps a BOM.
+    // TextDecoder strips it by default, so keep it here or every context line
+    // of a BOM file compares unequal and a silent rewrite drops the bytes.
+    return { exists: true, text: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) };
+  } catch {
+    throw userError('file-binary', `${display} 不是 UTF-8 文本，未回滚任何文件。`);
+  }
+}
+
+/**
+ * Apply one recorded diff backwards: current state in, the state before that turn out.
+ * @param state - what is on disk now.
+ * @param diff - the recorded text comparison.
+ * @returns the state this turn started from.
+ */
+export function invert(state, diff) {
+  if (state.exists !== diff.after) throw userError('file-changed', `${diff.display} 在记录之后又被修改过，已停止回滚。`);
+  // A file this turn created has nothing to invert: the pre-turn state is absence.
+  // Its current content is still compared, so a later edit is refused instead of
+  // being deleted silently.
+  if (!diff.before) {
+    const expected = textSide(true, diff.hunks, true) ?? '';
+    if (terminated(state.text ?? '') !== expected) throw userError('file-changed', `${diff.display} 在记录之后又被修改过，已停止回滚。`);
+    return { exists: false, text: null };
+  }
+  // A file this turn deleted restores from the removed lines alone.
+  if (!diff.after) return { exists: true, text: textSide(true, diff.hunks, false) };
+  return { exists: true, text: inversePatch(state.text ?? '', diff.hunks) };
+}
+
+async function pruneEmptyParents(path, root) {
+  let parent = dirname(path);
+  while (insideRoot(root, parent)) {
+    try {
+      const entries = await fsp.readdir(parent);
+      if (entries.length > 0) return;
+      await fsp.rmdir(parent);
+    } catch {
+      return;
+    }
+    parent = dirname(parent);
+  }
+}
+
+/**
+ * Resolve every touched file to its pre-cut content without touching disk.
+ * @param readDiff - reads one recorded comparison; throws when it is unavailable.
+ * @param records - `workspace/changes` records in ascending sequence order.
+ * @returns per-path plan carrying the current state and the target state.
+ */
+export async function planRewind(readDiff, records) {
+  const targets = new Map();
+  for (const { seq, summary } of records) {
+    if (!summary) continue;
+    const root = resolve(summary.cwd);
+    for (let index = 0; index < summary.files.length; index += 1) {
+      const file = summary.files[index];
+      const path = resolve(root, file.path);
+      if (!insideRoot(root, path)) throw userError('path-escape', `${file.display} 不在该轮工作区内，未回滚任何文件。`);
+      if (!targets.has(path)) targets.set(path, { path, display: file.display, root, steps: [] });
+      targets.get(path).steps.push({ seq, index });
+    }
+  }
+  for (const target of targets.values()) {
+    target.actual = await readFileState(target.path, target.display);
+    let state = { ...target.actual };
+    // Newest change first: each diff expects the file as that turn left it.
+    for (let index = target.steps.length - 1; index >= 0; index -= 1) {
+      const step = target.steps[index];
+      try {
+        state = invert(state, await readDiff(step.seq, step.index));
+      } catch (error) {
+        throw userError(error?.rewindCode ?? 'file-rewind', `${target.display}：${text(error)}`);
+      }
+    }
+    target.original = state;
+  }
+  return targets;
+}
+
+async function restoreTargets(done) {
+  const failures = [];
+  for (const target of [...done].reverse()) {
+    try {
+      if (!target.actual.exists) await fsp.rm(target.path, { force: true });
+      else {
+        await fsp.mkdir(dirname(target.path), { recursive: true });
+        await fsp.writeFile(target.path, target.actual.text, 'utf8');
+      }
+    } catch (restoreError) {
+      failures.push(`${target.display}：${text(restoreError)}`);
+    }
+  }
+  return failures;
+}
+
+/**
+ * Write every planned pre-cut content and return an undo restoring the current state.
+ * @param targets - the plan from {@link planRewind}.
+ * @returns the number of files written and the undo, or throws after undoing a partial write.
+ */
+export async function applyRewind(targets) {
+  const done = [];
+  try {
+    for (const target of targets.values()) {
+      if (target.original.exists) {
+        await fsp.mkdir(dirname(target.path), { recursive: true });
+        await fsp.writeFile(target.path, target.original.text, 'utf8');
+        done.push(target);
+      } else if (target.actual.exists) {
+        await fsp.rm(target.path);
+        done.push(target);
+      }
+    }
+  } catch (error) {
+    const failures = await restoreTargets(done);
+    if (failures.length) throw userError('file-restore-failed', `文件回滚中断，以下文件需人工检查：${failures.join('；')}`);
+    throw error;
+  }
+  for (const target of done) if (!target.original.exists) await pruneEmptyParents(target.path, target.root);
+  const undo = async () => {
+    const failures = await restoreTargets(done);
+    if (failures.length) throw userError('file-restore-failed', `文件未能恢复原状，请人工检查：${failures.join('；')}`);
+  };
+  return { written: done.length, undo };
+}

package/files.test.js

@@ -0,0 +1,160 @@
+/**
+ * File-rewind self-check against a real temporary directory. The recorded
+ * diffs are handcrafted to match what `dsh-workspace-changes` produces: it diffs
+ * newline-terminated text with jsdiff, so every hunk line carries its `\n`, and a
+ * deletion is `before: true, after: false`.
+ */
+import assert from 'node:assert/strict';
+import { promises as fsp } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { planRewind, applyRewind, invert } from './files.js';
+
+let passed = 0;
+const check = (label, fn) => fn().then(() => { passed += 1; }, (error) => { throw new Error(`${label}: ${error.message}`); });
+
+const workspace = await fsp.mkdtemp(join(tmpdir(), 'dmr-files-'));
+const recordsFor = (entries) => entries.map(({ seq, files }) => ({
+  seq,
+  summary: { turn: 1, cwd: workspace, files, total: files.length, added: 0, deleted: 0 },
+}));
+const readDiffFrom = (table) => async (seq, index) => {
+  const found = table[`${seq}:${index}`];
+  if (!found) throw new Error(`no recorded diff for ${seq}:${index}`);
+  return found;
+};
+const abs = (name) => join(workspace, name);
+const textDiff = (path, before, after, hunks) => ({ kind: 'text', path, display: path, before, after, hunks, coarse: false });
+
+// --- a turn that deleted a file is restorable ------------------------------
+const deletedName = 'deleted.txt';
+const deletedBefore = 'one\ntwo\n';
+const deletedDiff = textDiff(deletedName, true, false, [{ oldStart: 1, oldLines: 2, newStart: 0, newLines: 0, lines: ['-one\n', '-two\n'] }]);
+await check('deleted file is recreated', async () => {
+  assert.deepEqual(await readExists(deletedName), null);
+  const targets = await planRewind(readDiffFrom({ '1:0': deletedDiff }), recordsFor([{ seq: 1, files: [{ path: deletedName, display: deletedName }] }]));
+  assert.deepEqual([...targets.values()][0].original, { exists: true, text: deletedBefore });
+  await applyRewind(targets);
+  assert.equal(await fsp.readFile(abs(deletedName), 'utf8'), deletedBefore);
+});
+
+// --- a turn that created a file is undone by removing it --------------------
+const createdName = 'created.txt';
+const createdDiff = textDiff(createdName, false, true, [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: 1, lines: ['+abc'] }]);
+await check('created file is removed', async () => {
+  await fsp.writeFile(abs(createdName), 'abc', 'utf8');
+  const targets = await planRewind(readDiffFrom({ '2:0': createdDiff }), recordsFor([{ seq: 2, files: [{ path: createdName, display: createdName }] }]));
+  assert.deepEqual([...targets.values()][0].original, { exists: false, text: null });
+  await applyRewind(targets);
+  await assert.rejects(() => fsp.stat(abs(createdName)));
+});
+
+// --- a turn that modified a file is reverted -------------------------------
+const editedName = 'edited.txt';
+const editedDiff = textDiff(editedName, true, true, [{ oldStart: 1, oldLines: 3, newStart: 1, newLines: 3, lines: [' zero\n', ' one\n', '-two\n', '+TWO\n'] }]);
+await check('modified file is reverted', async () => {
+  await fsp.writeFile(abs(editedName), 'zero\none\nTWO\n', 'utf8');
+  const targets = await planRewind(readDiffFrom({ '3:0': editedDiff }), recordsFor([{ seq: 3, files: [{ path: editedName, display: editedName }] }]));
+  await applyRewind(targets);
+  assert.equal(await fsp.readFile(abs(editedName), 'utf8'), 'zero\none\ntwo\n');
+});
+
+// --- a file stored without a final newline still matches the diff ----------
+const bareName = 'bare.txt';
+const bareDiff = textDiff(bareName, true, true, [{ oldStart: 1, oldLines: 1, newStart: 1, newLines: 2, lines: [' x\n', '+y'] }]);
+await check('unterminated file is reverted', async () => {
+  await fsp.writeFile(abs(bareName), 'x\ny', 'utf8');
+  const targets = await planRewind(readDiffFrom({ '4:0': bareDiff }), recordsFor([{ seq: 4, files: [{ path: bareName, display: bareName }] }]));
+  await applyRewind(targets);
+  assert.equal(await fsp.readFile(abs(bareName), 'utf8'), 'x\n');
+});
+
+// --- a UTF-8 BOM survives the round trip -----------------------------------
+const bomName = 'bom.txt';
+const bomDiff = textDiff(bomName, true, true, [{ oldStart: 1, oldLines: 2, newStart: 1, newLines: 2, lines: [' \uFEFFone\n', '-two\n', '+TWO\n'] }]);
+await check('utf-8 BOM file is reverted without losing the BOM', async () => {
+  const bom = Buffer.from([0xEF, 0xBB, 0xBF]);
+  await fsp.writeFile(abs(bomName), Buffer.concat([bom, Buffer.from('one\nTWO\n', 'utf8')]));
+  const targets = await planRewind(readDiffFrom({ '10:0': bomDiff }), recordsFor([{ seq: 10, files: [{ path: bomName, display: bomName }] }]));
+  await applyRewind(targets);
+  const bytes = await fsp.readFile(abs(bomName));
+  assert.deepEqual([...bytes.subarray(0, 3)], [0xEF, 0xBB, 0xBF]);
+  assert.equal(bytes.toString('utf8'), '\uFEFFone\ntwo\n');
+});
+
+// --- a created file edited after its turn is refused, not deleted ----------
+const createdLaterName = 'created-later.txt';
+const createdLaterDiff = textDiff(createdLaterName, false, true, [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: 1, lines: ['+original\n'] }]);
+await check('created file edited later is refused', async () => {
+  await fsp.writeFile(abs(createdLaterName), 'original\nplus a manual edit\n', 'utf8');
+  await assert.rejects(
+    () => planRewind(readDiffFrom({ '11:0': createdLaterDiff }), recordsFor([{ seq: 11, files: [{ path: createdLaterName, display: createdLaterName }] }])),
+    /created-later\.txt：.*在记录之后又被修改过/,
+  );
+  await fsp.writeFile(abs(createdLaterName), 'original\n', 'utf8');
+  const targets = await planRewind(readDiffFrom({ '12:0': createdLaterDiff }), recordsFor([{ seq: 12, files: [{ path: createdLaterName, display: createdLaterName }] }]));
+  await applyRewind(targets);
+  await assert.rejects(() => fsp.stat(abs(createdLaterName)));
+});
+
+// --- a file changed after that turn refuses instead of guessing -------------
+await check('conflicting later edit is refused', async () => {
+  await fsp.writeFile(abs(editedName), 'zero\none\nTHREE\n', 'utf8');
+  await assert.rejects(
+    () => planRewind(readDiffFrom({ '5:0': editedDiff }), recordsFor([{ seq: 5, files: [{ path: editedName, display: editedName }] }])),
+    /edited\.txt：.*(在记录之后又被修改过|文件版本已改变)/,
+  );
+});
+
+// --- several turns on one path unwind newest first -------------------------
+const chainedName = 'chained.txt';
+const chainedCreated = textDiff(chainedName, false, true, [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: 1, lines: ['+abc'] }]);
+const chainedEdited = textDiff(chainedName, true, true, [{ oldStart: 1, oldLines: 1, newStart: 1, newLines: 2, lines: [' abc\n', '+def\n'] }]);
+await check('multi-turn path unwinds to absent', async () => {
+  await fsp.writeFile(abs(chainedName), 'abc\ndef\n', 'utf8');
+  const targets = await planRewind(
+    readDiffFrom({ '6:0': chainedCreated, '7:0': chainedEdited }),
+    recordsFor([
+      { seq: 6, files: [{ path: chainedName, display: chainedName }] },
+      { seq: 7, files: [{ path: chainedName, display: chainedName }] },
+    ]),
+  );
+  await applyRewind(targets);
+  await assert.rejects(() => fsp.stat(abs(chainedName)));
+});
+
+// --- undo restores exactly what the rewind replaced --------------------------
+await check('undo restores the pre-rewind state', async () => {
+  await fsp.writeFile(abs(editedName), 'zero\none\nTWO\n', 'utf8');
+  const targets = await planRewind(readDiffFrom({ '8:0': editedDiff }), recordsFor([{ seq: 8, files: [{ path: editedName, display: editedName }] }]));
+  const applied = await applyRewind(targets);
+  assert.equal(await fsp.readFile(abs(editedName), 'utf8'), 'zero\none\ntwo\n');
+  await applied.undo();
+  assert.equal(await fsp.readFile(abs(editedName), 'utf8'), 'zero\none\nTWO\n');
+});
+
+// --- a path outside the recorded workspace is refused ----------------------
+await check('path outside the workspace is refused', async () => {
+  await assert.rejects(
+    () => planRewind(readDiffFrom({}), recordsFor([{ seq: 9, files: [{ path: '../escape.txt', display: '../escape.txt' }] }])),
+    /不在该轮工作区内/,
+  );
+});
+
+// --- invert is a pure total function on absence ----------------------------
+assert.deepEqual(invert({ exists: false, text: null }, deletedDiff), { exists: true, text: deletedBefore });
+assert.deepEqual(invert({ exists: true, text: 'abc' }, createdDiff), { exists: false, text: null });
+assert.throws(() => invert({ exists: true, text: 'abc changed' }, createdDiff), /在记录之后又被修改过/);
+
+async function readExists(name) {
+  try {
+    return await fsp.readFile(abs(name), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+await fsp.rm(workspace, { recursive: true, force: true });
+console.log(`files self-check passed (${passed} scenarios)`);
+

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect x="7" y="9" width="50" height="42" rx="13" fill="#247bbf"/>
+  <path d="M22 24h20M22 32h13M22 40h9" stroke="white" stroke-width="4" stroke-linecap="round"/>
+  <path d="M40 45a11 11 0 1 0 1-17" stroke="#bce5ff" stroke-width="4" stroke-linecap="round"/>
+  <path d="m39 23 10 5-10 5" fill="#bce5ff"/>
+</svg>