#!/usr/bin/env node
// scripts/annotate.mjs
//
// Builds a self-contained operator-annotation HTML for a voyage artifact
// (brief.md / plan.md / review.md). The producing commands call this on
// their last step and print the file:// link; the operator opens it in
// a browser, clicks any line to attach their own note, watches a sidebar
// of all their annotations, and copies a single prompt (with every note)
// back into Claude. Claude revises the source .md from the notes.
//
// • Operator drives every annotation. No pre-generated suggestions.
// • Each annotation is anchored to the source line number (1-based).
// • Annotations persist in localStorage per artifact path — refresh
// does not lose work; closing the browser does not either.
// • Zero external network, zero npm deps, deterministic output.
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { basename, resolve } from 'node:path';
import { splitFrontmatter } from '../lib/util/frontmatter.mjs';
function escapeHtml(s) {
return String(s)
.replace(/&/g, '&')
.replace(//g, '>')
.replace(/"/g, '"');
}
function deriveTitle(mdText, fallbackName) {
const { hasFrontmatter, frontmatter } = splitFrontmatter(mdText);
if (hasFrontmatter) {
const taskMatch = frontmatter.match(/^task:\s*(.+)$/m);
if (taskMatch) return taskMatch[1].trim().replace(/^["']|["']$/g, '');
const slugMatch = frontmatter.match(/^slug:\s*(.+)$/m);
if (slugMatch) return slugMatch[1].trim().replace(/^["']|["']$/g, '');
}
const h1 = mdText.match(/^#\s+(.+)$/m);
if (h1) return h1[1].trim();
return fallbackName;
}
function buildHtml(artifactPath, mdText) {
const lines = mdText.replace(/\r\n/g, '\n').split('\n');
const fileName = basename(artifactPath);
const title = deriveTitle(mdText, fileName);
const linesJson = JSON.stringify(lines);
const artifactPathJson = JSON.stringify(artifactPath);
const titleEsc = escapeHtml(title);
const fileNameEsc = escapeHtml(fileName);
return '\n'
+ '\n'
+ '\n'
+ '' + titleEsc + ' — annotate \n'
+ '\n'
+ '\n'
+ '\n'
+ '\n'
+ '
\n'
+ '
\n'
+ ' \n'
+ ' Click any line to add your own annotation. Annotations are saved in your browser per artifact path.
\n'
+ '
\n'
+ ' \n'
+ ' \n'
+ ' \n'
+ '
\n'
+ ' \n'
+ ' Prompt for Claude \n'
+ ' Copy Prompt \n'
+ '
\n'
+ ' Click a line and add a note to generate a prompt. \n'
+ ' \n'
+ '
$1 ');
s = s.replace(/\\*\\*([^*]+)\\*\\*/g, '$1 ');
s = s.replace(/(^|[\\s])\\*([^*\\s][^*]*?)\\*(?=\\s|[.,;:!?]|$)/g, '$1$2 ');
s = s.replace(/\\[([^\\]]+)\\]\\(([^)\\s]+)\\)/g, function(m, t, h) {
const safe = /^(https?:|mailto:|#)/i.test(h) ? h : '#';
return '' + t + ' ';
});
return s;
}
function classifyLine(raw) {
if (/^#{1,6}\\s/.test(raw)) {
const m = raw.match(/^(#{1,6})\\s+(.*)$/);
return { kind: 'heading', level: m[1].length, content: m[2] };
}
if (raw.trim() === '') return { kind: 'blank' };
return { kind: 'text', content: raw };
}
function renderDocLine(raw, lineNum) {
const cls = classifyLine(raw);
const escaped = escapeHtml(cls.content || raw);
let inner = '';
if (cls.kind === 'heading') {
inner = '' + renderInline(escaped) + ' ';
} else if (cls.kind === 'blank') {
inner = ' ';
} else {
inner = renderInline(escaped);
}
return inner;
}
function getAnnotationsForLine(lineNum) {
return state.annotations.filter(function(a){ return a.line === lineNum; });
}
function renderDoc() {
const root = document.getElementById('doc');
const html = DOC_LINES.map(function(raw, i) {
const lineNum = i + 1;
const anns = getAnnotationsForLine(lineNum);
const annotated = anns.length > 0 ? ' annotated' : '';
const active = state.activeId && anns.some(function(a){return a.id === state.activeId;}) ? ' active' : '';
const gutter = anns.length > 0 ? String(anns.length) : '';
const content = renderDocLine(raw, lineNum);
let row = ''
+ '' + lineNum + ' '
+ '' + (gutter || '+') + ' '
+ '' + content + ' '
+ '
';
if (state.openInputLine === lineNum) {
const placeholder = anns.length > 0 ? 'Add another note for line ' + lineNum + '...' : 'Your note for line ' + lineNum + '...';
row += '';
}
return row;
}).join('');
root.innerHTML = html;
root.querySelectorAll('.doc-line').forEach(function(el) {
el.addEventListener('click', function(e) {
if (e.target.closest('.input-row')) return;
const ln = parseInt(el.getAttribute('data-line'), 10);
state.openInputLine = state.openInputLine === ln ? null : ln;
state.activeId = null;
renderAll();
if (state.openInputLine) {
setTimeout(function(){
const ta = document.getElementById('input-' + ln);
if (ta) ta.focus();
}, 0);
}
});
});
root.querySelectorAll('button[data-act]').forEach(function(b) {
b.addEventListener('click', function(e) {
e.stopPropagation();
const act = b.dataset.act;
if (act === 'cancel-input') { state.openInputLine = null; renderAll(); }
else if (act === 'save-input') {
const ln = parseInt(b.dataset.line, 10);
const ta = document.getElementById('input-' + ln);
const text = ta.value.trim();
if (!text) return;
addAnnotation(ln, text);
}
});
});
root.querySelectorAll('textarea[id^="input-"]').forEach(function(ta) {
ta.addEventListener('input', function() {
const ln = parseInt(ta.id.replace('input-', ''), 10);
const saveBtn = document.querySelector('button[data-act="save-input"][data-line="' + ln + '"]');
if (saveBtn) saveBtn.disabled = ta.value.trim().length === 0;
});
ta.addEventListener('keydown', function(e) {
if (e.key === 'Escape') { state.openInputLine = null; renderAll(); }
else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
const ln = parseInt(ta.id.replace('input-', ''), 10);
const text = ta.value.trim();
if (text) addAnnotation(ln, text);
}
});
});
}
function addAnnotation(lineNum, text) {
const raw = DOC_LINES[lineNum - 1] || '';
const snippet = raw.trim().length > 80 ? raw.trim().slice(0, 77) + '…' : raw.trim();
const a = { id: nextId++, line: lineNum, target: snippet || '(blank line)', text: text, ts: new Date().toISOString() };
state.annotations.push(a);
state.openInputLine = null;
state.activeId = a.id;
save();
renderAll();
setTimeout(function(){
const card = document.getElementById('card-' + a.id);
if (card) card.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
}, 50);
}
function deleteAnnotation(id) {
state.annotations = state.annotations.filter(function(a){ return a.id !== id; });
if (state.activeId === id) state.activeId = null;
if (state.editingId === id) state.editingId = null;
save();
renderAll();
}
function updateAnnotation(id, text) {
const a = state.annotations.find(function(x){ return x.id === id; });
if (!a) return;
if (!text.trim()) { deleteAnnotation(id); return; }
a.text = text.trim();
a.ts = new Date().toISOString();
state.editingId = null;
save();
renderAll();
}
function renderNotesList() {
const root = document.getElementById('notes-list');
if (state.annotations.length === 0) {
root.innerHTML = 'No annotations yet.
';
return;
}
const sorted = state.annotations.slice().sort(function(a, b){ return a.line - b.line || a.id - b.id; });
root.innerHTML = sorted.map(function(a) {
const active = a.id === state.activeId ? ' active' : '';
const editing = a.id === state.editingId;
return ''
+ '
'
+ 'Line ' + a.line + ' '
+ '✕ '
+ '
'
+ '
' + escapeHtml(a.target) + '
'
+ (editing
? '
'
+ '
'
+ 'Cancel '
+ 'Save '
+ '
'
: '
' + escapeHtml(a.text) + '
')
+ '
No annotations yet '
: '' + n + ' annotation' + (n === 1 ? '' : 's') + ' ';
const copyBtn = document.getElementById('copy');
copyBtn.disabled = n === 0;
}
function renderPrompt() {
const out = document.getElementById('prompt');
if (state.annotations.length === 0) {
out.classList.add('empty');
out.textContent = 'Click a line and add a note to generate a prompt.';
return;
}
out.classList.remove('empty');
const sorted = state.annotations.slice().sort(function(a, b){ return a.line - b.line || a.id - b.id; });
let p = 'Please revise the voyage artifact at \`' + ARTIFACT_PATH + '\` with the operator annotations below.\\n';
p += 'Each annotation is anchored to a specific line of the source markdown.\\n';
p += 'Treat the operator notes as authoritative direction for what should change.\\n\\n';
p += '## Annotations (' + state.annotations.length + ' total)\\n\\n';
for (let i = 0; i < sorted.length; i++) {
const a = sorted[i];
p += '### Line ' + a.line + '\\n';
p += 'Source: ' + a.target + '\\n';
p += 'Operator note: ' + a.text + '\\n\\n';
}
out.textContent = p;
}
document.getElementById('copy').addEventListener('click', async function() {
const txt = document.getElementById('prompt').textContent;
try {
await navigator.clipboard.writeText(txt);
const btn = document.getElementById('copy');
btn.classList.add('copied');
const old = btn.textContent;
btn.textContent = 'Copied!';
setTimeout(function(){ btn.classList.remove('copied'); btn.textContent = old; }, 1500);
} catch (e) { alert('Copy failed: ' + e.message); }
});
document.getElementById('clear-all').addEventListener('click', function() {
if (state.annotations.length === 0) return;
if (confirm('Remove all ' + state.annotations.length + ' annotations? This cannot be undone.')) {
state.annotations = []; state.activeId = null; state.editingId = null;
save(); renderAll();
}
});
document.addEventListener('keydown', function(e) {
if (e.key === 'Escape' && state.openInputLine !== null) {
state.openInputLine = null;
renderAll();
}
});
function renderAll() {
renderDoc();
renderNotesList();
renderStats();
renderPrompt();
}
load();
renderAll();
`.trim();
// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------
function parseArgs(argv) {
const args = { input: null, out: null, help: false };
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--out') args.out = argv[++i];
else if (a === '--help' || a === '-h') args.help = true;
else if (!args.input) args.input = a;
}
return args;
}
function render(inputPath, outputPath) {
if (!existsSync(inputPath)) {
process.stderr.write('annotate: input not found: ' + inputPath + '\n');
process.exit(2);
}
const text = readFileSync(inputPath, 'utf-8');
const html = buildHtml(resolve(inputPath), text);
const out = outputPath || inputPath.replace(/\.md$/, '.html');
writeFileSync(out, html);
return out;
}
if (import.meta.url === `file://${process.argv[1]}`) {
const args = parseArgs(process.argv.slice(2));
if (args.help || !args.input) {
process.stdout.write(
'Usage: annotate [--out ]\n\n'
+ 'Builds a self-contained operator-annotation HTML for a voyage\n'
+ 'artifact. The operator opens the HTML, clicks lines to attach\n'
+ 'their own notes, copies a structured prompt, pastes back into\n'
+ 'Claude. Annotations persist in localStorage per artifact path.\n\n'
+ 'Default output: .html next to input.\n',
);
process.exit(args.help ? 0 : 2);
}
const out = render(args.input, args.out);
process.stdout.write(out + '\n');
}
export { render, buildHtml, parseArgs };