@ashikahmad/kanbanmd 0.0.0-stage → 2.0.0

package/core/changes.js

@@ -0,0 +1,130 @@
+// Turn "the page's state differs from the last saved state" into a list of ops, and apply a list of
+// ops to a pair of file texts. This is what lets the page keep mutating its in-memory arrays (and
+// its ~16 save call sites) while the file is only ever changed by minimal, verified patches that are
+// applied to the file's CURRENT content, so edits made elsewhere in the meantime survive.
+//
+// State shape (the page's own): { config, tasks, archive, backlog? }  (see parseBoard / parseArchive;
+// backlog is the optional backlog file's tasks). With a backlog file a task's status decides which file
+// it lives in, so moving a task into or out of the backlog is just a status update.
+// Not expressible as ops (reported in `unsupported`, caller falls back): changes to preserved
+// sections (`extra`), the board title, or a task that appears directly in the archive.
+import { applyOp, orderKinds } from './ops.js';
+import { deepEqual } from './text.js';
+
+const TASK_KEYS = ['title', 'status', 'order', 'priority', 'category', 'assignees', 'tags', 'blockedBy', 'created', 'started', 'due', 'completed', 'description', 'subtasks', 'notes'];
+const LISTS = ['categories', 'users', 'priorities', 'tags'];
+const byId = (tasks) => new Map(tasks.map((t) => [t.id, t]));
+
+export function diffToOps(base, next) {
+    const ops = [], unsupported = [];
+    // "live" = the board plus the backlog file: the two files a task moves between by changing its status
+    const bB = byId([...base.tasks, ...(base.backlog || [])]), bA = byId(base.archive);
+    const nB = byId([...next.tasks, ...(next.backlog || [])]), nA = byId(next.archive);
+    const baseColumnIds = base.config.columns.map((c) => c.id);
+    const nextColumnIds = next.config.columns.map((c) => c.id);
+
+    // 1. deleted
+    for (const id of [...bB.keys(), ...bA.keys()]) if (!nB.has(id) && !nA.has(id)) ops.push({ type: 'deleteTask', id });
+
+    // 2. archived / restored
+    for (const id of bB.keys()) if (nA.has(id)) ops.push({ type: 'archiveTask', id });
+    for (const id of bA.keys()) if (nB.has(id)) ops.push({ type: 'restoreTask', id });
+
+    // 3. columns. Tasks whose column id was renamed or removed are re-homed by `reassign`, so the
+    //    per-task status updates for them are skipped below.
+    const reassign = {};
+    const colChanged = !deepEqual(base.config.columns, next.config.columns);
+    const rehomed = new Set();
+    if (colChanged) {
+        for (const old of baseColumnIds.filter((id) => !nextColumnIds.includes(id))) {
+            // Where did the tasks of this removed column end up? Renamed column: they followed it. Deleted
+            // column: the page leaves a board task with the old id, which on disk means "first column"
+            // (how an unknown status reads back); an archived task is left alone.
+            const dest = new Map(); // destination -> task ids
+            const note = (id, to) => dest.set(to, [...(dest.get(to) || []), id]);
+            for (const [id, bt] of bB) {
+                if (bt.status !== old) continue;
+                const nt = nB.get(id) || nA.get(id);
+                if (!nt) continue;
+                if (nA.has(id) && !nextColumnIds.includes(nt.status)) continue; // archived with an orphan status: left alone, like the rest of the archive
+                note(id, nextColumnIds.includes(nt.status) ? nt.status : nextColumnIds[0]);
+            }
+            for (const [id, bt] of bA) {
+                if (bt.status !== old) continue;
+                const nt = nA.get(id) || nB.get(id);
+                if (nt && nextColumnIds.includes(nt.status)) note(id, nt.status);
+            }
+            if (!dest.size) continue;
+            // The most common destination becomes the column-wide reassign; any task that went elsewhere
+            // is moved by its own updateTask afterwards.
+            const [to, ids] = [...dest.entries()].sort((a, b) => b[1].length - a[1].length)[0];
+            reassign[old] = to;
+            for (const id of ids) rehomed.add(id);
+        }
+        ops.push({ type: 'setColumns', columns: next.config.columns.map((c) => ({ name: c.name, id: c.id })), ...(Object.keys(reassign).length && { reassign }) });
+    }
+
+    // 4. field changes on tasks present in both
+    const updatesFor = (bt, nt) => {
+        const set = {};
+        for (const k of TASK_KEYS) {
+            if (k === 'status' && rehomed.has(nt.id)) continue;
+            if (!deepEqual(bt[k], nt[k])) set[k] = k === 'order' && nt[k] === null ? '' : nt[k];
+        }
+        if (!deepEqual(bt.extra, nt.extra)) unsupported.push(`${nt.id}: preserved sections (Links/Review/Dependencies) cannot be edited`);
+        return set;
+    };
+    for (const [id, nt] of [...nB, ...nA]) {
+        const bt = bB.get(id) || bA.get(id);
+        if (!bt) continue;
+        let before = bt;
+        if (bA.has(id) && nB.has(id)) { // restored: the restore op itself applies the page's fallback status
+            const fallback = next.config.columns.some((c) => c.id === bt.status) ? bt.status : next.config.columns[0].id;
+            before = { ...bt, status: fallback };
+        }
+        const set = updatesFor(before, nt);
+        if (Object.keys(set).length) ops.push({ type: 'updateTask', id, set });
+    }
+
+    // 5. created (appended last, as the page appends)
+    for (const [id, nt] of nB) {
+        if (bB.has(id) || bA.has(id)) continue;
+        const task = {};
+        for (const k of TASK_KEYS) {
+            const v = nt[k];
+            if (k === 'order' ? v !== null : !(v === '' || (Array.isArray(v) && !v.length))) task[k] = v;
+        }
+        ops.push({ type: 'createTask', task, clientId: id });
+    }
+    for (const id of nA.keys()) if (!bA.has(id) && !bB.has(id)) unsupported.push(`${id}: a task appeared directly in the archive`);
+
+    // 6. config lists
+    for (const name of LISTS) {
+        if (!deepEqual(base.config[name], next.config[name])) ops.push({ type: 'setConfigList', name, values: next.config[name] });
+    }
+    if (base.config.boardTitle !== next.config.boardTitle) unsupported.push('the board title changed');
+    if (!deepEqual(base.config.housekeeping, next.config.housekeeping)) unsupported.push('the housekeeping settings changed');
+
+    return { ops, unsupported };
+}
+
+// Apply ops in order to { board, archive, backlog } texts. Returns the final texts, the files to write (only
+// those that really differ from the start, destinations before sources) and each op's result. Stops at the
+// first failing op (its BoardError carries `opIndex`).
+export function applyOps(ws, ops, options = {}) {
+    const start = { board: ws.board, archive: ws.archive ?? null, backlog: ws.backlog ?? null };
+    let cur = { ...start };
+    const results = [], moves = [], names = {};
+    for (let i = 0; i < ops.length; i++) {
+        const { clientId, ...op } = ops[i];
+        let out;
+        try { out = applyOp(cur, op, options); }
+        catch (e) { e.opIndex = i; throw e; }
+        for (const f of out.files) names[f.kind] = f.name;
+        moves.push(...out.moves);
+        cur = { board: out.board, archive: out.archive, backlog: out.backlog };
+        results.push({ ...out.result, ...(clientId && { clientId }) });
+    }
+    const kinds = orderKinds(Object.keys(names).filter((k) => cur[k] !== start[k]), moves);
+    return { ...cur, results, files: kinds.map((k) => ({ name: names[k], kind: k, text: cur[k] })) };
+}

