@polderlabs/openkan 0.4.0

package/dist/ok/commands/prd.js

@@ -0,0 +1,202 @@
+// ok/commands/prd.ts — `ok prd add|list|show|update`.
+import { touch, byUpdatedDesc, } from "../schemas.js";
+import { initIfMissing, readPrd, writePrd, listPrds, readConfig, rebuildIndex, paths as computePaths, } from "../storage.js";
+import { newId, nowIso, parseArgs, flagString, flagCsv, flagBool } from "../ids.js";
+const STATUSES = ["draft", "active", "shipped", "abandoned"];
+const GOAL_STATUSES = ["open", "in_progress", "met", "dropped"];
+const MILESTONE_STATUSES = ["open", "hit", "missed", "dropped"];
+function parsePrdStatus(v) {
+    if (!v)
+        return undefined;
+    if (!STATUSES.includes(v))
+        throw new Error(`status must be one of ${STATUSES.join("|")}`);
+    return v;
+}
+function parseGoalStatus(v) {
+    if (!v)
+        throw new Error("goal status required");
+    if (!GOAL_STATUSES.includes(v)) {
+        throw new Error(`goal status must be one of ${GOAL_STATUSES.join("|")}`);
+    }
+    return v;
+}
+function parseMilestoneStatus(v) {
+    if (!v)
+        throw new Error("milestone status required");
+    if (!MILESTONE_STATUSES.includes(v)) {
+        throw new Error(`milestone status must be one of ${MILESTONE_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 PRDs)\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 runPrd(args) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "add": return cmdPrdAdd(rest);
+        case "list": return cmdPrdList(rest);
+        case "show": return cmdPrdShow(rest);
+        case "update": return cmdPrdUpdate(rest);
+        default:
+            process.stderr.write("usage: ok prd <add|list|show|update>\n");
+            return 2;
+    }
+}
+async function cmdPrdAdd(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length === 0) {
+        process.stderr.write("usage: ok prd add <title> [--vision …] [--goals g1|g2|g3] [--non-goals …] [--milestones m1|m2]\n");
+        return 2;
+    }
+    const title = positionals.join(" ");
+    const vision = flagString(flags, "vision") ?? "";
+    if (!vision) {
+        process.stderr.write("--vision is required (one paragraph)\n");
+        return 2;
+    }
+    const goalTexts = flagCsv(flags, "goals");
+    const nonGoals = flagCsv(flags, "non-goals");
+    const metricSpecs = flagCsv(flags, "metrics");
+    const milestoneTexts = flagCsv(flags, "milestones");
+    const owners = flagCsv(flags, "owners");
+    const cadence = flagString(flags, "review-cadence");
+    const p = await paths();
+    const now = nowIso();
+    const prd = {
+        schema: "ok.prd.v1",
+        id: newId("prd"),
+        title,
+        vision,
+        goals: goalTexts.map((text, i) => ({
+            id: `g${i + 1}`,
+            text,
+            status: "open",
+        })),
+        nonGoals,
+        successMetrics: metricSpecs.map((spec) => {
+            const [name, target, current] = spec.split("|");
+            return {
+                name: name ?? spec,
+                target: target ?? "",
+                current: current || undefined,
+            };
+        }),
+        milestones: milestoneTexts.map((text, i) => ({
+            id: `m${i + 1}`,
+            title: text,
+            status: "open",
+        })),
+        risks: [],
+        plans: [],
+        owners: owners.length ? owners : flagString(flags, "owner") ? [flagString(flags, "owner")] : [],
+        status: "draft",
+        createdAt: now,
+        updatedAt: now,
+    };
+    if (cadence)
+        prd.reviewCadence = cadence;
+    await writePrd(p, prd);
+    await rebuildIndex(p);
+    process.stdout.write(`${prd.id}\n`);
+    return 0;
+}
+async function cmdPrdList(args) {
+    const { flags } = parseArgs(args);
+    const p = await paths();
+    let prds = await listPrds(p);
+    const status = parsePrdStatus(flagString(flags, "status"));
+    if (status)
+        prds = prds.filter((pr) => pr.status === status);
+    prds = byUpdatedDesc(prds);
+    if (flagBool(flags, "json")) {
+        process.stdout.write(JSON.stringify(prds, null, 2) + "\n");
+        return 0;
+    }
+    printTable(prds.map((pr) => ({ id: pr.id, status: pr.status, title: pr.title, updatedAt: pr.updatedAt })));
+    return 0;
+}
+async function cmdPrdShow(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok prd show <id> [--json]\n");
+        return 2;
+    }
+    const p = await paths();
+    const prd = await readPrd(p, positionals[0]);
+    if (!prd) {
+        process.stderr.write(`no such PRD: ${positionals[0]}\n`);
+        return 1;
+    }
+    if (flagBool(flags, "json")) {
+        process.stdout.write(JSON.stringify(prd, null, 2) + "\n");
+        return 0;
+    }
+    for (const [k, v] of Object.entries(prd)) {
+        process.stdout.write(`${k}: ${typeof v === "string" ? v : JSON.stringify(v)}\n`);
+    }
+    return 0;
+}
+async function cmdPrdUpdate(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok prd update <id> [--status …] [--goal g1 --goal-status met] [--milestone m1 --milestone-status hit] [--append-plan pln-…] [--review-cadence weekly]\n");
+        return 2;
+    }
+    const p = await paths();
+    const existing = await readPrd(p, positionals[0]);
+    if (!existing) {
+        process.stderr.write(`no such PRD: ${positionals[0]}\n`);
+        return 1;
+    }
+    let next = touch(existing);
+    const status = parsePrdStatus(flagString(flags, "status"));
+    if (status)
+        next.status = status;
+    const goalId = flagString(flags, "goal");
+    const goalStatusRaw = flagString(flags, "goal-status");
+    if (goalId) {
+        const goalStatus = parseGoalStatus(goalStatusRaw);
+        next = {
+            ...next,
+            goals: next.goals.map((g) => (g.id === goalId ? { ...g, status: goalStatus } : g)),
+        };
+    }
+    const milestoneId = flagString(flags, "milestone");
+    const milestoneStatusRaw = flagString(flags, "milestone-status");
+    if (milestoneId) {
+        const milestoneStatus = parseMilestoneStatus(milestoneStatusRaw);
+        next = {
+            ...next,
+            milestones: next.milestones.map((m) => (m.id === milestoneId ? { ...m, status: milestoneStatus } : m)),
+        };
+    }
+    const appendPlan = flagString(flags, "append-plan");
+    if (appendPlan && !next.plans.includes(appendPlan)) {
+        next.plans = [...next.plans, appendPlan];
+    }
+    const cadence = flagString(flags, "review-cadence");
+    if (cadence !== undefined)
+        next.reviewCadence = cadence;
+    const nextReview = flagString(flags, "next-review");
+    if (nextReview !== undefined)
+        next.nextReviewAt = nextReview;
+    await writePrd(p, next);
+    await rebuildIndex(p);
+    process.stdout.write(`${next.id}\n`);
+    return 0;
+}

package/dist/ok/commands/progress.js

@@ -0,0 +1,31 @@
+import { paths, listTasks, listPlans, listPrds, readPrd } from "../storage.js";
+import { parseArgs, flagString, flagBool } from "../ids.js";
+export async function runProgress(args) {
+    const { flags } = parseArgs(args);
+    const p = paths(process.cwd());
+    const prdId = flagString(flags, 'prd');
+    if (prdId && !await readPrd(p, prdId))
+        throw new Error(`no such PRD: ${prdId}`);
+    const [allTasks, allPlans, allPrds] = await Promise.all([listTasks(p), listPlans(p), listPrds(p)]);
+    const prds = allPrds.filter(item => !prdId || item.id === prdId);
+    const plans = allPlans.filter(item => !prdId || item.prd === prdId || prds.some(prd => prd.plans.includes(item.id)));
+    const tasks = allTasks.filter(item => !prdId || item.prd === prdId || plans.some(plan => plan.id === item.plan || plan.tasks.includes(item.id)));
+    const summary = (items, states, done, excluded) => {
+        const counts = Object.fromEntries(states.map(state => [state, 0]));
+        for (const item of items)
+            counts[item.status] = (counts[item.status] || 0) + 1;
+        const total = items.length;
+        const actionable = total - excluded.reduce((sum, state) => sum + (counts[state] || 0), 0);
+        return { ...counts, total, percentComplete: actionable ? Math.round((counts[done] || 0) / actionable * 100) : 0 };
+    };
+    const report = {
+        project: process.cwd(), prd: prdId || null,
+        tasks: summary(tasks, ['pending', 'in_progress', 'review', 'done', 'cancelled'], 'done', ['cancelled']),
+        plans: summary(plans, ['draft', 'active', 'blocked', 'complete', 'abandoned'], 'complete', ['abandoned']),
+        goals: summary(prds.flatMap(prd => prd.goals), ['open', 'in_progress', 'met', 'dropped'], 'met', ['dropped']),
+        prds: summary(prds, ['draft', 'active', 'shipped', 'abandoned'], 'shipped', ['abandoned']),
+        nextTasks: tasks.filter(task => task.status === 'pending' && (task.deps || []).every(id => allTasks.some(dependency => dependency.id === id && dependency.status === 'done'))).map(task => ({ id: task.id, title: task.title, owner: task.owner || null })),
+    };
+    process.stdout.write(flagBool(flags, 'json') ? `${JSON.stringify(report, null, 2)}\n` : `Project: ${report.project}\n${Object.entries(report).filter(([name]) => ['tasks', 'plans', 'goals', 'prds'].includes(name)).map(([name, value]) => `${name}: ${value.total} total, ${value.percentComplete}% complete`).join('\n')}\nReady tasks: ${report.nextTasks.map(task => task.id).join(', ') || 'none'}\n`);
+    return 0;
+}

package/dist/ok/commands/task.js

@@ -0,0 +1,377 @@
+// ok/commands/task.ts — `ok task add|list|show|update|claim|heartbeat|complete|cancel`.
+import { touch, byUpdatedDesc, } from "../schemas.js";
+import { initIfMissing, readTask, writeTask, listTasks, readConfig, rebuildIndex, paths as computePaths, } from "../storage.js";
+import { newId, nowIso, parseArgs, flagString, flagCsv, flagBool, runMain } from "../ids.js";
+import { claim, heartbeat, release, assertUsable, LockHeldError } from "../lock.js";
+const STATUSES = ["pending", "in_progress", "review", "done", "cancelled"];
+const PRIORITIES = ["p0", "p1", "p2", "p3"];
+function parseStatus(v) {
+    if (!v)
+        return undefined;
+    if (!STATUSES.includes(v)) {
+        throw new Error(`status must be one of ${STATUSES.join("|")}`);
+    }
+    return v;
+}
+function parsePriority(v) {
+    if (!v)
+        return undefined;
+    if (!PRIORITIES.includes(v)) {
+        throw new Error(`priority must be one of ${PRIORITIES.join("|")}`);
+    }
+    return v;
+}
+async function paths() {
+    const p = computePaths(process.cwd());
+    // Auto-init if a session invokes commands but hasn't run `ok init` yet.
+    if (!await readConfig(p)) {
+        return initIfMissing(process.cwd());
+    }
+    return p;
+}
+function printTable(rows) {
+    if (rows.length === 0) {
+        process.stdout.write("(no tasks)\n");
+        return;
+    }
+    const w = Math.max(2, ...rows.map((r) => r.id.length));
+    const ts = Math.max(10, ...rows.map((r) => r.updatedAt.length));
+    for (const r of rows) {
+        process.stdout.write(`${r.id.padEnd(w)}  ${r.status.padEnd(11)}  ${r.updatedAt.padEnd(ts)}  ${r.title}\n`);
+    }
+}
+export async function runTask(args) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "add": return cmdTaskAdd(rest);
+        case "list": return cmdTaskList(rest);
+        case "show": return cmdTaskShow(rest);
+        case "update": return cmdTaskUpdate(rest);
+        case "claim": return cmdTaskClaim(rest);
+        case "heartbeat": return cmdTaskHeartbeat(rest);
+        case "complete": return cmdTaskComplete(rest);
+        case "cancel": return cmdTaskCancel(rest);
+        case "release": return cmdTaskRelease(rest);
+        default:
+            process.stderr.write("usage: ok task <add|list|show|update|claim|heartbeat|complete|cancel|release>\n");
+            return 2;
+    }
+}
+function titleFromArgs(positionals) {
+    if (positionals.length === 0) {
+        throw new Error("ok task add requires a title positional");
+    }
+    return positionals.join(" ");
+}
+async function cmdTaskAdd(args) {
+    const { positionals, flags } = parseArgs(args);
+    const title = titleFromArgs(positionals);
+    if (!title || title.trim().length === 0) {
+        throw new Error("ok task add: title must be a non-empty, non-whitespace string");
+    }
+    if (title.length > 200)
+        throw new Error("title must be <= 200 chars");
+    const status = parseStatus(flagString(flags, "status")) ?? "pending";
+    const p = await paths();
+    const cfg = (await readConfig(p));
+    const now = nowIso();
+    const task = {
+        schema: "ok.task.v1",
+        id: newId("tsk"),
+        title,
+        status,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const owner = flagString(flags, "owner");
+    if (owner)
+        task.owner = owner;
+    else if (cfg.defaultOwner)
+        task.owner = cfg.defaultOwner;
+    const priority = parsePriority(flagString(flags, "priority"));
+    if (priority)
+        task.priority = priority;
+    const plan = flagString(flags, "plan");
+    if (plan)
+        task.plan = plan;
+    const prd = flagString(flags, "prd");
+    if (prd)
+        task.prd = prd;
+    const scopes = flagCsv(flags, "scope");
+    if (scopes.length)
+        task.scopes = scopes;
+    const deps = flagCsv(flags, "deps");
+    if (deps.length)
+        task.deps = deps;
+    const desc = flagString(flags, "description");
+    if (desc)
+        task.description = desc;
+    const acceptance = flagCsv(flags, "acceptance");
+    if (acceptance.length)
+        task.acceptance = acceptance;
+    await writeTask(p, task);
+    await refreshIndex(p);
+    process.stdout.write(`${task.id}\n`);
+    return 0;
+}
+async function cmdTaskList(args) {
+    const { flags } = parseArgs(args);
+    const p = await paths();
+    let tasks = await listTasks(p);
+    const wantJson = flagBool(flags, "json");
+    const filterStatus = parseStatus(flagString(flags, "status"));
+    if (filterStatus)
+        tasks = tasks.filter((t) => t.status === filterStatus);
+    const owner = flagString(flags, "owner");
+    if (owner)
+        tasks = tasks.filter((t) => t.owner === owner);
+    const plan = flagString(flags, "plan");
+    if (plan)
+        tasks = tasks.filter((t) => t.plan === plan);
+    const prd = flagString(flags, "prd");
+    if (prd)
+        tasks = tasks.filter((t) => t.prd === prd);
+    tasks = byUpdatedDesc(tasks);
+    if (wantJson) {
+        process.stdout.write(JSON.stringify(tasks, null, 2) + "\n");
+    }
+    else {
+        const rows = tasks.map((t) => ({
+            id: t.id, status: t.status, title: t.title, updatedAt: t.updatedAt,
+        }));
+        printTable(rows);
+    }
+    return 0;
+}
+async function cmdTaskShow(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task show <id> [--json]\n");
+        return 2;
+    }
+    const p = await paths();
+    const task = await readTask(p, positionals[0]);
+    if (!task) {
+        process.stderr.write(`no such task: ${positionals[0]}\n`);
+        return 1;
+    }
+    if (flagBool(flags, "json")) {
+        process.stdout.write(JSON.stringify(task, null, 2) + "\n");
+    }
+    else {
+        for (const [k, v] of Object.entries(task)) {
+            process.stdout.write(`${k}: ${typeof v === "string" ? v : JSON.stringify(v)}\n`);
+        }
+    }
+    return 0;
+}
+async function cmdTaskUpdate(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task update <id> [--status …] [--owner …] [--priority …] [--evidence text] [--acceptance a,b,c]\n");
+        return 2;
+    }
+    const p = await paths();
+    const existing = await readTask(p, positionals[0]);
+    if (!existing) {
+        process.stderr.write(`no such task: ${positionals[0]}\n`);
+        return 1;
+    }
+    let next = touch(existing);
+    const status = parseStatus(flagString(flags, "status"));
+    if (status) {
+        if (status !== existing.status) {
+            next.status = status;
+            if (status === "in_progress" && !next.startedAt)
+                next.startedAt = nowIso();
+            if ((status === "done" || status === "cancelled") && !next.completedAt)
+                next.completedAt = nowIso();
+            if (status !== "done" && status !== "cancelled") {
+                next.completedAt = undefined;
+            }
+        }
+    }
+    const owner = flagString(flags, "owner");
+    if (owner !== undefined)
+        next.owner = owner;
+    const priority = parsePriority(flagString(flags, "priority"));
+    if (priority)
+        next.priority = priority;
+    const evidence = flagString(flags, "evidence");
+    if (evidence !== undefined) {
+        next.evidence = [...(existing.evidence ?? []), evidence];
+    }
+    const acceptance = flagCsv(flags, "acceptance");
+    if (acceptance.length) {
+        next.acceptance = [...(existing.acceptance ?? []), ...acceptance];
+    }
+    const desc = flagString(flags, "description");
+    if (desc !== undefined)
+        next.description = desc;
+    await writeTask(p, next);
+    await refreshIndex(p);
+    process.stdout.write(`${next.id}\n`);
+    return 0;
+}
+async function cmdTaskClaim(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task claim <id> --owner X [--lease-ms N]\n");
+        return 2;
+    }
+    const owner = flagString(flags, "owner");
+    if (!owner) {
+        process.stderr.write("--owner is required\n");
+        return 2;
+    }
+    const leaseMsRaw = flagString(flags, "lease-ms");
+    const leaseMs = leaseMsRaw ? Number(leaseMsRaw) : undefined;
+    if (leaseMs !== undefined && (!Number.isFinite(leaseMs) || leaseMs <= 0)) {
+        process.stderr.write("--lease-ms must be a positive integer\n");
+        return 2;
+    }
+    const p = await paths();
+    try {
+        await claim(p, positionals[0], owner, { leaseMs });
+    }
+    catch (e) {
+        if (e instanceof LockHeldError) {
+            process.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    const task = await readTask(p, positionals[0]);
+    if (task && task.status === "pending") {
+        const next = touch({ ...task, status: "in_progress", startedAt: task.startedAt ?? nowIso(), owner });
+        await writeTask(p, next);
+        await refreshIndex(p);
+    }
+    else if (task) {
+        const next = touch({ ...task, owner });
+        await writeTask(p, next);
+        await refreshIndex(p);
+    }
+    process.stdout.write(`${positionals[0]}\n`);
+    return 0;
+}
+async function cmdTaskHeartbeat(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task heartbeat <id> --owner X [--lease-ms N]\n");
+        return 2;
+    }
+    const owner = flagString(flags, "owner");
+    if (!owner) {
+        process.stderr.write("--owner is required\n");
+        return 2;
+    }
+    const leaseMsRaw = flagString(flags, "lease-ms");
+    const leaseMs = leaseMsRaw ? Number(leaseMsRaw) : undefined;
+    const p = await paths();
+    await heartbeat(p, positionals[0], owner, { leaseMs });
+    process.stdout.write(`${positionals[0]}\n`);
+    return 0;
+}
+async function cmdTaskComplete(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task complete <id> --owner X --evidence \"<text>\"\n");
+        return 2;
+    }
+    const owner = flagString(flags, "owner");
+    if (!owner) {
+        process.stderr.write("--owner is required\n");
+        return 2;
+    }
+    const evidence = flagString(flags, "evidence");
+    if (!evidence) {
+        process.stderr.write("--evidence is required (commit shas, file:line, URLs, etc.)\n");
+        return 2;
+    }
+    const p = await paths();
+    await assertUsable(p, positionals[0], owner);
+    const task = await readTask(p, positionals[0]);
+    if (!task) {
+        process.stderr.write(`no such task: ${positionals[0]}\n`);
+        return 1;
+    }
+    const now = nowIso();
+    const next = touch({
+        ...task,
+        status: "done",
+        owner,
+        completedAt: task.completedAt ?? now,
+        evidence: [...(task.evidence ?? []), evidence],
+    });
+    await writeTask(p, next);
+    await release(p, positionals[0], owner);
+    await refreshIndex(p);
+    process.stdout.write(`${next.id}\n`);
+    return 0;
+}
+async function cmdTaskCancel(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task cancel <id> --owner X --reason \"<text>\"\n");
+        return 2;
+    }
+    const owner = flagString(flags, "owner");
+    if (!owner) {
+        process.stderr.write("--owner is required\n");
+        return 2;
+    }
+    const reason = flagString(flags, "reason");
+    if (!reason) {
+        process.stderr.write("--reason is required\n");
+        return 2;
+    }
+    const p = await paths();
+    await assertUsable(p, positionals[0], owner);
+    const task = await readTask(p, positionals[0]);
+    if (!task) {
+        process.stderr.write(`no such task: ${positionals[0]}\n`);
+        return 1;
+    }
+    const next = touch({
+        ...task,
+        status: "cancelled",
+        owner,
+        completedAt: task.completedAt ?? nowIso(),
+        evidence: [...(task.evidence ?? []), `cancelled: ${reason}`],
+    });
+    await writeTask(p, next);
+    await release(p, positionals[0], owner);
+    await refreshIndex(p);
+    process.stdout.write(`${next.id}\n`);
+    return 0;
+}
+async function cmdTaskRelease(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length !== 1) {
+        process.stderr.write("usage: ok task release <id> --owner X\n");
+        return 2;
+    }
+    const owner = flagString(flags, "owner");
+    if (!owner) {
+        process.stderr.write("--owner is required\n");
+        return 2;
+    }
+    const p = await paths();
+    const removed = await release(p, positionals[0], owner);
+    process.stdout.write(removed ? `${positionals[0]}\n` : `no lock for ${positionals[0]}\n`);
+    return removed ? 0 : 1;
+}
+async function refreshIndex(p) {
+    try {
+        await rebuildIndex(p);
+    }
+    catch (e) {
+        process.stderr.write(`warning: index rebuild failed: ${e.message}\n`);
+    }
+}
+// `node --experimental-strip-types ok/commands/task.ts [args]` invocation
+// (used by bin/ok.ts shell wrapper for per-subprocess isolation).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await runMain(async () => runTask(process.argv.slice(2)));
+}