@zq-silk/yui 0.0.0

package/dist/cli.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { renderCommandHelp } from "./cli/helpRenderer.js";
+import { routeInvocation } from "./cli/invocationRouter.js";
+import { renderCompletion } from "./cli/completion.js";
+import { resolveCompletionCandidates } from "./cli/dynamicCompletion.js";
+import { allowsInteractiveSelection, resolveInteractiveArguments } from "./cli/interactiveSelection.js";
+import { runCompletionWizard } from "./cli/completionWizard.js";
+import { resolveRoleWizardArguments } from "./cli/roleWizard.js";
+import { runUpdateCommand } from "./cli/updateCommand.js";
+import { runAgentCommand } from "./commands/agentCommands.js";
+import { runGlobalRoleCommand } from "./commands/globalRoleCommands.js";
+import { runJobCommand } from "./commands/jobCommands.js";
+import { runOperatorCommand } from "./commands/operatorCommands.js";
+import { runRepositoryCommand } from "./commands/repositoryCommands.js";
+import { runTaskCommand } from "./commands/taskCommands.js";
+import { FileCompletionManager, resolveCliIdentity } from "./completion/fileCompletionManager.js";
+import { callFileTaskController, ensureFileTaskController, FileTaskWorkflowRuntime, restartFileTaskController } from "./controller/clientRuntime.js";
+import { FileSchedulerStoreAdapter } from "./controller/fileSchedulerStoreAdapter.js";
+import { runSessionNotifyCommand } from "./controller/sessionNotify.js";
+import { runDoctorCommand } from "./doctor/doctor.js";
+import { CliError, usageError } from "./errors/cliError.js";
+import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
+import { FileTaskWorkspacePreparer } from "./repository/taskWorkspacePreparer.js";
+import { inspectStorageSchema, requireStorageSchema } from "./storage/storageSchema.js";
+import { FileTaskStore, resolveYuiHome } from "./storage/taskStore.js";
+import { runSetupCommand, validateSetupInvocation } from "./setup/setupCommand.js";
+import { NodeCommandExecutor } from "./tmux/commandExecutor.js";
+import { TmuxManager } from "./tmux/tmuxManager.js";
+const VERSION = readPackageVersion();
+const rawArgs = process.argv.slice(2);
+const jsonOutput = rawArgs.includes("--json");
+const args = normalizeAliases(jsonOutput ? rawArgs.filter((argument) => argument !== "--json") : rawArgs);
+void main().catch((error) => {
+    if (error instanceof CliError) {
+        const rendered = jsonOutput
+            ? JSON.stringify({ ok: false, code: error.code, message: error.message, details: {} })
+            : `${error.code}: ${error.message}${error.helpText === undefined ? "" : `\n\n${error.helpText.trimEnd()}`}`;
+        process.stderr.write(`${rendered}\n`);
+        process.exitCode = error.exitCode;
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${jsonOutput
+        ? JSON.stringify({ ok: false, code: "RUNTIME_ERROR", message, details: {} })
+        : `RUNTIME_ERROR: ${message}`}\n`);
+    process.exitCode = 5;
+});
+export async function main() {
+    if (args.length === 0) {
+        emit(renderCommandHelp((await import("./cli/commandCatalog.js")).ROOT_COMMAND, VERSION));
+        return;
+    }
+    if (args[0] === "version" && args.length === 1) {
+        emit(VERSION, true);
+        return;
+    }
+    const invocation = routeInvocation(args);
+    if (invocation.kind === "help") {
+        emit(renderCommandHelp(invocation.node, VERSION), true);
+        return;
+    }
+    if (invocation.kind === "path-error") {
+        throw usageError(`Unknown command: ${invocation.typedPath}`, renderCommandHelp(invocation.helpNode, VERSION));
+    }
+    if (invocation.kind === "incomplete") {
+        throw usageError(`Command required after: ${invocation.typedPath}`, renderCommandHelp(invocation.helpNode, VERSION));
+    }
+    if (args[0] === "version")
+        throw usageError("Version usage: yui version");
+    if (args[0] === "update") {
+        if (jsonOutput)
+            throw usageError("Update does not support --json.");
+        if (args.length !== 1)
+            throw usageError("Update usage: yui update");
+        process.exitCode = runUpdateCommand();
+        return;
+    }
+    const home = resolveYuiHome(process.env);
+    if (args[0] === "completion") {
+        await completionCommand(home, invocation.node);
+        return;
+    }
+    if (args[0] === "setup") {
+        if (jsonOutput)
+            throw usageError("Setup does not support --json.");
+        const setupIo = {
+            input: process.stdin,
+            output: process.stdout,
+            forceInteractive: process.env.YUI_SETUP_INTERACTIVE === "1"
+        };
+        validateSetupInvocation(args.slice(1), setupIo);
+        emit(await runSetupCommand(args.slice(1), process.env, new NodeCommandExecutor(), setupIo));
+        return;
+    }
+    if (args[0] === "doctor") {
+        emit(runDoctorCommand(args.slice(1), process.env, new NodeCommandExecutor()));
+        return;
+    }
+    if (args[0] === "internal") {
+        if (args[1] !== "session-notify" || args.length !== 3) {
+            throw usageError("Internal session notify usage is invalid.");
+        }
+        await runSessionNotifyCommand(args[2], process.env);
+        return;
+    }
+    requireStorageSchema(home);
+    const store = new FileTaskStore(home);
+    const resolved = await resolveTerminalArguments(args, invocation.node, store);
+    if (resolved === null) {
+        emit("Cancelled.");
+        return;
+    }
+    if (resolved[0] === "controller") {
+        const method = resolved[1];
+        if ((method !== "status" && method !== "stop" && method !== "restart") || resolved.length !== 2) {
+            throw usageError("Controller usage: yui controller status|stop|restart.");
+        }
+        const controllerMethod = method;
+        const result = controllerMethod === "restart"
+            ? await restartFileTaskController(home, { environment: process.env })
+            : await callFileTaskController(home, `controller.${controllerMethod}`);
+        emit(renderControllerResult(controllerMethod, result));
+        return;
+    }
+    const executor = new NodeCommandExecutor();
+    const tmux = new TmuxManager(process.env.YUI_TMUX_BIN ?? "tmux", executor, { yuiHome: home, terminalInput: process.stdin });
+    const schedulerStore = new FileSchedulerStoreAdapter(store);
+    const planner = new FileRoleLaunchPlanner(home, store, { environment: process.env });
+    const workspacePreparer = new FileTaskWorkspacePreparer(home, store);
+    const runtime = new FileTaskWorkflowRuntime(home, store, schedulerStore, planner, tmux, workspacePreparer, {
+        environment: process.env,
+        onError: (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Controller runtime error: ${message}\n`);
+        }
+    });
+    if (resolved[0] === "agent") {
+        emit(runAgentCommand(resolved.slice(1), store));
+        return;
+    }
+    if (resolved[0] === "repository") {
+        emit(await runRepositoryCommand(resolved.slice(1), store));
+        return;
+    }
+    if (resolved[0] === "role") {
+        const roleOptions = {
+            yuiHome: home,
+            env: process.env
+        };
+        const result = runGlobalRoleCommand(resolved.slice(1), store, roleOptions);
+        if (typeof result === "string") {
+            emit(result);
+            return;
+        }
+        await ensureFileTaskController(home, { environment: process.env });
+        runtime.prepareGlobalRoleEnter(result.role.name);
+        tmux.attachRole("operator", result.role.name);
+        return;
+    }
+    if (resolved[0] === "operator") {
+        if (resolved[1] === "enter") {
+            if (resolved.length !== 2)
+                throw usageError("Operator enter usage: yui operator enter.");
+            await ensureFileTaskController(home, { environment: process.env });
+            runtime.prepareGlobalRoleEnter("operator");
+            tmux.attachRole("operator", "operator");
+            return;
+        }
+        const result = runOperatorCommand(resolved.slice(1), store, { runtime, environment: process.env });
+        if (result.kind !== "output")
+            throw new Error("Operator submit returned an invalid control result.");
+        emit(result.output);
+        return;
+    }
+    if (resolved[0] === "task") {
+        const enteringTask = (resolved[1] === "enter")
+            || (resolved[1] === "role" && resolved[2] === "enter");
+        if (enteringTask) {
+            await ensureFileTaskController(home, { environment: process.env });
+            const taskId = resolved[1] === "enter" ? resolved[2] : resolved[3];
+            const task = taskId === undefined ? null : store.getTask(taskId);
+            if (task?.status === "active" && task.repositoryId !== undefined) {
+                await workspacePreparer.prepareTaskWorkspace(task.id);
+            }
+        }
+        const result = runTaskCommand(resolved.slice(1), store, { runtime, environment: process.env });
+        if (result.kind === "output") {
+            emit(result.output, false, result.data);
+            return;
+        }
+        if (result.output !== undefined)
+            emit(result.output);
+        tmux.attachRole(result.taskId, result.roleName);
+        return;
+    }
+    if (resolved[0] === "jobs") {
+        emit(runJobCommand(resolved.slice(1), store, { runtime }));
+        return;
+    }
+    throw usageError(`Command is not connected to the restored FileTaskStore framework yet: ${resolved[0]}.`, renderCommandHelp(invocation.node, VERSION));
+}
+function renderControllerResult(method, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return JSON.stringify(value);
+    }
+    const result = value;
+    if (method === "status") {
+        if (result.running !== true)
+            return "Controller is not running.";
+        return result.pid === undefined
+            ? "Controller is running."
+            : `Controller is running (PID ${String(result.pid)}).`;
+    }
+    if (method === "restart") {
+        const previousPid = Number.isSafeInteger(result.previousPid) ? String(result.previousPid) : undefined;
+        const pid = Number.isSafeInteger(result.pid) ? String(result.pid) : undefined;
+        if (previousPid !== undefined && pid !== undefined) {
+            return `Controller restarted (PID ${previousPid} -> ${pid}). tmux sessions were not stopped.`;
+        }
+        return pid === undefined
+            ? "Controller restarted. tmux sessions were not stopped."
+            : `Controller started (PID ${pid}). tmux sessions were not stopped.`;
+    }
+    return result.stopped === true
+        ? "Controller stopped."
+        : "Controller was already stopped.";
+}
+async function completionCommand(home, node) {
+    if (args[1] === "candidates") {
+        const separator = args.indexOf("--");
+        const prefix = args[2];
+        if (prefix === undefined || separator !== 3) {
+            throw usageError("Completion candidates usage: yui completion candidates <prefix> -- <words...>");
+        }
+        const candidates = await resolveCompletionCandidates({
+            current: prefix,
+            words: args.slice(separator + 1),
+            ports: completionSelectionPorts(home)
+        });
+        process.stdout.write(candidates.length === 0 ? "" : `${candidates.join("\n")}\n`);
+        return;
+    }
+    if (jsonOutput)
+        throw usageError("Completion configuration does not support --json.");
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        throw usageError("Completion configuration requires an interactive terminal.");
+    }
+    const shell = completionShell(args[1]);
+    if (args.length > (shell === undefined ? 1 : 2)) {
+        throw usageError("Completion usage: yui completion [bash|zsh|fish]");
+    }
+    requireStorageSchema(home);
+    const store = new FileTaskStore(home);
+    const ioHandle = terminalIo();
+    try {
+        const manager = new FileCompletionManager(store, process.env, resolveCliIdentity(process.env));
+        emit(await runCompletionWizard(manager, ioHandle.io, shell === undefined ? {} : { shell }));
+    }
+    finally {
+        ioHandle.close();
+    }
+    void node;
+}
+function completionShell(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "bash" || value === "zsh" || value === "fish")
+        return value;
+    throw usageError("Completion shell must be one of bash, zsh, fish.");
+}
+async function resolveTerminalArguments(commandArgs, node, store) {
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    if (!interactive || !allowsInteractiveSelection(commandArgs, jsonOutput)) {
+        return [...commandArgs];
+    }
+    const handle = terminalIo();
+    try {
+        const ports = selectionPorts(store);
+        // Global Role add owns its Agent choice so the configured default can be
+        // shown explicitly. Other commands first resolve missing positional
+        // targets through the generic selector, then enter the focused Role UI.
+        if ((commandArgs[0] === "role" && commandArgs[1] === "add")
+            || (commandArgs[0] === "task" && commandArgs[1] === "role" && commandArgs[2] === "add")) {
+            const wizard = await resolveRoleWizardArguments(commandArgs, ports, handle.io);
+            if (wizard.kind === "cancelled")
+                return null;
+            const selected = await resolveInteractiveArguments(wizard.args, node, ports, handle.io);
+            return selected.kind === "cancelled" ? null : selected.args;
+        }
+        const selected = await resolveInteractiveArguments(commandArgs, node, ports, handle.io);
+        if (selected.kind === "cancelled")
+            return null;
+        const wizard = await resolveRoleWizardArguments(selected.args, ports, handle.io);
+        return wizard.kind === "cancelled" ? null : wizard.args;
+    }
+    finally {
+        // The Agent process must be the only reader of stdin after Role enter.
+        handle.close();
+    }
+}
+function terminalIo() {
+    const readline = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    return {
+        io: {
+            interactive: true,
+            json: jsonOutput,
+            width: process.stdout.columns ?? 100,
+            write: (value) => { process.stdout.write(value); },
+            question: async (prompt) => {
+                try {
+                    return await readline.question(prompt);
+                }
+                catch (error) {
+                    if (error instanceof Error && (error.name === "AbortError"
+                        || ("code" in error && error.code === "ERR_USE_AFTER_CLOSE")))
+                        return undefined;
+                    throw error;
+                }
+            }
+        },
+        close: () => { readline.close(); }
+    };
+}
+function selectionPorts(store) {
+    return {
+        call: (method, params) => selectionCall(store, method, params)
+    };
+}
+function selectionCall(store, method, params) {
+    const reader = store;
+    switch (method) {
+        case "agent.list": return store.listConfiguredAgents();
+        case "config.get": return store.getConfig();
+        case "role.list": return store.listGlobalRoles();
+        case "role.show": return store.getGlobalRole(String(params.name ?? ""));
+        case "repository.list": return callOptional(reader, "listRepositories");
+        case "task.list": return callOptional(reader, "listTasks");
+        case "task.role.list": return callOptional(reader, "listRoles", [params.taskId]);
+        case "task.role.show": return callOptional(reader, "getRole", [params.taskId, params.roleName]);
+        case "task.work.list": return callOptional(reader, "listWorkItems", [params.taskId]);
+        case "task.input.list": {
+            const taskId = typeof params.taskId === "string" ? params.taskId : undefined;
+            const requests = taskId === undefined
+                ? store.listAllInputRequests()
+                : store.listInputRequests(taskId);
+            return params.all === true ? requests : requests.filter((request) => request.status === "open");
+        }
+        case "task.run.list": return callOptional(reader, "listAgentRuns", [params.workItemId]);
+        case "task.decision.list": return callOptional(reader, "listDecisions", [params.taskId]);
+        case "task.milestone.list": return callOptional(reader, "listMilestones", [params.taskId]);
+        case "task.event.list": return callOptional(reader, "listEvents", [params.taskId]);
+        case "jobs.list": return callOptional(reader, "listJobs");
+        default: return [];
+    }
+}
+function callOptional(reader, method, args = []) {
+    const operation = reader[method];
+    return operation === undefined ? [] : Reflect.apply(operation, reader, args);
+}
+function readableStore(home) {
+    requireStorageSchema(home);
+    return new FileTaskStore(home);
+}
+function completionSelectionPorts(home) {
+    if (inspectStorageSchema(home).status === "uninitialized") {
+        return { call: () => [] };
+    }
+    return selectionPorts(readableStore(home));
+}
+function emit(output, literal = false, data) {
+    const normalized = literal ? output.trimEnd() : output.trimEnd();
+    process.stdout.write(`${jsonOutput
+        ? JSON.stringify(data === undefined
+            ? { ok: true, output: normalized }
+            : { ok: true, data })
+        : normalized}\n`);
+}
+function readPackageVersion() {
+    try {
+        const value = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        if (typeof value.version === "string" && value.version.length > 0)
+            return value.version;
+    }
+    catch {
+        // Keep help/version available if package metadata is damaged.
+    }
+    return "0.0.0";
+}
+export function cliIdentity(env) {
+    return env.YUI_CLI_NAME === "yui-dev" ? "yui-dev" : "yui";
+}
+function normalizeAliases(input) {
+    const normalized = [...input];
+    if (normalized.length === 1 && (normalized[0] === "-v" || normalized[0] === "--version")) {
+        return ["version"];
+    }
+    const help = normalized.findIndex((argument) => argument === "-h" || argument === "--help");
+    return help === normalized.length - 1 ? ["help", ...normalized.slice(0, help)] : normalized;
+}
+export { renderCompletion };

