@polderlabs/openkan 0.4.0

package/dist/kanban/watcher.js

@@ -0,0 +1,270 @@
+// OpenKan — filesystem watcher using Node's built-in fs.watch.
+import { watch as fsWatch } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+// ─── Default ignore list ─────────────────────────────────────────────────────
+const DEFAULT_IGNORED = [
+    /server\.lock$/,
+    /server\.pid$/,
+    /server\.log$/,
+    /changelog\.jsonl$/,
+    /[/\\]node_modules[/\\]/, // matches node_modules/ or node_modules\ anywhere in path
+];
+function defaultIgnore(absPath) {
+    const normalized = absPath.replace(/\\/g, "/"); // Windows path normalisation
+    return DEFAULT_IGNORED.some(re => re.test(normalized)) || normalized.endsWith(".tmp");
+}
+/**
+ * An AsyncIterable that yields filesystem change events from one or more fs.watch
+ * handles. Debouncing coalesces rapid write+rename bursts into single deliveries.
+ */
+class WatchEventIterable {
+    queue = [];
+    root;
+    debounceMs;
+    ignoreFn;
+    stats;
+    closed;
+    closeWatchers;
+    resolveNext = null;
+    debounceTimer = null;
+    /** Set when close() is explicitly called — no more events accepted. */
+    done = false;
+    /** Set when a consumer exits (return() called) — blocks new events but allows reuse. */
+    closing = false;
+    constructor(root, debounceMs, ignoreFn, stats, closed, closeWatchers) {
+        this.root = root;
+        this.debounceMs = debounceMs;
+        this.ignoreFn = ignoreFn;
+        this.stats = stats;
+        this.closed = closed;
+        this.closeWatchers = closeWatchers;
+    }
+    /** Called by fs.watch callbacks to enqueue an event. */
+    pushEvent(kind, absPath) {
+        if (this.closed())
+            return;
+        if (this.closing)
+            return; // close() was called; no more events accepted
+        this.stats.started += 1;
+        if (this.ignoreFn(absPath)) {
+            this.stats.filtered += 1;
+            return;
+        }
+        this.queue.push({ kind, absPath });
+        if (this.resolveNext) {
+            this.resolveNext();
+            this.resolveNext = null;
+        }
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.debounceTimer !== null)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            if (this.queue.length === 0)
+                return;
+            if (this.resolveNext) {
+                this.resolveNext();
+                this.resolveNext = null;
+            }
+        }, this.debounceMs);
+    }
+    async next() {
+        // Always drain any pending events first.
+        if (this.queue.length > 0) {
+            const ev = this.queue.shift();
+            this.stats.delivered += 1;
+            return {
+                done: false,
+                value: {
+                    kind: ev.kind,
+                    path: relative(this.root, ev.absPath).replace(/\\/g, "/"),
+                    absPath: ev.absPath,
+                    ts: new Date().toISOString(),
+                },
+            };
+        }
+        if (this.done)
+            return { done: true, value: undefined };
+        // Wait for next event.
+        let resolveWait = null;
+        const waitForEvent = new Promise(r => { resolveWait = r; });
+        this.resolveNext = () => { if (resolveWait) {
+            resolveWait();
+            resolveWait = null;
+        } };
+        // Poll for done=true every 5ms so we don't wait forever on a closed watcher.
+        const pollDone = setInterval(() => {
+            if (this.done && resolveWait) {
+                resolveWait();
+                resolveWait = null;
+            }
+        }, 5);
+        await waitForEvent;
+        clearInterval(pollDone);
+        this.resolveNext = null;
+        // Drain queue even if done=true (e.g., events arrived just before done was set).
+        if (this.queue.length > 0) {
+            const ev = this.queue.shift();
+            this.stats.delivered += 1;
+            return {
+                done: false,
+                value: {
+                    kind: ev.kind,
+                    path: relative(this.root, ev.absPath).replace(/\\/g, "/"),
+                    absPath: ev.absPath,
+                    ts: new Date().toISOString(),
+                },
+            };
+        }
+        // If closing (consumer exited), return done=true so for-await exits permanently.
+        // If done=true (close() was called), also return done=true.
+        return { done: this.closing || this.done, value: undefined };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /** Called by for-await when the consumer exits (timeout or normal end). */
+    async return() {
+        // Only permanently close if the queue is empty. If events are pending (e.g., a
+        // debounced event arrived just before this return() call), keep the watcher
+        // alive so the next consumer can drain them. Only close watchers if done=true.
+        if (this.queue.length === 0) {
+            this.closing = true; // block new events; watchers stay open until close()
+        }
+        if (this.resolveNext) {
+            this.resolveNext();
+            this.resolveNext = null;
+        }
+        if (this.debounceTimer !== null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        return { done: true, value: undefined };
+    }
+    /** Mark iteration as permanently done and clean up watchers. */
+    destroy() {
+        this.done = true;
+        this.closing = true;
+        this.closeWatchers();
+        if (this.resolveNext) {
+            this.resolveNext();
+            this.resolveNext = null;
+        }
+        if (this.debounceTimer !== null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+    }
+}
+/**
+ * Watch a directory for filesystem changes.
+ *
+ * Uses `fs.watch` with `recursive: true` on Linux/macOS. On Windows (where
+ * recursive is not supported), falls back to a manual readdirRecursive walk
+ * and watches each sub-directory individually.
+ *
+ * Events are debounced (default 100 ms) to coalesce rapid write+rename bursts.
+ * A default filter ignores server.lock, server.pid, server.log, changelog.jsonl,
+ * node_modules, and any .tmp file. Additional ignores can be passed via options.
+ */
+export function watch(options) {
+    const root = isAbsolute(options.root) ? options.root : join(process.cwd(), options.root);
+    const debounceMs = options.debounceMs ?? 100;
+    const extraIgnore = options.ignore ?? (() => false);
+    const ignoreFn = (absPath) => defaultIgnore(absPath) || extraIgnore(absPath);
+    const stats = { started: 0, delivered: 0, filtered: 0 };
+    let closedFlag = false;
+    function isClosed() { return closedFlag; }
+    // ── Try recursive watch (Linux / macOS) ─────────────────────────────────────
+    let recursiveWatchers = [];
+    try {
+        const w = fsWatch(root, { recursive: true, persistent: true }, () => { });
+        recursiveWatchers = [w];
+    }
+    catch {
+        recursiveWatchers = []; // not supported; use fallback
+    }
+    if (recursiveWatchers.length > 0) {
+        // Recursive watch works.
+        const watcher = recursiveWatchers[0];
+        const iterable = new WatchEventIterable(root, debounceMs, ignoreFn, stats, isClosed, () => { for (const w of recursiveWatchers)
+            w.close(); });
+        watcher.on("change", (eventName, filename) => {
+            if (!filename || closedFlag)
+                return;
+            const kind = eventName === "rename" ? "rename" : "change";
+            iterable.pushEvent(kind, join(root, filename));
+        });
+        watcher.on("error", () => { });
+        return {
+            events: iterable,
+            close() {
+                closedFlag = true;
+                iterable.destroy();
+            },
+            stats,
+        };
+    }
+    // ── Fallback: manual recursive walk + per-directory watches (Windows) ───────
+    const dirsToWatch = [root];
+    function walkDirs(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === "node_modules")
+                continue;
+            const abs = join(dir, entry);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                dirsToWatch.push(abs);
+                walkDirs(abs);
+            }
+        }
+    }
+    walkDirs(root);
+    const perDirWatchers = [];
+    const iterable = new WatchEventIterable(root, debounceMs, ignoreFn, stats, isClosed, () => { for (const w of perDirWatchers)
+        w.close(); });
+    for (const dir of dirsToWatch) {
+        try {
+            const w = fsWatch(dir, (eventName, filename) => {
+                if (!filename || closedFlag)
+                    return;
+                const kind = eventName === "rename" ? "rename" : "change";
+                iterable.pushEvent(kind, join(dir, filename));
+            });
+            w.on("error", () => { });
+            perDirWatchers.push(w);
+        }
+        catch { /* directory deleted between stat and watch */ }
+    }
+    return {
+        events: iterable,
+        close() {
+            closedFlag = true;
+            iterable.destroy();
+        },
+        stats,
+    };
+}
+/**
+ * Return the absolute path of a task's source file, or null if the task has no source.
+ * The returned path is suitable for comparison against WatchEvent.absPath.
+ */
+export function sourcePathOfTask(t, kanbanDir) {
+    return t.source?.path ? join(kanbanDir, "..", t.source.path) : null;
+}

