@astrosheep/keiyaku 2.9.2 → 2.9.4

package/build/cli/commands/projection/wait/meta.js

@@ -1,11 +1,16 @@
+export const WAIT_SET_SELECTION_ERROR = "wait requires exactly one of --any or --all when selecting multiple projections";
 export const meta = {
     command: "wait",
     summary: "Wait for an akuma projection",
     usage: [
         "keiyaku wait <projection-address> [--timeout DURATION]",
-        "keiyaku @addr wait <projection-address> [--timeout DURATION]",
+        "keiyaku wait <projection-address> <projection-address>... (--any|--all) [--timeout DURATION]",
+        "keiyaku @addr wait [<projection-address>...] (--any|--all) [--timeout DURATION]",
     ],
     stdin: "none",
-    flags: ["cwd", "repo", "contract", "timeout"],
+    flags: ["cwd", "repo", "contract", "timeout", "any", "all"],
+    flagDescriptions: {
+        all: "For a projection set, return only after every admitted member reaches a terminal state.",
+    },
     purpose: "Read an akuma projection until its outcome is available, or show a timeout snapshot.",
 };

package/build/cli/commands/registry.js

@@ -5,40 +5,7 @@ import { akumaCatalog } from "./akuma/catalog.js";
 import { skillsCatalog } from "./skills/catalog.js";
 import { systemCatalog } from "./system/catalog.js";
 import { taskCatalog } from "./task/catalog.js";
