@astrosheep/keiyaku 2.9.9 → 2.9.11

package/build/core/task/commands.js

@@ -1,20 +1,26 @@
 import { FlowError } from "../../flow-error.js";
-import { IdentifierSlugError, normalizeIdentifierSlug, SUFFIXABLE_IDENTIFIER_SLUG_MAX_UTF8_BYTES, } from "../identifier-slug.js";
+import { IdentifierSlugError, taskIdentifierSlug, } from "../identifier-slug.js";
+import { markdownSourceSections } from "../scope.js";
 import { requireCanonicalTaskId, requireHealthy, resolveTaskId, } from "./board.js";
 import { dateTimestamp, invalid, nonblank, } from "./validation.js";
 import { advancedTaskUpdatedAt } from "./model.js";
+import { formatTaskCoordinate, parseTaskCoordinate } from "./coordinate.js";
 export async function readTaskBoard(repository) {
     return repository.read();
 }
 function documentFromView(view) {
     return {
         id: view.id,
+        namespace: view.namespace,
+        coordinate: view.coordinate,
         title: view.title,
         state: view.state,
         pri: view.pri,
         needs: [...view.needs],
         parent: view.parent,
         from: [...view.from],
+        supersedes: [...view.supersedes],
+        relatesTo: [...view.relatesTo],
         createdAt: view.createdAt,
         ...(view.updatedAt === undefined ? {} : { updatedAt: view.updatedAt }),
         creator: view.creator,
@@ -23,14 +29,18 @@ function documentFromView(view) {
         body: view.body,
     };
 }
+function documentCoordinate(document) {
+    return document.coordinate ?? formatTaskCoordinate(document.namespace ?? null, document.id);
+}
 function replaceDocument(document, subject) {
     return {
         replacements: [document],
         subject,
         select(resulting) {
-            const value = resulting.byId.get(document.id);
+            const coordinate = documentCoordinate(document);
+            const value = resulting.byId.get(coordinate);
             if (!value)
-                throw new FlowError("INTERNAL_STATE", `mutated task ${document.id} disappeared from the board`);
+                throw new FlowError("INTERNAL_STATE", `mutated task ${coordinate} disappeared from the board`);
             return value;
         },
     };
@@ -44,24 +54,45 @@ function requireExisting(board, id) {
 function resolveMutationIds(board, ids) {
     return ids.map((id) => resolveTaskId(board, id));
 }
+function validateRelations(board, id, supersedes, relatesTo) {
+    if (supersedes.includes(id) || relatesTo.includes(id))
+        invalid(`task ${id} relations must not reference itself`);
+    const seen = new Set();
+    const reachesSource = (current) => {
+        if (current === id)
+            return true;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        return (board.byId.get(current)?.supersedes ?? []).some(reachesSource);
+    };
+    for (const target of supersedes) {
+        seen.clear();
+        if (reachesSource(target))
+            invalid(`task ${id} would create a supersedes cycle`);
+    }
+}
+function updateRelations(board, document, field, additions, removals) {
+    const added = resolveMutationIds(board, additions ?? []);
+    if (new Set(added).size !== added.length)
+        invalid(`task ${field} edges must be unique`);
+    const removed = new Set(resolveMutationIds(board, removals ?? []));
+    const retained = (document[field] ?? []).filter((value) => !removed.has(value));
+    if (added.some((value) => retained.includes(value)))
+        invalid(`task ${field} edges must be unique`);
+    document[field] = [...retained, ...added];
+}
 export async function createTask(repository, input, deps) {
     nonblank("title", input.title);
     nonblank("creator", input.creator);
-    let baseId;
-    try {
-        baseId = normalizeIdentifierSlug(input.title, SUFFIXABLE_IDENTIFIER_SLUG_MAX_UTF8_BYTES);
-    }
-    catch (error) {
-        if (error instanceof IdentifierSlugError) {
-            throw new FlowError("INVALID_TARGET", `task title ${error.message}`, { cause: error });
-        }
-        throw error;
-    }
     const pri = input.pri ?? 2;
     if (!Number.isInteger(pri) || pri < 0 || pri > 3)
         invalid("task priority must be an integer from 0 through 3");
     return repository.mutate((board) => {
         requireHealthy(board);
+        const namespace = input.namespace ?? null;
+        if (namespace !== null)
+            parseTaskCoordinate(`${namespace}/task`, "task namespace");
         const needs = resolveMutationIds(board, input.needs ?? []);
         if (new Set(needs).size !== needs.length)
             invalid("task needs must be unique");
@@ -69,34 +100,64 @@ export async function createTask(repository, input, deps) {
         const from = resolveMutationIds(board, input.from ?? []);
         if (new Set(from).size !== from.length)
             invalid("task from edges must be unique");
-        let id = baseId;
-        for (let ordinal = 2; board.byId.has(id); ordinal += 1) {
+        const supersedes = resolveMutationIds(board, input.supersedes ?? []);
+        if (new Set(supersedes).size !== supersedes.length)
+            invalid("task supersedes edges must be unique");
+        const relatesTo = resolveMutationIds(board, input.relatesTo ?? []);
+        if (new Set(relatesTo).size !== relatesTo.length)
+            invalid("task relatesTo edges must be unique");
+        let ordinal = 1;
+        let id;
+        for (;;) {
             if (!Number.isSafeInteger(ordinal)) {
-                throw new FlowError("INTERNAL_STATE", `task id collision ordinal exceeded the safe integer range for ${baseId}`);
+                throw new FlowError("INTERNAL_STATE", "task id collision ordinal exceeded the safe integer range");
+            }
+            try {
+                id = taskIdentifierSlug(input.title, ordinal === 1 ? "" : `-${ordinal}`);
             }
-            id = `${baseId}-${ordinal}`;
+            catch (error) {
+                if (error instanceof IdentifierSlugError) {
+                    throw new FlowError("INVALID_TARGET", `task title ${error.message}`, { cause: error });
+                }
+                throw error;
+            }
+            if (!board.byId.has(formatTaskCoordinate(namespace, id)))
+                break;
+            ordinal += 1;
         }
+        const coordinate = formatTaskCoordinate(namespace, id);
+        validateRelations(board, coordinate, supersedes, relatesTo);
         const now = deps.now();
         const document = {
             id,
+            namespace,
+            coordinate,
             title: input.title,
             state: "open",
             pri,
             needs,
             parent,
             from,
+            supersedes,
+            relatesTo,
             createdAt: dateTimestamp("createdAt", now),
             updatedAt: dateTimestamp("updatedAt", now),
             creator: input.creator,
             body: input.body ?? "",
         };
-        return replaceDocument(document, `Add task ${id}`);
+        return replaceDocument(document, `Add task ${coordinate}`);
     });
 }
 export async function updateTask(repository, fullIdValue, patch, now = new Date()) {
+    return (await updateTaskWithReceipt(repository, fullIdValue, patch, now)).task;
+}
+export async function updateTaskWithReceipt(repository, fullIdValue, patch, now = new Date()) {
     const hasChange = Object.values(patch).some((value) => value !== undefined);
     if (!hasChange)
         throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
+    if (patch.body !== undefined && patch.appendBody !== undefined) {
+        throw new FlowError("EMPTY_PARAM", "task update cannot combine --body and --append");
+    }
     return repository.mutate((board) => {
         requireHealthy(board);
         const id = resolveTaskId(board, fullIdValue);
@@ -106,6 +167,8 @@ export async function updateTask(repository, fullIdValue, patch, now = new Date(
             document.title = nonblank("title", patch.title);
         if (patch.body !== undefined)
             document.body = patch.body;
+        if (patch.appendBody !== undefined)
+            document.body = appendBody(document.body, patch.appendBody);
         if (patch.pri !== undefined) {
             if (!Number.isInteger(patch.pri) || patch.pri < 0 || patch.pri > 3)
                 invalid("task priority must be an integer from 0 through 3");
@@ -119,18 +182,82 @@ export async function updateTask(repository, fullIdValue, patch, now = new Date(
         if (patch.from !== undefined) {
             document.from = [...new Set([...document.from, ...resolveMutationIds(board, patch.from)])];
         }
+        updateRelations(board, document, "supersedes", patch.addSupersedes, patch.dropSupersedes);
+        updateRelations(board, document, "relatesTo", patch.addRelatesTo, patch.dropRelatesTo);
+        validateRelations(board, document.coordinate, document.supersedes, document.relatesTo);
         if (JSON.stringify(document) === JSON.stringify(documentFromView(current))) {
             throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
         }
         document.updatedAt = advancedTaskUpdatedAt(current, now);
-        return replaceDocument(document, `Update task ${id}`);
+        const bodyChange = patch.body === undefined ? undefined : describeBodyChange(current.body, document.body);
+        return {
+            replacements: [document],
+            subject: `Update task ${id}`,
+            select(resulting) {
+                const coordinate = documentCoordinate(document);
+                const task = resulting.byId.get(coordinate);
+                if (!task)
+                    throw new FlowError("INTERNAL_STATE", `mutated task ${coordinate} disappeared from the board`);
+                return { task, ...(bodyChange === undefined ? {} : { bodyChange }) };
+            },
+        };
     });
 }
+function appendBody(body, addition) {
+    if (!body || !addition || body.endsWith("\n\n") || addition.startsWith("\n"))
+        return body + addition;
+    return `${body}${body.endsWith("\n") ? "\n" : "\n\n"}${addition}`;
+}
+function markdownLevelTwoSections(body) {
+    return markdownSourceSections(body)
+        .filter((section) => section.level === 2)
+        .map((section) => section.title.trim());
+}
+function bodyLines(body) {
+    return body.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+function lineDiffstat(before, after) {
+    const oldLines = bodyLines(before);
+    const newLines = bodyLines(after);
+    const lcs = Array(newLines.length + 1).fill(0);
+    for (const oldLine of oldLines) {
+        let previous = 0;
+        for (let index = 1; index <= newLines.length; index += 1) {
+            const saved = lcs[index];
+            lcs[index] = oldLine === newLines[index - 1]
+                ? previous + 1
+                : Math.max(lcs[index], lcs[index - 1]);
+            previous = saved;
+        }
+    }
+    const unchanged = lcs[newLines.length];
+    return { additions: newLines.length - unchanged, deletions: oldLines.length - unchanged };
+}
+function describeBodyChange(before, after) {
+    const remaining = new Map();
+    for (const section of markdownLevelTwoSections(after)) {
+        remaining.set(section, (remaining.get(section) ?? 0) + 1);
+    }
+    const oldBytes = Buffer.byteLength(before, "utf8");
+    const newBytes = Buffer.byteLength(after, "utf8");
+    return {
+        oldBytes,
+        newBytes,
+        removedSections: markdownLevelTwoSections(before).filter((section) => {
+            const count = remaining.get(section) ?? 0;
+            if (count === 0)
+                return true;
+            remaining.set(section, count - 1);
+            return false;
+        }),
+        diffstat: lineDiffstat(before, after),
+    };
+}
 async function transition(repository, fullIdValue, apply, subject, now) {
     return repository.mutate((board) => {
         requireHealthy(board);
         const id = fullIdValue === undefined
-            ? selectSoleInProgress(board).id
+            ? selectSoleInProgress(board).coordinate
             : resolveTaskId(board, fullIdValue);
         const current = requireExisting(board, id);
         const document = documentFromView(current);
@@ -141,17 +268,18 @@ async function transition(repository, fullIdValue, apply, subject, now) {
 }
 function rejectBound(document, action = "state") {
     if (document.contractId !== undefined) {
+        const coordinate = documentCoordinate(document);
         if (action === "drop") {
-            throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; forfeit the contract before dropping this task`);
+            throw new FlowError("UNSUPPORTED_POLICY", `task ${coordinate} is bound to contract ${document.contractId}; forfeit the contract before dropping this task`);
         }
-        throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; its state follows the contract`);
+        throw new FlowError("UNSUPPORTED_POLICY", `task ${coordinate} is bound to contract ${document.contractId}; its state follows the contract`);
     }
 }
 export async function startTask(repository, fullId, now) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "open")
-            invalid(`task ${document.id} is ${document.state}, not open`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open`);
         document.state = "in_progress";
         document.startedAt = dateTimestamp("startedAt", now);
     }, (id) => `Start task ${id}`, now);
@@ -160,16 +288,34 @@ export async function stopTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "in_progress")
-            invalid(`task ${document.id} is ${document.state}, not in_progress`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not in_progress`);
         document.state = "open";
         delete document.startedAt;
     }, (id) => `Stop task ${id}`, now);
 }
-export async function doneTask(repository, fullId, now = new Date()) {
+export async function holdTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "open" && document.state !== "in_progress") {
-            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open or in_progress`);
+        }
+        document.state = "on_hold";
+        delete document.startedAt;
+    }, (id) => `Hold task ${id}`, now);
+}
+export async function resumeTask(repository, fullId, now = new Date()) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "on_hold")
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not on_hold`);
+        document.state = "open";
+    }, (id) => `Resume task ${id}`, now);
+}
+export async function doneTask(repository, fullId, now = new Date()) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "open" && document.state !== "in_progress" && document.state !== "on_hold") {
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open, in_progress, or on_hold`);
         }
         document.state = "done";
         delete document.startedAt;
@@ -178,8 +324,8 @@ export async function doneTask(repository, fullId, now = new Date()) {
 export async function dropTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document, "drop");
-        if (document.state !== "open" && document.state !== "in_progress") {
-            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+        if (document.state !== "open" && document.state !== "in_progress" && document.state !== "on_hold") {
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open, in_progress, or on_hold`);
         }
         document.state = "drop";
         delete document.startedAt;
@@ -189,11 +335,13 @@ export function selectSoleInProgress(board) {
     const candidates = board.tasks.filter((task) => task.state === "in_progress");
     if (candidates.length === 1)
         return candidates[0];
-    const ids = candidates.map((task) => task.id).sort();
-    const code = candidates.length === 0 ? "INVALID_TARGET" : "CONTRACT_AMBIGUOUS";
+    const ids = candidates.map((task) => task.coordinate).sort();
+    const code = candidates.length === 0 ? "INVALID_TARGET" : "TASK_AMBIGUOUS";
     throw Object.assign(new FlowError(code, candidates.length === 0
         ? "no task in progress"
-        : "more than one task in progress; pass an ID"), { candidates: ids, candidateTasks: candidates });
+        : "more than one task in progress; pass a coordinate", candidates.length === 0 ? undefined : {
+        facts: { kind: "task_ambiguous", candidates: ids },
+    }), { candidates: ids, candidateTasks: candidates });
 }
 /** Reopen task pointers whose contract authority has disappeared. The caller
  * supplies the ledger fact; this operation itself remains storage-neutral. */
@@ -201,7 +349,7 @@ export async function rollbackOrphanTaskPointers(repository, contractIds, now =
     const before = await repository.read();
     const orphans = before.tasks
         .filter((task) => task.contractId !== undefined && !contractIds.has(task.contractId))
-        .map((task) => ({ taskId: task.id, contractId: task.contractId }))
+        .map((task) => ({ taskId: task.coordinate, contractId: task.contractId }))
         .sort((a, b) => a.taskId.localeCompare(b.taskId));
     if (orphans.length === 0)
         return [];
@@ -220,7 +368,7 @@ export async function rollbackOrphanTaskPointers(repository, contractIds, now =
         if (replacements.length === 0)
             throw new FlowError("CONCURRENT_MODIFICATION", "task pointers changed while doctor was reconciling them");
         const subject = replacements.length === 1
-            ? `Clear orphan contract pointer from task ${replacements[0].id}`
+            ? `Clear orphan contract pointer from task ${documentCoordinate(replacements[0])}`
             : `Clear orphan contract pointers from ${replacements.length} tasks`;
         return { replacements, subject, select: () => undefined };
     });

package/build/core/task/coordinate.js

@@ -0,0 +1,56 @@
+import { FlowError } from "../../flow-error.js";
+import { isNormalizedIdentifierSlug } from "../identifier-slug.js";
+import { taskIdentifierSlug } from "../identifier-slug.js";
+export function formatTaskCoordinate(namespace, localId) {
+    return namespace === null ? localId : `${namespace}/${localId}`;
+}
+export function parseTaskCoordinate(value, field = "task coordinate") {
+    const parts = value.split("/");
+    if (parts.length < 1 || parts.length > 2) {
+        throw new FlowError("INVALID_TARGET", `${field} must be <local-id> or <namespace>/<local-id>`);
+    }
+    const namespace = parts.length === 1 ? null : parts[0];
+    const localId = parts.at(-1);
+    if (!isNormalizedIdentifierSlug(localId) || (namespace !== null && !isNormalizedIdentifierSlug(namespace))) {
+        throw new FlowError("INVALID_TARGET", `${field} must be <local-id> or <namespace>/<local-id>`);
+    }
+    return { namespace, localId, coordinate: formatTaskCoordinate(namespace, localId) };
+}
+export function isTaskCoordinate(value) {
+    try {
+        parseTaskCoordinate(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function taskCoordinateFromSourcePath(sourcePath) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const marker = "/.keiyaku/tasks/";
+    const markerIndex = normalized.lastIndexOf(marker);
+    const relative = markerIndex < 0 ? normalized : normalized.slice(markerIndex + marker.length);
+    if (!relative.endsWith(".md")) {
+        throw new FlowError("INVALID_TARGET", `task source must be a Markdown file below .keiyaku/tasks: ${sourcePath}`);
+    }
+    return parseTaskCoordinate(relative.slice(0, -3), "task source coordinate");
+}
+export const TASK_NAMESPACE_SCOPE_PREFIX = ".keiyaku/tasks/";
+export function taskNamespaceScope(namespace) {
+    parseTaskCoordinate(`${namespace}/task`, "task namespace");
+    return `${TASK_NAMESPACE_SCOPE_PREFIX}${namespace}/**`;
+}
+export function taskNamespaceFromScope(term) {
+    const match = /^\.keiyaku\/tasks\/([^/]+)\/\*\*$/.exec(term);
+    if (!match || !isNormalizedIdentifierSlug(match[1]))
+        return undefined;
+    return match[1];
+}
+export function allocateTaskNamespace(title, occupied) {
+    for (let ordinal = 1; Number.isSafeInteger(ordinal); ordinal += 1) {
+        const candidate = taskIdentifierSlug(title, ordinal === 1 ? "" : `-${ordinal}`);
+        if (!occupied.has(candidate))
+            return candidate;
+    }
+    throw new FlowError("INTERNAL_STATE", "task namespace collision ordinal exceeded the safe integer range");
+}

package/build/core/task/document.js

@@ -1,5 +1,5 @@
 import { isAlias, isMap, isScalar, isSeq, parseDocument, stringify, } from "yaml";
-import { canonicalTimestamp, fullId, invalid, nonblank, TASK_STATES, } from "./validation.js";
+import { canonicalTimestamp, fullId, isTaskId, invalid, nonblank, TASK_STATES, } from "./validation.js";
 const FIELD_ORDER = [
     "id",
     "title",
@@ -8,6 +8,8 @@ const FIELD_ORDER = [
     "needs",
     "parent",
     "from",
+    "supersedes",
+    "relatesTo",
     "createdAt",
     "updatedAt",
     "creator",
@@ -100,11 +102,13 @@ export function parseTaskDocument(source) {
             invalid(`task field '${key}' must be a scalar or string array`);
         }
     }
-    const id = fullId("id", values.get("id"));
+    const id = nonblank("id", values.get("id"));
+    if (!isTaskId(id))
+        invalid("task field 'id' must be a canonical local task 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");
+        invalid("task field 'state' must be open, in_progress, on_hold, done, or drop");
     }
     const pri = values.get("pri");
     if (typeof pri !== "number" || !Number.isInteger(pri) || pri < 0 || pri > 3) {
@@ -120,10 +124,7 @@ export function parseTaskDocument(source) {
         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;
+        return fullId(field, value);
     };
     const parent = relationship("parent");
     const fromValue = values.get("from");
@@ -132,8 +133,19 @@ export function parseTaskDocument(source) {
     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 relationships = (field) => {
+        const value = values.get(field);
+        if (value === undefined)
+            return [];
+        if (!Array.isArray(value))
+            invalid(`task field '${field}' must be a string array`);
+        const related = value.map((item) => fullId(field, item));
+        if (new Set(related).size !== related.length)
+            invalid(`task field '${field}' must be unique`);
+        return related;
+    };
+    const supersedes = relationships("supersedes");
+    const relatesTo = relationships("relatesTo");
     const createdAt = canonicalTimestamp("createdAt", values.get("createdAt"));
     const updatedValue = values.get("updatedAt");
     const updatedAt = updatedValue === undefined ? undefined : canonicalTimestamp("updatedAt", updatedValue);
@@ -156,6 +168,8 @@ export function parseTaskDocument(source) {
         needs,
         parent,
         from,
+        supersedes,
+        relatesTo,
         createdAt,
         ...(updatedAt === undefined ? {} : { updatedAt }),
         creator,
@@ -177,6 +191,8 @@ function serializeUnchecked(document) {
         needs: [...document.needs],
         parent: document.parent,
         from: document.from,
+        ...(document.supersedes.length === 0 ? {} : { supersedes: document.supersedes }),
+        ...(document.relatesTo.length === 0 ? {} : { relatesTo: document.relatesTo }),
         createdAt: document.createdAt,
         ...(document.updatedAt === undefined ? {} : { updatedAt: document.updatedAt }),
         creator: document.creator,

package/build/core/task/index.js

@@ -3,10 +3,13 @@
  * Only symbols required by current external consumers are re-exported.
  * Package-internal modules must import each other directly, not through this file.
  */
-export { previewTaskBoardForBind, reconcileTaskForfeit, settleTaskBoardForBind, settleTaskBoardForLanding, } from "./task-contract.js";
+export { previewTaskBoardForBind, reconcileTaskForfeit, replayClaimTasks, } from "./task-contract.js";
+export { replayPreparedTaskBind, replayPreparedTaskBindLocked, replayCommittedTaskBind, replayCommittedTaskBindForfeit, replayPreparedTaskBindForfeit, withPreparedTaskBind, } from "./task-bind-preparation.js";
+export { readTaskBoardGeneration } from "./task-git-store.js";
 export { resolveTaskCreator } from "./task-git-actor.js";
-export { openTaskCommandRepository, readTaskDoctor, taskCommandContractId, } from "./task-git-runtime.js";
-export { openTaskStore, readTaskHistory } from "./task-git-store.js";
+export { openTaskCommandRepository, openTaskMutationContext, readTaskDoctor, taskCommandContractId, taskCommandNamespace, } from "./task-git-runtime.js";
+export { openTaskStore, readTaskHistory, readTaskNamespaces } from "./task-git-store.js";
 export { taskRepositoryFromStore } from "./task-store-repository.js";
 export { isTaskId } from "./validation.js";
-export { buildTaskTree, createTask, doneTask, dropTask, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, updateTask, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";
+export { isTaskCoordinate, parseTaskCoordinate, taskCoordinateFromSourcePath } from "./coordinate.js";
+export { buildTaskTree, createTask, doneTask, dropTask, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, holdTask, resumeTask, updateTask, updateTaskWithReceipt, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";

package/build/core/task/query.js

@@ -1,18 +1,19 @@
 import { FlowError } from "../../flow-error.js";
 import { isCommissionId } from "../ids.js";
 import { taskUpdatedAt } from "./model.js";
-import { isTaskId } from "./validation.js";
+import { isTaskCoordinate } from "./coordinate.js";
+import { parseStructuredQuery, STRUCTURED_QUERY_COMPLETION, STRUCTURED_QUERY_GRAMMAR, } from "../structured-query.js";
 export const TASK_FILTER_FIELDS = [
     "title", "state", "priority", "parent", "needs", "blocks", "contract", "created", "updated",
 ];
 export const TASK_FILTER_OPERATORS = ["=", "!=", "~", "<", "<=", ">", ">="];
-export const TASK_FILTER_GRAMMAR = "FIELD OP VALUE[,VALUE...] [| FIELD OP VALUE[,VALUE...]]...";
-export const TASK_FILTER_COMPLETION = "FIELD OP VALUE[,VALUE...]|FIELD OP VALUE[,VALUE...]";
+export const TASK_FILTER_GRAMMAR = STRUCTURED_QUERY_GRAMMAR;
+export const TASK_FILTER_COMPLETION = STRUCTURED_QUERY_COMPLETION;
 const FILTER_FIELDS = new Set(TASK_FILTER_FIELDS);
 const ORDERED_FIELDS = new Set(["priority", "created", "updated"]);
 const TITLE_OPERATORS = new Set(["=", "!=", "~"]);
 const ORDERED_OPERATORS = new Set(["=", "!=", "<", "<=", ">", ">="]);
-const DISPLAY_VALUES = new Set(["ready", "blocked", "in_progress", "done", "dropped", "bound"]);
+const DISPLAY_VALUES = new Set(["ready", "blocked", "in_progress", "on_hold", "done", "dropped", "bound"]);
 const SORT_KEYS = new Set(["priority", "modified", "created"]);
 const RELATIVE_TIME = /^now-([1-9][0-9]*)([smhdw])$/;
 const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
@@ -21,6 +22,8 @@ export function deriveTaskDisplay(task) {
         return "done";
     if (task.state === "drop")
         return "dropped";
+    if (task.state === "on_hold")
+        return "on_hold";
     if (task.contractId !== undefined)
         return "bound";
     if (task.state === "in_progress")
@@ -43,14 +46,7 @@ function invalidFilter(detail, recoveredTerms = []) {
         },
     });
 }
-function parseTaskFilterTerm(term, expression, recoveredTerms) {
-    const match = /^([a-z][a-z0-9_-]*)(!=|<=|>=|~|=|<|>)(.*)$/.exec(term);
-    if (!match)
-        invalidFilter(`'${expression}' must use ${TASK_FILTER_GRAMMAR}`, recoveredTerms);
-    const field = match[1];
-    const operator = match[2];
-    if (!FILTER_FIELDS.has(field))
-        invalidFilter(`unknown field '${field}'`, recoveredTerms);
+function validateTaskFilterTerm(field, operator, values, recoveredTerms) {
     if (field === "title" && !TITLE_OPERATORS.has(operator)) {
         invalidFilter(`field '${field}' does not support operator '${operator}'`, recoveredTerms);
     }
@@ -59,21 +55,15 @@ function parseTaskFilterTerm(term, expression, recoveredTerms) {
         : operator !== "=" && operator !== "!=")) {
         invalidFilter(`field '${field}' does not support operator '${operator}'`, recoveredTerms);
     }
-    const values = match[3].split(",");
-    if (values.some((value) => value.length === 0))
-        invalidFilter(`field '${field}' has an empty value`, recoveredTerms);
     validateFilterValues(field, values, recoveredTerms);
-    return { field, operator, values };
 }
 export function parseTaskFilter(expression) {
-    const terms = expression.split("|");
-    const parsed = [];
-    for (const term of terms) {
-        if (term.length === 0)
-            invalidFilter(`'${expression}' must use ${TASK_FILTER_GRAMMAR}`, parsed);
-        parsed.push(parseTaskFilterTerm(term, expression, parsed));
-    }
-    return parsed;
+    return parseStructuredQuery({
+        expression,
+        fields: FILTER_FIELDS,
+        invalid: invalidFilter,
+        validate: validateTaskFilterTerm,
+    });
 }
 function parseTimestamp(value, nowMs, recoveredTerms = []) {
     const relative = RELATIVE_TIME.exec(value);
@@ -114,8 +104,8 @@ function validateFilterValues(field, values, recoveredTerms) {
         for (const value of values) {
             if (field === "parent" && value === "none")
                 continue;
-            if (!isTaskId(value))
-                invalidFilter(`value '${value}' must be a canonical full task id`, recoveredTerms);
+            if (!isTaskCoordinate(value))
+                invalidFilter(`value '${value}' must be a canonical full task coordinate`, recoveredTerms);
         }
         return;
     }
@@ -183,7 +173,7 @@ function selected(task, selection) {
 }
 function displayOrder(task) {
     const display = deriveTaskDisplay(task);
-    return display === "in_progress" ? 0 : display === "ready" ? 1 : display === "blocked" ? 2 : display === "bound" ? 3 : display === "done" ? 4 : 5;
+    return display === "in_progress" ? 0 : display === "on_hold" ? 1 : display === "ready" ? 2 : display === "blocked" ? 3 : display === "bound" ? 4 : display === "done" ? 5 : 6;
 }
 function defaultCompare(left, right) {
     return displayOrder(left) - displayOrder(right)