@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/core/task/document.js

@@ -0,0 +1,189 @@
+import { isAlias, isMap, isScalar, isSeq, parseDocument, stringify, } from "yaml";
+import { canonicalTimestamp, fullId, invalid, nonblank, TASK_STATES, } from "./validation.js";
+const FIELD_ORDER = [
+    "id",
+    "title",
+    "state",
+    "pri",
+    "needs",
+    "parent",
+    "from",
+    "createdAt",
+    "creator",
+    "startedAt",
+    "contractId",
+];
+const FIELD_SET = new Set(FIELD_ORDER);
+function validateNode(node) {
+    if (node == null)
+        return;
+    if (isAlias(node))
+        invalid("task front matter must not contain aliases");
+    if ("anchor" in node && node.anchor)
+        invalid("task front matter must not contain anchors");
+    if ("tag" in node && node.tag)
+        invalid("task front matter must not contain explicit tags");
+    if (isMap(node)) {
+        for (const item of node.items) {
+            const pair = item;
+            validateNode(pair.key);
+            validateNode(pair.value);
+        }
+    }
+    else if (isSeq(node)) {
+        for (const item of node.items)
+            validateNode(item);
+    }
+    else if (!isScalar(node)) {
+        invalid("task front matter contains an unsupported YAML node");
+    }
+}
+function frontMatter(source) {
+    if (!source.text.startsWith("---\n") && !source.text.startsWith("---\r\n")) {
+        invalid("task document must begin with exactly one '---' front matter block");
+    }
+    const lines = source.text.split(/\r?\n/);
+    let closing = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index] === "---") {
+            closing = index;
+            break;
+        }
+    }
+    if (closing < 0)
+        invalid("task document front matter is not closed");
+    return {
+        yaml: lines.slice(1, closing).join("\n"),
+        body: lines.slice(closing + 1).join("\n"),
+    };
+}
+export function parseTaskDocument(source) {
+    const split = frontMatter(source);
+    const parsed = parseDocument(split.yaml, {
+        merge: false,
+        prettyErrors: false,
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (parsed.errors.length > 0) {
+        invalid(`invalid task YAML: ${parsed.errors[0].message}`);
+    }
+    validateNode(parsed.contents);
+    if (!isMap(parsed.contents))
+        invalid("task front matter must be a YAML mapping");
+    const values = new Map();
+    for (const item of parsed.contents.items) {
+        if (!isScalar(item.key) || typeof item.key.value !== "string") {
+            invalid("task front matter keys must be strings");
+        }
+        const key = item.key.value;
+        if (!FIELD_SET.has(key))
+            invalid(`unknown task front matter key '${key}'`);
+        const value = item.value;
+        if (isSeq(value)) {
+            const items = value.items.map((entry) => {
+                if (!isScalar(entry) || typeof entry.value !== "string") {
+                    return invalid(`task field '${key}' must contain only strings`);
+                }
+                return entry.value;
+            });
+            values.set(key, items);
+        }
+        else if (isScalar(value)) {
+            values.set(key, value.value);
+        }
+        else if (value === null) {
+            values.set(key, null);
+        }
+        else {
+            invalid(`task field '${key}' must be a scalar or string array`);
+        }
+    }
+    const id = fullId("id", values.get("id"));
+    const title = nonblank("title", values.get("title"));
+    const state = values.get("state");
+    if (typeof state !== "string" || !TASK_STATES.has(state)) {
+        invalid("task field 'state' must be open, in_progress, done, or drop");
+    }
+    const pri = values.get("pri");
+    if (typeof pri !== "number" || !Number.isInteger(pri) || pri < 0 || pri > 3) {
+        invalid("task field 'pri' must be an integer from 0 through 3");
+    }
+    const needsValue = values.get("needs");
+    if (!Array.isArray(needsValue))
+        invalid("task field 'needs' must be a string array");
+    const needs = needsValue.map((need) => fullId("needs", need));
+    if (new Set(needs).size !== needs.length)
+        invalid("task field 'needs' must be unique");
+    const relationship = (field) => {
+        const value = values.get(field);
+        if (value === null)
+            return null;
+        const related = fullId(field, value);
+        if (related === id)
+            invalid(`task field '${field}' must not reference itself`);
+        return related;
+    };
+    const parent = relationship("parent");
+    const fromValue = values.get("from");
+    if (!Array.isArray(fromValue))
+        invalid("task field 'from' must be a string array");
+    const from = fromValue.map((related) => fullId("from", related));
+    if (new Set(from).size !== from.length)
+        invalid("task field 'from' must be unique");
+    if (from.includes(id))
+        invalid("task field 'from' must not reference itself");
+    const createdAt = canonicalTimestamp("createdAt", values.get("createdAt"));
+    const creator = nonblank("creator", values.get("creator"));
+    const startedValue = values.get("startedAt");
+    const contractValue = values.get("contractId");
+    const startedAt = startedValue === undefined ? undefined : canonicalTimestamp("startedAt", startedValue);
+    const contractId = contractValue === undefined ? undefined : nonblank("contractId", contractValue);
+    if (state === "in_progress" && startedAt === undefined) {
+        invalid("task field 'startedAt' is required when state is in_progress");
+    }
+    if (state !== "in_progress" && startedAt !== undefined) {
+        invalid("task field 'startedAt' is forbidden unless state is in_progress");
+    }
+    return {
+        id,
+        title,
+        state: state,
+        pri,
+        needs,
+        parent,
+        from,
+        createdAt,
+        creator,
+        ...(startedAt === undefined ? {} : { startedAt }),
+        ...(contractId === undefined ? {} : { contractId }),
+        body: split.body,
+        source,
+    };
+}
+function validateDocument(document) {
+    return parseTaskDocument({ path: `${document.id}.md`, text: serializeUnchecked(document) });
+}
+function serializeUnchecked(document) {
+    const data = {
+        id: document.id,
+        title: document.title,
+        state: document.state,
+        pri: document.pri,
+        needs: [...document.needs],
+        parent: document.parent,
+        from: document.from,
+        createdAt: document.createdAt,
+        creator: document.creator,
+    };
+    if (document.startedAt !== undefined)
+        data.startedAt = document.startedAt;
+    if (document.contractId !== undefined)
+        data.contractId = document.contractId;
+    const yaml = stringify(data, { lineWidth: 0 }).trimEnd();
+    return `---\n${yaml}\n---\n${document.body}`;
+}
+export function serializeTaskDocument(document) {
+    validateDocument(document);
+    return serializeUnchecked(document);
+}

package/build/core/task/model.js

@@ -0,0 +1 @@
+export {};

package/build/core/task/settlement-git.js

@@ -0,0 +1,207 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { FlowError } from "../../flow-error.js";
+import { parseTaskDocument } from "../task.js";
+function gitResult(cwd, args, input, env) {
+    return spawnSync("git", [...args], {
+        cwd,
+        input,
+        encoding: "utf8",
+        env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+}
+function git(cwd, args, input, env) {
+    const result = gitResult(cwd, args, input, env);
+    if (result.error) {
+        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.error.message}`, { cause: result.error });
+    }
+    if (result.status !== 0) {
+        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    }
+    return result.stdout;
+}
+function boardPath(root, source) {
+    const relative = path.relative(root, source.path).split(path.sep).join("/");
+    if (!relative.startsWith(".keiyaku/tasks/") || relative.includes("..")) {
+        throw new FlowError("INTERNAL_STATE", `task source is outside the board: ${source.path}`);
+    }
+    return relative;
+}
+export function inspectCurrentBranch(cwd) {
+    const branch = gitResult(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
+    if (branch.error) {
+        throw new FlowError("INTERNAL_STATE", `cannot inspect HEAD: ${branch.error.message}`, { cause: branch.error });
+    }
+    if (branch.status !== 0 || branch.stdout.trim() === "") {
+        throw new FlowError("DETACHED_HEAD", "cannot publish task board from detached HEAD");
+    }
+    return { ref: branch.stdout.trim(), head: git(cwd, ["rev-parse", "HEAD"]).trim() };
+}
+export function createTaskBoardCommit(input) {
+    const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-task-index-"));
+    const indexPath = path.join(temporaryDirectory, "index");
+    const env = { GIT_INDEX_FILE: indexPath };
+    try {
+        git(input.cwd, ["read-tree", input.parent], undefined, env);
+        git(input.cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        for (const source of input.sources) {
+            const oid = git(input.cwd, ["hash-object", "-w", "--stdin"], source.text).trim();
+            git(input.cwd, ["update-index", "--add", "--cacheinfo", `100644,${oid},${boardPath(input.root, source)}`], undefined, env);
+        }
+        const tree = git(input.cwd, ["write-tree"], undefined, env).trim();
+        return git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject]).trim();
+    }
+    finally {
+        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+function taskTreeEntries(cwd, commit) {
+    return git(cwd, ["ls-tree", "-r", "-z", commit, "--", ".keiyaku/tasks"])
+        .split("\0")
+        .filter(Boolean)
+        .map((record) => {
+        const tab = record.indexOf("\t");
+        const [mode, type, oid] = record.slice(0, tab).split(" ");
+        if (tab < 0 || type !== "blob" || !mode || !oid) {
+            throw new FlowError("INTERNAL_STATE", `invalid task tree entry in ${commit}`);
+        }
+        return { mode, oid, path: record.slice(tab + 1) };
+    });
+}
+export function reconcileTaskIndex(cwd, commit) {
+    const existing = git(cwd, ["ls-files", "-z", "--", ".keiyaku/tasks"])
+        .split("\0")
+        .filter(Boolean);
+    for (const file of existing)
+        git(cwd, ["update-index", "--force-remove", "--", file]);
+    for (const entry of taskTreeEntries(cwd, commit)) {
+        git(cwd, ["update-index", "--add", "--cacheinfo", `${entry.mode},${entry.oid},${entry.path}`]);
+    }
+}
+export function refHead(cwd, ref) {
+    return git(cwd, ["rev-parse", ref]).trim();
+}
+export function readableRefHead(cwd, ref) {
+    const result = gitResult(cwd, ["rev-parse", ref]);
+    if (result.status !== 0)
+        return undefined;
+    return result.stdout.trim();
+}
+export function taskContractAtCommit(cwd, commit, id) {
+    const sourcePath = `.keiyaku/tasks/${id}.md`;
+    const result = gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
+    if (result.status !== 0)
+        return undefined;
+    return parseTaskDocument({ path: sourcePath, text: result.stdout }).contractId;
+}
+export async function updateBranch(input, deps) {
+    if (deps.updateBranch)
+        await deps.updateBranch(input);
+    else
+        git(input.cwd, ["update-ref", input.ref, input.next, input.expected]);
+}
+export async function publishForwardTaskBoardCommit(input, deps) {
+    let lastError;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const parent = refHead(input.cwd, input.ref);
+        const commit = createTaskBoardCommit({ ...input, parent });
+        try {
+            await updateBranch({ cwd: input.cwd, ref: input.ref, next: commit, expected: parent }, deps);
+            try {
+                reconcileTaskIndex(input.cwd, commit);
+            }
+            catch { /* the forward branch fact remains authoritative */ }
+            return commit;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
+function treeWithoutTasks(cwd, commit, gitDir) {
+    const temporaryDirectory = fs.mkdtempSync(path.join(gitDir, "keiyaku-landing-index-"));
+    const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
+    try {
+        git(cwd, ["read-tree", commit], undefined, env);
+        git(cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        return git(cwd, ["write-tree"], undefined, env).trim();
+    }
+    finally {
+        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+function composeLandingTree(input) {
+    const baseTree = treeWithoutTasks(input.cwd, input.base, input.gitDir);
+    const targetTree = treeWithoutTasks(input.cwd, input.target, input.gitDir);
+    const deliveryTree = treeWithoutTasks(input.cwd, input.delivery, input.gitDir);
+    let mergedTree;
+    try {
+        mergedTree = git(input.cwd, [
+            "merge-tree",
+            "--write-tree",
+            "--merge-base",
+            baseTree,
+            targetTree,
+            deliveryTree,
+        ]).trim();
+    }
+    catch (error) {
+        throw new FlowError("CLOSE_MERGE_CONFLICT", "claim merge conflict outside task board", { cause: error });
+    }
+    const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-landing-index-"));
+    const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
+    try {
+        git(input.cwd, ["read-tree", mergedTree], undefined, env);
+        git(input.cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        for (const source of input.sources) {
+            const oid = git(input.cwd, ["hash-object", "-w", "--stdin"], source.text).trim();
+            git(input.cwd, [
+                "update-index",
+                "--add",
+                "--cacheinfo",
+                `100644,${oid},${boardPath(input.root, source)}`,
+            ], undefined, env);
+        }
+        return git(input.cwd, ["write-tree"], undefined, env).trim();
+    }
+    finally {
+        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+export function createLandingCommit(input) {
+    const tree = composeLandingTree(input);
+    return git(input.cwd, [
+        "commit-tree",
+        tree,
+        "-p",
+        input.target,
+        "-p",
+        input.delivery,
+        "-m",
+        `keiyaku: claim ${input.contractId}`,
+        "-m",
+        `Merge contract ${input.contractId} into ${input.targetBranch}.`,
+    ]).trim();
+}
+export function containsCommit(cwd, ancestor, descendant) {
+    return gitResult(cwd, ["merge-base", "--is-ancestor", ancestor, descendant]).status === 0;
+}
+export function updateTargetRef(cwd, ref, next, expected) {
+    git(cwd, ["update-ref", ref, next, expected]);
+}
+export function sameTaskSourceBytes(root, left, right) {
+    const snapshot = (sources) => new Map(sources.map((source) => [boardPath(root, source), source.text]));
+    const leftSnapshot = snapshot(left);
+    const rightSnapshot = snapshot(right);
+    return leftSnapshot.size === rightSnapshot.size
+        && [...leftSnapshot].every(([sourcePath, sourceText]) => rightSnapshot.get(sourcePath) === sourceText);
+}
+export function taskWritesFromSources(sources) {
+    return sources.map((source) => ({
+        id: path.basename(source.path, ".md"),
+        text: source.text,
+    }));
+}

package/build/core/task/settlement-policy.js

@@ -0,0 +1,82 @@
+import { FlowError } from "../../flow-error.js";
+import { resolveTaskReadId } from "./board.js";
+export function requireHealthySettlementBoard(board) {
+    if (board.diseases.length > 0) {
+        throw new FlowError("INTERNAL_STATE", `authoritative task board is diseased: ${board.diseases.map((disease) => disease.message).join("; ")}`);
+    }
+    return board;
+}
+function settlementDocument(task, contractId) {
+    return {
+        id: task.id,
+        title: task.title,
+        state: task.state,
+        pri: task.pri,
+        needs: [...task.needs],
+        parent: task.parent,
+        from: [...task.from],
+        createdAt: task.createdAt,
+        creator: task.creator,
+        ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
+        ...(contractId === undefined ? {} : { contractId }),
+        body: task.body,
+    };
+}
+export function contractPointerDocument(task, contractId) {
+    return settlementDocument(task, contractId);
+}
+export function reopenedTaskDocument(task) {
+    const document = settlementDocument(task, undefined);
+    document.state = "open";
+    delete document.startedAt;
+    return document;
+}
+export function selectReadyTaskForBind(board, taskId) {
+    requireHealthySettlementBoard(board);
+    const id = resolveTaskReadId(board, taskId);
+    const task = board.byId.get(id);
+    if (task.state === "in_progress") {
+        throw new FlowError("INVALID_TARGET", `task ${id} is in_progress; stop it before bind`);
+    }
+    if (task.state !== "open") {
+        throw new FlowError("INVALID_TARGET", `task ${id} is ${task.state}, not ready for bind`);
+    }
+    const unsatisfied = task.needs
+        .filter((need) => {
+        const dependency = board.byId.get(need);
+        return dependency.state === "open" || dependency.state === "in_progress";
+    })
+        .sort();
+    if (unsatisfied.length > 0) {
+        throw new FlowError("INVALID_TARGET", `task ${id} is blocked by: ${unsatisfied.join(", ")}`);
+    }
+    if (task.contractId !== undefined) {
+        throw new FlowError("INVALID_TARGET", `task ${id} is already bound to contract ${task.contractId}`);
+    }
+    return task;
+}
+export function taskForContract(board, contractId) {
+    requireHealthySettlementBoard(board);
+    const matches = board.tasks
+        .filter((task) => task.contractId === contractId)
+        .sort((left, right) => left.id.localeCompare(right.id));
+    if (matches.length > 1) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} is referenced by multiple tasks: ${matches.map((task) => task.id).join(", ")}`);
+    }
+    return matches[0];
+}
+export function requireSettledTask(board, id) {
+    const task = requireHealthySettlementBoard(board).byId.get(id);
+    if (!task)
+        throw new FlowError("INTERNAL_STATE", `task ${id} disappeared from the board`);
+    return task;
+}
+export function doneTaskReplacement(board, contractId) {
+    const bound = taskForContract(board, contractId);
+    if (!bound)
+        return undefined;
+    const settled = settlementDocument(bound, undefined);
+    settled.state = "done";
+    delete settled.startedAt;
+    return settled;
+}

package/build/core/task/source-board.js

@@ -0,0 +1,84 @@
+import { buildTaskBoardFromDocuments } from "./board.js";
+import { parseTaskDocument } from "./document.js";
+import { invalid } from "./validation.js";
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function diseaseSort(left, right) {
+    return compareText(left.path, right.path)
+        || compareText(left.code, right.code)
+        || compareText(left.id ?? "", right.id ?? "")
+        || compareText(left.message, right.message);
+}
+function sourceBasename(sourcePath) {
+    return sourcePath.split(/[\\/]/).at(-1) ?? "";
+}
+function taskDocument(parsed) {
+    return {
+        id: parsed.id,
+        title: parsed.title,
+        state: parsed.state,
+        pri: parsed.pri,
+        needs: [...parsed.needs],
+        parent: parsed.parent,
+        from: [...parsed.from],
+        createdAt: parsed.createdAt,
+        creator: parsed.creator,
+        ...(parsed.startedAt === undefined ? {} : { startedAt: parsed.startedAt }),
+        ...(parsed.contractId === undefined ? {} : { contractId: parsed.contractId }),
+        body: parsed.body,
+    };
+}
+export function buildTaskSourceBoard(sources) {
+    const sourceDiseases = [];
+    const authoritative = [];
+    for (const source of [...sources].sort((a, b) => compareText(a.path, b.path))) {
+        try {
+            const parsed = parseTaskDocument(source);
+            if (sourceBasename(source.path) !== `${parsed.id}.md`) {
+                invalid(`task source basename must be ${parsed.id}.md`);
+            }
+            authoritative.push(parsed);
+        }
+        catch (error) {
+            sourceDiseases.push({
+                code: "invalid_document",
+                path: source.path,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const counts = new Map();
+    for (const task of authoritative)
+        counts.set(task.id, (counts.get(task.id) ?? 0) + 1);
+    const candidates = new Map();
+    for (const task of authoritative) {
+        if (counts.get(task.id) > 1) {
+            sourceDiseases.push({
+                code: "duplicate_id",
+                path: task.source.path,
+                message: `duplicate authoritative task id ${task.id}`,
+                id: task.id,
+            });
+        }
+        else {
+            candidates.set(task.id, task);
+        }
+    }
+    const domainBoard = buildTaskBoardFromDocuments([...candidates.values()].map(taskDocument));
+    const graphDiseases = domainBoard.diseases.map((disease) => ({
+        ...disease,
+        path: disease.id === undefined ? "" : candidates.get(disease.id)?.source.path ?? "",
+    }));
+    const tasks = domainBoard.tasks.map((task) => ({
+        ...task,
+        path: candidates.get(task.id).source.path,
+    }));
+    return {
+        tasks,
+        diseases: [...sourceDiseases, ...graphDiseases].sort(diseaseSort),
+        byId: new Map(tasks.map((task) => [task.id, task])),
+    };
+}
+/** Compatibility name for source-backed board consumers. */
+export const buildTaskBoard = buildTaskSourceBoard;

package/build/core/task/source-model.js

@@ -0,0 +1 @@
+export {};

package/build/core/task/validation.js

@@ -0,0 +1,44 @@
+import { FlowError } from "../../flow-error.js";
+export const TASK_ID = /^k-[0-9a-f]{12}$/;
+export const TASK_STATES = new Set(["open", "in_progress", "done", "drop"]);
+const CANONICAL_ISO_UTC_MS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+export function invalid(message) {
+    throw new FlowError("INVALID_TARGET", message);
+}
+export function nonblank(field, value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        return invalid(`task field '${field}' must be a nonblank string`);
+    }
+    return value;
+}
+export function fullId(field, value) {
+    const id = nonblank(field, value);
+    if (!TASK_ID.test(id))
+        invalid(`task field '${field}' must be a canonical full task id`);
+    return id;
+}
+export function canonicalTimestamp(field, value) {
+    const timestamp = nonblank(field, value);
+    if (!CANONICAL_ISO_UTC_MS.test(timestamp)) {
+        invalid(`task field '${field}' must be a canonical ISO UTC millisecond timestamp`);
+    }
+    try {
+        if (new Date(timestamp).toISOString() !== timestamp) {
+            invalid(`task field '${field}' must be a canonical ISO UTC millisecond timestamp`);
+        }
+    }
+    catch {
+        invalid(`task field '${field}' must be a canonical ISO UTC millisecond timestamp`);
+    }
+    return timestamp;
+}
+export function dateTimestamp(field, value) {
+    try {
+        return canonicalTimestamp(field, value.toISOString());
+    }
+    catch (error) {
+        if (error instanceof FlowError)
+            throw error;
+        return invalid(`task field '${field}' must be a valid date`);
+    }
+}