@astrosheep/keiyaku 4.5.7 → 4.5.9

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

@@ -1,4 +1,5 @@
 import { archetypeName } from "../../akuma/identity.js";
+import { parseTaskNamespaceSelector } from "../../task/catalog.js";
 import { CliUsageError, usageLine } from "../usage.js";
 function parseAkumaCatalogPath(value) {
     if (value === "aku" || value === "aku/")
@@ -23,21 +24,21 @@ export const CONTRACT_COMMAND_SPECS = {
             "fork-of": "value",
             json: "boolean",
         },
-        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
+        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>] [--json]",
         purpose: "Create one Contract from stdin Markdown or a sibling fork.",
     },
     amend: {
         positional: "optional",
         stdin: "optional",
         flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
-        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
+        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]",
         purpose: "Amend one Contract's document operations or structured terms.",
         details: [
+            "  ## Context|Objective|Design|Region|Criteria|Verification|<extension>  (replace, or add new extension)",
             "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
             "  ## Append: Context|Objective|Design|Criteria|<extension>",
             "  ## Add: Criteria|<new-extension-title>",
             "  ## Update: <existing-extension-title>",
-            "  ## Remove: Criterion <existing-title>",
             "  ## Remove: <existing-extension-title>",
         ].join("\n"),
     },
@@ -45,77 +46,76 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "optional",
         stdin: "none",
         flags: {
-            actor: "value",
             message: "value",
             "include-dirty": "boolean",
             "materialize-conflict": "boolean",
             json: "boolean",
         },
-        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--actor <actor>]",
+        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--json]",
         purpose: "Deliver one Contract candidate from the appointed worktree.",
         details: [
             "  --include-dirty         Capture the complete non-ignored worktree tree as the",
-            "                          candidate; stages nothing, commits nothing. Refused",
-            "                          while unmerged paths exist.",
+            "                          candidate; stages nothing, commits nothing, including",
+            "                          an unmerged shared index.",
             "  --materialize-conflict  After a conflict result, project the judged targetHead",
             "                          into the worktree as an uncommitted merge. Not a",
-            "                          delivery: resolve, stage, deliver again.",
+            "                          delivery: resolve, then deliver with --include-dirty.",
         ].join("\n"),
     },
     review: {
         positional: "optional",
         stdin: "optional",
-        flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
-        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]",
+        flags: { satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
+        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--json]",
         purpose: "Record one review verdict.",
     },
     arc: {
         positional: "optional",
         stdin: "required",
         flags: { actor: "value", json: "boolean" },
-        usage: "arc [<contract>|@<contract>] [--actor <actor>] -",
+        usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -",
         purpose: "Record stdin arc Markdown for one Contract.",
     },
     abandon: {
         positional: "optional",
         stdin: "none",
         flags: { actor: "value", note: "value", json: "boolean" },
-        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]",
+        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]",
         purpose: "Abandon one Contract with an optional note.",
     },
     status: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "status [<contract>|@name|<aku/...>]...",
+        usage: "status [<contract>|@name|<aku/...>]... [--json]",
         purpose: "Read the world status board or one or more Contract and Akuma projections.",
     },
     show: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "show [<contract>|@<contract>]",
