@zq-silk/yui 0.0.0

package/dist/commands/globalRoleCommands.js

@@ -0,0 +1,367 @@
+import { roleNotFound, usageError } from "../errors/cliError.js";
+import { createRoleSessionSet, recordRoleAgentSession } from "../executor/agentExecutor.js";
+import { resolveAgentAdapter } from "../executor/agentAdapter.js";
+import { resolveAgentEnvironment } from "../agent/agent.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { activeRoleSummary, renderRoleDetails } from "../output/rolePresentation.js";
+import { activeRoleAgentBinding, createGlobalRole, createRoleAgentBinding, switchActiveRoleAgent, updateGlobalRole } from "../role/role.js";
+import { isSystemRoleName, SYSTEM_ROLE_NAMES, systemRoleDescription } from "../role/systemRoles.js";
+import { hasAgentConfigOptions, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfileFrom, roleProfilePatch } from "./roleConfiguration.js";
+export function runGlobalRoleCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "add": return addRole(rest, store);
+        case "list": return listRoles(rest, store);
+        case "show": return showRole(rest, store);
+        case "update": return updateRole(rest, store);
+        case "remove": return removeRole(rest, store);
+        case "bind": return bindRole(rest, store);
+        case "enter": return enterRole(rest, store, options);
+        case "session": return roleSession(rest, store, options);
+        default:
+            throw usageError(command === undefined
+                ? "Role command is required."
+                : `Unknown command: role ${command}`);
+    }
+}
+function addRole(args, store) {
+    const [rawName, ...tail] = args;
+    const name = roleName(rawName);
+    const parsed = parseRoleOptions(tail, roleOptionSpecs({
+        update: false, includeAgent: true, includeWorkspace: true
+    }));
+    const agentId = required(parsed.one("--agent"), "--agent");
+    const agent = requireAgent(agentId, store);
+    if (parsed.has("--workspace") && trimmed(parsed.one("--workspace")) === undefined) {
+        throw usageError("--workspace is required.");
+    }
+    const workspace = trimmed(parsed.one("--workspace"))
+        ?? store.getConfig().defaultWorkspace
+        ?? process.cwd();
+    const binding = patchRoleAgentBinding(createRoleAgentBinding(definition(agent)), parsed);
+    const role = createGlobalRole(name, [binding], agent.id, workspace, new Date(), roleProfileFrom(parsed));
+    const created = store.createGlobalRoleIfAbsent(role);
+    if (created === null)
+        throw usageError(`Role already exists: ${name}.`);
+    return presentRole(`Added role ${name}`, created, store);
+}
+function listRoles(args, store) {
+    assertNoArguments(args, "Role list usage: yui role list");
+    const rows = new Map();
+    for (const name of SYSTEM_ROLE_NAMES) {
+        const role = store.getGlobalRole(name);
+        rows.set(name, role === null
+            ? [name, "system", "?", "?", "?", "?"]
+            : roleListRow(role, "system"));
+    }
+    for (const role of store.listGlobalRoles()) {
+        if (!rows.has(role.name)) {
+            rows.set(role.name, roleListRow(role, "global"));
+        }
+    }
+    if (rows.size === 0)
+        return "No roles configured.\n";
+    return `${renderTable("Roles", [
+        { header: "Role", minWidth: 4, maxWidth: 24 },
+        { header: "Kind", minWidth: 6, maxWidth: 8 },
+        { header: "Active Agent", minWidth: 8, maxWidth: 20 },
+        { header: "Model", minWidth: 8, maxWidth: 22 },
+        { header: "Effort", minWidth: 8, maxWidth: 14 },
+        { header: "Workspace", minWidth: 9, maxWidth: 54 }
+    ], [...rows.values()].sort((left, right) => left[0].localeCompare(right[0])), defaultTableWidth())}\n`;
+}
+function showRole(args, store) {
+    const [rawName, ...rest] = args;
+    const name = roleName(rawName);
+    assertNoArguments(rest, "Role show usage: yui role show <role>");
+    const role = store.getGlobalRole(name);
+    if (role === null) {
+        if (isSystemRoleName(name))
+            return renderMissingSystemRole(name);
+        throw roleNotFound(name);
+    }
+    return renderRoleDetails(`Role: ${name}`, role, {
+        kind: isSystemRoleName(name) ? "system" : "global",
+        sessions: store.getGlobalRoleSessionSet(name)
+    });
+}
+function updateRole(args, store) {
+    const [rawName, ...tail] = args;
+    const name = roleName(rawName);
+    const role = requireRole(name, store);
+    const parsed = parseRoleOptions(tail, roleOptionSpecs({
+        update: true, includeAgent: true, includeWorkspace: true
+    }));
+    if (parsed.has("--agent") && trimmed(parsed.one("--agent")) === undefined) {
+        throw usageError("--agent is required.");
+    }
+    if (parsed.has("--workspace") && trimmed(parsed.one("--workspace")) === undefined) {
+        throw usageError("--workspace is required.");
+    }
+    if ([...parsed.seen].every((option) => option === "--agent")) {
+        throw usageError("At least one role update option is required.");
+    }
+    const workspace = trimmed(parsed.one("--workspace"));
+    let bindings = role.agentBindings;
+    if (hasAgentConfigOptions(parsed)) {
+        const agentId = parsed.one("--agent")?.trim() || role.activeAgentId;
+        const agent = requireAgent(agentId, store);
+        const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
+        const activeSession = store.getGlobalRoleSessionSet(name)?.sessions[agentId];
+        if (agentId === role.activeAgentId && activeSession?.status === "running") {
+            throw usageError("Active Agent settings cannot be changed while its native process is running.");
+        }
+        bindings = { ...role.agentBindings, [agentId]: patchRoleAgentBinding(binding, parsed) };
+    }
+    const next = {
+        ...updateGlobalRole(role, {
+            ...(workspace === undefined ? {} : { workspace }),
+            ...(bindings === role.agentBindings ? {} : { agentBindings: bindings }),
+            ...roleProfilePatch(parsed)
+        }, new Date())
+    };
+    store.saveGlobalRole(next);
+    return renderRoleDetails(`Updated role ${name}`, next, {
+        kind: isSystemRoleName(name) ? "system" : "global",
+        sessions: store.getGlobalRoleSessionSet(name)
+    });
+}
+function bindRole(args, store) {
+    const [rawName, rawAgentId, ...rest] = args;
+    const name = roleName(rawName);
+    const agentId = required(rawAgentId, "Agent id");
+    assertNoArguments(rest, "Role bind usage: yui role bind <role> <agent-id>");
+    const role = requireRole(name, store);
+    const agent = requireAgent(agentId, store);
+    const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
+    const withBinding = updateGlobalRole(role, {
+        agentBindings: { ...role.agentBindings, [agentId]: binding }
+    }, new Date());
+    if (agentId === role.activeAgentId) {
+        store.saveGlobalRole(withBinding);
+        return presentRole(`Role ${name} already bound to ${agentId}`, withBinding, store);
+    }
+    const existingSet = store.getGlobalRoleSessionSet(name);
+    const activeSession = existingSet?.sessions[role.activeAgentId];
+    try {
+        const switched = switchActiveRoleAgent(withBinding, existingSet ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, new Date()), agentId, { activeRun: false, nativeProcessRunning: activeSession?.status === "running" }, new Date());
+        store.saveGlobalRoleWithSessionSet(switched.role, switched.sessions);
+        return presentRole(`Bound role ${name} to ${agentId}`, switched.role, store);
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
+function removeRole(args, store) {
+    const [rawName, ...rest] = args;
+    const name = roleName(rawName);
+    assertNoArguments(rest, "Role remove usage: yui role remove <role>");
+    if (isSystemRoleName(name))
+        throw usageError(`System role cannot be removed: ${name}`);
+    const role = requireRole(name, store);
+    const active = store.getGlobalRoleSessionSet(name)?.sessions[role.activeAgentId];
+    if (active?.status === "running") {
+        throw usageError(`GlobalRole is active and cannot be removed: ${name}.`);
+    }
+    if (!store.removeGlobalRole(name))
+        throw roleNotFound(name);
+    return `Removed role ${name}\n`;
+}
+function enterRole(args, store, options) {
+    const [rawName, ...rest] = args;
+    const name = roleName(rawName);
+    assertNoArguments(rest, "Role enter usage: yui role enter <role>");
+    const role = requireRole(name, store);
+    const agent = requireAgent(role.activeAgentId, store);
+    const set = store.getGlobalRoleSessionSet(name);
+    const session = set?.sessions[role.activeAgentId] ?? null;
+    const launch = compileGlobalRoleLaunch(role, agent, session?.nativeSessionId, options);
+    return { kind: "enter", role, launch };
+}
+function roleSession(args, store, options) {
+    const [command, rawName, ...tail] = args;
+    if (command !== "record" && command !== "replace") {
+        throw usageError("Role session usage: yui role session record|replace <role> --native-id <id> [--reason <reason>].");
+    }
+    const name = roleName(rawName);
+    const parsed = parseOptions(tail, new Map([
+        ["--native-id", false],
+        ...(command === "replace" ? [["--reason", false]] : [])
+    ]));
+    const nativeSessionId = required(parsed.one("--native-id"), "--native-id");
+    if (nativeSessionId.trim() !== nativeSessionId || nativeSessionId.length === 0) {
+        throw usageError("Native session id must not contain surrounding whitespace.");
+    }
+    const role = requireRole(name, store);
+    const binding = activeRoleAgentBinding(role);
+    const agent = requireAgent(binding.agentId, store);
+    const environment = options.env ?? process.env;
+    assertSessionProvenance(command, role, nativeSessionId, environment);
+    const set = store.getGlobalRoleSessionSet(name)
+        ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, new Date());
+    const existing = set.sessions[role.activeAgentId] ?? null;
+    const input = () => ({
+        agentId: binding.agentId,
+        adapterId: binding.adapterId,
+        nativeSessionId,
+        policy: "fixed",
+        status: environment.YUI_ROLE === name ? "running" : "ready"
+    });
+    if (command === "record") {
+        if (existing !== null && existing.nativeSessionId !== nativeSessionId) {
+            throw usageError("GlobalRole session replacement must be explicit.");
+        }
+        store.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input(), new Date()));
+        return `Recorded native session for role ${name}\n`;
+    }
+    if (existing === null) {
+        throw usageError("Native session replacement requires an existing native session.");
+    }
+    if (existing.status === "running") {
+        throw usageError("Native session replacement is blocked while the native Agent process is running.");
+    }
+    if (existing.nativeSessionId === nativeSessionId) {
+        throw usageError("Native session replacement requires a different native session identity.");
+    }
+    const reason = required(parsed.one("--reason"), "--reason").trim();
+    store.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input(), new Date()));
+    return `Replaced native session for role ${name}\n`;
+}
+function assertSessionProvenance(command, role, nativeSessionId, environment) {
+    const values = [
+        environment.YUI_ROLE,
+        environment.YUI_AGENT_ID,
+        environment.YUI_ADAPTER_ID
+    ];
+    if (values.every((value) => value === undefined))
+        return;
+    if (values.some((value) => value === undefined || value.trim().length === 0)) {
+        throw usageError("Native session registration provenance is incomplete.");
+    }
+    if (command !== "record") {
+        throw usageError("A running Agent may record only its current native session.");
+    }
+    const binding = activeRoleAgentBinding(role);
+    if (environment.YUI_ROLE !== role.name
+        || environment.YUI_AGENT_ID !== binding.agentId
+        || environment.YUI_ADAPTER_ID !== binding.adapterId) {
+        throw usageError("Native session registration does not match the active GlobalRole binding.");
+    }
+    if (binding.adapterId === "codex" && environment.CODEX_THREAD_ID?.trim() !== nativeSessionId) {
+        throw usageError("Native session id does not match CODEX_THREAD_ID.");
+    }
+}
+function parseOptions(args, specs) {
+    const values = new Map();
+    const seen = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index];
+        const kind = specs.get(option);
+        if (kind === undefined) {
+            throw usageError(option.startsWith("--")
+                ? `Unsupported option: ${option}`
+                : `Unexpected argument: ${option}`);
+        }
+        const repeatable = kind === true;
+        if (!repeatable && seen.has(option)) {
+            throw usageError(`Option may only be specified once: ${option}`);
+        }
+        seen.add(option);
+        if (kind === "flag")
+            continue;
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--"))
+            throw usageError(`${option} is required.`);
+        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 compileGlobalRoleLaunch(role, agent, nativeSessionId, options) {
+    const adapter = resolveAgentAdapter(agent.adapterId);
+    const input = {
+        agent: definition(agent),
+        config: activeRoleAgentBinding(role).config,
+        workspace: role.workspace,
+        systemPrompt: role.systemPrompt
+    };
+    const compiled = nativeSessionId === undefined
+        ? adapter.compileNew(input)
+        : adapter.compileResume({ ...input, nativeSessionId });
+    const baseEnvironment = options.env ?? process.env;
+    return {
+        command: agent.command,
+        args: compiled.argv,
+        env: stringEnvironment({
+            ...baseEnvironment,
+            ...resolveAgentEnvironment(definition(agent), baseEnvironment),
+            ...(options.yuiHome === undefined ? {} : { YUI_HOME: options.yuiHome }),
+            YUI_ROLE: role.name,
+            YUI_AGENT_ID: agent.id,
+            YUI_ADAPTER_ID: agent.adapterId,
+            YUI_WORKSPACE: role.workspace
+        })
+    };
+}
+function stringEnvironment(environment) {
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+}
+function definition(agent) {
+    return { ...agent, baseArgs: [...agent.baseArgs], environment: [...agent.environment], source: "custom" };
+}
+function requireAgent(id, store) {
+    const agent = store.getConfiguredAgent(id);
+    if (agent === null)
+        throw usageError(`Unsupported agent: ${id}`);
+    return agent;
+}
+function requireRole(name, store) {
+    const role = store.getGlobalRole(name);
+    if (role === null)
+        throw roleNotFound(name);
+    return role;
+}
+function roleName(value) {
+    if (value === undefined || value.trim().length === 0)
+        throw usageError("Role name is required.");
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw usageError("Role name may only contain letters, numbers, hyphens, and underscores.");
+    }
+    return value.trim();
+}
+function required(value, label) {
+    if (value === undefined || value.trim().length === 0)
+        throw usageError(`${label} is required.`);
+    return value.trim();
+}
+function trimmed(value) {
+    const result = value?.trim();
+    return result === undefined || result.length === 0 ? undefined : result;
+}
+function assertNoArguments(args, message) {
+    if (args.length > 0)
+        throw usageError(`${message}. Unexpected argument: ${args[0]}`);
+}
+function presentRole(title, role, store) {
+    return renderRoleDetails(title, role, {
+        kind: isSystemRoleName(role.name) ? "system" : "global",
+        sessions: store.getGlobalRoleSessionSet(role.name)
+    });
+}
+function roleListRow(role, kind) {
+    const summary = activeRoleSummary(role);
+    return [role.name, kind, summary.agent, summary.model, summary.effort, role.workspace];
+}
+function renderMissingSystemRole(name) {
+    return [
+        `Role: ${name}`,
+        `System: ${systemRoleDescription(name)}`,
+        "Active agent: ?",
+        "Workspace: ?"
+    ].join("\n").concat("\n");
+}

