@polderlabs/openkan 0.4.0

package/dist/ok/schemas.js

@@ -0,0 +1,402 @@
+// ok/schemas.ts — TypeScript types and validators for every planning entity.
+//
+// The single source of truth lives in JSDoc-typed TypeScript interfaces and
+// is materialised to JSON via the standalone `validate*` helpers below.
+// `ok doctor` runs every persisted JSON through these helpers and reports
+// the first offending path; consumers that already trust the data should
+// still treat the helpers as the contract.
+import { idSuffix, isoCompare, nowIso } from "./ids.js";
+export function isTask(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const t = obj;
+    if (t.schema !== "ok.task.v1")
+        return false;
+    if (typeof t.id !== "string" || !/^tsk-[A-Za-z0-9_-]+$/.test(t.id))
+        return false;
+    if (typeof t.title !== "string" || t.title.length === 0 || t.title.length > 200)
+        return false;
+    const statuses = ["pending", "in_progress", "review", "done", "cancelled"];
+    if (typeof t.status !== "string" || !statuses.includes(t.status))
+        return false;
+    if (!isIso(t.createdAt) || !isIso(t.updatedAt))
+        return false;
+    if (t.startedAt !== undefined && !isIso(t.startedAt))
+        return false;
+    if (t.completedAt !== undefined && !isIso(t.completedAt))
+        return false;
+    if (t.priority !== undefined && !["p0", "p1", "p2", "p3"].includes(t.priority))
+        return false;
+    if (t.description !== undefined && typeof t.description !== "string")
+        return false;
+    if (t.owner !== undefined && typeof t.owner !== "string")
+        return false;
+    if (t.plan !== undefined && (typeof t.plan !== "string" || !/^pln-/.test(t.plan)))
+        return false;
+    if (t.prd !== undefined && (typeof t.prd !== "string" || !/^prd-/.test(t.prd)))
+        return false;
+    if (t.scopes !== undefined && !isStringArray(t.scopes))
+        return false;
+    if (t.deps !== undefined && !isStringArray(t.deps))
+        return false;
+    if (t.evidence !== undefined && !isStringArray(t.evidence))
+        return false;
+    if (t.acceptance !== undefined && !isStringArray(t.acceptance))
+        return false;
+    return true;
+}
+export function validateTask(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return { reason: "task must be an object" };
+    }
+    const t = obj;
+    if (t.schema !== "ok.task.v1")
+        return { reason: `unknown schema ${String(t.schema)}` };
+    if (typeof t.id !== "string" || !/^tsk-[A-Za-z0-9_-]+$/.test(t.id)) {
+        return { id: typeof t.id === "string" ? t.id : undefined, reason: "id must match tsk-<id>" };
+    }
+    if (typeof t.title !== "string")
+        return { id: t.id, reason: "title must be a string" };
+    if (t.title.length === 0 || t.title.length > 200) {
+        return { id: t.id, reason: "title must be 1..200 chars" };
+    }
+    const statuses = ["pending", "in_progress", "review", "done", "cancelled"];
+    if (typeof t.status !== "string" || !statuses.includes(t.status)) {
+        return { id: t.id, reason: `status must be one of ${statuses.join("|")}` };
+    }
+    if (!isIso(t.createdAt))
+        return { id: t.id, reason: "createdAt must be ISO timestamp" };
+    if (!isIso(t.updatedAt))
+        return { id: t.id, reason: "updatedAt must be ISO timestamp" };
+    if (t.startedAt !== undefined && !isIso(t.startedAt)) {
+        return { id: t.id, reason: "startedAt must be ISO timestamp when present" };
+    }
+    if (t.completedAt !== undefined && !isIso(t.completedAt)) {
+        return { id: t.id, reason: "completedAt must be ISO timestamp when present" };
+    }
+    if (t.priority !== undefined && !["p0", "p1", "p2", "p3"].includes(t.priority)) {
+        return { id: t.id, reason: "priority must be p0|p1|p2|p3 when present" };
+    }
+    if (t.scopes !== undefined && !isStringArray(t.scopes)) {
+        return { id: t.id, reason: "scopes must be string[] when present" };
+    }
+    if (t.deps !== undefined && !isStringArray(t.deps)) {
+        return { id: t.id, reason: "deps must be string[] when present" };
+    }
+    if (t.evidence !== undefined && !isStringArray(t.evidence)) {
+        return { id: t.id, reason: "evidence must be string[] when present" };
+    }
+    if (t.acceptance !== undefined && !isStringArray(t.acceptance)) {
+        return { id: t.id, reason: "acceptance must be string[] when present" };
+    }
+    if (t.plan !== undefined && (typeof t.plan !== "string" || !/^pln-/.test(t.plan))) {
+        return { id: t.id, reason: "plan must be a pln-<id> string when present" };
+    }
+    if (t.prd !== undefined && (typeof t.prd !== "string" || !/^prd-/.test(t.prd))) {
+        return { id: t.id, reason: "prd must be a prd-<id> string when present" };
+    }
+    return null;
+}
+export function isPlan(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const p = obj;
+    if (p.schema !== "ok.plan.v1")
+        return false;
+    if (typeof p.id !== "string" || !/^pln-[A-Za-z0-9_-]+$/.test(p.id))
+        return false;
+    if (typeof p.title !== "string" || p.title.length === 0)
+        return false;
+    if (typeof p.summary !== "string")
+        return false;
+    const statuses = ["draft", "active", "blocked", "complete", "abandoned"];
+    if (typeof p.status !== "string" || !statuses.includes(p.status))
+        return false;
+    if (!Array.isArray(p.tasks) || !p.tasks.every((x) => typeof x === "string"))
+        return false;
+    if (!Array.isArray(p.acceptance) || !p.acceptance.every((x) => typeof x === "string"))
+        return false;
+    if (!isIso(p.createdAt) || !isIso(p.updatedAt))
+        return false;
+    if (p.prd !== undefined && (typeof p.prd !== "string" || !/^prd-/.test(p.prd)))
+        return false;
+    if (p.phase !== undefined && typeof p.phase !== "string")
+        return false;
+    return true;
+}
+export function validatePlan(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return { reason: "plan must be an object" };
+    const p = obj;
+    if (p.schema !== "ok.plan.v1")
+        return { reason: `unknown schema ${String(p.schema)}` };
+    if (typeof p.id !== "string" || !/^pln-[A-Za-z0-9_-]+$/.test(p.id)) {
+        return { id: typeof p.id === "string" ? p.id : undefined, reason: "id must match pln-<id>" };
+    }
+    if (typeof p.title !== "string" || p.title.length === 0) {
+        return { id: typeof p.id === "string" ? p.id : undefined, reason: "title required" };
+    }
+    if (typeof p.summary !== "string") {
+        return { id: p.id, reason: "summary required" };
+    }
+    const statuses = ["draft", "active", "blocked", "complete", "abandoned"];
+    if (typeof p.status !== "string" || !statuses.includes(p.status)) {
+        return { id: p.id, reason: `status must be one of ${statuses.join("|")}` };
+    }
+    if (!Array.isArray(p.tasks) || !p.tasks.every((x) => typeof x === "string")) {
+        return { id: p.id, reason: "tasks must be string[]" };
+    }
+    if (!Array.isArray(p.acceptance) || !p.acceptance.every((x) => typeof x === "string")) {
+        return { id: p.id, reason: "acceptance must be string[]" };
+    }
+    if (!isIso(p.createdAt))
+        return { id: p.id, reason: "createdAt must be ISO" };
+    if (!isIso(p.updatedAt))
+        return { id: p.id, reason: "updatedAt must be ISO" };
+    return null;
+}
+export function isPrd(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const p = obj;
+    if (p.schema !== "ok.prd.v1")
+        return false;
+    if (typeof p.id !== "string" || !/^prd-[A-Za-z0-9_-]+$/.test(p.id))
+        return false;
+    if (typeof p.title !== "string" || p.title.length === 0)
+        return false;
+    if (typeof p.vision !== "string")
+        return false;
+    const statuses = ["draft", "active", "shipped", "abandoned"];
+    if (typeof p.status !== "string" || !statuses.includes(p.status))
+        return false;
+    if (!isIso(p.createdAt) || !isIso(p.updatedAt))
+        return false;
+    if (!Array.isArray(p.goals) || !p.goals.every(isGoal))
+        return false;
+    if (!Array.isArray(p.nonGoals) || !p.nonGoals.every((x) => typeof x === "string"))
+        return false;
+    if (!Array.isArray(p.successMetrics) || !p.successMetrics.every(isMetric))
+        return false;
+    if (!Array.isArray(p.milestones) || !p.milestones.every(isMilestone))
+        return false;
+    if (!Array.isArray(p.risks) || !p.risks.every(isRisk))
+        return false;
+    if (!Array.isArray(p.plans) || !p.plans.every((x) => typeof x === "string" && /^pln-/.test(x)))
+        return false;
+    if (!Array.isArray(p.owners) || !p.owners.every((x) => typeof x === "string"))
+        return false;
+    if (p.reviewCadence !== undefined && typeof p.reviewCadence !== "string")
+        return false;
+    if (p.nextReviewAt !== undefined && !isIso(p.nextReviewAt))
+        return false;
+    return true;
+}
+export function validatePrd(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return { reason: "prd must be an object" };
+    const p = obj;
+    if (p.schema !== "ok.prd.v1")
+        return { reason: `unknown schema ${String(p.schema)}` };
+    if (typeof p.id !== "string" || !/^prd-[A-Za-z0-9_-]+$/.test(p.id)) {
+        return { id: typeof p.id === "string" ? p.id : undefined, reason: "id must match prd-<id>" };
+    }
+    if (typeof p.title !== "string" || p.title.length === 0) {
+        return { id: p.id, reason: "title required" };
+    }
+    if (typeof p.vision !== "string") {
+        return { id: p.id, reason: "vision required" };
+    }
+    const statuses = ["draft", "active", "shipped", "abandoned"];
+    if (typeof p.status !== "string" || !statuses.includes(p.status)) {
+        return { id: p.id, reason: `status must be one of ${statuses.join("|")}` };
+    }
+    if (!Array.isArray(p.goals) || !p.goals.every(isGoal)) {
+        return { id: p.id, reason: "goals must be well-formed" };
+    }
+    if (!Array.isArray(p.nonGoals) || !p.nonGoals.every((x) => typeof x === "string")) {
+        return { id: p.id, reason: "nonGoals must be string[]" };
+    }
+    if (!Array.isArray(p.successMetrics) || !p.successMetrics.every(isMetric)) {
+        return { id: p.id, reason: "successMetrics must be well-formed" };
+    }
+    if (!Array.isArray(p.milestones) || !p.milestones.every(isMilestone)) {
+        return { id: p.id, reason: "milestones must be well-formed" };
+    }
+    if (!Array.isArray(p.risks) || !p.risks.every(isRisk)) {
+        return { id: p.id, reason: "risks must be well-formed" };
+    }
+    if (!Array.isArray(p.plans) || !p.plans.every((x) => typeof x === "string" && /^pln-/.test(x))) {
+        return { id: p.id, reason: "plans must be pln-<id> strings" };
+    }
+    if (!Array.isArray(p.owners) || !p.owners.every((x) => typeof x === "string")) {
+        return { id: p.id, reason: "owners must be string[]" };
+    }
+    if (!isIso(p.createdAt))
+        return { id: p.id, reason: "createdAt must be ISO" };
+    if (!isIso(p.updatedAt))
+        return { id: p.id, reason: "updatedAt must be ISO" };
+    return null;
+}
+function isGoal(g) {
+    if (typeof g !== "object" || g === null)
+        return false;
+    const o = g;
+    if (typeof o.id !== "string" || typeof o.text !== "string")
+        return false;
+    return ["open", "in_progress", "met", "dropped"].includes(o.status);
+}
+function isMetric(m) {
+    if (typeof m !== "object" || m === null)
+        return false;
+    const o = m;
+    return typeof o.name === "string" && typeof o.target === "string"
+        && (o.current === undefined || typeof o.current === "string");
+}
+function isMilestone(m) {
+    if (typeof m !== "object" || m === null)
+        return false;
+    const o = m;
+    if (typeof o.id !== "string" || typeof o.title !== "string")
+        return false;
+    return ["open", "hit", "missed", "dropped"].includes(o.status)
+        && (o.dueBy === undefined || isIso(o.dueBy));
+}
+function isRisk(r) {
+    if (typeof r !== "object" || r === null)
+        return false;
+    const o = r;
+    if (typeof o.id !== "string" || typeof o.text !== "string")
+        return false;
+    return ["low", "med", "high"].includes(o.severity)
+        && (o.mitigation === undefined || typeof o.mitigation === "string");
+}
+export function isOkConfig(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const c = obj;
+    if (c.schema !== "ok.config.v1")
+        return false;
+    if (c.version !== 1)
+        return false;
+    if (!isIso(c.createdAt) || !isIso(c.updatedAt))
+        return false;
+    if (c.defaultOwner !== undefined && typeof c.defaultOwner !== "string")
+        return false;
+    return true;
+}
+export function isOkIndex(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const i = obj;
+    if (i.schema !== "ok.index.v1")
+        return false;
+    if (!Array.isArray(i.tasks) || !Array.isArray(i.plans) || !Array.isArray(i.prds))
+        return false;
+    if (!isIso(i.updatedAt))
+        return false;
+    for (const arr of [i.tasks, i.plans, i.prds]) {
+        for (const e of arr) {
+            if (!e || typeof e !== "object")
+                return false;
+            const o = e;
+            if (typeof o.id !== "string" || typeof o.status !== "string" ||
+                typeof o.title !== "string" || typeof o.updatedAt !== "string") {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function isIso(v) {
+    return typeof v === "string" && !Number.isNaN(Date.parse(v));
+}
+/** Bump `updatedAt` to now. Returns a new object. */
+export function touch(entity) {
+    return { ...entity, updatedAt: nowIso() };
+}
+/** Stable sort by `updatedAt` descending. Returns a new array. */
+export function byUpdatedDesc(items) {
+    return [...items].sort((a, b) => isoCompare(b.updatedAt, a.updatedAt));
+}
+export function isAgentProfile(v) {
+    return (typeof v === "object" && v !== null &&
+        v.schema === "openkan.agent-profile.v1");
+}
+export function isAgentsConfig(v) {
+    return (typeof v === "object" && v !== null &&
+        v.schema === "openkan.agents.v1");
+}
+const VALID_KINDS = new Set(["claude-code", "codex-cli", "cursor", "cline", "custom"]);
+/**
+ * Validate a single AgentProfile.
+ * Returns null on success, or the first error found.
+ */
+export function validateAgentProfile(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return { path: "", reason: "expected object" };
+    }
+    const o = obj;
+    if (typeof o["id"] !== "string" || !o["id"]) {
+        return { path: "id", reason: "required, non-empty string" };
+    }
+    if (!o["kind"] || !VALID_KINDS.has(o["kind"])) {
+        return { path: "kind", reason: `required, must be one of: ${[...VALID_KINDS].join(", ")}` };
+    }
+    if (typeof o["bin"] !== "string" || !o["bin"].trim()) {
+        return { path: "bin", reason: "required, non-empty string" };
+    }
+    if (o["description"] !== undefined && typeof o["description"] !== "string") {
+        return { path: "description", reason: "optional, must be string" };
+    }
+    if (o["meta"] !== undefined && (typeof o["meta"] !== "object" || o["meta"] === null || Array.isArray(o["meta"]))) {
+        return { path: "meta", reason: "optional, must be object" };
+    }
+    return null;
+}
+/**
+ * Validate an AgentsConfig object.
+ * Returns null on success, or the first error found.
+ */
+export function validateAgentsConfig(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return { path: "", reason: "expected object" };
+    }
+    const o = obj;
+    if (typeof o["active"] !== "string" || !o["active"]) {
+        return { path: "active", reason: "required, non-empty string" };
+    }
+    if (!Array.isArray(o["profiles"])) {
+        return { path: "profiles", reason: "required, must be array" };
+    }
+    for (let i = 0; i < o["profiles"].length; i++) {
+        const err = validateAgentProfile(o["profiles"][i]);
+        if (err) {
+            err.path = `profiles[${i}].${err.path}`;
+            return err;
+        }
+    }
+    return null;
+}
+/** Default agent profile registered when no profiles exist yet. */
+export const DEFAULT_AGENT_PROFILE = {
+    schema: "openkan.agent-profile.v1",
+    id: "claude-code",
+    kind: "claude-code",
+    bin: "claude",
+    description: "Default Claude Code agent profile",
+};
+/** Default agents config used when none exists. */
+export const DEFAULT_AGENTS_CONFIG = {
+    schema: "openkan.agents.v1",
+    active: "claude-code",
+    profiles: [DEFAULT_AGENT_PROFILE],
+};
+/** Strip the id prefix from each id-suffix in the array, for logging. */
+export function suffixList(items) {
+    return items.map((i) => idSuffix(i.id) ?? i.id);
+}

package/dist/ok/storage.js

@@ -0,0 +1,222 @@
+// ok/storage.ts — async JSON storage for every planning entity.
+//
+// Storage rules:
+// - One file per entity (e.g. `.ok/tasks/tsk-Vn4kRp2x.json`).
+// - Writes are atomic via `.tmp` + `rename` (same pattern as kanban/io.ts).
+// - Reads tolerate concurrent overwrites but never silently mutate.
+// - Unknown files in directories are ignored — agents may add helpers.
+//
+// Every entity has a JSON envelope `{schema, ...payload}`; the `schema`
+// discriminator is the only addressable identity in tests.
+import { promises as fs } from "node:fs";
+import * as fsSync from "node:fs";
+import * as path from "node:path";
+import { isTask, isPlan, isPrd, isOkConfig, isOkIndex, } from "./schemas.js";
+import { nowIso } from "./ids.js";
+export const OK_DIR = ".ok";
+export const CONFIG_FILE = "config.json";
+export const INDEX_FILE = "index.json";
+export const TASKS_DIR = "tasks";
+export const PLANS_DIR = "plans";
+export const PRDS_DIR = "prds";
+export const SESSIONS_DIR = "sessions";
+export const LOCKS_DIR = "locks";
+/** Resolve all well-known paths under `<root>/.ok/`. */
+export function paths(root) {
+    const okRoot = path.join(root, OK_DIR);
+    return {
+        root: okRoot,
+        configFile: path.join(okRoot, CONFIG_FILE),
+        indexFile: path.join(okRoot, INDEX_FILE),
+        tasksDir: path.join(okRoot, TASKS_DIR),
+        plansDir: path.join(okRoot, PLANS_DIR),
+        prdsDir: path.join(okRoot, PRDS_DIR),
+        sessionsDir: path.join(okRoot, SESSIONS_DIR),
+        locksDir: path.join(okRoot, LOCKS_DIR),
+    };
+}
+/** Read the JSON at `p` and narrow it; throws if missing or malformed. */
+export async function readJson(p, narrow) {
+    const raw = await fs.readFile(p, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`invalid JSON in ${p}: ${e.message}`);
+    }
+    if (!narrow(parsed)) {
+        throw new Error(`invalid shape in ${p} (failed schema check). ` +
+            `If this file was created by a bug or external tool, you can remove it with: rm "${p}"`);
+    }
+    return parsed;
+}
+/** Best-effort reader; returns `undefined` instead of throwing on missing files. */
+export async function readJsonOptional(p, narrow) {
+    try {
+        return await readJson(p, narrow);
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+/** Atomic JSON write (tmp + rename). */
+export async function writeJson(p, body) {
+    const tmp = `${p}.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, p);
+}
+export async function ensureDirs(p) {
+    for (const dir of [p.root, p.tasksDir, p.plansDir, p.prdsDir, p.sessionsDir, p.locksDir]) {
+        await fs.mkdir(dir, { recursive: true });
+    }
+}
+// ─── Typed getters/setters ──────────────────────────────────────────────────
+export async function readConfig(p) {
+    return readJsonOptional(p.configFile, isOkConfig);
+}
+export async function writeConfig(p, cfg) {
+    await ensureDirs(p);
+    await writeJson(p.configFile, cfg);
+}
+export async function readIndex(p) {
+    return readJsonOptional(p.indexFile, isOkIndex);
+}
+export async function writeIndex(p, idx) {
+    await writeJson(p.indexFile, idx);
+}
+export async function listDir(p, prefix) {
+    let names;
+    try {
+        names = await fs.readdir(p);
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    return names
+        .filter((n) => n.startsWith(`${prefix}-`) && n.endsWith(".json"))
+        .sort();
+}
+export async function readTask(p, id) {
+    if (!/^tsk-[A-Za-z0-9_-]+$/.test(id))
+        throw new Error(`invalid task id: ${id}`);
+    return readJsonOptional(path.join(p.tasksDir, `${id}.json`), isTask);
+}
+export async function writeTask(p, task) {
+    await fs.mkdir(p.tasksDir, { recursive: true });
+    await writeJson(path.join(p.tasksDir, `${task.id}.json`), task);
+}
+export async function listTasks(p) {
+    const files = await listDir(p.tasksDir, "tsk");
+    const out = [];
+    for (const f of files) {
+        const v = await readJsonOptional(path.join(p.tasksDir, f), isTask);
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+export async function readPlan(p, id) {
+    if (!/^pln-[A-Za-z0-9_-]+$/.test(id))
+        throw new Error(`invalid plan id: ${id}`);
+    return readJsonOptional(path.join(p.plansDir, `${id}.json`), isPlan);
+}
+export async function writePlan(p, plan) {
+    await fs.mkdir(p.plansDir, { recursive: true });
+    await writeJson(path.join(p.plansDir, `${plan.id}.json`), plan);
+}
+export async function listPlans(p) {
+    const files = await listDir(p.plansDir, "pln");
+    const out = [];
+    for (const f of files) {
+        const v = await readJsonOptional(path.join(p.plansDir, f), isPlan);
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+export async function readPrd(p, id) {
+    if (!/^prd-[A-Za-z0-9_-]+$/.test(id))
+        throw new Error(`invalid prd id: ${id}`);
+    return readJsonOptional(path.join(p.prdsDir, `${id}.json`), isPrd);
+}
+export async function writePrd(p, prd) {
+    await fs.mkdir(p.prdsDir, { recursive: true });
+    await writeJson(path.join(p.prdsDir, `${prd.id}.json`), prd);
+}
+export async function listPrds(p) {
+    const files = await listDir(p.prdsDir, "prd");
+    const out = [];
+    for (const f of files) {
+        const v = await readJsonOptional(path.join(p.prdsDir, f), isPrd);
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+// ─── Index builder ──────────────────────────────────────────────────────────
+/** Rebuild `.ok/index.json` from the filesystem. */
+export async function rebuildIndex(p) {
+    const [tasks, plans, prds] = await Promise.all([listTasks(p), listPlans(p), listPrds(p)]);
+    const toEntry = (e) => ({
+        id: e.id,
+        status: e.status,
+        title: e.title,
+        updatedAt: e.updatedAt,
+    });
+    const idx = {
+        schema: "ok.index.v1",
+        tasks: tasks
+            .map(toEntry)
+            .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0)),
+        plans: plans
+            .map(toEntry)
+            .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0)),
+        prds: prds
+            .map(toEntry)
+            .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0)),
+        updatedAt: nowIso(),
+    };
+    await writeIndex(p, idx);
+    return idx;
+}
+/** True when `.ok/config.json` is present at the project root. */
+export function hasOkDir(root) {
+    return fsSync.existsSync(path.join(root, OK_DIR, CONFIG_FILE));
+}
+/**
+ * Initialise `.ok/` in the project root if missing. Idempotent.
+ * Returns the resolved paths either way.
+ */
+export async function initIfMissing(root) {
+    const p = paths(root);
+    await ensureDirs(p);
+    if (!(await readConfig(p))) {
+        const now = nowIso();
+        const cfg = {
+            schema: "ok.config.v1",
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await writeConfig(p, cfg);
+    }
+    if (!(await readIndex(p))) {
+        await rebuildIndex(p);
+    }
+    return p;
+}