Skip to content

ShipfoxHQ/shipfox / .claude/skills/impeccable

impeccable

Flagged

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

FileKindSize
SKILL.mdskill md10.5 KB
reference/adapt.mdmarkdown10.1 KB
reference/adapt.native.mdmarkdown3.8 KB
reference/android.mdmarkdown3.2 KB
reference/animate.mdmarkdown4.7 KB
reference/audit.mdmarkdown7.7 KB
reference/audit.native.mdmarkdown8.2 KB
reference/bolder.mdmarkdown3.1 KB
reference/clarify.mdmarkdown4.5 KB
reference/colorize.mdmarkdown4.4 KB
reference/craft-floor.mdmarkdown3.7 KB
reference/craft.mdmarkdown555 B
reference/critique.mdmarkdown39.0 KB
reference/delight.mdmarkdown3.6 KB
reference/distill.mdmarkdown5.5 KB
reference/doctor.mdmarkdown4.6 KB
reference/document.mdmarkdown26.8 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.3 KB
reference/hooks.mdmarkdown11.6 KB
reference/init.mdmarkdown8.6 KB
reference/ios.mdmarkdown2.9 KB
reference/layout.mdmarkdown5.0 KB
reference/live-setup.mdmarkdown7.2 KB
reference/live.mdmarkdown34.8 KB
reference/new-work.mdmarkdown27.8 KB
reference/onboard.mdmarkdown7.6 KB
reference/operate.mdmarkdown4.0 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.6 KB
reference/polish.mdmarkdown5.1 KB
reference/quieter.mdmarkdown4.7 KB
reference/routing.mdmarkdown2.8 KB
reference/shape.mdmarkdown3.5 KB
reference/typeset.mdmarkdown5.1 KB
reference/visualize.mdmarkdown10.2 KB
scripts/command-metadata.jsonconfig7.7 KB
scripts/concept-seed.mjsscript27.0 KB
scripts/context-signals.mjsscript14.0 KB
scripts/context.mjsscript58.4 KB
scripts/critique-storage.mjsscript7.9 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript79.6 KB
scripts/detector/cli/main.mjsscript18.8 KB
scripts/detector/design-system.mjsscript34.3 KB
scripts/detector/detect-antipatterns-browser.jsscript358.1 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript14.1 KB
scripts/detector/engines/regex/detect-text.mjsscript34.5 KB
scripts/detector/engines/static-html/css-cascade.mjsscript42.7 KB
scripts/detector/engines/static-html/detect-html.mjsscript11.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript766 B
scripts/detector/node/file-system.mjsscript7.6 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript27.2 KB
scripts/detector/rules/checks.mjsscript246.3 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.6 KB
scripts/detector/shared/fonts.mjsscript852 B
scripts/detector/shared/inline-ignores.mjsscript6.0 KB
scripts/detector/shared/page.mjsscript252 B
scripts/doctor.mjsscript11.6 KB
scripts/embed-prompt.mjsscript5.8 KB
scripts/generate-image.mjsscript9.6 KB
scripts/hook-admin.mjsscript28.4 KB
scripts/hook-before-edit.mjsscript18.3 KB
scripts/hook-lib.mjsscript81.4 KB
scripts/hook.mjsscript2.6 KB
scripts/lib/artifact-schema.mjsscript3.8 KB
scripts/lib/composition-catalog.mjsscript10.0 KB
scripts/lib/concept-catalog.mjsscript17.4 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript22.2 KB
scripts/lib/impeccable-paths.mjsscript4.9 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/lib/provider.mjsscript332 B
scripts/lib/roll-selection.mjsscript16.9 KB
scripts/lib/staleness-deep.mjsscript19.6 KB
scripts/lib/staleness-notice.mjsscript6.5 KB
scripts/lib/staleness.mjsscript19.0 KB
scripts/lib/surface-briefs.mjsscript6.1 KB
scripts/lib/target-args.mjsscript1.1 KB
scripts/lib/target-slug.mjsscript1.0 KB
scripts/lib/template-extensions.mjsscript5.3 KB
scripts/live-accept.mjsscript35.5 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript489.1 KB
scripts/live-commit-manual-edits.mjsscript41.2 KB
scripts/live-complete.mjsscript4.7 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript18.1 KB
scripts/live-insert.mjsscript9.8 KB
scripts/live-manual-edit-evidence.mjsscript11.6 KB
scripts/live-poll.mjsscript15.7 KB
scripts/live-resume.mjsscript6.0 KB
scripts/live-server.mjsscript66.1 KB
scripts/live-status.mjsscript2.6 KB
scripts/live-target.mjsscript934 B
scripts/live-wrap.mjsscript38.2 KB
scripts/live.mjsscript13.1 KB
scripts/live/accept-css.mjsscript22.0 KB
scripts/live/accept-verify.mjsscript2.7 KB
scripts/live/browser-script-parts.mjsscript2.1 KB
scripts/live/completion.mjsscript1.4 KB
scripts/live/event-validation.mjsscript9.4 KB
scripts/live/frameworks/astro.mjsscript1.7 KB
scripts/live/frameworks/detect-utils.mjsscript2.1 KB
scripts/live/frameworks/index.mjsscript5.7 KB
scripts/live/frameworks/journal.mjsscript7.0 KB
scripts/live/frameworks/nextjs.mjsscript1.7 KB
scripts/live/frameworks/nuxt.mjsscript5.1 KB
scripts/live/frameworks/script-src.mjsscript699 B
scripts/live/frameworks/static-html.mjsscript656 B
scripts/live/frameworks/sveltekit.mjsscript1.8 KB
scripts/live/frameworks/tag-strategy.mjsscript10.6 KB
scripts/live/frameworks/tanstack-start.mjsscript1.6 KB
scripts/live/frameworks/vite-generic.mjsscript1.3 KB
scripts/live/generation-preflight.mjsscript5.8 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/instructions.mjsscript12.9 KB
scripts/live/manual-apply.mjsscript34.1 KB
scripts/live/manual-edit-routes.mjsscript14.6 KB
scripts/live/manual-edits-buffer.mjsscript5.0 KB
scripts/live/poll-lanes.mjsscript759 B
scripts/live/roots.mjsscript20.4 KB
scripts/live/session-store.mjsscript22.4 KB
scripts/live/source-lock.mjsscript3.6 KB
scripts/live/source-search.mjsscript4.2 KB
scripts/live/svelte-ast.mjsscript37.7 KB
scripts/live/svelte-component.mjsscript49.6 KB
scripts/live/sveltekit-adapter.mjsscript11.1 KB
scripts/live/tanstack-adapter.mjsscript9.5 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript7.0 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript55.5 KB
scripts/pin.mjsscript6.3 KB
scripts/serve-question.mjsscript60.2 KB
scripts/surface-brief.mjsscript2.5 KB