package/dist/commands/jobCommands.js

@@ -0,0 +1,100 @@
+import { runtimeError, taskNotFound, usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
+const WAKEUP_PREFIX = "leader-wakeup:";
+const RECOVERY_PREFIX = "leader-recovery:";
+/**
+ * A compatibility view over the two durable scheduler records. This does not
+ * reintroduce the deleted generic Job queue.
+ */
+export function runJobCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    if (command === "list")
+        return listJobs(rest, store);
+    if (command === "retry")
+        return retryJob(rest, store, options);
+    throw usageError(command === undefined
+        ? "Jobs command is required."
+        : `Unknown command: jobs ${command}`);
+}
+function listJobs(args, store) {
+    if (args.length !== 0)
+        throw usageError("Jobs list usage: yui jobs list.");
+    const jobs = collectJobs(store);
+    if (jobs.length === 0)
+        return "No scheduler jobs found.\n";
+    return `${renderTable("Scheduler jobs", [
+        { header: "Job", minWidth: 12, maxWidth: 44 },
+        { header: "Task", minWidth: 6, maxWidth: 20 },
+        { header: "Kind", minWidth: 12, maxWidth: 18 },
+        { header: "Status", minWidth: 6, maxWidth: 10 },
+        { header: "Updated", minWidth: 10, maxWidth: 28 },
+        { header: "Detail", minWidth: 8, maxWidth: 64 }
+    ], jobs.map((job) => [
+        job.id,
+        job.taskId,
+        job.kind,
+        job.status,
+        job.updatedAt,
+        job.detail
+    ]), defaultTableWidth())}\n`;
+}
+function collectJobs(store) {
+    const jobs = [];
+    for (const task of store.listTasks()) {
+        const wakeup = store.getPendingWakeup(task.id);
+        if (wakeup !== null) {
+            jobs.push({
+                id: `${WAKEUP_PREFIX}${task.id}`,
+                taskId: task.id,
+                kind: "leader-wakeup",
+                status: "pending",
+                detail: `${wakeup.reasons.join(", ")} (${wakeup.requestCount})`,
+                updatedAt: wakeup.lastRequestedAt
+            });
+        }
+        const failure = store.getLeaderFailure(task.id);
+        const notification = store.getOperatorNotification(task.id);
+        if (failure !== null || notification !== null) {
+            jobs.push({
+                id: `${RECOVERY_PREFIX}${task.id}`,
+                taskId: task.id,
+                kind: "leader-recovery",
+                status: "failed",
+                detail: failure?.message ?? notification?.message ?? "Leader recovery failed.",
+                updatedAt: failure?.lastFailedAt ?? notification?.updatedAt ?? task.updatedAt
+            });
+        }
+    }
+    return jobs.sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }));
+}
+function retryJob(args, store, options) {
+    if (args.length !== 1 || args[0].trim().length === 0) {
+        throw usageError("Jobs retry usage: yui jobs retry <id>.");
+    }
+    const id = args[0].trim();
+    if (!id.startsWith(RECOVERY_PREFIX) || id.length === RECOVERY_PREFIX.length) {
+        throw usageError(`Job is not retryable: ${id}. Only leader-recovery jobs can be retried.`);
+    }
+    const taskId = id.slice(RECOVERY_PREFIX.length);
+    const now = options.now?.() ?? new Date();
+    const runtime = options.runtime;
+    if (runtime === undefined)
+        throw runtimeError("Task workflow runtime is not configured.");
+    store.transaction((tx) => {
+        const task = tx.getTask(taskId);
+        if (task === null)
+            throw taskNotFound(taskId);
+        if (task.status !== "active") {
+            throw usageError(`Leader recovery can only be retried for an active Task: ${task.id}.`);
+        }
+        if (tx.getLeaderFailure(task.id) === null && tx.getOperatorNotification(task.id) === null) {
+            throw usageError(`Job not found: ${id}.`);
+        }
+        tx.clearLeaderFailure(task.id);
+        tx.clearOperatorNotification(task.id);
+        queueLeaderWakeup(tx, task.id, "recovery-retry", now);
+    });
+    runtime.notifyStateChanged(taskId);
+    return `Retry requested for ${id}\n`;
+}

