@sudodevstudio/astro-ai 0.1.0

package/src/visual/capability-resolver.ts

@@ -0,0 +1,83 @@
+import type { VisualCapabilities } from '../shared/selection-context.js';
+import type { VisualComponentDefinition } from '../shared/visual-components.js';
+import type { SourceNodeRecord } from '../resolver/types.js';
+
+export class VisualCapabilityResolver {
+  readonly #components: Map<string, VisualComponentDefinition>;
+
+  constructor(components: VisualComponentDefinition[] = []) {
+    this.#components = new Map(components.map((component) => [component.name, component]));
+  }
+
+  resolve(node: SourceNodeRecord): VisualCapabilities {
+    const previous = node.previousSiblingId;
+    const next = node.nextSiblingId;
+    const reorderable = previous !== undefined || next !== undefined;
+    const nodeType = node.componentName ?? node.tagName ?? '*';
+    const allowedParentSlots = [...this.#components.values()].flatMap((component) =>
+      (component.slots ?? []).flatMap((slot) =>
+        slot.accepts === undefined || slot.accepts.includes('*') || slot.accepts.includes(nodeType)
+          ? [`${component.name}:${slot.name}`]
+          : []
+      )
+    );
+
+    return {
+      editableText:
+        node.textRange !== undefined &&
+        (node.sourceKind === 'literal-source' || node.sourceKind === 'repeated-template') &&
+        !node.hydratedIsland,
+      movable: (reorderable || allowedParentSlots.length > 0) && !node.hydratedIsland,
+      reorderable: reorderable && !node.hydratedIsland,
+      removable: node.instrumentable && !node.hydratedIsland,
+      editableProps: node.hydratedIsland ? [] : this.#editableProps(node),
+      allowedParentSlots,
+      sourceKind: node.sourceKind,
+      dataProvenance: node.dataProvenance,
+      ...(node.repeatContext === undefined
+        ? {}
+        : { repeatContext: node.repeatContext }),
+      reorderTargets: {
+        ...(previous === undefined ? {} : { previous }),
+        ...(next === undefined ? {} : { next }),
+      },
+    };
+  }
+
+  #editableProps(node: SourceNodeRecord) {
+    const definition = node.componentName === undefined
+      ? undefined
+      : this.#components.get(node.componentName);
+    return node.literalProps.flatMap((prop) => {
+      const propDefinition = definition?.props?.[prop.name];
+      if (definition !== undefined && propDefinition === undefined) return [];
+      return [
+        {
+          ...toEditableProp(prop),
+          ...(propDefinition?.values === undefined
+            ? {}
+            : { allowedValues: propDefinition.values }),
+          ...(propDefinition === undefined ? {} : { control: propDefinition.control }),
+        },
+      ];
+    });
+  }
+
+  acceptsSlot(parentComponent: string, slotName: string, childType: string): boolean {
+    const slot = this.#components.get(parentComponent)?.slots?.find(({ name }) => name === slotName);
+    return slot !== undefined && (slot.accepts === undefined || slot.accepts.includes('*') || slot.accepts.includes(childType));
+  }
+
+  slotsFor(component: string): NonNullable<VisualComponentDefinition['slots']> {
+    return this.#components.get(component)?.slots ?? [];
+  }
+}
+
+function toEditableProp({ name, type, value, allowedValues }: SourceNodeRecord['literalProps'][number]) {
+  return {
+    name,
+    type,
+    value,
+    ...(allowedValues === undefined ? {} : { allowedValues }),
+  };
+}

