@ashikahmad/kanbanmd 0.0.0-stage → 2.0.0

package/cli/kanbanmd.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// kanbanmd: command line front end for the board core. Every command prints one JSON document.
+//   kanbanmd [--dir DIR] [--dry-run] [--actor NAME] <command> [args]
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { getBoard, getTask, getConfig, listArchive, getStats, summarizeChanges } from '../core/read.js';
+import { etagOf } from '../core/text.js';
+import { getHousekeeping, archiveCandidates } from '../core/housekeeping.js';
+import { parseHousekeepingSpec } from '../core/housekeeping-spec.js';
+import { BoardError } from '../core/text.js';
+import { TASK_FIELDS } from '../core/ops.js';
+import { runInit, parseAgents, promptAgents, AGENT_NAMES } from './init.js';
+import { startServer, openBrowser, DEFAULT_PORT } from './serve.js';
+import { readWorkspace, readActivity, mutate, migrateProject } from '../io/node-fs.js';
+
+const BOOL = new Set(['dry-run', 'at-end', 'overdue', 'reverse', 'apply', 'enable', 'disable', 'no-open', 'force', 'yes', 'no-mcp', 'no-skill', 'no-instructions', 'no-board']);
+function parseArgs(argv) {
+    const flags = {}, pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const k = a.slice(2);
+            if (BOOL.has(k)) flags[k] = true;
+            else flags[k] = argv[++i];
+        } else pos.push(a);
+    }
+    return { flags, pos };
+}
+
+const HELP = `kanbanmd [--dir DIR] [--dry-run] [--actor NAME] <command>
+
+  housekeeping [--apply] [--set SPEC|off|reset]   what to archive or review; --apply archives the finished ones in one edit;
+                      --set "done=done after=30d | backlog=backlog after=90d | max=200" edits the policy
+  serve [--port N] [--no-open]                     serve the page and this folder on 127.0.0.1 so any browser can edit it (Ctrl-C stops)
+  init [--agent claude,cursor,vscode,gemini,codex,generic|all] [--force] [--yes] [--no-mcp] [--no-skill] [--no-instructions] [--no-board]
+                      set this folder up for AI agents: MCP config, skill, instruction block, a starter board (--dry-run previews)
+  mcp [--read-only]   run the MCP server (stdio) for this folder; this is what an agent's MCP config starts
+  migrate                                          rewrite kanban.md / archive.md in the current format (backups kept)
+  board [filters]     compact task list in display order.  (alias: list)
+  task <id> [--fields a,b]   one task in full, with its etag.  (alias: show)
+  config              valid columns, priorities, categories, users, tags
+  archived [filters] [--reverse]   archived tasks (to archive one: archive <id>)
+  backlog [filters]                tasks in the backlog file;  backlog --enable [--column ID] [--file NAME.md]  /  --disable
+                                   moves the backlog column's tasks into (or back out of) their own file
+  stats               counts by status / assignee / priority, overdue and due soon
+  changes [--since ISO]   edits made through the tools (the page's edits are not logged)
+    filters: --status a,b --assignee @x --tag t --priority P --category C --text "words"
+             --due-before YYYY-MM-DD --overdue --limit N --offset N --fields title,status,progress   (replaces the default columns; id is always kept)
+  apply <json | ->                                 apply one op as JSON
+  create --title T [--status ID] [--priority P] [--category C] [--assignees a,b] [--tags x,y]
+         [--due YYYY-MM-DD] [--description D]
+  update <id> --<field> <value> ...                fields: ${TASK_FIELDS.join(', ')}
+  move <id> <status> [--before ID | --at-end]       in place by default; a position relocates the block
+  sort --mode blocks|ids|positions|clear [--order asc|desc] [--scope board|archive|both]   (mode is required)
+       blocks: reorder file blocks by id.  ids / positions: write Order keys from id order / current order.
+       clear: remove all Order keys.
+  toggle <id> <index|text>        subtask <id> <text>        note <id> <text>
+  archive <id>   restore <id>   delete <id>
+  config <categories|users|priorities|tags> a,b,c
+  columns <json>                                   [{"name","id"}], optional "reassign" via apply`;
+
+function summary(t) {
+    return { id: t.id, title: t.title, status: t.status, ...(t.order != null && { order: t.order }), priority: t.priority, assignees: t.assignees, due: t.due, tags: t.tags };
+}
+
+async function main() {
+    const { flags, pos } = parseArgs(process.argv.slice(2));
+    const dir = resolve(flags.dir || process.env.KANBANMD_DIR || '.');
+    const [cmd, ...a] = pos;
+    const opt = { dryRun: !!flags['dry-run'], actor: flags.actor || 'cli' };
+    const need = (n, what) => { if (a.length < n) throw new BoardError('usage', `Missing ${what}`, { hint: 'Run kanbanmd --help' }); };
+
+    if (!cmd || cmd === 'help' || flags.help !== undefined) { console.log(HELP); return; }
+
+    if (cmd === 'backlog' && (flags.enable || flags.disable)) {
+        const op = flags.disable ? { type: 'setBacklogFile', enabled: false } : { type: 'setBacklogFile', enabled: true, column: flags.column, file: flags.file };
+        console.log(JSON.stringify({ ok: true, ...(await mutate(dir, op, opt)) }));
+        return;
+    }
+
+    if (cmd === 'housekeeping') {
+        if (flags.set !== undefined) {
+            const spec = String(flags.set).trim();
+            const h = parseHousekeepingSpec(spec) || {};
+            const op = spec === 'reset' ? { type: 'setHousekeeping', reset: true }
+                : spec.toLowerCase() === 'off' ? { type: 'setHousekeeping', off: true }
+                : { type: 'setHousekeeping', done: h.done, backlog: h.backlog, max: h.max };
+            console.log(JSON.stringify({ ok: true, ...(await mutate(dir, op, opt)) }));
+            return;
+        }
+        const ws = await readWorkspace(dir);
+        if (flags.apply) {
+            const ids = archiveCandidates(ws);
+            if (!ids.length) { console.log(JSON.stringify({ ok: true, archived: 0, note: 'nothing to archive' })); return; }
+            console.log(JSON.stringify({ ok: true, archived: ids.length, ...(await mutate(dir, { type: 'archiveTasks', ids }, opt)) }));
+            return;
+        }
+        console.log(JSON.stringify({ ok: true, ...getHousekeeping(ws) }));
+        return;
+    }
+
+    if (cmd === 'mcp') {
+        await import('../mcp/server.js'); // loaded only here, so the other commands never need the MCP SDK
+        await new Promise(() => {}); // the server keeps the process alive over stdio
+    }
+
+    if (cmd === 'init') {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).name;
+        let agents;
+        if (flags.agent !== undefined) agents = parseAgents(flags.agent);
+        else if (process.stdin.isTTY && !flags.yes) agents = await promptAgents();
+        else agents = ['claude'];
+        const report = runInit({ dir, agents, pkg, dryRun: opt.dryRun, force: !!flags.force, mcp: !flags['no-mcp'], skill: !flags['no-skill'], instructions: !flags['no-instructions'], board: !flags['no-board'] });
+        console.log(JSON.stringify({ ok: true, ...report }, null, 2));
+        return;
+    }
+
+    if (cmd === 'serve') {
+        const html = readFileSync(fileURLToPath(new URL('../kanbanmd.html', import.meta.url)), 'utf8');
+        const svc = await startServer({ dir, html, port: flags.port !== undefined ? Number(flags.port) : DEFAULT_PORT });
+        console.log(`Kanban.md is serving ${dir}\n\n  ${svc.url}\n\nOpen that address (it carries the access key for this run). Ctrl-C to stop.`);
+        if (!flags['no-open']) openBrowser(svc.url);
+        await new Promise((r) => { process.once('SIGINT', r); process.once('SIGTERM', r); });
+        await svc.close();
+        return;
+    }
+
+    if (cmd === 'migrate') {
+        console.log(JSON.stringify({ ok: true, ...(await migrateProject(dir, { dryRun: opt.dryRun, actor: opt.actor })) }));
+        return;
+    }
+
+    const READS = ['board', 'list', 'task', 'show', 'config', 'archived', 'backlog', 'stats', 'changes'];
+    // `config` alone shows the config; `config <list> a,b,c` writes a list.
+    if (READS.includes(cmd) && !(cmd === 'config' && a.length > 0)) {
+        const ws = await readWorkspace(dir);
+        const q = { status: flags.status, assignee: flags.assignee, tag: flags.tag, priority: flags.priority, category: flags.category,
+            text: flags.text, dueBefore: flags['due-before'], overdue: flags.overdue, limit: flags.limit, offset: flags.offset,
+            fields: flags.fields, reverse: flags.reverse };
+        let out;
+        if (cmd === 'board' || cmd === 'list') out = getBoard(ws, q);
+        else if (cmd === 'task' || cmd === 'show') { need(1, 'task id'); out = { task: getTask(ws, a[0], q) }; }
+        else if (cmd === 'config') out = getConfig(ws);
+        else if (cmd === 'archived') out = listArchive(ws, q);
+        else if (cmd === 'backlog') out = getBoard(ws, { ...q, backlog: true });
+        else if (cmd === 'stats') out = getStats(ws);
+        else out = summarizeChanges(await readActivity(dir), { since: flags.since, rev: etagOf(ws.board) });
+        console.log(JSON.stringify({ ok: true, ...out }));
+        return;
+    }
+
+    let op;
+    if (cmd === 'apply') {
+        need(1, 'a JSON op, or "-" for stdin');
+        op = JSON.parse(a[0] === '-' ? readFileSync(0, 'utf8') : a[0]);
+    } else if (cmd === 'create') {
+        const task = {};
+        for (const f of TASK_FIELDS) if (flags[f] !== undefined) task[f] = flags[f];
+        if (task.subtasks) task.subtasks = JSON.parse(task.subtasks);
+        op = { type: 'createTask', task };
+    } else if (cmd === 'update') {
+        need(1, 'task id');
+        const set = {};
+        for (const f of TASK_FIELDS) if (flags[f] !== undefined) set[f] = f === 'subtasks' ? JSON.parse(flags[f]) : flags[f];
+        op = { type: 'updateTask', id: a[0], set, ifMatch: flags['if-match'] };
+    } else if (cmd === 'move') {
+        need(2, 'task id and status');
+        op = { type: 'moveTask', id: a[0], status: a[1], before: flags.before, atEnd: flags['at-end'], ifMatch: flags['if-match'] };
+    } else if (cmd === 'sort') {
+        op = { type: 'sortTasks', mode: flags.mode, scope: flags.scope, order: flags.order };
+    } else if (cmd === 'toggle') {
+        need(2, 'task id and subtask index or text');
+        op = /^\d+$/.test(a[1]) ? { type: 'toggleSubtask', id: a[0], index: +a[1] } : { type: 'toggleSubtask', id: a[0], text: a[1] };
+    } else if (cmd === 'subtask') { need(2, 'task id and text'); op = { type: 'addSubtask', id: a[0], text: a.slice(1).join(' ') }; }
+    else if (cmd === 'note') { need(2, 'task id and text'); op = { type: 'appendNote', id: a[0], text: a.slice(1).join(' ') }; }
+    else if (cmd === 'archive') { need(1, 'task id'); op = { type: 'archiveTask', id: a[0] }; }
+    else if (cmd === 'restore') { need(1, 'task id'); op = { type: 'restoreTask', id: a[0] }; }
+    else if (cmd === 'delete') { need(1, 'task id'); op = { type: 'deleteTask', id: a[0] }; }
+    else if (cmd === 'config') { need(2, 'list name and comma separated values'); op = { type: 'setConfigList', name: a[0], values: a[1].split(',') }; }
+    else if (cmd === 'columns') { need(1, 'a JSON array of { name, id }'); op = { type: 'setColumns', columns: JSON.parse(a[0]) }; }
+    else throw new BoardError('usage', `Unknown command "${cmd}"`, { hint: 'Run kanbanmd --help' });
+
+    const out = await mutate(dir, op, opt);
+    console.log(JSON.stringify({ ok: true, ...out }));
+}
+
+main().catch((e) => {
+    const err = e instanceof BoardError ? e.toJSON() : { code: 'internal', message: e.message };
+    console.log(JSON.stringify({ ok: false, error: err }));
+    process.exitCode = 1;
+});

