@polderlabs/openkan 0.4.0

package/dist/ok/ids.js

@@ -0,0 +1,98 @@
+// ok/ids.ts — id and timestamp helpers used by every planning entity.
+//
+// IDs follow the `<prefix>-<short>` convention: `tsk-abc12def`, `pln-…`,
+// `prd-…`. The short suffix is a nanoid URL-safe string (8 chars by default),
+// which gives ~47 bits of entropy — plenty for per-workspace uniqueness
+// without becoming unreadable in listings.
+import { nanoid } from "nanoid";
+/** Generate a new id of the given kind, e.g. `tsk-Vn4kRp2x`. */
+export function newId(kind, alphabetSize = 8) {
+    return `${kind}-${nanoid(alphabetSize)}`;
+}
+/** Strip the `<kind>-` prefix off an id, returning the suffix or `null`. */
+export function idSuffix(id) {
+    const m = /^[a-z]{3}-([A-Za-z0-9_-]+)$/.exec(id);
+    return m ? m[1] : null;
+}
+/** True when `id` is a well-formed id of `kind`. */
+export function isIdOf(id, kind) {
+    const m = new RegExp(`^${kind}-[A-Za-z0-9_-]+$`).exec(id);
+    return m !== null;
+}
+/** Return current ISO timestamp (millisecond precision). */
+export function nowIso() {
+    return new Date().toISOString();
+}
+/** Compare two ISO timestamps lexicographically. */
+export function isoCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (!tok.startsWith("--")) {
+            positionals.push(tok);
+            continue;
+        }
+        const eq = tok.indexOf("=");
+        let name;
+        let inline;
+        if (eq !== -1) {
+            name = tok.slice(2, eq);
+            inline = tok.slice(eq + 1);
+        }
+        else {
+            name = tok.slice(2);
+            inline = undefined;
+        }
+        if (inline !== undefined) {
+            flags[name] = inline;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+            flags[name] = true;
+        }
+        else {
+            flags[name] = next;
+            i++;
+        }
+    }
+    return { positionals, flags };
+}
+/** Read a string flag. Returns `undefined` when missing or boolean-shaped. */
+export function flagString(flags, name) {
+    const v = flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Read a CSV-style flag, splitting on either `,` or `|`. `|` is the
+ * canonical separator for prd goals / milestones per the design contract;
+ * `,` matches the more common shell convention for scope/deps/acceptance.
+ */
+export function flagCsv(flags, name) {
+    const v = flags[name];
+    if (typeof v !== "string")
+        return [];
+    return v
+        .split(/[,|]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Read a boolean flag (present at all). */
+export function flagBool(flags, name) {
+    return flags[name] !== undefined;
+}
+/** Wrap an async main so callers don't need to repeat the boilerplate. */
+export async function runMain(fn) {
+    try {
+        const code = await fn();
+        process.exit(code);
+    }
+    catch (e) {
+        process.stderr.write(`ok: ${e?.message ?? e}\n`);
+        process.exit(1);
+    }
+}

package/dist/ok/lock.js

@@ -0,0 +1,156 @@
+// ok/lock.ts — per-task claim/heartbeat/release lock protocol.
+//
+// Locks are advisory JSON files under `.ok/locks/`. They prevent the
+// most common multi-agent failure (two writers updating the same task
+// at once) without requiring native fcntl or OS-level coordination.
+//
+// Protocol:
+//   claim(id, owner, leaseMs) -> writes .ok/locks/<id>.lock with
+//     {owner, leasedUntil}. If a lock already exists held by a *different*
+//     non-expired owner, claim throws. If the existing owner is "us"
+//     (same string), heartbeat semantics apply.
+//   heartbeat(id, owner, leaseMs) -> same write, refreshes leasedUntil.
+//     Throws if the lock is not held by `owner`.
+//   release(id, owner) -> removes the lock if held by `owner`.
+//   inspect(id) -> returns the current Lock | undefined.
+//
+// Expiration is checked against `now`. A lock whose `leasedUntil` is
+// in the past is treated as if it didn't exist — another writer can
+// claim it.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { nowIso } from "./ids.js";
+const DEFAULT_LEASE_MS = 60 * 60 * 1000;
+export class LockHeldError extends Error {
+    currentOwner;
+    leasedUntil;
+    constructor(currentOwner, leasedUntil) {
+        super(`locked by ${currentOwner} until ${leasedUntil}`);
+        this.name = "LockHeldError";
+        this.currentOwner = currentOwner;
+        this.leasedUntil = leasedUntil;
+    }
+}
+export class LockNotHeldError extends Error {
+    constructor(id, owner) {
+        super(`lock for ${id} is not held by ${owner}`);
+        this.name = "LockNotHeldError";
+    }
+}
+function lockPath(p, id) {
+    if (!/^tsk-[A-Za-z0-9_-]+$/.test(id))
+        throw new Error(`invalid task id for lock: ${id}`);
+    return path.join(p.locksDir, `${id}.lock`);
+}
+export async function inspect(p, id) {
+    try {
+        const raw = await fs.readFile(lockPath(p, id), "utf-8");
+        const obj = JSON.parse(raw);
+        if (typeof obj.owner !== "string" || typeof obj.leasedUntil !== "string")
+            return undefined;
+        return {
+            owner: obj.owner,
+            leasedUntil: obj.leasedUntil,
+            acquiredAt: typeof obj.acquiredAt === "string" ? obj.acquiredAt : undefined,
+        };
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+export function isExpired(lock, now = Date.now()) {
+    const t = Date.parse(lock.leasedUntil);
+    if (Number.isNaN(t))
+        return true;
+    return t <= now;
+}
+async function writeLockFile(filePath, body) {
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const data = JSON.stringify(body, null, 2);
+    let fh;
+    try {
+        fh = await fs.open(tmp, "w");
+        await fh.writeFile(data, "utf-8");
+        await fh.sync();
+    }
+    finally {
+        if (fh)
+            await fh.close();
+    }
+    await fs.rename(tmp, filePath);
+}
+/**
+ * Acquire (or refresh) a lock for `id`. If the lock is absent, expired,
+ * or already owned by `owner`, succeeds. If owned by a *different*
+ * non-expired holder, throws `LockHeldError`.
+ */
+export async function claim(p, id, owner, opts = {}) {
+    if (!owner)
+        throw new Error("claim requires an owner");
+    const leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS;
+    const filePath = lockPath(p, id);
+    await fs.mkdir(p.locksDir, { recursive: true });
+    const existing = await inspect(p, id);
+    const now = Date.now();
+    const target = {
+        owner,
+        leasedUntil: new Date(now + leaseMs).toISOString(),
+        acquiredAt: existing?.owner === owner ? existing.acquiredAt ?? nowIso() : nowIso(),
+    };
+    if (existing && existing.owner !== owner && !isExpired(existing, now)) {
+        throw new LockHeldError(existing.owner, existing.leasedUntil);
+    }
+    await writeLockFile(filePath, target);
+    return target;
+}
+/**
+ * Refresh an existing lock's lease. Throws if the lock is absent or
+ * owned by a different owner.
+ */
+export async function heartbeat(p, id, owner, opts = {}) {
+    const existing = await inspect(p, id);
+    if (!existing || existing.owner !== owner) {
+        throw new LockNotHeldError(id, owner);
+    }
+    const leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS;
+    const target = {
+        owner,
+        leasedUntil: new Date(Date.now() + leaseMs).toISOString(),
+        acquiredAt: existing.acquiredAt ?? nowIso(),
+    };
+    await writeLockFile(lockPath(p, id), target);
+    return target;
+}
+/**
+ * Remove a lock owned by `owner`. No-op if not held by `owner`.
+ * Returns true if the lock was removed.
+ */
+export async function release(p, id, owner) {
+    const existing = await inspect(p, id);
+    if (!existing)
+        return false;
+    if (existing.owner !== owner)
+        return false;
+    try {
+        await fs.unlink(lockPath(p, id));
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            throw e;
+    }
+    return true;
+}
+/**
+ * Assert that the lock is either absent, expired, or owned by `owner`.
+ * Used by task transitions that may have been pre-claimed.
+ */
+export async function assertUsable(p, id, owner) {
+    const existing = await inspect(p, id);
+    if (!existing || isExpired(existing))
+        return;
+    if (existing.owner !== owner) {
+        throw new LockHeldError(existing.owner, existing.leasedUntil);
+    }
+}

package/dist/ok/migrate.js

@@ -0,0 +1,197 @@
+// ok/migrate.ts — one-shot import from a legacy `.ok/` workspace into the
+// new `.ok/` schema. Idempotent: rerunning reports what was newly imported
+// (i.e. what wasn't already in `.ok/`).
+//
+// Mapping:
+//   .ok/tasks.json  -> .ok/tasks/<id>.json   (Task)
+//   .ok/tasks/<id>/task.mdx  -> .ok/tasks/<id>.json  (description/body)
+//   .ok/tasks/<id>/comments.json -> .ok/tasks/<id>.json#comments (inlined evidence)
+//   .ok/board.json  -> index entries only (column/order state is folded
+//                            into Task.status / acceptance).
+//
+// Status mapping:
+//   board.json.state = "done"      -> ok Task.status = "done"
+//   board.json.state = "running"   -> ok Task.status = "in_progress"
+//   board.json.state = "waiting-for-input" -> ok Task.status = "in_progress"
+//   board.json.state = "cancelled" -> ok Task.status = "cancelled"
+//   board.json.state = "failed"    -> ok Task.status = "cancelled"
+//   otherwise                     -> ok Task.status = "pending"   (and column != backlog/todo)
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { newId, nowIso } from "./ids.js";
+import { initIfMissing, readTask, writeTask, } from "./storage.js";
+function mapStatus(t) {
+    const s = (t.state ?? "").toLowerCase();
+    if (s === "done")
+        return "done";
+    if (s === "running" || s === "waiting-for-input")
+        return "in_progress";
+    if (s === "cancelled" || s === "failed")
+        return "cancelled";
+    // Use column to infer: review -> review; doing -> in_progress; everything
+    // else (backlog, todo) stays pending.
+    const col = (t.column ?? "").toLowerCase();
+    if (col === "review")
+        return "review";
+    if (col === "doing")
+        return "in_progress";
+    return "pending";
+}
+function mapPriority(p) {
+    if (!p)
+        return undefined;
+    if (p === "urgent" || p === "high")
+        return "p0";
+    if (p === "normal")
+        return "p2";
+    if (p === "low")
+        return "p3";
+    return undefined;
+}
+function deriveNewId(legacy) {
+    const original = (legacy.id ?? "").trim();
+    // Old IDs are 8-char base-N strings (e.g. "bug3kx7p"). Reuse when well-formed
+    // to keep URLs / log references stable.
+    if (/^[A-Za-z0-9_-]{6,16}$/.test(original) && !original.startsWith("tsk-")) {
+        return `tsk-${original}`;
+    }
+    if (/^tsk-[A-Za-z0-9_-]+$/.test(original))
+        return original;
+    return newId("tsk");
+}
+async function importTaskFromJson(p, legacy, openkanDir) {
+    const id = deriveNewId(legacy);
+    const existing = await readTask(p, id);
+    if (existing)
+        return { id, created: false };
+    const task = {
+        schema: "ok.task.v1",
+        id,
+        title: (legacy.title ?? "untitled").slice(0, 200),
+        status: mapStatus(legacy),
+        createdAt: legacy.createdAt ?? nowIso(),
+        updatedAt: legacy.updatedAt ?? nowIso(),
+    };
+    if (legacy.agent)
+        task.owner = legacy.agent;
+    // Legacy Task type does not have `description`; pull from the .mdx body
+    // if available so migrated tasks aren't blank. Resolve relative to the
+    // openkanDir (not process.cwd) so the migration is portable.
+    if (legacy.mdxPath) {
+        const mdxAbs = path.isAbsolute(legacy.mdxPath)
+            ? legacy.mdxPath
+            : path.join(openkanDir, legacy.mdxPath);
+        try {
+            const raw = await fs.readFile(mdxAbs, "utf-8");
+            const fmStripped = raw.replace(/^---[\s\S]*?---\n?/, "");
+            if (fmStripped.trim().length > 0)
+                task.description = fmStripped.trim();
+        }
+        catch { /* optional */ }
+    }
+    const p2 = mapPriority(legacy.priority);
+    if (p2)
+        task.priority = p2;
+    if (Array.isArray(legacy.tags) && legacy.tags.length)
+        task.scopes = legacy.tags;
+    await writeTask(p, task);
+    return { id, created: true };
+}
+/**
+ * Run the migration in `root`. Returns counts and the list of imported
+ * task ids. If `.ok/` does not exist, returns zero-import result.
+ */
+export async function migrateFromOpenkan(root) {
+    const okPaths = await initIfMissing(root);
+    // Source: the legacy `.openkan/` directory. Even after the project itself
+    // migrated, this entry point is still useful for users that keep `.openkan/`
+    // data alongside an old `.ok/` installation (e.g. on shared filesystems).
+    const openkanDir = path.join(root, ".openkan");
+    let tasksJsonRaw;
+    try {
+        tasksJsonRaw = await fs.readFile(path.join(openkanDir, "tasks.json"), "utf-8");
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            throw e;
+    }
+    let boardJsonRaw;
+    try {
+        boardJsonRaw = await fs.readFile(path.join(openkanDir, "board.json"), "utf-8");
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            throw e;
+    }
+    const imported = [];
+    const skipped = [];
+    const seen = new Set();
+    const fromOpenkan = openkanDir;
+    if (tasksJsonRaw) {
+        const parsed = JSON.parse(tasksJsonRaw);
+        for (const legacy of parsed.tasks ?? []) {
+            const id = deriveNewId(legacy);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const res = await importTaskFromJson(okPaths, legacy, openkanDir);
+            if (res.created)
+                imported.push(res.id);
+            else
+                skipped.push(res.id);
+        }
+    }
+    if (boardJsonRaw) {
+        const parsed = JSON.parse(boardJsonRaw);
+        for (const legacy of parsed.tasks ?? []) {
+            if (legacy.archived)
+                continue;
+            const id = deriveNewId(legacy);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const res = await importTaskFromJson(okPaths, legacy, openkanDir);
+            if (res.created)
+                imported.push(res.id);
+            else
+                skipped.push(res.id);
+        }
+    }
+    return { fromOpenkan, imported: imported.length, skipped: skipped.length, tasks: imported };
+}
+/** Thin CLI wrapper used by `bin/ok.ts migrate-from-openkan`. */
+export async function cmdMigrateFromOpenkan(argv) {
+    // Accept `--path <dir>` (or `--path=<dir>`) as an explicit alias for the
+    // positional `root`. Reject a bare `--path` token (no value) with a clear
+    // error so a missing value cannot silently become the source directory.
+    const positionals = [];
+    let pathFlag;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--path") {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error("--path requires a directory argument");
+            }
+            pathFlag = next;
+            i++;
+            continue;
+        }
+        if (tok.startsWith("--path=")) {
+            pathFlag = tok.slice("--path=".length);
+            continue;
+        }
+        if (tok.startsWith("--") && tok !== "--list") {
+            throw new Error(`unknown flag: ${tok}`);
+        }
+        positionals.push(tok);
+    }
+    const root = pathFlag ?? positionals[0] ?? process.cwd();
+    const res = await migrateFromOpenkan(root);
+    process.stdout.write(`migrated ${res.imported} tasks from ${res.fromOpenkan} (skipped ${res.skipped} already in .ok/)\n`);
+    if (argv.includes("--list")) {
+        for (const id of res.tasks)
+            process.stdout.write(`  ${id}\n`);
+    }
+    return 0;
+}