package/core/dates.js

@@ -0,0 +1,14 @@
+// Date helpers on YYYY-MM-DD strings. Pure.
+export function localToday() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// Days since 1970-01-01 for a real calendar date, else null (JS would roll 2026-02-31 over; we do not).
+export function dayNumber(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso || '');
+    if (!m) return null;
+    const t = Date.UTC(+m[1], +m[2] - 1, +m[3]);
+    const d = new Date(t);
+    return d.getUTCFullYear() === +m[1] && d.getUTCMonth() === +m[2] - 1 && d.getUTCDate() === +m[3] ? t / 86400000 : null;
+}

package/core/housekeeping-spec.js

@@ -0,0 +1,62 @@
+// The optional "**Housekeeping**:" config line and the policy it resolves to. Pure, no imports.
+//
+//   **Housekeeping**: done=done after=30d | backlog=backlog after=90d | max=200
+//   **Housekeeping**: off
+//
+// Absent line = the defaults below (nudges are ON by default; they only ever suggest, never act).
+// Only what is written in the line is stored in config.housekeeping; resolveHousekeeping fills in
+// the rest, and guesses the done / backlog columns from their names when none is configured.
+export const HOUSEKEEPING_DEFAULTS = { doneAfterDays: 30, backlogAfterDays: 90, max: 200, backlogFileAbove: 100 };
+
+const DONE_NAME = /^(done|completed?|closed|finished|released|shipped)$/i;
+const BACKLOG_NAME = /backlog/i;
+const plain = (s) => s.replace(/[^\w\s-]/g, '').trim();
+
+// "done=done after=30d | backlog=backlog after=90d | max=200" | "off"  ->  { enabled, done?, backlog?, max? } | null
+export function parseHousekeepingSpec(text) {
+    if (text === undefined || text === null) return null;
+    const out = { enabled: true };
+    for (const seg of String(text).split('|').map((s) => s.trim()).filter(Boolean)) {
+        if (/^off$/i.test(seg)) return { enabled: false };
+        // a segment is "<name>[=<value>] [after=<N>d]": done=done after=30d, backlog after=90d, max=200
+        const [head, ...rest] = seg.split(/\s+/);
+        const [name, value] = head.split('=');
+        const kv = Object.fromEntries(rest.map((tok) => tok.split('=')).filter((p) => p.length === 2).map(([k, v]) => [k.toLowerCase(), v]));
+        const days = kv.after !== undefined && /^\d+d?$/i.test(kv.after) ? parseInt(kv.after, 10) : undefined;
+        const key = name.toLowerCase();
+        if (key === 'done' || key === 'backlog') out[key] = { ...(value && { column: value }), ...(days !== undefined && { afterDays: days }) };
+        else if (key === 'max' && /^\d+$/.test(value || '')) out.max = parseInt(value, 10);
+    }
+    return out;
+}
+
+export function formatHousekeepingSpec(h) {
+    if (!h) return '';
+    if (h.enabled === false) return 'off';
+    const parts = [];
+    const side = (name, v) => { if (v) parts.push([`${name}=${v.column || ''}`.replace(/=$/, ''), v.afterDays !== undefined ? `after=${v.afterDays}d` : ''].filter(Boolean).join(' ')); };
+    side('done', h.done);
+    side('backlog', h.backlog);
+    if (h.max !== undefined) parts.push(`max=${h.max}`);
+    return parts.join(' | ') || 'on';
+}
+
+// Canonical stored form of a user-supplied object (what parse(format(x)) gives back).
+export function normalizeHousekeeping(h) {
+    return parseHousekeepingSpec(formatHousekeepingSpec(h)) || null;
+}
+
+// The full policy for a board: explicit values, else defaults; done / backlog columns guessed by name.
+export function resolveHousekeeping(config) {
+    const h = config.housekeeping || { enabled: true };
+    const cols = config.columns || [];
+    const find = (re) => (cols.find((c) => re.test(c.id) || re.test(plain(c.name))) || {}).id || null;
+    const known = (id) => (id && cols.some((c) => c.id === id) ? id : null);
+    return {
+        enabled: h.enabled !== false,
+        done: { column: known(h.done && h.done.column) || (h.done && h.done.column ? null : find(DONE_NAME)), afterDays: (h.done && h.done.afterDays) ?? HOUSEKEEPING_DEFAULTS.doneAfterDays },
+        backlog: { column: known(h.backlog && h.backlog.column) || (h.backlog && h.backlog.column ? null : find(BACKLOG_NAME)), afterDays: (h.backlog && h.backlog.afterDays) ?? HOUSEKEEPING_DEFAULTS.backlogAfterDays },
+        max: h.max ?? HOUSEKEEPING_DEFAULTS.max,
+        backlogFileAbove: HOUSEKEEPING_DEFAULTS.backlogFileAbove,
+    };
+}