package/dist/commands/operatorCommands.js

@@ -0,0 +1,38 @@
+import { usageError } from "../errors/cliError.js";
+import { submitOperatorMessage } from "./taskCommands.js";
+/** Operator is intentionally small: interactive entry is owned by the tmux CLI path. */
+export function runOperatorCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    if (command !== "submit") {
+        throw usageError(command === undefined
+            ? "Operator command is required."
+            : `Unknown command: operator ${command}`);
+    }
+    const usage = "Operator submit usage: yui operator submit <body> [--task <id>].";
+    const positionals = [];
+    let taskId;
+    for (let index = 0; index < rest.length; index += 1) {
+        const value = rest[index];
+        if (value !== "--task") {
+            if (value.startsWith("--"))
+                throw usageError(`Unsupported option: ${value}.`, usage);
+            positionals.push(value);
+            continue;
+        }
+        if (taskId !== undefined)
+            throw usageError("Option may only be specified once: --task.", usage);
+        const candidate = rest[index + 1];
+        if (candidate === undefined || candidate.startsWith("--")) {
+            throw usageError("--task is required.", usage);
+        }
+        taskId = candidate.trim();
+        index += 1;
+    }
+    if (positionals.length !== 1 || positionals[0].trim().length === 0) {
+        throw usageError(usage);
+    }
+    return {
+        kind: "output",
+        output: submitOperatorMessage(positionals[0], taskId, store, options)
+    };
+}

