@astrosheep/keiyaku 4.5.19 → 4.5.21

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

@@ -1,5 +1,15 @@
 import { resolveActor } from "../actor.js";
 import { CliUsageError } from "../usage.js";
+async function consumeExecution(execution, edge) {
+    const observation = edge.progress === undefined ? undefined : Promise.resolve().then(() => edge.progress(execution.progress));
+    void observation?.catch(() => undefined);
+    try {
+        return await execution.result;
+    }
+    finally {
+        await observation?.catch(() => undefined);
+    }
+}
 function actorFromEdge(actor, environment) {
     try {
         return resolveActor({ env: environment, ...(actor === undefined ? {} : { actor }) });
@@ -141,15 +151,16 @@ async function existingSeat(input, parsed, library) {
     const actor = "actor" in parsed ? actorFromEdge(parsed.actor, edge.environment) : undefined;
     return { contract, id, ...(actor === undefined ? {} : { actor }), ...(hooks === undefined ? {} : { hooks }) };
 }
-async function invokeDeliver(parsed, seat) {
+async function invokeDeliver(parsed, seat, edge) {
     const { acceptedDeliver } = await import("../accepted.js");
     try {
-        const delivered = await seat.contract.deliver({
+        const delivered = await consumeExecution(seat.contract.startDelivery({
             ...(parsed.message === undefined ? {} : { message: parsed.message }),
             includeDirty: parsed.includeDirty,
             materializeConflict: parsed.materializeConflict,
             overwrite: parsed.overwrite,
-        });
+            ...(edge.signal === undefined ? {} : { signal: edge.signal }),
+        }), edge);
         if (!("facts" in delivered))
             return delivered;
         return acceptedDeliver(delivered, seat.id);
@@ -166,13 +177,15 @@ async function invokeDeliver(parsed, seat) {
         throw error;
     }
 }
-async function invokeReview(parsed, seat, readStdin) {
-    const summary = parsed.summaryFromStdin === true ? await readStdin() : parsed.summary;
+async function invokeReview(parsed, seat, edge) {
+    const summary = parsed.summaryFromStdin === true ? await edge.readStdin() : parsed.summary;
     const { acceptedReview, resultFromMutationCall } = await import("../accepted.js");
-    return resultFromMutationCall("review", () => seat.contract.review({
+    const input = {
         verdict: parsed.verdict,
         ...(summary === undefined ? {} : { summary }),
-    }), (result) => acceptedReview(result, seat.id), { coordinate: seat.id });
+        ...(edge.signal === undefined ? {} : { signal: edge.signal }),
+    };
+    return resultFromMutationCall("review", () => consumeExecution(seat.contract.startReview(input), edge), (result) => acceptedReview(result, seat.id), { coordinate: seat.id });
 }
 async function contractLibrary(input, parsed) {
     const { configuration, edge, hooks } = input;
@@ -214,9 +227,9 @@ export async function invokeContractMutation(input) {
             }), (result) => acceptedAmend(result, id), { coordinate: id });
         }
         case "deliver":
-            return invokeDeliver(parsed, seat);
+            return invokeDeliver(parsed, seat, edge);
         case "review":
-            return invokeReview(parsed, seat, edge.readStdin);
+            return invokeReview(parsed, seat, edge);
         case "arc": {
             const markdown = await edge.readStdin();
             const { acceptedArc, resultFromMutationCall } = await import("../accepted.js");
@@ -236,10 +249,11 @@ export async function invokeContractMutation(input) {
         }
         case "audit": {
             const { acceptedAudit, resultFromMutationCall } = await import("../accepted.js");
-            return resultFromMutationCall("audit", () => contract.audit({
+            return resultFromMutationCall("audit", () => consumeExecution(contract.startAudit({
                 includeDirty: parsed.includeDirty,
                 showDiff: parsed.showDiff,
-            }), (result) => acceptedAudit(result, id), { coordinate: id });
+                ...(edge.signal === undefined ? {} : { signal: edge.signal }),
+            }), edge), (result) => acceptedAudit(result, id), { coordinate: id });
         }
     }
 }

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

@@ -20,13 +20,15 @@ function optionalFlag(flags, name) {
 function refuse(command, message) {
     throw new CliUsageError(message, commandGuide(command, CONTRACT_COMMAND_SPECS[command].usage));
 }
-function parseGateBundleNames(parts, command) {
+function parseGateNames(parts, command) {
     const value = optionalFlag(parts.flags, "gates");
     if (value === undefined)
         return undefined;
+    if (value === "")
+        return [];
     const names = value.split(",");
     if (names.some((name) => name.length === 0)) {
-        refuse(command, "--gates requires nonempty comma-separated names");
+        refuse(command, '--gates requires comma-separated names or "" to clear gates');
     }
     return names;
 }
@@ -53,7 +55,7 @@ function parseBind(parts) {
     const task = optionalFlag(parts.flags, "task");
     const target = optionalFlag(parts.flags, "target");
     const after = parts.flags.after === undefined ? [] : Array.isArray(parts.flags.after) ? parts.flags.after : [parts.flags.after];
-    const gates = parseGateBundleNames(parts, "bind");
+    const gates = parseGateNames(parts, "bind");
     return {
         command: "bind",
         ...(task === undefined ? {} : { task }),
@@ -69,7 +71,7 @@ function parseAmend(parts) {
     const after = parts.flags.after === undefined ? [] : Array.isArray(parts.flags.after) ? parts.flags.after : [parts.flags.after];
     if (parts.flags["clear-after"] === true && after.length > 0)
         refuse("amend", "--clear-after and --after are mutually exclusive");
-    const gates = parseGateBundleNames(parts, "amend");
+    const gates = parseGateNames(parts, "amend");
     if (!parts.stdin && parts.flags.after === undefined && parts.flags["clear-after"] !== true && gates === undefined) {
         refuse("amend", "amend requires stdin or --after, --clear-after, or --gates");
     }

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

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

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

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CliUsageError, commandGuide, usageLine } from "../usage.js";
 export const HARNESS_NAMES = ["codex", "claude", "opencode", "pi"];
-export const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\ninstall --all [--json]";
+export const INSTALL_USAGE = "install <codex|claude|opencode|pi>\ninstall --all";
 export const INSTALL_ROOT_PURPOSE = "Install Keiyaku into coding harnesses";
 function isHarness(value) {
     return value !== undefined && HARNESS_NAMES.includes(value);

package/build/src/cli/commands/status-set.js

@@ -13,33 +13,25 @@ async function statusSetAkuma(selector, id, alias, world, repo) {
         ...(result.alias === undefined ? {} : { alias: result.alias }),
     };
 }
-async function statusSetEntry(selector, world, repo, observed) {
-    let resolved = selector;
-    let alias;
+async function statusSetContract(selector, id, world, repo) {
+    if (repo === undefined)
+        throw new CliUsageError("cannot select a contract while the Contract world is absent");
+    const observation = await (await import("../../kanshi/index.js")).observeKanshi({ world, repo, contract: canonicalContractSelector(id) });
+    return { selector, kind: "contract", report: observation.report };
+}
+async function statusSetEntry(selector, world, repo, named) {
     if (selector.startsWith("@")) {
-        if (observed === undefined)
+        if (named === undefined)
             throw new CliUsageError("cannot resolve a named status selector");
         const { resolveNamedAddress } = await import("../../library/address.js");
-        const address = resolveNamedAddress({ selector, report: observed.report, aliases: observed.aliases });
+        const address = resolveNamedAddress({ selector, report: named.report, aliases: named.aliases });
         if (address.kind === "akuma")
             return await statusSetAkuma(selector, address.id, selector, world, repo);
-        resolved = address.id;
-        alias = selector;
+        return await statusSetContract(selector, address.id, world, repo);
     }
-    if (resolved.startsWith("aku/"))
-        return await statusSetAkuma(selector, resolved, alias, world, repo);
-    if (repo === undefined)
-        throw new CliUsageError("cannot select a contract while the Contract world is absent");
-    if (observed === undefined)
-        throw new CliUsageError("cannot observe Contract status without a Kanshi report");
-    return {
-        selector,
-        kind: "contract",
-        report: (await import("../../kanshi/index.js")).selectKanshi({
-            report: observed.report,
-            contract: canonicalContractSelector(resolved),
-        }),
-    };
+    if (selector.startsWith("aku/"))
+        return await statusSetAkuma(selector, selector, undefined, world, repo);
+    return await statusSetContract(selector, selector, world, repo);
 }
 export async function invokeStatusSet(selectors, world, repo) {
     if (selectors.length < 2)
@@ -47,8 +39,7 @@ export async function invokeStatusSet(selectors, world, repo) {
     if (selectors.some((selector) => !selector.startsWith("aku/") && !selector.startsWith("@")) && repo === undefined) {
         throw new CliUsageError("cannot select a contract while the Contract world is absent");
     }
-    const needsKanshi = selectors.some((selector) => !selector.startsWith("aku/"));
-    const observed = needsKanshi
+    const named = selectors.some((selector) => selector.startsWith("@"))
         ? await (await import("../../kanshi/index.js")).observeKanshi({
             world,
             ...(repo === undefined ? {} : { repo }),
@@ -56,6 +47,6 @@ export async function invokeStatusSet(selectors, world, repo) {
         : undefined;
     const entries = [];
     for (const selector of selectors)
-        entries.push(await statusSetEntry(selector, world, repo, observed));
+        entries.push(await statusSetEntry(selector, world, repo, named));
     return { kind: "status-set", entries };
 }

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

@@ -19,39 +19,39 @@ const TASK_COMMAND_SPECS = {
             note: "value",
             actor: "value",
         },
-        usage: `task add <TITLE> [--namespace <ns>] [--priority 0..3] [--json]
+        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>] [--json] -`,
+task add [--namespace <ns>] [--actor <actor>] -`,
         purpose: "Create one Task from flags or a canonical stdin document.",
     },
     show: {
         arity: [1, Number.POSITIVE_INFINITY],
         flags: COMMON,
-        usage: "task show <TaskId>... [--json]",
+        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>] [--json]",
+        usage: "task ls [<namespace-selector>] [--closed | --all] [--world] [--limit <n>]",
         purpose: "List Tasks in the selected scope.",
         details: "--world lists every namespace in the current Task world.",
     },
     ready: {
         arity: [0, 0],
         flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" },
-        usage: "task ready [--world] [--parent <TaskId>] [--limit <n>] [--json]",
+        usage: "task ready [--world] [--parent <TaskId>] [--limit <n>]",
         purpose: "List open Tasks whose every need is terminal.",
         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>] [--json]",
+        usage: "task blocked [--world] [--parent <TaskId>] [--limit <n>]",
         purpose: "List Tasks blocked by dependencies.",
         details: "--world lists every namespace in the current Task world.",
     },
@@ -59,7 +59,7 @@ task add [--namespace <ns>] [--actor <actor>] [--json] -`,
         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]`,
+  [--sort priority|created|updated|id] [--limit <n>]`,
         purpose: "Query Task facts with a typed boolean expression.",
         details: [
             "fields: state priority title id parent under needs blocks ready blocked created updated",
@@ -73,13 +73,13 @@ task add [--namespace <ns>] [--actor <actor>] [--json] -`,
     tree: {
         arity: [1, 1],
         flags: COMMON,
-        usage: "task tree <TaskId> [--json]",
+        usage: "task tree <TaskId>",
         purpose: "Read one Task parent decomposition tree.",
     },
     doctor: {
         arity: [0, 0],
         flags: COMMON,
-        usage: "task doctor [--json]",
+        usage: "task doctor",
         purpose: "Inspect Task authority without repairing it.",
     },
     update: {
@@ -105,56 +105,56 @@ task add [--namespace <ns>] [--actor <actor>] [--json] -`,
   [--priority 0..3] [--needs <TaskId>]... [--drop-needs <TaskId>]...
   [--parent <TaskId> | --no-parent]
   [--supersedes <TaskId>]... [--drop-supersedes <TaskId>]...
-  [--relates <TaskId>]... [--drop-relates <TaskId>]... [--json]`,
+  [--relates <TaskId>]... [--drop-relates <TaskId>]...`,
         purpose: "Apply one or more patches to a Task.",
     },
     start: {
         arity: [1, Number.POSITIVE_INFINITY],
         flags: COMMON,
-        usage: "task start <TaskId>... [--json]",
+        usage: "task start <TaskId>...",
         purpose: "Move one or more open Tasks into progress.",
     },
     stop: {
         arity: [1, 1],
         flags: COMMON,
-        usage: "task stop <TaskId> [--json]",
+        usage: "task stop <TaskId>",
         purpose: "Return one in-progress Task to open.",
     },
     hold: {
         arity: [1, Number.POSITIVE_INFINITY],
         flags: COMMON,
-        usage: "task hold <TaskId>... [--json]",
+        usage: "task hold <TaskId>...",
         purpose: "Put one or more Tasks on hold.",
     },
     resume: {
         arity: [1, 1],
         flags: COMMON,
-        usage: "task resume <TaskId> [--json]",
+        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>] [--json]",
+        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>] [--json]",
+        usage: "task drop <TaskId>... [--note <text>]",
         purpose: "Drop one or more Tasks.",
     },
     context: {
         arity: [0, 1],
         flags: COMMON,
-        usage: "task context [<namespace>] [--json]",
+        usage: "task context [<namespace>]",
         purpose: "Read or replace the directory Task context.",
     },
     compose: {
         arity: [0, 0],
         stdin: "compose",
         flags: { ...COMMON, actor: "value", plan: "boolean" },
-        usage: "task compose [--actor <actor>] [--plan] [--json] -",
+        usage: "task compose [--actor <actor>] [--plan] -",
         purpose: "Plan or admit one explicit Task composition.",
         details: [
             "nodes: + <Title> creates; @task/<id> modifies a pre-existing Task",

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

@@ -1,3 +1,4 @@
+import type { ExecutionEvent } from "../library/execution.js";
 import type { AkumaInvocationResult } from "./commands/akuma-invoke.js";
 import type { InstallInvocationResult } from "./commands/install.js";
 import type { TaskInvocationResult } from "./commands/task-invoke.js";
@@ -11,6 +12,8 @@ type InvokeRuntime = Readonly<{
     environment?: NodeJS.ProcessEnv;
     readStdin?: () => Promise<string>;
     actor?: ActorId;
+    signal?: AbortSignal;
+    progress?: (events: AsyncIterable<ExecutionEvent>) => Promise<void>;
 }>;
 export type SettingsInvocationResult = Readonly<{
     kind: "settings";

package/build/src/cli/invoke.js

@@ -1,9 +1,11 @@
+import { resolve } from "node:path";
 import { resolveActor } from "./actor.js";
 import { isParsedAkumaCommand } from "./commands/akuma.js";
 import { invokeContractMutation } from "./commands/contract-invoke.js";
 import { assertExplicitRepoUse, CliUsageError, usageGuideForCommand, } from "./parse.js";
 import { isBlankInput } from "./usage.js";
 import { AKUMA_REQUESTS_ENV } from "../akuma/provider.js";
+import { canonicalBirthCwd } from "../akuma/call-input.js";
 import { bodyRequestExecution, executionChannel, localExecutionContext, } from "../akuma/requests.js";
 async function readStdin() {
     const chunks = [];
@@ -118,7 +120,7 @@ async function selectContract(repo, selector, scope) {
 }
 async function invokeAkumaFromEdge(parsed, input) {
     try {
-        const { statedCwd, repo, edge } = input;
+        const { executionCwd, repo, edge } = input;
         const path = await akumaWorldFor(parsed, input.located, input.candidate, input.establish);
         const home = parsed.command === "call" ? input.home : undefined;
         const configuration = parsed.command === "call" ? await settingsAt(path, home) : undefined;
@@ -131,7 +133,7 @@ async function invokeAkumaFromEdge(parsed, input) {
             : undefined;
         return await invokeAkuma(parsed, {
             path,
-            ...(statedCwd === undefined ? {} : { statedCwd }),
+            ...(executionCwd === undefined ? {} : { executionCwd }),
             ...(home === undefined ? {} : { home }),
             ...(configuration === undefined ? {} : { settings: configuration }),
             ...(contract === undefined ? (repo === undefined ? {} : { repo }) : { contract }),
@@ -326,13 +328,56 @@ async function resolveInvocationCoordinates(invocation, runtime) {
         command: invocation.command,
     });
 }
+async function invokeTask(parsed, runtime, edge, execution, coordinates) {
+    const actor = taskActor(parsed, runtime, edge.environment);
+    return await (await import("./commands/task-invoke.js")).invokeTaskFromEdge({
+        parsed,
+        world: coordinates.world,
+        candidate: coordinates.candidateWorld,
+        context: coordinates.taskContext,
+        establish: coordinates.establishWorld,
+        readStdin: edge.readStdin,
+        actor,
+        execution,
+    });
+}
+async function callExecutionCwd(input) {
+    if (input.command.command !== "call")
+        return undefined;
+    if (input.workdir !== undefined) {
+        return await canonicalBirthCwd(resolve(input.cwd, input.workdir), `workdir is not an existing directory: ${input.workdir}`);
+    }
+    return input.command.contract === undefined ? input.cwd : undefined;
+}
+async function invokeParsedAkuma(input) {
+    const executionCwd = await callExecutionCwd({
+        command: input.parsed,
+        cwd: input.cwd,
+        ...(input.workdir === undefined ? {} : { workdir: input.workdir }),
+    });
+    return await invokeAkumaFromEdge(input.parsed, {
+        located: input.world,
+        candidate: input.candidate,
+        establish: input.establish,
+        ...(executionCwd === undefined ? {} : { executionCwd }),
+        ...(input.repo === undefined ? {} : { repo: input.repo }),
+        ...(input.home === undefined ? {} : { home: input.home }),
+        edge: input.edge,
+        execution: input.execution,
+    });
+}
 // eslint-disable-next-line complexity -- command dispatch keeps the CLI's existing boundary in one place.
 async function invokeParsed(invocation, runtime) {
     const environment = runtime.environment ?? process.env;
     const execution = executionForEnvironment(environment);
     const coordinates = await resolveInvocationCoordinates(invocation, runtime);
-    const { cwd, cwdSource, repo, world, candidateWorld, establishWorld, taskContext } = coordinates;
-    const edge = { environment, readStdin: runtime.readStdin ?? readStdin };
+    const { cwd, repo, world, candidateWorld, establishWorld } = coordinates;
+    const edge = {
+        environment,
+        readStdin: runtime.readStdin ?? readStdin,
+        ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
+        ...(runtime.progress === undefined ? {} : { progress: runtime.progress }),
+    };
     const parsed = invocation.command;
     const mapped = edge.environment.KEIYAKU_HOME?.trim();
     const home = mapped === undefined || mapped.length === 0 ? undefined : mapped;
@@ -340,34 +385,23 @@ async function invokeParsed(invocation, runtime) {
         return { kind: "settings", value: await settingsAt(world ?? undefined, home) };
     if (parsed.command === "nuke")
         return await (await import("./commands/nuke.js")).invokeNuke(parsed, world);
-    if (parsed.command === "task") {
-        const actor = taskActor(parsed, runtime, edge.environment);
-        return await (await import("./commands/task-invoke.js")).invokeTaskFromEdge({
-            parsed,
-            world,
-            candidate: candidateWorld,
-            context: taskContext,
-            establish: coordinates.establishWorld,
-            readStdin: edge.readStdin,
-            actor,
-            execution,
-        });
-    }
+    if (parsed.command === "task")
+        return await invokeTask(parsed, runtime, edge, execution, coordinates);
     if (parsed.command === "history" && "contract" in parsed)
         return await invokeContractHistory(repo, parsed.contract);
-    if (isParsedAkumaCommand(parsed)) {
-        return await invokeAkumaFromEdge(parsed, {
-            located: world,
+    if (isParsedAkumaCommand(parsed))
+        return await invokeParsedAkuma({
+            parsed,
+            cwd,
+            ...(invocation.workdir === undefined ? {} : { workdir: invocation.workdir }),
+            world,
             candidate: candidateWorld,
             establish: coordinates.establishWorld,
-            invocationCwd: cwd,
-            ...(cwdSource === "input" ? { statedCwd: cwd } : {}),
             ...(repo === undefined ? {} : { repo }),
             ...(home === undefined ? {} : { home }),
             edge,
             execution,
         });
-    }
     if (parsed.command === "ls")
         return await invokeCatalog(parsed, world, repo, home);
     if (parsed.command === "status")
@@ -434,6 +468,7 @@ export async function invoke(invocation, runtime = {}) {
         return await invokeParsed({
             ...(invocation.cwd === undefined ? {} : { cwd: invocation.cwd }),
             ...(invocation.repo === undefined ? {} : { repo: invocation.repo }),
+            ...(invocation.workdir === undefined ? {} : { workdir: invocation.workdir }),
             command,
         }, acquiredRuntime);
     }

package/build/src/cli/main.js

@@ -1,4 +1,5 @@
 import { CliUsageError, parseArgv, renderHelp } from "./parse.js";
+import { installedPackageVersion } from "./version.js";
 export async function main(argv = process.argv.slice(2)) {
     try {
         const parsed = parseArgv(argv);
@@ -8,6 +9,10 @@ export async function main(argv = process.argv.slice(2)) {
             process.stdout.write(help.endsWith("\n") ? help : `${help}\n`);
             return 0;
         }
+        if ("version" in parsed) {
+            process.stdout.write(`${await installedPackageVersion()}\n`);
+            return 0;
+        }
         return await (await import("./runtime.js")).runCliCommand(parsed);
     }
     catch (error) {

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

@@ -29,10 +29,13 @@ export type CliHelpCoordinate = Readonly<{
 export type ParsedExecution = Readonly<{
     cwd?: string;
     repo?: string;
+    workdir?: string;
     command: ParsedCommand;
 }>;
 export type ParsedInvocation = ParsedExecution | Readonly<{
     help: CliHelpCoordinate;
+}> | Readonly<{
+    version: true;
 }>;
 type RepoUse = "none" | "optional" | "required";
 export type CommandRepoPolicy = Readonly<{

package/build/src/cli/parse.js

@@ -10,6 +10,7 @@ const ROOT_USAGE = [
     "usage  keiyaku <command> [options]",
     "      keiyaku <command> --help   shows that command's complete usage",
 ].join("\n");
+const INVOCATION_PATH_OPTIONS = new Set(["-C", "--cwd", "--repo", "--workdir"]);
 export function renderRootHelp(columns) {
     return renderHelpText([
         "keiyaku — Contract, Task, and Akuma control for one repository",
@@ -31,9 +32,13 @@ export function renderRootHelp(columns) {
         `  install   ${INSTALL_ROOT_PURPOSE}`,
         `  settings  ${CONTRACT_COMMAND_SPECS.settings.purpose}`,
         "",
+        "Package",
+        "  --version  Print the running package version.",
+        "",
         "Global options:",
         "  -C, --cwd <path>  Set the invocation working directory.",
         "  --repo <path>     Select the Git repository coordinate.",
+        "  --workdir <path>  Set the execution directory for call only.",
     ].join("\n"), columns);
 }
 function renderHelpText(help, columns) {
@@ -219,25 +224,31 @@ function scanArgv(argv) {
 function invocationOptions(argv) {
     let cwd;
     let repo;
+    let workdir;
     const commandArgv = [];
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
-        if (token !== "-C" && token !== "--cwd" && token !== "--repo") {
+        if (!INVOCATION_PATH_OPTIONS.has(token)) {
             commandArgv.push(token);
             continue;
         }
         if (token === "--repo" && repo !== undefined) {
             throw new CliUsageError("--repo may appear only once", ROOT_USAGE_GUIDE);
         }
-        if (token !== "--repo" && cwd !== undefined) {
+        if ((token === "-C" || token === "--cwd") && cwd !== undefined) {
             throw new CliUsageError("-C/--cwd may appear only once", ROOT_USAGE_GUIDE);
         }
+        if (token === "--workdir" && workdir !== undefined) {
+            throw new CliUsageError("--workdir may appear only once", ROOT_USAGE_GUIDE);
+        }
         const value = argv[index + 1];
-        if (value === undefined || value === "-" || value.startsWith("-") || isBlankInput(value)) {
+        if (invalidInvocationPath(value)) {
             throw new CliUsageError(`${token} requires a path`, ROOT_USAGE_GUIDE);
         }
         if (token === "--repo")
             repo = value;
+        else if (token === "--workdir")
+            workdir = value;
         else
             cwd = value;
         index += 1;
@@ -245,9 +256,13 @@ function invocationOptions(argv) {
     return {
         ...(cwd === undefined ? {} : { cwd }),
         ...(repo === undefined ? {} : { repo }),
+        ...(workdir === undefined ? {} : { workdir }),
         commandArgv,
     };
 }
+function invalidInvocationPath(value) {
+    return value === undefined || value === "-" || value.startsWith("-") || isBlankInput(value);
+}
 function helpCoordinate(argv) {
     const help = argv.indexOf("--help");
     if (help < 0)
@@ -272,6 +287,8 @@ export function parseArgv(argv) {
     const help = helpCoordinate(invocation.commandArgv);
     if (help !== null)
         return { help };
+    if (invocation.commandArgv.length === 1 && invocation.commandArgv[0] === "--version")
+        return { version: true };
     if (invocation.commandArgv[0] === "ls" &&
         (invocation.commandArgv.length === 1 ||
             (invocation.commandArgv.length === 2 && invocation.commandArgv[1] === "--json"))) {
@@ -280,9 +297,14 @@ export function parseArgv(argv) {
     const task = invocation.commandArgv[0] === "task" ? parseTaskCommand(invocation.commandArgv.slice(1)) : undefined;
     const install = invocation.commandArgv[0] === "install" ? parseInstallCommand(invocation.commandArgv.slice(1)) : undefined;
     const akuma = isAkumaAction(invocation.commandArgv[0]) ? parseAkumaCommand(invocation.commandArgv) : undefined;
+    const command = task ?? akuma ?? install ?? parseContractCommand(scanArgv(invocation.commandArgv));
+    if (invocation.workdir !== undefined && command.command !== "call") {
+        throw new CliUsageError(`option --workdir is not valid for ${command.command}`, usageGuideForCommand(command));
+    }
     return {
         ...(invocation.cwd === undefined ? {} : { cwd: invocation.cwd }),
         ...(invocation.repo === undefined ? {} : { repo: invocation.repo }),
-        command: task ?? akuma ?? install ?? parseContractCommand(scanArgv(invocation.commandArgv)),
+        ...(invocation.workdir === undefined ? {} : { workdir: invocation.workdir }),
+        command,
     };
 }