package/core/housekeeping.js

@@ -0,0 +1,81 @@
+// Housekeeping: which tasks a board would be better off without, per its policy (see
+// housekeeping-spec.js). Suggestions only: nothing here changes a file. Acting on one is an
+// ordinary op (archiveTasks), so it is one verified diff and can be previewed with dry_run.
+import { parseBoard, parseBacklog } from './board.js';
+import { resolveBacklogFile } from './backlog-spec.js';
+import { resolveHousekeeping } from './housekeeping-spec.js';
+import { dayNumber, localToday } from './dates.js';
+
+const LIST_CAP = 20;
+
+// The board plus, when a backlog file is configured, its tasks: housekeeping is about all live tasks.
+function loadLive(ws) {
+    const bp = parseBoard(ws.board);
+    const bf = resolveBacklogFile(bp.config);
+    const store = bf && typeof ws.backlog === 'string' ? parseBacklog(ws.backlog, bp.config.columns, bf.column).tasks : [];
+    return { bp, bf, live: [...bp.tasks, ...store] };
+}
+
+function candidates(bp, live, policy, today) {
+    const now = dayNumber(today);
+    const age = (iso) => { const d = dayNumber(iso); return d === null || now === null ? null : now - d; };
+    const done = policy.done.column ? bp.tasks.filter((t) => t.status === policy.done.column) : [];
+    const doneOld = done.filter((t) => t.completed && age(t.completed) >= policy.done.afterDays)
+        .sort((a, b) => a.completed.localeCompare(b.completed));
+    const backlog = policy.backlog.column ? live.filter((t) => t.status === policy.backlog.column) : [];
+    const backlogStale = backlog.filter((t) => {
+        const created = t.created ? age(t.created) : null;
+        const overdue = t.due && !t.completed ? age(t.due) : null; // how long past its due date, if it is
+        return (created !== null && created >= policy.backlog.afterDays) || (overdue !== null && overdue >= policy.backlog.afterDays);
+    }).sort((a, b) => (a.created || '').localeCompare(b.created || ''));
+    return { done, doneOld, backlog, backlogStale };
+}
+
+// { policy, suggestions: [{ kind, count, ..., ids (capped), message }] }; suggestions is empty when
+// nothing is over a threshold (so it costs nothing to include).
+export function getHousekeeping(ws, { today = localToday() } = {}) {
+    const { bp, bf, live } = loadLive(ws);
+    const policy = resolveHousekeeping(bp.config);
+    const out = { policy, suggestions: [] };
+    if (!policy.enabled) return out;
+    const c = candidates(bp, live, policy, today);
+    const capped = (tasks) => tasks.slice(0, LIST_CAP).map((t) => t.id);
+
+    if (c.doneOld.length) {
+        const undated = c.done.filter((t) => !t.completed).length;
+        out.suggestions.push({
+            kind: 'archive_done', count: c.doneOld.length, afterDays: policy.done.afterDays, ids: capped(c.doneOld), ...(undated && { undated }),
+            message: `${c.doneOld.length} task(s) in "${policy.done.column}" were finished ${policy.done.afterDays}+ days ago: archive them to keep the board small.`,
+        });
+    }
+    if (c.backlogStale.length) {
+        out.suggestions.push({
+            kind: 'stale_backlog', count: c.backlogStale.length, afterDays: policy.backlog.afterDays, ids: capped(c.backlogStale),
+            message: `${c.backlogStale.length} task(s) in "${policy.backlog.column}" are ${policy.backlog.afterDays}+ days old: review, archive or delete them.`,
+        });
+    }
+    // A big backlog is the one thing a separate file fixes: suggest it (once it is on, there is nothing to suggest).
+    if (!bf && c.backlog.length > policy.backlogFileAbove) {
+        out.suggestions.push({ kind: 'backlog_large', count: c.backlog.length, max: policy.backlogFileAbove, column: policy.backlog.column, message: `${c.backlog.length} tasks in "${policy.backlog.column}" (limit ${policy.backlogFileAbove}): move them to their own backlog file to keep the board small.` });
+    }
+    if (bp.tasks.length > policy.max) {
+        out.suggestions.push({ kind: 'board_large', count: bp.tasks.length, max: policy.max, message: `${bp.tasks.length} tasks on the board (limit ${policy.max}): archive what is finished.` });
+    }
+    return out;
+}
+
+// Every id the stale-backlog nudge flags (the page highlights those cards).
+export function staleBacklogIds(ws, { today = localToday() } = {}) {
+    const { bp, live } = loadLive(ws);
+    const policy = resolveHousekeeping(bp.config);
+    if (!policy.enabled) return [];
+    return candidates(bp, live, policy, today).backlogStale.map((t) => t.id);
+}
+
+// Every id the "archive done" nudge would archive (the suggestion's own list is capped for display).
+export function archiveCandidates(ws, { today = localToday() } = {}) {
+    const { bp, live } = loadLive(ws);
+    const policy = resolveHousekeeping(bp.config);
+    if (!policy.enabled) return [];
+    return candidates(bp, live, policy, today).doneOld.map((t) => t.id);
+}

