@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/history.js

@@ -0,0 +1,600 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { openHistory, withHistory } from './db.js';
+import { readEvidenceMap } from './evidence.js';
+import { pathExists } from './fs.js';
+import { loadPages, loadProject } from './project.js';
+import { lineHunks } from './text-diff.js';
+/** Open a request row before the agent starts, so an interrupted run is still visible. */
+export async function startRequest(root, input) {
+    const id = `req-${randomUUID().slice(0, 12)}`;
+    const recorded = await withHistory(root, (database) => {
+        database
+            .prepare(`INSERT INTO requests (id, created_at, kind, trigger, request_text, agent, model,
+           reasoning_effort, status)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running')`)
+            .run(id, now(), input.kind, input.trigger ?? 'manual', text(input.requestText), text(input.agent), text(input.model), text(input.reasoningEffort));
+        return id;
+    });
+    return recorded;
+}
+export async function finishRequest(root, id, input) {
+    if (!id)
+        return;
+    await withHistory(root, (database) => {
+        database
+            .prepare(`UPDATE requests
+            SET finished_at = ?,
+                duration_ms = CAST((julianday(?) - julianday(created_at)) * 86400000 AS INTEGER),
+                status = ?,
+                pages_changed = COALESCE(?, pages_changed),
+                lines_added = COALESCE(?, lines_added),
+                lines_removed = COALESCE(?, lines_removed),
+                validation_pages = ?,
+                validation_errors = ?,
+                validation_warnings = ?,
+                error_message = ?,
+                input_tokens = COALESCE(?, input_tokens),
+                output_tokens = COALESCE(?, output_tokens),
+                cache_read_tokens = COALESCE(?, cache_read_tokens),
+                cache_creation_tokens = COALESCE(?, cache_creation_tokens),
+                cost_usd = COALESCE(?, cost_usd),
+                agent_turns = COALESCE(?, agent_turns),
+                agent_sessions = COALESCE(?, agent_sessions),
+                max_context_tokens = COALESCE(?, max_context_tokens)
+          WHERE id = ?`)
+            .run(now(), now(), input.status, input.pagesChanged ?? null, input.linesAdded ?? null, input.linesRemoved ?? null, input.validation?.pages ?? null, input.validation?.errors ?? null, input.validation?.warnings ?? null, text(input.error), ...usageColumns(input.usage), id);
+    });
+}
+/**
+ * Capture page content so a direct authoring run can be measured afterwards.
+ * Held in memory rather than read back from the page registry: the UI server
+ * backfills that registry on startup, which would otherwise claim the pages a
+ * still-running agent is in the middle of writing.
+ */
+export async function snapshotPages(root, project) {
+    const snapshot = new Map();
+    try {
+        const resolved = project ?? (await loadProject(root));
+        for (const absolute of await loadPages(root, resolved)) {
+            snapshot.set(portable(relative(root, absolute)), await readFile(absolute, 'utf8'));
+        }
+    }
+    catch {
+        // A project with no content directory yet simply starts from nothing.
+    }
+    return snapshot;
+}
+/**
+ * Record what an authoring run changed. `create` and `update` write straight to
+ * disk instead of producing a proposal, so the diff against the pre-run
+ * snapshot is the only account of which pages the request touched.
+ */
+export async function recordAuthoredPages(root, requestId, before, project) {
+    const result = { paths: new Set(), linesAdded: 0, linesRemoved: 0 };
+    const after = await snapshotPages(root, project);
+    const changes = [];
+    const paths = new Set([...before.keys(), ...after.keys()]);
+    for (const path of [...paths].sort()) {
+        const previous = before.get(path);
+        const current = after.get(path);
+        if (previous === current)
+            continue;
+        let added = 0;
+        let removed = 0;
+        for (const hunk of lineHunks(previous ?? '', current ?? '', path)) {
+            added += hunk.newLines.length;
+            removed += hunk.oldLines.length;
+        }
+        result.paths.add(path);
+        result.linesAdded += added;
+        result.linesRemoved += removed;
+        changes.push({
+            path,
+            kind: current === undefined ? 'deleted' : previous === undefined ? 'added' : 'modified',
+            title: text(frontmatterTitle(current ?? previous ?? '')),
+            added,
+            removed,
+        });
+    }
+    if (!requestId || changes.length === 0)
+        return result;
+    await withHistory(root, (database) => {
+        const timestamp = now();
+        // Authoring writes straight to the working tree, so every page it touched is
+        // already in effect — there is no pending decision to make later.
+        const upsert = database.prepare(`INSERT INTO request_pages (request_id, path, title, change_kind, category, decision,
+         decided_at, lines_added, lines_removed)
+       VALUES (?, ?, ?, ?, 'page', 'accepted', ?, ?, ?)
+       ON CONFLICT (request_id, path) DO UPDATE SET
+         title = excluded.title,
+         change_kind = excluded.change_kind,
+         lines_added = excluded.lines_added,
+         lines_removed = excluded.lines_removed`);
+        for (const change of changes) {
+            upsert.run(requestId, change.path, change.title, change.kind, timestamp, change.added, change.removed);
+        }
+    });
+    return result;
+}
+/**
+ * Mirror a proposal into history. Called on every status change, so the row
+ * survives even when the run directory is later pruned.
+ */
+export async function recordSyncRun(root, run, context = {}) {
+    await withHistory(root, (database) => {
+        const counts = lineCounts(run.changes);
+        const finishedAt = run.appliedAt ?? run.rejectedAt ?? run.completedAt ?? null;
+        database
+            .prepare(`INSERT INTO requests (id, created_at, finished_at, duration_ms, kind, trigger,
+           request_text, agent, model, reasoning_effort, status, pages_changed, lines_added,
+           lines_removed, validation_pages, validation_errors, validation_warnings,
+           source_summary, stale_pages_count, error_message, run_dir, input_tokens,
+           output_tokens, cache_read_tokens, cache_creation_tokens, cost_usd, agent_turns,
+           agent_sessions, max_context_tokens)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (id) DO UPDATE SET
+           finished_at = excluded.finished_at,
+           duration_ms = excluded.duration_ms,
+           kind = excluded.kind,
+           status = excluded.status,
+           pages_changed = excluded.pages_changed,
+           lines_added = excluded.lines_added,
+           lines_removed = excluded.lines_removed,
+           validation_pages = excluded.validation_pages,
+           validation_errors = excluded.validation_errors,
+           validation_warnings = excluded.validation_warnings,
+           source_summary = excluded.source_summary,
+           stale_pages_count = excluded.stale_pages_count,
+           error_message = excluded.error_message,
+           request_text = COALESCE(excluded.request_text, requests.request_text),
+           agent = COALESCE(excluded.agent, requests.agent),
+           model = COALESCE(excluded.model, requests.model),
+           input_tokens = COALESCE(excluded.input_tokens, requests.input_tokens),
+           output_tokens = COALESCE(excluded.output_tokens, requests.output_tokens),
+           cache_read_tokens = COALESCE(excluded.cache_read_tokens, requests.cache_read_tokens),
+           cache_creation_tokens = COALESCE(excluded.cache_creation_tokens, requests.cache_creation_tokens),
+           cost_usd = COALESCE(excluded.cost_usd, requests.cost_usd),
+           agent_turns = COALESCE(excluded.agent_turns, requests.agent_turns),
+           agent_sessions = COALESCE(excluded.agent_sessions, requests.agent_sessions),
+           max_context_tokens = COALESCE(excluded.max_context_tokens, requests.max_context_tokens)`)
+            .run(run.id, run.createdAt, finishedAt, finishedAt ? elapsed(run.createdAt, finishedAt) : null, run.editRequest ? 'edit' : run.authoringMode ?? 'update', run.trigger, text(run.editRequest?.followUps.at(-1)?.instruction ?? run.editRequest?.instruction ?? context.requestText), text(context.agent), text(context.model), text(context.reasoningEffort), run.status, run.changes.filter((change) => change.category === 'page').length, counts.added, counts.removed, run.validation?.pages ?? null, run.validation?.errors ?? null, run.validation?.warnings ?? null, text(run.sourceSummary), run.stalePages.length, text(run.error), text(context.runDir), ...usageColumns(run.usage));
+        const upsertPage = database.prepare(`INSERT INTO request_pages (request_id, path, title, change_kind, category, decision,
+         decided_at, lines_added, lines_removed)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (request_id, path) DO UPDATE SET
+         title = COALESCE(excluded.title, request_pages.title),
+         change_kind = excluded.change_kind,
+         category = excluded.category,
+         decision = excluded.decision,
+         decided_at = excluded.decided_at,
+         lines_added = excluded.lines_added,
+         lines_removed = excluded.lines_removed`);
+        if (run.editRequest) {
+            for (const path of run.editRequest.paths) {
+                if (run.changes.some((change) => change.path === path))
+                    continue;
+                upsertPage.run(run.id, path, null, 'modified', 'page', 'pending', null, 0, 0);
+            }
+        }
+        for (const change of run.changes) {
+            const decision = changeDecision(change);
+            const changeCounts = lineCounts([change]);
+            upsertPage.run(run.id, change.path, text(change.title), change.kind, change.category, decision.state, decision.at, changeCounts.added, changeCounts.removed);
+        }
+    });
+}
+/** Append the baselines a run was written against. Ignores repeats. */
+export async function recordSourceSyncs(root, state, requestId) {
+    if (!state)
+        return;
+    await withHistory(root, (database) => {
+        const insert = database.prepare(`INSERT OR IGNORE INTO source_syncs (source_name, commit_hash, fingerprint, recorded_at,
+         request_id)
+       VALUES (?, ?, ?, ?, ?)`);
+        for (const [name, record] of Object.entries(state.sources)) {
+            insert.run(name, record.commit ?? '', record.contentFingerprint ?? '', record.recordedAt, text(requestId));
+        }
+    });
+}
+export async function recordDeployment(root, input) {
+    await withHistory(root, (database) => {
+        const finishedAt = now();
+        database
+            .prepare(`INSERT INTO deployments (started_at, finished_at, duration_ms, target, name, slug,
+           visibility, url, status, pages_count, media_count, bytes, pages_created,
+           pages_updated, pages_deleted, error_message)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.startedAt, finishedAt, elapsed(input.startedAt, finishedAt), input.target, text(input.name), text(input.slug), text(input.visibility), text(input.url), input.status, input.pagesCount ?? null, input.mediaCount ?? null, input.bytes ?? null, input.pagesCreated ?? null, input.pagesUpdated ?? null, input.pagesDeleted ?? null, text(input.error));
+    });
+}
+/**
+ * Reconcile the page registry with what is on disk. Content hashes make edits
+ * that bypassed Doxloop visible instead of silently absent from history.
+ */
+export async function syncPageRegistry(root, project, requestId, authored) {
+    const database = await openHistory(root);
+    if (!database)
+        return;
+    try {
+        const resolved = project ?? (await loadProject(root));
+        const contentRoot = join(root, resolved.contentDir);
+        const absolutePaths = await loadPages(root, resolved);
+        const evidence = await readEvidenceMap(root);
+        const seen = new Set();
+        const timestamp = now();
+        for (const absolute of absolutePaths) {
+            const path = portable(relative(root, absolute));
+            seen.add(path);
+            const content = await readFile(absolute, 'utf8');
+            const hash = createHash('sha256').update(content).digest('hex');
+            const title = frontmatterTitle(content) ?? portable(relative(contentRoot, absolute));
+            const confidence = evidence?.pages[path]?.confidence;
+            const existing = database
+                .prepare('SELECT content_hash FROM pages WHERE path = ?')
+                .get(path);
+            if (existing?.content_hash === hash) {
+                database
+                    .prepare('UPDATE pages SET title = ?, evidence_confidence = ?, status = ? WHERE path = ?')
+                    .run(title, text(confidence), 'active', path);
+                // A registry refresh may have recorded this content first — the UI server
+                // backfills on startup, mid-run. The hash then matches even though this
+                // request is what wrote the page, so attribution has to be set explicitly.
+                if (requestId && authored?.has(path)) {
+                    database
+                        .prepare('UPDATE pages SET last_request_id = ? WHERE path = ?')
+                        .run(requestId, path);
+                }
+                continue;
+            }
+            database
+                .prepare(`INSERT INTO pages (path, title, created_at, updated_at, last_request_id, content_hash,
+             change_count, evidence_confidence, status)
+           VALUES (?, ?, ?, ?, ?, ?, 1, ?, 'active')
+           ON CONFLICT (path) DO UPDATE SET
+             title = excluded.title,
+             updated_at = excluded.updated_at,
+             last_request_id = excluded.last_request_id,
+             content_hash = excluded.content_hash,
+             change_count = pages.change_count + 1,
+             evidence_confidence = excluded.evidence_confidence,
+             status = 'active'`)
+                .run(path, title, timestamp, timestamp, text(requestId), hash, text(confidence));
+        }
+        const known = database.prepare("SELECT path FROM pages WHERE status = 'active'").all();
+        for (const row of known) {
+            if (seen.has(row.path))
+                continue;
+            database
+                .prepare("UPDATE pages SET status = 'deleted', updated_at = ?, last_request_id = ? WHERE path = ?")
+                .run(timestamp, text(requestId), row.path);
+        }
+    }
+    catch {
+        // A registry refresh is best effort; documentation commands must not fail on it.
+    }
+}
+export async function listRequests(root, limit = 20) {
+    const rows = await withHistory(root, (database) => database
+        .prepare(`SELECT id, created_at, finished_at, duration_ms, kind, trigger, request_text, agent,
+                model, status, pages_changed, lines_added, lines_removed, validation_errors,
+                validation_warnings, source_summary, error_message, input_tokens, output_tokens,
+                cache_read_tokens, cache_creation_tokens, cost_usd, agent_turns, agent_sessions,
+                max_context_tokens
+           FROM requests
+          ORDER BY created_at DESC
+          LIMIT ?`)
+        .all(limit));
+    return (rows ?? []).map(toRequest);
+}
+/**
+ * The pages each request touched, keyed by request id. Attached to a request
+ * list so the workspace can show what changed without a second round trip.
+ */
+export async function requestPages(root, requestIds) {
+    if (requestIds.length === 0)
+        return {};
+    const rows = await withHistory(root, (database) => database
+        .prepare(`SELECT request_id, path, title, change_kind, decision, lines_added, lines_removed
+         FROM request_pages
+          WHERE category = 'page'
+            AND request_id IN (${requestIds.map(() => '?').join(', ')})
+          ORDER BY path`)
+        .all(...requestIds));
+    const grouped = {};
+    for (const row of rows ?? []) {
+        const record = row;
+        const id = String(record.request_id);
+        const pages = grouped[id] ?? (grouped[id] = []);
+        pages.push({
+            path: String(record.path),
+            title: optional(record.title),
+            changeKind: String(record.change_kind),
+            decision: String(record.decision),
+            linesAdded: Number(record.lines_added ?? 0),
+            linesRemoved: Number(record.lines_removed ?? 0),
+        });
+    }
+    return grouped;
+}
+export async function pageHistory(root, path, limit = 20) {
+    const rows = await withHistory(root, (database) => database
+        .prepare(`SELECT rp.request_id, rp.path, rp.title, rp.change_kind, rp.decision, rp.decided_at,
+                rp.lines_added, rp.lines_removed, r.created_at, r.request_text, r.agent, r.status
+           FROM request_pages rp
+           JOIN requests r ON r.id = rp.request_id
+          WHERE rp.path = ?
+          ORDER BY r.created_at DESC
+          LIMIT ?`)
+        .all(path, limit));
+    return (rows ?? []).map((row) => {
+        const record = row;
+        return {
+            requestId: String(record.request_id),
+            path: String(record.path),
+            title: optional(record.title),
+            changeKind: String(record.change_kind),
+            decision: String(record.decision),
+            decidedAt: optional(record.decided_at),
+            linesAdded: Number(record.lines_added ?? 0),
+            linesRemoved: Number(record.lines_removed ?? 0),
+            requestedAt: String(record.created_at),
+            requestText: optional(record.request_text),
+            agent: optional(record.agent),
+            requestStatus: String(record.status),
+        };
+    });
+}
+export async function listPages(root) {
+    const rows = await withHistory(root, (database) => database
+        .prepare(`SELECT path, title, created_at, updated_at, change_count, evidence_confidence, status
+           FROM pages
+          ORDER BY updated_at DESC`)
+        .all());
+    return (rows ?? []).map((row) => {
+        const record = row;
+        return {
+            path: String(record.path),
+            title: optional(record.title),
+            createdAt: String(record.created_at),
+            updatedAt: String(record.updated_at),
+            changeCount: Number(record.change_count ?? 0),
+            evidenceConfidence: optional(record.evidence_confidence),
+            status: String(record.status),
+        };
+    });
+}
+export async function listDeployments(root, limit = 20) {
+    const rows = await withHistory(root, (database) => database
+        .prepare(`SELECT started_at, finished_at, duration_ms, target, name, slug, visibility, url, status,
+                pages_count, pages_created, pages_updated, pages_deleted, error_message
+           FROM deployments
+          ORDER BY started_at DESC
+          LIMIT ?`)
+        .all(limit));
+    return (rows ?? []).map((row) => {
+        const record = row;
+        return {
+            startedAt: String(record.started_at),
+            finishedAt: optional(record.finished_at),
+            durationMs: record.duration_ms === null ? undefined : Number(record.duration_ms),
+            target: String(record.target),
+            name: optional(record.name),
+            slug: optional(record.slug),
+            visibility: optional(record.visibility),
+            url: optional(record.url),
+            status: String(record.status),
+            pagesCount: record.pages_count === null ? undefined : Number(record.pages_count),
+            pagesCreated: record.pages_created === null ? undefined : Number(record.pages_created),
+            pagesUpdated: record.pages_updated === null ? undefined : Number(record.pages_updated),
+            pagesDeleted: record.pages_deleted === null ? undefined : Number(record.pages_deleted),
+            error: optional(record.error_message),
+        };
+    });
+}
+/**
+ * Import the JSON state written before history existed, so an upgraded project
+ * does not start empty. Runs once; the marker keeps later commands cheap.
+ */
+export async function backfillHistory(root, force = false) {
+    const database = await openHistory(root);
+    if (!database)
+        return 0;
+    try {
+        if (!force) {
+            // Version 2 re-imports retained run manifests once so older create runs
+            // that were incorrectly stored as updates receive the right action.
+            const marker = database.prepare("SELECT value FROM meta WHERE key = 'backfilled_at_v2'").get();
+            if (marker)
+                return 0;
+        }
+        let imported = 0;
+        const runsRoot = join(root, '.doxloop', 'runs');
+        if (await pathExists(runsRoot)) {
+            const { readdir } = await import('node:fs/promises');
+            const entries = await readdir(runsRoot, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const manifest = join(runsRoot, entry.name, 'run.json');
+                if (!(await pathExists(manifest)))
+                    continue;
+                try {
+                    const raw = JSON.parse(await readFile(manifest, 'utf8'));
+                    if ((raw.schemaVersion !== 1 && raw.schemaVersion !== 2) || !Array.isArray(raw.changes))
+                        continue;
+                    await recordSyncRun(root, raw, { runDir: join('.doxloop', 'runs', entry.name) });
+                    imported += 1;
+                }
+                catch {
+                    // An interrupted run directory is not history worth importing.
+                }
+            }
+        }
+        const syncState = join(root, '.doxloop', 'sync-state.json');
+        if (await pathExists(syncState)) {
+            try {
+                await recordSourceSyncs(root, JSON.parse(await readFile(syncState, 'utf8')));
+            }
+            catch {
+                // A malformed baseline file simply contributes nothing.
+            }
+        }
+        await syncPageRegistry(root);
+        database
+            .prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('backfilled_at_v2', ?)")
+            .run(now());
+        return imported;
+    }
+    catch {
+        return 0;
+    }
+}
+export function formatRequestHistory(requests) {
+    if (requests.length === 0) {
+        return 'No documentation history recorded yet.';
+    }
+    const lines = requests.map((request) => {
+        const when = request.createdAt.replace('T', ' ').slice(0, 16);
+        const changes = request.pagesChanged > 0
+            ? `${request.pagesChanged} page${request.pagesChanged === 1 ? '' : 's'} (+${request.linesAdded}/-${request.linesRemoved})`
+            : 'no changes';
+        const detail = request.requestText
+            ? `\n      "${truncate(request.requestText, 96)}"`
+            : request.sourceSummary
+                ? `\n      ${truncate(request.sourceSummary, 96)}`
+                : '';
+        return `  ${statusMark(request.status)} ${when}  ${request.kind.padEnd(6)} ${changes}${request.agent ? ` · ${request.agent}` : ''}${detail}`;
+    });
+    return `Documentation history (${requests.length} most recent)\n${lines.join('\n')}`;
+}
+function statusMark(status) {
+    if (status === 'applied')
+        return '✓';
+    if (status === 'rejected')
+        return '✗';
+    if (status === 'failed')
+        return '!';
+    if (status === 'running' || status === 'generating')
+        return '·';
+    return '○';
+}
+function toRequest(row) {
+    const record = row;
+    return {
+        id: String(record.id),
+        createdAt: String(record.created_at),
+        finishedAt: optional(record.finished_at),
+        durationMs: record.duration_ms === null ? undefined : Number(record.duration_ms),
+        kind: String(record.kind),
+        trigger: String(record.trigger),
+        requestText: optional(record.request_text),
+        agent: optional(record.agent),
+        model: optional(record.model),
+        status: String(record.status),
+        pagesChanged: Number(record.pages_changed ?? 0),
+        linesAdded: Number(record.lines_added ?? 0),
+        linesRemoved: Number(record.lines_removed ?? 0),
+        validationErrors: record.validation_errors === null ? undefined : Number(record.validation_errors),
+        validationWarnings: record.validation_warnings === null ? undefined : Number(record.validation_warnings),
+        sourceSummary: optional(record.source_summary),
+        error: optional(record.error_message),
+        usage: usageFromRow(record),
+    };
+}
+/** The eight usage columns in table order, all null when the agent reported no usage. */
+function usageColumns(usage) {
+    if (!usage)
+        return [null, null, null, null, null, null, null, null];
+    return [
+        usage.inputTokens,
+        usage.outputTokens,
+        usage.cacheReadTokens,
+        usage.cacheCreationTokens,
+        usage.costUsd ?? null,
+        usage.turns,
+        usage.sessions,
+        usage.maxContextTokens,
+    ];
+}
+/** Rebuild the usage from a request row; undefined when no usage was ever recorded for it. */
+function usageFromRow(record) {
+    const count = (value) => value === null || value === undefined ? undefined : Number(value);
+    const input = count(record.input_tokens);
+    const output = count(record.output_tokens);
+    const cacheRead = count(record.cache_read_tokens);
+    const cacheCreation = count(record.cache_creation_tokens);
+    if (input === undefined && output === undefined && cacheRead === undefined && cacheCreation === undefined) {
+        return undefined;
+    }
+    const cost = count(record.cost_usd);
+    return {
+        inputTokens: input ?? 0,
+        outputTokens: output ?? 0,
+        cacheReadTokens: cacheRead ?? 0,
+        cacheCreationTokens: cacheCreation ?? 0,
+        totalTokens: (input ?? 0) + (output ?? 0) + (cacheRead ?? 0) + (cacheCreation ?? 0),
+        ...(cost !== undefined ? { costUsd: cost } : {}),
+        turns: count(record.agent_turns) ?? 0,
+        sessions: count(record.agent_sessions) ?? 1,
+        maxContextTokens: count(record.max_context_tokens) ?? 0,
+        durationMs: count(record.duration_ms) ?? 0,
+    };
+}
+function changeDecision(change) {
+    const decided = change.hunks.filter((hunk) => hunk.acceptedAt || hunk.rejectedAt);
+    if (decided.length === 0)
+        return { state: 'pending', at: null };
+    const accepted = change.hunks.filter((hunk) => hunk.acceptedAt);
+    const at = decided
+        .map((hunk) => hunk.acceptedAt ?? hunk.rejectedAt ?? '')
+        .sort()
+        .at(-1) ?? null;
+    if (accepted.length === change.hunks.length)
+        return { state: 'accepted', at };
+    if (accepted.length === 0 && decided.length === change.hunks.length) {
+        return { state: 'rejected', at };
+    }
+    return { state: 'partial', at };
+}
+function lineCounts(changes) {
+    let added = 0;
+    let removed = 0;
+    for (const change of changes) {
+        for (const hunk of change.hunks) {
+            added += hunk.newLines.length;
+            removed += hunk.oldLines.length;
+        }
+    }
+    return { added, removed };
+}
+function frontmatterTitle(content) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+    if (!match)
+        return undefined;
+    const title = /^title:\s*(.+)$/m.exec(match[1] ?? '');
+    return title?.[1]?.trim().replace(/^["']|["']$/g, '') || undefined;
+}
+function elapsed(from, to) {
+    const start = Date.parse(from);
+    const end = Date.parse(to);
+    return Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, end - start) : null;
+}
+function truncate(value, length) {
+    const single = value.replace(/\s+/g, ' ').trim();
+    return single.length > length ? `${single.slice(0, length - 1)}…` : single;
+}
+function portable(path) {
+    return path.split('\\').join('/');
+}
+function optional(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function text(value) {
+    return value === undefined || value === '' ? null : value;
+}
+function now() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=history.js.map

package/dist/html-markdown.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Dependency-free HTML to Markdown conversion for crawled documentation pages.
+ *
+ * The converter is intentionally tolerant: documentation sites ship imperfect
+ * HTML, and the output feeds an agent that reads Markdown for context rather
+ * than a renderer that needs exact fidelity. Navigation chrome, scripts,
+ * styles, and hidden elements are dropped before conversion.
+ */
+export interface HtmlNode {
+    type: 'element' | 'text';
+    name?: string;
+    attributes: Record<string, string>;
+    children: HtmlNode[];
+    text?: string;
+}
+export interface HtmlDocumentSummary {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    generator?: string;
+    language?: string;
+    /** Absolute or relative link targets found in the main content and navigation. */
+    links: string[];
+    /** Image sources found in the main content. */
+    images: string[];
+    headings: Array<{
+        level: number;
+        text: string;
+    }>;
+    markdown: string;
+    /** Approximate word count of the converted main content. */
+    words: number;
+}
+export declare function decodeEntities(value: string): string;
+/** Parse tolerant HTML into a lightweight tree. */
+export declare function parseHtml(html: string): HtmlNode;
+/** Convert an HTML document into a Markdown summary of its main content. */
+export declare function summarizeHtmlDocument(html: string): HtmlDocumentSummary;
+/**
+ * The same summary for a page served as Markdown. Mintlify, GitBook, and
+ * other client-rendered docs sites send an empty HTML shell to a crawler but
+ * serve each page's source at `<page>.md` (and list those URLs in llms.txt).
+ * Their own "documentation index" preamble is dropped.
+ */
+export declare function summarizeMarkdownDocument(source: string): HtmlDocumentSummary;
+//# sourceMappingURL=html-markdown.d.ts.map