package/dist/commands/agentCommands.js

@@ -0,0 +1,196 @@
+import { agentNotFound, usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { createConfiguredAgent } from "../agent/agent.js";
+const SUPPORTED_ADAPTERS = Object.freeze(["codex", "claude"]);
+export function runAgentCommand(args, store) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "add": return addAgent(rest, store);
+        case "list": return listAgents(rest, store);
+        case "show": return showAgent(rest, store);
+        case "update": return updateAgent(rest, store);
+        case "remove": return removeAgent(rest, store);
+        default:
+            throw usageError(command === undefined
+                ? "Agent command is required."
+                : `Unknown command: agent ${command}`);
+    }
+}
+function addAgent(args, store) {
+    const [rawId, ...tail] = args;
+    const id = agentId(rawId);
+    const parsed = parseAgentOptions(tail, "add");
+    const adapterId = parsed.one("--adapter") ?? (SUPPORTED_ADAPTERS.includes(id) ? id : undefined);
+    if (adapterId === undefined)
+        throw usageError("--adapter is required.");
+    assertAdapter(adapterId);
+    const command = parsed.one("--command")?.trim();
+    if (command === undefined || command.length === 0)
+        throw usageError("--command is required.");
+    let agent;
+    try {
+        agent = createConfiguredAgent(id, adapterId, command, parsed.many("--arg"), parsed.many("--env").map(parseEnvironmentBinding), new Date());
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+    const created = store.createConfiguredAgentIfAbsent(agent);
+    if (created === null) {
+        throw usageError(`Agent already exists: ${id}. Use yui agent update to change it.`);
+    }
+    return renderAgent(`Added agent ${id}`, created);
+}
+function listAgents(args, store) {
+    assertNoArguments(args, "Agent list usage: yui agent list");
+    const agents = store.listConfiguredAgents();
+    if (agents.length === 0)
+        return "No agents configured.\n";
+    return `${renderTable("Agents", [
+        { header: "Agent", minWidth: 5, maxWidth: 24 },
+        { header: "Adapter", minWidth: 7, maxWidth: 12 },
+        { header: "Command", minWidth: 7, maxWidth: 48 },
+        { header: "Environment", minWidth: 11, maxWidth: 32 }
+    ], agents.map((agent) => [
+        agent.id,
+        agent.adapterId,
+        [agent.command, ...agent.baseArgs].join(" "),
+        agent.environment.map((binding) => `${binding.target}<-${binding.sourceName}`).join(", ")
+    ]), defaultTableWidth())}\n`;
+}
+function showAgent(args, store) {
+    const [rawId, ...rest] = args;
+    const id = agentId(rawId);
+    assertNoArguments(rest, "Agent show usage: yui agent show <agent-id>");
+    const agent = store.getConfiguredAgent(id);
+    if (agent === null)
+        throw agentNotFound(id);
+    return renderAgent(`Agent: ${id}`, agent);
+}
+function updateAgent(args, store) {
+    const [rawId, ...tail] = args;
+    const id = agentId(rawId);
+    const parsed = parseAgentOptions(tail, "update");
+    if (parsed.seen.size === 0) {
+        throw usageError("Agent update requires at least one operational option.");
+    }
+    if (parsed.has("--arg") && parsed.has("--clear-args")) {
+        throw usageError("--arg and --clear-args cannot be used together.");
+    }
+    if (parsed.has("--env") && parsed.has("--clear-env")) {
+        throw usageError("--env and --clear-env cannot be used together.");
+    }
+    const adapterId = parsed.one("--adapter")?.trim();
+    if (adapterId !== undefined)
+        assertAdapter(adapterId);
+    const command = parsed.one("--command")?.trim();
+    if (command !== undefined && command.length === 0)
+        throw usageError("--command is required.");
+    const patch = {
+        ...(adapterId === undefined ? {} : { adapterId }),
+        ...(command === undefined ? {} : { command }),
+        ...(parsed.has("--arg")
+            ? { baseArgs: parsed.many("--arg") }
+            : parsed.has("--clear-args") ? { baseArgs: [] } : {}),
+        ...(parsed.has("--env")
+            ? { environment: parsed.many("--env").map(parseEnvironmentBinding) }
+            : parsed.has("--clear-env") ? { environment: [] } : {})
+    };
+    const result = store.updateConfiguredAgent(id, patch, new Date());
+    if (result === null)
+        throw agentNotFound(id);
+    return result.status === "unchanged"
+        ? `Agent ${id} unchanged\n`
+        : renderAgent(`Updated agent ${id}`, result.agent);
+}
+function removeAgent(args, store) {
+    const [rawId, ...rest] = args;
+    const id = agentId(rawId);
+    assertNoArguments(rest, "Agent remove usage: yui agent remove <agent-id>");
+    if (!store.removeConfiguredAgent(id))
+        throw agentNotFound(id);
+    return `Removed agent ${id}\n`;
+}
+function parseAgentOptions(args, mode) {
+    const valueOptions = new Map([
+        ["--adapter", { repeatable: false, allowOptionLikeValue: false }],
+        ["--command", { repeatable: false, allowOptionLikeValue: false }],
+        ["--arg", { repeatable: true, allowOptionLikeValue: true }],
+        ["--env", { repeatable: true, allowOptionLikeValue: false }]
+    ]);
+    const flags = mode === "update" ? new Set(["--clear-args", "--clear-env"]) : new Set();
+    const seen = new Set();
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index];
+        if (flags.has(option)) {
+            if (seen.has(option))
+                throw usageError(`Option may only be specified once: ${option}`);
+            seen.add(option);
+            continue;
+        }
+        const spec = valueOptions.get(option);
+        if (spec === undefined) {
+            throw usageError(option.startsWith("--")
+                ? `Unsupported option: ${option}`
+                : `Unexpected argument: ${option}`);
+        }
+        if (!spec.repeatable && seen.has(option)) {
+            throw usageError(`Option may only be specified once: ${option}`);
+        }
+        const value = args[index + 1];
+        if (value === undefined || (!spec.allowOptionLikeValue && value.startsWith("--"))) {
+            throw usageError(`${option} is required.`);
+        }
+        seen.add(option);
+        values.set(option, [...(values.get(option) ?? []), value]);
+        index += 1;
+    }
+    return {
+        seen,
+        has: (option) => seen.has(option),
+        one: (option) => values.get(option)?.[0],
+        many: (option) => [...(values.get(option) ?? [])]
+    };
+}
+function parseEnvironmentBinding(value) {
+    const separator = value.indexOf("=");
+    if (separator <= 0 || separator === value.length - 1) {
+        throw usageError("--env must use TARGET=PROCESS_NAME.");
+    }
+    const target = value.slice(0, separator).trim();
+    const sourceName = value.slice(separator + 1).trim();
+    if (!environmentName(target) || !environmentName(sourceName)) {
+        throw usageError("--env must use valid environment names: TARGET=PROCESS_NAME.");
+    }
+    return { target, source: "process", sourceName, required: true };
+}
+function environmentName(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function agentId(value) {
+    if (value === undefined || !/^[A-Za-z0-9_-]+$/.test(value.trim())) {
+        throw usageError(value === undefined || value.trim().length === 0
+            ? "Agent id is required."
+            : "Agent id may only contain letters, numbers, hyphens, and underscores.");
+    }
+    return value.trim();
+}
+function assertAdapter(value) {
+    if (!SUPPORTED_ADAPTERS.includes(value)) {
+        throw usageError(`Agent adapter is not supported: ${value}. Supported adapters: ${SUPPORTED_ADAPTERS.join(", ")}.`);
+    }
+}
+function assertNoArguments(args, message) {
+    if (args.length > 0)
+        throw usageError(`${message}. Unexpected argument: ${args[0]}`);
+}
+function renderAgent(title, agent) {
+    return [
+        title,
+        `Adapter: ${agent.adapterId}`,
+        `Executable: ${agent.command}`,
+        `Arguments: ${agent.baseArgs.join(" ")}`,
+        `Environment bindings: ${agent.environment.length}`,
+        ...agent.environment.map((binding) => `  ${binding.target} <- process:${binding.sourceName} (${binding.required ? "required" : "optional"})`)
+    ].join("\n").concat("\n");
+}