+        usage: "show [<contract>|@<contract>] [--json]",
         purpose: "Read one Contract guidance projection.",
     },
     ls: {
         positional: "optional",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: 'ls task[/]\n       keiyaku ls kei[/]\n       keiyaku ls aku[/]\n       keiyaku ls aku/<akuma>[/]\n       keiyaku ls "aku/*/*"',
+        usage: 'ls task[/] [--json]\nls kei[/] [--json]\nls aku[/] [--json]\nls aku/<akuma>[/] [--json]\nls "aku/*/*" [--json]',
         purpose: "List one identity directory.",
     },
     audit: {
         positional: "optional",
         stdin: "none",
-        flags: { "include-dirty": "boolean", diff: "boolean", actor: "value", json: "boolean" },
-        usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--actor <actor>]",
+        flags: { "include-dirty": "boolean", diff: "boolean", json: "boolean" },
+        usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--json]",
         purpose: "Ask what candidate preparation, Verification, and target placement would do.",
     },
     reconcile: {
         positional: "optional",
         stdin: "none",
         flags: { "retry-hooks": "boolean", json: "boolean" },
-        usage: "reconcile [<contract>|@<contract>] [--retry-hooks]",
+        usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]",
         purpose: "Reconcile one Contract or the invocation world.",
     },
     nuke: {
@@ -129,14 +129,14 @@ export const CONTRACT_COMMAND_SPECS = {
         positional: "none",
         stdin: "none",
         flags: { json: "boolean" },
-        usage: "settings",
-        purpose: "Read user and project Settings resources.",
+        usage: "settings [--json]",
+        purpose: "Show effective Settings (user + project, read-only)",
     },
     region: {
         positional: "optional",
         stdin: "none",
         flags: { path: "repeat-value", json: "boolean" },
-        usage: "region [<contract>]\n       region --path <pattern> [--path <pattern> ...]",
+        usage: "region [<contract>] [--json]\nregion --path <pattern> [--path <pattern> ...] [--json]",
         purpose: "Read active declared Contract Regions.",
     },
 };