package/core/index.js

@@ -0,0 +1,14 @@
+// Everything the page needs from the core, as one bundle entry (see build.mjs). Node code imports
+// the individual modules directly.
+export * from './text.js';
+export * from './board.js';
+export * from './migrate.js';
+export * from './ops.js';
+export * from './read.js';
+export * from './changes.js';
+export * from './housekeeping-spec.js';
+export * from './backlog-spec.js';
+export * from './share.js';
+export * from './links.js';
+export * from './board-url.js';
+export * from './housekeeping.js';

package/core/links.js

@@ -0,0 +1,55 @@
+// The label as a metadata line only when the value is nothing but task ids. A hand-written line such as
+// "**Blocked by**: waiting on legal" is ordinary description text and stays exactly as written.
+export const BLOCKED_LABEL = 'Blocked by(?=\\*\\*\\s*:[ \\t]*(?:[Tt][Aa][Ss][Kk]-\\d+[\\s,]*)+$)';
+
+// Task links: **Blocked by** is the only stored relation. "Blocks" is derived from it, so the two can never
+// disagree. Advice only: nothing here stops a move or a save.
+
+// A task is finished when it sits in the board's last column or has been archived (an archived task counts as
+// done whatever its status line says: archiving is how a finished task leaves the board).
+// `where` says which file a task lives in: 'board' | 'backlog' | 'archive'.
+export function indexTasks({ board = [], backlog = [], archive = [] }) {
+    const byId = new Map();
+    for (const [where, tasks] of [['archive', archive], ['backlog', backlog], ['board', board]]) {
+        for (const task of tasks) byId.set(task.id, { task, where });
+    }
+    return byId;
+}
+
+export function isFinished(entry, columns) {
+    if (!entry) return false;
+    if (entry.where === 'archive') return true;
+    return columns.length > 0 && entry.task.status === columns[columns.length - 1].id;
+}
+
+// What a task waits on: { open: [entry], done: [entry], unknown: [id] }. `open` is what the badge counts; a
+// blocker in the backlog file is open, an id that matches no task is unknown and counts for nothing.
+export function blockersOf(task, byId, columns) {
+    const out = { open: [], done: [], unknown: [] };
+    for (const id of task.blockedBy || []) {
+        const entry = byId.get(id);
+        if (!entry) out.unknown.push(id);
+        else (isFinished(entry, columns) ? out.done : out.open).push(entry);
+    }
+    return out;
+}
+
+// The tasks whose **Blocked by** names `id`, board and backlog first (they are the ones still in play).
+export function blockedByThis(id, byId) {
+    return [...byId.values()].filter(({ task }) => (task.blockedBy || []).includes(id));
+}
+
+// Does following **Blocked by** links from `id` come back to it? (A warning in the UI, never an error.)
+export function hasCycle(id, byId) {
+    const seen = new Set();
+    const walk = (cur) => {
+        for (const next of (byId.get(cur)?.task.blockedBy) || []) {
+            if (next === id) return true;
+            if (seen.has(next)) continue;
+            seen.add(next);
+            if (walk(next)) return true;
+        }
+        return false;
+    };
+    return walk(id);
+}