package/dist/ok/commands/goal.js

@@ -0,0 +1,65 @@
+import { listPrds, readPrd, writePrd, rebuildIndex, paths } from "../storage.js";
+import { parseArgs, flagString, flagBool } from "../ids.js";
+import { touch } from "../schemas.js";
+const statuses = ['open', 'in_progress', 'met', 'dropped'];
+export async function runGoal(args) {
+    const [sub, ...rest] = args;
+    const { positionals, flags } = parseArgs(rest);
+    const p = paths(process.cwd());
+    const output = (value) => process.stdout.write(`${typeof value === 'string' && !flagBool(flags, 'json') ? value : JSON.stringify(value, null, 2)}\n`);
+    if (sub === 'list') {
+        const prdId = flagString(flags, 'prd') || positionals[0];
+        const status = flagString(flags, 'status');
+        if (status && !statuses.includes(status))
+            throw new Error(`status must be ${statuses.join('|')}`);
+        const prds = prdId ? [await readPrd(p, prdId)] : await listPrds(p);
+        if (prds.some(prd => !prd))
+            throw new Error(`no such PRD: ${prdId}`);
+        const goals = prds.flatMap(prd => prd.goals.map(goal => ({ ...goal, prd: prd.id }))).filter(goal => !status || goal.status === status);
+        if (flagBool(flags, 'json'))
+            output(goals);
+        else
+            output(goals.map(goal => `${goal.prd}/${goal.id}  ${goal.status}  ${goal.text}`).join('\n') || '(no goals)');
+        return 0;
+    }
+    if (!['add', 'show', 'update'].includes(sub))
+        throw new Error('Usage: openkan goal list [--prd ID] [--json] | add <prd-id> <text> | show <prd-id> <goal-id> | update <prd-id> <goal-id> --status open|in_progress|met|dropped [--text TEXT]');
+    const [prdId, goalId, ...extra] = positionals;
+    if (!prdId || !goalId || (sub !== 'add' && extra.length))
+        throw new Error(`Usage: openkan goal ${sub} <prd-id> <${sub === 'add' ? 'text' : 'goal-id'}>`);
+    const prd = await readPrd(p, prdId);
+    if (!prd)
+        throw new Error(`no such PRD: ${prdId}`);
+    let goal;
+    if (sub === 'add') {
+        const number = Math.max(0, ...prd.goals.map(g => Number(g.id.match(/^g(\d+)$/)?.[1] || 0))) + 1;
+        goal = { id: `g${number}`, text: [goalId, ...extra].join(' '), status: 'open' };
+        prd.goals.push(goal);
+    }
+    else {
+        const found = prd.goals.find(g => g.id === goalId);
+        if (!found)
+            throw new Error(`no such goal: ${prdId}/${goalId}`);
+        goal = found;
+        if (sub === 'update') {
+            const status = flagString(flags, 'status');
+            const text = flagString(flags, 'text');
+            if (!status && text === undefined)
+                throw new Error('goal update requires --status or --text');
+            if (status && !statuses.includes(status))
+                throw new Error(`status must be ${statuses.join('|')}`);
+            if (text !== undefined && !text.trim())
+                throw new Error('goal text must not be empty');
+            if (status)
+                goal.status = status;
+            if (text !== undefined)
+                goal.text = text;
+        }
+    }
+    if (sub !== 'show') {
+        await writePrd(p, touch(prd));
+        await rebuildIndex(p);
+    }
+    output(goal);
+    return 0;
+}

