pentimento 0.3.0

package/dist/cli.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createTwoFilesPatch } from 'diff';
+import { addComment, loadDoc, readMeta, readRevision, resolveComment, revert, snapshot } from './core.js';
+import { renderDiffPage, renderToFile } from './render.js';
+import { findPentimentoDocs, verifyDoc } from './verify.js';
+import { serveViewer } from './viewer.js';
+const USAGE = `pentimento — living documents
+
+Usage:
+  pentimento snapshot <doc> --summary "..." [--why "..."] [--source "..."] [--author name]
+  pentimento list <doc>
+  pentimento diff <doc> [revA] [revB] [--html [-o out.html]]
+                                      (defaults: latest two; one arg diffs it against the canonical;
+                                       --html renders a readable word-level diff page)
+  pentimento verify <doc-or-directory>    (check canonical/history/meta consistency)
+  pentimento revert <doc> <rev> [--author name]
+  pentimento render <doc> [-o out.html] [--artifact]
+                                      (--artifact: fragment for claude.ai Artifact publishing;
+                                       default: standalone HTML that works anywhere)
+  pentimento serve [dir] [--port 4820] [--host 127.0.0.1 | --tailscale] [--author name]
+                                      (live viewer: document index, revision picker, diffs,
+                                       hot reload, select-to-comment; never binds 0.0.0.0)
+  pentimento comments <doc>               (list open comments, plus a resolved count)
+  pentimento comment <doc> --text "..." [--anchor "#id"] [--quote "..."] [--author name]
+  pentimento address <doc>                (open comments formatted for an agent to act on)
+  pentimento resolve <doc> <comment-id> [--rev rNNN]
+
+Inline comments: leave %% @c: a note %% in the markdown — snapshot extracts them
+into meta.yml anchored to the nearest heading.
+`;
+const parseArgs = (argv) => {
+    const positional = [];
+    const flags = {};
+    const boolean = new Set(['artifact', 'html', 'tailscale']);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--') && boolean.has(a.slice(2)))
+            flags[a.slice(2)] = 'true';
+        else if (a.startsWith('--'))
+            flags[a.slice(2)] = argv[++i] ?? '';
+        else if (a === '-o')
+            flags.out = argv[++i] ??
+                '';
+        else if (a === '-s')
+            flags.summary = argv[++i] ?? '';
+        else
+            positional.push(a);
+    }
+    return { positional, flags };
+};
+const fail = (msg) => {
+    console.error(`pentimento: ${msg}`);
+    process.exit(1);
+};
+const tailscaleIp = () => {
+    try {
+        const out = execSync('tailscale ip -4', { encoding: 'utf8', timeout: 5000 }).trim().split('\n')[0];
+        if (/^100\./.test(out))
+            return out;
+    }
+    catch { /* fall through to interface scan */ }
+    for (const addrs of Object.values(os.networkInterfaces())) {
+        for (const a of addrs ?? []) {
+            // Tailscale hands out CGNAT range 100.64.0.0/10
+            if (a.family === 'IPv4' && /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(a.address))
+                return a.address;
+        }
+    }
+    return fail('could not determine a Tailscale IP (is tailscale up?)');
+};
+const defaultAuthor = () => {
+    try {
+        const name = execSync('git config user.name', { encoding: 'utf8', timeout: 3000 }).trim();
+        if (name)
+            return name;
+    }
+    catch {
+        // not in a git repo or git missing — fall through
+    }
+    return process.env.USER || process.env.USERNAME || undefined;
+};
+const main = () => {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const { positional, flags } = parseArgs(rest);
+    const doc = positional[0];
+    switch (cmd) {
+        case 'snapshot': {
+            if (!doc)
+                fail('snapshot needs a document path');
+            if (!flags.summary)
+                fail('snapshot needs --summary "what changed"');
+            const res = snapshot(doc, {
+                summary: flags.summary,
+                why: flags.why,
+                source: flags.source,
+                author: flags.author ?? defaultAuthor(),
+            });
+            console.log(`${res.rev} → ${res.historyFile}`);
+            break;
+        }
+        case 'list': {
+            if (!doc)
+                fail('list needs a document path');
+            const meta = readMeta(loadDoc(doc).historyDir);
+            if (!meta.revisions.length) {
+                console.log('no revisions');
+                break;
+            }
+            for (const r of meta.revisions) {
+                console.log(`${r.id}  ${r.created_at}  ${r.author}`);
+                console.log(`      ${r.summary}`);
+                if (r.why)
+                    console.log(`      why: ${r.why}`);
+            }
+            const open = meta.comments.filter((c) => c.status === 'open');
+            if (open.length)
+                console.log(`\n${open.length} open comment(s)`);
+            break;
+        }
+        case 'diff': {
+            if (!doc)
+                fail('diff needs a document path');
+            const d = loadDoc(doc);
+            const meta = readMeta(d.historyDir);
+            const revs = meta.revisions.map((r) => r.id);
+            let a;
+            let b;
+            let bContent;
+            if (positional.length >= 3) {
+                ;
+                [a, b] = [positional[1], positional[2]];
+                bContent = readRevision(doc, b);
+            }
+            else if (positional.length === 2) {
+                a = positional[1];
+                b = 'canonical';
+                bContent = d.raw;
+            }
+            else {
+                if (revs.length < 2)
+                    fail('need at least two revisions to diff (or pass revisions explicitly)');
+                [a, b] = revs.slice(-2);
+                bContent = readRevision(doc, b);
+            }
+            if (flags.html === 'true') {
+                const out = flags.out
+                    ? path.resolve(flags.out)
+                    : path.join(path.dirname(d.canonicalPath), `${d.name.toLowerCase()}-${a}-${b === 'canonical' ? 'now' : b}.html`);
+                fs.writeFileSync(out, renderDiffPage(doc, a, b), 'utf8');
+                console.log(out);
+            }
+            else {
+                process.stdout.write(createTwoFilesPatch(`${d.name} ${a}`, `${d.name} ${b}`, readRevision(doc, a), bContent));
+            }
+            break;
+        }
+        case 'verify': {
+            if (!doc)
+                fail('verify needs a document path or a directory');
+            const targets = fs.statSync(doc).isDirectory() ? findPentimentoDocs(doc) : [doc];
+            if (!targets.length) {
+                console.log('no Pentimento documents found');
+                break;
+            }
+            let errors = 0;
+            for (const t of targets) {
+                const issues = verifyDoc(t);
+                const label = path.relative(process.cwd(), t) || t;
+                if (!issues.length) {
+                    console.log(`✓ ${label}`);
+                    continue;
+                }
+                console.log(`${issues.some((i) => i.level === 'error') ? '✗' : '•'} ${label}`);
+                for (const i of issues) {
+                    console.log(`    ${i.level.toUpperCase().padEnd(5)} ${i.message}`);
+                    if (i.level === 'error')
+                        errors++;
+                }
+            }
+            if (errors)
+                process.exit(1);
+            break;
+        }
+        case 'revert': {
+            if (!doc || !positional[1])
+                fail('revert needs a document path and a revision (e.g. r002)');
+            const res = revert(doc, positional[1], flags.author ?? defaultAuthor());
+            console.log(`canonical restored from ${positional[1]}; recorded as ${res.rev}`);
+            break;
+        }
+        case 'render': {
+            if (!doc)
+                fail('render needs a document path');
+            const out = renderToFile(doc, flags.out, { artifact: flags.artifact === 'true' });
+            console.log(out);
+            break;
+        }
+        case 'serve': {
+            const root = path.resolve(doc ?? '.');
+            if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+                fail(`not a directory: ${root}`);
+            const port = Number(flags.port ?? 4820);
+            const host = flags.tailscale === 'true' ? tailscaleIp() : (flags.host?.trim() || '127.0.0.1');
+            serveViewer(root, { host, port, author: flags.author ?? defaultAuthor() });
+            console.log(`pentimento viewer → http://${host}:${port}/  (watching ${root})`);
+            break;
+        }
+        case 'comments': {
+            if (!doc)
+                fail('comments needs a document path');
+            const meta = readMeta(loadDoc(doc).historyDir);
+            const open = meta.comments.filter((c) => c.status === 'open');
+            const resolved = meta.comments.length - open.length;
+            if (!meta.comments.length) {
+                console.log('no comments');
+                break;
+            }
+            for (const c of open) {
+                console.log(`[${c.id}] OPEN ${c.anchor || '(document)'} — ${c.author}, ${c.created_at.slice(0, 10)}`);
+                if (c.quote)
+                    console.log(`    > ${c.quote}`);
+                console.log(`    ${c.text}`);
+            }
+            if (resolved)
+                console.log(`(+ ${resolved} resolved)`);
+            break;
+        }
+        case 'comment': {
+            if (!doc)
+                fail('comment needs a document path');
+            if (!flags.text)
+                fail('comment needs --text "..."');
+            const entry = addComment(doc, {
+                text: flags.text,
+                anchor: flags.anchor,
+                quote: flags.quote,
+                author: flags.author ?? defaultAuthor(),
+            });
+            console.log(entry.id);
+            break;
+        }
+        case 'address': {
+            if (!doc)
+                fail('address needs a document path');
+            const d = loadDoc(doc);
+            const meta = readMeta(d.historyDir);
+            const open = meta.comments.filter((c) => c.status === 'open');
+            if (!open.length) {
+                console.log('no open comments — nothing to address');
+                break;
+            }
+            console.log(`${d.name} (${d.frontmatter['Current Revision'] ?? 'no revision'}) has ${open.length} open comment${open.length > 1 ? 's' : ''}:\n`);
+            for (const c of open) {
+                console.log(`[${c.id}] anchored at ${c.anchor || '(document)'} — ${c.author}, ${c.created_at.slice(0, 10)}`);
+                if (c.quote)
+                    console.log(`  quoted text: "${c.quote}"`);
+                if (c.prefix || c.suffix)
+                    console.log(`  context: …${c.prefix ?? ''}[quote]${c.suffix ?? ''}…`);
+                console.log(`  comment: ${c.text}\n`);
+            }
+            console.log('To address: revise the canonical markdown accordingly, then:');
+            console.log(`  pentimento snapshot ${positional[0]} --summary "Address review comments" --why "..."`);
+            console.log(`  pentimento resolve ${positional[0]} <comment-id> --rev <new revision>   # once per addressed comment`);
+            break;
+        }
+        case 'resolve': {
+            if (!doc || !positional[1])
+                fail('resolve needs a document path and a comment id');
+            const c = resolveComment(doc, positional[1], flags.rev);
+            console.log(`${c.id} resolved${c.resolved_in ? ` in ${c.resolved_in}` : ''}`);
+            break;
+        }
+        default: {
+            const wantsHelp = !cmd || cmd === 'help' || cmd === '--help' || cmd === '-h';
+            console.log(USAGE);
+            process.exit(wantsHelp ? 0 : 1);
+        }
+    }
+};
+try {
+    main();
+}
+catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+}

