@polderlabs/openkan 0.4.0

package/dist/kanban/io.js

@@ -0,0 +1,75 @@
+// OpenKan — low-level filesystem I/O helpers.
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/**
+ * Write `data` to `path` atomically:
+ * - write to `<path>.tmp`
+ * - fsync the temp file
+ * - rename to `path`
+ * This matches the pattern used in kanban/board.ts:persist.
+ */
+export function writeFileAtomic(path, data) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, data, "utf-8");
+    try {
+        const fd = openSync(tmp, "r");
+        fsyncSync(fd);
+        closeSync(fd);
+    }
+    catch (_) { }
+    renameSync(tmp, path);
+}
+/** Recursively ensure `dir` exists. Analogous to `mkdir -p`. */
+export function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+/**
+ * Remove any `.tmp` files under `dir` older than `maxAgeMs` (default: 1 hour).
+ * Used by initBoard to clean up stale atomic-write temporaries.
+ */
+export function cleanupStaleTmp(dir, maxAgeMs = 60 * 60 * 1000) {
+    if (!existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const entry of entries) {
+        if (!entry.endsWith(".tmp"))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        if (now - st.mtimeMs > maxAgeMs) {
+            try {
+                unlinkSync(full);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+/** Recursively remove a directory (or file), silently ignoring errors. */
+export function removeDir(dir) {
+    if (!existsSync(dir))
+        return;
+    try {
+        rmSync(dir, { force: true, recursive: true });
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/kanban/mdx-render.js

@@ -0,0 +1,348 @@
+// OpenKan — server-side MDX → HTML renderer with block markers and custom components.
+import { createHash } from "node:crypto";
+import sanitizeHtml from "sanitize-html";
+// ─── Block ID ─────────────────────────────────────────────────────────────────
+/**
+ * Produce a stable block ID from block text and its position among top-level siblings.
+ * Same content at the same sibling position → same ID even if lines are added above.
+ */
+export function blockIdFor(blockText, siblingIndex) {
+    const normalised = normalizeLine(blockText).slice(0, 80);
+    const input = `${siblingIndex}|${normalised}`;
+    const sha = createHash("sha1").update(input).digest("hex").slice(0, 12);
+    return `blk-${sha}`;
+}
+// ─── Normalization helpers ────────────────────────────────────────────────────
+function normalizeLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function trimLines(text) {
+    return text.replace(/^[ \t]+|[ \t]+$/gm, "");
+}
+const CUSTOM_COMPONENTS = ["Ask", "Choice", "Input", "Confirm", "Preview"];
+function isCustomComponent(name) {
+    return CUSTOM_COMPONENTS.includes(name);
+}
+function detectBlockType(firstLine) {
+    const t = firstLine.trim();
+    if (/^#{1,6}\s/.test(t))
+        return "heading";
+    if (t === "---")
+        return "other"; // frontmatter separator — treated as other
+    if (/^(```|~~~)/.test(t))
+        return "code";
+    if (/^>\s/.test(t))
+        return "quote";
+    if (/^\|/.test(t))
+        return "table";
+    if (/^[-*+]\s/.test(t))
+        return "list";
+    if (/^<[A-Z][a-zA-Z]*(\s|>|\/>)/.test(t))
+        return "component";
+    return "paragraph";
+}
+function isBlankLine(line) {
+    return /^ *$/.test(line);
+}
+/**
+ * Parse source MDX into top-level blocks.
+ * Each block has: type, lines (raw), startLine (1-indexed).
+ */
+function parseBlocks(source) {
+    const lines = source.split("\n");
+    const blocks = [];
+    let i = 0;
+    let siblingIndex = 0;
+    while (i < lines.length) {
+        // Skip blank lines before a block
+        while (i < lines.length && isBlankLine(lines[i]))
+            i++;
+        if (i >= lines.length)
+            break;
+        const startLine = i + 1; // 1-indexed
+        const firstLine = lines[i];
+        // Check for code fence open/close
+        if (/^(```|~~~)/.test(firstLine.trim())) {
+            const fence = firstLine.trim().match(/^(```|~~~)/)[1];
+            const fenceRE = new RegExp(`^${fence === "```" ? "\\`\\`\\`" : "~~~"}\s*$`);
+            const blockLines = [firstLine];
+            i++;
+            while (i < lines.length && !fenceRE.test(lines[i].trim())) {
+                blockLines.push(lines[i]);
+                i++;
+            }
+            if (i < lines.length)
+                blockLines.push(lines[i]); // closing fence
+            i++;
+            blocks.push({ type: "code", lines: blockLines, startLine });
+            siblingIndex++;
+            continue;
+        }
+        // Detect component on a single line: <Name ... />
+        if (/^<[A-Z][a-zA-Z]*\s/.test(firstLine.trim()) || /^<[A-Z][a-zA-Z]*\/>$/.test(firstLine.trim())) {
+            const singleLine = firstLine.trim();
+            // Check if it's self-closing or has a closing tag on same line
+            const selfClose = /^\s*<([A-Z][a-zA-Z]*)[^>]*\/>\s*$/.test(singleLine);
+            const sameLineClose = /<\/[A-Z][a-zA-Z]*>\s*$/.test(singleLine);
+            if (selfClose || sameLineClose) {
+                blocks.push({ type: "component", lines: [firstLine], startLine });
+                i++;
+                siblingIndex++;
+                continue;
+            }
+            // Multi-line component: find closing tag
+            const openMatch = singleLine.match(/^<([A-Z][a-zA-Z]*)/);
+            if (openMatch) {
+                const tagName = openMatch[1];
+                const closeRE = new RegExp(`</${tagName}\\s*>\\s*$`);
+                const blockLines = [firstLine];
+                i++;
+                while (i < lines.length && !closeRE.test(lines[i].trim())) {
+                    blockLines.push(lines[i]);
+                    i++;
+                }
+                if (i < lines.length)
+                    blockLines.push(lines[i]);
+                i++;
+                blocks.push({ type: "component", lines: blockLines, startLine });
+                siblingIndex++;
+                continue;
+            }
+        }
+        // For other types, accumulate lines that belong to the block
+        const bType = detectBlockType(firstLine);
+        const blockLines = [firstLine];
+        i++;
+        if (bType === "heading" || bType === "code" || bType === "component") {
+            // Already handled above; heading shouldn't reach here
+        }
+        else {
+            // Accumulate continuation lines for paragraph/list/quote/table
+            while (i < lines.length) {
+                const peek = lines[i];
+                const peekTrimmed = peek.trim();
+                if (isBlankLine(peek)) {
+                    // Blank line ends paragraph/quote/table
+                    if (bType === "paragraph" || bType === "quote" || bType === "table")
+                        break;
+                    i++;
+                    continue;
+                }
+                if (/^#{1,6}\s/.test(peekTrimmed))
+                    break; // next heading
+                if (/^(```|~~~)/.test(peekTrimmed))
+                    break; // next fence
+                if (/^<\/?[A-Z]/.test(peekTrimmed))
+                    break; // next component tag
+                if (bType === "list" && !/^[-*+]\s/.test(peekTrimmed) && !/^\d+\.\s/.test(peekTrimmed)) {
+                    // Indented continuation is ok; non-indented non-list ends the block
+                    if (!/^\s/.test(peek) && !/^\d+\.\s/.test(peekTrimmed))
+                        break;
+                }
+                blockLines.push(peek);
+                i++;
+            }
+        }
+        blocks.push({ type: bType, lines: blockLines, startLine });
+        siblingIndex++;
+    }
+    return blocks;
+}
+// ─── Block-to-HTML ─────────────────────────────────────────────────────────────
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function normalizeWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function blockPreview(blockLines) {
+    return normalizeWhitespace(trimLines(blockLines.join(" "))).slice(0, 80);
+}
+// Extract attributes from a self-closing or block component tag
+function extractAttrs(line) {
+    const attrs = {};
+    // Match key="value" or key='value' patterns
+    const re = /([a-zA-Z_][a-zA-Z0-9_]*)=["']([^"']*)["']/g;
+    let m;
+    while ((m = re.exec(line)) !== null) {
+        attrs[m[1]] = m[2];
+    }
+    return attrs;
+}
+function renderCustomComponent(tagName, blockLines, blockId, line, opts) {
+    // For Preview, we emit a placeholder that the frontend replaces with an iframe
+    if (tagName === "Preview") {
+        // Get all content between <Preview ... /> or <Preview ...>...</Preview>
+        const full = blockLines.join("\n");
+        const tsxMatch = full.match(/tsx=["']([^"']*)["']/) || full.match(/tsx=["']([^"']*)["']/);
+        const propsMatch = full.match(/props=["']([^"']*)["']/) || full.match(/props=["']([^"']*)["']/);
+        const tsx = tsxMatch ? tsxMatch[1] : "";
+        const props = propsMatch ? propsMatch[1] : "{}";
+        const escapedTsx = tsx.replace(/<\/script>/gi, "<\\/script>").replace(/<\/iframe>/gi, "<\\/iframe>");
+        const escapedProps = props.replace(/"/g, "&quot;");
+        return `<section data-mdx-component="Preview" data-mdx-tsx="${escapedTsx}" data-mdx-props="${escapedProps}" data-block-id="${blockId}" data-line="${line}"></section>`;
+    }
+    // For Ask/Choice/Input/Confirm — render as interactive widgets
+    const full = blockLines.join("\n");
+    const questionMatch = full.match(/question=["']([^"']*)["']/) || /<Ask>([^<]*)<\/Ask>/s.test(full) ? full.match(/<Ask>([^<]*)<\/Ask>/s)?.[1] : null;
+    const question = questionMatch ? questionMatch[1] : "";
+    const placeholder = extractAttrs(full).placeholder ?? "";
+    const opts_match = full.match(/options=\{(\[[^\]]*\])/);
+    const optionsJson = opts_match ? opts_match[1] : "[]";
+    return `<section data-mdx-component="${tagName}" data-block-id="${blockId}" data-line="${line}" data-question="${escapeHtml(question)}" data-placeholder="${escapeHtml(placeholder)}" data-options="${escapeHtml(optionsJson)}"></section>`;
+}
+function blockToHtml(block, siblingIndex, opts) {
+    const blockId = blockIdFor(block.lines.join("\n"), siblingIndex);
+    const preview = blockPreview(block.lines);
+    const rawLines = block.lines.join("\n");
+    if (block.type === "component") {
+        const firstLine = block.lines[0].trim();
+        const tagMatch = firstLine.match(/^<([A-Z][a-zA-Z]*)/);
+        if (tagMatch) {
+            const tagName = tagMatch[1];
+            if (isCustomComponent(tagName)) {
+                const inner = renderCustomComponent(tagName, block.lines, blockId, block.startLine, opts);
+                return `<section class="mdx-block" data-block-id="${blockId}" data-line="${block.startLine}" data-block-type="${block.type}">${inner}</section>`;
+            }
+        }
+        // Unknown component — pass through safely
+        const inner = escapeHtml(rawLines);
+        return `<section class="mdx-block" data-block-id="${blockId}" data-line="${block.startLine}" data-block-type="${block.type}">${inner}</section>`;
+    }
+    // Build inner HTML from the block content
+    let inner = "";
+    const trimmed = trimLines(rawLines);
+    switch (block.type) {
+        case "heading": {
+            const m = trimmed.match(/^(#{1,6})\s(.*)/);
+            const level = m ? m[1].length : 2;
+            inner = `<h${level}>${escapeHtml(m ? m[2] : trimmed.replace(/^#+\s/, ""))}</h${level}>`;
+            break;
+        }
+        case "code": {
+            const codeLines = block.lines.slice(1, -1).join("\n");
+            const langMatch = block.lines[0].trim().match(/^```(\w*)/);
+            const lang = langMatch && langMatch[1] ? langMatch[1] : "";
+            inner = `<pre><code class="language-${lang}">${escapeHtml(codeLines)}</code></pre>`;
+            break;
+        }
+        case "list": {
+            const items = block.lines.map((l) => {
+                const text = l.replace(/^\s*[-*+]\s/, "").replace(/^\s*\d+\.\s/, "");
+                return `<li>${escapeHtml(text.trim())}</li>`;
+            }).join("");
+            inner = trimmed.startsWith("1.") ? `<ol>${items}</ol>` : `<ul>${items}</ul>`;
+            break;
+        }
+        case "quote": {
+            const text = block.lines.map((l) => l.replace(/^>\s?/, "")).join(" ");
+            inner = `<blockquote>${escapeHtml(text.trim())}</blockquote>`;
+            break;
+        }
+        case "table": {
+            // Simple pipe table: first row = header, second row = separator, rest = body
+            const rows = block.lines.map((l) => l.trim()).filter((l) => l.startsWith("|"));
+            if (rows.length < 2) {
+                inner = `<p>${escapeHtml(trimmed)}</p>`;
+            }
+            else {
+                const cells = rows[0].split("|").map((c) => c.trim()).filter((c) => c !== "");
+                const header = `<thead><tr>${cells.map((c) => `<th>${escapeHtml(c)}</th>`).join("")}</tr></thead>`;
+                const bodyRows = rows.slice(2).map((row) => {
+                    const cells = row.split("|").map((c) => c.trim()).filter((c) => c !== "");
+                    return `<tr>${cells.map((c) => `<td>${escapeHtml(c)}</td>`).join("")}</tr>`;
+                }).join("");
+                inner = `<table>${header}<tbody>${bodyRows}</tbody></table>`;
+            }
+            break;
+        }
+        case "paragraph":
+        default: {
+            inner = `<p>${escapeHtml(normalizeWhitespace(trimmed))}</p>`;
+            break;
+        }
+    }
+    return `<section class="mdx-block" data-block-id="${blockId}" data-line="${block.startLine}" data-block-type="${block.type}">${inner}</section>`;
+}
+// ─── Frontmatter stripping ─────────────────────────────────────────────────────
+/**
+ * Strip YAML frontmatter from an MDX string.
+ * Handles the common ---...--- delimiter format used in task MDX files.
+ * Returns the body text (without frontmatter) trimmed of leading whitespace.
+ */
+export function stripMdxFrontmatter(mdx) {
+    if (!mdx || typeof mdx !== "string")
+        return mdx ?? "";
+    // Frontmatter: starts with `---\n` or `---\r\n`, ends with `\n---\n` or `\r?\n---\r?\n`
+    const m = mdx.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!m)
+        return mdx;
+    return mdx.slice(m[0].length).trimStart();
+}
+// ─── Main render function ──────────────────────────────────────────────────────
+const SANITIZE_ALLOWED_TAGS = new Set([
+    "h1", "h2", "h3", "h4", "h5", "h6", "p", "ul", "ol", "li",
+    "code", "pre", "blockquote", "a", "strong", "em", "hr", "br",
+    "table", "thead", "tbody", "tr", "th", "td",
+    "section", "iframe", "button", "input", "select", "option", "label",
+]);
+const SANITIZE_ALLOWED_ATTRS = {
+    a: ["href", "title"],
+    code: ["class"],
+    td: ["align"],
+    th: ["align"],
+    img: ["src", "alt", "width", "height"],
+    section: ["class", "data-block-id", "data-line", "data-block-type", "data-mdx-component", "data-mdx-tsx", "data-mdx-props", "data-question", "data-placeholder", "data-options"],
+    iframe: ["sandbox", "referrerpolicy", "srcdoc", "title"],
+    button: ["type", "onclick", "class"],
+    input: ["type", "placeholder", "value", "oninput", "class"],
+    select: ["class"],
+    option: ["value", "selected"],
+    label: ["class", "for"],
+};
+const SANITIZE_ALLOWED_SCHEMES = ["http:", "https:", "mailto:", "data:image/"];
+function urlFilter(url) {
+    try {
+        const u = new URL(url);
+        if (SANITIZE_ALLOWED_SCHEMES.some((s) => u.protocol === s))
+            return true;
+        if (u.protocol === "javascript:")
+            return false;
+        return false;
+    }
+    catch {
+        return !url.startsWith("javascript:") && !url.startsWith("data:");
+    }
+}
+export async function renderMdx(source, opts) {
+    const blocks = parseBlocks(stripMdxFrontmatter(source));
+    const warnings = [];
+    const htmlParts = [];
+    const blockResults = [];
+    blocks.forEach((b, i) => {
+        const blockId = blockIdFor(b.lines.join("\n"), i);
+        blockResults.push({
+            id: blockId,
+            line: b.startLine,
+            preview: blockPreview(b.lines),
+            type: b.type,
+        });
+        htmlParts.push(blockToHtml(b, i, opts));
+    });
+    let html = htmlParts.join("\n");
+    // Sanitize final HTML
+    const clean = sanitizeHtml(html, {
+        allowedTags: Array.from(SANITIZE_ALLOWED_TAGS),
+        allowedAttributes: SANITIZE_ALLOWED_ATTRS,
+        allowedSchemes: SANITIZE_ALLOWED_SCHEMES,
+    });
+    return {
+        html: clean,
+        blocks: blockResults,
+        warnings,
+    };
+}

package/dist/kanban/mdx.js

@@ -0,0 +1,231 @@
+import { writeFileSync, mkdirSync, existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { listInputs } from "./inputs.js";
+export function categoryEmoji(c) {
+    const map = {
+        frontend: "🎨", backend: "⚙️", infra: "☁️", docs: "📖",
+        test: "🧪", design: "✏️", data: "🗄️", security: "🔒", task: "📋",
+    };
+    return map[c] ?? "📋";
+}
+export function priorityEmoji(p) {
+    const map = {
+        urgent: "🚨", high: "⬆️", normal: "➡️", low: "⬇️",
+    };
+    return map[p] ?? "➡️";
+}
+const TASKS_DIR = "tasks";
+const SESSIONS_DIR = "sessions";
+const TRUNCATE_AT = 4000;
+// ─── Pure formatters ──────────────────────────────────────────────────────────
+export function taskToMarkdown(task, board, extra) {
+    const col = board.columns.find(c => c.id === task.column);
+    const prio = task.priority ?? "normal";
+    const effort = task.effort ?? "—";
+    const tags = task.tags ?? [];
+    const lines = [
+        "---",
+        `title: ${task.title}`,
+        `id: ${task.id}`,
+        `column: ${task.column}`,
+        `order: ${task.order}`,
+        `state: ${task.state}`,
+        `status: ${task.status}`,
+        `agent: ${task.agent || "(default)"}`,
+        `model: ${task.model ?? "(default)"}`,
+        `createdAt: ${task.createdAt}`,
+        `updatedAt: ${task.updatedAt}`,
+        `tags: [${tags.map(t => `"${t}"`).join(", ")}]`,
+        `category: ${task.category ?? "task"}`,
+        `priority: ${prio}`,
+        `effort: ${effort}`,
+        `archived: ${task.archived ? "true" : "false"}`,
+        "---",
+        "",
+        `# ${task.title}`,
+        "",
+        `> **Category:** \`${task.category ?? "task"}\` · **Priority:** ${priorityEmoji(prio)} ${prio} · **Effort:** ${effort}`,
+        `> **Tags:** ${tags.map(t => `\`${t}\``).join(" ")}`,
+        "",
+    ];
+    if (task.description) {
+        lines.push(task.description, "");
+    }
+    if (task.stale) {
+        lines.push("> ⚠️ Source has changed since this task was imported. Re-run kanban_import to refresh.", "");
+    }
+    if (task.source) {
+        lines.push(`> 📄 Source: \`${task.source.path}:${task.source.line}\` *(imported from line ${task.source.line})*`, "");
+    }
+    lines.push(`_agent: ${task.agent || "(default)"} · _state: ${task.state}_`);
+    if (task.sessionId) {
+        lines.push(`_session: ${task.sessionId}_`);
+    }
+    if (task.lastError) {
+        lines.push("", `**Last error:** ${task.lastError}`);
+    }
+    if (task.sessionArtifact) {
+        lines.push("", `[Session transcript](./sessions/${task.sessionId}.mdx)`);
+    }
+    // If there are pending inputs, append an "Awaiting input" section
+    const pending = extra?.pendingInputs ?? [];
+    const unresolved = pending.filter(i => i.status === "pending");
+    if (unresolved.length > 0) {
+        lines.push("", "## Awaiting input", "");
+        for (const inp of unresolved) {
+            if (inp.type === "choice" && inp.options) {
+                const opts = inp.options.map(o => `- **${o.label}**${o.description ? `: ${o.description}` : ""}`).join("\n");
+                lines.push(`<Choice question="${inp.question}" options={${JSON.stringify(inp.options.map(o => ({ id: o.id, label: o.label })))}} />`);
+            }
+            else {
+                lines.push(`<Ask question="${inp.question}" />`);
+            }
+            lines.push("");
+        }
+    }
+    // Agent progress section — read from progress.json in the task dir
+    const progressFile = join(task.artifacts.mdxPath, "..", "progress.json");
+    let progressNotes = [];
+    try {
+        if (existsSync(progressFile)) {
+            progressNotes = JSON.parse(readFileSync(progressFile, "utf-8"));
+        }
+    }
+    catch { /* ignore */ }
+    if (progressNotes.length > 0) {
+        lines.push("", "## Agent progress", "");
+        for (const note of progressNotes) {
+            const time = new Date(note.ts).toLocaleTimeString("en-US", { hour12: false });
+            lines.push(`- [${time}] ${note.text}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function sessionToMarkdown(sessionId, rec, task, messages, status) {
+    const lines = [
+        "---",
+        `title: Session ${sessionId}`,
+        `id: ${sessionId}`,
+        `taskId: ${rec.taskId}`,
+        `status: ${rec.status}`,
+        `startedAt: ${rec.startedAt}`,
+        `endedAt: ${rec.endedAt ?? ""}`,
+        "---",
+        "",
+        `# Session ${sessionId}`,
+        "",
+    ];
+    if (task) {
+        lines.push(`**Task:** [${task.title}](./${task.id}.mdx)`, "");
+    }
+    lines.push(`**Status:** ${status}`, `**Started:** ${rec.startedAt}`, rec.endedAt ? `**Ended:** ${rec.endedAt}` : "", "", "## Transcript", "");
+    for (const msg of messages) {
+        const content = msg.content.length > TRUNCATE_AT
+            ? msg.content.slice(0, TRUNCATE_AT) + "\n\n_(truncated — message too long)_"
+            : msg.content;
+        lines.push(`### ${msg.role}`, "", content, "");
+    }
+    return lines.join("\n");
+}
+export function boardToMarkdown(board) {
+    const cols = board.columns;
+    const lines = [
+        "---",
+        `title: Kanban Board`,
+        `generated: ${new Date().toISOString()}`,
+        `columns: ${cols.map(c => c.id).join(", ")}`,
+        "---",
+        "",
+        "# Kanban Board",
+        "",
+    ];
+    for (const col of cols) {
+        const tasks = board.tasks
+            .filter(t => t.column === col.id)
+            .sort((a, b) => a.order - b.order);
+        lines.push(`## ${col.title}`, "");
+        if (tasks.length === 0) {
+            lines.push("_No tasks_", "");
+        }
+        else {
+            for (const t of tasks) {
+                const agent = t.agent || "(default)";
+                lines.push(`- [${t.id.toUpperCase()}] ${t.title}`);
+                lines.push(`  _agent: ${agent} · status: ${t.status}_`);
+                lines.push("");
+            }
+        }
+    }
+    return lines.join("\n");
+}
+// ─── I/O ──────────────────────────────────────────────────────────────────────
+function ensureDir(dir, sub) {
+    const p = join(dir, sub);
+    if (!existsSync(p))
+        mkdirSync(p, { recursive: true });
+}
+/** Write task MDX to per-task directory (tasks/<id>/task.mdx). */
+export async function writeTaskMdx(task, dir, board) {
+    ensureDir(dir, TASKS_DIR);
+    const taskDir = join(dir, TASKS_DIR, task.id);
+    ensureDir(dir, `${TASKS_DIR}/${task.id}`);
+    const path = join(taskDir, "task.mdx");
+    // Load pending inputs for the "Awaiting input" section
+    let pendingInputs = [];
+    try {
+        pendingInputs = listInputs(task.id, dir);
+    }
+    catch {
+        // ignore
+    }
+    const mdxContent = taskToMarkdown(task, board, { pendingInputs });
+    writeFileSync(path, mdxContent, "utf-8");
+}
+export async function writeSessionMdx(sessionId, rec, task, dir, _client) {
+    ensureDir(dir, SESSIONS_DIR);
+    const path = join(dir, SESSIONS_DIR, `${sessionId}.mdx`);
+    // Placeholder — real transcript requires client.session.history() which
+    // the SDK may not expose yet. Write a stub; caller can rewrite later.
+    const stub = sessionToMarkdown(sessionId, rec, task, [], rec.status);
+    writeFileSync(path, stub, "utf-8");
+}
+export async function writeBoardMdx(board, dir) {
+    const path = join(dir, "board.mdx");
+    writeFileSync(path, boardToMarkdown(board), "utf-8");
+}
+export async function regenerateAll(board, dir) {
+    await writeBoardMdx(board, dir);
+    for (const task of board.tasks) {
+        await writeTaskMdx(task, dir, board);
+    }
+    for (const [sid, rec] of Object.entries(board.sessions)) {
+        const task = board.tasks.find(t => t.id === rec.taskId);
+        await writeSessionMdx(sid, rec, task, dir, undefined);
+    }
+}
+// ─── Frontmatter helpers ───────────────────────────────────────────────────────
+/**
+ * Strip YAML frontmatter from an MDX string and return the body text, trimmed.
+ * Handles the common ---...--- delimiter format used in task MDX files.
+ */
+export function extractDescription(mdx) {
+    const match = mdx.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    if (!match)
+        return mdx.trim();
+    return match[1].trim();
+}
+/**
+ * Return the mtime of a task's MDX file, or null if it doesn't exist.
+ * @param taskId - the task id
+ * @param kanbanDir - the .ok directory path
+ */
+export function statMdxMtime(taskId, kanbanDir) {
+    const mdxPath = join(kanbanDir, "tasks", taskId, "task.mdx");
+    try {
+        if (existsSync(mdxPath)) {
+            return statSync(mdxPath).mtime.toISOString();
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}