@astrosheep/keiyaku 4.6.4 → 4.6.7

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

@@ -2,7 +2,7 @@ import { CliUsageError, isBlankInput } from "../usage.js";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { squareAssignedParticipantName } from "@astrosheep/square";
-import { emitInitiatingPluginSignal } from "../../plugin/akuma-signals.js";
+import { emitPluginSignal } from "../../plugin/akuma-signals.js";
 import { canonicalBirthCwd } from "../../akuma/call-input.js";
 import { Schema } from "../../akuma/index.js";
 import { executionChannel } from "../../akuma/requests.js";
@@ -12,10 +12,10 @@ import { akumasWithExecution } from "../../library/akumas.js";
 import { World } from "../../world.js";
 import { contractFromInput } from "../selectors.js";
 import { ActivityDriver } from "../activity.js";
-import { displayContext, resultContext, writeJson, writeStderr, writeStdout } from "../streams.js";
+import { displayContext, emit, resultContext, writeJson, writeStderr, writeStdout } from "../streams.js";
 import { callObservationStream, inputWaitStream, waitObservationStream, } from "../render/akuma-activity.js";
-import { askRawAnswer, callRawAnswer, historyRawAnswer, waitRawAnswer } from "../render/akuma-activity.js";
-import { askExitCode, askProgressStream, callExitCode, callObservationHead, forkExitCode, historyExitCode, killExitCode, renderCallText, renderForkText, renderHistoryText, renderKillText, renderTellText, renderWaitText, tellExitCode, waitedTellProgress, } from "../render/akuma.js";
+import { askRawAnswer, callRawAnswer, historyRawAnswer, historyText, tellText, waitRawAnswer, waitText, } from "../render/akuma-activity.js";
+import { askExitCode, askProgressStream, callExitCode, callObservationHead, forkExitCode, historyExitCode, killExitCode, renderCallText, renderForkText, renderKillText, tellExitCode, waitedTellProgress, } from "../render/akuma.js";
 export { isParsedAkumaCommand, renderAkumaHelp } from "./akuma-grammar.js";
 // ---------------------------------------------------------------------------
 // Leaf dispatch: acquisition, one public SDK invocation, direct rendering
