From e8e3665142ed96e8afe6a1b3f7302971bc7386b6 Mon Sep 17 00:00:00 2001
From: Abdul Wahab <32850166+abdulwahabone@users.noreply.github.com>
Date: Fri, 29 May 2026 11:02:12 +0900
Subject: [PATCH] Live mode: staged AI copy edits (#158)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* feat(live): manual text-edit panel + Astro inject + stale-lockfile reap
Adds a manual text-edit popover under the live-mode bar so users can
retype copy directly without going through generate. The footer's
"Apply edits" button fires a manual_edits event; the server writes
the changes back to source via the new live-edit.mjs deterministic
file mutator. Mirrors the wrap+accept flow but skips variant generation.
New scripts:
- skill/scripts/live-edit.mjs: writes manual_edits back to source
- skill/scripts/live-text-rows.js: browser walker that surfaces every
pure-text descendant of the picked element as an editable row
Touched scripts:
- skill/scripts/live-browser.js: text panel UI, CONFIGURING state hook
- skill/scripts/live-poll.mjs: manual_edits routing
- skill/scripts/live-server.mjs: manual_edits endpoint + handler
- skill/scripts/live-wrap.mjs: small adjustments to support the flow
Docs + tests:
- skill/reference/live.md: manual-edit section
- tests/live-edit.test.mjs, tests/live-text-rows.test.mjs
Also bundles two live-mode reliability fixes that surfaced during
manual testing of the feature:
1. live-inject now emits is:inline when the inject target is a .astro
file. Astro otherwise processes the \n' +
+ '\n' +
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
);
}
-function insertTag(content, config, port) {
- const block = buildTagBlock(config.commentSyntax, port);
+function insertTag(content, config, port, filePath) {
+ const block = buildTagBlock(config.commentSyntax, port, filePath);
// insertBefore: match the LAST occurrence. Anchors like `` naturally
// belong at the end, and the same literal can appear earlier in code blocks
// within rendered documentation pages.
@@ -299,12 +303,21 @@ function insertTag(content, config, port) {
*/
function removeTag(content, _syntax) {
const patterns = [
- /([ \t]*)[\s\S]*?[ \t]*\n/,
- /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}[ \t]*\n/,
+ /([ \t]*)[\s\S]*?([ \t]*(?:\n|$)?)/,
+ /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\n|$)?)/,
];
for (const pat of patterns) {
- const next = content.replace(pat, '$1');
- if (next !== content) return next;
+ let changed = false;
+ let next = content;
+ do {
+ content = next;
+ next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
+ if (trailing.includes('\n')) return leadingIndent;
+ return leadingIndent || trailing || '';
+ });
+ if (next !== content) changed = true;
+ } while (next !== content);
+ if (changed) return next;
}
return content;
}
diff --git a/.agents/skills/impeccable/scripts/live-manual-edit-evidence.mjs b/.agents/skills/impeccable/scripts/live-manual-edit-evidence.mjs
new file mode 100644
index 000000000..860278b73
--- /dev/null
+++ b/.agents/skills/impeccable/scripts/live-manual-edit-evidence.mjs
@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Collect evidence for pending live copy edits.
+ *
+ * This module intentionally does not edit source files and does not choose a
+ * winner. It gathers staged browser edits, rendered context, framework source
+ * hints, and likely source candidates so the AI copy-edit batch runner can make
+ * source changes with full repo context.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+import { readBuffer, getBufferPath } from './live-manual-edits-buffer.mjs';
+
+const EVIDENCE_VERSION = 1;
+const TEXT_EXTENSIONS = new Set(['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro', '.js', '.mjs', '.ts']);
+const SEARCH_DIRS = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', 'site', 'lib', 'data'];
+const STRONG_LITERAL_MATCH_LIMIT = 8;
+const WEAK_LITERAL_MATCH_LIMIT = 4;
+const OBJECT_KEY_MATCH_LIMIT = 8;
+const LOCATOR_MATCH_LIMIT = 4;
+const CONTEXT_MATCH_LIMIT = 8;
+const CONTEXT_MATCH_PER_HINT = 2;
+const SKIP_DIRS = new Set([
+ 'node_modules',
+ '.git',
+ '.impeccable',
+ '.astro',
+ '.next',
+ '.nuxt',
+ '.svelte-kit',
+ 'dist',
+ 'build',
+ 'out',
+ 'coverage',
+]);
+
+export function buildManualEditEvidence({ cwd = process.cwd(), pageUrl = null } = {}) {
+ const buffer = readBuffer(cwd);
+ const entries = pageUrl
+ ? buffer.entries.filter((entry) => entry.pageUrl === pageUrl)
+ : buffer.entries;
+ const opCount = countOps(entries);
+
+ if (opCount === 0) {
+ return {
+ pageUrl,
+ count: 0,
+ entries: [],
+ ops: [],
+ candidates: [],
+ };
+ }
+
+ const searchFiles = collectSearchFiles(cwd);
+ const ops = flattenOps(entries);
+ const candidates = ops.map((op) => buildCandidatesForOp(op, cwd, searchFiles));
+ return {
+ version: EVIDENCE_VERSION,
+ pageUrl: pageUrl || null,
+ count: opCount,
+ entries,
+ ops,
+ context: {
+ cwd,
+ bufferPath: path.relative(cwd, getBufferPath(cwd)),
+ totalEntries: entries.length,
+ totalOps: opCount,
+ },
+ candidates,
+ };
+}
+
+function countOps(entries) {
+ let count = 0;
+ for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
+ return count;
+}
+
+function flattenOps(entries) {
+ const out = [];
+ for (const entry of entries) {
+ const contextHintsByRef = buildContextHintsByRef(entry);
+ for (const op of entry.ops || []) {
+ out.push({
+ entryId: entry.id,
+ pageUrl: entry.pageUrl,
+ ref: op.ref,
+ contextRef: op.contextRef || null,
+ tag: op.tag,
+ elementId: op.elementId || null,
+ classes: Array.isArray(op.classes) ? op.classes : [],
+ originalText: op.originalText,
+ newText: op.newText,
+ deleted: op.deleted === true,
+ sourceHint: op.sourceHint || null,
+ leaf: op.leaf || null,
+ nearbyEditableTexts: Array.isArray(op.nearbyEditableTexts) ? op.nearbyEditableTexts : [],
+ container: op.container || null,
+ contextHints: contextHintsByRef.get(op.ref) || [],
+ });
+ }
+ }
+ return out;
+}
+
+function buildContextHintsByRef(entry) {
+ const map = new Map();
+ for (const op of entry.ops || []) {
+ const hints = new Set();
+ const add = (value) => {
+ const text = normalizeText(decodeBasicHtml(String(value || '')));
+ if (text.length < 3 || text.length > 160) return;
+ if (text === normalizeText(op.originalText) || text === normalizeText(op.newText)) return;
+ hints.add(text);
+ };
+
+ for (const item of op.nearbyEditableTexts || []) {
+ add(typeof item === 'string' ? item : item?.text);
+ }
+ const outer = typeof entry.element?.outerHTML === 'string' ? entry.element.outerHTML : '';
+ for (const match of outer.matchAll(/data-impeccable-original-text="([^"]*)"/g)) add(match[1]);
+ if (typeof entry.element?.textContent === 'string') {
+ for (const chunk of entry.element.textContent.split(/\s{2,}|\n|\t/)) add(chunk);
+ }
+ map.set(op.ref, [...hints].slice(0, 16));
+ }
+ return map;
+}
+
+function buildCandidatesForOp(op, cwd, searchFiles) {
+ const originalText = String(op.originalText || '');
+ const contextNeedles = op.contextHints || [];
+ return {
+ entryId: op.entryId,
+ ref: op.ref,
+ originalText,
+ sourceHint: analyzeSourceHint(op, cwd),
+ textMatches: originalText ? findLiteralMatches(searchFiles, originalText, { max: literalMatchLimit(originalText) }) : [],
+ objectKeyMatches: originalText ? findObjectKeyMatches(searchFiles, originalText, { max: OBJECT_KEY_MATCH_LIMIT }) : [],
+ locatorMatches: findLocatorMatches(searchFiles, op, { max: LOCATOR_MATCH_LIMIT }),
+ contextTextMatches: findContextMatches(searchFiles, contextNeedles, { maxPerHint: CONTEXT_MATCH_PER_HINT, max: CONTEXT_MATCH_LIMIT }),
+ };
+}
+
+function literalMatchLimit(text) {
+ return isWeakSourceNeedle(text) ? WEAK_LITERAL_MATCH_LIMIT : STRONG_LITERAL_MATCH_LIMIT;
+}
+
+function isWeakSourceNeedle(text) {
+ const normalized = normalizeText(text);
+ return normalized.length < 4 || /^[\d.,+\-%\s]+$/.test(normalized);
+}
+
+function analyzeSourceHint(op, cwd) {
+ const hint = normalizeSourceHint(op.sourceHint);
+ if (!hint.file) return null;
+ const file = path.resolve(cwd, hint.file);
+ const relativeFile = path.relative(cwd, file);
+ if (!isPathInsideOrEqual(cwd, file)) {
+ return { ...hint, status: 'outside_cwd', relativeFile: hint.file };
+ }
+ if (!fs.existsSync(file)) {
+ return { ...hint, status: 'file_missing', relativeFile };
+ }
+ if (isGeneratedFile(file, { cwd })) {
+ return { ...hint, status: 'generated', relativeFile };
+ }
+
+ const content = fs.readFileSync(file, 'utf-8');
+ const lines = content.split('\n');
+ const line = hint.line || 1;
+ const start = Math.max(0, line - 4);
+ const end = Math.min(lines.length, line + 3);
+ const windowText = lines.slice(start, end).join('\n');
+ const containsOriginalText = typeof op.originalText === 'string' && windowText.includes(op.originalText);
+ return {
+ ...hint,
+ status: containsOriginalText ? 'ok' : 'text_not_found_near_hint',
+ relativeFile,
+ excerpt: lines.slice(start, end).map((text, index) => ({
+ line: start + index + 1,
+ text: text.slice(0, 240),
+ })),
+ };
+}
+
+function normalizeSourceHint(hint) {
+ if (!hint || typeof hint !== 'object') return {};
+ let line = Number.isFinite(Number(hint.line)) ? Number(hint.line) : null;
+ let column = Number.isFinite(Number(hint.column)) ? Number(hint.column) : null;
+ if ((!line || !column) && typeof hint.loc === 'string') {
+ const match = hint.loc.match(/^(\d+)(?::(\d+))?/);
+ if (match) {
+ line = Number(match[1]);
+ if (match[2]) column = Number(match[2]);
+ }
+ }
+ return {
+ file: typeof hint.file === 'string' ? hint.file : '',
+ loc: typeof hint.loc === 'string' ? hint.loc : '',
+ line,
+ column,
+ };
+}
+
+function collectSearchFiles(cwd) {
+ const out = [];
+ const seenDirs = new Set();
+ const seenFiles = new Set();
+ for (const dir of SEARCH_DIRS) {
+ scanDir(path.join(cwd, dir), cwd, seenDirs, seenFiles, out, 0);
+ }
+ scanRootFiles(cwd, seenFiles, out);
+ return out;
+}
+
+function scanDir(dir, cwd, seenDirs, seenFiles, out, depth) {
+ if (depth > 7 || !fs.existsSync(dir)) return;
+ let realDir;
+ try { realDir = fs.realpathSync(dir); } catch { return; }
+ if (seenDirs.has(realDir)) return;
+ seenDirs.add(realDir);
+
+ let entries;
+ try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ if (SKIP_DIRS.has(entry.name)) continue;
+ scanDir(fullPath, cwd, seenDirs, seenFiles, out, depth + 1);
+ continue;
+ }
+ if (!entry.isFile() || !TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) continue;
+ maybeAddSearchFile(fullPath, cwd, seenFiles, out);
+ }
+}
+
+function scanRootFiles(cwd, seenFiles, out) {
+ let entries;
+ try { entries = fs.readdirSync(cwd, { withFileTypes: true }); } catch { return; }
+ for (const entry of entries) {
+ if (!entry.isFile() || !TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) continue;
+ maybeAddSearchFile(path.join(cwd, entry.name), cwd, seenFiles, out);
+ }
+}
+
+function maybeAddSearchFile(file, cwd, seenFiles, out) {
+ let realFile;
+ try { realFile = fs.realpathSync(file); } catch { return; }
+ if (seenFiles.has(realFile)) return;
+ seenFiles.add(realFile);
+ if (isGeneratedFile(file, { cwd })) return;
+ let content;
+ try { content = fs.readFileSync(file, 'utf-8'); } catch { return; }
+ out.push({ file, relativeFile: path.relative(cwd, file), content, lines: content.split('\n') });
+}
+
+function findLiteralMatches(searchFiles, needle, { max }) {
+ return findMatches(searchFiles, needle, { kind: 'text', max });
+}
+
+function findObjectKeyMatches(searchFiles, text, { max }) {
+ const re = new RegExp('(["\\\'`])' + escapeRegExp(text) + '\\1(?=\\s*:)', 'g');
+ const out = [];
+ for (const file of searchFiles) {
+ for (const match of file.content.matchAll(re)) {
+ out.push(matchForIndex(file, match.index, 'object_key', text));
+ if (out.length >= max) return out;
+ }
+ }
+ return out;
+}
+
+function findLocatorMatches(searchFiles, op, { max }) {
+ const needles = [];
+ if (op.elementId) needles.push({ kind: 'id', needle: op.elementId });
+ for (const cls of op.classes || []) {
+ if (cls) needles.push({ kind: 'class', needle: cls });
+ }
+ if (op.tag) needles.push({ kind: 'tag', needle: '<' + op.tag });
+
+ const out = [];
+ const seen = new Set();
+ for (const { kind, needle } of needles) {
+ for (const match of findMatches(searchFiles, needle, { kind, max })) {
+ const key = match.file + ':' + match.line + ':' + kind + ':' + needle;
+ if (seen.has(key)) continue;
+ seen.add(key);
+ out.push({ ...match, needle });
+ if (out.length >= max) return out;
+ }
+ }
+ return out;
+}
+
+function findContextMatches(searchFiles, hints, { maxPerHint, max }) {
+ const out = [];
+ const seen = new Set();
+ for (const hint of hints || []) {
+ for (const match of findMatches(searchFiles, hint, { kind: 'context', max: maxPerHint })) {
+ const key = match.file + ':' + match.line + ':' + hint;
+ if (seen.has(key)) continue;
+ seen.add(key);
+ out.push({ ...match, needle: hint });
+ if (out.length >= max) return out;
+ }
+ }
+ return out;
+}
+
+function findMatches(searchFiles, needle, { kind, max }) {
+ const text = String(needle || '');
+ if (!text) return [];
+ const out = [];
+ for (const file of searchFiles) {
+ let index = 0;
+ while (out.length < max) {
+ index = file.content.indexOf(text, index);
+ if (index === -1) break;
+ out.push(matchForIndex(file, index, kind, text));
+ index += Math.max(1, text.length);
+ }
+ if (out.length >= max) break;
+ }
+ return out;
+}
+
+function matchForIndex(file, index, kind, needle) {
+ const line = file.content.slice(0, index).split('\n').length;
+ const lineText = file.lines[line - 1] || '';
+ return {
+ kind,
+ file: file.relativeFile,
+ line,
+ needle,
+ excerpt: lineText.trim().slice(0, 240),
+ };
+}
+
+function isPathInsideOrEqual(cwd, file) {
+ const rel = path.relative(path.resolve(cwd), path.resolve(file));
+ return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function normalizeText(value) {
+ return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function decodeBasicHtml(value) {
+ return value
+ .replace(/"/g, '"')
+ .replace(/'/g, "'")
+ .replace(/'/g, "'")
+ .replace(/&/g, '&')
+ .replace(//g, '>');
+}
+
+function escapeRegExp(value) {
+ return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/.agents/skills/impeccable/scripts/live-manual-edits-buffer.mjs b/.agents/skills/impeccable/scripts/live-manual-edits-buffer.mjs
new file mode 100644
index 000000000..9e3dcf455
--- /dev/null
+++ b/.agents/skills/impeccable/scripts/live-manual-edits-buffer.mjs
@@ -0,0 +1,152 @@
+/**
+ * Shared helpers for the pending-manual-edits buffer on disk.
+ *
+ * Location: .impeccable/live/pending-manual-edits.json (project-local).
+ * Schema: { version: 1, entries: [{ id, pageUrl, element, ops, stagedAt }] }
+ *
+ * Each entry corresponds to one Save action from the browser. Ops merge by
+ * (pageUrl, ref): if the user re-edits the same element before committing, the
+ * existing entry's `newText` is replaced and `originalText` is kept (it holds
+ * the real source state).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLiveDir } from './impeccable-paths.mjs';
+
+const BUFFER_VERSION = 1;
+const BUFFER_FILENAME = 'pending-manual-edits.json';
+
+export function getBufferPath(cwd = process.cwd()) {
+ return path.join(getLiveDir(cwd), BUFFER_FILENAME);
+}
+
+export function readBuffer(cwd = process.cwd()) {
+ return readBufferInternal(cwd, { strict: false });
+}
+
+export function readBufferStrict(cwd = process.cwd()) {
+ return readBufferInternal(cwd, { strict: true });
+}
+
+function readBufferInternal(cwd, { strict }) {
+ const filePath = getBufferPath(cwd);
+ try {
+ const raw = fs.readFileSync(filePath, 'utf-8');
+ const parsed = JSON.parse(raw);
+ if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.entries)) {
+ if (strict) throw new Error('manual_edit_buffer_invalid_schema');
+ return { version: BUFFER_VERSION, entries: [] };
+ }
+ return { version: BUFFER_VERSION, entries: parsed.entries };
+ } catch (err) {
+ if (strict && err?.code !== 'ENOENT') {
+ throw new Error('manual_edit_buffer_unreadable: ' + (err.message || String(err)));
+ }
+ return { version: BUFFER_VERSION, entries: [] };
+ }
+}
+
+export function writeBuffer(cwd, buffer) {
+ const filePath = getBufferPath(cwd);
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
+ fs.writeFileSync(filePath, JSON.stringify({ version: BUFFER_VERSION, entries: buffer.entries }, null, 2));
+}
+
+/**
+ * Merge a new entry into the buffer. For each op in the new entry, if there's
+ * already a buffered op for the same (pageUrl, ref), update that op's newText
+ * and keep its original originalText (the true source state). Otherwise add
+ * the op (creating an entry if needed).
+ *
+ * Multiple ops in one Save are allowed; each is keyed by (pageUrl, ref).
+ */
+export function stageEntry(cwd, newEntry) {
+ const buf = readBufferStrict(cwd);
+ const pageUrl = newEntry.pageUrl;
+ for (const newOp of newEntry.ops) {
+ let mergedIntoExisting = false;
+ for (const existing of buf.entries) {
+ if (existing.pageUrl !== pageUrl) continue;
+ const existingOpIdx = existing.ops.findIndex((op) => op.ref === newOp.ref);
+ if (existingOpIdx >= 0) {
+ // Keep the original source text but refresh the latest DOM/source evidence.
+ existing.ops[existingOpIdx] = {
+ ...newOp,
+ originalText: existing.ops[existingOpIdx].originalText,
+ newText: newOp.newText,
+ deleted: newOp.deleted || false,
+ };
+ if (newEntry.element) existing.element = newEntry.element;
+ existing.stagedAt = new Date().toISOString();
+ mergedIntoExisting = true;
+ break;
+ }
+ }
+ if (mergedIntoExisting) continue;
+ // No existing op for this (pageUrl, ref). Find or create an entry to hold it.
+ let entry = buf.entries.find((e) => e.pageUrl === pageUrl && e.id === newEntry.id);
+ if (!entry) {
+ entry = {
+ id: newEntry.id,
+ pageUrl,
+ element: newEntry.element,
+ ops: [],
+ stagedAt: new Date().toISOString(),
+ };
+ buf.entries.push(entry);
+ }
+ entry.ops.push(newOp);
+ entry.stagedAt = new Date().toISOString();
+ }
+ writeBuffer(cwd, buf);
+ return buf;
+}
+
+/**
+ * Remove entries matching a predicate. Returns count of removed *ops* (not
+ * entries) so callers report a unit consistent with truncateBuffer and the
+ * pill's per-page op count. Empty entries (no ops left) are also pruned.
+ */
+export function removeEntries(cwd, predicate) {
+ const buf = readBuffer(cwd);
+ let removedOps = 0;
+ const kept = [];
+ for (const entry of buf.entries) {
+ if (predicate(entry)) {
+ removedOps += entry.ops?.length || 0;
+ } else if (entry.ops && entry.ops.length > 0) {
+ kept.push(entry);
+ }
+ }
+ buf.entries = kept;
+ writeBuffer(cwd, buf);
+ return removedOps;
+}
+
+/**
+ * Count by page for the counter UI. Returns { totalCount, perPage: {[pageUrl]: count} }.
+ */
+export function countByPage(cwd = process.cwd()) {
+ const buf = readBuffer(cwd);
+ const perPage = {};
+ let totalCount = 0;
+ for (const entry of buf.entries) {
+ const n = entry.ops.length;
+ perPage[entry.pageUrl] = (perPage[entry.pageUrl] || 0) + n;
+ totalCount += n;
+ }
+ return { totalCount, perPage };
+}
+
+/**
+ * Truncate the buffer to empty (used by discard-all). Returns the count of
+ * removed ops.
+ */
+export function truncateBuffer(cwd) {
+ const buf = readBuffer(cwd);
+ let removed = 0;
+ for (const entry of buf.entries) removed += entry.ops.length;
+ writeBuffer(cwd, { version: BUFFER_VERSION, entries: [] });
+ return removed;
+}
diff --git a/.agents/skills/impeccable/scripts/live-poll.mjs b/.agents/skills/impeccable/scripts/live-poll.mjs
index cbf17d54f..fad836612 100644
--- a/.agents/skills/impeccable/scripts/live-poll.mjs
+++ b/.agents/skills/impeccable/scripts/live-poll.mjs
@@ -21,7 +21,7 @@ import { readLiveServerInfo } from './impeccable-paths.mjs';
// depending on the standalone undici package.
export const PER_REQUEST_TIMEOUT_MS = 270_000;
-const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer']);
+const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply']);
function readServerInfo() {
const record = readLiveServerInfo(process.cwd());
@@ -36,6 +36,69 @@ export function buildPollReplyPayload(token, { id, type, message, file, data })
return { token, id, type, message, file, data };
}
+export function manualApplyPollBanner(event = {}) {
+ const id = event.id || 'EVENT_ID';
+ return [
+ `Manual Apply action required: edit source, then reply with \`live-poll.mjs --reply ${id} done --data '