package/dist/commands/repositoryCommands.js

@@ -0,0 +1,86 @@
+import { usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
+import { createRepository } from "../repository/repository.js";
+export async function runRepositoryCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    if (command === "add")
+        return addRepository(rest, store, options);
+    if (command === "list")
+        return listRepositories(rest, store);
+    throw usageError(command === undefined
+        ? "Repository command is required."
+        : `Unknown command: repository ${command}`);
+}
+async function addRepository(args, store, options) {
+    const usage = "Repository add usage: yui repository add <name> <path> [--base <ref>].";
+    const parsed = parseAddArguments(args, usage);
+    const git = options.git ?? new NodeGitWorkspace();
+    const inspected = await git.inspect(parsed.path, parsed.baseRef ?? "HEAD");
+    const repository = createRepository(store.nextRepositoryId(), parsed.name, inspected.root, parsed.baseRef ?? inspected.baseRef, (options.now ?? (() => new Date()))());
+    if (store.listRepositories().some((entry) => entry.path === repository.path)) {
+        throw usageError(`Repository path is already registered: ${repository.path}.`);
+    }
+    const created = store.createRepositoryIfAbsent(repository);
+    if (created === null)
+        throw usageError(`Repository already exists: ${repository.name}.`);
+    return [
+        `Added repository ${created.id}`,
+        `Name: ${created.name}`,
+        `Path: ${created.path}`,
+        `Base: ${created.defaultBranch}`
+    ].join("\n").concat("\n");
+}
+function listRepositories(args, store) {
+    if (args.length !== 0) {
+        throw usageError("Repository list usage: yui repository list.");
+    }
+    const repositories = store.listRepositories();
+    if (repositories.length === 0)
+        return "No repositories found.\n";
+    return `${renderTable("Repositories", [
+        { header: "Repository", minWidth: 10, maxWidth: 24 },
+        { header: "Name", minWidth: 4, maxWidth: 28 },
+        { header: "Path", minWidth: 8, maxWidth: 64 },
+        { header: "Base", minWidth: 4, maxWidth: 24 }
+    ], repositories.map((repository) => [
+        repository.id,
+        repository.name,
+        repository.path,
+        repository.defaultBranch
+    ]), defaultTableWidth())}\n`;
+}
+function parseAddArguments(args, usage) {
+    const positionals = [];
+    let baseRef;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--base") {
+            if (baseRef !== undefined)
+                throw usageError(`--base may only be provided once. ${usage}`);
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--"))
+                throw usageError(`--base is required. ${usage}`);
+            baseRef = requireText(next, "--base");
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unknown option: ${value}. ${usage}`);
+        positionals.push(value);
+    }
+    if (positionals.length !== 2)
+        throw usageError(usage);
+    return {
+        name: requireText(positionals[0], "Repository name"),
+        path: requireText(positionals[1], "Repository path"),
+        ...(baseRef === undefined ? {} : { baseRef })
+    };
+}
+function requireText(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.includes("\0")) {
+        throw usageError(`${label} is required.`);
+    }
+    return normalized;
+}