@astrosheep/keiyaku 4.0.1 → 4.0.2

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

@@ -7,7 +7,7 @@ function values(command, name) {
     const item = command.flags[name];
     return Array.isArray(item) ? item : undefined;
 }
-function namespace(raw) { return raw === undefined ? undefined : raw === "" ? [] : raw.split("/"); }
+function namespace(raw) { return raw === undefined ? undefined : raw === "/" ? [] : raw.split("/"); }
 function priority(raw) {
     if (raw === undefined)
         return undefined;
@@ -16,10 +16,17 @@ function priority(raw) {
 }
 function state(raw) { return raw; }
 function ids(items) { return items; }
-function invokeAdd(tasks, command, readStdin) {
+function limit(command) { const raw = value(command, "limit"); return raw === undefined ? undefined : Number(raw); }
+async function invokeAdd(tasks, command, input) {
     const selectedNamespace = namespace(value(command, "namespace"));
-    if (command.stdin === "document")
-        return tasks.addDocument({ markdown: readStdin(), ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }) });
+    const actor = input.actor;
+    if (command.stdin === "document") {
+        return tasks.addDocument({
+            markdown: await input.readStdin(),
+            ...(selectedNamespace === undefined ? {} : { namespace: selectedNamespace }),
+            ...(actor === undefined ? {} : { actor }),
+        });
+    }
     const body = value(command, "body"), note = value(command, "note"), initialState = state(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"));
@@ -28,11 +35,12 @@ function invokeAdd(tasks, command, readStdin) {
         ...(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(tasks, command, readStdin) {
-    const body = command.stdin === "body" ? readStdin() : value(command, "body"), appendBody = command.stdin === "append" ? readStdin() : value(command, "append");
-    const note = command.stdin === "note" ? readStdin() : value(command, "note");
+async function invokeUpdate(tasks, command, readStdin) {
+    const body = command.stdin === "body" ? await readStdin() : value(command, "body"), appendBody = command.stdin === "append" ? await readStdin() : value(command, "append");
+    const note = command.stdin === "note" ? await readStdin() : 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"));
@@ -53,24 +61,37 @@ async function invokeRead(tasks, command) {
             const detail = await tasks.task({ id }).read();
             return detail ?? { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
         }
-        case "ls": return tasks.list({ selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", ...(command.flags.world === true ? { scope: "world" } : {}) });
-        case "ready": return tasks.ready(command.flags.world === true ? { scope: "world" } : {});
-        case "blocked": return tasks.blocked(command.flags.world === true ? { scope: "world" } : {});
-        case "tree": return tasks.task({ id }).tree(command.flags.full === true ? { full: true } : {});
+        case "ls": return tasks.list({ selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active", ...(command.flags.world === true ? { scope: "world" } : {}), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "ready": return tasks.ready({ ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "blocked": return tasks.blocked({ ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "parent") === undefined ? {} : { parent: value(command, "parent") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "query": return tasks.query({ ...(command.where === undefined ? {} : { where: command.where }), ...(command.flags.world === true ? { scope: "world" } : {}), ...(value(command, "sort") === undefined ? {} : { sort: value(command, "sort") }), ...(limit(command) === undefined ? {} : { limit: limit(command) }) });
+        case "tree": return tasks.task({ id }).tree();
         case "doctor": return tasks.doctor();
         default: throw new Error(`task action is not a read: ${command.action}`);
     }
 }
+function isWorldObservation(command) {
+    return command.action === "ls" || command.action === "ready" || command.action === "blocked"
+        || command.action === "query" || command.action === "doctor";
+}
+function diagnostic(error) { return error instanceof Error ? error.message : String(error); }
+async function observeWorldRead(tasks, command) {
+    try {
+        return { kind: "present", value: await invokeRead(tasks, command) };
+    }
+    catch (error) {
+        return { kind: "failed", failure: { message: diagnostic(error) } };
+    }
+}
 function missingWorld(command) {
     const missing = (id) => ({
         kind: "refused",
         refusal: { kind: "task-missing", taskId: id },
     });
-    if (command.action === "doctor")
-        return { issues: [] };
-    if (command.action === "ls" || command.action === "ready" || command.action === "blocked" || command.action === "namespace") {
+    if (isWorldObservation(command))
+        return { kind: "absent" };
+    if (command.action === "namespace")
         return { kind: "accepted", value: [] };
-    }
     if (command.action === "hold" || command.action === "done" || command.action === "drop") {
         return { items: command.positionals.map((id) => ({ id: id, outcome: missing(id) })) };
     }
@@ -80,17 +101,19 @@ export async function invokeTask(command, input) {
     let world = input.world;
     if (world === null && (command.action === "add" || command.action === "compose"
         || (command.action === "namespace" && command.positionals.length > 0))) {
-        world = input.establish();
+        world = await input.establish();
     }
     if (world === null)
         return missingWorld(command);
     const tasks = Tasks.of(world);
-    if (["show", "ls", "ready", "blocked", "tree", "doctor"].includes(command.action))
+    if (isWorldObservation(command))
+        return observeWorldRead(tasks, command);
+    if (command.action === "show" || command.action === "tree")
         return invokeRead(tasks, command);
     if (command.action === "add")
-        return invokeAdd(tasks, command, input.readStdin);
+        return await invokeAdd(tasks, command, input);
     if (command.action === "update")
-        return invokeUpdate(tasks, command, input.readStdin);
+        return await invokeUpdate(tasks, command, input.readStdin);
     const id = command.positionals[0];
     switch (command.action) {
         case "start": return tasks.task({ id }).start();
@@ -111,7 +134,7 @@ export async function invokeTask(command, input) {
                 await tasks.setNamespace({ namespace: selected });
             return tasks.namespace();
         }
-        case "compose": return tasks.compose({ markdown: input.readStdin() });
+        case "compose": return tasks.compose({ markdown: await input.readStdin(), ...(input.actor === undefined ? {} : { actor: input.actor }) });
         default: throw new Error(`task action has no invocation: ${command.action}`);
     }
 }

package/build/src/cli/commands/task-query.d.ts

@@ -0,0 +1,5 @@
+import type { TaskQueryExpression } from "../../task/index.js";
+export type { TaskQueryExpression } from "../../task/index.js";
+export declare function parseTaskQueryExpression(source: string): TaskQueryExpression;
+export declare function validateTaskLimit(source: string): void;
+export declare function validateTaskParent(source: string): void;

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

@@ -0,0 +1,247 @@
+import { MAX_TASK_LIMIT, normalizeTaskQuery } from "../../task/query.js";
+function syntax(message, offset) { throw new Error(`${message} at column ${offset + 1}`); }
+function scanString(source, offset) {
+    let index = offset + 1;
+    let value = "";
+    while (index < source.length && source[index] !== "\"") {
+        const character = source[index];
+        if (character !== "\\") {
+            value += character;
+            index += 1;
+            continue;
+        }
+        const escaped = source[index + 1];
+        if (escaped === undefined)
+            syntax("unterminated string", offset);
+        if (escaped !== "\\" && escaped !== "\"")
+            syntax("only \\\\ and \\\" escapes are supported", index);
+        value += escaped;
+        index += 2;
+    }
+    if (source[index] !== "\"")
+        syntax("unterminated string", offset);
+    return { token: { kind: "string", value, offset }, next: index + 1 };
+}
+function scanOperator(source, offset) {
+    const pair = source.slice(offset, offset + 2);
+    if (pair === "!=" || pair === "<=" || pair === ">=") {
+        return { token: { kind: "operator", value: pair, offset }, next: offset + 2 };
+    }
+    const character = source[offset];
+    if (character !== "=" && character !== "<" && character !== ">" && character !== "~")
+        return null;
+    return { token: { kind: "operator", value: character, offset }, next: offset + 1 };
+}
+function scanWord(source, offset) {
+    let index = offset;
+    while (index < source.length && !/[\s()=!<>~"]/u.test(source[index]))
+        index += 1;
+    if (index === offset)
+        syntax(`unexpected ${JSON.stringify(source[offset])}`, offset);
+    return { token: { kind: "word", value: source.slice(offset, index), offset }, next: index };
+}
+function lex(source) {
+    const tokens = [];
+    let index = 0;
+    while (index < source.length) {
+        if (/\s/u.test(source[index])) {
+            index += 1;
+            continue;
+        }
+        const offset = index, character = source[index];
+        if (character === "(") {
+            tokens.push({ kind: "left", value: character, offset });
+            index += 1;
+            continue;
+        }
+        if (character === ")") {
+            tokens.push({ kind: "right", value: character, offset });
+            index += 1;
+            continue;
+        }
+        if (character === "\"") {
+            const scanned = scanString(source, offset);
+            tokens.push(scanned.token);
+            index = scanned.next;
+            continue;
+        }
+        const operator = scanOperator(source, offset);
+        if (operator !== null) {
+            tokens.push(operator.token);
+            index = operator.next;
+            continue;
+        }
+        const word = scanWord(source, offset);
+        tokens.push(word.token);
+        index = word.next;
+    }
+    tokens.push({ kind: "end", value: "", offset: source.length });
+    return tokens;
+}
+function canonicalTaskId(token, field) {
+    if (!token.value.startsWith("task/"))
+        return syntax(`${field} requires a canonical TaskId`, token.offset);
+    return token.value;
+}
+function state(token) {
+    if (token.value !== "open" && token.value !== "in_progress" && token.value !== "on_hold" && token.value !== "done" && token.value !== "drop") {
+        return syntax(`invalid state ${JSON.stringify(token.value)}`, token.offset);
+    }
+    return token.value;
+}
+function priority(token) {
+    const value = Number(token.value);
+    if (!Number.isInteger(value) || value < 0 || value > 3)
+        return syntax("priority requires 0..3", token.offset);
+    return value;
+}
+function boolean(token) {
+    if (token.value === "true")
+        return true;
+    if (token.value === "false")
+        return false;
+    return syntax("boolean predicate requires true or false", token.offset);
+}
+function timestamp(token, field) {
+    const milliseconds = Date.parse(token.value);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== token.value)
+        return syntax(`${field} requires a canonical UTC ISO timestamp`, token.offset);
+    return token.value;
+}
+function equalityOperator(token, field) {
+    if (token.value !== "=" && token.value !== "!=")
+        syntax(`${field} supports only = and !=`, token.offset);
+    return token.value;
+}
+function orderedOperator(token, field) {
+    if (token.value === "~")
+        syntax(`${field} operator is invalid`, token.offset);
+    return token.value;
+}
+function textOperator(token, field) {
+    if (token.value !== "=" && token.value !== "!=" && token.value !== "~") {
+        syntax(`${field} supports only =, !=, and ~`, token.offset);
+    }
+    return token.value;
+}
+function parseTextPredicate(field, operator, value) {
+    const selected = textOperator(operator, field);
+    if (field === "title" && value.kind !== "string")
+        syntax("title values must use double quotes", value.offset);
+    if (field === "id" && selected !== "~")
+        canonicalTaskId(value, "id");
+    return { field, operator: selected, value: value.value };
+}
+function parseRelationPredicate(field, operator, value) {
+    return { field, operator: equalityOperator(operator, field), value: canonicalTaskId(value, field) };
+}
+function parseBooleanPredicate(field, operator, value) {
+    return { field, operator: equalityOperator(operator, field), value: boolean(value) };
+}
+function parseTimestampPredicate(field, operator, value) {
+    return { field, operator: orderedOperator(operator, field), value: timestamp(value, field) };
+}
+class Parser {
+    tokens;
+    index = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    current() { return this.tokens[this.index]; }
+    take() { const token = this.current(); this.index += 1; return token; }
+    word(value) { return this.current().kind === "word" && this.current().value === value; }
+    parse() {
+        const value = this.or();
+        if (this.current().kind !== "end")
+            syntax(`unexpected ${JSON.stringify(this.current().value)}`, this.current().offset);
+        return value;
+    }
+    or() {
+        const terms = [this.and()];
+        while (this.word("or")) {
+            this.take();
+            terms.push(this.and());
+        }
+        return terms.length === 1 ? terms[0] : { kind: "or", terms };
+    }
+    and() {
+        const terms = [this.not()];
+        while (this.word("and")) {
+            this.take();
+            terms.push(this.not());
+        }
+        return terms.length === 1 ? terms[0] : { kind: "and", terms };
+    }
+    not() {
+        if (this.word("not")) {
+            this.take();
+            return { kind: "not", term: this.not() };
+        }
+        return this.primary();
+    }
+    primary() {
+        if (this.current().kind === "left") {
+            const opening = this.take();
+            const value = this.or();
+            if (this.current().kind !== "right")
+                syntax("missing closing parenthesis", opening.offset);
+            this.take();
+            return value;
+        }
+        return { kind: "predicate", predicate: this.predicate() };
+    }
+    predicate() {
+        const field = this.take();
+        if (field.kind !== "word")
+            syntax("expected query field", field.offset);
+        if ((field.value === "ready" || field.value === "blocked") && this.current().kind !== "operator") {
+            return { field: field.value, operator: "=", value: true };
+        }
+        const operator = this.take();
+        if (operator.kind !== "operator")
+            syntax(`expected operator after ${field.value}`, operator.offset);
+        const value = this.take();
+        if (value.kind !== "word" && value.kind !== "string")
+            syntax(`expected value for ${field.value}`, value.offset);
+        return this.typedPredicate(field, operator, value);
+    }
+    typedPredicate(field, operator, value) {
+        switch (field.value) {
+            case "state": return { field: "state", operator: equalityOperator(operator, "state"), value: state(value) };
+            case "priority": return { field: "priority", operator: orderedOperator(operator, "priority"), value: priority(value) };
+            case "title": return parseTextPredicate("title", operator, value);
+            case "id": return parseTextPredicate("id", operator, value);
+            case "parent": return {
+                field: "parent",
+                operator: equalityOperator(operator, "parent"),
+                value: value.value === "none" ? null : canonicalTaskId(value, "parent"),
+            };
+            case "under": return parseRelationPredicate("under", operator, value);
+            case "needs": return parseRelationPredicate("needs", operator, value);
+            case "blocks": return parseRelationPredicate("blocks", operator, value);
+            case "ready": return parseBooleanPredicate("ready", operator, value);
+            case "blocked": return parseBooleanPredicate("blocked", operator, value);
+            case "created": return parseTimestampPredicate("created", operator, value);
+            case "updated": return parseTimestampPredicate("updated", operator, value);
+            default: return syntax(`unknown query field ${JSON.stringify(field.value)}`, field.offset);
+        }
+    }
+}
+export function parseTaskQueryExpression(source) {
+    if (source.trim().length === 0)
+        return syntax("query expression must be nonblank", 0);
+    return normalizeTaskQuery(new Parser(lex(source)).parse());
+}
+export function validateTaskLimit(source) {
+    if (!/^[1-9][0-9]*$/u.test(source) || Number(source) > MAX_TASK_LIMIT) {
+        throw new Error(`--limit must be an integer from 1 to ${MAX_TASK_LIMIT}`);
+    }
+}
+export function validateTaskParent(source) {
+    try {
+        normalizeTaskQuery({ kind: "predicate", predicate: { field: "under", operator: "=", value: source } });
+    }
+    catch {
+        throw new Error("--parent requires a canonical TaskId");
+    }
+}

package/build/src/cli/commands/task.d.ts

@@ -1,4 +1,5 @@
-export type TaskAction = "add" | "show" | "ls" | "ready" | "blocked" | "tree" | "doctor" | "update" | "start" | "stop" | "hold" | "resume" | "done" | "drop" | "namespace" | "compose";
+import { type TaskQueryExpression } from "./task-query.js";
+export type TaskAction = "add" | "show" | "ls" | "ready" | "blocked" | "tree" | "doctor" | "update" | "query" | "start" | "stop" | "hold" | "resume" | "done" | "drop" | "namespace" | "compose";
 type TaskFlagValue = string | true | readonly string[];
 type TaskStdin = "document" | "body" | "append" | "note" | "compose";
 export type ParsedTaskCommand = Readonly<{
@@ -8,6 +9,7 @@ export type ParsedTaskCommand = Readonly<{
     positionals: readonly string[];
     flags: Readonly<Record<string, TaskFlagValue>>;
     stdin?: TaskStdin;
+    where?: TaskQueryExpression;
 }>;
 export declare function isTaskAction(value: string | undefined): value is TaskAction;
 export declare function renderTaskHelp(action?: TaskAction): string;

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

@@ -1,22 +1,25 @@
-import { CliUsageError, usageLine } from "../usage.js";
+import { CliUsageError, isBlankInput, usageLine } from "../usage.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" },
+        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>]
+  [--note <text>] [--actor <actor>]
   [--needs <TaskId>]... [--parent <TaskId>]
   [--supersedes <TaskId>]... [--relates <TaskId>]...
   [--body <text>] [--json]
-task add [--namespace <ns>] [--json] -`,
+task add [--namespace <ns>] [--actor <actor>] [--json] -`,
         purpose: "Create one Task from flags or a canonical stdin document.",
     },
     show: { arity: [1, 1], flags: COMMON, usage: "task show <TaskId> [--json]", purpose: "Read one Task and its relationships." },
-    ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean" }, usage: "task ls [--closed | --all] [--world] [--json]", purpose: "List Tasks in the selected scope." },
-    ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean" }, usage: "task ready [--world] [--json]", purpose: "List Tasks whose dependencies are satisfied." },
-    blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean" }, usage: "task blocked [--world] [--json]", purpose: "List Tasks blocked by dependencies." },
-    tree: { arity: [1, 1], flags: { ...COMMON, full: "boolean" }, usage: "task tree <TaskId> [--full] [--json]", purpose: "Read one Task dependency tree." },
+    ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" }, usage: "task ls [--closed | --all] [--world] [--limit <n>] [--json]", purpose: "List Tasks in the selected scope." },
+    ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task ready [--world] [--parent <TaskId>] [--limit <n>] [--json]", purpose: "List open Tasks whose every need is terminal." },
+    blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" }, usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>] [--json]", purpose: "List Tasks blocked by dependencies." },
+    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>] [--json]`, purpose: "Query Task facts with a typed boolean expression." },
+    tree: { arity: [1, 1], flags: COMMON, usage: "task tree <TaskId> [--json]", purpose: "Read one Task parent decomposition tree." },
     doctor: { arity: [0, 0], flags: COMMON, usage: "task doctor [--json]", purpose: "Inspect Task authority without repairing it." },
     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" },
@@ -35,7 +38,7 @@ task add [--namespace <ns>] [--json] -`,
     done: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task done <TaskId>... [--note <text>] [--json]", purpose: "Mark one or more Tasks done." },
     drop: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task drop <TaskId>... [--note <text>] [--json]", purpose: "Drop one or more Tasks." },
     namespace: { arity: [0, 1], flags: COMMON, usage: "task namespace [<namespace>] [--json]", purpose: "Read or replace the current Task namespace." },
-    compose: { arity: [0, 0], stdin: "compose", flags: COMMON, usage: "task compose [--json] -", purpose: "Admit independent Task document changes from stdin; partial admission is reported." },
+    compose: { arity: [0, 0], stdin: "compose", flags: { ...COMMON, actor: "value" }, usage: "task compose [--actor <actor>] [--json] -", purpose: "Admit Task documents independently; partial admission has no cross-file atomicity or rollback." },
 };
 export function isTaskAction(value) {
     return value !== undefined && Object.hasOwn(TASK_COMMAND_SPECS, value);
@@ -64,6 +67,8 @@ function setFlag(flags, name, kind, value, fail) {
     }
     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];
@@ -99,6 +104,8 @@ function scanTaskArgv(action, argv, fail) {
             continue;
         }
         if (!token.startsWith("--")) {
+            if (isBlankInput(token))
+                fail(`task ${action} requires a nonblank value`);
             positionals.push(token);
             continue;
         }
@@ -117,18 +124,40 @@ function validateUpdate(scanned, fail) {
     if (Object.keys(flags).every((name) => name === "json"))
         fail("task update requires at least one patch option");
 }
+function validateTaskReadFlags(action, flags, fail) {
+    if (action === "ls" && flags.closed === true && flags.all === true)
+        fail("--closed and --all are mutually exclusive");
+    if (typeof flags.limit === "string") {
+        try {
+            validateTaskLimit(flags.limit);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    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 ((action === "ready" || action === "blocked") && typeof flags.parent === "string") {
+        try {
+            validateTaskParent(flags.parent);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+}
 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 final '-' input");
-    if (action === "add" && stdin === "document" && Object.keys(flags).some((name) => name !== "json" && name !== "namespace"))
+    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 final '-' input");
-    if (action === "ls" && flags.closed === true && flags.all === true)
-        fail("--closed and --all are mutually exclusive");
+    validateTaskReadFlags(action, flags, fail);
     if (action === "update")
         validateUpdate(scanned, fail);
 }
@@ -140,5 +169,14 @@ export function parseTaskCommand(argv) {
     const fail = (message) => { throw new CliUsageError(message, renderTaskUsage(action)); };
     const scanned = scanTaskArgv(action, argv, fail);
     validateTaskScan(action, scanned, fail);
-    return { command: "task", action, output: scanned.flags.json === true ? "json" : "text", ...scanned };
+    let where;
+    if (action === "query" && typeof scanned.flags.where === "string") {
+        try {
+            where = parseTaskQueryExpression(scanned.flags.where);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return { command: "task", action, output: scanned.flags.json === true ? "json" : "text", ...scanned, ...(where === undefined ? {} : { where }) };
 }

package/build/src/cli/coordinates.d.ts

@@ -0,0 +1,18 @@
+import { Repo } from "../index.js";
+import { type WorldRoot } from "../world.js";
+import { type ParsedCommand } from "./parse.js";
+export type CliCoordinates = Readonly<{
+    cwd: string;
+    repo?: Repo;
+    world: WorldRoot | null;
+    candidateWorld: WorldRoot | null;
+    establishWorld: () => Promise<WorldRoot>;
+}>;
+export type CliCoordinateInput = Readonly<{
+    processCwd?: string;
+    cwd?: string;
+    repo?: string;
+    command: ParsedCommand;
+}>;
+export declare function assertExplicitRepoUse(command: ParsedCommand, repo: string | undefined): void;
+export declare function resolveCliCoordinates(input: CliCoordinateInput): Promise<CliCoordinates>;

package/build/src/cli/coordinates.js

@@ -0,0 +1,120 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { NoGitWorldError, Repo } from "../index.js";
+import { World, WorldError } from "../world.js";
+import { CliUsageError } from "./parse.js";
+async function canonicalInvocationCwd(input) {
+    try {
+        return await realpath(input);
+    }
+    catch {
+        throw new CliUsageError(`invocation cwd is not an existing directory: ${input}`);
+    }
+}
+async function discoverRepoAt(coordinate) {
+    try {
+        return { kind: "present", repo: await Repo.at({ path: coordinate }) };
+    }
+    catch (error) {
+        if (error instanceof NoGitWorldError)
+            return { kind: "absent", error };
+        throw error;
+    }
+}
+function repoPolicy(command) {
+    switch (command.command) {
+        case "bind":
+        case "amend":
+        case "deliver":
+        case "review":
+        case "arc":
+        case "abandon":
+        case "audit":
+        case "reconcile":
+        case "show":
+        case "region":
+            return { use: "required", acceptsExplicit: true };
+        case "ls":
+            return { use: command.query.kind === "contracts" ? "required" : "none", acceptsExplicit: false };
+        case "status":
+        case "tell":
+        case "history":
+            return { use: "optional", acceptsExplicit: false };
+        case "fork":
+            return { use: "optional", acceptsExplicit: true };
+        case "wait":
+        case "kill": {
+            const contractSelector = command.akuma.some((selector) => selector.startsWith("kei/"));
+            return { use: contractSelector ? "required" : "optional", acceptsExplicit: contractSelector };
+        }
+        case "call":
+            return {
+                use: command.contract === undefined ? "none" : "required",
+                acceptsExplicit: command.contract !== undefined,
+            };
+        case "settings":
+        case "task":
+        case "install":
+            return { use: "none", acceptsExplicit: false };
+    }
+}
+function refuseUnusedRepo(command) {
+    if (command.command === "call")
+        throw new CliUsageError("--repo has no consumer without --contract");
+    throw new CliUsageError(`--repo has no consumer for ${command.command}`);
+}
+export function assertExplicitRepoUse(command, repo) {
+    if (repo !== undefined && !repoPolicy(command).acceptsExplicit)
+        refuseUnusedRepo(command);
+}
+function repoFor(use, discovery) {
+    if (use === "none")
+        return undefined;
+    if (discovery.kind === "present")
+        return discovery.repo;
+    if (use === "required")
+        throw discovery.error;
+    return undefined;
+}
+async function resolveWorld(cwd, repo) {
+    try {
+        const resolution = await World.resolve({ cwd, ...(repo === undefined ? {} : { repositoryRoot: repo.root }) });
+        return {
+            root: resolution.root,
+            candidate: resolution.candidate,
+            async establish() {
+                try {
+                    return await resolution.establish();
+                }
+                catch (error) {
+                    if (error instanceof WorldError)
+                        throw new CliUsageError(error.message);
+                    throw error;
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof WorldError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+}
+export async function resolveCliCoordinates(input) {
+    const processCwd = resolve(input.processCwd ?? ".");
+    const cwd = await canonicalInvocationCwd(resolve(processCwd, input.cwd ?? "."));
+    const invocationRepo = await discoverRepoAt(cwd);
+    const selectedRepo = input.repo === undefined
+        ? invocationRepo
+        : await discoverRepoAt(resolve(cwd, input.repo));
+    const worldRepo = invocationRepo.kind === "present" ? invocationRepo.repo : undefined;
+    const repo = repoFor(repoPolicy(input.command).use, selectedRepo);
+    const world = await resolveWorld(cwd, worldRepo);
+    return {
+        cwd,
+        ...(repo === undefined ? {} : { repo }),
+        world: world.root,
+        candidateWorld: world.candidate,
+        establishWorld: world.establish,
+    };
+}