package/core/migrate.js

@@ -0,0 +1,69 @@
+// Migration of kanban.md / archive.md to the current format (v3: one metadata field per line).
+//
+// Accepts v1 (status by section) and v2 (joined metadata lines). The file is rewritten
+// canonically, and the result is only returned if re-parsing it gives exactly the same tasks and
+// configuration as the original: a migration that would lose or change anything is refused.
+import { parseBoard, parseArchive, generateBoard, generateTaskBlock, normalizeConfig, SOURCE_COMMENT, hasSourceComment } from './board.js';
+import { BoardError, deepEqual, firstDifference, detectEol, toEol, splitLines, stripEol } from './text.js';
+
+export const CURRENT_VERSION = 3;
+
+const unsafe = (message, details) => new BoardError('migration_unsafe', message, { details, hint: 'The file was left untouched. Fix the reported problem by hand and run the migration again.' });
+
+// The parser keeps a file's line endings inside notes and preserved sections, so when a mixed
+// file is rewritten with one ending, the expected tasks are normalized the same way.
+const withEol = (tasks, eol) => tasks.map((t) => ({ ...t, notes: t.notes.replace(/\r?\n/g, eol), extra: t.extra.replace(/\r?\n/g, eol) }));
+
+function assertTotalParse(md, tasks, what) {
+    // Every "### TASK-" line must have produced exactly one distinct task, or a rewrite would drop one.
+    const blocks = (md.match(/^###\s+TASK-/gm) || []).length;
+    const unique = new Set(tasks.map((t) => t.id)).size;
+    if (tasks.length !== blocks || unique !== blocks) {
+        throw unsafe(`${what}: ${tasks.length} of ${blocks} task blocks could be read (${unique} distinct ids)`, { blocks, parsed: tasks.length, unique });
+    }
+}
+
+// kanban.md text -> { text, from, changed }
+export function migrateBoardText(md) {
+    const before = parseBoard(md);
+    const from = before.formatVersion;
+    if (from >= CURRENT_VERSION) return { text: md, from, changed: false };
+    assertTotalParse(md, before.tasks, 'kanban.md');
+
+    const eol = detectEol(md);
+    const text = toEol(generateBoard({ config: before.config, tasks: before.tasks }, { sourceComment: true }), eol);
+
+    const after = parseBoard(text);
+    const diff = firstDifference(
+        { config: normalizeConfig(before.config), tasks: withEol(before.tasks, eol) },
+        { config: after.config, tasks: after.tasks });
+    if (diff || after.formatVersion !== CURRENT_VERSION) throw unsafe('kanban.md would not read back identically after migration', diff || { path: 'formatVersion' });
+    return { text, from, changed: true };
+}
+
+// archive.md text -> { text, from, changed }. The archive's own heading lines (title, description,
+// section, in whatever language) are kept verbatim; only the format marker and the task blocks change.
+export function migrateArchiveText(md, columns) {
+    const before = parseArchive(md, columns);
+    const from = before.formatVersion;
+    if (from >= CURRENT_VERSION) return { text: md, from, changed: false };
+    assertTotalParse(md, before.tasks, 'archive.md');
+
+    const eol = detectEol(md);
+    const lines = splitLines(md);
+    let firstTask = lines.findIndex((l) => /^###\s+TASK-/.test(l));
+    if (firstTask < 0) firstTask = lines.length;
+    const head = lines.slice(0, firstTask).filter((l) => !/<!--\s*Format:/i.test(l));
+    if (!head.length) head.push('# Archive' + eol);
+    const hadSource = hasSourceComment(md);
+    head.splice(1, 0, `<!-- Format: v${CURRENT_VERSION} -->` + eol, ...(hadSource ? [] : [SOURCE_COMMENT + eol]));
+    while (head.length && stripEol(head[head.length - 1]).trim() === '') head.pop();
+    const text = toEol(head.join('') + '\n\n' + before.tasks.map(generateTaskBlock).join(''), eol);
+
+    const after = parseArchive(text, columns);
+    const diff = firstDifference(withEol(before.tasks, eol), after.tasks);
+    if (diff || after.formatVersion !== CURRENT_VERSION || !deepEqual(after.tasks.length, before.tasks.length)) {
+        throw unsafe('archive.md would not read back identically after migration', diff || { path: 'formatVersion' });
+    }
+    return { text, from, changed: true };
+}