package/dist/core.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument, parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export const splitRaw = (raw) => {
+    const m = FRONTMATTER_RE.exec(raw);
+    return m ? { frontmatterRaw: m[1], body: raw.slice(m[0].length) } : { frontmatterRaw: null, body: raw };
+};
+export const slugify = (s) => s.toLowerCase().replace(/`/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const INLINE_COMMENT_RE = /[ \t]*%%\s*@c:\s*([\s\S]*?)%%/g;
+/** Pull `%% @c: ... %%` inline comments out of the source, anchored to the nearest preceding heading. */
+export const extractInlineComments = (raw) => {
+    const found = [];
+    const headingFor = (index) => {
+        const matches = [...raw.slice(0, index).matchAll(/^#{1,3}\s+(.+)$/gm)];
+        if (!matches.length)
+            return '';
+        const title = matches[matches.length - 1][1];
+        const idm = /<!--[^>]*\bid:\s*([\w-]+)/.exec(title);
+        if (idm)
+            return `#${idm[1]}`;
+        return `#${slugify(title.replace(/<!--.*?-->/, '').trim())}`;
+    };
+    const cleaned = raw.replace(INLINE_COMMENT_RE, (_m, text, offset) => {
+        found.push({ text: text.trim(), anchor: headingFor(offset) });
+        return '';
+    });
+    return { cleaned, found };
+};
+export const nowStamp = () => {
+    const d = new Date();
+    const offsetMin = -d.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? '+' : '-';
+    const abs = Math.abs(offsetMin);
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+        `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+};
+export const atomicWrite = (filePath, content) => {
+    const tmp = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, content, 'utf8');
+    fs.renameSync(tmp, filePath);
+};
+export const revId = (n) => `r${String(n).padStart(3, '0')}`;
+export const parseRevId = (value) => {
+    const m = /^r(\d{3,})$/.exec(String(value ?? '').trim());
+    if (!m)
+        throw new Error(`Invalid Current Revision value: ${JSON.stringify(value)} — expected rNNN`);
+    return Number(m[1]);
+};
+export const loadDoc = (docPath) => {
+    const canonicalPath = path.resolve(docPath);
+    if (!fs.existsSync(canonicalPath))
+        throw new Error(`No such document: ${canonicalPath}`);
+    const raw = fs.readFileSync(canonicalPath, 'utf8');
+    const m = FRONTMATTER_RE.exec(raw);
+    const frontmatter = m ? (parseYaml(m[1]) ?? {}) : {};
+    const body = m ? raw.slice(m[0].length) : raw;
+    const name = path.basename(canonicalPath).replace(/\.md$/i, '');
+    // History Folder is canonical-relative — the single path contract (audit C3)
+    const historyRel = typeof frontmatter['History Folder'] === 'string'
+        ? frontmatter['History Folder']
+        : path.join('.history', name);
+    const historyDir = path.resolve(path.dirname(canonicalPath), historyRel);
+    return { canonicalPath, name, historyDir, frontmatter, body, raw };
+};
+/** Rewrite one scalar frontmatter key, preserving all other formatting (audit H3). */
+export const stampFrontmatter = (raw, updates) => {
+    const m = FRONTMATTER_RE.exec(raw);
+    if (m) {
+        const doc = parseDocument(m[1]);
+        for (const [k, v] of Object.entries(updates))
+            v === null ? doc.delete(k) : doc.set(k, v);
+        return `---\n${String(doc).replace(/\n$/, '')}\n---\n${raw.slice(m[0].length)}`;
+    }
+    const kept = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== null));
+    const fmDoc = stringifyYaml(kept).replace(/\n$/, '');
+    return `---\n${fmDoc}\n---\n\n${raw}`;
+};
+export const readMeta = (historyDir) => {
+    const metaPath = path.join(historyDir, 'meta.yml');
+    if (!fs.existsSync(metaPath))
+        return { revisions: [], comments: [] };
+    const parsed = parseYaml(fs.readFileSync(metaPath, 'utf8'));
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new Error(`Unreadable meta.yml at ${metaPath} — refusing to touch it`);
+    }
+    return { revisions: parsed.revisions ?? [], comments: parsed.comments ?? [] };
+};
+export const writeMeta = (historyDir, meta) => {
+    const metaPath = path.join(historyDir, 'meta.yml');
+    atomicWrite(metaPath, stringifyYaml({ revisions: meta.revisions, comments: meta.comments }));
+};
+const withLock = (historyDir, fn) => {
+    const lockDir = path.join(historyDir, '.lock');
+    fs.mkdirSync(historyDir, { recursive: true });
+    try {
+        fs.mkdirSync(lockDir);
+    }
+    catch {
+        const age = Date.now() - fs.statSync(lockDir).mtimeMs;
+        if (age < 10 * 60 * 1000)
+            throw new Error(`Another pentimento operation holds the lock: ${lockDir}`);
+        fs.rmdirSync(lockDir);
+        fs.mkdirSync(lockDir);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmdirSync(lockDir);
+    }
+};
+/**
+ * Capture the canonical as the next revision.
+ * Order: history file first (refusing to overwrite), then meta, then canonical stamp —
+ * a crash mid-way surfaces loudly on the next run instead of silently overwriting (audit C1).
+ */
+export const snapshot = (docPath, opts) => {
+    const doc = loadDoc(docPath);
+    return withLock(doc.historyDir, () => {
+        // 'Vellum: true' is the pre-rename marker — keep reading it so old docs snapshot cleanly
+        const isPentimento = doc.frontmatter['Pentimento'] === true || doc.frontmatter['Vellum'] === true;
+        const current = isPentimento && doc.frontmatter['Current Revision'] !== undefined
+            ? parseRevId(doc.frontmatter['Current Revision'])
+            : 0;
+        const next = revId(current + 1);
+        const historyFile = path.join(doc.historyDir, `${next}.md`);
+        if (fs.existsSync(historyFile)) {
+            throw new Error(`${historyFile} already exists — history and frontmatter disagree; refusing to overwrite`);
+        }
+        const historyRel = path
+            .relative(path.dirname(doc.canonicalPath), doc.historyDir)
+            .split(path.sep)
+            .join('/');
+        const { cleaned, found } = extractInlineComments(doc.raw);
+        const stamped = stampFrontmatter(cleaned, {
+            Pentimento: true,
+            Vellum: null, // migrate pre-rename docs: drop the legacy marker on first snapshot
+            'Current Revision': next,
+            'History Folder': historyRel,
+        });
+        fs.writeFileSync(historyFile, stamped, { flag: 'wx' });
+        const meta = readMeta(doc.historyDir);
+        meta.revisions.push({
+            id: next,
+            created_at: nowStamp(),
+            author: opts.author ?? 'unknown',
+            summary: opts.summary,
+            ...(opts.why ? { why: opts.why } : {}),
+            ...(opts.source ? { source: opts.source } : {}),
+        });
+        for (const f of found) {
+            meta.comments.push(makeComment(meta, { text: f.text, anchor: f.anchor, author: opts.author }));
+        }
+        writeMeta(doc.historyDir, meta);
+        atomicWrite(doc.canonicalPath, stamped);
+        return { rev: next, historyFile };
+    });
+};
+const makeComment = (meta, input) => {
+    const stamp = nowStamp();
+    const date = stamp.slice(0, 10);
+    const seq = meta.comments.filter((c) => c.id.startsWith(`c-${date}`)).length + 1;
+    return {
+        id: `c-${date}-${String(seq).padStart(3, '0')}`,
+        anchor: input.anchor ?? '',
+        ...(input.quote ? { quote: input.quote } : {}),
+        ...(input.prefix ? { prefix: input.prefix } : {}),
+        ...(input.suffix ? { suffix: input.suffix } : {}),
+        text: input.text,
+        status: 'open',
+        created_at: stamp,
+        author: input.author ?? 'reader',
+        resolved_in: null,
+    };
+};
+export const addComment = (docPath, input) => {
+    const doc = loadDoc(docPath);
+    return withLock(doc.historyDir, () => {
+        const meta = readMeta(doc.historyDir);
+        const entry = makeComment(meta, input);
+        meta.comments.push(entry);
+        writeMeta(doc.historyDir, meta);
+        return entry;
+    });
+};
+export const resolveComment = (docPath, id, rev) => {
+    const doc = loadDoc(docPath);
+    return withLock(doc.historyDir, () => {
+        const meta = readMeta(doc.historyDir);
+        const c = meta.comments.find((x) => x.id === id);
+        if (!c)
+            throw new Error(`no comment ${id} on ${doc.name}`);
+        c.status = 'resolved';
+        c.resolved_in = rev ?? null;
+        writeMeta(doc.historyDir, meta);
+        return c;
+    });
+};
+export const readRevision = (docPath, rev) => {
+    const doc = loadDoc(docPath);
+    const file = path.join(doc.historyDir, `${rev}.md`);
+    if (!fs.existsSync(file))
+        throw new Error(`No revision ${rev} for ${doc.name} (looked at ${file})`);
+    return fs.readFileSync(file, 'utf8');
+};
+/** Restore an earlier revision's body as a new revision (history stays append-only). */
+export const revert = (docPath, rev, author) => {
+    const target = readRevision(docPath, rev);
+    const doc = loadDoc(docPath);
+    const targetBody = FRONTMATTER_RE.exec(target)
+        ? target.slice(FRONTMATTER_RE.exec(target)[0].length)
+        : target;
+    const restored = doc.raw.slice(0, doc.raw.length - doc.body.length) + targetBody;
+    atomicWrite(doc.canonicalPath, restored);
+    return snapshot(docPath, {
+        summary: `Restored content of ${rev}`,
+        why: `pentimento revert ${rev}`,
+        author,
+    });
+};