1import { randomUUID } from 'node:crypto';
2import fs from 'node:fs';
3import path from 'node:path';
4import { getLiveDir } from '../lib/impeccable-paths.mjs';
5import { readBuffer as readManualEditsBuffer } from './manual-edits-buffer.mjs';
6 
7const APPLY_EVENT_HARD_TIMEOUT_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_HARD_TIMEOUT_MS || 150_000);
8const APPLY_EVENT_SOFT_DEADLINE_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_SOFT_DEADLINE_MS || 120_000);
9const DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE = 3;
10const MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE = 1;
11const MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE = 20;
12const MANUAL_APPLY_COMPACT_TEXT_LIMIT = 240;
13const MANUAL_APPLY_COMPACT_NEARBY_LIMIT = 4;
14 
15export function createManualApplyController({
16  pendingEvents,
17  pendingApplyDeferreds,
18  timedOutApplyIds,
19  enqueueEvent,
20  acknowledgePendingEvent,
21  flushPendingPolls,
22  recordManualEditActivity,
23  cwd = () => process.cwd(),
24} = {}) {
25  const projectCwd = () => typeof cwd === 'function' ? cwd() : cwd || process.cwd();
26 
27  function tombstoneTimedOutApplyId(eventId, details = {}) {
28    if (!eventId) return;
29    timedOutApplyIds.set(eventId, details);
30    if (timedOutApplyIds.size <= 200) return;
31    const oldest = timedOutApplyIds.keys().next().value;
32    timedOutApplyIds.delete(oldest);
33  }
34 
35  function pushApplyEventAndWait(batch, pageUrl, chunk = null, repair = null) {
36    const cwdValue = projectCwd();
37    const eventId = randomUUID().replace(/-/g, '').slice(0, 8);
38    const evidencePath = writeManualApplyEvidence(eventId, batch, cwdValue);
39    const event = {
40      type: 'manual_edit_apply',
41      id: eventId,
42      pageUrl,
43      batch: compactManualApplyBatch(batch, cwdValue),
44      evidencePath,
45      agentAction: buildManualApplyAgentAction(eventId),
46      schemaVersion: 1,
47      deadlineMs: APPLY_EVENT_SOFT_DEADLINE_MS,
48    };
49    if (chunk) event.chunk = chunk;
50    if (repair) event.repair = repair;
51    const rollbackSnapshot = snapshotApplyEventFiles(batch, cwdValue);
52    recordManualEditActivity('manual_edit_apply_dispatched', {
53      id: eventId,
54      pageUrl,
55      chunk,
56      repair,
57      entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
58      opCount: countManualApplyOps(batch),
59      fileCount: collectManualApplyFiles(batch, [], cwdValue).length,
60    });
61    return new Promise((resolve, reject) => {
62      const timer = setTimeout(() => {
63        pendingApplyDeferreds.delete(eventId);
64        tombstoneTimedOutApplyId(eventId, { batch, rollbackSnapshot, cwd: cwdValue });
65        acknowledgePendingEvent(eventId);
66        removeManualApplyEvidence(evidencePath, cwdValue);
67        recordManualEditActivity('manual_edit_apply_timeout', {
68          id: eventId,
69          pageUrl,
70          chunk,
71          entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
72          opCount: countManualApplyOps(batch),
73        });
74        reject(new Error('chat_agent_timeout'));
75      }, APPLY_EVENT_HARD_TIMEOUT_MS);
76      pendingApplyDeferreds.set(eventId, { resolve, reject, timer, event, batch, pageUrl, rollbackSnapshot, cwd: cwdValue });
77      enqueueEvent(event);
78    });
79  }
80 
81  async function pushBatchInChunksAndWait(batch, pageUrl, context = {}) {
82    const repair = context?.repair || batch?.repair || null;
83    if (repair) return pushApplyEventAndWait(batch, pageUrl, null, repair);
84    const chunks = splitManualApplyBatch(batch, manualEditApplyChunkSize());
85    if (chunks.length <= 1) return pushApplyEventAndWait(batch, pageUrl);
86 
87    const expectedOpsByEntry = new Map();
88    for (const entry of batch?.entries || []) {
89      expectedOpsByEntry.set(entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0);
90    }
91 
92    const appliedOpsByEntry = new Map();
93    const failedByEntry = new Map();
94    const files = new Set();
95    const notes = [];
96    let aborted = false;
97 
98    for (const chunk of chunks) {
99      if (aborted) {
100        markChunkEntriesFailed(failedByEntry, chunk, 'manual_edit_chunk_aborted');
101        continue;
102      }
103 
104      let result;
105      try {
106        result = normalizeApplyChunkResult(await pushApplyEventAndWait(chunk.batch, pageUrl, chunk.meta));
107      } catch (err) {
108        markChunkEntriesFailed(failedByEntry, chunk, err.message || 'chat_agent_error');
109        aborted = true;
110        continue;
111      }
112 
113      for (const file of result.files) files.add(file);
114      notes.push(...result.notes);
115 
116      const chunkFailedIds = new Set();
117      for (const item of result.failed) {
118        const entryId = item.entryId || item.id;
119        if (!entryId) continue;
120        chunkFailedIds.add(entryId);
121        if (!failedByEntry.has(entryId)) {
122          failedByEntry.set(entryId, {
123            entryId,
124            reason: item.reason || item.message || 'failed',
125            candidates: Array.isArray(item.candidates) ? item.candidates : [],
126          });
127        }
128      }
129 
130      if (result.status === 'error') {
131        markChunkEntriesFailed(failedByEntry, chunk, result.message || firstFailureReason(result) || 'chat_agent_error');
132        aborted = true;
133        continue;
134      }
135 
136      const reportedAppliedIds = new Set(result.appliedEntryIds);
137      for (const entryId of reportedAppliedIds) {
138        if (!chunk.entryIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
139        appliedOpsByEntry.set(entryId, (appliedOpsByEntry.get(entryId) || 0) + (chunk.opCountsByEntry.get(entryId) || 0));
140      }
141 
142      for (const entryId of chunk.entryIds) {
143        if (reportedAppliedIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
144        if (!failedByEntry.has(entryId)) {
145          failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
146        }
147      }
148    }
149 
150    const appliedEntryIds = [];
151    for (const [entryId, expectedOps] of expectedOpsByEntry.entries()) {
152      if (failedByEntry.has(entryId)) continue;
153      if ((appliedOpsByEntry.get(entryId) || 0) === expectedOps && expectedOps > 0) {
154        appliedEntryIds.push(entryId);
155      } else if (!failedByEntry.has(entryId)) {
156        failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
157      }
158    }
159 
160    const failed = [...failedByEntry.values()];
161    return {
162      status: failed.length === 0 ? 'done' : appliedEntryIds.length > 0 ? 'partial' : 'error',
163      appliedEntryIds,
164      failed,
165      files: [...files],
166      notes,
167    };
168  }
169 
170  function getDeferred(eventId) {
171    return pendingApplyDeferreds.get(eventId) || null;
172  }
173 
174  function hasTimedOutId(eventId) {
175    return timedOutApplyIds.has(eventId);
176  }
177 
178  function resolveDeferred(eventId, body) {
179    const deferred = pendingApplyDeferreds.get(eventId);
180    if (!deferred) return false;
181    pendingApplyDeferreds.delete(eventId);
182    clearTimeout(deferred.timer);
183    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
184    deferred.resolve(body);
185    return true;
186  }
187 
188  function rejectDeferred(eventId, reason) {
189    const deferred = pendingApplyDeferreds.get(eventId);
190    if (!deferred) return false;
191    pendingApplyDeferreds.delete(eventId);
192    clearTimeout(deferred.timer);
193    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
194    deferred.reject(new Error(reason || 'chat_agent_error'));
195    return true;
196  }
197 
198  function referencedManualApplyEvidencePaths(cwdValue = projectCwd()) {
199    const referenced = new Set();
200    const add = (event) => {
201      const fullPath = normalizeManualApplyEvidencePath(event?.evidencePath, cwdValue);
202      if (fullPath) referenced.add(fullPath);
203    };
204    for (const entry of pendingEvents) add(entry.event);
205    for (const deferred of pendingApplyDeferreds.values()) add(deferred.event);
206    return referenced;
207  }
208 
209  function pruneStaleEvidence(cwdValue = projectCwd()) {
210    const dir = manualApplyEvidenceDir(cwdValue);
211    if (!fs.existsSync(dir)) return [];
212    const referenced = referencedManualApplyEvidencePaths(cwdValue);
213    const removed = [];
214    for (const name of fs.readdirSync(dir)) {
215      if (!name.endsWith('.json')) continue;
216      const fullPath = path.join(dir, name);
217      if (referenced.has(fullPath)) continue;
218      try {
219        fs.unlinkSync(fullPath);
220        removed.push(fullPath);
221      } catch {
222        // Stale evidence cleanup is best-effort; Apply verification never relies
223        // on deleting these files.
224      }
225    }
226    return removed;
227  }
228 
229  function rollbackTimedOutReply(msg) {
230    const details = timedOutApplyIds.get(msg.id);
231    if (!details) return { rolledBackFiles: [], rollbackFailures: [] };
232    timedOutApplyIds.delete(msg.id);
233    return rollbackApplySnapshot(
234      details.batch,
235      details.rollbackSnapshot,
236      msg.data?.files || [],
237      'stale_manual_edit_apply_reply',
238      details.cwd || projectCwd(),
239    );
240  }
241 
242  function cancelPendingEvents(pageUrl, reason = 'manual_edit_discarded') {
243    const canceledById = new Map();
244    const shouldCancel = (event) => event?.type === 'manual_edit_apply' && (!pageUrl || event.pageUrl === pageUrl);
245 
246    for (let i = pendingEvents.length - 1; i >= 0; i -= 1) {
247      const event = pendingEvents[i]?.event;
248      if (!shouldCancel(event)) continue;
249      pendingEvents.splice(i, 1);
250      removeManualApplyEvidence(event.evidencePath, projectCwd());
251      canceledById.set(event.id, {
252        id: event.id,
253        pageUrl: event.pageUrl,
254        entryCount: event.batch?.entries?.length || 0,
255      });
256    }
257 
258    for (const [eventId, deferred] of [...pendingApplyDeferreds.entries()]) {
259      if (!shouldCancel(deferred.event)) continue;
260      pendingApplyDeferreds.delete(eventId);
261      clearTimeout(deferred.timer);
262      const cwdValue = deferred.cwd || projectCwd();
263      const rollback = rollbackApplySnapshot(deferred.batch, deferred.rollbackSnapshot, [], reason, cwdValue);
264      tombstoneTimedOutApplyId(eventId, {
265        batch: deferred.batch,
266        rollbackSnapshot: deferred.rollbackSnapshot,
267        reason,
268        cwd: cwdValue,
269      });
270      removeManualApplyEvidence(deferred.event?.evidencePath, cwdValue);
271      canceledById.set(eventId, {
272        id: eventId,
273        pageUrl: deferred.pageUrl,
274        entryCount: deferred.batch?.entries?.length || 0,
275        rolledBackFiles: rollback.rolledBackFiles,
276        rollbackFailures: rollback.rollbackFailures,
277      });
278      deferred.reject(new Error(reason));
279    }
280 
281    if (canceledById.size > 0) flushPendingPolls();
282    return [...canceledById.values()];
283  }
284 
285  return {
286    buildAgentAction: buildManualApplyAgentAction,
287    cancelPendingEvents,
288    clearTransaction: (transactionId = null) => clearManualApplyTransaction(projectCwd(), transactionId),
289    countOps: countManualApplyOps,
290    getDeferred,
291    hasTimedOutId,
292    pruneStaleEvidence,
293    pushBatchInChunksAndWait,
294    readTransaction: () => readManualApplyTransaction(projectCwd()),
295    rejectDeferred,
296    resolveDeferred,
297    rollbackTimedOutReply,
298    rollbackTransaction: (opts = {}) => rollbackManualApplyTransaction({
299      cwd: projectCwd(),
300      recordManualEditActivity,
301      ...opts,
302    }),
303    summarizeEvent: (event = {}, batch = event.batch) => summarizeManualApplyEvent(event, batch, projectCwd()),
304    validateResultMessage: validateManualApplyResultMessage,
305    writeTransaction: (opts = {}) => writeManualApplyTransaction({ cwd: projectCwd(), ...opts }),
306  };
307}
308 
309export function manualEditApplyChunkSize(env = process.env) {
310  const raw = Number(env.IMPECCABLE_LIVE_MANUAL_EDIT_CHUNK_SIZE);
311  if (!Number.isFinite(raw)) return DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE;
312  const size = Math.trunc(raw);
313  return Math.max(MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE, Math.min(MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE, size));
314}
315 
316export function countManualApplyOps(entriesOrBatch) {
317  const entries = Array.isArray(entriesOrBatch)
318    ? entriesOrBatch
319    : Array.isArray(entriesOrBatch?.entries) ? entriesOrBatch.entries : [];
320  let count = 0;
321  for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
322  return count;
323}
324 
325export function writeManualApplyEvidence(eventId, batch, cwd = process.cwd()) {
326  const dir = manualApplyEvidenceDir(cwd);
327  fs.mkdirSync(dir, { recursive: true });
328  const evidencePath = path.join(dir, `${eventId}.json`);
329  fs.writeFileSync(evidencePath, JSON.stringify(batch, null, 2) + '\n', 'utf-8');
330  return evidencePath;
331}
332 
333export function manualApplyEvidenceDir(cwd = process.cwd()) {
334  return path.join(getLiveDir(cwd), 'manual-edit-evidence');
335}
336 
337export function normalizeManualApplyEvidencePath(evidencePath, cwd = process.cwd()) {
338  if (!evidencePath || typeof evidencePath !== 'string') return null;
339  const fullPath = path.isAbsolute(evidencePath) ? evidencePath : path.resolve(cwd, evidencePath);
340  const evidenceDir = manualApplyEvidenceDir(cwd);
341  const relative = path.relative(evidenceDir, fullPath);
342  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
343  if (path.extname(relative) !== '.json') return null;
344  return fullPath;
345}
346 
347export function removeManualApplyEvidence(evidencePath, cwd = process.cwd()) {
348  const fullPath = normalizeManualApplyEvidencePath(evidencePath, cwd);
349  if (!fullPath) return false;
350  try {
351    fs.unlinkSync(fullPath);
352    return true;
353  } catch {
354    return false;
355  }
356}
357 
358export function compactManualApplyBatch(batch = {}, cwd = process.cwd()) {
359  const entries = (batch.entries || []).map(compactManualApplyEntry);
360  const candidates = compactManualApplyCandidates(batch.candidates || [], cwd);
361  return {
362    version: batch.version,
363    pageUrl: batch.pageUrl || null,
364    count: batch.count,
365    entries,
366    ops: entries.flatMap((entry) => entry.ops.map((op) => ({ ...op, entryId: entry.id }))),
367    candidates: candidates.length > 0 ? candidates : undefined,
368    context: batch.context ? {
369      bufferPath: batch.context.bufferPath,
370      totalEntries: batch.context.totalEntries,
371      totalOps: batch.context.totalOps,
372      chunkIndex: batch.context.chunkIndex,
373      chunkTotal: batch.context.chunkTotal,
374      totalApplyOps: batch.context.totalApplyOps,
375    } : undefined,
376  };
377}
378 
379export function compactManualApplyCandidates(candidates, cwd = process.cwd()) {
380  return (Array.isArray(candidates) ? candidates : [])
381    .slice(0, 24)
382    .map((candidate) => ({
383      entryId: candidate.entryId,
384      ref: candidate.ref,
385      sourceHint: compactManualApplySourceMatch(candidate.sourceHint, cwd),
386      textMatches: compactManualApplySourceMatches(candidate.textMatches, 8, cwd),
387      objectKeyMatches: compactManualApplySourceMatches(candidate.objectKeyMatches, 8, cwd),
388      contextTextMatches: compactManualApplySourceMatches(candidate.contextTextMatches, 8, cwd),
389      locatorMatches: compactManualApplySourceMatches(candidate.locatorMatches, 6, cwd),
390    }));
391}
392 
393function compactManualApplySourceMatches(matches, limit, cwd) {
394  return (Array.isArray(matches) ? matches : [])
395    .slice(0, limit)
396    .map((match) => compactManualApplySourceMatch(match, cwd))
397    .filter(Boolean);
398}
399 
400function compactManualApplySourceMatch(match, cwd) {
401  if (!match || typeof match !== 'object') return null;
402  const file = match.relativeFile || match.file;
403  if (!file && !match.line) return null;
404  return {
405    file: summarizeManualLogFile(file, cwd),
406    line: match.line || null,
407    column: match.column || null,
408    reason: match.reason || match.kind || undefined,
409    status: match.status || undefined,
410  };
411}
412 
413function compactManualApplyEntry(entry = {}) {
414  return {
415    id: entry.id,
416    pageUrl: entry.pageUrl,
417    stagedAt: entry.stagedAt || null,
418    element: compactManualApplyContext(entry.element),
419    ops: (entry.ops || []).map(compactManualApplyOp),
420  };
421}
422 
423function compactManualApplyOp(op = {}) {
424  return {
425    entryId: op.entryId,
426    ref: op.ref,
427    contextRef: op.contextRef,
428    tag: op.tag,
429    elementId: op.elementId,
430    classes: Array.isArray(op.classes) ? op.classes : [],
431    originalText: op.originalText,
432    newText: op.newText,
433    deleted: op.deleted === true || undefined,
434    sourceHint: op.sourceHint || null,
435    leaf: compactManualApplyContext(op.leaf),
436    nearbyEditableTexts: compactNearbyManualEditTexts(op.nearbyEditableTexts),
437    container: compactManualApplyContext(op.container),
438    contextHints: Array.isArray(op.contextHints) ? op.contextHints.slice(0, 8) : undefined,
439  };
440}
441 
442function compactManualApplyContext(value) {
443  if (!value || typeof value !== 'object') return null;
444  return {
445    ref: value.ref,
446    tagName: value.tagName || value.tag || null,
447    id: value.id || null,
448    classes: Array.isArray(value.classes) ? value.classes : [],
449    textContent: truncateManualApplyText(value.textContent, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
450  };
451}
452 
453function compactNearbyManualEditTexts(items) {
454  return (Array.isArray(items) ? items : [])
455    .slice(0, MANUAL_APPLY_COMPACT_NEARBY_LIMIT)
456    .map((item) => typeof item === 'string' ? { text: truncateManualApplyText(item, MANUAL_APPLY_COMPACT_TEXT_LIMIT) } : {
457      ref: item?.ref,
458      tag: item?.tag,
459      classes: Array.isArray(item?.classes) ? item.classes : [],
460      text: truncateManualApplyText(item?.text, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
461    });
462}
463 
464function truncateManualApplyText(value, max) {
465  if (typeof value !== 'string') return value || null;
466  return value.length > max ? value.slice(0, max) : value;
467}
468 
469function normalizeApplyChunkResult(result) {
470  const status = result?.status === 'partial' ? 'partial' : result?.status === 'error' ? 'error' : 'done';
471  return {
472    status,
473    message: typeof result?.message === 'string' ? result.message : null,
474    appliedEntryIds: Array.isArray(result?.appliedEntryIds) ? result.appliedEntryIds.filter((id) => typeof id === 'string') : [],
475    failed: Array.isArray(result?.failed) ? result.failed.filter(Boolean) : [],
476    files: Array.isArray(result?.files) ? result.files.filter((file) => typeof file === 'string') : [],
477    notes: Array.isArray(result?.notes) ? result.notes.filter((note) => typeof note === 'string') : [],
478  };
479}
480 
481function manualApplyResultShapeHint(eventId = 'EVENT_ID') {
482  return `Use live-poll.mjs --reply ${eventId} done --data '{"status":"done","appliedEntryIds":["ENTRY_ID"],"failed":[],"files":["src/page.html"],"notes":[]}'`;
483}
484 
485function invalidManualApplyResult(reason, eventId, extra = {}) {
486  return {
487    ok: false,
488    body: {
489      error: 'invalid_manual_apply_result',
490      reason,
491      hint: manualApplyResultShapeHint(eventId),
492      ...extra,
493    },
494  };
495}
496 
497export function validateManualApplyResultMessage(msg, deferred) {
498  let data = msg?.data;
499  const eventId = msg?.id || deferred?.event?.id || 'EVENT_ID';
500  if (!data || typeof data !== 'object' || Array.isArray(data)) {
501    return invalidManualApplyResult('missing_result_data', eventId);
502  }
503  if ('entries' in data || 'ops' in data) {
504    return invalidManualApplyResult('summary_result_not_allowed', eventId);
505  }
506  if (!['done', 'partial', 'error'].includes(data.status)) {
507    return invalidManualApplyResult('invalid_status', eventId, { status: data.status ?? null });
508  }
509 
510  for (const key of ['appliedEntryIds', 'failed', 'files', 'notes']) {
511    if (!Array.isArray(data[key])) {
512      return invalidManualApplyResult(`${key}_must_be_array`, eventId);
513    }
514  }
515 
516  for (const [index, value] of data.appliedEntryIds.entries()) {
517    if (typeof value !== 'string' || !value) {
518      return invalidManualApplyResult('appliedEntryIds_must_contain_strings', eventId, { index });
519    }
520  }
521  for (const [index, value] of data.files.entries()) {
522    if (typeof value !== 'string' || !value) {
523      return invalidManualApplyResult('files_must_contain_strings', eventId, { index });
524    }
525  }
526  for (const [index, value] of data.notes.entries()) {
527    if (typeof value !== 'string') {
528      return invalidManualApplyResult('notes_must_contain_strings', eventId, { index });
529    }
530  }
531  for (const [index, item] of data.failed.entries()) {
532    if (!item || typeof item !== 'object' || Array.isArray(item)) {
533      return invalidManualApplyResult('failed_must_contain_objects', eventId, { index });
534    }
535    if (typeof item.entryId !== 'string' || !item.entryId) {
536      return invalidManualApplyResult('failed_entryId_required', eventId, { index });
537    }
538    if (typeof item.reason !== 'string' || !item.reason) {
539      return invalidManualApplyResult('failed_reason_required', eventId, { index });
540    }
541  }
542 
543  const eventEntryIds = new Set((deferred?.batch?.entries || []).map((entry) => entry.id).filter(Boolean));
544  for (const entryId of data.appliedEntryIds) {
545    if (eventEntryIds.size > 0 && !eventEntryIds.has(entryId)) {
546      return invalidManualApplyResult('applied_entry_id_not_in_event', eventId, { entryId });
547    }
548  }
549  for (const item of data.failed) {
550    if (eventEntryIds.size > 0 && !eventEntryIds.has(item.entryId)) {
551      return invalidManualApplyResult('failed_entry_id_not_in_event', eventId, { entryId: item.entryId });
552    }
553  }
554 
555  if (data.status === 'done') {
556    if (data.failed.length > 0) {
557      return invalidManualApplyResult('done_result_has_failed_entries', eventId);
558    }
559    if (countManualApplyOps(deferred?.batch) > 0 && data.appliedEntryIds.length === 0) {
560      return invalidManualApplyResult('done_result_missing_applied_entry_ids', eventId);
561    }
562  }
563  if (data.status === 'partial' && data.appliedEntryIds.length === 0 && data.failed.length === 0) {
564    return invalidManualApplyResult('partial_result_has_no_entries', eventId);
565  }
566  if (data.status === 'error' && data.appliedEntryIds.length > 0) {
567    return invalidManualApplyResult('error_result_has_applied_entries', eventId);
568  }
569 
570  return {
571    ok: true,
572    result: {
573      status: data.status,
574      message: typeof data.message === 'string' ? data.message : undefined,
575      appliedEntryIds: data.appliedEntryIds,
576      failed: data.failed,
577      files: data.files,
578      notes: data.notes,
579    },
580  };
581}
582 
583function firstFailureReason(result) {
584  const first = Array.isArray(result?.failed) ? result.failed.find(Boolean) : null;
585  return first?.reason || first?.message || null;
586}
587 
588function markChunkEntriesFailed(failedByEntry, chunk, reason) {
589  for (const entryId of chunk.entryIds) {
590    if (failedByEntry.has(entryId)) continue;
591    failedByEntry.set(entryId, { entryId, reason, candidates: [] });
592  }
593}
594 
595export function splitManualApplyBatch(batch, maxOps) {
596  const totalOpCount = countManualApplyOps(batch);
597  if (totalOpCount <= maxOps) {
598    return [{
599      batch,
600      meta: null,
601      entryIds: new Set((batch?.entries || []).map((entry) => entry.id).filter(Boolean)),
602      opCountsByEntry: new Map((batch?.entries || []).map((entry) => [entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0])),
603    }];
604  }
605 
606  const rawChunks = [];
607  let current = createManualApplyChunkBuilder();
608  for (const entry of batch?.entries || []) {
609    const ops = entry.ops || [];
610    if (ops.length <= maxOps) {
611      if (current.opCount > 0 && current.opCount + ops.length > maxOps) {
612        rawChunks.push(current);
613        current = createManualApplyChunkBuilder();
614      }
615      for (const op of ops) addOpToManualApplyChunk(current, entry, op);
616      continue;
617    }
618    if (current.opCount > 0) {
619      rawChunks.push(current);
620      current = createManualApplyChunkBuilder();
621    }
622    for (const op of ops) {
623      if (current.opCount >= maxOps) {
624        rawChunks.push(current);
625        current = createManualApplyChunkBuilder();
626      }
627      addOpToManualApplyChunk(current, entry, op);
628    }
629  }
630  if (current.opCount > 0) rawChunks.push(current);
631 
632  return rawChunks.map((chunk, index) => ({
633    batch: {
634      ...batch,
635      count: chunk.opCount,
636      entries: chunk.entries,
637      ops: chunk.ops,
638      candidates: filterManualApplyChunkCandidates(batch, chunk.refsByEntry),
639      context: {
640        ...(batch?.context || {}),
641        totalEntries: chunk.entries.length,
642        totalOps: chunk.opCount,
643        chunkIndex: index + 1,
644        chunkTotal: rawChunks.length,
645        totalApplyOps: totalOpCount,
646      },
647    },
648    meta: {
649      index: index + 1,
650      total: rawChunks.length,
651      opCount: chunk.opCount,
652      totalOpCount,
653    },
654    entryIds: new Set(chunk.entries.map((entry) => entry.id).filter(Boolean)),
655    opCountsByEntry: chunk.opCountsByEntry,
656  }));
657}
658 
659function createManualApplyChunkBuilder() {
660  return {
661    entries: [],
662    entryById: new Map(),
663    entryIds: new Set(),
664    ops: [],
665    refsByEntry: new Map(),
666    opCountsByEntry: new Map(),
667    opCount: 0,
668  };
669}
670 
671function addOpToManualApplyChunk(chunk, entry, op) {
672  let chunkEntry = chunk.entryById.get(entry.id);
673  if (!chunkEntry) {
674    chunkEntry = { ...entry, ops: [] };
675    chunk.entryById.set(entry.id, chunkEntry);
676    chunk.entryIds.add(entry.id);
677    chunk.entries.push(chunkEntry);
678  }
679  chunkEntry.ops.push(op);
680  chunk.ops.push({ ...op, entryId: op.entryId || entry.id });
681  if (!chunk.refsByEntry.has(entry.id)) chunk.refsByEntry.set(entry.id, new Set());
682  if (op.ref) chunk.refsByEntry.get(entry.id).add(op.ref);
683  chunk.opCountsByEntry.set(entry.id, (chunk.opCountsByEntry.get(entry.id) || 0) + 1);
684  chunk.opCount += 1;
685}
686 
687function filterManualApplyChunkCandidates(batch, refsByEntry) {
688  return (batch?.candidates || []).filter((candidate) => {
689    const refs = refsByEntry.get(candidate.entryId);
690    if (!refs) return false;
691    if (!candidate.ref) return true;
692    return refs.has(candidate.ref);
693  });
694}
695 
696export function snapshotApplyEventFiles(batch, cwd = process.cwd()) {
697  const snapshot = new Map();
698  for (const relativeFile of collectManualApplyFiles(batch, [], cwd)) {
699    const absolute = path.resolve(cwd, relativeFile);
700    try {
701      snapshot.set(relativeFile, {
702        exists: fs.existsSync(absolute),
703        content: fs.existsSync(absolute) ? fs.readFileSync(absolute, 'utf-8') : '',
704      });
705    } catch {
706      // If a file cannot be read before dispatch, do not attempt late rollback.
707    }
708  }
709  return snapshot;
710}
711 
712export function manualApplyTransactionPath(cwd = process.cwd()) {
713  return path.join(getLiveDir(cwd), 'manual-edit-apply-transaction.json');
714}
715 
716export function readManualApplyTransaction(cwd = process.cwd()) {
717  const file = manualApplyTransactionPath(cwd);
718  if (!fs.existsSync(file)) return null;
719  try {
720    return JSON.parse(fs.readFileSync(file, 'utf-8'));
721  } catch {
722    return null;
723  }
724}
725 
726export function writeManualApplyTransaction({ cwd = process.cwd(), pageUrl = null, batch }) {
727  const file = manualApplyTransactionPath(cwd);
728  const files = collectManualApplyFiles(batch, [], cwd);
729  const transaction = {
730    version: 1,
731    id: randomUUID().replace(/-/g, '').slice(0, 8),
732    createdAt: new Date().toISOString(),
733    pageUrl,
734    entryIds: (batch?.entries || []).map((entry) => entry.id).filter(Boolean),
735    files: files.map((relativeFile) => {
736      const absolute = path.resolve(cwd, relativeFile);
737      const exists = fs.existsSync(absolute);
738      return {
739        file: relativeFile,
740        exists,
741        content: exists ? fs.readFileSync(absolute, 'utf-8') : '',
742      };
743    }),
744  };
745  fs.mkdirSync(path.dirname(file), { recursive: true });
746  fs.writeFileSync(`${file}.tmp`, JSON.stringify(transaction, null, 2) + '\n', 'utf-8');
747  fs.renameSync(`${file}.tmp`, file);
748  return transaction;
749}
750 
751export function clearManualApplyTransaction(cwd = process.cwd(), transactionId = null) {
752  const file = manualApplyTransactionPath(cwd);
753  if (!fs.existsSync(file)) return false;
754  if (transactionId) {
755    const existing = readManualApplyTransaction(cwd);
756    if (existing?.id && existing.id !== transactionId) return false;
757  }
758  try {
759    fs.unlinkSync(file);
760    return true;
761  } catch {
762    return false;
763  }
764}
765 
766export function rollbackManualApplyTransaction({
767  cwd = process.cwd(),
768  pageUrl = null,
769  reason = 'manual_edit_transaction_rollback',
770  recordManualEditActivity = null,
771} = {}) {
772  const transaction = readManualApplyTransaction(cwd);
773  if (!transaction) return null;
774  if (pageUrl && transaction.pageUrl && transaction.pageUrl !== pageUrl) return null;
775 
776  let pendingIds = new Set();
777  try {
778    const buffer = readManualEditsBuffer(cwd);
779    pendingIds = new Set((buffer.entries || []).map((entry) => entry.id).filter(Boolean));
780  } catch {
781    pendingIds = new Set(transaction.entryIds || []);
782  }
783  const shouldRollback = (transaction.entryIds || []).some((id) => pendingIds.has(id));
784  if (!shouldRollback) {
785    clearManualApplyTransaction(cwd, transaction.id);
786    return { id: transaction.id, reason, rolledBackFiles: [], rollbackFailures: [], skipped: 'entries_not_pending' };
787  }
788 
789  const rolledBackFiles = [];
790  const rollbackFailures = [];
791  for (const item of transaction.files || []) {
792    const relativeFile = normalizeProjectFile(item.file, cwd);
793    if (!relativeFile) continue;
794    const absolute = path.resolve(cwd, relativeFile);
795    try {
796      if (item.exists) {
797        fs.mkdirSync(path.dirname(absolute), { recursive: true });
798        fs.writeFileSync(absolute, item.content || '', 'utf-8');
799      } else if (fs.existsSync(absolute)) {
800        fs.rmSync(absolute);
801      }
802      rolledBackFiles.push(relativeFile);
803    } catch (err) {
804      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
805    }
806  }
807  clearManualApplyTransaction(cwd, transaction.id);
808  recordManualEditActivity?.('manual_edit_transaction_rolled_back', {
809    id: transaction.id,
810    pageUrl: transaction.pageUrl || null,
811    reason,
812    entryIds: transaction.entryIds || [],
813    rolledBackFiles: rolledBackFiles.map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean),
814    rollbackFailures: summarizeManualDiagnostics(rollbackFailures, cwd),
815  });
816  return { id: transaction.id, reason, rolledBackFiles, rollbackFailures };
817}
818 
819export function collectManualApplyFiles(batch, extraFiles = [], cwd = process.cwd()) {
820  const files = [];
821  for (const entry of batch?.entries || []) {
822    for (const op of entry.ops || []) files.push(op.sourceHint?.file);
823  }
824  for (const candidate of batch?.candidates || []) {
825    files.push(candidate.sourceHint?.relativeFile, candidate.sourceHint?.file);
826    for (const item of candidate.textMatches || []) files.push(item.file);
827    for (const item of candidate.objectKeyMatches || []) files.push(item.file);
828    for (const item of candidate.locatorMatches || []) files.push(item.file);
829    for (const item of candidate.contextTextMatches || []) files.push(item.file);
830  }
831  files.push(...(extraFiles || []));
832  return [...new Set(files)]
833    .map((file) => normalizeProjectFile(file, cwd))
834    .filter(Boolean);
835}
836 
837function normalizeProjectFile(file, cwd = process.cwd()) {
838  if (!file || typeof file !== 'string') return null;
839  const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
840  const relative = path.relative(cwd, absolute);
841  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
842  return relative;
843}
844 
845export function rollbackApplySnapshot(
846  batch,
847  rollbackSnapshot,
848  extraFiles = [],
849  _reason = 'manual_edit_apply_snapshot_rollback',
850  cwd = process.cwd(),
851) {
852  const scope = collectManualApplyFiles(batch, extraFiles, cwd);
853  const rolledBackFiles = [];
854  const rollbackFailures = [];
855  for (const relativeFile of scope) {
856    const before = rollbackSnapshot?.get(relativeFile);
857    if (!before) continue;
858    const absolute = path.resolve(cwd, relativeFile);
859    try {
860      if (before.exists) {
861        fs.mkdirSync(path.dirname(absolute), { recursive: true });
862        fs.writeFileSync(absolute, before.content, 'utf-8');
863      } else if (fs.existsSync(absolute)) {
864        fs.rmSync(absolute);
865      }
866      rolledBackFiles.push(relativeFile);
867    } catch (err) {
868      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
869    }
870  }
871  return { rolledBackFiles, rollbackFailures };
872}
873 
874function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
875  const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
876  return `live-poll.mjs --reply ${id} done --data '<json>'`;
877}
878 
879export function buildManualApplyAgentAction(eventOrId = 'EVENT_ID') {
880  return {
881    kind: 'manual_edit_apply',
882    required: 'apply_source_edits_then_reply',
883    replyCommand: manualApplyReplyCommand(eventOrId),
884    warning: 'Polling only leases this work item; it does not commit source edits.',
885  };
886}
887 
888export function summarizeManualApplyEvent(event = {}, batch = event.batch, cwd = process.cwd()) {
889  const entries = Array.isArray(batch?.entries) ? batch.entries : [];
890  const opCount = entries.reduce((sum, entry) => sum + (Array.isArray(entry.ops) ? entry.ops.length : 0), 0);
891  return {
892    pageUrl: event.pageUrl || null,
893    chunk: event.chunk || null,
894    entryCount: entries.length,
895    opCount,
896    files: collectManualApplyFiles(batch, [], cwd),
897  };
898}
899 
900export function summarizeManualApplyFailures(failed, cwd = process.cwd()) {
901  if (!Array.isArray(failed)) return [];
902  return failed.slice(0, 20).map((item) => ({
903    id: item.id || item.entryId || null,
904    reason: item.reason || item.message || 'failed',
905    message: compactManualLogText(item.message, 300),
906    files: Array.isArray(item.files) ? item.files.slice(0, 12).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
907    checks: summarizeManualDiagnostics(item.checks, cwd),
908    failures: summarizeManualDiagnostics(item.failures, cwd),
909    candidates: summarizeManualDiagnostics(item.candidates, cwd),
910  }));
911}
912 
913export function summarizeManualDiagnostics(items, cwd = process.cwd()) {
914  if (!Array.isArray(items) || items.length === 0) return undefined;
915  return items.slice(0, 12).map((item) => ({
916    reason: item.reason || item.kind || undefined,
917    detail: compactManualLogText(item.detail, 220),
918    message: compactManualLogText(item.message, 300),
919    file: summarizeManualLogFile(item.file || item.relativeFile, cwd),
920    line: item.line || undefined,
921    ref: compactManualLogText(item.ref, 180),
922    marker: compactManualLogText(item.marker, 120),
923    files: Array.isArray(item.files) ? item.files.slice(0, 8).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
924  }));
925}
926 
927export function summarizeManualLogFile(file, cwd = process.cwd()) {
928  if (!file || typeof file !== 'string') return undefined;
929  if (!path.isAbsolute(file)) return file;
930  const relative = path.relative(cwd, file);
931  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
932}
933 
934export function compactManualLogText(value, max = 200) {
935  if (typeof value !== 'string') return undefined;
936  const normalized = value.replace(/\s+/g, ' ').trim();
937  if (normalized.length <= max) return normalized;
938  return normalized.slice(0, max) + `... [truncated ${normalized.length - max} chars]`;
939}
940