package/dist/ok/commands/index.js

@@ -0,0 +1,87 @@
+// ok/commands/index.ts — `ok index` and `ok doctor`.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { isTask, isPlan, isPrd, validateTask, validatePlan, validatePrd, } from "../schemas.js";
+import { initIfMissing, rebuildIndex, paths as computePaths, } from "../storage.js";
+async function paths() {
+    const p = computePaths(process.cwd());
+    return initIfMissing(process.cwd());
+}
+export async function runIndex() {
+    const p = await paths();
+    const idx = await rebuildIndex(p);
+    process.stdout.write(`tasks: ${idx.tasks.length}, plans: ${idx.plans.length}, prds: ${idx.prds.length}\n`);
+    return 0;
+}
+async function readMaybeJson(p) {
+    try {
+        const raw = await fs.readFile(p, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return undefined;
+        return { __parseError: e.message };
+    }
+}
+export async function runDoctor() {
+    const p = await paths();
+    const issues = [];
+    for (const file of await fs.readdir(p.tasksDir).catch(() => [])) {
+        if (!file.endsWith(".json"))
+            continue;
+        const full = path.join(p.tasksDir, file);
+        const v = await readMaybeJson(full);
+        if (v === undefined)
+            continue;
+        if (v && typeof v === "object" && "__parseError" in v) {
+            issues.push({ file, reason: `JSON parse error: ${v.__parseError}` });
+            continue;
+        }
+        if (!isTask(v)) {
+            const err = validateTask(v) ?? { reason: "schema mismatch" };
+            issues.push({ file, ...err });
+        }
+    }
+    for (const file of await fs.readdir(p.plansDir).catch(() => [])) {
+        if (!file.endsWith(".json"))
+            continue;
+        const full = path.join(p.plansDir, file);
+        const v = await readMaybeJson(full);
+        if (v === undefined)
+            continue;
+        if (v && typeof v === "object" && "__parseError" in v) {
+            issues.push({ file, reason: `JSON parse error: ${v.__parseError}` });
+            continue;
+        }
+        if (!isPlan(v)) {
+            const err = validatePlan(v) ?? { reason: "schema mismatch" };
+            issues.push({ file, ...err });
+        }
+    }
+    for (const file of await fs.readdir(p.prdsDir).catch(() => [])) {
+        if (!file.endsWith(".json"))
+            continue;
+        const full = path.join(p.prdsDir, file);
+        const v = await readMaybeJson(full);
+        if (v === undefined)
+            continue;
+        if (v && typeof v === "object" && "__parseError" in v) {
+            issues.push({ file, reason: `JSON parse error: ${v.__parseError}` });
+            continue;
+        }
+        if (!isPrd(v)) {
+            const err = validatePrd(v) ?? { reason: "schema mismatch" };
+            issues.push({ file, ...err });
+        }
+    }
+    if (issues.length === 0) {
+        process.stdout.write("ok doctor: 0 issues\n");
+        return 0;
+    }
+    process.stdout.write(`ok doctor: ${issues.length} issue(s)\n`);
+    for (const issue of issues) {
+        process.stdout.write(`  ${issue.file}${issue.id ? ` (${issue.id})` : ""}: ${issue.reason}\n`);
+    }
+    return 1;
+}

package/dist/ok/commands/init.js

@@ -0,0 +1,15 @@
+// ok/commands/init.ts — `ok init` — create .ok/ in cwd.
+import { initIfMissing } from "../storage.js";
+export async function cmdInit() {
+    const root = process.cwd();
+    const p = await initIfMissing(root);
+    process.stdout.write(`.ok/ initialised at ${p.root}\n`);
+    process.stdout.write("  config.json\n");
+    process.stdout.write("  index.json\n");
+    process.stdout.write(`  ${p.tasksDir.replace(`${p.root}/`, "")}/\n`);
+    process.stdout.write(`  ${p.plansDir.replace(`${p.root}/`, "")}/\n`);
+    process.stdout.write(`  ${p.prdsDir.replace(`${p.root}/`, "")}/\n`);
+    process.stdout.write(`  ${p.sessionsDir.replace(`${p.root}/`, "")}/\n`);
+    process.stdout.write(`  ${p.locksDir.replace(`${p.root}/`, "")}/\n`);
+    return 0;
+}

package/dist/ok/commands/plan.js

@@ -0,0 +1,155 @@
+// ok/commands/plan.ts — `ok plan add|list|show|update`.
+import { touch, byUpdatedDesc, } from "../schemas.js";
+import { initIfMissing, readPlan, writePlan, listPlans, readTask, writeTask, readConfig, rebuildIndex, paths as computePaths, } from "../storage.js";
+import { newId, nowIso, parseArgs, flagString, flagCsv, flagBool } from "../ids.js";
+const STATUSES = ["draft", "active", "blocked", "complete", "abandoned"];
+function parseStatus(v) {
+    if (!v)
+        return undefined;
+    if (!STATUSES.includes(v)) {
+        throw new Error(`status must be one of ${STATUSES.join("|")}`);
+    }
+    return v;
+}
+async function paths() {
+    const p = computePaths(process.cwd());
+    if (!(await readConfig(p))) {
+        return initIfMissing(process.cwd());
+    }
+    return p;
+}
+function printTable(rows) {
+    if (rows.length === 0) {
+        process.stdout.write("(no plans)\n");
+        return;
+    }
+    const w = Math.max(2, ...rows.map((r) => r.id.length));
+    for (const r of rows) {
+        process.stdout.write(`${r.id.padEnd(w)}  ${r.status.padEnd(10)}  ${r.updatedAt}  ${r.title}\n`);
+    }
+}
+export async function runPlan(args) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "add": return cmdPlanAdd(rest);
+        case "list": return cmdPlanList(rest);
+        case "show": return cmdPlanShow(rest);
+        case "update": return cmdPlanUpdate(rest);
+        default:
+            process.stderr.write("usage: ok plan <add|list|show|update>\n");
+            return 2;
+    }
+}
+async function cmdPlanAdd(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length === 0) {
+        process.stderr.write("usage: ok plan add <title> [--summary …] [--prd <id>] [--tasks t1,t2,…]\n");
+        return 2;
+    }
+    const title = positionals.join(" ");
+    const summary = flagString(flags, "summary") ?? title;
+    const prd = flagString(flags, "prd");
+    const tasks = flagCsv(flags, "tasks");
+    const acceptance = flagCsv(flags, "acceptance");
+    const phase = flagString(flags, "phase");
+    const p = await paths();
+    const now = nowIso();
+    const plan = {
+        schema: "ok.plan.v1",
+        id: newId("pln"),
+        title,
+        summary,
+        status: "draft",
+        tasks,
+        acceptance,
+        createdAt: now,
+        updatedAt: now,
+    };
+    if (prd)
+        plan.prd = prd;
+    if (phase)
+        plan.phase = phase;
+    await writePlan(p, plan);
+    // Backlink: set plan on each referenced task if not already set.
+    for (const tid of tasks) {
+        const t = await readTask(p, tid);
+        if (t && !t.plan) {
+            await writeTask(p, touch({ ...t, plan: plan.id }));
+        }
+    }
+    await rebuildIndex(p);
+    process.stdout.write(`${plan.id}\n`);
+    return 0;
+}
+async function cmdPlanList(args) {
+    const { flags } = parseArgs(args);
+    const p = await paths();
+    let plans = await listPlans(p);
+    const status = parseStatus(flagString(flags, "status"));
+    if (status)
+        plans = plans.filter((pl) => pl.status === status);
+    const prd = flagString(flags, "prd");
+    if (prd)
+        plans = plans.filter((pl) => pl.prd === prd);
+    plans = byUpdatedDesc(plans);
+    if (flagBool(flags, "json")) {
+        process.stdout.write(JSON.stringify(plans, null, 2) + "\n");
+        return 0;
+    }
+    printTable(plans.map((pl) => ({ id: pl.id, status: pl.status, title: pl.title, updatedAt: pl.updatedAt })));
+    return 0;
+}
+async function cmdPlanShow(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok plan show <id> [--json]\n");
+        return 2;
+    }
+    const p = await paths();
+    const plan = await readPlan(p, positionals[0]);
+    if (!plan) {
+        process.stderr.write(`no such plan: ${positionals[0]}\n`);
+        return 1;
+    }
+    if (flagBool(flags, "json")) {
+        process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+        return 0;
+    }
+    for (const [k, v] of Object.entries(plan)) {
+        process.stdout.write(`${k}: ${typeof v === "string" ? v : JSON.stringify(v)}\n`);
+    }
+    return 0;
+}
+async function cmdPlanUpdate(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok plan update <id> [--status …] [--phase …] [--tasks t1,t2,…] [--append-task t]\n");
+        return 2;
+    }
+    const p = await paths();
+    const existing = await readPlan(p, positionals[0]);
+    if (!existing) {
+        process.stderr.write(`no such plan: ${positionals[0]}\n`);
+        return 1;
+    }
+    let next = touch(existing);
+    const status = parseStatus(flagString(flags, "status"));
+    if (status)
+        next.status = status;
+    const phase = flagString(flags, "phase");
+    if (phase !== undefined)
+        next.phase = phase;
+    const tasksCsv = flagString(flags, "tasks");
+    if (tasksCsv !== undefined)
+        next.tasks = flagCsv({ tasks: tasksCsv }, "tasks");
+    const appendTask = flagString(flags, "append-task");
+    if (appendTask)
+        next.tasks = [...next.tasks, appendTask];
+    const appendTasks = flagCsv(flags, "append-tasks");
+    for (const t of appendTasks)
+        next.tasks = [...next.tasks, t];
+    await writePlan(p, next);
+    await rebuildIndex(p);
+    process.stdout.write(`${next.id}\n`);
+    return 0;
+}