@@ -217,7 +217,6 @@ function parseDeliver(parts) {
     return {
         command: "deliver",
         ...(contract === undefined ? {} : { contract }),
-        ...(parts.actor === undefined ? {} : { actor: parts.actor }),
         ...(message === undefined ? {} : { message }),
         includeDirty: parts.flags["include-dirty"] === true,
         materializeConflict: parts.flags["materialize-conflict"] === true,
@@ -239,7 +238,6 @@ function parseReview(parts) {
         verdict: parts.flags.satisfied === true ? "satisfied" : "unsatisfied",
         ...(summary === undefined ? {} : { summary }),
         ...(parts.stdin ? { summaryFromStdin: true } : {}),
-        ...(parts.actor === undefined ? {} : { actor: parts.actor }),
         output: parts.output,
     };
 }
@@ -269,7 +267,21 @@ function parseRegion(parts) {
 function parseLs(parts) {
     const path = parts.positionals[0];
     if (path === "task" || path === "task/")
-        return { command: "ls", query: { kind: "tasks" }, output: parts.output };
+        return { command: "ls", query: { kind: "tasks", namespace: [] }, output: parts.output };
+    if (path.startsWith("task/")) {
+        if (!path.endsWith("/"))
+            refuse("ls", `invalid Task namespace selector: ${path}`);
+        const body = path.slice("task/".length, -1);
+        if (body.length === 0 || body.split("/").some((segment) => segment.length === 0))
+            refuse("ls", `invalid Task namespace selector: ${path}`);
+        try {
+            const namespace = parseTaskNamespaceSelector(path);
+            return { command: "ls", query: { kind: "tasks", namespace }, output: parts.output };
+        }
+        catch (error) {
+            refuse("ls", error instanceof Error ? error.message : `invalid Task namespace selector: ${path}`);
+        }
+    }
     if (path === "kei" || path === "kei/")
         return { command: "ls", query: { kind: "contracts" }, output: parts.output };
     try {
@@ -286,6 +298,28 @@ function parseLs(parts) {
 }
 export function renderContractHelp(command) {
     const spec = CONTRACT_COMMAND_SPECS[command];
+    if (command === "settings") {
+        return [
+            "Show effective Settings — the merged read-only view of:",
+            "  user      ~/.keiyaku/settings.json",
+            "  project   <WorldRoot>/.keiyaku/settings.json",
+            "A project record wholly shadows the same-name user record.",
+            "",
+            "Shape: namespace -> entry -> JSON value. There is no write",
+            "command; edit the files directly.",
+            "",
+            "Recognized settings:",
+            "  gates                            gate bundles selected by bind and amend",
+            "  worktree                         commands run when worktrees are created or destroyed",
+            "  git.requireBranchesToBeUpToDate  whether deliver and audit require up-to-date target branches",
+            "  providers                        the available Akuma and how each is run",
+            "",
+            "Each entry is validated by the feature that reads it. A rejected",
+            "value's diagnostic states the expected shape.",
+            "",
+            usageLine(spec.usage),
+        ].join("\n");
+    }
     const help = `${spec.purpose}\n\n${usageLine(spec.usage)}`;
     return spec.details === undefined ? help : `${help}\n\n${spec.details}`;
 }
@@ -337,7 +371,6 @@ export function parseContractCommand(parts) {
                 ...(contract === undefined ? {} : { contract }),
                 includeDirty: parts.flags["include-dirty"] === true,
                 showDiff: parts.flags.diff === true,
-                ...(parts.actor === undefined ? {} : { actor: parts.actor }),
                 output: parts.output,
             };
         }

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

@@ -16,7 +16,8 @@ export type InstallInvocationResult = Readonly<{
     results: readonly HarnessInstallResult[];
 }>;
 export type InstallRunner = (input: ProcessInput) => Promise<ProcessOutcome>;
-export declare const INSTALL_USAGE = "install <codex|claude|opencode|pi>\n       install --all";
+export declare const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\ninstall --all [--json]";
+export declare const INSTALL_ROOT_PURPOSE = "Install Keiyaku into coding harnesses";
 export declare function parseInstallCommand(argv: readonly string[]): ParsedInstallCommand;
 export declare function renderInstallHelp(): string;
 export declare function installAssetsRoot(): string;

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

@@ -2,7 +2,8 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CliUsageError, usageLine } from "../usage.js";
 export const HARNESS_NAMES = ["codex", "claude", "opencode", "pi"];
-export const INSTALL_USAGE = "install <codex|claude|opencode|pi>\n       install --all";
+export const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\ninstall --all [--json]";
+export const INSTALL_ROOT_PURPOSE = "Install Keiyaku into coding harnesses";
 function isHarness(value) {
     return value !== undefined && HARNESS_NAMES.includes(value);
 }
@@ -42,7 +43,7 @@ export function parseInstallCommand(argv) {
     };
 }
 export function renderInstallHelp() {
-    return `Install the Keiyaku skills into one or more agent harnesses.\n\n${usageLine(INSTALL_USAGE)}`;
+    return `Install Keiyaku into your coding harnesses via each harness's native plugin/package installer. --all continues past failures; any failure exits 1.\n\n${usageLine(INSTALL_USAGE)}`;
 }
 const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
 const ASSET_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../integrations/marketplace");

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

@@ -1,6 +1,7 @@
 import { type BlockedTaskList, type TaskBatchResult, type TaskCompositionResult, type TaskDecompositionTree, type TaskDetail, type TaskDoctorReport, type TaskList, type TaskMutationResult, type TaskContextResult, type TaskQueryResult, type TaskUpdateResult } from "../../task/index.js";
 import type { ParsedTaskCommand } from "./task.js";
 import type { WorldRoot } from "../../world.js";
+import { type ExecutionContext } from "../../akuma/requests.js";
 export type TaskShowResult = TaskDetail | readonly TaskDetail[] | Extract<TaskMutationResult, {
     kind: "refused";
 }>;
@@ -29,6 +30,7 @@ type TaskInput = Readonly<{
     establish(): Promise<WorldRoot>;
     readStdin(): Promise<string>;
     actor?: string;
+    execution: ExecutionContext;
 }>;
 export declare function invokeTaskFromEdge(input: Readonly<{
     parsed: ParsedTaskCommand;
@@ -41,6 +43,7 @@ export declare function invokeTaskFromEdge(input: Readonly<{
     establish: () => Promise<WorldRoot>;
     readStdin: () => Promise<string>;
     actor: string | undefined;
+    execution?: ExecutionContext;
 }>): Promise<TaskInvocationResult>;
 export declare function invokeTask(command: ParsedTaskCommand, input: TaskInput): Promise<TaskInvocationResult>;
 export {};

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

@@ -2,8 +2,8 @@
 import { Tasks, } from "../../task/index.js";
 import { taskCompositionNamespaceHeader } from "../../task/compose-language.js";
 import { observeTaskDetails } from "../../task/operations.js";
-import { injectedBodyRequests, requestBodyTask } from "../../akuma/requests.js";
-import { decodeTaskMutationRequest } from "../../task/mutation.js";
+import { parseTaskNamespaceSelector } from "../../task/catalog.js";
+import { localExecutionContext } from "../../akuma/requests.js";
 import { resolveTaskNamespaceContext, writeTaskNamespaceContext } from "../../task/context.js";
 import { CliUsageError } from "../usage.js";
 export async function invokeTaskFromEdge(input) {
@@ -15,6 +15,7 @@ export async function invokeTaskFromEdge(input) {
             establish: input.establish,
             readStdin: input.readStdin,
             ...(input.actor === undefined ? {} : { actor: input.actor }),
+            execution: input.execution ?? localExecutionContext(),
         });
     }
     catch (error) {
@@ -50,6 +51,11 @@ function limit(command) {
     const raw = value(command, "limit");
     return raw === undefined ? undefined : Number(raw);
 }
+function explicitListNamespace(command) {
+    return command.action === "ls" && command.positionals.length === 1
+        ? parseTaskNamespaceSelector(command.positionals[0])
+        : undefined;
+}
 async function invokeAdd(tasks, command, input, current) {
     const selectedNamespace = namespace(value(command, "namespace")) ?? current;
     const actor = input.actor;
@@ -104,127 +110,6 @@ async function invokeUpdate(tasks, command, readStdin) {
         ...(dropRelates === undefined ? {} : { dropRelates }),
     });
 }
-async function addMutationRequest(command, input, current) {
-    const selectedNamespace = namespace(value(command, "namespace")) ?? current;
-    if (command.stdin === "document")
-        return {
-            action: "task.addDocument",
-            input: {
-                markdown: await input.readStdin(),
-                namespace: selectedNamespace,
-            },
-        };
-    const body = value(command, "body"), note = value(command, "note");
-    const 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"));
-    return {
-        action: "task.add",
-        input: {
-            title: command.positionals[0],
-            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 }),
-        },
-    };
-}
-async function updateMutationRequest(command, input) {
-    const body = command.stdin === "body" ? await input.readStdin() : value(command, "body");
-    const appendBody = command.stdin === "append" ? await input.readStdin() : value(command, "append");
-    const note = command.stdin === "note" ? await input.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"));
-    const dropSupersedes = ids(values(command, "drop-supersedes")), addRelates = ids(values(command, "relates"));
-    const dropRelates = ids(values(command, "drop-relates"));
-    return {
-        action: "task.update",
-        id: command.positionals[0],
-        input: {
-            ...(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 lifecycleMutationRequest(command) {
-    const id = command.positionals[0];
-    switch (command.action) {
-        case "start":
-            return { action: "task.start", id };
-        case "stop":
-            return { action: "task.stop", id };
-        case "resume":
-            return { action: "task.resume", id };
-        case "hold":
-            return { action: "task.hold", ids: command.positionals };
-        case "done":
-            return {
-                action: "task.done",
-                ids: command.positionals,
-                ...(value(command, "note") === undefined ? {} : { note: value(command, "note") }),
-            };
-        case "drop":
-            return {
-                action: "task.drop",
-                ids: command.positionals,
-                ...(value(command, "note") === undefined ? {} : { note: value(command, "note") }),
-            };
-        default:
-            throw new Error(`task action cannot forward: ${command.action}`);
-    }
-}
-async function mutationRequest(command, input, current, composeMarkdown) {
-    if (command.action === "add")
-        return await addMutationRequest(command, input, current);
-    if (command.action === "compose")
-        return { action: "task.compose", markdown: composeMarkdown ?? (await input.readStdin()), namespace: current };
-    if (command.action === "update")
-        return await updateMutationRequest(command, input);
-    return lifecycleMutationRequest(command);
-}
-function validatedMutationRequest(request) {
-    switch (request.action) {
-        case "task.add":
-        case "task.addDocument":
-            return decodeTaskMutationRequest(request.action, { input: request.input });
-        case "task.compose":
-            return decodeTaskMutationRequest(request.action, { markdown: request.markdown, namespace: request.namespace });
-        case "task.update":
-            return decodeTaskMutationRequest(request.action, { id: request.id, input: request.input });
-        case "task.start":
-        case "task.stop":
-        case "task.resume":
-            return decodeTaskMutationRequest(request.action, { id: request.id });
-        case "task.hold":
-            return decodeTaskMutationRequest(request.action, { ids: request.ids });
-        case "task.done":
-        case "task.drop":
-            return decodeTaskMutationRequest(request.action, {
-                ids: request.ids,
-                ...(request.note === undefined ? {} : { note: request.note }),
-            });
-    }
-}
 function readScope(command, current) {
     return command.flags.world === true ? { scope: "world" } : { namespace: current ?? [] };
 }
@@ -241,7 +126,9 @@ async function invokeRead(tasks, command, current) {
         case "ls":
             return tasks.list({
                 selection: command.flags.all === true ? "all" : command.flags.closed === true ? "closed" : "active",
-                ...readScope(command, current),
+                ...(explicitListNamespace(command) === undefined
+                    ? readScope(command, current)
+                    : { namespace: explicitListNamespace(command) }),
                 ...(limit(command) === undefined ? {} : { limit: limit(command) }),
             });
         case "ready":
@@ -300,7 +187,12 @@ function missingWorld(command) {
         return { kind: "absent" };
     if (command.action === "context")
         return { kind: "accepted", value: { namespace: [], source: "default-root" } };
-    if (command.action === "hold" || command.action === "done" || command.action === "drop") {
+    if (command.action === "start" && command.positionals.length === 1)
+        return missing(command.positionals[0]);
+    if (command.action === "start" ||
+        command.action === "hold" ||
+        command.action === "done" ||
+        command.action === "drop") {
         return { items: command.positionals.map((id) => ({ id: id, outcome: missing(id) })) };
     }
     return missing(command.positionals[0]);
@@ -318,7 +210,7 @@ async function invokeLocalMutation(input) {
     const id = command.positionals[0];
     switch (command.action) {
         case "start":
-            return tasks.task({ id }).start();
+            return invokeStart(tasks, command.positionals, id);
         case "stop":
             return tasks.task({ id }).stop();
         case "resume":
@@ -355,18 +247,14 @@ async function invokeLocalMutation(input) {
             throw new Error(`task action has no invocation: ${command.action}`);
     }
 }
+function invokeStart(tasks, ids, firstId) {
+    return ids.length === 1 ? tasks.task({ id: firstId }).start() : tasks.batch({ verb: "start", ids });
+}
 function establishesWorld(command) {
     return (command.action === "add" ||
         (command.action === "compose" && command.flags.plan !== true) ||
         (command.action === "context" && command.positionals.length > 0));
 }
-function forwardsMutation(command) {
-    return (command.action !== "show" &&
-        command.action !== "tree" &&
-        command.action !== "context" &&
-        !(command.action === "compose" && command.flags.plan === true) &&
-        !isWorldObservation(command));
-}
 // eslint-disable-next-line complexity -- this is the single CLI edge ordering world, context, forwarding, and local execution.
 export async function invokeTask(command, input) {
     const planOnly = command.action === "compose" && command.flags.plan === true;
@@ -380,11 +268,11 @@ export async function invokeTask(command, input) {
     const world = input.world ?? (planOnly ? input.candidate : establishesWorld(command) ? await input.establish() : null);
     if (world === null)
         return missingWorld(command);
-    const tasks = Tasks.of(world);
+    const tasks = Tasks.of(world, { execution: input.execution });
     const contextSensitive = command.action === "context" ||
         (command.action === "add" && explicitNamespace === undefined) ||
         (command.action === "compose" && composition?.specified !== true) ||
-        ((command.action === "ls" ||
+        (((command.action === "ls" && explicitListNamespace(command) === undefined) ||
             command.action === "ready" ||
             command.action === "blocked" ||
             command.action === "query") &&
@@ -399,11 +287,6 @@ export async function invokeTask(command, input) {
             return { kind: "accepted", value: resolved };
         }
     }
-    const requests = injectedBodyRequests();
-    if (requests !== null && forwardsMutation(command)) {
-        const request = validatedMutationRequest(await mutationRequest(command, input, explicitNamespace ?? current ?? [], composeMarkdown));
-        return (await requestBodyTask({ directory: requests, world, request }));
-    }
     return await invokeLocalMutation({
         tasks,
         command,