-/** Stable metadata key order consumed by help and tests. */
-const METADATA_ORDER = [
-    "bind",
-    "arc",
-    "call",
-    "revive",
-    "wait",
-    "tell",
-    "kill",
-    "log",
-    "akuma",
-    "akuma ls",
-    "akuma view",
-    "skills",
-    "skills install",
-    "amend",
-    "renew",
-    "petition",
-    "forfeit",
-    "guide",
-    "completion",
-    "status",
-    "task",
-    "task add",
-    "task view",
-    "task ls",
-    "task start",
-    "task stop",
-    "task done",
-    "task drop",
-    "task update",
-    "task doctor",
-    "dump-env",
-];
+import { COMMAND_METADATA_ORDER } from "./metadata.js";
 function buildRegistry(catalogs) {
     const registrations = catalogs.flat();
     const byCommand = new Map();
@@ -50,7 +17,7 @@ function buildRegistry(catalogs) {
         byCommand.set(command, registration);
     }
     const registry = {};
-    for (const command of METADATA_ORDER) {
+    for (const command of COMMAND_METADATA_ORDER) {
         const registration = byCommand.get(command);
         if (!registration) {
             throw new FlowError("INTERNAL_STATE", `missing CLI command registration: ${command}`);
@@ -72,28 +39,9 @@ const REGISTRY = buildRegistry([
     systemCatalog,
     taskCatalog,
 ]);
-/** Longest multi-token match first; same token count keeps METADATA_ORDER. */
-function deriveParseOrder(order) {
-    return [...order].sort((a, b) => {
-        const tokenDelta = b.split(" ").length - a.split(" ").length;
-        if (tokenDelta !== 0)
-            return tokenDelta;
-        return order.indexOf(a) - order.indexOf(b);
-    });
-}
-const PARSE_ORDER = deriveParseOrder(METADATA_ORDER);
 export function getCommandRegistration(command) {
     return REGISTRY[command];
 }
-export function getCommandMetadata(command) {
-    return REGISTRY[command].meta;
-}
-export function allCommandMetadata() {
-    return METADATA_ORDER.map((command) => REGISTRY[command].meta);
-}
-export function commandParseOrder() {
-    return PARSE_ORDER;
-}
 export async function loadCommandHandler(command) {
     const module = await REGISTRY[command].load();
     return module.handler;

package/build/cli/commands/shared.js

@@ -1,8 +1,9 @@
 import { FlowError } from "../../flow-error.js";
 import { AddressResolutionError, buildResolutionAttempt, } from "../../core/addressing.js";
+import { normalizeFilesystemCoordinate } from "../../fs/path-coordinate.js";
 import { assertGitObservation, observeGitRepository } from "../../git/branches.js";
 import { stableRepoRoot } from "../../core/worktree-path.js";
-import { assertProjectionAlias } from "../../core/projection-alias.js";
+import { assertProjectionAlias } from "../../core/projection/index.js";
 export function titleFromCallPrompt(prompt) {
     const firstLine = prompt
         .split(/\r?\n/)
@@ -15,15 +16,15 @@ export function titleFromCallPrompt(prompt) {
 export function repositoryCoordinateFromAddress(address) {
     return address?.repo.kind === "repository" ? address.repo.stableRoot : undefined;
 }
-export function buildCallInput(content, flags, mode = "call") {
-    const cwd = flags.cwd ?? process.cwd();
+export function buildCallInput(content, flags, mode = "call", platform = process.platform) {
+    const cwd = effectiveDirectory(flags, platform);
     const task = content.trim();
     if (!task) {
         throw new FlowError("EMPTY_PARAM", `${mode} body cannot be empty`);
     }
     return {
         cwd,
-        repo: flags.repo,
+        repo: flags.repo === undefined ? undefined : normalizeFilesystemCoordinate(flags.repo, platform),
         mode,
         contractId: flags.contractId,
         contractAddressSource: flags.contractAddressSource,
@@ -41,11 +42,13 @@ export function buildCallInput(content, flags, mode = "call") {
 export function revivePrompt(stdin) {
     return stdin.trim() ? stdin : "Continue from the previous response.";
 }
-export function effectiveDirectory(flags) {
-    return flags.cwd ?? process.cwd();
+export function effectiveDirectory(flags, platform = process.platform) {
+    return normalizeFilesystemCoordinate(flags.cwd ?? process.cwd(), platform);
 }
 export async function repositoryDirectory(flags, operation) {
-    const candidate = flags.repo ?? effectiveDirectory(flags);
+    const candidate = flags.repo === undefined
+        ? effectiveDirectory(flags)
+        : normalizeFilesystemCoordinate(flags.repo);
     if (assertGitObservation(await observeGitRepository(candidate), operation) === "non-repository") {
         if (flags.contractId) {
             const asTyped = flags.contractAddressSource === "at-address"

package/build/cli/commands/skills/install/handler.js

@@ -1,10 +1,7 @@
 import { installOfficialSkills } from "../../../skills-install.js";
+import { renderSkillsInstallReceipt } from "../../../render/skills.js";
 import { textResponse } from "../../../render/shared.js";
 export const handler = async (_stdin, flags) => {
     const result = await installOfficialSkills(flags.force);
-    return textResponse([
-        "Installed official Keiyaku skills:",
-        ...result.targets.map((target) => `- ${target.path} -> ${target.source} (${target.status})`),
-        ...(result.warnings.length > 0 ? ["", "## Warning", ...result.warnings.map((warning) => `- ${warning}`)] : []),
-    ].join("\n"));
+    return textResponse(renderSkillsInstallReceipt(result));
 };

package/build/cli/commands/skills/skills/handler.js

@@ -1,4 +1,4 @@
-import { missingSubcommandError } from "../../../help.js";
+import { missingSubcommandError } from "../../../missing-subcommand.js";
 export const handler = async () => {
     throw missingSubcommandError("skills", ["install"]);
 };

package/build/cli/commands/task/add/handler.js

@@ -1,21 +1,13 @@
-import { randomBytes } from "node:crypto";
-import { resolveTaskCreator } from "../../../../core/task-git-actor.js";
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { createTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-import { parseTaskAddInput } from "../shared.js";
+import { createTask, resolveTaskCreator, } from "../../../../core/task/index.js";
+import { parseTaskAddInput, runTaskMutationCommand } from "../shared.js";
 export const handler = async (stdin, flags, _signal, positional) => {
-    const cwd = effectiveDirectory(flags);
     const input = parseTaskAddInput(positional[0] === "-" ? stdin : positional[0]);
-    const task = await createTask(await openTaskCommandRepository(cwd), {
+    return runTaskMutationCommand(flags, async (repository, cwd) => createTask(repository, {
         ...input,
-        creator: resolveTaskCreator(cwd),
+        creator: await resolveTaskCreator(cwd),
         ...(flags.taskPri === undefined ? {} : { pri: flags.taskPri }),
         needs: flags.taskNeeds ?? [],
         parent: flags.taskParent ?? null,
         from: flags.taskFrom ?? [],
-    }, { randomBytes, now: () => new Date() });
-    return textResponse(renderTaskMutationRow(task));
+    }, { now: () => new Date() }));
 };

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

@@ -1,6 +1,6 @@
 import { meta as taskMeta } from "./task/meta.js";
 import { meta as addMeta } from "./add/meta.js";
-import { meta as viewMeta } from "./view/meta.js";
+import { meta as showMeta } from "./show/meta.js";
 import { meta as lsMeta } from "./ls/meta.js";
 import { meta as startMeta } from "./start/meta.js";
 import { meta as stopMeta } from "./stop/meta.js";
@@ -11,7 +11,7 @@ import { meta as doctorMeta } from "./doctor/meta.js";
 export const taskCatalog = [
     { meta: taskMeta, load: () => import("./task/handler.js") },
     { meta: addMeta, load: () => import("./add/handler.js") },
-    { meta: viewMeta, load: () => import("./view/handler.js") },
+    { meta: showMeta, load: () => import("./show/handler.js") },
     { meta: lsMeta, load: () => import("./ls/handler.js") },
     { meta: startMeta, load: () => import("./start/handler.js") },
     { meta: stopMeta, load: () => import("./stop/handler.js") },

package/build/cli/commands/task/done/handler.js

@@ -1,15 +1,11 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { doneTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
+import { doneTask } from "../../../../core/task/index.js";
 import { effectiveDirectory } from "../../shared.js";
-import { mutationSelectionMessage, rejectBareContractTaskState } from "../shared.js";
+import { mutationSelectionMessage, rejectBareContractTaskState, runTaskMutationCommand } from "../shared.js";
 export const handler = async (_stdin, flags, _signal, positional) => {
     try {
-        const cwd = effectiveDirectory(flags);
         if (positional[0] === undefined)
-            await rejectBareContractTaskState(cwd, "done");
-        return textResponse(renderTaskMutationRow(await doneTask(await openTaskCommandRepository(cwd), positional[0])));
+            await rejectBareContractTaskState(effectiveDirectory(flags), "done");
+        return await runTaskMutationCommand(flags, (repository) => doneTask(repository, positional[0]));
     }
     catch (error) {
         return mutationSelectionMessage(error);

package/build/cli/commands/task/drop/handler.js

@@ -1,6 +1,3 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { dropTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-export const handler = async (_stdin, flags, _signal, positional) => textResponse(renderTaskMutationRow(await dropTask(await openTaskCommandRepository(effectiveDirectory(flags)), positional[0])));
+import { dropTask } from "../../../../core/task/index.js";
+import { runTaskMutationCommand } from "../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => runTaskMutationCommand(flags, (repository) => dropTask(repository, positional[0]));

package/build/cli/commands/task/ls/handler.js

@@ -1,11 +1,9 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { readTaskBoard } from "../../../../core/task.js";
+import { readTaskBoard } from "../../../../core/task/index.js";
 import { renderTaskList, renderTaskListJson } from "../../../render/task.js";
 import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-import { taskJsonText, taskSelection } from "../shared.js";
+import { taskJsonText, taskSelection, withTaskCommandRepository } from "../shared.js";
 export const handler = async (_stdin, flags) => {
-    const board = await readTaskBoard(await openTaskCommandRepository(effectiveDirectory(flags)));
+    const board = await withTaskCommandRepository(flags, (repository) => readTaskBoard(repository));
     const selection = taskSelection(flags);
     return textResponse(flags.json
         ? taskJsonText(renderTaskListJson(board.tasks, selection))

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

@@ -1,8 +1,18 @@
 import * as path from "node:path";
 import { FlowError } from "../../../flow-error.js";
-import { readTaskDoctor, taskCommandContractId } from "../../../core/task-git-runtime.js";
-import { deriveTaskDisplay, renderTaskList, } from "../../render/task.js";
-import { parseTaskDocument, } from "../../../core/task.js";
+import { isTaskId, openTaskCommandRepository, parseTaskDocument, readTaskDoctor, taskCommandContractId, } from "../../../core/task/index.js";
+import { deriveTaskDisplay, renderTaskList, renderTaskMutationRow, } from "../../render/task.js";
+import { textResponse } from "../../render/shared.js";
+import { effectiveDirectory } from "../shared.js";
+/** Open the task command repository for flags.cwd and run the verb. */
+export async function withTaskCommandRepository(flags, run) {
+    const cwd = effectiveDirectory(flags);
+    return run(await openTaskCommandRepository(cwd), cwd);
+}
+/** Shared shell: open repository → mutate → renderTaskMutationRow receipt. */
+export async function runTaskMutationCommand(flags, mutate) {
+    return textResponse(renderTaskMutationRow(await withTaskCommandRepository(flags, mutate)));
+}
 export function parseTaskAddInput(input) {
     if (!input.trim())
         throw new FlowError("EMPTY_PARAM", "task add input cannot be blank");
@@ -49,7 +59,7 @@ function renderTaskDiseaseRows(diseases, documents) {
     for (const disease of diseases) {
         if (disease.code === "invalid_document") {
             const name = path.basename(disease.path).replace(/\.md$/, "");
-            if (/^k-[0-9a-f]{12}$/.test(name))
+            if (isTaskId(name))
                 rows.push(`! ${name} invalid front matter — quarantined`);
             continue;
         }

package/build/cli/commands/task/{view → show}/handler.js

@@ -1,14 +1,13 @@
 import { FlowError } from "../../../../flow-error.js";
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { readTaskBoard, resolveTaskReadId } from "../../../../core/task.js";
+import { buildTaskTree, readTaskBoard, resolveTaskReadId, } from "../../../../core/task/index.js";
 import { renderTaskShow, renderTaskShowJson } from "../../../render/task.js";
 import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-import { taskJsonText } from "../shared.js";
-export const handler = async (_stdin, flags, _signal, positional) => {
-    const board = await readTaskBoard(await openTaskCommandRepository(effectiveDirectory(flags)));
+import { taskJsonText, withTaskCommandRepository } from "../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => withTaskCommandRepository(flags, async (repository) => {
+    const board = await readTaskBoard(repository);
     const task = board.byId.get(resolveTaskReadId(board, positional[0]));
     if (!task)
         throw new FlowError("INTERNAL_STATE", "resolved task disappeared from the board");
-    return textResponse(flags.json ? taskJsonText(renderTaskShowJson(task)) : renderTaskShow(task));
-};
+    const tree = buildTaskTree(board, task.id);
+    return textResponse(flags.json ? taskJsonText(renderTaskShowJson(task, tree)) : renderTaskShow(task, tree));
+});

package/build/cli/commands/task/show/meta.js

@@ -0,0 +1,8 @@
+export const meta = {
+    command: "task show",
+    summary: "Show one task and its children tree",
+    usage: ["keiyaku task show [-C|--cwd DIR] ID [--json]"],
+    stdin: "none",
+    flags: ["cwd", "json"],
+    purpose: "Read one task and every descendant linked by parent edges.",
+};

package/build/cli/commands/task/start/handler.js

@@ -1,6 +1,3 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { startTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
-export const handler = async (_stdin, flags, _signal, positional) => textResponse(renderTaskMutationRow(await startTask(await openTaskCommandRepository(effectiveDirectory(flags)), positional[0], new Date())));
+import { startTask } from "../../../../core/task/index.js";
+import { runTaskMutationCommand } from "../shared.js";
+export const handler = async (_stdin, flags, _signal, positional) => runTaskMutationCommand(flags, (repository) => startTask(repository, positional[0], new Date()));

package/build/cli/commands/task/stop/handler.js

@@ -1,15 +1,11 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { stopTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
+import { stopTask } from "../../../../core/task/index.js";
 import { effectiveDirectory } from "../../shared.js";
-import { mutationSelectionMessage, rejectBareContractTaskState } from "../shared.js";
+import { mutationSelectionMessage, rejectBareContractTaskState, runTaskMutationCommand } from "../shared.js";
 export const handler = async (_stdin, flags, _signal, positional) => {
     try {
-        const cwd = effectiveDirectory(flags);
         if (positional[0] === undefined)
-            await rejectBareContractTaskState(cwd, "stop");
-        return textResponse(renderTaskMutationRow(await stopTask(await openTaskCommandRepository(cwd), positional[0])));
+            await rejectBareContractTaskState(effectiveDirectory(flags), "stop");
+        return await runTaskMutationCommand(flags, (repository) => stopTask(repository, positional[0]));
     }
     catch (error) {
         return mutationSelectionMessage(error);

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

@@ -1,4 +1,4 @@
-import { missingSubcommandError } from "../../../help.js";
+import { missingSubcommandError } from "../../../missing-subcommand.js";
 import { TASK_SUBCOMMANDS } from "../../../types.js";
 export const handler = async () => {
     throw missingSubcommandError("task", TASK_SUBCOMMANDS);

package/build/cli/commands/task/update/handler.js

@@ -1,11 +1,8 @@
-import { openTaskCommandRepository } from "../../../../core/task-git-runtime.js";
-import { updateTask } from "../../../../core/task.js";
-import { renderTaskMutationRow } from "../../../render/task.js";
-import { textResponse } from "../../../render/shared.js";
-import { effectiveDirectory } from "../../shared.js";
+import { updateTask } from "../../../../core/task/index.js";
+import { runTaskMutationCommand } from "../shared.js";
 export const handler = async (stdin, flags, _signal, positional) => {
     const body = flags.taskBody === "-" ? stdin : flags.taskBody;
-    const task = await updateTask(await openTaskCommandRepository(effectiveDirectory(flags)), positional[0], {
+    return runTaskMutationCommand(flags, (repository) => updateTask(repository, positional[0], {
         ...(flags.taskTitle === undefined ? {} : { title: flags.taskTitle }),
         ...(body === undefined ? {} : { body }),
         ...(flags.taskPri === undefined ? {} : { pri: flags.taskPri }),
@@ -13,6 +10,5 @@ export const handler = async (stdin, flags, _signal, positional) => {
         ...(flags.taskDropNeeds === undefined ? {} : { dropNeeds: flags.taskDropNeeds }),
         ...(flags.taskParent !== undefined ? { parent: flags.taskParent } : flags.taskNoParent ? { parent: null } : {}),
         ...(flags.taskFrom === undefined ? {} : { from: flags.taskFrom }),
-    });
-    return textResponse(renderTaskMutationRow(task));
+    }));
 };

package/build/cli/completion.js

@@ -2,7 +2,7 @@ import { assertSettingsKnobUsable } from "../config/settings/disease.js";
 import { loadKeiyakuSettings } from "../config/settings/loader.js";
 import { loadAkumaCatalog } from "../config/akuma-loader.js";
 import { listContractIds } from "../core/ledger.js";
-import { allCommandMetadata, getCommandMetadata } from "./commands/registry.js";
+import { allCommandMetadata, getCommandMetadata } from "./commands/metadata.js";
 function topLevelCommands() {
     return allCommandMetadata()
         .filter((meta) => meta.completionRank !== undefined)

package/build/cli/flags.js

@@ -4,12 +4,12 @@ export const FLAG_SPECS = {
     cwd: {
         kind: "value",
         placeholder: "DIR",
-        description: "Select the effective command directory (-C/--cwd). Defaults to the process working directory.",
+        description: "Select the effective command directory (-C/--cwd). Defaults to the process working directory; the repository is inferred from here unless --repo is set.",
     },
     repo: {
         kind: "value",
         placeholder: "DIR",
-        description: "Select the repository that supplies contract ledgers.",
+        description: "Override the repository inferred from the effective directory. Needed only when the contract ledger lives in a different repository; the same value as -C is always redundant.",
     },
     contract: {
         kind: "value",
@@ -46,6 +46,10 @@ export const FLAG_SPECS = {
         placeholder: "DURATION",
         description: "Wait at most a positive duration such as 45s, 5m, or 2h (maximum 24h).",
     },
+    any: {
+        kind: "boolean",
+        description: "For a projection set, return when the first observed member reaches a terminal state.",
+    },
     wait: {
         kind: "value",
         placeholder: "DURATION",
@@ -57,7 +61,7 @@ export const FLAG_SPECS = {
     },
     bare: {
         kind: "boolean",
-        description: "Skip contract attachment; Akuma, history, sandbox, credentials, projection, and repository policy remain active.",
+        description: "Explicitly select standalone execution (also the default without --contract); history, sandbox, credentials, projection, and repository policy remain active.",
     },
     detach: {
         kind: "boolean",
@@ -119,6 +123,18 @@ export const FLAG_SPECS = {
         placeholder: "PATH",
         description: "Allow one explicit out-of-scope path for this seal. May be repeated.",
     },
+    resolve: {
+        kind: "boolean",
+        description: "Open a durable Keiyaku-owned renew recovery session when the rewrite conflicts.",
+    },
+    continue: {
+        kind: "boolean",
+        description: "Continue the open Keiyaku-owned renew recovery session.",
+    },
+    abort: {
+        kind: "boolean",
+        description: "Restore and remove the open Keiyaku-owned renew recovery session.",
+    },
     shell: {
         kind: "value",
         placeholder: "SHELL",

package/build/cli/help.js

@@ -1,11 +1,5 @@
-import { FlowError } from "../flow-error.js";
-import { allCommandMetadata, getCommandMetadata } from "./commands/registry.js";
-export function formatSubcommandList(subcommands) {
-    return subcommands.length < 2 ? (subcommands[0] ?? "") : `${subcommands.slice(0, -1).join(", ")} or ${subcommands.at(-1)}`;
-}
-export function missingSubcommandError(name, subcommands) {
-    return new FlowError("EMPTY_PARAM", `${name} requires subcommand: ${formatSubcommandList(subcommands)}`);
-}
+import { CLI_COMMAND_METADATA, getCommandMetadata } from "./commands/metadata.js";
+export { formatSubcommandList, missingSubcommandError } from "./missing-subcommand.js";
 function indent(lines) {
     return lines.map((line) => line ? `  ${line}` : "");
 }
@@ -21,15 +15,14 @@ function flagUsage(name, specs) {
     }
     return spec?.kind === "value" ? `--${name} ${spec.placeholder ?? "VALUE"}` : `--${name}`;
 }
-/** Metadata keyed by command; key order matches the historical CLI_COMMAND_METADATA object. */
-export const CLI_COMMAND_METADATA = Object.fromEntries(allCommandMetadata().map((meta) => [meta.command, meta]));
+export { CLI_COMMAND_METADATA };
 export function renderCliCommandHelp(_command, spec, flagSpecs) {
     const lines = ["Keiyaku command help", "", `${spec.command} - ${spec.summary}`, ""];
     section(lines, "Usage:", spec.usage);
     section(lines, "Purpose:", [spec.purpose]);
     section(lines, "Subcommands:", spec.subcommands);
     section(lines, "Input:", spec.input);
-    section(lines, "Options:", spec.flags.map((name) => `${flagUsage(name, flagSpecs)}  ${flagSpecs[name]?.description ?? ""}`));
+    section(lines, "Options:", spec.flags.map((name) => `${flagUsage(name, flagSpecs)}  ${spec.flagDescriptions?.[name] ?? flagSpecs[name]?.description ?? ""}`));
     section(lines, "Notes:", spec.notes);
     section(lines, "Examples:", spec.examples);
     return lines.join("\n").trimEnd();