@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/cli/commands/task.js

@@ -1,394 +1,444 @@
-import { CliUsageError, isBlankInput, TASK_FAMILY_USAGE_GUIDE, unknownCommandGuide, } from "../usage.js";
+import { CliUsageError, isBlankInput } from "../usage.js";
 import { parseTaskNamespaceSelector } from "../../task/catalog.js";
-import { parseTaskQueryExpression, validateTaskLimit, validateTaskParent, } from "./task-query.js";
-const COMMON = { json: "boolean" };
-const TASK_COMMAND_SPECS = {
-    add: {
-        arity: [0, 1],
-        stdin: "document",
-        flags: {
-            ...COMMON,
-            namespace: "value",
-            state: "value",
-            priority: "value",
-            needs: "repeat",
-            parent: "value",
-            supersedes: "repeat",
-            relates: "repeat",
-            body: "value",
-            note: "value",
-            actor: "value",
-        },
-        usage: `task add <TITLE> [--namespace <ns>] [--priority 0..3]
-  [--state open|in_progress|on_hold|done|drop]
-  [--note <text>] [--actor <actor>]
-  [--needs <TaskId>]... [--parent <TaskId>]
-  [--supersedes <TaskId>]... [--relates <TaskId>]...
-  [--body <text>]
-task add [--namespace <ns>] [--actor <actor>] -`,
-        purpose: "Create a Task from flags or a Task document on stdin.",
-    },
-    show: {
-        arity: [1, Number.POSITIVE_INFINITY],
-        flags: COMMON,
-        usage: "task show <TaskId>...",
-        purpose: "Read one or more Tasks and their relationships.",
-    },
-    ls: {
-        arity: [0, 1],
-        flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" },
-        usage: "task ls [<namespace-selector>] [--closed | --all] [--world] [--limit <n>]",
-        purpose: "List Tasks in the selected namespace.",
-        details: [
-            "With no selector, lists the current directory Task context.",
-            "task/ selects the root namespace; --world lists every namespace in the current Task world.",
-        ].join("\n"),
-    },
-    ready: {
-        arity: [0, 0],
-        flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" },
-        usage: "task ready [--world] [--parent <TaskId>] [--limit <n>]",
-        purpose: "List open Tasks whose every dependency is complete or dropped.",
-        details: "--world lists every namespace in the current Task world.",
-    },
-    blocked: {
-        arity: [0, 0],
-        flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" },
-        usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>]",
-        purpose: "List Tasks with unmet dependencies.",
-        details: "--world lists every namespace in the current Task world.",
-    },
-    query: {
-        arity: [0, 0],
-        flags: { ...COMMON, where: "value", world: "boolean", sort: "value", limit: "value" },
-        usage: `task query [--where <expression>] [--world]
-  [--sort priority|created|updated|id] [--limit <n>]`,
-        purpose: "Filter and sort Tasks with a boolean expression.",
-        details: [
-            "fields: state priority title id parent under needs blocks ready blocked created updated",
-            "operators: = != < > <= >= ~ and or not ( )",
-            "sort: priority and created ascend; updated descends; id is lexical. Default: priority.",
-            "--world lists every namespace in the current Task world.",
-            "examples:",
-            "  keiyaku task query --where 'priority <= 1 and ready' --world",
-            "  keiyaku task query --where 'updated < 2026-08-06T00:00:00.000Z' --world",
-        ].join("\n"),
-    },
-    tree: {
-        arity: [1, 1],
-        flags: COMMON,
-        usage: "task tree <TaskId>",
-        purpose: "Show a Task and its parent/child breakdown.",
-    },
-    doctor: {
-        arity: [0, 0],
-        flags: COMMON,
-        usage: "task doctor",
-        purpose: "Check Tasks for inconsistencies without changing them.",
-    },
-    update: {
-        arity: [1, 1],
-        flags: {
-            ...COMMON,
-            title: "value",
-            body: "value",
-            append: "value",
-            note: "value",
-            priority: "value",
-            needs: "repeat",
-            "drop-needs": "repeat",
-            parent: "value",
-            "no-parent": "boolean",
-            supersedes: "repeat",
-            "drop-supersedes": "repeat",
-            relates: "repeat",
-            "drop-relates": "repeat",
-        },
-        usage: `task update <TaskId> [--title <text>] [--body <text>|- | --append <text>]
-  [--note <text>]
-  [--priority 0..3] [--needs <TaskId>]... [--drop-needs <TaskId>]...
-  [--parent <TaskId> | --no-parent]
-  [--supersedes <TaskId>]... [--drop-supersedes <TaskId>]...
-  [--relates <TaskId>]... [--drop-relates <TaskId>]...`,
-        purpose: "Change a Task's fields and relationships.",
-        details: [
-            "--body replaces the body; --append adds text after it, separated by a newline when needed.",
-            "--body - reads replacement body text from stdin.",
-        ].join("\n"),
-    },
-    start: {
-        arity: [1, Number.POSITIVE_INFINITY],
-        flags: COMMON,
-        usage: "task start <TaskId>...",
-        purpose: "Move one or more open Tasks into progress.",
-    },
-    stop: {
-        arity: [1, 1],
-        flags: COMMON,
-        usage: "task stop <TaskId>",
-        purpose: "Return one in-progress Task to open.",
-    },
-    hold: {
-        arity: [1, Number.POSITIVE_INFINITY],
-        flags: COMMON,
-        usage: "task hold <TaskId>...",
-        purpose: "Put one or more Tasks on hold.",
-    },
-    resume: {
-        arity: [1, 1],
-        flags: COMMON,
-        usage: "task resume <TaskId>",
-        purpose: "Return one held Task to open.",
-    },
-    done: {
-        arity: [1, Number.POSITIVE_INFINITY],
-        flags: { ...COMMON, note: "value" },
-        usage: "task done <TaskId>... [--note <text>]",
-        purpose: "Mark one or more Tasks done.",
-    },
-    drop: {
-        arity: [1, Number.POSITIVE_INFINITY],
-        flags: { ...COMMON, note: "value" },
-        usage: "task drop <TaskId>... [--note <text>]",
-        purpose: "Mark one or more Tasks as no longer needed.",
-    },
-    context: {
-        arity: [0, 1],
-        flags: COMMON,
-        usage: "task context [<namespace>]",
-        purpose: "Set or read the default Task namespace for this directory.",
-        details: "Omit <namespace> to read the current context; use / to reset it to the root namespace.",
-    },
-    compose: {
-        arity: [0, 0],
-        stdin: "compose",
-        flags: { ...COMMON, actor: "value", plan: "boolean" },
-        usage: "task compose [--actor <actor>] [--plan] -",
-        purpose: "Create or update several Tasks from one document, with an optional preview.",
-        details: [
-            "nodes: + <Title> creates; @task/<id> modifies a pre-existing Task",
-            "properties: as = <alias>; state = open|in_progress|on_hold|done|drop; pri = 0..3; parent = <ref>|empty",
-            "relations: needs|supersedes|relates with =, +=, or -=",
-            "references: @task/... is pre-existing; ^alias is new in this document",
-            "body: body = clears; body <<TOKEN reads exact content to TOKEN",
-            "TOKEN: [A-Z][A-Z0-9_]* with length 3..32",
-            "example:",
-            "  ns=feature",
-            "  + Parent",
-            "  as = parent",
-            "  pri = 1",
-            "  body <<BODY",
-            "  Exact body bytes.",
-            "  BODY",
-            "  + Child",
-            "  parent = ^parent",
-        ].join("\n"),
-    },
-};
-export function isTaskAction(value) {
-    return value !== undefined && Object.hasOwn(TASK_COMMAND_SPECS, value);
+import { taskRowViewLimit, tasksWithExecution, } from "../../task/index.js";
+import { taskCompositionNamespaceHeader } from "../../task/compose-language.js";
+import { resolveTaskNamespaceContext, writeTaskNamespaceContext } from "../../task/context.js";
+import { displayContext, writeJson, writeStderr, writeStdout } from "../streams.js";
+import { renderTaskCompose, renderTaskContext, renderTaskDoctor, renderTaskFailure, renderTaskIncompleteDiagnostic, renderTaskLifecycle, renderTaskList, renderTaskMutation, renderTaskShow, renderTaskTree, renderTaskUpdate, taskExitCode, } from "../render/task.js";
+import { actorFromEdge } from "../actor.js";
+import { taskQuerySelection } from "../../task/query.js";
+export { renderTaskHelp } from "./task-grammar.js";
+function value(command, name) {
+    const item = command.flags[name];
+    return typeof item === "string" ? item : undefined;
 }
-export function renderTaskHelp(action) {
-    if (action !== undefined) {
-        const spec = TASK_COMMAND_SPECS[action];
-        return `${spec.purpose}\n\n${renderTaskUsage(action)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`;
-    }
-    return [
-        "usage  keiyaku task <command> ...",
-        "",
-        "commands:",
-        ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage
-            .split("\n")
-            .map((line) => `  ${line}`)
-            .concat(`    ${spec.purpose}`)),
-    ].join("\n");
+function values(command, name) {
+    const item = command.flags[name];
+    return Array.isArray(item) ? item : undefined;
 }
-export function renderTaskUsage(action) {
-    return TASK_COMMAND_SPECS[action].usage
-        .split("\n")
-        .map((line, index) => {
-        if (index === 0 || line.trimStart().startsWith("task ")) {
-            const command = line.trimStart().startsWith("task ") ? `keiyaku ${line.trim()}` : `keiyaku ${line}`;
-            return `${index === 0 ? "usage  " : "      "}${command}`;
-        }
-        return `      ${line.trim()}`;
-    })
-        .join("\n");
+function namespace(raw) {
+    return raw === undefined ? undefined : raw === "/" ? [] : raw.split("/");
 }
-function taskUsage(action) {
-    const lines = TASK_COMMAND_SPECS[action].usage.split("\n");
-    return lines
-        .map((line, index) => {
-        if (index === 0 || line.trimStart().startsWith("task "))
-            return `keiyaku ${line.trim()}`;
-        return `           ${line.trim()}`;
-    })
-        .join("\n");
+function priority(raw) {
+    if (raw === undefined)
+        return undefined;
+    return Number(raw);
 }
-export function taskUsageGuide(action) {
-    return {
-        scope: `keiyaku task ${action}`,
-        accepts: taskUsage(action),
-        help: `keiyaku task ${action} --help`,
-    };
+function ids(items) {
+    return items;
 }
-function setFlag(flags, name, kind, value, fail) {
-    if (flags[name] !== undefined && kind !== "repeat")
-        fail(`duplicate option: --${name}`);
-    if (kind === "boolean") {
-        flags[name] = true;
-        return;
-    }
-    if (value === undefined)
-        fail(`--${name} requires a value`);
-    if (isBlankInput(value))
-        fail(`--${name} requires a nonblank value`);
-    if (kind === "repeat") {
-        const current = flags[name];
-        flags[name] = [...(Array.isArray(current) ? current : []), value];
+function limit(command) {
+    const raw = value(command, "limit");
+    return raw === undefined ? undefined : Number(raw);
+}
+function validateTaskRowView(command) {
+    if (command.action === "ls" ||
+        command.action === "ready" ||
+        command.action === "blocked" ||
+        command.action === "query")
+        taskRowViewLimit(limit(command));
+}
+function explicitListNamespace(command) {
+    return command.action === "ls" && command.positionals.length === 1
+        ? parseTaskNamespaceSelector(command.positionals[0])
+        : undefined;
+}
+function taskStdinDiagnostic(command) {
+    switch (command.stdin) {
+        case "document":
+            return "task add requires a nonblank stdin document";
+        case "compose":
+            return "task compose requires a nonblank stdin document";
+        case "body":
+            return "task update --body requires a nonblank value";
+        case "append":
+            return "task update --append requires a nonblank value";
+        case "note":
+            return "task update --note requires a nonblank value";
+        default:
+            return undefined;
     }
+}
+/**
+ * The shared output primitive: one native answer, its matching rendered text, and the native exit
+ * classifier's verdict. JSON writes the untouched native value; text writes the rendered lines.
+ */
+function emitTask(output, result, project, code) {
+    if (output === "json")
+        writeJson(result);
     else
-        flags[name] = value;
+        writeStdout(project());
+    return code;
+}
+async function invokeAdd(input) {
+    const { tasks, command, current = [] } = input;
+    const selectedNamespace = namespace(value(command, "namespace")) ?? current;
+    const actor = input.actor;
+    if (command.stdin === "document") {
+        return tasks.addDocument({
+            markdown: input.stdin,
+            ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }),
+            ...(actor === undefined ? {} : { actor }),
+        });
+    }
+    const body = value(command, "body"), note = value(command, "note"), initialState = value(command, "state"), selectedPriority = priority(value(command, "priority"));
+    const needs = ids(values(command, "needs")), parent = value(command, "parent");
+    const supersedes = ids(values(command, "supersedes")), relates = ids(values(command, "relates"));
+    return tasks.add({
+        title: command.positionals[0],
+        ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }),
+        ...(body === undefined ? {} : { body }),
+        ...(note === undefined ? {} : { note }),
+        ...(initialState === undefined ? {} : { state: initialState }),
+        ...(selectedPriority === undefined ? {} : { priority: selectedPriority }),
+        ...(needs === undefined ? {} : { needs }),
+        ...(parent === undefined ? {} : { parent: parent }),
+        ...(supersedes === undefined ? {} : { supersedes }),
+        ...(relates === undefined ? {} : { relates }),
+        ...(actor === undefined ? {} : { actor }),
+    });
+}
+function invokeUpdate(input) {
+    const { tasks, command, stdin } = input;
+    const body = command.stdin === "body" ? stdin : value(command, "body"), appendBody = command.stdin === "append" ? stdin : value(command, "append");
+    const note = command.stdin === "note" ? stdin : value(command, "note");
+    const title = value(command, "title"), selectedPriority = priority(value(command, "priority"));
+    const addNeeds = ids(values(command, "needs")), dropNeeds = ids(values(command, "drop-needs"));
+    const parent = value(command, "parent"), addSupersedes = ids(values(command, "supersedes"));
+    const dropSupersedes = ids(values(command, "drop-supersedes")), addRelates = ids(values(command, "relates"));
+    const dropRelates = ids(values(command, "drop-relates"));
+    return tasks.task({ id: command.positionals[0] }).update({
+        ...(title === undefined ? {} : { title }),
+        ...(body === undefined ? {} : { body }),
+        ...(appendBody === undefined ? {} : { appendBody }),
+        ...(note === undefined ? {} : { note }),
+        ...(selectedPriority === undefined ? {} : { priority: selectedPriority }),
+        ...(addNeeds === undefined ? {} : { addNeeds }),
+        ...(dropNeeds === undefined ? {} : { dropNeeds }),
+        ...(command.flags["no-parent"] === true
+            ? { parent: null }
+            : parent === undefined
+                ? {}
+                : { parent: parent }),
+        ...(addSupersedes === undefined ? {} : { addSupersedes }),
+        ...(dropSupersedes === undefined ? {} : { dropSupersedes }),
+        ...(addRelates === undefined ? {} : { addRelates }),
+        ...(dropRelates === undefined ? {} : { dropRelates }),
+    });
 }
-function scanTaskOption(input, fail) {
-    const token = input.argv[input.index], name = token.slice(2), kind = input.spec.flags[name];
-    if (kind === undefined)
-        fail(`option ${token} is not valid for task ${input.action}`);
-    const next = kind === "boolean" ? undefined : input.argv[input.index + 1];
-    if (next === "-" && input.action === "update" && name === "body") {
-        if (input.stdin !== undefined)
-            fail("stdin marker '-' may appear only once");
-        input.flags[name] = "";
-        return { index: input.index + 1, stdin: name };
+function readScope(command, current) {
+    return command.flags.world === true ? { scope: "world" } : { namespace: current ?? [] };
+}
+/** One addressed read per caller-supplied id, in caller order; the native null survives to JSON. */
+async function runShow(command, tasks) {
+    const handles = command.positionals.map((taskId) => tasks.task({ id: taskId }).id);
+    const details = [];
+    for (const id of handles)
+        details.push(await tasks.task({ id }).read());
+    const missing = details.findIndex((detail) => detail === null);
+    const code = missing >= 0 ? 1 : 0;
+    if (command.output === "json") {
+        writeJson(handles.length === 1 ? details[0] : details);
+        return code;
+    }
+    if (missing >= 0) {
+        const refusal = { kind: "refused", refusal: { kind: "task-missing", taskId: handles[missing] } };
+        return emitTask(command.output, refusal, () => renderTaskShow(refusal, displayContext()), code);
     }
-    if (kind !== "boolean" && (next === undefined || next.startsWith("--") || next === "-"))
-        fail(`--${name} requires a value`);
-    setFlag(input.flags, name, kind, next, fail);
-    return {
-        index: input.index + (kind === "boolean" ? 0 : 1),
-        ...(input.stdin === undefined ? {} : { stdin: input.stdin }),
-    };
+    const found = details.filter((detail) => detail !== null);
+    const result = found.length === 1 ? found[0] : found;
+    return emitTask(command.output, result, () => renderTaskShow(result, displayContext()), code);
+}
+/** Presentation-only list scope the leaf acquired, never part of the native answer. */
+function listPresentation(command) {
+    if (command.flags.world === true)
+        return "world";
+    const first = command.positionals[0];
+    return command.action === "ls" && first !== undefined ? { namespace: first } : "current";
 }
-function scanTaskArgv(action, argv, fail) {
-    const spec = TASK_COMMAND_SPECS[action], positionals = [], flags = {};
-    let stdin;
-    for (let index = 1; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (token === "-") {
-            if (spec.stdin === undefined)
-                fail("stdin marker '-' is not valid here");
-            if (stdin !== undefined)
-                fail("stdin marker '-' may appear only once");
-            stdin = spec.stdin;
-            continue;
+async function runRead(input) {
+    const { tasks, command, current } = input;
+    const id = command.positionals[0];
+    const scope = listPresentation(command);
+    switch (command.action) {
+        case "ls": {
+            const result = await tasks.list({
+                selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active",
+                ...(explicitListNamespace(command) === undefined
+                    ? readScope(command, current)
+                    : { namespace: explicitListNamespace(command) }),
+                ...(limit(command) === undefined ? {} : { limit: limit(command) }),
+            });
+            return emitTask(command.output, result, () => renderTaskList("ls", scope, result, displayContext()), taskExitCode(result));
+        }
+        case "ready": {
+            const result = await tasks.ready({
+                ...readScope(command, current),
+                ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }),
+                ...(limit(command) === undefined ? {} : { limit: limit(command) }),
+            });
+            return emitTask(command.output, result, () => renderTaskList("ready", scope, result, displayContext()), taskExitCode(result));
+        }
+        case "blocked": {
+            const result = await tasks.blocked({
+                ...readScope(command, current),
+                ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }),
+                ...(limit(command) === undefined ? {} : { limit: limit(command) }),
+            });
+            return emitTask(command.output, result, () => renderTaskList("blocked", scope, result, displayContext()), taskExitCode(result));
         }
-        if (!token.startsWith("--")) {
-            if (isBlankInput(token))
-                fail(`task ${action} requires a nonblank value`);
-            positionals.push(token);
-            continue;
+        case "query": {
+            const result = await tasks.query({
+                where: taskQuerySelection(command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", command.where),
+                ...readScope(command, current),
+                ...(value(command, "sort") === undefined ? {} : { sort: value(command, "sort") }),
+                ...(limit(command) === undefined ? {} : { limit: limit(command) }),
+            });
+            return emitTask(command.output, result, () => renderTaskList("query", scope, result, displayContext()), taskExitCode(result));
         }
-        const scanned = scanTaskOption({ action, spec, argv, index, flags, ...(stdin === undefined ? {} : { stdin }) }, fail);
-        index = scanned.index;
-        stdin = scanned.stdin;
+        case "tree": {
+            const result = await tasks.task({ id }).tree();
+            return emitTask(command.output, result, () => renderTaskTree(result, displayContext()), taskExitCode(result));
+        }
+        case "doctor": {
+            const result = await tasks.doctor();
+            return emitTask(command.output, result, () => renderTaskDoctor(result), taskExitCode(result));
+        }
+        default:
+            throw new Error(`task action is not a read: ${command.action}`);
     }
-    return { positionals, flags, ...(stdin === undefined ? {} : { stdin }) };
 }
-function validateUpdate(scanned, fail) {
-    const flags = scanned.flags;
-    if (flags.body !== undefined && flags.append !== undefined)
-        fail("--body and --append are mutually exclusive");
-    if (flags.parent !== undefined && flags["no-parent"] === true)
-        fail("--parent and --no-parent are mutually exclusive");
-    if (Object.keys(flags).every((name) => name === "json"))
-        fail("task update requires at least one patch option");
+function isWorldObservationAction(command) {
+    return (command.action === "ls" ||
+        command.action === "ready" ||
+        command.action === "blocked" ||
+        command.action === "query" ||
+        command.action === "doctor");
 }
-function validateTaskReadFlags(action, flags, fail) {
-    if (action === "ls" && flags.closed === true && flags.all === true)
-        fail("--closed and --all are mutually exclusive");
-    if (action === "ls" && flags.world === true) {
-        // An explicit selector is checked below, after positional shape is known.
-    }
-    if (typeof flags.limit === "string") {
-        try {
-            validateTaskLimit(flags.limit);
-        }
-        catch (error) {
-            fail(error instanceof Error ? error.message : String(error));
+function missingTask(id) {
+    return { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+}
+/**
+ * The one CLI edge mapping a Task action with no World to its native refusal answer, then through
+ * the matching action renderer and the native exit classifier.
+ */
+function missingWorld(command) {
+    const output = command.output;
+    if (command.action === "show") {
+        // An addressed missing read keeps its native null in JSON; text refuses without partial output.
+        if (output === "json") {
+            writeJson(command.positionals.length === 1 ? null : command.positionals.map(() => null));
+            return 1;
         }
+        const refusal = missingTask(command.positionals[0]);
+        return emitTask(output, refusal, () => renderTaskShow(refusal, displayContext()), 1);
     }
-    if (typeof flags.sort === "string" &&
-        flags.sort !== "priority" &&
-        flags.sort !== "created" &&
-        flags.sort !== "updated" &&
-        flags.sort !== "id") {
-        fail("--sort must be priority, created, updated, or id");
+    if (isWorldObservationAction(command) || (command.action === "compose" && command.flags.plan === true)) {
+        if (output === "json")
+            writeJson({ kind: "absent" });
+        else
+            writeStdout("task world absent");
+        return 1;
     }
-    if ((action === "ready" || action === "blocked") && typeof flags.parent === "string") {
-        try {
-            validateTaskParent(flags.parent);
-        }
-        catch (error) {
-            fail(error instanceof Error ? error.message : String(error));
+    if (command.action === "context") {
+        const result = { kind: "accepted", value: { namespace: [], source: "default-root" } };
+        return emitTask(output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
+    }
+    if (command.action === "tree") {
+        const result = missingTask(command.positionals[0]);
+        return emitTask(output, result, () => renderTaskTree(result, displayContext()), taskExitCode(result));
+    }
+    if (command.action === "update") {
+        const result = missingTask(command.positionals[0]);
+        return emitTask(output, result, () => renderTaskUpdate(result, displayContext()), taskExitCode(result));
+    }
+    if (command.action === "start" ||
+        command.action === "stop" ||
+        command.action === "hold" ||
+        command.action === "resume") {
+        if (command.positionals.length === 1) {
+            const result = missingTask(command.positionals[0]);
+            return emitTask(output, result, () => renderTaskMutation(command.action, result, displayContext()), taskExitCode(result));
         }
+        const result = {
+            items: command.positionals.map((id) => ({ id: id, outcome: missingTask(id) })),
+        };
+        return emitTask(output, result, () => renderTaskLifecycle(command.action, result, displayContext()), taskExitCode(result));
+    }
+    if (command.action === "done" || command.action === "drop") {
+        const result = {
+            items: command.positionals.map((id) => ({ id: id, outcome: missingTask(id) })),
+        };
+        return emitTask(output, result, () => renderTaskLifecycle(command.action, result, displayContext()), taskExitCode(result));
     }
+    throw new Error(`task action has no missing-world answer: ${command.action}`);
 }
-function validateTaskScan(action, scanned, fail) {
-    const spec = TASK_COMMAND_SPECS[action], { positionals, flags, stdin } = scanned;
-    if (positionals.length < spec.arity[0] || positionals.length > spec.arity[1])
-        fail(`task ${action} has invalid positional arguments`);
-    if (action === "add" && (stdin === "document") === (positionals.length === 1))
-        fail("task add requires either TITLE or '-' input");
-    if (action === "add" &&
-        stdin === "document" &&
-        Object.keys(flags).some((name) => name !== "json" && name !== "namespace" && name !== "actor"))
-        fail("task add document input owns its creation fields");
-    if (action === "compose" && stdin !== "compose")
-        fail("task compose requires '-' input");
-    if (action === "ls" && positionals.length === 1) {
-        const selector = positionals[0];
-        if (selector !== "task/" && (!selector.startsWith("task/") || !selector.endsWith("/")))
-            fail(`invalid Task namespace selector: ${selector}`);
-        if (selector !== "task/") {
-            try {
-                parseTaskNamespaceSelector(selector);
-            }
-            catch (error) {
-                fail(error instanceof Error ? error.message : String(error));
+/**
+ * One compose execution outcome: JSON keeps the untouched native value, while an incomplete text
+ * answer recovers its draft and puts the diagnostic on stderr.
+ */
+function emitCompose(output, result) {
+    if (output === "json") {
+        writeJson(result);
+        return taskExitCode(result);
+    }
+    if (result.kind === "incomplete") {
+        const diagnostic = renderTaskIncompleteDiagnostic(result);
+        if (diagnostic.length > 0)
+            writeStderr(diagnostic);
+        process.stdout.write(result.draft);
+        return taskExitCode(result);
+    }
+    writeStdout(renderTaskCompose(result, displayContext()));
+    return taskExitCode(result);
+}
+/** One plural Task lifecycle answer: every verb shares the same batch shape and renderer. */
+async function runBatchLifecycle(tasks, command, verb) {
+    const note = value(command, "note");
+    const result = await tasks.batch({
+        verb,
+        ids: command.positionals,
+        ...(note === undefined ? {} : { note }),
+    });
+    return emitTask(command.output, result, () => renderTaskLifecycle(verb, result, displayContext()), taskExitCode(result));
+}
+async function runMutation(input) {
+    const { tasks, command, current, stdin, composeMarkdown, composeNamespace } = input;
+    if (isWorldObservationAction(command) || command.action === "tree")
+        return await runRead(input);
+    switch (command.action) {
+        case "add": {
+            const result = await invokeAdd(input);
+            return emitTask(command.output, result, () => renderTaskMutation("add", result, displayContext()), taskExitCode(result));
+        }
+        case "update": {
+            const result = await invokeUpdate(input);
+            return emitTask(command.output, result, () => renderTaskUpdate(result, displayContext()), taskExitCode(result));
+        }
+        case "start":
+        case "stop":
+        case "resume": {
+            const result = await invokeLifecycle(tasks, command.positionals, command.positionals[0], command.action);
+            return emitTask(command.output, result, () => renderTaskLifecycle(command.action, result, displayContext()), taskExitCode(result));
+        }
+        case "hold":
+        case "done":
+        case "drop":
+            return await runBatchLifecycle(tasks, command, command.action);
+        case "context": {
+            const selected = namespace(command.positionals[0]);
+            if (selected !== undefined) {
+                await writeTaskNamespaceContext(input.context.writeRoot ?? input.context.directory, selected);
+                const resolved = await resolveTaskNamespaceContext(input.context);
+                if (typeof resolved === "object" && "kind" in resolved) {
+                    const result = { kind: "refused", refusal: resolved };
+                    return emitTask(command.output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
+                }
+                const result = { kind: "accepted", value: resolved };
+                return emitTask(command.output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
             }
+            const result = {
+                kind: "accepted",
+                value: { namespace: current ?? [], source: "default-root" },
+            };
+            return emitTask(command.output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
         }
-        if (flags.world === true)
-            fail("--world cannot be combined with an explicit Task namespace selector");
+        case "compose": {
+            const result = await tasks.compose({
+                markdown: composeMarkdown ?? stdin ?? "",
+                namespace: composeNamespace ?? current ?? [],
+                ...(input.actor === undefined ? {} : { actor: input.actor }),
+                ...(command.flags.plan === true ? { plan: true } : {}),
+            });
+            return emitCompose(command.output, result);
+        }
+        default:
+            throw new Error(`task action has no invocation: ${command.action}`);
     }
-    validateTaskReadFlags(action, flags, fail);
-    if (action === "update")
-        validateUpdate(scanned, fail);
 }
-export function parseTaskCommand(argv) {
-    const candidate = argv[0];
-    if (!isTaskAction(candidate)) {
-        throw new CliUsageError(`unknown task command: ${candidate ?? ""}`, unknownCommandGuide(TASK_FAMILY_USAGE_GUIDE, candidate ?? ""));
-    }
-    const action = candidate;
-    const fail = (message) => {
-        throw new CliUsageError(message, taskUsageGuide(action));
-    };
-    const scanned = scanTaskArgv(action, argv, fail);
-    validateTaskScan(action, scanned, fail);
-    let where;
-    if (action === "query" && typeof scanned.flags.where === "string") {
-        try {
-            where = parseTaskQueryExpression(scanned.flags.where);
+function invokeLifecycle(tasks, taskIds, firstId, verb) {
+    return taskIds.length === 1 ? tasks.task({ id: firstId })[verb]() : tasks.batch({ verb, ids: taskIds });
+}
+function establishesWorld(command) {
+    return (command.action === "add" ||
+        (command.action === "compose" && command.flags.plan !== true) ||
+        (command.action === "context" && command.positionals.length > 0));
+}
+/**
+ * One CLI edge turning a namespace-context refusal into the addressed action's native refusal
+ * answer, rendered through the matching action renderer and classified natively.
+ */
+function refuseNamespace(command, refusal) {
+    const result = { kind: "refused", refusal };
+    switch (command.action) {
+        case "ls":
+        case "ready":
+        case "blocked":
+        case "query": {
+            const action = command.action;
+            return emitTask(command.output, result, () => renderTaskList(action, listPresentation(command), result, displayContext()), taskExitCode(result));
         }
-        catch (error) {
-            fail(error instanceof Error ? error.message : String(error));
+        case "add":
+            return emitTask(command.output, result, () => renderTaskMutation("add", result, displayContext()), taskExitCode(result));
+        case "context":
+            return emitTask(command.output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
+        case "compose":
+            return emitTask(command.output, result, () => renderTaskFailure("compose", result, displayContext()), taskExitCode(result));
+        default:
+            throw new Error(`task action has no namespace refusal: ${command.action}`);
+    }
+}
+// eslint-disable-next-line complexity -- this is the single CLI edge ordering world, context, forwarding, and local execution.
+export async function runTaskCommand(command, coordinates, runtime) {
+    validateTaskRowView(command);
+    const stdinDiagnostic = taskStdinDiagnostic(command);
+    const stdin = stdinDiagnostic === undefined ? undefined : await runtime.readStdin();
+    if (stdinDiagnostic !== undefined && isBlankInput(stdin ?? ""))
+        throw new CliUsageError(stdinDiagnostic);
+    const planOnly = command.action === "compose" && command.flags.plan === true;
+    const composeMarkdown = command.action === "compose" ? stdin : undefined;
+    const composition = composeMarkdown === undefined ? undefined : taskCompositionNamespaceHeader(composeMarkdown);
+    const explicitNamespace = command.action === "add"
+        ? namespace(value(command, "namespace"))
+        : command.action === "compose" && composition?.specified
+            ? composition.namespace
+            : undefined;
+    const actor = actorFromEdge(typeof command.flags.actor === "string" ? command.flags.actor : undefined, runtime.environment);
+    const world = coordinates.world ??
+        (planOnly ? coordinates.candidateWorld : establishesWorld(command) ? await coordinates.establishWorld() : null);
+    if (world === null)
+        return missingWorld(command);
+    const tasks = tasksWithExecution(world, runtime.execution);
+    const contextSensitive = command.action === "context" ||
+        (command.action === "add" && explicitNamespace === undefined) ||
+        (command.action === "compose" && composition?.specified !== true) ||
+        (((command.action === "ls" && explicitListNamespace(command) === undefined) ||
+            command.action === "ready" ||
+            command.action === "blocked" ||
+            command.action === "query") &&
+            command.flags.world !== true);
+    let current;
+    if (contextSensitive) {
+        const resolved = await resolveTaskNamespaceContext(coordinates.taskContext);
+        if (typeof resolved === "object" && "kind" in resolved)
+            return refuseNamespace(command, resolved);
+        current = resolved.namespace;
+        if (command.action === "context" && command.positionals.length === 0) {
+            const result = { kind: "accepted", value: resolved };
+            return emitTask(command.output, result, () => renderTaskContext(result, displayContext()), taskExitCode(result));
         }
     }
-    return {
-        command: "task",
-        action,
-        output: scanned.flags.json === true ? "json" : "text",
-        ...scanned,
-        ...(where === undefined ? {} : { where }),
-    };
+    if (command.action === "show")
+        return await runShow(command, tasks);
+    return await runMutation({
+        tasks,
+        command,
+        runtime,
+        context: coordinates.taskContext,
+        ...(actor === undefined ? {} : { actor }),
+        ...(current === undefined ? {} : { current }),
+        ...(stdin === undefined ? {} : { stdin }),
+        ...(composeMarkdown === undefined ? {} : { composeMarkdown }),
+        ...(explicitNamespace === undefined ? {} : { composeNamespace: explicitNamespace }),
+    });
 }