package/cli/serve.js

@@ -0,0 +1,161 @@
+// kanbanmd serve: a local HTTP service that serves the page (kanbanmd.html) and a tiny file API for one
+// project folder, so any browser (Firefox, Safari, Chrome) can edit the real files. Zero dependencies.
+//
+// Access: the server listens on 127.0.0.1 only. `/?t=<token>` (the URL it prints) sets an HttpOnly,
+// SameSite=Strict session cookie and redirects to `/`. Every request must carry the right Host, a matching
+// Origin when the browser sends one, and (for the API) the session cookie; writes also need the X-Kanbanmd
+// header, which no other site can add without a CORS preflight that this server never approves.
+// Only kanban.md, archive.md, the board's backlog file and the v1 backup files can be read or written.
+import http from 'node:http';
+import { promises as fs } from 'node:fs';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { join, sep } from 'node:path';
+import { spawn } from 'node:child_process';
+import { backlogFileNameOf } from '../core/backlog-spec.js';
+
+export const DEFAULT_PORT = 4777;
+const MAX_BODY = 5 * 1024 * 1024;
+
+function sameToken(a, b) {
+    const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function cookieOf(req, name) {
+    for (const part of String(req.headers.cookie || '').split(';')) {
+        const i = part.indexOf('=');
+        if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+    }
+    return null;
+}
+
+const etagOf = (st) => `"${Math.round(st.mtimeMs)}-${st.size}"`;
+
+// Start the service. `html` is the page's text. Resolves to { url, port, token, close }.
+// `port: 0` picks a free port; a busy named port falls through to the next ones.
+export async function startServer({ dir, html, port = DEFAULT_PORT, token = randomBytes(24).toString('base64url') }) {
+    const sessions = new Set();
+    // The label the page shows: the last two parts of the path ("Kanban.md/board"), since a folder name alone
+    // (board, docs) says little. The full path is its tooltip.
+    const name = dir.split(sep).filter(Boolean).slice(-2).join('/') || dir;
+    let boundPort = 0;
+    const cookieName = () => `kanbanmd_${boundPort}`;
+    const page = () => {
+        const inject = `<script>window.KANBANMD_SERVICE=${JSON.stringify({ api: '/api', name, path: dir }).replace(/</g, '\\u003c')};</script>`;
+        const i = html.indexOf('<script');
+        return i < 0 ? html + inject : html.slice(0, i) + inject + html.slice(i);
+    };
+
+    const send = (res, status, body, headers = {}) => {
+        res.writeHead(status, { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Content-Type': 'text/plain; charset=utf-8', ...headers });
+        res.end(body);
+    };
+
+    // Which file names the API accepts.
+    async function allowedName(n) {
+        if (n === 'kanban.md' || n === 'archive.md') return true;
+        if (/^(kanban|archive)\.v\d+-backup\.md$/.test(n)) return true;
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/.test(n)) return false;
+        try { return n === backlogFileNameOf(await fs.readFile(join(dir, 'kanban.md'), 'utf8')); }
+        catch { return false; }
+    }
+
+    async function readBody(req) {
+        const chunks = []; let size = 0;
+        for await (const c of req) {
+            size += c.length;
+            if (size > MAX_BODY) { const e = new Error('too large'); e.status = 413; throw e; }
+            chunks.push(c);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+
+    async function api(req, res, url) {
+        const m = /^\/api\/file\/([^/]+)$/.exec(url.pathname);
+        if (!m) return send(res, 404, 'Not found');
+        let n;
+        try { n = decodeURIComponent(m[1]); } catch { return send(res, 400, 'Bad name'); }
+        if (!(await allowedName(n))) return send(res, 404, 'Not found');
+        const path = join(dir, n);
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            let st;
+            try { st = await fs.stat(path); } catch { return send(res, 404, 'Not found'); }
+            const headers = { ETag: etagOf(st), 'Content-Type': 'text/markdown; charset=utf-8' };
+            if (req.method === 'HEAD') return send(res, 200, '', headers);
+            return send(res, 200, await fs.readFile(path), headers);
+        }
+        if (req.method === 'PUT') {
+            const text = await readBody(req);
+            const want = req.headers['if-match'];
+            if (want) {
+                let cur = null;
+                try { cur = etagOf(await fs.stat(path)); } catch { /* no file */ }
+                if (cur !== want) return send(res, 412, 'The file changed');
+            }
+            const tmp = join(dir, `.${n}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+            try { await fs.writeFile(tmp, text); await fs.rename(tmp, path); }
+            catch (e) { await fs.rm(tmp, { force: true }); throw e; }
+            return send(res, 200, '', { ETag: etagOf(await fs.stat(path)) });
+        }
+        return send(res, 405, 'Method not allowed', { Allow: 'GET, HEAD, PUT' });
+    }
+
+    const server = http.createServer(async (req, res) => {
+        try {
+            // Host and Origin: refuse anything that is not this server addressed as itself.
+            const host = String(req.headers.host || '').toLowerCase();
+            const hosts = [`127.0.0.1:${boundPort}`, `localhost:${boundPort}`];
+            if (!hosts.includes(host)) return send(res, 403, 'Wrong host');
+            const origin = req.headers.origin;
+            if (origin && !hosts.some((h) => origin === `http://${h}`)) return send(res, 403, 'Wrong origin');
+
+            const url = new URL(req.url, `http://${host}`);
+            const sid = cookieOf(req, cookieName());
+            const authed = !!sid && sessions.has(sid);
+
+            if (url.pathname === '/' && (req.method === 'GET' || req.method === 'HEAD')) {
+                const t = url.searchParams.get('t');
+                if (t !== null) {
+                    if (!sameToken(t, token)) return send(res, 401, 'This link is not valid. Use the address printed by kanbanmd serve.');
+                    const id = randomBytes(24).toString('base64url');
+                    sessions.add(id);
+                    return send(res, 302, '', { Location: '/', 'Set-Cookie': `${cookieName()}=${id}; HttpOnly; SameSite=Strict; Path=/` });
+                }
+                if (!authed) return send(res, 401, 'Open the address that kanbanmd serve printed in the terminal (it carries the access key).');
+                return send(res, 200, req.method === 'HEAD' ? '' : page(), { 'Content-Type': 'text/html; charset=utf-8' });
+            }
+            if (url.pathname.startsWith('/api/')) {
+                if (!authed) return send(res, 401, 'Not signed in');
+                if (req.method !== 'GET' && req.method !== 'HEAD' && req.headers['x-kanbanmd'] !== '1') return send(res, 403, 'Missing header');
+                return await api(req, res, url);
+            }
+            return send(res, 404, 'Not found');
+        } catch (e) {
+            send(res, e.status || 500, e.status ? e.message : 'Server error');
+        }
+    });
+
+    const tries = port === 0 ? 1 : 20;
+    for (let i = 0; i < tries; i++) {
+        const p = port === 0 ? 0 : port + i;
+        try {
+            await new Promise((ok, fail) => { server.once('error', fail); server.listen(p, '127.0.0.1', () => { server.off('error', fail); ok(); }); });
+            break;
+        } catch (e) {
+            if (e.code !== 'EADDRINUSE' || i === tries - 1) throw e;
+        }
+    }
+    boundPort = server.address().port;
+    return {
+        port: boundPort, token, sessions,
+        url: `http://127.0.0.1:${boundPort}/?t=${token}`,
+        close: () => new Promise((ok) => { server.close(ok); server.closeAllConnections?.(); }),
+    };
+}
+
+// Open a URL in the default browser (best effort).
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+    try { spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref(); } catch { /* the URL is printed anyway */ }
+}

package/core/backlog-spec.js

@@ -0,0 +1,48 @@
+// The optional "**Backlog file**:" config line. Pure, no imports besides the housekeeping spec.
+//
+//   **Backlog file**: backlog.md (backlog)
+//
+// The file name, and in brackets the id of the column whose tasks live in that file (like the
+// "name (id)" convention of the Columns line). Without brackets the column is guessed from the
+// column names, as the housekeeping policy does. No line = no backlog file.
+//
+// The invariant: with a backlog file configured, a task lives in that file exactly when its status is
+// that column. Every op re-establishes it, so promoting or demoting a task is just changing its status.
+import { resolveHousekeeping } from './housekeeping-spec.js';
+
+export const BACKLOG_DEFAULT_FILE = 'backlog.md';
+const RESERVED = new Set(['kanban.md', 'archive.md']);
+
+export const isValidStoreFileName = (name) => /^[\w.-]+\.md$/.test(name) && !name.includes('..') && !RESERVED.has(name.toLowerCase());
+
+// "backlog.md (backlog)" | "backlog.md" | "off" -> { file, column? } | null
+export function parseBacklogFileSpec(text) {
+    if (text === undefined || text === null) return null;
+    const s = String(text).trim();
+    if (!s || /^off$/i.test(s)) return null;
+    const m = /^(\S+?)\s*(?:\(([^)]+)\))?\s*$/.exec(s);
+    if (!m || !isValidStoreFileName(m[1])) return null;
+    return { file: m[1], ...(m[2] && { column: m[2].trim() }) };
+}
+
+export function formatBacklogFileSpec(b) {
+    if (!b) return 'off';
+    return b.column ? `${b.file} (${b.column})` : b.file;
+}
+
+// The usable setting: the file and an existing column (explicit or guessed), or null when there is none.
+export function resolveBacklogFile(config) {
+    const b = config.backlogFile;
+    if (!b) return null;
+    const cols = config.columns || [];
+    const column = (b.column && cols.some((c) => c.id === b.column) ? b.column : null) || (b.column ? null : resolveHousekeeping({ ...config, housekeeping: null }).backlog.column);
+    return column ? { file: b.file, column } : null;
+}
+
+// The backlog file's name as the board text declares it (or the default), found without a full parse:
+// the I/O layer needs it to know which file to read.
+export function backlogFileNameOf(boardText) {
+    const m = /\*\*Backlog file\*\*:\s*(.+)/.exec(boardText);
+    const spec = m && parseBacklogFileSpec(m[1].trim());
+    return spec ? spec.file : BACKLOG_DEFAULT_FILE;
+}

package/core/board-url.js

@@ -0,0 +1,35 @@
+// Opening a board from a web address (the page's `?board=<url>`): which URL to fetch, whether it is on the
+// page's own site, where the board's other files are, and whether a fetched text is a board at all. Pure:
+// the fetching is the page's web source.
+
+// `param` is the ?board= value, `pageHref` the page's own address (relative values resolve against it).
+// Returns { href, origin, sameOrigin, label } or null when it is not an http(s) address.
+// - A github.com "blob" link (the page that shows a file) becomes the raw file on raw.githubusercontent.com.
+// - A folder address (ending in "/") means the kanban.md in it.
+export function resolveBoardUrl(param, pageHref) {
+    const text = String(param ?? '').trim();
+    if (!text) return null;
+    let url;
+    try { url = new URL(text, pageHref); } catch (e) { return null; }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+    const blob = url.hostname === 'github.com' && /^\/([^/]+)\/([^/]+)\/blob\/(.+)$/.exec(url.pathname);
+    if (blob) url = new URL(`https://raw.githubusercontent.com/${blob[1]}/${blob[2]}/${blob[3]}`);
+    if (url.pathname.endsWith('/')) url.pathname += 'kanban.md';
+    url.hash = '';
+    let pageOrigin = null;
+    try { pageOrigin = new URL(pageHref).origin; } catch (e) { /* no page address: never same-origin */ }
+    return { href: url.href, origin: url.origin, sameOrigin: url.origin === pageOrigin, label: url.host + url.pathname };
+}
+
+// The address of another file of the board (archive.md, the backlog file), next to kanban.md. Only plain
+// file names are allowed, so a board cannot point the page at another folder or site. null = not allowed.
+export function boardFileUrl(boardHref, name) {
+    if (!/^\w[\w.-]*\.md$/.test(String(name)) || name.includes('..')) return null;
+    return new URL(name, boardHref).href;
+}
+
+// Whether a fetched text is a Kanban.md board (and not, say, an HTML page or some other Markdown file).
+export function looksLikeBoard(text) {
+    const s = String(text ?? '');
+    return /<!-- Config: Last Task ID: \d+ -->/.test(s) || /^\*\*Columns\*\*:/m.test(s) || /^###\s+TASK-\d+\s*\|/m.test(s);
+}