package/src/visual/command-engine.ts

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import { parse as parseAstro } from '@astrojs/compiler-rs';
+import { parse as parseJavaScript } from '@babel/parser';
+
+import type { AstroResolver } from '../resolver/astro-resolver.js';
+import type { SourceNodeRecord, SourceProp } from '../resolver/types.js';
+import type { DeterministicVisualCommand } from './commands.js';
+import {
+  PatchTransactionStore,
+  type PatchTransactionSummary,
+} from './patch-transactions.js';
+
+export class VisualCommandEngine {
+  readonly #resolver: AstroResolver;
+  readonly transactions: PatchTransactionStore;
+
+  constructor(
+    resolver: AstroResolver,
+    transactions = new PatchTransactionStore(resolver),
+  ) {
+    this.#resolver = resolver;
+    this.transactions = transactions;
+  }
+
+  async execute(command: DeterministicVisualCommand): Promise<PatchTransactionSummary> {
+    if (command.kind === 'insert-literal-element') return this.#insertLiteralElement(command);
+    const node = this.#resolver.requireNode(command.nodeId);
+    const before = await this.#readFreshSource(node);
+    const capabilities = this.#resolver.resolveSelection(node.nodeId, '').capabilities;
+    let after: string;
+
+    switch (command.kind) {
+      case 'edit-literal-text':
+        if (!capabilities.editableText || typeof command.text !== 'string') {
+          throw new Error('Rendered or generated text cannot be overwritten safely.');
+        }
+        after = editLiteralText(node, before, command.text);
+        break;
+      case 'reorder-sibling':
+        if (!capabilities.reorderable) {
+          throw new Error('This node cannot be reordered safely.');
+        }
+        after = this.#reorderSibling(node, before, command.direction);
+        break;
+      case 'set-literal-prop': {
+        const editableProp = capabilities.editableProps.find(
+          (candidate) => candidate.name === command.prop,
+        );
+        if (editableProp === undefined) {
+          throw new Error(`Prop “${command.prop}” is not a proven-safe literal prop.`);
+        }
+        after = setLiteralProp(
+          node,
+          before,
+          command.prop,
+          command.value,
+          editableProp.allowedValues,
+        );
+        break;
+      }
+      case 'remove-source-node':
+        if (!capabilities.removable) throw new Error('This source node cannot be removed safely.');
+        after = replaceRange(before, node.range.start, node.range.end, '');
+        break;
+      case 'move-to-slot':
+        after = this.#moveToSlot(node, before, command.targetNodeId, command.slot);
+        break;
+      default:
+        throw new Error('Unsupported visual operation; route it to the agent fallback.');
+    }
+
+    assertValidSource(after, node);
+    const transaction = await this.transactions.commit(command.kind, node.filePath, before, after);
+    // Populate the resolver once immediately so a second local command can use
+    // the stable selection. Vite's subsequent transform hits the source-hash
+    // cache instead of parsing the same file again.
+    this.#resolver.indexFile(node.filePath, after);
+    return transaction;
+  }
+
+  async #insertLiteralElement(command: Extract<DeterministicVisualCommand, { kind: 'insert-literal-element' }>): Promise<PatchTransactionSummary> {
+    if (!/^[a-z][a-z0-9-]*$/.test(command.tag)) throw new Error('Only native lowercase element names can be inserted deterministically.');
+    const file = this.#resolver.toAbsoluteProjectFile(command.file);
+    const before = await readFile(file, 'utf8');
+    const zone = this.#resolver.findInsertionPoints(file).find((candidate) =>
+      candidate.parentNodeId === command.parentNodeId && candidate.slot === command.slot
+    );
+    if (zone === undefined) throw new Error('The requested insertion zone is no longer available.');
+    const slotAttribute = command.slot === undefined ? '' : ` slot=${JSON.stringify(command.slot)}`;
+    const markup = `<${command.tag}${slotAttribute}>${escapeJsxText(command.text)}</${command.tag}>`;
+    const after = replaceRange(before, zone.offset, zone.offset, `${zone.offset === 0 ? '' : '\n'}${markup}`);
+    assertValidFile(after, file);
+    const transaction = await this.transactions.commit(command.kind, file, before, after);
+    this.#resolver.indexFile(file, after);
+    return transaction;
+  }
+
+  async #readFreshSource(node: SourceNodeRecord): Promise<string> {
+    const source = await readFile(node.filePath, 'utf8');
+    const sourceHash = createHash('sha256').update(source).digest('hex');
+    if (sourceHash !== node.sourceHash) {
+      throw new Error('The source changed after selection; inspect the element again.');
+    }
+    return source;
+  }
+
+  #reorderSibling(
+    node: SourceNodeRecord,
+    source: string,
+    direction: 'previous' | 'next',
+  ): string {
+    if (direction !== 'previous' && direction !== 'next') {
+      throw new Error('Unknown sibling reorder direction.');
+    }
+    const siblingId = direction === 'previous'
+      ? node.previousSiblingId
+      : node.nextSiblingId;
+    if (siblingId === undefined) throw new Error(`This node cannot move ${direction}.`);
+    const sibling = this.#resolver.requireNode(siblingId);
+    if (
+      sibling.filePath !== node.filePath ||
+      sibling.siblingGroupId === undefined ||
+      sibling.siblingGroupId !== node.siblingGroupId
+    ) {
+      throw new Error('The target is not a compatible source sibling.');
+    }
+
+    const left = node.range.start < sibling.range.start ? node : sibling;
+    const right = left === node ? sibling : node;
+    const separator = source.slice(left.range.end, right.range.start);
+    if (separator.trim() !== '') {
+      throw new Error('Reordering across expressions or comments is not safe.');
+    }
+
+    return replaceRange(
+      source,
+      left.range.start,
+      right.range.end,
+      `${source.slice(right.range.start, right.range.end)}${separator}${source.slice(left.range.start, left.range.end)}`,
+    );
+  }
+
+  #moveToSlot(node: SourceNodeRecord, source: string, targetNodeId: string, slot: string): string {
+    const target = this.#resolver.requireNode(targetNodeId);
+    const childType = node.componentName ?? node.tagName ?? '';
+    if (
+      target.filePath !== node.filePath || target.componentName === undefined || target.selfClosing
+      || !this.#resolver.acceptsSlot(target.componentName, slot, childType)
+      || (target.range.start >= node.range.start && target.range.end <= node.range.end)
+    ) throw new Error('The target is not a compatible declared source slot.');
+    if (node.literalProps.some(({ name }) => name === 'slot')) throw new Error('The node already declares a slot assignment.');
+    const opening = source.slice(node.openingRange.start, node.openingRange.end);
+    const insertion = opening.endsWith('/>') ? opening.length - 2 : opening.length - 1;
+    const moved = `${opening.slice(0, insertion)} slot=${JSON.stringify(slot)}${opening.slice(insertion)}${source.slice(node.openingRange.end, node.range.end)}`;
+    const without = replaceRange(source, node.range.start, node.range.end, '');
+    let targetOffset = target.range.end - `</${target.componentName}>`.length;
+    if (node.range.start < targetOffset) targetOffset -= node.range.end - node.range.start;
+    return replaceRange(without, targetOffset, targetOffset, `\n${moved}\n`);
+  }
+}
+
+function editLiteralText(node: SourceNodeRecord, source: string, text: string): string {
+  if (node.textRange === undefined || node.dataProvenance.kind !== 'literal') {
+    throw new Error('Rendered or generated text cannot be overwritten safely.');
+  }
+  const current = source.slice(node.textRange.start, node.textRange.end);
+  const leading = current.match(/^\s*/)?.[0] ?? '';
+  const trailing = current.match(/\s*$/)?.[0] ?? '';
+  return replaceRange(
+    source,
+    node.textRange.start,
+    node.textRange.end,
+    `${leading}${escapeJsxText(text)}${trailing}`,
+  );
+}
+
+function setLiteralProp(
+  node: SourceNodeRecord,
+  source: string,
+  name: string,
+  value: string | number | boolean,
+  allowedValues: Array<string | number | boolean> | undefined,
+): string {
+  const prop = node.literalProps.find((candidate) => candidate.name === name);
+  if (prop === undefined) throw new Error(`Prop “${name}” is not a safe literal prop.`);
+  if (typeof value !== prop.type) {
+    throw new Error(`Prop “${name}” requires a ${prop.type} value.`);
+  }
+  if (allowedValues !== undefined && !allowedValues.includes(value)) {
+    throw new Error(`Prop “${name}” does not accept that value.`);
+  }
+
+  return replaceRange(source, prop.range.start, prop.range.end, serializeProp(prop, value));
+}
+
+function serializeProp(prop: SourceProp, value: string | number | boolean): string {
+  if (prop.syntax === 'shorthand') {
+    return value === true ? prop.name : `${prop.name}={false}`;
+  }
+  if (prop.syntax === 'quoted') return JSON.stringify(value);
+  return `{${typeof value === 'string' ? JSON.stringify(value) : String(value)}}`;
+}
+
+function escapeJsxText(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('{', '&#123;');
+}
+
+function replaceRange(source: string, start: number, end: number, value: string): string {
+  return `${source.slice(0, start)}${value}${source.slice(end)}`;
+}
+
+function assertValidSource(source: string, node: SourceNodeRecord): void {
+  if (node.sourceLanguage === 'astro') {
+    const result = parseAstro(source);
+    const error = result.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+    if (error !== undefined) {
+      throw new Error(`Source transformation made ${node.source.file} invalid: ${error.text}`);
+    }
+    return;
+  }
+
+  try {
+    parseJavaScript(source, {
+      sourceType: 'unambiguous',
+      plugins: node.sourceLanguage === 'tsx' ? ['jsx', 'typescript'] : ['jsx'],
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : 'Unknown parser error.';
+    throw new Error(`Source transformation made ${node.source.file} invalid: ${detail}`);
+  }
+}
+
+function assertValidFile(source: string, file: string): void {
+  if (file.endsWith('.astro')) {
+    const error = parseAstro(source).diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+    if (error !== undefined) throw new Error(`Source transformation made ${file} invalid: ${error.text}`);
+    return;
+  }
+  try {
+    parseJavaScript(source, { sourceType: 'unambiguous', plugins: file.endsWith('.tsx') ? ['jsx', 'typescript'] : ['jsx'] });
+  } catch (error) {
+    throw new Error(`Source transformation made ${file} invalid: ${error instanceof Error ? error.message : 'Unknown parser error.'}`);
+  }
+}

package/src/visual/commands.ts

@@ -0,0 +1,37 @@
+export type EditLiteralTextCommand = {
+  kind: 'edit-literal-text';
+  nodeId: string;
+  text: string;
+};
+
+export type ReorderSiblingCommand = {
+  kind: 'reorder-sibling';
+  nodeId: string;
+  direction: 'previous' | 'next';
+};
+
+export type SetLiteralPropCommand = {
+  kind: 'set-literal-prop';
+  nodeId: string;
+  prop: string;
+  value: string | number | boolean;
+};
+
+export type RemoveSourceNodeCommand = { kind: 'remove-source-node'; nodeId: string };
+export type MoveToSlotCommand = { kind: 'move-to-slot'; nodeId: string; targetNodeId: string; slot: string };
+export type InsertLiteralElementCommand = {
+  kind: 'insert-literal-element';
+  file: string;
+  parentNodeId?: string;
+  slot?: string;
+  tag: string;
+  text: string;
+};
+
+export type DeterministicVisualCommand =
+  | EditLiteralTextCommand
+  | ReorderSiblingCommand
+  | SetLiteralPropCommand
+  | RemoveSourceNodeCommand
+  | MoveToSlotCommand
+  | InsertLiteralElementCommand;

package/src/visual/patch-transactions.ts

@@ -0,0 +1,270 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import type { AstroResolver } from '../resolver/astro-resolver.js';
+
+export type PatchTransactionKind = 'edit-literal-text' | 'reorder-sibling' | 'set-literal-prop' | 'remove-source-node' | 'move-to-slot' | 'insert-literal-element' | 'agent';
+export type ProposedFileChange = { file: string; before?: string; after?: string };
+export type PatchConflict = { file: string; reason: string; recoveryFile?: string };
+export type PatchTransactionHooks = {
+  beforeApply?(absoluteFiles: string[]): void | Promise<void>;
+  afterApply?(absoluteFiles: string[]): void | Promise<void>;
+  historyFile?: string | false;
+  onHistoryWarning?(message: string): void;
+  maxRecoveryFiles?: number;
+};
+type StoredFileChange = ProposedFileChange;
+export type PatchTransaction = { id: string; kind: PatchTransactionKind; changes: StoredFileChange[]; createdAt: string };
+export type PatchTransactionSummary = {
+  id: string;
+  kind: PatchTransactionKind;
+  file: string;
+  files: string[];
+  createdAt: string;
+  diff: string;
+  conflicts?: PatchConflict[];
+};
+export type PatchHistoryState = { canUndo: boolean; canRedo: boolean; undoLabel?: PatchTransactionKind; redoLabel?: PatchTransactionKind };
+type PersistedHistory = { version: 1; undo: PatchTransaction[]; redo: PatchTransaction[] };
+const DEFAULT_MAX_RECOVERY_FILES = 20;
+
+export class PatchTransactionStore {
+  readonly #resolver: AstroResolver;
+  readonly #hooks: PatchTransactionHooks;
+  readonly #historyFile: string | false;
+  readonly #undoStack: PatchTransaction[] = [];
+  readonly #redoStack: PatchTransaction[] = [];
+  readonly #readyPromise: Promise<void>;
+
+  constructor(resolver: AstroResolver, hooks: PatchTransactionHooks = {}) {
+    this.#resolver = resolver;
+    this.#hooks = hooks;
+    this.#historyFile = hooks.historyFile === undefined
+      ? join(resolver.projectRoot, '.astro', 'astro-ai', 'transactions.json')
+      : hooks.historyFile;
+    this.#readyPromise = this.#load();
+  }
+
+  ready(): Promise<void> { return this.#readyPromise; }
+
+  commit(kind: PatchTransactionKind, file: string, before: string, after: string): Promise<PatchTransactionSummary> {
+    return this.commitBatch(kind, [{ file, before, after }]);
+  }
+
+  async commitBatch(kind: PatchTransactionKind, proposed: ProposedFileChange[]): Promise<PatchTransactionSummary> {
+    await this.ready();
+    const normalized = proposed.filter(({ before, after }) => before !== after).map(({ file, before, after }) => ({
+      file: this.#resolver.toProjectPath(file),
+      ...(before === undefined ? {} : { before }),
+      ...(after === undefined ? {} : { after }),
+    }));
+    if (normalized.length === 0) throw new Error('The operation would not change the source.');
+
+    const changes: StoredFileChange[] = [];
+    const conflicts: PatchConflict[] = [];
+    for (const change of normalized) {
+      const current = await readOptional(this.#resolver.toAbsoluteProjectFile(change.file));
+      const merged = reconcileChange(change.before, change.after, current);
+      if (!merged.ok) {
+        conflicts.push({ file: change.file, reason: merged.reason });
+        continue;
+      }
+      changes.push({ file: change.file, ...(current === undefined ? {} : { before: current }), ...(merged.after === undefined ? {} : { after: merged.after }) });
+    }
+    if (conflicts.length > 0) await this.#writeRecovery(normalized, conflicts);
+    if (changes.length === 0) {
+      throw new Error(`No files were applied because the source changed during the agent run. The generated diff was saved for recovery. Conflicts: ${conflicts.map(({ file }) => file).join(', ')}`);
+    }
+
+    await this.#applyWithBoundary(changes, 'after', 'before');
+    const transaction: PatchTransaction = { id: randomUUID(), kind, changes, createdAt: new Date().toISOString() };
+    this.#undoStack.push(transaction);
+    this.#redoStack.length = 0;
+    await this.#persist();
+    return summarize(transaction, conflicts);
+  }
+
+  async undo(): Promise<PatchTransactionSummary> {
+    await this.ready();
+    const skipped: PatchConflict[] = [];
+    while (this.#undoStack.length > 0) {
+      const transaction = this.#undoStack.pop();
+      if (transaction === undefined) break;
+      const { compatible, conflicts } = await this.#compatibleChanges(transaction.changes, 'after');
+      skipped.push(...conflicts);
+      if (compatible.length === 0) continue;
+      await this.#applyWithBoundary(compatible, 'before', 'after');
+      const applied = { ...transaction, changes: compatible };
+      this.#redoStack.push(applied);
+      await this.#persist();
+      return summarize(applied, skipped);
+    }
+    await this.#persist();
+    if (skipped.length > 0) throw new Error('Undo skipped externally modified transactions; no older compatible transaction remains.');
+    throw new Error('There is no visual operation to undo.');
+  }
+
+  async redo(): Promise<PatchTransactionSummary> {
+    await this.ready();
+    const skipped: PatchConflict[] = [];
+    while (this.#redoStack.length > 0) {
+      const transaction = this.#redoStack.pop();
+      if (transaction === undefined) break;
+      const { compatible, conflicts } = await this.#compatibleChanges(transaction.changes, 'before');
+      skipped.push(...conflicts);
+      if (compatible.length === 0) continue;
+      await this.#applyWithBoundary(compatible, 'after', 'before');
+      const applied = { ...transaction, changes: compatible };
+      this.#undoStack.push(applied);
+      await this.#persist();
+      return summarize(applied, skipped);
+    }
+    await this.#persist();
+    if (skipped.length > 0) throw new Error('Redo skipped externally modified transactions; no older compatible transaction remains.');
+    throw new Error('There is no visual operation to redo.');
+  }
+
+  state(): PatchHistoryState {
+    const undo = this.#undoStack.at(-1);
+    const redo = this.#redoStack.at(-1);
+    return { canUndo: undo !== undefined, canRedo: redo !== undefined, ...(undo === undefined ? {} : { undoLabel: undo.kind }), ...(redo === undefined ? {} : { redoLabel: redo.kind }) };
+  }
+
+  async #compatibleChanges(changes: StoredFileChange[], expectedKey: 'before' | 'after'): Promise<{ compatible: StoredFileChange[]; conflicts: PatchConflict[] }> {
+    const compatible: StoredFileChange[] = [];
+    const conflicts: PatchConflict[] = [];
+    for (const change of changes) {
+      const current = await readOptional(this.#resolver.toAbsoluteProjectFile(change.file));
+      if (current === change[expectedKey]) compatible.push(change);
+      else conflicts.push({ file: change.file, reason: 'The file was changed outside this transaction and was left untouched.' });
+    }
+    return { compatible, conflicts };
+  }
+
+  async #applyWithRollback(changes: StoredFileChange[], targetKey: 'before' | 'after', rollbackKey: 'before' | 'after'): Promise<void> {
+    const applied: StoredFileChange[] = [];
+    try {
+      for (const change of changes) { await this.#write(change.file, change[targetKey]); applied.push(change); }
+    } catch (error) {
+      for (const change of applied.reverse()) await this.#write(change.file, change[rollbackKey]);
+      throw error;
+    }
+  }
+
+  async #applyWithBoundary(changes: StoredFileChange[], targetKey: 'before' | 'after', rollbackKey: 'before' | 'after'): Promise<void> {
+    const absoluteFiles = changes.map(({ file }) => this.#resolver.toAbsoluteProjectFile(file));
+    await this.#hooks.beforeApply?.(absoluteFiles);
+    try { await this.#applyWithRollback(changes, targetKey, rollbackKey); }
+    finally { await this.#hooks.afterApply?.(absoluteFiles); }
+  }
+
+  async #write(projectFile: string, content: string | undefined): Promise<void> {
+    const absoluteFile = this.#resolver.toAbsoluteProjectFile(projectFile);
+    if (content === undefined) {
+      await rm(absoluteFile, { force: true });
+      if (isSourceFile(absoluteFile)) this.#resolver.removeFile(absoluteFile);
+      return;
+    }
+    await mkdir(dirname(absoluteFile), { recursive: true });
+    await writeFile(absoluteFile, content, 'utf8');
+    // Vite's watcher is the single re-indexing path, avoiding a duplicate parse.
+  }
+
+  async #load(): Promise<void> {
+    if (this.#historyFile === false) return;
+    try {
+      const parsed = JSON.parse(await readFile(this.#historyFile, 'utf8')) as PersistedHistory;
+      if (parsed.version !== 1 || !Array.isArray(parsed.undo) || !Array.isArray(parsed.redo)) {
+        this.#hooks.onHistoryWarning?.(`Ignored invalid visual transaction history at ${this.#historyFile}. Delete the file to reset undo history.`);
+        return;
+      }
+      this.#undoStack.push(...parsed.undo.slice(-50));
+      this.#redoStack.push(...parsed.redo.slice(-50));
+    } catch (error) {
+      if (isNotFound(error)) return;
+      const detail = error instanceof Error ? error.message : 'unknown read error';
+      this.#hooks.onHistoryWarning?.(`Could not load visual transaction history at ${this.#historyFile}: ${detail}. Delete the file to reset undo history.`);
+    }
+  }
+
+  async #persist(): Promise<void> {
+    if (this.#historyFile === false) return;
+    await mkdir(dirname(this.#historyFile), { recursive: true });
+    const temporary = `${this.#historyFile}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify({ version: 1, undo: this.#undoStack.slice(-50), redo: this.#redoStack.slice(-50) }), 'utf8');
+    await rename(temporary, this.#historyFile);
+  }
+
+  async #writeRecovery(changes: StoredFileChange[], conflicts: PatchConflict[]): Promise<void> {
+    if (this.#historyFile === false) return;
+    const recovery = join(dirname(this.#historyFile), 'recovery', `${Date.now()}-${randomUUID()}.diff`);
+    await mkdir(dirname(recovery), { recursive: true });
+    await writeFile(recovery, renderDiff(changes), 'utf8');
+    await pruneRecoveryDirectory(dirname(recovery), this.#hooks.maxRecoveryFiles ?? DEFAULT_MAX_RECOVERY_FILES);
+    for (const conflict of conflicts) conflict.recoveryFile = recovery;
+  }
+}
+
+export async function pruneRecoveryDirectory(
+  directory: string,
+  maximumFiles = DEFAULT_MAX_RECOVERY_FILES,
+): Promise<void> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const stale = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.diff'))
+    .map(({ name }) => name)
+    .sort((left, right) => right.localeCompare(left))
+    .slice(Math.max(0, maximumFiles));
+  await Promise.all(stale.map((name) => rm(join(directory, name), { force: true })));
+}
+
+type Reconciled = { ok: true; after?: string } | { ok: false; reason: string };
+function reconcileChange(before: string | undefined, after: string | undefined, current: string | undefined): Reconciled {
+  if (current === before) return { ok: true, ...(after === undefined ? {} : { after }) };
+  if (before === undefined || after === undefined || current === undefined) return { ok: false, reason: 'The file was created, removed, or replaced externally.' };
+  const merged = mergeSingleRegion(before, after, current);
+  return merged === undefined ? { ok: false, reason: 'The generated edit overlaps an external edit.' } : { ok: true, after: merged };
+}
+
+/** Applies a generated single-region edit when the same source region remains unique in current text. */
+export function mergeSingleRegion(base: string, generated: string, current: string): string | undefined {
+  let prefix = 0;
+  while (prefix < base.length && prefix < generated.length && base[prefix] === generated[prefix]) prefix += 1;
+  let suffix = 0;
+  while (suffix < base.length - prefix && suffix < generated.length - prefix && base[base.length - 1 - suffix] === generated[generated.length - 1 - suffix]) suffix += 1;
+  const removed = base.slice(prefix, base.length - suffix);
+  const inserted = generated.slice(prefix, generated.length - suffix);
+  if (removed === '') {
+    const left = base.slice(Math.max(0, prefix - 32), prefix);
+    const right = base.slice(prefix, Math.min(base.length, prefix + 32));
+    const anchor = `${left}${right}`;
+    const index = current.indexOf(anchor);
+    if (anchor === '' || index < 0 || current.indexOf(anchor, index + 1) >= 0) return undefined;
+    return `${current.slice(0, index + left.length)}${inserted}${current.slice(index + left.length)}`;
+  }
+  const index = current.indexOf(removed);
+  if (index < 0 || current.indexOf(removed, index + 1) >= 0) return undefined;
+  return `${current.slice(0, index)}${inserted}${current.slice(index + removed.length)}`;
+}
+
+function isSourceFile(file: string): boolean { return /\.(?:astro|jsx?|tsx?)$/.test(file); }
+async function readOptional(file: string): Promise<string | undefined> { try { return await readFile(file, 'utf8'); } catch (error) { if (isNotFound(error)) return undefined; throw error; } }
+function isNotFound(error: unknown): boolean { return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT'; }
+
+function summarize(transaction: PatchTransaction, conflicts: PatchConflict[] = []): PatchTransactionSummary {
+  const files = transaction.changes.map(({ file }) => file);
+  return { id: transaction.id, kind: transaction.kind, file: files[0] ?? '', files, createdAt: transaction.createdAt, diff: renderDiff(transaction.changes), ...(conflicts.length === 0 ? {} : { conflicts }) };
+}
+
+export function renderDiff(changes: StoredFileChange[]): string {
+  return changes.map(({ file, before = '', after = '' }) => {
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    let prefix = 0;
+    while (prefix < beforeLines.length && prefix < afterLines.length && beforeLines[prefix] === afterLines[prefix]) prefix += 1;
+    let suffix = 0;
+    while (suffix < beforeLines.length - prefix && suffix < afterLines.length - prefix && beforeLines[beforeLines.length - 1 - suffix] === afterLines[afterLines.length - 1 - suffix]) suffix += 1;
+    return [`--- a/${file}`, `+++ b/${file}`, `@@ ${prefix + 1} @@`, ...beforeLines.slice(prefix, beforeLines.length - suffix).map((line) => `-${line}`), ...afterLines.slice(prefix, afterLines.length - suffix).map((line) => `+${line}`)].join('\n');
+  }).join('\n\n');
+}