@polderlabs/openkan 0.4.0

package/dist/kanban/comments.js

@@ -0,0 +1,80 @@
+// OpenKan — comment CRUD anchored to MDX blocks.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { nanoid } from "nanoid";
+import { ensureDir } from "./io.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const STORE_FILE = "comments.json";
+function storePath(taskDir) {
+    return join(taskDir, STORE_FILE);
+}
+function loadStore(taskDir) {
+    const p = storePath(taskDir);
+    if (!existsSync(p))
+        return { comments: [] };
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return { comments: [] };
+    }
+}
+function saveStore(taskDir, store) {
+    ensureDir(taskDir);
+    writeFileSync(storePath(taskDir), JSON.stringify(store, null, 2), "utf-8");
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/** List all comments for a task, newest first. */
+export function listComments(taskId, dir) {
+    const taskDir = join(dir, taskId);
+    const { comments } = loadStore(taskDir);
+    return comments
+        .filter((c) => c.taskId === taskId)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+/** Add a new comment. */
+export function addComment(taskId, dir, data) {
+    const taskDir = join(dir, taskId);
+    ensureDir(taskDir);
+    const store = loadStore(taskDir);
+    const comment = {
+        id: `cmt-${nanoid(8)}`,
+        taskId,
+        blockId: data.blockId,
+        line: data.line ?? 1,
+        text: data.text,
+        author: data.author,
+        createdAt: new Date().toISOString(),
+        resolved: false,
+    };
+    store.comments.push(comment);
+    saveStore(taskDir, store);
+    return comment;
+}
+/** Delete a comment by id. Returns true if deleted. */
+export function deleteComment(taskId, dir, commentId) {
+    const taskDir = join(dir, taskId);
+    const store = loadStore(taskDir);
+    const before = store.comments.length;
+    store.comments = store.comments.filter((c) => !(c.id === commentId && c.taskId === taskId));
+    if (store.comments.length === before)
+        return false;
+    saveStore(taskDir, store);
+    return true;
+}
+/** Set resolved state of a comment. Returns updated Comment or null if not found. */
+export function resolveComment(taskId, dir, commentId, resolved, resolvedBy, resolvedAt, resolvedReason) {
+    const taskDir = join(dir, taskId);
+    const store = loadStore(taskDir);
+    const idx = store.comments.findIndex((c) => c.id === commentId && c.taskId === taskId);
+    if (idx === -1)
+        return null;
+    const now = resolvedAt ?? new Date().toISOString();
+    store.comments[idx] = {
+        ...store.comments[idx],
+        resolved,
+        ...(resolved ? { resolvedBy: resolvedBy ?? store.comments[idx].author, resolvedAt: now, resolvedReason } : {}),
+    };
+    saveStore(taskDir, store);
+    return store.comments[idx];
+}

package/dist/kanban/docs.js

@@ -0,0 +1,144 @@
+// OpenKan — docs file tree and read helpers for <projectRoot>/docs/
+import { existsSync, readFileSync, statSync, readdirSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { renderMdx } from "./mdx-render.js";
+// ─── Path safety ─────────────────────────────────────────────────────────────
+/**
+ * Reject any path that escapes the docs root (contains ".." or resolves outside).
+ */
+function isSafeRelPath(docsRoot, relPath) {
+    if (relPath.includes(".."))
+        return false;
+    const full = resolve(docsRoot, relPath);
+    const normalizedRoot = resolve(docsRoot);
+    // full must equal the root exactly OR be inside it (start with root + /)
+    if (full !== normalizedRoot && !full.startsWith(normalizedRoot + sep))
+        return false;
+    return true;
+}
+// ─── listDocs ────────────────────────────────────────────────────────────────
+function buildEntry(docsRoot, relPath, depth, maxDepth) {
+    const full = join(docsRoot, relPath);
+    if (!existsSync(full))
+        return null;
+    let st;
+    try {
+        st = statSync(full);
+    }
+    catch {
+        return null;
+    }
+    const name = relPath.split("/").pop() ?? relPath;
+    if (!st.isDirectory()) {
+        return {
+            path: relPath,
+            name,
+            isDir: false,
+            size: st.size,
+            modified: st.mtime.toISOString(),
+        };
+    }
+    // Directory
+    const children = [];
+    if (depth < maxDepth) {
+        let entries;
+        try {
+            entries = readdirSync(full);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries.sort()) {
+            // Skip hidden files/dirs
+            if (entry.startsWith("."))
+                continue;
+            const childRel = relPath ? `${relPath}/${entry}` : entry;
+            const child = buildEntry(docsRoot, childRel, depth + 1, maxDepth);
+            if (child)
+                children.push(child);
+        }
+    }
+    return {
+        path: relPath,
+        name,
+        isDir: true,
+        children,
+    };
+}
+/**
+ * List the docs directory tree.
+ * @param opts.root - project root
+ * @param opts.docsDir - defaults to "docs"
+ * @param opts.maxDepth - defaults to 4
+ */
+export function listDocs(opts) {
+    const docsRoot = join(opts.root, opts.docsDir ?? "docs");
+    const maxDepth = opts.maxDepth ?? 4;
+    if (!existsSync(docsRoot))
+        return { entries: [] };
+    if (!isSafeRelPath(docsRoot, "."))
+        return { entries: [] };
+    let entries = [];
+    let dirEntries;
+    try {
+        dirEntries = readdirSync(docsRoot);
+    }
+    catch {
+        return { entries: [] };
+    }
+    for (const entry of dirEntries.sort()) {
+        if (entry.startsWith("."))
+            continue;
+        const child = buildEntry(docsRoot, entry, 1, maxDepth);
+        if (child)
+            entries.push(child);
+    }
+    return { entries };
+}
+// ─── readDoc ─────────────────────────────────────────────────────────────────
+/**
+ * Read a single doc file, optionally render it.
+ * @param opts.root - project root
+ * @param opts.relPath - relative to docs root, no leading slash
+ * @param opts.render - default true for .md/.mdx
+ */
+export async function readDoc(opts) {
+    const docsRoot = join(opts.root, opts.docsDir ?? "docs");
+    // Security check: reject traversal attempts
+    if (!isSafeRelPath(docsRoot, opts.relPath)) {
+        throw new Error("Unsafe path");
+    }
+    const fullPath = resolve(docsRoot, opts.relPath);
+    if (!existsSync(fullPath))
+        throw new Error("File not found");
+    let st;
+    try {
+        st = statSync(fullPath);
+    }
+    catch {
+        throw new Error("File not found");
+    }
+    if (!st.isFile())
+        throw new Error("Not a file");
+    const raw = readFileSync(fullPath, "utf-8");
+    const ext = fullPath.split(".").pop()?.toLowerCase() ?? "";
+    const doRender = (opts.render ?? true) && (ext === "md" || ext === "mdx");
+    const result = {
+        path: opts.relPath,
+        mtime: st.mtime.toISOString(),
+        size: st.size,
+    };
+    if (doRender) {
+        const rendered = await renderMdx(raw);
+        result.html = rendered.html;
+        result.rendered = rendered.html; // back-compat alias
+        result.blocks = rendered.blocks;
+        result.raw = raw; // keep raw available even in rendered mode
+    }
+    else {
+        // Raw mode: caller handles content-type; return minimal shape
+        result.raw = raw;
+        result.contentType = "text/markdown";
+    }
+    return result;
+}

package/dist/kanban/fs.js

@@ -0,0 +1,163 @@
+// kanban/fs.ts — file-system helpers for the browser
+import { readdirSync, statSync, lstatSync, realpathSync } from "node:fs";
+import { join, basename, resolve } from "node:path";
+import os from "node:os";
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/** Realpath but returns undefined on error (e.g. broken symlink). */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Build a single FsEntry from a path (without children). */
+function entryFromPath(absPath) {
+    try {
+        // Use lstatSync to detect symlinks without following them
+        const lst = lstatSync(absPath, { throwIfNoEntry: false });
+        if (!lst)
+            return null;
+        const isSymlink = lst.isSymbolicLink();
+        // Use statSync to get the type of the target (follows symlinks)
+        const st = statSync(absPath, { throwIfNoEntry: false });
+        if (!st)
+            return null;
+        return {
+            name: basename(absPath),
+            path: absPath,
+            isDir: st.isDirectory(),
+            isFile: st.isFile(),
+            isSymlink,
+            size: st.size,
+            mtime: st.mtime.toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan a single directory and return sorted FsEntry[] (no children).
+ * Caps at maxEntries.
+ */
+function scanDir(dirPath, includeHidden, maxEntries) {
+    let entries;
+    try {
+        entries = readdirSync(dirPath, { encoding: "utf8", withFileTypes: false });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    const sorted = [...entries].sort();
+    for (const name of sorted) {
+        if (result.length >= maxEntries)
+            break;
+        // Skip . and .. entries returned by readdirSync
+        if (name === "." || name === "..")
+            continue;
+        if (!includeHidden && name.startsWith("."))
+            continue;
+        const absPath = join(dirPath, name);
+        const entry = entryFromPath(absPath);
+        if (entry)
+            result.push(entry);
+    }
+    return result;
+}
+// ─── Security helpers ─────────────────────────────────────────────────────────
+const DENY_LIST = ["/etc", "/proc", "/sys", "/dev", "/boot", "/root"];
+/** Check if a path starts with a deny-listed prefix. */
+export function isDenyListed(path) {
+    const abs = resolve(path);
+    return DENY_LIST.some(prefix => abs === prefix || abs.startsWith(prefix + "/"));
+}
+/** Canonicalize a symlink and check if it resolves inside an allowed tree. */
+export function realPathIfAllowed(path) {
+    const abs = resolve(path);
+    const real = safeRealpath(abs);
+    if (!real)
+        return { realPath: abs, allowed: false };
+    if (isDenyListed(real))
+        return { realPath: real, allowed: false };
+    return { realPath: real, allowed: true };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Walk a directory tree up to `depth` levels.
+ * - Hidden files (starting with `.`) excluded by default.
+ * - Symlinks are noted but NOT followed (security).
+ * - Each directory caps at `maxEntries` entries.
+ */
+export async function listFs(opts) {
+    const { root, depth = 1, includeHidden = false, followSymlinks = false, maxEntries = 500, } = opts;
+    const absRoot = resolve(root);
+    function buildEntry(absPath, currentDepth) {
+        const entry = entryFromPath(absPath);
+        if (!entry)
+            return null;
+        if (entry.isDir && currentDepth < depth) {
+            const children = scanDir(absPath, includeHidden, maxEntries);
+            entry.children = children.flatMap(child => {
+                const built = buildEntry(child.path, currentDepth + 1);
+                return built !== null ? [built] : [];
+            });
+        }
+        return entry;
+    }
+    const rootEntry = buildEntry(absRoot, 0);
+    if (!rootEntry) {
+        return {
+            name: basename(absRoot),
+            path: absRoot,
+            isDir: false,
+            isFile: false,
+            isSymlink: false,
+            size: 0,
+            mtime: new Date(0).toISOString(),
+            children: [],
+        };
+    }
+    return rootEntry;
+}
+/**
+ * Return the user's home directory and its top-level entries (depth 1).
+ */
+export async function readHome() {
+    const home = os.homedir();
+    const absHome = resolve(home);
+    const rootEntry = await listFs({
+        root: absHome,
+        depth: 1,
+        includeHidden: false,
+        followSymlinks: false,
+        maxEntries: 500,
+    });
+    return {
+        home: absHome,
+        entries: rootEntry.children ?? [],
+    };
+}
+/**
+ * Return ancestor entries for `path` up to `maxDepth` levels (each depth 0, no children).
+ * Used for breadcrumb display.
+ * Note: The path itself is NOT included — only its parent directories.
+ */
+export function parents(path, maxDepth) {
+    const absPath = resolve(path);
+    // Split by "/" to get segments (works on all platforms since absPath uses forward slashes)
+    const raw = absPath.split("/").filter(Boolean);
+    // raw = ["home", "drb0rk", "Projects", "openkan", ".ok"] for /home/drb0rk/Projects/openkan/.ok
+    const result = [];
+    // Build each ancestor by accumulating segments from root
+    for (let i = 0; i < raw.length - 1 && result.length < maxDepth; i++) {
+        // Skip raw.length-1 (the leaf) so we only get ancestors
+        const accumulated = "/" + raw.slice(0, i + 1).join("/");
+        const entry = entryFromPath(accumulated);
+        if (entry)
+            result.push(entry);
+    }
+    return result;
+}

package/dist/kanban/git.js

@@ -0,0 +1,196 @@
+// OpenKan — pure git utilities (read-only).
+import { spawnSync } from "child_process";
+const GIT_TIMEOUT_MS = 5000;
+function git(args, root) {
+    try {
+        const result = spawnSync("git", args, {
+            cwd: root,
+            timeout: GIT_TIMEOUT_MS,
+            encoding: "utf-8",
+            shell: false,
+        });
+        if (result.error || result.status !== 0)
+            return "";
+        return (result.stdout ?? "");
+    }
+    catch {
+        return "";
+    }
+}
+// ─── Basic checks ──────────────────────────────────────────────────────────
+export function isGitRepo(root) {
+    try {
+        const result = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: root,
+            timeout: GIT_TIMEOUT_MS,
+            encoding: "utf-8",
+        });
+        return (result.stdout ?? "").trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+export function currentUser(root) {
+    // Read ONLY local config to avoid inheriting from global ~/.gitconfig
+    const name = git(["config", "--local", "user.name"], root).trim();
+    const email = git(["config", "--local", "user.email"], root).trim();
+    if (!name || !email)
+        return null;
+    return { name, email };
+}
+// ─── Contributors ──────────────────────────────────────────────────────────
+export function listContributors(root, opts) {
+    // Use git log to enumerate commits with author info, then group by email
+    const args = ["log", "--no-merges", "--format=%aI|%an|%ae", "--use-mailmap"];
+    if (opts?.since)
+        args.push(`--since=${opts.since}`);
+    if (opts?.until)
+        args.push(`--until=${opts.until}`);
+    if (opts?.maxCount)
+        args.push(`--max-count=${opts.maxCount}`);
+    const output = git(args, root);
+    if (!output)
+        return [];
+    // Group by email
+    const byEmail = new Map();
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf("|");
+        if (idx === -1)
+            continue;
+        const ts = trimmed.slice(0, idx);
+        const rest = trimmed.slice(idx + 1);
+        const nidx = rest.indexOf("|");
+        if (nidx === -1)
+            continue;
+        const name = rest.slice(0, nidx);
+        const email = rest.slice(nidx + 1);
+        if (!byEmail.has(email)) {
+            byEmail.set(email, { name, emails: new Set([email]), dates: [] });
+        }
+        byEmail.get(email).dates.push(ts);
+    }
+    const contributors = [];
+    for (const [email, info] of byEmail) {
+        const dates = info.dates.sort();
+        contributors.push({
+            name: info.name,
+            email,
+            commits: info.dates.length,
+            firstSeen: dates[0] ?? new Date(0).toISOString(),
+            lastSeen: dates[dates.length - 1] ?? new Date().toISOString(),
+            linesAdded: 0,
+            linesDeleted: 0,
+        });
+    }
+    return contributors;
+}
+// ─── Commits ────────────────────────────────────────────────────────────────
+export function listCommits(root, opts) {
+    // Format: each commit is preceded by --OPENKAN-SEP-- on its own line.
+    // Per commit: sha\nauthor\nemail\niso\nsubject\nbody\nfilename1\nfilename2\n
+    // Since --pretty=format with %b outputs nothing when body is empty, the
+    // number of header lines varies. We use --OPENKAN-SEP-- as an anchor:
+    // --OPENKAN-SEP--\nSHA\nAN\nAE\nTS\nSUBJECT\n%B\nFILES...\n\n
+    // But %b with empty body still consumes a \n, so files appear 6 lines after SHA
+    // regardless of whether body is empty. Use this invariant to extract files.
+    const SEP = "--OPENKAN-SEP";
+    const args = [
+        "log",
+        `--pretty=format:${SEP}%n%H%n%an%n%ae%n%aI%n%s%n%b`,
+        "--name-only",
+        "--no-merges",
+    ];
+    if (opts?.since)
+        args.push(`--since=${opts.since}`);
+    if (opts?.until)
+        args.push(`--until=${opts.until}`);
+    if (opts?.maxCount)
+        args.push(`--max-count=${opts.maxCount}`);
+    if (opts?.author)
+        args.push(`--author=${opts.author}`);
+    const output = git(args, root);
+    if (!output)
+        return [];
+    // Split into commit records: "SEP\nSHA\nAN\nAE\nTS\nSUBJECT\n%B\nFILE1\nFILE2\n\n"
+    const SEP_PATTERN = `${SEP}\n`;
+    const rawRecords = output.split(SEP_PATTERN).filter(r => r.trim());
+    const commits = [];
+    for (const raw of rawRecords) {
+        const lines = raw.split("\n");
+        if (lines.length < 6)
+            continue;
+        // sha at lines[0], author at [1], email at [2], ts at [3], subject at [4]
+        // %b output at [5] (empty string if no body), then files from [6] onward
+        // until first empty line (blank separator between commits)
+        const sha = lines[0];
+        const author = lines[1];
+        const email = lines[2];
+        const ts = lines[3];
+        const subject = lines[4];
+        // body is lines[5] (may be empty string) — we use it as-is
+        const body = lines[5] ?? "";
+        // Files: lines[6] onward, until first empty string (blank line between records)
+        const fileLines = [];
+        for (let i = 6; i < lines.length; i++) {
+            if (lines[i] === "")
+                break;
+            fileLines.push(lines[i]);
+        }
+        commits.push({ sha, author, email, ts, subject, body, files: fileLines });
+    }
+    return commits;
+}
+// ─── Commit-to-task attribution ────────────────────────────────────────────
+export function attributeCommitsToTasks(root, tasks, opts) {
+    const result = new Map();
+    const commits = listCommits(root, { since: opts?.since, maxCount: opts?.maxCount });
+    for (const task of tasks) {
+        result.set(task.id, []);
+    }
+    for (const commit of commits) {
+        for (const task of tasks) {
+            let matched = false;
+            // 1. Exact file match
+            if (task.source?.path) {
+                if (commit.files.includes(task.source.path)) {
+                    matched = true;
+                }
+                else {
+                    // 2. Commit touches a file under the same directory
+                    const taskDir = task.source.path.replace(/\/[^/]+$/, ""); // parent dir
+                    if (taskDir && commit.files.some(f => f.startsWith(taskDir + "/"))) {
+                        matched = true;
+                    }
+                }
+            }
+            // 3. Subject or body contains task id (tsk-xxxxxxxx)
+            if (!matched && task.id) {
+                if (commit.subject.includes(task.id) || commit.body.includes(task.id)) {
+                    matched = true;
+                }
+            }
+            // 4. Subject or body contains title (case-insensitive, min 8 chars)
+            if (!matched && task.title && task.title.length >= 8) {
+                const lc = task.title.toLowerCase();
+                if (commit.subject.toLowerCase().includes(lc) || commit.body.toLowerCase().includes(lc)) {
+                    matched = true;
+                }
+            }
+            if (matched) {
+                result.get(task.id).push({
+                    sha: commit.sha,
+                    author: commit.author,
+                    email: commit.email,
+                    ts: commit.ts,
+                    subject: commit.subject,
+                    files: commit.files,
+                });
+            }
+        }
+    }
+    return result;
+}