scripts/live/manual-apply.mjs

View on GitHub
import { randomUUID } from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
import { getLiveDir } from '../lib/impeccable-paths.mjs';
import { readBuffer as readManualEditsBuffer } from './manual-edits-buffer.mjs';

const APPLY_EVENT_HARD_TIMEOUT_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_HARD_TIMEOUT_MS || 150_000);
const APPLY_EVENT_SOFT_DEADLINE_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_SOFT_DEADLINE_MS || 120_000);
const DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE = 3;
const MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE = 1;
const MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE = 20;
const MANUAL_APPLY_COMPACT_TEXT_LIMIT = 240;
const MANUAL_APPLY_COMPACT_NEARBY_LIMIT = 4;

export function createManualApplyController({
  pendingEvents,
  pendingApplyDeferreds,
  timedOutApplyIds,
  enqueueEvent,
  acknowledgePendingEvent,
  flushPendingPolls,
  recordManualEditActivity,
  cwd = () => process.cwd(),
} = {}) {
  const projectCwd = () => typeof cwd === 'function' ? cwd() : cwd || process.cwd();

  function tombstoneTimedOutApplyId(eventId, details = {}) {
    if (!eventId) return;
    timedOutApplyIds.set(eventId, details);
    if (timedOutApplyIds.size <= 200) return;
    const oldest = timedOutApplyIds.keys().next().value;
    timedOutApplyIds.delete(oldest);
  }

  function pushApplyEventAndWait(batch, pageUrl, chunk = null, repair = null) {
    const cwdValue = projectCwd();
    const eventId = randomUUID().replace(/-/g, '').slice(0, 8);
    const evidencePath = writeManualApplyEvidence(eventId, batch, cwdValue);
    const event = {
      type: 'manual_edit_apply',
      id: eventId,
      pageUrl,
      batch: compactManualApplyBatch(batch, cwdValue),
      evidencePath,
      agentAction: buildManualApplyAgentAction(eventId),
      schemaVersion: 1,
      deadlineMs: APPLY_EVENT_SOFT_DEADLINE_MS,
    };
    if (chunk) event.chunk = chunk;
    if (repair) event.repair = repair;
    const rollbackSnapshot = snapshotApplyEventFiles(batch, cwdValue);
    recordManualEditActivity('manual_edit_apply_dispatched', {
      id: eventId,
      pageUrl,
      chunk,
      repair,
      entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
      opCount: countManualApplyOps(batch),
      fileCount: collectManualApplyFiles(batch, [], cwdValue).length,
    });
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        pendingApplyDeferreds.delete(eventId);
        tombstoneTimedOutApplyId(eventId, { batch, rollbackSnapshot, cwd: cwdValue });
        acknowledgePendingEvent(eventId);
        removeManualApplyEvidence(evidencePath, cwdValue);
        recordManualEditActivity('manual_edit_apply_timeout', {
          id: eventId,
          pageUrl,
          chunk,
          entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
          opCount: countManualApplyOps(batch),
        });
        reject(new Error('chat_agent_timeout'));
      }, APPLY_EVENT_HARD_TIMEOUT_MS);
      pendingApplyDeferreds.set(eventId, { resolve, reject, timer, event, batch, pageUrl, rollbackSnapshot, cwd: cwdValue });
      enqueueEvent(event);
    });
  }

  async function pushBatchInChunksAndWait(batch, pageUrl, context = {}) {
    const repair = context?.repair || batch?.repair || null;
    if (repair) return pushApplyEventAndWait(batch, pageUrl, null, repair);
    const chunks = splitManualApplyBatch(batch, manualEditApplyChunkSize());
    if (chunks.length <= 1) return pushApplyEventAndWait(batch, pageUrl);

    const expectedOpsByEntry = new Map();
    for (const entry of batch?.entries || []) {
      expectedOpsByEntry.set(entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0);
    }

    const appliedOpsByEntry = new Map();
    const failedByEntry = new Map();
    const files = new Set();
    const notes = [];
    let aborted = false;

    for (const chunk of chunks) {
      if (aborted) {
        markChunkEntriesFailed(failedByEntry, chunk, 'manual_edit_chunk_aborted');
        continue;
      }

      let result;
      try {
        result = normalizeApplyChunkResult(await pushApplyEventAndWait(chunk.batch, pageUrl, chunk.meta));
      } catch (err) {
        markChunkEntriesFailed(failedByEntry, chunk, err.message || 'chat_agent_error');
        aborted = true;
        continue;
      }

      for (const file of result.files) files.add(file);
      notes.push(...result.notes);

      const chunkFailedIds = new Set();
      for (const item of result.failed) {
        const entryId = item.entryId || item.id;
        if (!entryId) continue;
        chunkFailedIds.add(entryId);
        if (!failedByEntry.has(entryId)) {
          failedByEntry.set(entryId, {
            entryId,
            reason: item.reason || item.message || 'failed',
            candidates: Array.isArray(item.candidates) ? item.candidates : [],
          });
        }
      }

      if (result.status === 'error') {
        markChunkEntriesFailed(failedByEntry, chunk, result.message || firstFailureReason(result) || 'chat_agent_error');
        aborted = true;
        continue;
      }

      const reportedAppliedIds = new Set(result.appliedEntryIds);
      for (const entryId of reportedAppliedIds) {
        if (!chunk.entryIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
        appliedOpsByEntry.set(entryId, (appliedOpsByEntry.get(entryId) || 0) + (chunk.opCountsByEntry.get(entryId) || 0));
      }

      for (const entryId of chunk.entryIds) {
        if (reportedAppliedIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
        if (!failedByEntry.has(entryId)) {
          failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
        }
      }
    }

    const appliedEntryIds = [];
    for (const [entryId, expectedOps] of expectedOpsByEntry.entries()) {
      if (failedByEntry.has(entryId)) continue;
      if ((appliedOpsByEntry.get(entryId) || 0) === expectedOps && expectedOps > 0) {
        appliedEntryIds.push(entryId);
      } else if (!failedByEntry.has(entryId)) {
        failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
      }
    }

    const failed = [...failedByEntry.values()];
    return {
      status: failed.length === 0 ? 'done' : appliedEntryIds.length > 0 ? 'partial' : 'error',
      appliedEntryIds,
      failed,
      files: [...files],
      notes,
    };
  }

  function getDeferred(eventId) {
    return pendingApplyDeferreds.get(eventId) || null;
  }

  function hasTimedOutId(eventId) {
    return timedOutApplyIds.has(eventId);
  }

  function resolveDeferred(eventId, body) {
    const deferred = pendingApplyDeferreds.get(eventId);
    if (!deferred) return false;
    pendingApplyDeferreds.delete(eventId);
    clearTimeout(deferred.timer);
    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
    deferred.resolve(body);
    return true;
  }

  function rejectDeferred(eventId, reason) {
    const deferred = pendingApplyDeferreds.get(eventId);
    if (!deferred) return false;
    pendingApplyDeferreds.delete(eventId);
    clearTimeout(deferred.timer);
    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
    deferred.reject(new Error(reason || 'chat_agent_error'));
    return true;
  }

  function referencedManualApplyEvidencePaths(cwdValue = projectCwd()) {
    const referenced = new Set();
    const add = (event) => {
      const fullPath = normalizeManualApplyEvidencePath(event?.evidencePath, cwdValue);
      if (fullPath) referenced.add(fullPath);
    };
    for (const entry of pendingEvents) add(entry.event);
    for (const deferred of pendingApplyDeferreds.values()) add(deferred.event);
    return referenced;
  }

  function pruneStaleEvidence(cwdValue = projectCwd()) {
    const dir = manualApplyEvidenceDir(cwdValue);
    if (!fs.existsSync(dir)) return [];
    const referenced = referencedManualApplyEvidencePaths(cwdValue);
    const removed = [];
    for (const name of fs.readdirSync(dir)) {
      if (!name.endsWith('.json')) continue;
      const fullPath = path.join(dir, name);
      if (referenced.has(fullPath)) continue;
      try {
        fs.unlinkSync(fullPath);
        removed.push(fullPath);
      } catch {
        // Stale evidence cleanup is best-effort; Apply verification never relies
        // on deleting these files.
      }
    }
    return removed;
  }

  function rollbackTimedOutReply(msg) {
    const details = timedOutApplyIds.get(msg.id);
    if (!details) return { rolledBackFiles: [], rollbackFailures: [] };
    timedOutApplyIds.delete(msg.id);
    return rollbackApplySnapshot(
      details.batch,
      details.rollbackSnapshot,
      msg.data?.files || [],
      'stale_manual_edit_apply_reply',
      details.cwd || projectCwd(),
    );
  }

  function cancelPendingEvents(pageUrl, reason = 'manual_edit_discarded') {
    const canceledById = new Map();
    const shouldCancel = (event) => event?.type === 'manual_edit_apply' && (!pageUrl || event.pageUrl === pageUrl);

    for (let i = pendingEvents.length - 1; i >= 0; i -= 1) {
      const event = pendingEvents[i]?.event;
      if (!shouldCancel(event)) continue;
      pendingEvents.splice(i, 1);
      removeManualApplyEvidence(event.evidencePath, projectCwd());
      canceledById.set(event.id, {
        id: event.id,
        pageUrl: event.pageUrl,
        entryCount: event.batch?.entries?.length || 0,
      });
    }

    for (const [eventId, deferred] of [...pendingApplyDeferreds.entries()]) {
      if (!shouldCancel(deferred.event)) continue;
      pendingApplyDeferreds.delete(eventId);
      clearTimeout(deferred.timer);
      const cwdValue = deferred.cwd || projectCwd();
      const rollback = rollbackApplySnapshot(deferred.batch, deferred.rollbackSnapshot, [], reason, cwdValue);
      tombstoneTimedOutApplyId(eventId, {
        batch: deferred.batch,
        rollbackSnapshot: deferred.rollbackSnapshot,
        reason,
        cwd: cwdValue,
      });
      removeManualApplyEvidence(deferred.event?.evidencePath, cwdValue);
      canceledById.set(eventId, {
        id: eventId,
        pageUrl: deferred.pageUrl,
        entryCount: deferred.batch?.entries?.length || 0,
        rolledBackFiles: rollback.rolledBackFiles,
        rollbackFailures: rollback.rollbackFailures,
      });
      deferred.reject(new Error(reason));
    }

    if (canceledById.size > 0) flushPendingPolls();
    return [...canceledById.values()];
  }

  return {
    buildAgentAction: buildManualApplyAgentAction,
    cancelPendingEvents,
    clearTransaction: (transactionId = null) => clearManualApplyTransaction(projectCwd(), transactionId),
    countOps: countManualApplyOps,
    getDeferred,
    hasTimedOutId,
    pruneStaleEvidence,
    pushBatchInChunksAndWait,
    readTransaction: () => readManualApplyTransaction(projectCwd()),
    rejectDeferred,
    resolveDeferred,
    rollbackTimedOutReply,
    rollbackTransaction: (opts = {}) => rollbackManualApplyTransaction({
      cwd: projectCwd(),
      recordManualEditActivity,
      ...opts,
    }),
    summarizeEvent: (event = {}, batch = event.batch) => summarizeManualApplyEvent(event, batch, projectCwd()),
    validateResultMessage: validateManualApplyResultMessage,
    writeTransaction: (opts = {}) => writeManualApplyTransaction({ cwd: projectCwd(), ...opts }),
  };
}

export function manualEditApplyChunkSize(env = process.env) {
  const raw = Number(env.IMPECCABLE_LIVE_MANUAL_EDIT_CHUNK_SIZE);
  if (!Number.isFinite(raw)) return DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE;
  const size = Math.trunc(raw);
  return Math.max(MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE, Math.min(MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE, size));
}

export function countManualApplyOps(entriesOrBatch) {
  const entries = Array.isArray(entriesOrBatch)
    ? entriesOrBatch
    : Array.isArray(entriesOrBatch?.entries) ? entriesOrBatch.entries : [];
  let count = 0;
  for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
  return count;
}

export function writeManualApplyEvidence(eventId, batch, cwd = process.cwd()) {
  const dir = manualApplyEvidenceDir(cwd);
  fs.mkdirSync(dir, { recursive: true });
  const evidencePath = path.join(dir, `${eventId}.json`);
  fs.writeFileSync(evidencePath, JSON.stringify(batch, null, 2) + '\n', 'utf-8');
  return evidencePath;
}

export function manualApplyEvidenceDir(cwd = process.cwd()) {
  return path.join(getLiveDir(cwd), 'manual-edit-evidence');
}

export function normalizeManualApplyEvidencePath(evidencePath, cwd = process.cwd()) {
  if (!evidencePath || typeof evidencePath !== 'string') return null;
  const fullPath = path.isAbsolute(evidencePath) ? evidencePath : path.resolve(cwd, evidencePath);
  const evidenceDir = manualApplyEvidenceDir(cwd);
  const relative = path.relative(evidenceDir, fullPath);
  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
  if (path.extname(relative) !== '.json') return null;
  return fullPath;
}

export function removeManualApplyEvidence(evidencePath, cwd = process.cwd()) {
  const fullPath = normalizeManualApplyEvidencePath(evidencePath, cwd);
  if (!fullPath) return false;
  try {
    fs.unlinkSync(fullPath);
    return true;
  } catch {
    return false;
  }
}

export function compactManualApplyBatch(batch = {}, cwd = process.cwd()) {
  const entries = (batch.entries || []).map(compactManualApplyEntry);
  const candidates = compactManualApplyCandidates(batch.candidates || [], cwd);
  return {
    version: batch.version,
    pageUrl: batch.pageUrl || null,
    count: batch.count,
    entries,
    ops: entries.flatMap((entry) => entry.ops.map((op) => ({ ...op, entryId: entry.id }))),
    candidates: candidates.length > 0 ? candidates : undefined,
    context: batch.context ? {
      bufferPath: batch.context.bufferPath,
      totalEntries: batch.context.totalEntries,
      totalOps: batch.context.totalOps,
      chunkIndex: batch.context.chunkIndex,
      chunkTotal: batch.context.chunkTotal,
      totalApplyOps: batch.context.totalApplyOps,
    } : undefined,
  };
}

export function compactManualApplyCandidates(candidates, cwd = process.cwd()) {
  return (Array.isArray(candidates) ? candidates : [])
    .slice(0, 24)
    .map((candidate) => ({
      entryId: candidate.entryId,
      ref: candidate.ref,
      sourceHint: compactManualApplySourceMatch(candidate.sourceHint, cwd),
      textMatches: compactManualApplySourceMatches(candidate.textMatches, 8, cwd),
      objectKeyMatches: compactManualApplySourceMatches(candidate.objectKeyMatches, 8, cwd),
      contextTextMatches: compactManualApplySourceMatches(candidate.contextTextMatches, 8, cwd),
      locatorMatches: compactManualApplySourceMatches(candidate.locatorMatches, 6, cwd),
    }));
}

function compactManualApplySourceMatches(matches, limit, cwd) {
  return (Array.isArray(matches) ? matches : [])
    .slice(0, limit)
    .map((match) => compactManualApplySourceMatch(match, cwd))
    .filter(Boolean);
}

function compactManualApplySourceMatch(match, cwd) {
  if (!match || typeof match !== 'object') return null;
  const file = match.relativeFile || match.file;
  if (!file && !match.line) return null;
  return {
    file: summarizeManualLogFile(file, cwd),
    line: match.line || null,
    column: match.column || null,
    reason: match.reason || match.kind || undefined,
    status: match.status || undefined,
  };
}

function compactManualApplyEntry(entry = {}) {
  return {
    id: entry.id,
    pageUrl: entry.pageUrl,
    stagedAt: entry.stagedAt || null,
    element: compactManualApplyContext(entry.element),
    ops: (entry.ops || []).map(compactManualApplyOp),
  };
}

function compactManualApplyOp(op = {}) {
  return {
    entryId: op.entryId,
    ref: op.ref,
    contextRef: op.contextRef,
    tag: op.tag,
    elementId: op.elementId,
    classes: Array.isArray(op.classes) ? op.classes : [],
    originalText: op.originalText,
    newText: op.newText,
    deleted: op.deleted === true || undefined,
    sourceHint: op.sourceHint || null,
    leaf: compactManualApplyContext(op.leaf),
    nearbyEditableTexts: compactNearbyManualEditTexts(op.nearbyEditableTexts),
    container: compactManualApplyContext(op.container),
    contextHints: Array.isArray(op.contextHints) ? op.contextHints.slice(0, 8) : undefined,
  };
}

function compactManualApplyContext(value) {
  if (!value || typeof value !== 'object') return null;
  return {
    ref: value.ref,
    tagName: value.tagName || value.tag || null,
    id: value.id || null,
    classes: Array.isArray(value.classes) ? value.classes : [],
    textContent: truncateManualApplyText(value.textContent, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
  };
}

function compactNearbyManualEditTexts(items) {
  return (Array.isArray(items) ? items : [])
    .slice(0, MANUAL_APPLY_COMPACT_NEARBY_LIMIT)
    .map((item) => typeof item === 'string' ? { text: truncateManualApplyText(item, MANUAL_APPLY_COMPACT_TEXT_LIMIT) } : {
      ref: item?.ref,
      tag: item?.tag,
      classes: Array.isArray(item?.classes) ? item.classes : [],
      text: truncateManualApplyText(item?.text, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
    });
}

function truncateManualApplyText(value, max) {
  if (typeof value !== 'string') return value || null;
  return value.length > max ? value.slice(0, max) : value;
}

function normalizeApplyChunkResult(result) {
  const status = result?.status === 'partial' ? 'partial' : result?.status === 'error' ? 'error' : 'done';
  return {
    status,
    message: typeof result?.message === 'string' ? result.message : null,
    appliedEntryIds: Array.isArray(result?.appliedEntryIds) ? result.appliedEntryIds.filter((id) => typeof id === 'string') : [],
    failed: Array.isArray(result?.failed) ? result.failed.filter(Boolean) : [],
    files: Array.isArray(result?.files) ? result.files.filter((file) => typeof file === 'string') : [],
    notes: Array.isArray(result?.notes) ? result.notes.filter((note) => typeof note === 'string') : [],
  };
}

function manualApplyResultShapeHint(eventId = 'EVENT_ID') {
  return `Use live-poll.mjs --reply ${eventId} done --data '{"status":"done","appliedEntryIds":["ENTRY_ID"],"failed":[],"files":["src/page.html"],"notes":[]}'`;
}

function invalidManualApplyResult(reason, eventId, extra = {}) {
  return {
    ok: false,
    body: {
      error: 'invalid_manual_apply_result',
      reason,
      hint: manualApplyResultShapeHint(eventId),
      ...extra,
    },
  };
}

export function validateManualApplyResultMessage(msg, deferred) {
  let data = msg?.data;
  const eventId = msg?.id || deferred?.event?.id || 'EVENT_ID';
  if (!data || typeof data !== 'object' || Array.isArray(data)) {
    return invalidManualApplyResult('missing_result_data', eventId);
  }
  if ('entries' in data || 'ops' in data) {
    return invalidManualApplyResult('summary_result_not_allowed', eventId);
  }
  if (!['done', 'partial', 'error'].includes(data.status)) {
    return invalidManualApplyResult('invalid_status', eventId, { status: data.status ?? null });
  }

  for (const key of ['appliedEntryIds', 'failed', 'files', 'notes']) {
    if (!Array.isArray(data[key])) {
      return invalidManualApplyResult(`${key}_must_be_array`, eventId);
    }
  }

  for (const [index, value] of data.appliedEntryIds.entries()) {
    if (typeof value !== 'string' || !value) {
      return invalidManualApplyResult('appliedEntryIds_must_contain_strings', eventId, { index });
    }
  }
  for (const [index, value] of data.files.entries()) {
    if (typeof value !== 'string' || !value) {
      return invalidManualApplyResult('files_must_contain_strings', eventId, { index });
    }
  }
  for (const [index, value] of data.notes.entries()) {
    if (typeof value !== 'string') {
      return invalidManualApplyResult('notes_must_contain_strings', eventId, { index });
    }
  }
  for (const [index, item] of data.failed.entries()) {
    if (!item || typeof item !== 'object' || Array.isArray(item)) {
      return invalidManualApplyResult('failed_must_contain_objects', eventId, { index });
    }
    if (typeof item.entryId !== 'string' || !item.entryId) {
      return invalidManualApplyResult('failed_entryId_required', eventId, { index });
    }
    if (typeof item.reason !== 'string' || !item.reason) {
      return invalidManualApplyResult('failed_reason_required', eventId, { index });
    }
  }

  const eventEntryIds = new Set((deferred?.batch?.entries || []).map((entry) => entry.id).filter(Boolean));
  for (const entryId of data.appliedEntryIds) {
    if (eventEntryIds.size > 0 && !eventEntryIds.has(entryId)) {
      return invalidManualApplyResult('applied_entry_id_not_in_event', eventId, { entryId });
    }
  }
  for (const item of data.failed) {
    if (eventEntryIds.size > 0 && !eventEntryIds.has(item.entryId)) {
      return invalidManualApplyResult('failed_entry_id_not_in_event', eventId, { entryId: item.entryId });
    }
  }

  if (data.status === 'done') {
    if (data.failed.length > 0) {
      return invalidManualApplyResult('done_result_has_failed_entries', eventId);
    }
    if (countManualApplyOps(deferred?.batch) > 0 && data.appliedEntryIds.length === 0) {
      return invalidManualApplyResult('done_result_missing_applied_entry_ids', eventId);
    }
  }
  if (data.status === 'partial' && data.appliedEntryIds.length === 0 && data.failed.length === 0) {
    return invalidManualApplyResult('partial_result_has_no_entries', eventId);
  }
  if (data.status === 'error' && data.appliedEntryIds.length > 0) {
    return invalidManualApplyResult('error_result_has_applied_entries', eventId);
  }

  return {
    ok: true,
    result: {
      status: data.status,
      message: typeof data.message === 'string' ? data.message : undefined,
      appliedEntryIds: data.appliedEntryIds,
      failed: data.failed,
      files: data.files,
      notes: data.notes,
    },
  };
}

function firstFailureReason(result) {
  const first = Array.isArray(result?.failed) ? result.failed.find(Boolean) : null;
  return first?.reason || first?.message || null;
}

function markChunkEntriesFailed(failedByEntry, chunk, reason) {
  for (const entryId of chunk.entryIds) {
    if (failedByEntry.has(entryId)) continue;
    failedByEntry.set(entryId, { entryId, reason, candidates: [] });
  }
}

export function splitManualApplyBatch(batch, maxOps) {
  const totalOpCount = countManualApplyOps(batch);
  if (totalOpCount <= maxOps) {
    return [{
      batch,
      meta: null,
      entryIds: new Set((batch?.entries || []).map((entry) => entry.id).filter(Boolean)),
      opCountsByEntry: new Map((batch?.entries || []).map((entry) => [entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0])),
    }];
  }

  const rawChunks = [];
  let current = createManualApplyChunkBuilder();
  for (const entry of batch?.entries || []) {
    const ops = entry.ops || [];
    if (ops.length <= maxOps) {
      if (current.opCount > 0 && current.opCount + ops.length > maxOps) {
        rawChunks.push(current);
        current = createManualApplyChunkBuilder();
      }
      for (const op of ops) addOpToManualApplyChunk(current, entry, op);
      continue;
    }
    if (current.opCount > 0) {
      rawChunks.push(current);
      current = createManualApplyChunkBuilder();
    }
    for (const op of ops) {
      if (current.opCount >= maxOps) {
        rawChunks.push(current);
        current = createManualApplyChunkBuilder();
      }
      addOpToManualApplyChunk(current, entry, op);
    }
  }
  if (current.opCount > 0) rawChunks.push(current);

  return rawChunks.map((chunk, index) => ({
    batch: {
      ...batch,
      count: chunk.opCount,
      entries: chunk.entries,
      ops: chunk.ops,
      candidates: filterManualApplyChunkCandidates(batch, chunk.refsByEntry),
      context: {
        ...(batch?.context || {}),
        totalEntries: chunk.entries.length,
        totalOps: chunk.opCount,
        chunkIndex: index + 1,
        chunkTotal: rawChunks.length,
        totalApplyOps: totalOpCount,
      },
    },
    meta: {
      index: index + 1,
      total: rawChunks.length,
      opCount: chunk.opCount,
      totalOpCount,
    },
    entryIds: new Set(chunk.entries.map((entry) => entry.id).filter(Boolean)),
    opCountsByEntry: chunk.opCountsByEntry,
  }));
}

function createManualApplyChunkBuilder() {
  return {
    entries: [],
    entryById: new Map(),
    entryIds: new Set(),
    ops: [],
    refsByEntry: new Map(),
    opCountsByEntry: new Map(),
    opCount: 0,
  };
}

function addOpToManualApplyChunk(chunk, entry, op) {
  let chunkEntry = chunk.entryById.get(entry.id);
  if (!chunkEntry) {
    chunkEntry = { ...entry, ops: [] };
    chunk.entryById.set(entry.id, chunkEntry);
    chunk.entryIds.add(entry.id);
    chunk.entries.push(chunkEntry);
  }
  chunkEntry.ops.push(op);
  chunk.ops.push({ ...op, entryId: op.entryId || entry.id });
  if (!chunk.refsByEntry.has(entry.id)) chunk.refsByEntry.set(entry.id, new Set());
  if (op.ref) chunk.refsByEntry.get(entry.id).add(op.ref);
  chunk.opCountsByEntry.set(entry.id, (chunk.opCountsByEntry.get(entry.id) || 0) + 1);
  chunk.opCount += 1;
}

function filterManualApplyChunkCandidates(batch, refsByEntry) {
  return (batch?.candidates || []).filter((candidate) => {
    const refs = refsByEntry.get(candidate.entryId);
    if (!refs) return false;
    if (!candidate.ref) return true;
    return refs.has(candidate.ref);
  });
}

export function snapshotApplyEventFiles(batch, cwd = process.cwd()) {
  const snapshot = new Map();
  for (const relativeFile of collectManualApplyFiles(batch, [], cwd)) {
    const absolute = path.resolve(cwd, relativeFile);
    try {
      snapshot.set(relativeFile, {
        exists: fs.existsSync(absolute),
        content: fs.existsSync(absolute) ? fs.readFileSync(absolute, 'utf-8') : '',
      });
    } catch {
      // If a file cannot be read before dispatch, do not attempt late rollback.
    }
  }
  return snapshot;
}

export function manualApplyTransactionPath(cwd = process.cwd()) {
  return path.join(getLiveDir(cwd), 'manual-edit-apply-transaction.json');
}

export function readManualApplyTransaction(cwd = process.cwd()) {
  const file = manualApplyTransactionPath(cwd);
  if (!fs.existsSync(file)) return null;
  try {
    return JSON.parse(fs.readFileSync(file, 'utf-8'));
  } catch {
    return null;
  }
}

export function writeManualApplyTransaction({ cwd = process.cwd(), pageUrl = null, batch }) {
  const file = manualApplyTransactionPath(cwd);
  const files = collectManualApplyFiles(batch, [], cwd);
  const transaction = {
    version: 1,
    id: randomUUID().replace(/-/g, '').slice(0, 8),
    createdAt: new Date().toISOString(),
    pageUrl,
    entryIds: (batch?.entries || []).map((entry) => entry.id).filter(Boolean),
    files: files.map((relativeFile) => {
      const absolute = path.resolve(cwd, relativeFile);
      const exists = fs.existsSync(absolute);
      return {
        file: relativeFile,
        exists,
        content: exists ? fs.readFileSync(absolute, 'utf-8') : '',
      };
    }),
  };
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(`${file}.tmp`, JSON.stringify(transaction, null, 2) + '\n', 'utf-8');
  fs.renameSync(`${file}.tmp`, file);
  return transaction;
}

export function clearManualApplyTransaction(cwd = process.cwd(), transactionId = null) {
  const file = manualApplyTransactionPath(cwd);
  if (!fs.existsSync(file)) return false;
  if (transactionId) {
    const existing = readManualApplyTransaction(cwd);
    if (existing?.id && existing.id !== transactionId) return false;
  }
  try {
    fs.unlinkSync(file);
    return true;
  } catch {
    return false;
  }
}

export function rollbackManualApplyTransaction({
  cwd = process.cwd(),
  pageUrl = null,
  reason = 'manual_edit_transaction_rollback',
  recordManualEditActivity = null,
} = {}) {
  const transaction = readManualApplyTransaction(cwd);
  if (!transaction) return null;
  if (pageUrl && transaction.pageUrl && transaction.pageUrl !== pageUrl) return null;

  let pendingIds = new Set();
  try {
    const buffer = readManualEditsBuffer(cwd);
    pendingIds = new Set((buffer.entries || []).map((entry) => entry.id).filter(Boolean));
  } catch {
    pendingIds = new Set(transaction.entryIds || []);
  }
  const shouldRollback = (transaction.entryIds || []).some((id) => pendingIds.has(id));
  if (!shouldRollback) {
    clearManualApplyTransaction(cwd, transaction.id);
    return { id: transaction.id, reason, rolledBackFiles: [], rollbackFailures: [], skipped: 'entries_not_pending' };
  }

  const rolledBackFiles = [];
  const rollbackFailures = [];
  for (const item of transaction.files || []) {
    const relativeFile = normalizeProjectFile(item.file, cwd);
    if (!relativeFile) continue;
    const absolute = path.resolve(cwd, relativeFile);
    try {
      if (item.exists) {
        fs.mkdirSync(path.dirname(absolute), { recursive: true });
        fs.writeFileSync(absolute, item.content || '', 'utf-8');
      } else if (fs.existsSync(absolute)) {
        fs.rmSync(absolute);
      }
      rolledBackFiles.push(relativeFile);
    } catch (err) {
      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
    }
  }
  clearManualApplyTransaction(cwd, transaction.id);
  recordManualEditActivity?.('manual_edit_transaction_rolled_back', {
    id: transaction.id,
    pageUrl: transaction.pageUrl || null,
    reason,
    entryIds: transaction.entryIds || [],
    rolledBackFiles: rolledBackFiles.map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean),
    rollbackFailures: summarizeManualDiagnostics(rollbackFailures, cwd),
  });
  return { id: transaction.id, reason, rolledBackFiles, rollbackFailures };
}

export function collectManualApplyFiles(batch, extraFiles = [], cwd = process.cwd()) {
  const files = [];
  for (const entry of batch?.entries || []) {
    for (const op of entry.ops || []) files.push(op.sourceHint?.file);
  }
  for (const candidate of batch?.candidates || []) {
    files.push(candidate.sourceHint?.relativeFile, candidate.sourceHint?.file);
    for (const item of candidate.textMatches || []) files.push(item.file);
    for (const item of candidate.objectKeyMatches || []) files.push(item.file);
    for (const item of candidate.locatorMatches || []) files.push(item.file);
    for (const item of candidate.contextTextMatches || []) files.push(item.file);
  }
  files.push(...(extraFiles || []));
  return [...new Set(files)]
    .map((file) => normalizeProjectFile(file, cwd))
    .filter(Boolean);
}

function normalizeProjectFile(file, cwd = process.cwd()) {
  if (!file || typeof file !== 'string') return null;
  const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
  const relative = path.relative(cwd, absolute);
  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
  return relative;
}

export function rollbackApplySnapshot(
  batch,
  rollbackSnapshot,
  extraFiles = [],
  _reason = 'manual_edit_apply_snapshot_rollback',
  cwd = process.cwd(),
) {
  const scope = collectManualApplyFiles(batch, extraFiles, cwd);
  const rolledBackFiles = [];
  const rollbackFailures = [];
  for (const relativeFile of scope) {
    const before = rollbackSnapshot?.get(relativeFile);
    if (!before) continue;
    const absolute = path.resolve(cwd, relativeFile);
    try {
      if (before.exists) {
        fs.mkdirSync(path.dirname(absolute), { recursive: true });
        fs.writeFileSync(absolute, before.content, 'utf-8');
      } else if (fs.existsSync(absolute)) {
        fs.rmSync(absolute);
      }
      rolledBackFiles.push(relativeFile);
    } catch (err) {
      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
    }
  }
  return { rolledBackFiles, rollbackFailures };
}

function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
  const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
  return `live-poll.mjs --reply ${id} done --data '<json>'`;
}

export function buildManualApplyAgentAction(eventOrId = 'EVENT_ID') {
  return {
    kind: 'manual_edit_apply',
    required: 'apply_source_edits_then_reply',
    replyCommand: manualApplyReplyCommand(eventOrId),
    warning: 'Polling only leases this work item; it does not commit source edits.',
  };
}

export function summarizeManualApplyEvent(event = {}, batch = event.batch, cwd = process.cwd()) {
  const entries = Array.isArray(batch?.entries) ? batch.entries : [];
  const opCount = entries.reduce((sum, entry) => sum + (Array.isArray(entry.ops) ? entry.ops.length : 0), 0);
  return {
    pageUrl: event.pageUrl || null,
    chunk: event.chunk || null,
    entryCount: entries.length,
    opCount,
    files: collectManualApplyFiles(batch, [], cwd),
  };
}

export function summarizeManualApplyFailures(failed, cwd = process.cwd()) {
  if (!Array.isArray(failed)) return [];
  return failed.slice(0, 20).map((item) => ({
    id: item.id || item.entryId || null,
    reason: item.reason || item.message || 'failed',
    message: compactManualLogText(item.message, 300),
    files: Array.isArray(item.files) ? item.files.slice(0, 12).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
    checks: summarizeManualDiagnostics(item.checks, cwd),
    failures: summarizeManualDiagnostics(item.failures, cwd),
    candidates: summarizeManualDiagnostics(item.candidates, cwd),
  }));
}

export function summarizeManualDiagnostics(items, cwd = process.cwd()) {
  if (!Array.isArray(items) || items.length === 0) return undefined;
  return items.slice(0, 12).map((item) => ({
    reason: item.reason || item.kind || undefined,
    detail: compactManualLogText(item.detail, 220),
    message: compactManualLogText(item.message, 300),
    file: summarizeManualLogFile(item.file || item.relativeFile, cwd),
    line: item.line || undefined,
    ref: compactManualLogText(item.ref, 180),
    marker: compactManualLogText(item.marker, 120),
    files: Array.isArray(item.files) ? item.files.slice(0, 8).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
  }));
}

export function summarizeManualLogFile(file, cwd = process.cwd()) {
  if (!file || typeof file !== 'string') return undefined;
  if (!path.isAbsolute(file)) return file;
  const relative = path.relative(cwd, file);
  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
}

export function compactManualLogText(value, max = 200) {
  if (typeof value !== 'string') return undefined;
  const normalized = value.replace(/\s+/g, ' ').trim();
  if (normalized.length <= max) return normalized;
  return normalized.slice(0, max) + `... [truncated ${normalized.length - max} chars]`;
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall