@astrosheep/keiyaku 2.9.0 → 2.9.2

package/build/cli/commands/akuma/list/handler.js

@@ -5,7 +5,7 @@ import { textResponse } from "../../../render/shared.js";
 import { projectDirectory } from "../../shared.js";
 import { renderAkumaList } from "../../akuma.js";
 export const handler = async (_stdin, flags) => {
-    const cwd = await projectDirectory(flags);
+    const cwd = await projectDirectory(flags, "akuma ls");
     const loaded = await loadKeiyakuSettings(cwd);
     // Role markers need settings pointers; catalog consumers keep legacy agents disease actionable.
     assertSettingsKnobUsable(loaded, "agents");

package/build/cli/commands/akuma/view/handler.js

@@ -22,7 +22,7 @@ export const handler = async (_stdin, flags, _signal, positional) => {
     if (isResponseArtifactId(name)) {
         throw new FlowError("EMPTY_PARAM", `artifact ${name} is a response artifact; akuma view expects an Akuma profile name`);
     }
-    const cwd = await projectDirectory(flags);
+    const cwd = await projectDirectory(flags, "akuma view");
     const loaded = await loadKeiyakuSettings(cwd);
     assertSettingsKnobUsable(loaded, "agents");
     assertSettingsKnobUsable(loaded, "default");

package/build/cli/commands/contract/amend/handler.js

@@ -5,6 +5,6 @@ import { renderCoreResult } from "../../../render/shared.js";
 import { effectiveDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (stdin, flags) => {
     const parsed = buildAmendInput(stdin, effectiveDirectory(flags), flags.contractId, flags.contractAddressSource);
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "amend");
     return renderCoreResult(amendKeiyaku({ ...parsed, cwd }), buildAmendResponse);
 };

package/build/cli/commands/contract/arc/handler.js

@@ -4,6 +4,6 @@ import { renderCoreResult } from "../../../render/shared.js";
 import { effectiveDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (stdin, flags) => {
     const parsed = buildArcInput(stdin, effectiveDirectory(flags), flags.waivePaths, flags.contractId, flags.contractAddressSource);
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "arc");
     return renderCoreResult(arcKeiyaku({ ...parsed, cwd }), buildArcResponse);
 };

package/build/cli/commands/contract/bind/handler.js

@@ -7,7 +7,7 @@ export const handler = async (stdin, flags) => {
     if (flags.dryRun) {
         return textResponse(stdin);
     }
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "bind");
     if (flags.draftOnly) {
         return buildBindDraftResponse(await writeDraftArtifact({ cwd, title: "bind-draft", content: stdin }));
     }

package/build/cli/commands/contract/forfeit/handler.js

@@ -4,7 +4,7 @@ import { forfeitContractCommand } from "../../../../core/forfeit.js";
 import { buildForfeitResponse } from "../../../render/shared.js";
 import { repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags) => {
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "forfeit");
     const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
     return await withResolvedAddress(address, async () => buildForfeitResponse({
         ...await forfeitContractCommand({ cwd, contractId: address.binding.commissionId, ...defaultActorClock(), note: flags.reason }),

package/build/cli/commands/contract/log/handler.js

@@ -3,7 +3,7 @@ import { readContractLog } from "../../../../core/log.js";
 import { buildLogResponse } from "../../../render/misc.js";
 import { repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags) => {
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "log");
     const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
     return await withResolvedAddress(address, async () => {
         const result = await readContractLog({ cwd, contractId: address.binding.commissionId });

package/build/cli/commands/contract/petition/handler.js

@@ -9,7 +9,7 @@ export const handler = async (stdin, flags, signal) => {
     if (flags.json && !flags.dryRun) {
         throw new FlowError("EMPTY_PARAM", "petition --json requires --dry-run");
     }
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "petition");
     const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
     return await withResolvedAddress(address, async () => {
         const input = buildPetitionClaimInput({ cwd, contractId: address.binding.commissionId, stdin, signal, waivePaths: flags.waivePaths });

package/build/cli/commands/contract/renew/handler.js

@@ -4,7 +4,7 @@ import { buildRenewResponse } from "../../../render/arc.js";
 import { renderCoreResult } from "../../../render/shared.js";
 import { repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags) => {
-    const cwd = await repositoryDirectory(flags);
+    const cwd = await repositoryDirectory(flags, "renew");
     const address = await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource);
     return renderCoreResult(renewKeiyaku({ cwd, address, waivePaths: flags.waivePaths }), buildRenewResponse);
 };

package/build/cli/commands/projection/call/handler.js

@@ -3,7 +3,7 @@ import { projectionDir } from "../../../../core/projection-core.js";
 import { waitForProjection } from "../../../../core/projection-wait.js";
 import { buildCallResponse, renderAdoptedLaunchReceipt } from "../../../render/call.js";
 import { buildWaitResponse } from "../../../render/wait.js";
-import { buildCallInput, projectDirectory } from "../../shared.js";
+import { buildCallInput } from "../../shared.js";
 export const handler = async (stdin, flags, signal) => {
     const outcome = await runCallAndPersist({
         ...buildCallInput(stdin, flags, "call"),
@@ -22,8 +22,11 @@ export const handler = async (stdin, flags, signal) => {
         const projection = outcome.result.projection;
         if (!projection)
             throw new Error("call --wait requires projection facts after launch");
+        const projectionRoot = outcome.result.address.repo.kind === "repository"
+            ? outcome.result.address.repo.stableRoot
+            : flags.cwd ?? process.cwd();
         return buildWaitResponse(projection.id, await waitForProjection({
-            projectionDirectory: projectionDir(await projectDirectory(flags), projection.id),
+            projectionDirectory: projectionDir(projectionRoot, projection.id),
             timeoutMs: flags.timeoutMs,
             signal,
         }), { alias: projection.alias });

package/build/cli/commands/projection/kill/handler.js

@@ -8,7 +8,9 @@ import { textResponse } from "../../../render/shared.js";
 import { buildWaitResponse } from "../../../render/wait.js";
 import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags, signal, positional) => {
-    const cwd = flags.contractId ? await repositoryDirectory(flags) : await projectDirectory(flags);
+    const cwd = flags.contractId
+        ? await repositoryDirectory(flags, "kill contract addressing")
+        : await projectDirectory(flags, "kill");
     const [projectionAddress] = positional;
     if (!projectionAddress)
         throw new FlowError("EMPTY_PARAM", "kill requires a projection address");

package/build/cli/commands/projection/revive/handler.js

@@ -3,15 +3,18 @@ import { FlowError } from "../../../../flow-error.js";
 import { buildArtifactResolutionAttempt, } from "../../../../core/addressing.js";
 import { runCallAndPersist } from "../../../../core/call-persist.js";
 import { locateResponseArtifact, reconcileResponseArtifactCatalog, } from "../../../../core/transcripts.js";
-import { isGitRepo } from "../../../../git/branches.js";
+import { observeGitRepository } from "../../../../git/branches.js";
 import { stableRepoRoot } from "../../../../core/worktree-path.js";
 import { buildCallResponse } from "../../../render/call.js";
 import { buildCallInput, effectiveDirectory, projectDirectory, revivePrompt } from "../../shared.js";
 export const handler = async (stdin, flags, signal, positional) => {
     const cwd = effectiveDirectory(flags);
-    const artifactCwd = await projectDirectory(flags);
+    const artifactCwd = await projectDirectory(flags, "revive");
     const artifactId = positional[0];
-    const isRepo = await isGitRepo(artifactCwd);
+    const repository = await observeGitRepository(artifactCwd);
+    if (repository.capability === "unknown")
+        throw repository.error;
+    const isRepo = repository.capability === "available" && repository.coordinate === "repository";
     const responseStoreCwd = isRepo ? await stableRepoRoot(artifactCwd) : await fs.realpath(artifactCwd);
     try {
         await reconcileResponseArtifactCatalog(responseStoreCwd);

package/build/cli/commands/projection/status/handler.js

@@ -4,11 +4,13 @@ import { isProjectionId } from "../../../../core/projection-core.js";
 import { FlowError } from "../../../../flow-error.js";
 import { renderProjectionFilteredStatus, renderStatusBoard } from "../../../render/status.js";
 import { textResponse } from "../../../render/shared.js";
-import { projectDirectory } from "../../shared.js";
+import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags, _signal, positional) => {
     // Status is read-only and must open outside Git. projectDirectory still
     // honors --repo as a repository coordinate when the operator names one.
-    const cwd = await projectDirectory(flags);
+    const cwd = flags.target === undefined
+        ? await projectDirectory(flags, "status")
+        : await repositoryDirectory(flags, "status target filtering");
     const target = flags.target === undefined ? undefined : normalizeTargetRef(flags.target);
     const board = await readKanshiBoard(cwd, Date.now(), {
         ...(target === undefined ? {} : { target }),

package/build/cli/commands/projection/tell/handler.js

@@ -9,7 +9,9 @@ import { textResponse } from "../../../render/shared.js";
 import { buildWaitResponse } from "../../../render/wait.js";
 import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (body, flags, signal, positional) => {
-    const cwd = flags.contractId ? await repositoryDirectory(flags) : await projectDirectory(flags);
+    const cwd = flags.contractId
+        ? await repositoryDirectory(flags, "tell contract addressing")
+        : await projectDirectory(flags, "tell");
     const projectionAddress = positional[0];
     if (!projectionAddress)
         throw new FlowError("EMPTY_PARAM", "tell requires a projection address and message");

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

@@ -6,7 +6,9 @@ import { prependAddressReceipt } from "../../../render/address.js";
 import { buildWaitResponse } from "../../../render/wait.js";
 import { projectDirectory, repositoryDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags, signal, positional) => {
-    const cwd = flags.contractId ? await repositoryDirectory(flags) : await projectDirectory(flags);
+    const cwd = flags.contractId
+        ? await repositoryDirectory(flags, "wait contract addressing")
+        : await projectDirectory(flags, "wait");
     const address = flags.contractId ? await resolveContractAddress(cwd, flags.contractId, flags.contractAddressSource) : undefined;
     const operation = async () => {
         const projection = await resolveProjectionAddress({

package/build/cli/commands/shared.js

@@ -1,6 +1,6 @@
 import { FlowError } from "../../flow-error.js";
 import { AddressResolutionError, buildResolutionAttempt, } from "../../core/addressing.js";
-import { isGitRepo } from "../../git/branches.js";
+import { assertGitObservation, observeGitRepository } from "../../git/branches.js";
 import { stableRepoRoot } from "../../core/worktree-path.js";
 import { assertProjectionAlias } from "../../core/projection-alias.js";
 export function titleFromCallPrompt(prompt) {
@@ -44,9 +44,9 @@ export function revivePrompt(stdin) {
 export function effectiveDirectory(flags) {
     return flags.cwd ?? process.cwd();
 }
-export async function repositoryDirectory(flags) {
+export async function repositoryDirectory(flags, operation) {
     const candidate = flags.repo ?? effectiveDirectory(flags);
-    if (!(await isGitRepo(candidate))) {
+    if (assertGitObservation(await observeGitRepository(candidate), operation) === "non-repository") {
         if (flags.contractId) {
             const asTyped = flags.contractAddressSource === "at-address"
                 ? `@${flags.contractId}`
@@ -64,8 +64,8 @@ export async function repositoryDirectory(flags) {
     }
     return flags.repo ? await stableRepoRoot(candidate) : candidate;
 }
-export async function projectDirectory(flags) {
+export async function projectDirectory(flags, operation) {
     if (flags.repo)
-        return await repositoryDirectory(flags);
+        return await repositoryDirectory(flags, operation);
     return effectiveDirectory(flags);
 }

package/build/cli/commands/system/completion/handler.js

@@ -2,7 +2,7 @@ import { renderCompletionCandidates, renderCompletionScript } from "../../../com
 import { textResponse } from "../../../render/shared.js";
 import { projectDirectory } from "../../shared.js";
 export const handler = async (_stdin, flags) => {
-    const cwd = await projectDirectory(flags);
+    const cwd = await projectDirectory(flags, "completion");
     if (flags.complete) {
         return textResponse(await renderCompletionCandidates({ cwd, word: flags.word, previous: flags.previous }));
     }

package/build/cli/parse-flags.js

@@ -0,0 +1,197 @@
+import { FlowError } from "../flow-error.js";
+import { getCommandMetadata } from "./commands/registry.js";
+import { BOOLEAN_FLAGS, CONTROL_FLAGS, SHORT_FLAG_ALIASES, VALUE_FLAGS, } from "./flags.js";
+import { normalizeContractAddress, parseWaitTimeout } from "./parse-metadata.js";
+function allowedFlagsForParse(command) {
+    const meta = getCommandMetadata(command);
+    return meta.parseFlags ?? meta.flags;
+}
+export function parseFlagName(raw) {
+    return raw.slice(2);
+}
+export function assertAllowedFlag(command, name) {
+    if (!allowedFlagsForParse(command).includes(name)) {
+        throw new FlowError("EMPTY_PARAM", `option --${name} is not valid for ${command}`);
+    }
+}
+export function assignFlag(flags, name, value) {
+    switch (name) {
+        case "cwd":
+            flags.cwd = String(value);
+            return;
+        case "repo":
+            flags.repo = String(value);
+            return;
+        case "contract":
+            flags.contractId = normalizeContractAddress(String(value));
+            flags.contractAddressSource = "explicit-flag";
+            return;
+        case "akuma":
+            flags.akuma = String(value);
+            return;
+        case "projection":
+            flags.projection = String(value);
+            return;
+        case "alias":
+            flags.alias = String(value);
+            return;
+        case "timeout":
+        case "wait":
+            flags.timeoutMs = parseWaitTimeout(String(value));
+            return;
+        case "model":
+            flags.model = String(value);
+            return;
+        case "effort":
+            flags.effort = String(value);
+            return;
+        case "incognito":
+            flags.incognito = Boolean(value);
+            return;
+        case "bare":
+            flags.bare = Boolean(value);
+            return;
+        case "detach":
+            flags.detach = Boolean(value);
+            return;
+        case "draft-only":
+            flags.draftOnly = Boolean(value);
+            return;
+        case "exclusive":
+            flags.exclusive = Boolean(value);
+            return;
+        case "place":
+            if (flags.bindPlace !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --place may only be specified once");
+            }
+            flags.bindPlace = String(value);
+            return;
+        case "objective":
+            if (flags.bindObjective !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --objective may only be specified once");
+            }
+            flags.bindObjective = String(value);
+            return;
+        case "scope":
+            if (flags.bindScope !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --scope may only be specified once");
+            }
+            flags.bindScope = String(value);
+            return;
+        case "checks":
+            if (flags.bindChecks !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --checks may only be specified once");
+            }
+            flags.bindChecks = String(value);
+            return;
+        case "task":
+            if (flags.bindTaskId !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --task may only be specified once");
+            }
+            flags.bindTaskId = String(value);
+            return;
+        case "after":
+            flags.after = [...(flags.after ?? []), String(value)];
+            return;
+        case "force":
+            flags.force = Boolean(value);
+            return;
+        case "reason":
+            flags.reason = String(value);
+            return;
+        case "dry-run":
+            flags.dryRun = Boolean(value);
+            return;
+        case "waive":
+            flags.waivePaths = [...(flags.waivePaths ?? []), String(value)];
+            return;
+        case "shell":
+            flags.shell = String(value);
+            return;
+        case "word":
+            flags.word = String(value);
+            return;
+        case "previous":
+            flags.previous = String(value);
+            return;
+        case "complete":
+            flags.complete = Boolean(value);
+            return;
+        case "all":
+            flags.all = Boolean(value);
+            return;
+        case "target":
+            if (flags.target !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --target may only be specified once");
+            }
+            flags.target = String(value);
+            return;
+        case "json":
+            flags.json = Boolean(value);
+            return;
+        case "done":
+            flags.done = Boolean(value);
+            return;
+        case "pri": {
+            const raw = String(value);
+            if (!/^[0-3]$/.test(raw)) {
+                throw new FlowError("EMPTY_PARAM", "task priority must be an integer from 0 through 3");
+            }
+            if (flags.taskPri !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --pri may only be specified once");
+            }
+            flags.taskPri = Number(raw);
+            return;
+        }
+        case "needs":
+            flags.taskNeeds = [...(flags.taskNeeds ?? []), String(value)];
+            return;
+        case "drop-needs":
+            flags.taskDropNeeds = [...(flags.taskDropNeeds ?? []), String(value)];
+            return;
+        case "from":
+            flags.taskFrom = [...(flags.taskFrom ?? []), String(value)];
+            return;
+        case "parent":
+            if (flags.taskParent !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --parent may only be specified once");
+            }
+            flags.taskParent = String(value);
+            return;
+        case "no-parent":
+            flags.taskNoParent = Boolean(value);
+            return;
+        case "title":
+            if (flags.taskTitle !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --title may only be specified once");
+            }
+            flags.taskTitle = String(value);
+            return;
+        case "body":
+            if (flags.taskBody !== undefined) {
+                throw new FlowError("EMPTY_PARAM", "option --body may only be specified once");
+            }
+            flags.taskBody = String(value);
+            return;
+        default:
+            throw new FlowError("EMPTY_PARAM", `unknown option: --${name}`);
+    }
+}
+export function readValueFlag(name, token, eq, tokens, index) {
+    if (eq !== -1) {
+        const value = token.slice(eq + 1);
+        if (value === "" && name !== "target" && name !== "body") {
+            throw new FlowError("EMPTY_PARAM", `option --${name} requires a value`);
+        }
+        return { value, nextIndex: index };
+    }
+    const value = tokens[index + 1];
+    if (value === undefined || value === "--" || value.startsWith("--")) {
+        throw new FlowError("EMPTY_PARAM", `option --${name} requires a value`);
+    }
+    if (value === "" && name !== "target" && name !== "body") {
+        throw new FlowError("EMPTY_PARAM", `option --${name} requires a value`);
+    }
+    return { value, nextIndex: index + 1 };
+}
+export { BOOLEAN_FLAGS, CONTROL_FLAGS, SHORT_FLAG_ALIASES, VALUE_FLAGS };

package/build/cli/parse-metadata.js

@@ -0,0 +1,129 @@
+import { FlowError } from "../flow-error.js";
+import { HELP_FLAGS, SHORT_FLAG_ALIASES, VALUE_FLAGS } from "./flags.js";
+import { commandParseOrder, getCommandMetadata } from "./commands/registry.js";
+import { TASK_SUBCOMMANDS } from "./types.js";
+export function normalizeContractAddress(raw) {
+    const value = raw.startsWith("@") ? raw.slice(1) : raw;
+    if (!value.trim()) {
+        throw new FlowError("EMPTY_PARAM", "contract address cannot be empty");
+    }
+    return value.trim();
+}
+export function isCallCommand(command) {
+    return command === "call";
+}
+export function isPetitionDryRunInvocation(tokens) {
+    const boundary = tokens.indexOf("--");
+    const head = boundary === -1 ? tokens : tokens.slice(0, boundary);
+    if (!head.some((token) => token === "--dry-run" || token.startsWith("--dry-run="))) {
+        return false;
+    }
+    for (let index = 0; index < head.length; index += 1) {
+        const token = head[index];
+        if (HELP_FLAGS.has(token) || token.startsWith("@")) {
+            continue;
+        }
+        if (/^-[A-Za-z]$/.test(token)) {
+            const name = SHORT_FLAG_ALIASES[token.slice(1)];
+            if (name && VALUE_FLAGS.has(name)) {
+                index += 1;
+            }
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            const name = (eq === -1 ? token : token.slice(0, eq)).slice(2);
+            if (eq === -1 && VALUE_FLAGS.has(name)) {
+                index += 1;
+            }
+            continue;
+        }
+        return token === "petition";
+    }
+    return false;
+}
+export function commandUsesPromptInput(command) {
+    return isCallCommand(command) || command === "tell" || command === "revive";
+}
+export function parseWaitTimeout(value) {
+    const matched = /^(?<amount>[1-9][0-9]*)(?<unit>[smh])$/.exec(value);
+    if (!matched?.groups) {
+        throw new FlowError("EMPTY_PARAM", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
+    }
+    const amount = Number(matched.groups.amount);
+    const multiplier = matched.groups.unit === "s" ? 1_000 : matched.groups.unit === "m" ? 60_000 : 3_600_000;
+    const timeoutMs = amount * multiplier;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs > 24 * 3_600_000) {
+        throw new FlowError("EMPTY_PARAM", "wait timeout must use <positive integer><s|m|h>, for example 45s, 5m, or 2h (maximum 24h)");
+    }
+    return timeoutMs;
+}
+export function commandPositionalRange(command) {
+    if (command === "akuma view") {
+        return { min: 1, max: 1, label: "<name>" };
+    }
+    if (command === "log") {
+        return { min: 0, max: 0, label: "" };
+    }
+    if (isCallCommand(command)) {
+        return { min: 1, max: 1, label: "<BODY|->" };
+    }
+    if (command === "tell") {
+        return { min: 2, max: 2, label: "<PROJECTION> <BODY|->" };
+    }
+    if (command === "revive") {
+        return { min: 1, max: 2, label: "<ARTIFACT> [BODY|-]" };
+    }
+    if (command === "wait") {
+        return { min: 1, max: 1, label: "<projection-address>" };
+    }
+    if (command === "kill") {
+        return { min: 1, max: 1, label: "<projection-address>" };
+    }
+    if (command === "status") {
+        return { min: 0, max: 1, label: "[projection-id]" };
+    }
+    if (command === "task add") {
+        return { min: 1, max: 1, label: "<BODY|->" };
+    }
+    if (command === "task view" || command === "task start" || command === "task drop") {
+        return { min: 1, max: 1, label: "<ID>" };
+    }
+    if (command === "task update") {
+        return { min: 1, max: 1, label: "<ID>" };
+    }
+    if (command === "task stop" || command === "task done") {
+        return { min: 0, max: 1, label: "[ID]" };
+    }
+    return { min: 0, max: 0 };
+}
+export function commandRequiresStdin(command) {
+    return getCommandMetadata(command).stdin === "required";
+}
+export function resolveCommand(tokens) {
+    if (tokens[0] === "petition" && (tokens[1] === "claim" || tokens[1] === "forfeit")) {
+        throw new FlowError("UNKNOWN_COMMAND", `unknown command: petition ${tokens[1]}`);
+    }
+    for (const command of commandParseOrder()) {
+        const parts = command.split(" ");
+        if (parts.every((part, index) => tokens[index] === part)) {
+            return { command, rest: tokens.slice(parts.length) };
+        }
+    }
+    const [head] = tokens;
+    if (head === "skills") {
+        return { command: "skills", rest: tokens.slice(1) };
+    }
+    if (!head) {
+        throw new FlowError("EMPTY_PARAM", "command cannot be empty");
+    }
+    throw new FlowError("UNKNOWN_COMMAND", `unknown command: ${head ?? ""}`.trim());
+}
+export function splitAtLiteralBoundary(tokens) {
+    const boundary = tokens.indexOf("--");
+    if (boundary === -1) {
+        return { head: tokens, payload: [] };
+    }
+    return { head: tokens.slice(0, boundary), payload: tokens.slice(boundary + 1) };
+}
+export { TASK_SUBCOMMANDS };

package/build/cli/parse-selectors.js

@@ -0,0 +1,65 @@
+import { FlowError } from "../flow-error.js";
+import { assignFlag } from "./parse-flags.js";
+import { normalizeContractAddress } from "./parse-metadata.js";
+const COMMISSION_SELECTOR_COMMANDS = new Set([
+    "arc",
+    "amend",
+    "call",
+    "wait",
+    "tell",
+    "kill",
+    "log",
+    "renew",
+    "petition",
+    "forfeit",
+]);
+function formatSelectorList(items) {
+    if (items.length <= 1) {
+        return items[0] ?? "";
+    }
+    if (items.length === 2) {
+        return `${items[0]} and ${items[1]}`;
+    }
+    return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+export function applyCommissionSelector(command, flags, atTokens, contractFlagRaws) {
+    if (atTokens.length > 0 && contractFlagRaws.length > 0) {
+        throw new FlowError("EMPTY_PARAM", `commission address supplied twice: ${atTokens[0]} and --contract ${contractFlagRaws[0]}; use exactly one form`);
+    }
+    if (atTokens.length > 1) {
+        throw new FlowError("EMPTY_PARAM", `${command} accepts one commission address; got ${formatSelectorList(atTokens)}`);
+    }
+    if (contractFlagRaws.length > 1) {
+        throw new FlowError("EMPTY_PARAM", `${command} accepts one commission address; got ${formatSelectorList(contractFlagRaws.map((raw) => `--contract ${raw}`))}`);
+    }
+    if (atTokens.length === 1) {
+        flags.contractId = normalizeContractAddress(atTokens[0]);
+        flags.contractAddressSource = "at-address";
+    }
+    else if (contractFlagRaws.length === 1) {
+        assignFlag(flags, "contract", contractFlagRaws[0]);
+    }
+}
+export function assertCommissionSelectorAllowed(command, flags) {
+    if (flags.contractId === undefined || COMMISSION_SELECTOR_COMMANDS.has(command)) {
+        return;
+    }
+    throw new FlowError("EMPTY_PARAM", command === "bind"
+        ? `bind creates a commission and does not accept @${flags.contractId}; use -C/--cwd to select the repository`
+        : `contract address @${flags.contractId} is not valid for ${command}`);
+}
+export function assertProjectionSelectorPresent(command, flags, atTokens, contractFlagRaws, restLength, payloadLength) {
+    if ((command !== "wait" && command !== "tell") || flags.contractId === undefined) {
+        return;
+    }
+    const selectorSpelling = flags.contractAddressSource === "at-address"
+        ? atTokens[0] ?? `@${flags.contractId}`
+        : `--contract ${contractFlagRaws[0] ?? flags.contractId}`;
+    const message = `${command} requires a projection id or alias; ${selectorSpelling} only limits projection lookup, so add the projection address`;
+    if (command === "wait" && restLength + payloadLength === 0) {
+        throw new FlowError("EMPTY_PARAM", message);
+    }
+    if (command === "tell" && restLength === 0) {
+        throw new FlowError("EMPTY_PARAM", message);
+    }
+}