@@ -73,20 +73,14 @@ async function inputInitiator(input) {
     // The initiator still travels with the request either way.
     if (!(await World.established(input.path)))
         return { initiator };
-    try {
-        await emitInitiatingPluginSignal({
-            world: input.path,
-            ...(input.settings === undefined ? {} : { settings: input.settings }),
-            initiator,
-            reportDiagnostic: (message) => writeStderr(message),
-        });
-    }
-    catch (error) {
-        writeStderr(`! plugin initiation: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    await emitPluginSignal({
+        world: input.path,
+        ...(input.settings === undefined ? {} : { settings: input.settings }),
+        reportDiagnostic: (message) => writeStderr(message),
+    }, { kind: "akuma.initiating", initiator });
     return { initiator };
 }
-function emitResult(body, exact) {
+function emitAnswer(body, exact) {
     if (exact)
         process.stdout.write(body);
     else
@@ -152,9 +146,9 @@ async function runCall(command, input) {
         }
         const raw = callRawAnswer(result, streamed);
         if (raw === undefined)
-            emitResult(renderCallText(result, streamed, displayContext()), false);
+            emitAnswer(renderCallText(result, streamed, displayContext()), false);
         else
-            emitResult(raw, true);
+            emitAnswer(raw, true);
         return callExitCode(result);
     }
     finally {
@@ -195,9 +189,9 @@ async function runWait(command, input) {
         }
         const raw = waitRawAnswer(result, streamed);
         if (raw === undefined)
-            emitResult(renderWaitText(result, presentation, displayContext()), false);
+            emitAnswer(waitText(result, presentation, displayContext()), false);
         else
-            emitResult(raw, true);
+            emitAnswer(raw, true);
         return 0;
     }
     finally {
@@ -214,12 +208,8 @@ async function runTell(command, input) {
         ...(input.repo === undefined ? {} : { repo: input.repo }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
-    if (command.output === "json") {
-        writeJson(result);
-        return tellExitCode(result);
-    }
-    emitResult(renderTellText(result, inputAlias(command.akuma), displayContext()), false);
-    return tellExitCode(result);
+    const text = () => tellText(result, inputAlias(command.akuma), displayContext());
+    return emit(command.output, result, text, tellExitCode(result));
 }
 async function runAsk(command, input) {
     const body = await promptBody("ask", command, input);
@@ -261,7 +251,7 @@ async function runAsk(command, input) {
             writeJson(result);
             return askExitCode(result);
         }
-        emitResult(askRawAnswer(result, schema !== undefined) ?? "", true);
+        emitAnswer(askRawAnswer(result, schema !== undefined) ?? "", true);
         return askExitCode(result);
     }
     finally {
@@ -289,11 +279,11 @@ async function runHistory(command, input) {
         last: command.last,
     };
     if (raw !== undefined)
-        emitResult(raw, true);
+        emitAnswer(raw, true);
     else if (command.last && result.kind === "last")
-        emitResult(result.answer, true);
+        emitAnswer(result.answer, true);
     else
-        emitResult(renderHistoryText(result, presentation, displayContext()), false);
+        emitAnswer(historyText(result, presentation, displayContext()), false);
     return historyExitCode(result, command.id);
 }
 async function runFork(command, input) {
@@ -302,12 +292,7 @@ async function runFork(command, input) {
         at: command.at,
         ...(input.repo === undefined ? {} : { repo: input.repo }),
     });
-    if (command.output === "json") {
-        writeJson(receipt);
-        return forkExitCode(receipt);
-    }
-    emitResult(renderForkText(receipt), false);
-    return forkExitCode(receipt);
+    return emit(command.output, receipt, () => renderForkText(receipt), forkExitCode(receipt));
 }
 async function runKill(command, input) {
     const alias = command.akuma.length === 1 ? inputAlias(command.akuma[0]) : undefined;
@@ -316,12 +301,8 @@ async function runKill(command, input) {
         ...(input.repo === undefined ? {} : { repo: input.repo }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
-    if (command.output === "json") {
-        writeJson(result);
-        return killExitCode(result);
-    }
-    emitResult(renderKillText(result, alias, displayContext()), false);
-    return killExitCode(result);
+    const text = () => renderKillText(result, alias, displayContext());
+    return emit(command.output, result, text, killExitCode(result));
 }
 async function akumaWorld(command, coordinates) {
     const world = command.command === "call"

package/build/src/cli/commands/contract-grammar.d.ts

@@ -44,7 +44,7 @@ export type ParsedDeliver = Output & Readonly<{
     materializeConflict: boolean;
     overwrite: boolean;
 }>;
-export type ParsedReview = Output & Readonly<{
+export type ParsedReview = Output & Actor & Readonly<{
     command: "review";
     contract?: string;
     verdict: "satisfied" | "unsatisfied";
@@ -66,11 +66,23 @@ export type ParsedStatus = Output & (Readonly<{
     selectors?: readonly string[];
     akuma?: never;
     guidance?: true;
+    category?: never;
+    limit?: never;
 }> | Readonly<{
     command: "status";
     contract: string;
     akuma: true;
     guidance?: never;
+    category?: never;
+    limit?: never;
+}> | Readonly<{
+    command: "status";
+    category: StatusCategory;
+    limit?: number;
+    contract?: never;
+    selectors?: never;
+    akuma?: never;
+    guidance?: never;
 }>);
 export type ParsedLs = Output & Readonly<{
     command: "ls";
@@ -108,5 +120,6 @@ export type ParsedContractParts = Readonly<{
     actor?: string;
 }>;
 export type ParsedContractCommand = ParsedBind | ParsedAmend | ParsedDeliver | ParsedReview | ParsedArc | ParsedAbandon | ParsedStatus | ParsedLs | ParsedAudit | ParsedReconcile | ParsedNuke | ParsedSettings | ParsedRegion;
+export type StatusCategory = "akuma" | "contract";
 export declare function parseContractCommand(parts: ParsedContractParts): ParsedContractCommand;
 export {};

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

@@ -123,32 +123,65 @@ 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,
     };
 }
-function parseStatus(parts) {
-    const guidance = parts.flags.guidance === true;
-    if (guidance) {
-        const selected = parts.positionals[0];
-        if (parts.positionals.length > 1)
-            refuse("status", "--guidance accepts at most one Contract selector");
-        if (selected?.startsWith("aku/") === true)
-            refuse("status", "--guidance cannot select an Akuma");
-        return {
-            command: "status",
-            ...(selected === undefined ? {} : { contract: selected }),
-            guidance: true,
-            output: parts.output,
-        };
+// Only these fixed category forms are status selectors.
+const STATUS_CATEGORY_SELECTORS = new Map([
+    ["aku", "akuma"],
+    ["aku/", "akuma"],
+    ["aku/*", "akuma"],
+    ["kei", "contract"],
+    ["kei/", "contract"],
+    ["kei/*", "contract"],
+]);
+function rejectStatusGlobs(positionals) {
+    for (const selector of positionals) {
+        if (!STATUS_CATEGORY_SELECTORS.has(selector) && !selector.startsWith("@") && /[*?\[\]]/u.test(selector))
+            refuse("status", `unsupported status glob: ${selector}`);
     }
+}
+function parseStatusGuidance(parts, limit) {
+    if (limit !== undefined)
+        refuse("status", "--limit is not valid with --guidance");
+    const selected = parts.positionals[0];
+    if (selected !== undefined && STATUS_CATEGORY_SELECTORS.has(selected))
+        refuse("status", "--guidance cannot select a category");
+    if (parts.positionals.length > 1)
+        refuse("status", "--guidance accepts at most one Contract selector");
+    if (selected?.startsWith("aku/") === true)
+        refuse("status", "--guidance cannot select an Akuma");
+    if (selected !== undefined && !selected.startsWith("@") && /[*?\[\]]/u.test(selected))
+        refuse("status", `unsupported status glob: ${selected}`);
+    return {
+        command: "status",
+        ...(selected === undefined ? {} : { contract: selected }),
+        guidance: true,
+        output: parts.output,
+    };
+}
+function parseStatus(parts) {
+    const limit = listLimit(parts, "status");
+    if (parts.flags.guidance === true)
+        return parseStatusGuidance(parts, limit);
+    rejectStatusGlobs(parts.positionals);
     if (parts.positionals.length > 1) {
+        if (limit !== undefined)
+            refuse("status", "--limit is valid only for one category selector");
+        if (parts.positionals.some((selector) => STATUS_CATEGORY_SELECTORS.has(selector)))
+            refuse("status", "a category selector cannot combine with other selectors");
         return { command: "status", selectors: parts.positionals, output: parts.output };
     }
-    const contract = parts.positionals[0];
-    if (contract?.startsWith("aku/") === true) {
-        return { command: "status", contract, akuma: true, output: parts.output };
-    }
-    return { command: "status", ...(contract === undefined ? {} : { contract }), output: parts.output };
+    const selected = parts.positionals[0];
+    const category = selected === undefined ? undefined : STATUS_CATEGORY_SELECTORS.get(selected);
+    if (category !== undefined)
+        return { command: "status", category, ...(limit === undefined ? {} : { limit }), output: parts.output };
+    if (limit !== undefined)
+        refuse("status", "--limit is valid only for a category selector");
+    if (selected?.startsWith("aku/") === true)
+        return { command: "status", contract: selected, akuma: true, output: parts.output };
+    return { command: "status", ...(selected === undefined ? {} : { contract: selected }), output: parts.output };
 }
 function parseRegion(parts) {
     const contract = parts.positionals[0];
@@ -172,10 +205,10 @@ function akumaCatalogQuery(query, parts) {
         ...(limit === undefined ? {} : { limit: Number(limit) }),
     };
 }
-function listLimit(parts) {
+function listLimit(parts, command = "ls") {
     const limit = optionalFlag(parts.flags, "limit");
     if (limit !== undefined && (!/^[1-9][0-9]*$/u.test(limit) || !Number.isSafeInteger(Number(limit))))
-        refuse("ls", "--limit requires a positive safe integer");
+        refuse(command, "--limit requires a positive safe integer");
     return limit === undefined ? undefined : Number(limit);
 }
 function taskCatalogQuery(path, limit) {

package/build/src/cli/commands/contract-help.d.ts

@@ -1,8 +1,8 @@
-type ContractFlagKind = "boolean" | "value" | "raw-value" | "repeat-value";
+import type { ScanFlagKind } from "../scan.js";
 export type ContractCommandSpec = Readonly<{
     positional: "none" | "optional";
     stdin: "none" | "optional" | "required";
-    flags: Readonly<Record<string, ContractFlagKind>>;
+    flags: Readonly<Record<string, ScanFlagKind>>;
     usage: string;
     purpose: string;
     details?: string;
@@ -15,7 +15,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
             readonly actor: "value";
             readonly task: "value";
             readonly target: "value";
-            readonly after: "repeat-value";
+            readonly after: "repeat";
             readonly gates: "raw-value";
             readonly "fork-of": "value";
             readonly json: "boolean";
@@ -29,7 +29,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly stdin: "optional";
         readonly flags: {
             readonly actor: "value";
-            readonly after: "repeat-value";
+            readonly after: "repeat";
             readonly "clear-after": "boolean";
             readonly gates: "raw-value";
             readonly json: "boolean";
@@ -56,12 +56,13 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly positional: "optional";
         readonly stdin: "optional";
         readonly flags: {
+            readonly actor: "value";
             readonly satisfied: "boolean";
             readonly unsatisfied: "boolean";
             readonly summary: "value";
             readonly json: "boolean";
         };
-        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -)";
+        readonly usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]";
         readonly purpose: "Record whether a Contract meets its acceptance criteria.";
         readonly details: string;
     };
@@ -92,9 +93,10 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly stdin: "none";
         readonly flags: {
             readonly guidance: "boolean";
+            readonly limit: "value";
             readonly json: "boolean";
         };
-        readonly usage: "status [<contract>|@name|<aku/...>]...\nstatus --guidance [<contract>|@<contract>]";
+        readonly usage: "status [<contract>|@name|<aku/...>]...\nstatus (aku|aku/|aku/*) [--limit <count>]\nstatus (kei|kei/|kei/*) [--limit <count>]\nstatus --guidance [<contract>|@<contract>]";
         readonly purpose: "Show the world overview or selected Contract and Akuma status.";
         readonly details: string;
     };
@@ -156,7 +158,7 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly positional: "optional";
         readonly stdin: "none";
         readonly flags: {
-            readonly path: "repeat-value";
+            readonly path: "repeat";
             readonly json: "boolean";
         };
         readonly usage: "region [<contract>]\nregion --path <pattern> [--path <pattern> ...]";
@@ -166,4 +168,3 @@ export declare const CONTRACT_COMMAND_SPECS: {
 };
 export type ContractCommand = keyof typeof CONTRACT_COMMAND_SPECS;
 export declare function renderContractHelp(command: ContractCommand): string;
-export {};

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

@@ -7,7 +7,7 @@ export const CONTRACT_COMMAND_SPECS = {
             actor: "value",
             task: "value",
             target: "value",
-            after: "repeat-value",
+            after: "repeat",
             gates: "raw-value",
             "fork-of": "value",
             json: "boolean",
@@ -47,6 +47,7 @@ export const CONTRACT_COMMAND_SPECS = {
             "A pattern containing whitespace binds with a warning. A fence carries no",
             "info string or exactly 'txt'.",
             "",
+            "Verification runs only with the verified gate; without it the section is inert text.",
             "Verification uses one or more closed bash, zsh, or pwsh fences. Its fence",
             "may add timeout=<integer><ms|s|m|h>; the section contains no other prose.",
             "Unknown ## sections are retained as extensions; reserved section names are refused.",
@@ -55,7 +56,7 @@ export const CONTRACT_COMMAND_SPECS = {
     amend: {
         positional: "optional",
         stdin: "optional",
-        flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
+        flags: { actor: "value", after: "repeat", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
         usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [-]",
         purpose: "Change a Contract's document, prerequisites, or acceptance gates.",
         details: [
@@ -91,6 +92,7 @@ export const CONTRACT_COMMAND_SPECS = {
         purpose: "Submit work for a Contract and integrate it when its requirements are met.",
         details: [
             "The Contract, not the current Arc, sets what delivery must satisfy. An Arc records progress; it does not narrow acceptance.",
+            "With the verified gate, delivery runs Verification or reuses current satisfied evidence.",
             "Verification, integration, and cleanup progress appears on stderr; stdout contains one final result.",
             "By default, delivery uses HEAD. --include-dirty includes all non-ignored worktree changes, staged or not; it leaves your branch and index unchanged, so staging or committing is unnecessary.",
             "Repeating delivery with unchanged work resumes unfinished verification or integration. Changed work replaces the candidate.",
@@ -107,8 +109,8 @@ export const CONTRACT_COMMAND_SPECS = {
     review: {
         positional: "optional",
         stdin: "optional",
-        flags: { satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
-        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -)",
+        flags: { actor: "value", satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
+        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--actor <actor>]",
         purpose: "Record whether a Contract meets its acceptance criteria.",
         details: [
             "A review checks the whole Contract, not just one Arc. After delivery it checks the candidate; before delivery it checks the current Contract and worktree, but cannot integrate.",
@@ -141,12 +143,16 @@ export const CONTRACT_COMMAND_SPECS = {
     status: {
         positional: "optional",
         stdin: "none",
-        flags: { guidance: "boolean", json: "boolean" },
-        usage: "status [<contract>|@name|<aku/...>]...\nstatus --guidance [<contract>|@<contract>]",
+        flags: { guidance: "boolean", limit: "value", json: "boolean" },
+        usage: "status [<contract>|@name|<aku/...>]...\nstatus (aku|aku/|aku/*) [--limit <count>]\nstatus (kei|kei/|kei/*) [--limit <count>]\nstatus --guidance [<contract>|@<contract>]",
         purpose: "Show the world overview or selected Contract and Akuma status.",
         details: [
             "Akuma entries show the directory each Akuma was started in.",
             "",
+            "aku, aku/, and aku/* show the recent Akuma board; kei, kei/, and kei/* show the",
+            "recent active Contract board. --limit bounds the board to that many recent rows",
+            "(default 10). The Contract category requires a Repo; the Akuma category does not.",
+            "",
             "--guidance reads one Contract's guidance instead of status. It accepts one Contract",
             "selector or the installed Contract selection context, and refuses an Akuma, plural,",
             "or world selection before the read.",
@@ -173,6 +179,7 @@ export const CONTRACT_COMMAND_SPECS = {
         details: [
             "--include-dirty checks all non-ignored worktree changes, staged or not.",
             "--show-diff includes the proposed candidate diff when one can be prepared.",
+            "Verification runs only with the verified gate; without it the section is inert text.",
             "Content identity names the change's content hash, never a commit; it survives rebase and Git cannot look it up.",
             "Progress appears on stderr; stdout contains one final result.",
         ].join("\n"),
@@ -203,7 +210,7 @@ export const CONTRACT_COMMAND_SPECS = {
     region: {
         positional: "optional",
         stdin: "none",
-        flags: { path: "repeat-value", json: "boolean" },
+        flags: { path: "repeat", json: "boolean" },
         usage: "region [<contract>]\nregion --path <pattern> [--path <pattern> ...]",
         purpose: "Show declared Contract write patterns — all, one Contract's, or those overlapping given paths.",
         details: "Check overlap before starting parallel work.",