@ashikahmad/kanbanmd 0.0.0-stage → 2.0.0

package/core/read.js

@@ -0,0 +1,252 @@
+// Read-side queries over a board: compact, filterable, paginated. Pure: take the two file texts,
+// return plain JSON-able objects. The CLI and the MCP server are thin wrappers around these.
+//
+// Compactness is the point (an agent pays for every byte it reads):
+//   - a board listing returns summaries, never descriptions, subtasks or notes
+//   - empty fields are omitted (an absent key means "empty")
+//   - filtering and paging happen here, not in the agent's context
+//   - the archive is only read when asked for
+import { parseBoard, parseArchive, parseBacklog, orderedTasks } from './board.js';
+import { resolveBacklogFile } from './backlog-spec.js';
+import { BoardError, etagOf } from './text.js';
+import { Doc, blocksOf } from './patch.js';
+import { localToday, dayNumber } from './dates.js';
+import { getHousekeeping } from './housekeeping.js';
+import { indexTasks, blockersOf, blockedByThis } from './links.js';
+import { resolveHousekeeping } from './housekeeping-spec.js';
+
+export { localToday };
+
+export const TASK_VIEW_FIELDS = ['id', 'title', 'status', 'order', 'priority', 'category', 'assignees', 'tags', 'blockedBy', 'openBlockers', 'blocks', 'created', 'started', 'due',
+    'completed', 'description', 'subtasks', 'notes', 'extra', 'progress', 'etag'];
+const SUMMARY_FIELDS = ['id', 'title', 'status', 'priority', 'assignees', 'due', 'tags'];
+const MAX_LIMIT = 500, DEFAULT_LIMIT = 50, STATS_LIST_CAP = 20;
+
+const fail = (code, message, extra) => { throw new BoardError(code, message, extra); };
+const clean = (p) => p.replace(/[^\w\s]+/, '').trim();
+const empty = (v) => v === '' || v === null || v === undefined || (Array.isArray(v) && v.length === 0);
+const list = (v) => (v === undefined || v === null || v === '' ? [] : Array.isArray(v) ? v : String(v).split(','));
+const norm = (s) => String(s).trim().toLowerCase();
+// "@bob (Bob Ito)" -> "bob"
+const userKey = (u) => norm(u).replace(/^@/, '').replace(/[\s(].*$/, '');
+
+// Same rule as the page's deadline badge: 'overdue' (due before today), 'soon' (within 2 days,
+// today included), or null. A task with a Finished date is never flagged.
+export function dueStatus(task, today) {
+    if (!task.due || task.completed) return null;
+    const due = dayNumber(task.due.trim()), now = dayNumber(today);
+    if (due === null || now === null) return null;
+    const days = due - now;
+    return days < 0 ? 'overdue' : days <= 2 ? 'soon' : null;
+}
+
+// ---- loading ----------------------------------------------------------------------------------
+
+function load(ws) {
+    const bp = parseBoard(ws.board);
+    const ap = typeof ws.archive === 'string' ? parseArchive(ws.archive, bp.config.columns) : { tasks: [], formatVersion: null };
+    // The backlog file's tasks, when one is configured. `live` is every task still in play (board + backlog).
+    const bf = resolveBacklogFile(bp.config);
+    const kp = bf && typeof ws.backlog === 'string' ? parseBacklog(ws.backlog, bp.config.columns, bf.column) : { tasks: [] };
+    // Derived link fields, readable like any other: `openBlockers` (blockedBy ids that are not finished yet) and
+    // `blocks` (the tasks that name this one). Nothing of this is stored.
+    const byId = indexTasks({ board: bp.tasks, backlog: kp.tasks, archive: ap.tasks });
+    for (const { task } of byId.values()) {
+        task.openBlockers = blockersOf(task, byId, bp.config.columns).open.map((e) => e.task.id);
+        task.blocks = blockedByThis(task.id, byId).map((e) => e.task.id);
+    }
+    return { bp, ap, kp, bf, live: [...bp.tasks, ...kp.tasks], ws };
+}
+
+function etags(text, kind) {
+    if (typeof text !== 'string') return new Map();
+    const doc = new Doc(text);
+    return new Map(blocksOf(doc, kind).map((b) => [b.id, etagOf(doc.lines.slice(b.start, b.end).join(''))]));
+}
+
+// ---- field selection --------------------------------------------------------------------------
+
+// `fields` replaces the default set; id is always kept (and first).
+function fieldList(fields, fallback) {
+    const given = !(fields === undefined || fields === null || fields === '');
+    const want = given ? list(fields).map((f) => String(f).trim()).filter(Boolean) : fallback;
+    for (const f of want) if (!TASK_VIEW_FIELDS.includes(f)) fail('invalid_field', `Unknown field "${f}"`, { valid: TASK_VIEW_FIELDS });
+    return { fields: ['id', ...want.filter((f) => f !== 'id')], given };
+}
+
+function view(task, fields, etag, extra = {}) {
+    const out = {};
+    for (const f of fields) {
+        let v;
+        if (f === 'progress') v = task.subtasks.length ? `${task.subtasks.filter((s) => s.completed).length}/${task.subtasks.length}` : '';
+        else if (f === 'etag') v = etag;
+        else v = task[f];
+        if (f === 'id' || !empty(v)) out[f] = v;
+    }
+    return { ...out, ...extra };
+}
+
+// ---- filtering --------------------------------------------------------------------------------
+
+function makeFilter(q, config, today) {
+    const statuses = list(q.status).map((s) => String(s).trim()).filter(Boolean);
+    const ids = config.columns.map((c) => c.id);
+    for (const s of statuses) if (!ids.includes(s)) fail('unknown_status', `Unknown status "${s}"`, { valid: ids });
+    const assignees = list(q.assignee).map(userKey).filter(Boolean);
+    const tags = list(q.tag).map((t) => norm(t).replace(/^#/, '')).filter(Boolean);
+    const priorities = list(q.priority).map((p) => norm(clean(String(p)))).filter(Boolean);
+    const categories = list(q.category).map(norm).filter(Boolean);
+    const terms = norm(q.text || '').split(/\s+/).filter(Boolean);
+    let dueBefore = null;
+    if (q.dueBefore !== undefined && q.dueBefore !== null && q.dueBefore !== '') {
+        if (dayNumber(String(q.dueBefore)) === null) fail('invalid_date', 'dueBefore must be YYYY-MM-DD', { hint: `Got "${q.dueBefore}".` });
+        dueBefore = String(q.dueBefore);
+    }
+    return (t) => {
+        if (statuses.length && !statuses.includes(t.status)) return false;
+        if (assignees.length && !assignees.some((a) => t.assignees.some((u) => userKey(u) === a))) return false;
+        if (tags.length && !tags.every((g) => t.tags.some((x) => norm(x).replace(/^#/, '') === g))) return false;
+        if (priorities.length && !priorities.includes(norm(clean(t.priority)))) return false;
+        if (categories.length && !categories.includes(norm(t.category))) return false;
+        if (dueBefore && !(t.due && t.due < dueBefore)) return false;
+        if (q.overdue && dueStatus(t, today) !== 'overdue') return false;
+        if (terms.length) {
+            const hay = norm([t.id, t.title, t.description, t.notes, t.category, t.tags.join(' ')].join(' \n '));
+            if (!terms.every((w) => hay.includes(w))) return false;
+        }
+        return true;
+    };
+}
+
+function page(rows, q) {
+    const limit = q.limit === undefined || q.limit === null ? DEFAULT_LIMIT : Number(q.limit);
+    const offset = q.offset === undefined || q.offset === null ? 0 : Number(q.offset);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) fail('invalid_field', `limit must be 1 to ${MAX_LIMIT}`);
+    if (!Number.isInteger(offset) || offset < 0) fail('invalid_field', 'offset must be 0 or more');
+    const slice = rows.slice(offset, offset + limit);
+    return { slice, meta: { total: rows.length, returned: slice.length, offset, ...(offset + limit < rows.length && { nextOffset: offset + limit }) } };
+}
+
+// ---- queries ----------------------------------------------------------------------------------
+
+// Board listing: summaries in display order, filtered and paged.
+export function getBoard(ws, q = {}, { today = localToday() } = {}) {
+    if (q.backlog) return listFile(ws, q, 'backlog', { today });
+    const { bp, kp } = load(ws);
+    const { fields, given } = fieldList(q.fields, SUMMARY_FIELDS.concat('etag'));
+    const match = makeFilter(q, bp.config, today);
+    const tags = etags(ws.board, 'board');
+    const all = orderedTasks(bp.tasks);
+    const { slice, meta } = page(all.filter(match), q);
+    const counts = Object.fromEntries(bp.config.columns.map((c) => [c.id, 0]));
+    for (const t of [...bp.tasks, ...kp.tasks]) counts[t.status] = (counts[t.status] || 0) + 1; // the backlog file's tasks count too
+    return {
+        rev: etagOf(ws.board),
+        ...meta,
+        columns: bp.config.columns.map((c) => ({ id: c.id, name: c.name, count: counts[c.id] })),
+        tasks: slice.map((t) => view(t, fields, tags.get(t.id), !given && t.order !== null ? { order: t.order } : {})),
+    };
+}
+
+const normId = (id) => {
+    const m = /^(?:task-)?(\d+)$/i.exec(String(id).trim());
+    return m ? 'TASK-' + m[1].padStart(3, '0') : String(id).trim();
+};
+
+// One task in full (or just `fields`), from the board or the archive.
+export function getTask(ws, id, q = {}) {
+    const { bp, ap, kp } = load(ws);
+    const want = normId(id);
+    let task = bp.tasks.find((t) => t.id === want), kind = 'board';
+    if (!task) { task = kp.tasks.find((t) => t.id === want); kind = 'backlog'; }
+    if (!task) { task = ap.tasks.find((t) => t.id === want); kind = 'archive'; }
+    if (!task) fail('unknown_task', `No task ${id}`, { hint: 'Ids look like TASK-014. Use get_board with filters to find one.' });
+    const { fields } = fieldList(q.fields, TASK_VIEW_FIELDS.filter((f) => f !== 'progress'));
+    const tag = etags(kind === 'board' ? ws.board : kind === 'backlog' ? ws.backlog : ws.archive, kind).get(task.id);
+    return view(task, fields, tag, kind === 'archive' ? { archived: true } : kind === 'backlog' ? { backlog: true } : {});
+}
+
+export function getConfig(ws) {
+    const { bp, ap, kp, bf } = load(ws);
+    const c = bp.config;
+    return {
+        title: c.boardTitle,
+        rev: etagOf(ws.board),
+        formatVersion: bp.formatVersion,
+        ...(bp.formatVersion < 3 && { migrationNeeded: true, hint: 'Edits need format v3: run `kanbanmd migrate`.' }),
+        lastTaskId: c.lastTaskId,
+        columns: c.columns.map((x) => ({ id: x.id, name: x.name })),
+        categories: c.categories,
+        users: c.users,
+        priorities: c.priorities.map(clean),
+        tags: c.tags,
+        housekeeping: resolveHousekeeping(bp.config),
+        manualOrder: bp.tasks.some((t) => t.order !== null),
+        tasks: bp.tasks.length,
+        ...(bf && { backlogFile: { file: bf.file, column: bf.column, tasks: kp.tasks.length } }),
+        archived: ap.tasks.length,
+    };
+}
+
+// A side file's tasks (the archive or the backlog file): summaries, filtered and paged like the board.
+function listFile(ws, q, kind, { today = localToday() } = {}) {
+    const { bp, ap, kp, bf } = load(ws);
+    if (kind === 'backlog' && !bf) fail('no_backlog_file', 'This board has no backlog file', { hint: 'Its backlog tasks are on the board: filter get_board by status. To split them off: update_config backlogFile { enabled: true }.' });
+    const { fields } = fieldList(q.fields, SUMMARY_FIELDS.concat('etag'));
+    const match = makeFilter(q, bp.config, today);
+    const tags = etags(kind === 'backlog' ? ws.backlog : ws.archive, kind);
+    let rows = (kind === 'backlog' ? kp.tasks : ap.tasks).filter(match);
+    if (q.reverse) rows = [...rows].reverse();
+    const { slice, meta } = page(rows, q);
+    return { ...meta, tasks: slice.map((t) => view(t, fields, tags.get(t.id))) };
+}
+
+export function listArchive(ws, q = {}, { today = localToday() } = {}) {
+    return listFile(ws, q, 'archive', { today });
+}
+
+export function getStats(ws, { today = localToday() } = {}) {
+    const { bp, ap, kp, bf, live } = load(ws);
+    const tally = (keyOf) => {
+        const out = {};
+        for (const t of live) for (const k of [].concat(keyOf(t))) if (k) out[k] = (out[k] || 0) + 1;
+        return out;
+    };
+    const byStatus = Object.fromEntries(bp.config.columns.map((c) => [c.id, 0]));
+    for (const t of live) byStatus[t.status] = (byStatus[t.status] || 0) + 1;
+    // The lists are capped so the call stays small on a big board; the count says how many exist.
+    const flagged = (kind) => orderedTasks(live).filter((t) => dueStatus(t, today) === kind)
+        .sort((a, b) => a.due.localeCompare(b.due));
+    const row = (t) => ({ id: t.id, title: t.title, due: t.due, status: t.status });
+    const overdue = flagged('overdue'), soon = flagged('soon');
+    const hk = getHousekeeping(ws, { today });
+    return {
+        rev: etagOf(ws.board),
+        today,
+        total: live.length,
+        ...(bf && { backlog: kp.tasks.length }),
+        archived: ap.tasks.length,
+        byStatus,
+        byAssignee: tally((t) => t.assignees.map((a) => '@' + userKey(a))),
+        unassigned: live.filter((t) => !t.assignees.length).length,
+        byPriority: tally((t) => clean(t.priority)),
+        overdue: overdue.slice(0, STATS_LIST_CAP).map(row),
+        ...(overdue.length > STATS_LIST_CAP && { overdueTotal: overdue.length }),
+        dueSoon: soon.slice(0, STATS_LIST_CAP).map(row),
+        ...(soon.length > STATS_LIST_CAP && { dueSoonTotal: soon.length }),
+        ...(hk.suggestions.length && { housekeeping: hk.suggestions }),
+    };
+}
+
+// Entries of the activity log (see io/node-fs.js) after `since`, compacted. Edits made through the
+// page are not logged, so `rev` (changes with any edit) is the authoritative "did it change?".
+export function summarizeChanges(entries, { since, rev, limit = 200 } = {}) {
+    const rows = entries.filter((e) => !since || e.ts > since);
+    const cut = rows.slice(-limit);
+    return {
+        rev,
+        ...(rows.length > cut.length && { truncated: rows.length - cut.length }),
+        changes: cut.map((e) => ({ ts: e.ts, actor: e.actor, op: e.op, ...(e.id && { id: e.id }) })),
+        note: 'Page edits are not logged; compare rev to detect any change.',
+    };
+}

package/core/share.js

@@ -0,0 +1,41 @@
+// Rendering a task for sharing outside the board: plain text for people (chat, mail), and a trimmed
+// Markdown block (the file format itself) that a board can import. Pure. What is included is the
+// sender's choice: notes and assignees can be left out.
+import { generateTaskBlock } from './board.js';
+
+const lf = (s) => String(s).replace(/\r\n/g, '\n');
+
+// Readable anywhere: no Markdown syntax needed to make sense of it.
+export function taskToPlainText(task, columns = [], { notes = true, assignees = true } = {}) {
+    const column = columns.find((c) => c.id === task.status);
+    const meta = [
+        task.priority,
+        task.category,
+        column ? column.name : task.status,
+        task.due && `Due ${task.due}`,
+        assignees && task.assignees.length && `Assigned ${task.assignees.join(', ')}`,
+    ].filter(Boolean).join(' · ');
+    const out = [task.title];
+    if (meta) out.push(meta);
+    if (task.tags.length) out.push(task.tags.join(' '));
+    if (task.description) out.push('', lf(task.description));
+    if (task.subtasks.length) {
+        const done = task.subtasks.filter((s) => s.completed).length;
+        out.push('', `Subtasks (${done}/${task.subtasks.length}):`, ...task.subtasks.map((s) => `${s.completed ? '[x]' : '[ ]'} ${s.text}`));
+    }
+    if (notes && task.notes) out.push('', 'Notes:', lf(task.notes));
+    return out.join('\n') + '\n';
+}
+
+// The task as a board block (format v3), with the board-specific parts dropped: no manual order key and no
+// **Blocked by** (ids mean nothing outside the board they came from).
+export function taskToMarkdown(task, { notes = true, assignees = true } = {}) {
+    return lf(generateTaskBlock({
+        ...task,
+        assignees: assignees ? task.assignees : [],
+        notes: notes ? task.notes : '',
+        extra: notes ? task.extra : '',
+        order: null,
+        blockedBy: [],
+    })).trimEnd() + '\n';
+}

package/core/text.js

@@ -0,0 +1,145 @@
+// Text helpers shared by the patch layer: lines, hashing, deep equality, line diffs.
+// Pure: no I/O, no DOM.
+
+// Structured, fixable errors. `code` is stable and meant for programs; `message` and `hint` for
+// the human or agent reading it.
+export class BoardError extends Error {
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = 'BoardError';
+        this.code = code;
+        Object.assign(this, extra); // hint, valid, details, ...
+    }
+    toJSON() {
+        const { code, message, hint, valid, details } = this;
+        return { code, message, ...(hint && { hint }), ...(valid && { valid }), ...(details && { details }) };
+    }
+}
+
+// Split into lines, each keeping its own terminator ("\n" or "\r\n"); the last may have none.
+export function splitLines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) || [];
+}
+
+export const stripEol = (line) => line.replace(/\r?\n$/, '');
+export const lineEol = (line) => (/\r?\n$/.exec(line) || [''])[0];
+
+// The file's line ending, taken from its first newline.
+export function detectEol(text) {
+    const i = text.indexOf('\n');
+    return i > 0 && text[i - 1] === '\r' ? '\r\n' : '\n';
+}
+
+export const toEol = (text, eol) => text.replace(/\r?\n/g, eol);
+
+// 53-bit string hash (cyrb53). Not cryptographic: used for change detection (etags), not security.
+export function hash53(str, seed = 0) {
+    let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0; i < str.length; i++) {
+        const ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+export const etagOf = (text) => hash53(text).toString(36);
+
+export function deepEqual(a, b) {
+    if (a === b) return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+}
+
+// First path at which two JSON-like values differ, for error messages.
+export function firstDifference(a, b, path = '') {
+    if (deepEqual(a, b)) return null;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) {
+        return { path, expected: a, actual: b };
+    }
+    for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+        const d = firstDifference(a[k], b[k], `${path}/${k}`);
+        if (d) return d;
+    }
+    return null;
+}
+
+// Line diff as hunks [{ at, del: [lines], add: [lines] }] where `at` is the index in `a`.
+// Common prefix/suffix are trimmed first, then an LCS runs on the middle (capped, so a huge
+// rewrite degrades to a single hunk instead of an O(n*m) blow-up).
+export function diffLines(aText, bText) {
+    const a = splitLines(aText), b = splitLines(bText);
+    let p = 0;
+    while (p < a.length && p < b.length && a[p] === b[p]) p++;
+    let s = 0;
+    while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
+    const am = a.slice(p, a.length - s), bm = b.slice(p, b.length - s);
+    if (!am.length && !bm.length) return [];
+    if (am.length * bm.length > 4_000_000) return [{ at: p, del: am, add: bm }];
+
+    const n = am.length, m = bm.length;
+    const L = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            L[i][j] = am[i] === bm[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+        }
+    }
+    const hunks = [];
+    let i = 0, j = 0, cur = null;
+    const flush = () => { if (cur) { hunks.push(cur); cur = null; } };
+    while (i < n || j < m) {
+        if (i < n && j < m && am[i] === bm[j]) { flush(); i++; j++; continue; }
+        if (!cur) cur = { at: p + i, del: [], add: [] };
+        if (j < m && (i === n || L[i][j + 1] >= L[i + 1][j])) cur.add.push(bm[j++]);
+        else cur.del.push(am[i++]);
+    }
+    flush();
+    return hunks;
+}
+
+// Summary used by tests and dry runs.
+export function diffStats(aText, bText) {
+    const hunks = diffLines(aText, bText);
+    return {
+        hunks: hunks.length,
+        removed: hunks.reduce((n, h) => n + h.del.length, 0),
+        added: hunks.reduce((n, h) => n + h.add.length, 0),
+        firstLine: hunks.length ? hunks[0].at : null,
+        lastLine: hunks.length ? Math.max(...hunks.map((h) => h.at + h.del.length)) : null,
+    };
+}
+
+export function unifiedDiff(aText, bText, name = 'file', context = 3) {
+    const a = splitLines(aText);
+    const hunks = diffLines(aText, bText);
+    if (!hunks.length) return '';
+    const out = [`--- a/${name}`, `+++ b/${name}`];
+    // Merge hunks whose context windows touch.
+    const groups = [];
+    for (const h of hunks) {
+        const last = groups[groups.length - 1];
+        if (last && h.at - (last.at + last.span) <= context * 2) { last.hunks.push(h); last.span = h.at + h.del.length - last.at; }
+        else groups.push({ at: h.at, span: h.del.length, hunks: [h] });
+    }
+    let delta = 0;
+    for (const g of groups) {
+        const start = Math.max(0, g.at - context);
+        const end = Math.min(a.length, g.at + g.span + context);
+        const body = [];
+        let pos = start, added = 0, removed = 0;
+        for (const h of g.hunks) {
+            for (; pos < h.at; pos++) body.push(' ' + stripEol(a[pos]));
+            for (const l of h.del) { body.push('-' + stripEol(l)); removed++; pos++; }
+            for (const l of h.add) { body.push('+' + stripEol(l)); added++; }
+        }
+        for (; pos < end; pos++) body.push(' ' + stripEol(a[pos]));
+        const aLen = end - start, bLen = aLen - removed + added;
+        out.push(`@@ -${start + 1},${aLen} +${start + 1 + delta},${bLen} @@`, ...body);
+        delta += added - removed;
+    }
+    return out.join('\n') + '\n';
+}

package/io/node-fs.js

@@ -0,0 +1,188 @@
+// Node file port: reads the two board files and applies an op to them safely.
+//
+// Writers that go through this module (CLI, MCP server, any number of processes) take turns via
+// an exclusive lock directory (mkdir is atomic), so their read-modify-write cycles never
+// interleave. The page cannot take that lock, so it is covered by a second layer: just before the
+// rename, every file that was read is re-read and its hash compared, and if anything moved the
+// op is recomputed from the fresh content. Each file is replaced atomically (temp file in the same
+// directory, fsync, rename), so a reader never sees a half-written file. The only remaining gap is
+// a foreign writer landing between that last check and the rename (microseconds); the per-task
+// etag (ifMatch) is the tool for callers that need certainty beyond that.
+import { promises as fs } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { join, basename, dirname } from 'node:path';
+import { applyOps } from '../core/changes.js';
+import { parseBoard } from '../core/board.js';
+import { migrateBoardText, migrateArchiveText } from '../core/migrate.js';
+import { backlogFileNameOf } from '../core/backlog-spec.js';
+import { BoardError, unifiedDiff } from '../core/text.js';
+
+const BOARD = 'kanban.md', ARCHIVE = 'archive.md', ACTIVITY = '.kanban-activity.jsonl', LOCK = '.kanban.lock';
+const sha = (s) => (s === null ? '-' : createHash('sha1').update(s).digest('hex'));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function readOptional(path) {
+    try { return await fs.readFile(path, 'utf8'); }
+    catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
+export async function readWorkspace(dir) {
+    const board = await readOptional(join(dir, BOARD));
+    if (board === null) throw new BoardError('no_board', `No ${BOARD} in ${dir}`, { hint: 'Pass --dir pointing at the project folder.' });
+    // The backlog file: the one the board declares, else a default-named file if one happens to exist (the
+    // ops need to see it to refuse to overwrite it).
+    return { board, archive: await readOptional(join(dir, ARCHIVE)), backlog: await readOptional(join(dir, backlogFileNameOf(board))) };
+}
+
+// Write `text` to a temp file next to `path` and return handles to commit (rename) or abort it.
+async function stage(path, text) {
+    const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+    const fh = await fs.open(tmp, 'w');
+    try {
+        await fh.writeFile(text, 'utf8');
+        await fh.sync();
+    } catch (e) {
+        await fh.close();
+        await fs.rm(tmp, { force: true });
+        throw e;
+    }
+    await fh.close();
+    return { tmp, path, abort: () => fs.rm(tmp, { force: true }), commit: () => fs.rename(tmp, path) };
+}
+
+// Exclusive, cross-process lock on a project folder. A lock older than `staleMs` is assumed
+// to belong to a crashed process and is broken.
+async function withLock(dir, fn, { timeoutMs = 15000, staleMs = 10000 } = {}) {
+    const lock = join(dir, LOCK);
+    const started = Date.now();
+    for (;;) {
+        try { await fs.mkdir(lock); break; }
+        catch (e) {
+            if (e.code !== 'EEXIST') throw e;
+            try {
+                const { mtimeMs } = await fs.stat(lock);
+                if (Date.now() - mtimeMs > staleMs) { await fs.rm(lock, { recursive: true, force: true }); continue; }
+            } catch { /* released between the mkdir and the stat: just retry */ }
+            if (Date.now() - started > timeoutMs) {
+                throw new BoardError('busy', 'Another process is writing to this board', { hint: 'Retry the call.' });
+            }
+            await sleep(2 + Math.random() * 8);
+        }
+    }
+    try { return await fn(); }
+    finally { await fs.rm(lock, { recursive: true, force: true }); }
+}
+
+async function logActivity(dir, entry) {
+    const path = join(dir, ACTIVITY);
+    try {
+        await fs.appendFile(path, JSON.stringify(entry) + '\n');
+        const { size } = await fs.stat(path);
+        if (size > 256 * 1024) { // keep the log bounded
+            const lines = (await fs.readFile(path, 'utf8')).trimEnd().split('\n');
+            await fs.writeFile(path, lines.slice(-1000).join('\n') + '\n');
+        }
+    } catch { /* the activity log is best effort and must never fail a write */ }
+}
+
+// The activity log as parsed entries (oldest first); [] when there is none.
+export async function readActivity(dir) {
+    const text = await readOptional(join(dir, ACTIVITY));
+    if (!text) return [];
+    return text.split('\n').filter(Boolean).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } });
+}
+
+// Apply one op, or an array of ops applied in order as one edit, to the project in `dir`.
+// Returns { result, files, diff? } for one op, { results, files, diff? } for an array.
+export async function mutate(dir, opOrOps, { dryRun = false, retries = 8, actor = 'cli', today, hooks = {}, lockTimeoutMs, lockStaleMs } = {}) {
+    const ops = Array.isArray(opOrOps) ? opOrOps : [opOrOps];
+    const shape = (results) => (Array.isArray(opOrOps) ? { results } : { result: results[0] });
+    const attempt = async () => {
+        const ws = await readWorkspace(dir);
+        const backlogName = backlogFileNameOf(ws.board);
+        const out = applyOps(ws, ops, { today });
+        // every file this edit read or will write: if any of them changes before the rename, start over
+        const watched = [...new Set([BOARD, ARCHIVE, backlogName, ...out.files.map((f) => f.name)])];
+        const hashes = {};
+        for (const name of watched) hashes[name] = sha(name === BOARD ? ws.board : name === ARCHIVE ? ws.archive : name === backlogName ? ws.backlog : await readOptional(join(dir, name)));
+        if (hooks.afterCompute) await hooks.afterCompute(); // test seam: lets a test interleave a foreign write
+        const names = out.files.map((f) => f.name);
+
+        if (dryRun) {
+            const diff = out.files.map((f) => unifiedDiff(ws[f.kind] || '', f.text, f.name)).join('');
+            return { done: { ...shape(out.results), files: names, diff, dryRun: true } };
+        }
+        if (!out.files.length) return { done: { ...shape(out.results), files: [] } };
+
+        const staged = [];
+        try {
+            for (const f of out.files) staged.push(await stage(join(dir, f.name), f.text));
+            // Last check before the renames: did a writer outside the lock (the page) move anything?
+            let moved = false;
+            for (const name of watched) if (sha(await readOptional(join(dir, name))) !== hashes[name]) moved = true;
+            if (moved) {
+                await Promise.all(staged.map((s) => s.abort()));
+                return { retry: true };
+            }
+            for (const s of staged) {
+                if (hooks.beforeRename) await hooks.beforeRename(s.path);
+                await s.commit();
+            }
+        } catch (e) {
+            await Promise.all(staged.map((s) => s.abort()));
+            throw e;
+        }
+        const ts = new Date().toISOString();
+        for (let i = 0; i < ops.length; i++) await logActivity(dir, { ts, actor, op: ops[i].type, id: out.results[i].id || null, files: names });
+        return { done: { ...shape(out.results), files: names } };
+    };
+
+    const run = async () => {
+        for (let i = 0; i <= retries; i++) {
+            const r = await attempt();
+            if (r.done) return r.done;
+            await sleep(2 + Math.random() * 10 * (i + 1));
+        }
+        throw new BoardError('busy', 'The board kept changing underneath this edit; gave up after several retries', { hint: 'Retry the call.' });
+    };
+    return dryRun ? run() : withLock(dir, run, { timeoutMs: lockTimeoutMs, staleMs: lockStaleMs });
+}
+
+// Migrate a project folder to the current format. Every file that changes is backed up first
+// (kanban.v<N>-backup.md; an existing backup is never overwritten), and nothing is written unless
+// the core verified that the new text reads back identically. Returns { changed, files, backups, diff? }.
+export async function migrateProject(dir, { dryRun = false, actor = 'cli', lockTimeoutMs, lockStaleMs } = {}) {
+    const run = async () => {
+        const ws = await readWorkspace(dir);
+        const board = migrateBoardText(ws.board);
+        const columns = parseBoard(board.text).config.columns;
+        const archive = ws.archive === null ? { changed: false } : migrateArchiveText(ws.archive, columns);
+        const steps = [
+            board.changed && { name: BOARD, from: board.from, before: ws.board, text: board.text },
+            archive.changed && { name: ARCHIVE, from: archive.from, before: ws.archive, text: archive.text },
+        ].filter(Boolean);
+        if (!steps.length) return { changed: false, files: [], backups: [] };
+        const files = steps.map((x) => x.name);
+        if (dryRun) return { changed: true, files, from: Object.fromEntries(steps.map((x) => [x.name, x.from])), dryRun: true, diff: steps.map((x) => unifiedDiff(x.before, x.text, x.name)).join('') };
+
+        const backups = [];
+        for (const x of steps) {
+            let name = x.name.replace(/\.md$/, `.v${x.from}-backup.md`);
+            if (await readOptional(join(dir, name)) !== null) name = name.replace(/\.md$/, `.${Date.now()}.md`);
+            const st = await stage(join(dir, name), x.before);
+            await st.commit();
+            backups.push(name);
+        }
+        const staged = [];
+        try {
+            for (const x of steps) staged.push(await stage(join(dir, x.name), x.text));
+            for (const st of staged) await st.commit();
+        } catch (e) {
+            await Promise.all(staged.map((st) => st.abort()));
+            throw e;
+        }
+        await logActivity(dir, { ts: new Date().toISOString(), actor, op: 'migrate', id: null, files });
+        return { changed: true, files, backups, from: Object.fromEntries(steps.map((x) => [x.name, x.from])) };
+    };
+    return withLock(dir, run, { timeoutMs: lockTimeoutMs, staleMs: lockStaleMs });
+}