@zq-silk/yui 0.0.0

package/dist/cli/completion.js

@@ -0,0 +1,111 @@
+import { ROOT_COMMAND, listPublicCommandPaths, orderedImmediateTokens, visibleChildren } from "./commandCatalog.js";
+export function renderCompletion(shell, identity = "yui") {
+    const entries = collectEntries(ROOT_COMMAND);
+    switch (shell) {
+        case "bash": return renderBash(entries, identity);
+        case "zsh": return renderZsh(entries, identity);
+        case "fish": return renderFish(entries, identity);
+        default: throw new Error("Completion shell must be one of bash, zsh, fish.");
+    }
+}
+function collectEntries(root) {
+    const entries = [];
+    const visit = (node) => {
+        if (!node.hidden && !node.commandPathArguments) {
+            entries.push({
+                path: node.path.slice(1).join(" "),
+                immediate: orderedImmediateTokens(node),
+                options: node.options
+            });
+        }
+        visibleChildren(node).forEach(visit);
+    };
+    visit(root);
+    return entries;
+}
+function manifest(prefix) {
+    return listPublicCommandPaths().map((path) => `${prefix} ${path}`).join("\n");
+}
+function renderBash(entries, identity) {
+    const functionName = identity === "yui" ? "_yui" : "_yui_dev";
+    return `${manifest("# yui command:")}
+${functionName}() {
+  local current path dynamic_candidate
+  local -a candidates dynamic_candidates
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  path=""
+  if (( COMP_CWORD > 1 )); then
+    path="\${COMP_WORDS[*]:1:COMP_CWORD-1}"
+  fi
+  while IFS= read -r dynamic_candidate; do
+    [[ -n "$dynamic_candidate" ]] && dynamic_candidates+=("$dynamic_candidate")
+  done < <(command ${identity} completion candidates "$current" -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" 2>/dev/null)
+  if (( \${#dynamic_candidates[@]} > 0 )); then
+    candidates=("\${dynamic_candidates[@]}")
+  else
+    case "$path" in
+${entries.map((entry) => `      ${bashPattern(entry.path)}) candidates=(${[...entry.immediate, ...entry.options].map(shellQuote).join(" ")});;`).join("\n")}
+      *) candidates=();;
+    esac
+  fi
+  COMPREPLY=( $(compgen -W "\${candidates[*]}" -- "$current") )
+}
+complete -F ${functionName} ${identity}
+`;
+}
+function renderZsh(entries, identity) {
+    return `#compdef ${identity}
+${manifest("# yui command:")}
+local current path dynamic_output
+local -a candidates
+current="$words[CURRENT]"
+path=""
+if (( CURRENT > 2 )); then
+  path="\${(j: :)words[2,CURRENT-1]}"
+fi
+dynamic_output="$(command ${identity} completion candidates "$current" -- "\${(@)words[2,CURRENT-1]}" 2>/dev/null)"
+if [[ -n "$dynamic_output" ]]; then
+  candidates=("\${(@f)dynamic_output}")
+else
+  case "$path" in
+${entries.map((entry) => `    ${zshPattern(entry.path)}) candidates=(${[...entry.immediate, ...entry.options].map(shellQuote).join(" ")});;`).join("\n")}
+    *) candidates=();;
+  esac
+fi
+(( \${#candidates[@]} > 0 )) && compadd -- "$candidates[@]"
+`;
+}
+function renderFish(entries, identity) {
+    const lines = [
+        manifest("# yui command:"),
+        `function __${identity.replaceAll("-", "_")}_dynamic`,
+        `  ${identity} completion candidates (commandline -ct) -- (commandline -opc | string split ' ' | tail -n +2) 2>/dev/null`,
+        "end",
+        `complete -c ${identity} -f -a '(__${identity.replaceAll("-", "_")}_dynamic)'`
+    ];
+    for (const entry of entries) {
+        const candidates = [...entry.immediate, ...entry.options].join(" ");
+        if (candidates.length === 0)
+            continue;
+        const condition = entry.path.length === 0
+            ? "__fish_use_subcommand"
+            : `__fish_seen_subcommand_from ${entry.path.split(" ").map(fishQuote).join(" ")}`;
+        lines.push(`complete -c ${identity} -n '${condition}' -a '${escapeSingle(candidates)}'`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function bashPattern(path) {
+    return path.length === 0 ? '""' : shellQuote(path);
+}
+function zshPattern(path) {
+    return path.length === 0 ? '""' : shellQuote(path);
+}
+function shellQuote(value) {
+    return `'${escapeSingle(value)}'`;
+}
+function fishQuote(value) {
+    return `'${escapeSingle(value)}'`;
+}
+function escapeSingle(value) {
+    return value.replaceAll("'", "'\\''");
+}

package/dist/cli/completionWizard.js

@@ -0,0 +1,143 @@
+import { resolve } from "node:path";
+import { COMPLETION_SHELLS, activationBlock, shellQuote, } from "../completion/completionState.js";
+import { renderTable } from "../output/table.js";
+export class CompletionWizardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompletionWizardError";
+    }
+}
+export async function runCompletionWizard(port, io, options = {}) {
+    if (!io.interactive || io.json) {
+        throw new CompletionWizardError("Completion configuration requires an interactive terminal.");
+    }
+    const overview = await port.inspect();
+    const state = options.shell === undefined
+        ? await chooseShell(overview, io, options.defaultSelection ?? "current-shell")
+        : overview.states.find((candidate) => candidate.shell === options.shell);
+    if (state === undefined) {
+        return "Completion setup skipped.\n";
+    }
+    const decision = normalize(await io.question(`Selected: ${label(state.shell)} (${state.action})\n`
+        + `Script: ${state.installation.scriptPath}\n`
+        + `Startup: ${state.installation.activationPath}`
+        + `${activationIsAutomatic(state.shell, state.installation, state.suggested)
+            ? " (automatic)"
+            : " (managed startup block)"}\n`
+        + "Use these paths? [Y/n/customize]: "));
+    if (decision === "n" || decision === "no") {
+        return `Completion ${state.shell} setup skipped.\n`;
+    }
+    let installation = state.installation;
+    let customized = false;
+    if (decision === "customize") {
+        installation = await customizeInstallation(state.installation, io);
+        customized = true;
+    }
+    else if (decision !== "" && decision !== "y" && decision !== "yes") {
+        throw new CompletionWizardError("Choose Y, n, or customize.");
+    }
+    const automatic = activationIsAutomatic(state.shell, installation, state.suggested);
+    let activate = false;
+    let activationReady = automatic;
+    if (!automatic) {
+        const activationAnswer = normalize(await io.question(`${activationBlock(state.shell, installation, overview.identity)}\n`
+            + `Update ${installation.activationPath} with this managed Yui block? [Y/n]: `));
+        if (activationAnswer !== ""
+            && activationAnswer !== "y"
+            && activationAnswer !== "yes"
+            && activationAnswer !== "n"
+            && activationAnswer !== "no") {
+            throw new CompletionWizardError("Choose Y or n.");
+        }
+        activate = activationAnswer === ""
+            || activationAnswer === "y"
+            || activationAnswer === "yes";
+        activationReady = activate || (!customized && state.activationCurrent);
+    }
+    await port.install({ shell: state.shell, installation, activate });
+    if (!activationReady) {
+        return `Completion ${state.shell} script installed; startup activation still required.\n`;
+    }
+    const result = `Completion ${state.shell} ${pastTense(state.action)}.\n`;
+    return automatic
+        ? result
+        : `${result}${activationGuidance(state.shell, installation, state.suggested, overview)}`;
+}
+async function chooseShell(overview, io, defaultSelection) {
+    io.write(`${renderCompletionStateTable(overview.states, io.width)}\n\n`);
+    const defaultHint = defaultSelection === "skip"
+        ? " [skip]"
+        : overview.currentShell === undefined ? "" : ` [${overview.currentShell}]`;
+    const skipHint = defaultSelection === "skip" ? "" : " (or skip)";
+    const answer = normalize(await io.question(`Choose shell by number or name${defaultHint}${skipHint}: `));
+    if (answer === "skip" || (answer === "" && defaultSelection === "skip")) {
+        return undefined;
+    }
+    const shell = parseShell(answer, overview.currentShell);
+    const state = overview.states.find((candidate) => candidate.shell === shell);
+    if (state === undefined)
+        throw new CompletionWizardError("Completion shell is unavailable.");
+    return state;
+}
+function renderCompletionStateTable(states, width) {
+    return renderTable("Completion installation", [
+        { header: "#", minWidth: 1, maxWidth: 3 },
+        { header: "Shell", minWidth: 4, maxWidth: 6 },
+        { header: "Status", minWidth: 12, maxWidth: 13 },
+        { header: "Action", minWidth: 7, maxWidth: 7 },
+        { header: "Current", minWidth: 7, maxWidth: 7 },
+        { header: "Script", minWidth: 8, maxWidth: 88 }
+    ], states.map((state, index) => [
+        String(index + 1),
+        label(state.shell),
+        state.status,
+        state.action,
+        state.current ? "yes" : "",
+        state.installation.scriptPath
+    ]), width);
+}
+async function customizeInstallation(suggested, io) {
+    const scriptAnswer = (await io.question(`Completion script path [${suggested.scriptPath}]: `))?.trim() ?? "";
+    const activationAnswer = (await io.question(`Startup file path [${suggested.activationPath}]: `))?.trim() ?? "";
+    return Object.freeze({
+        scriptPath: resolve(scriptAnswer || suggested.scriptPath),
+        activationPath: resolve(activationAnswer || suggested.activationPath)
+    });
+}
+function parseShell(value, current) {
+    if (value.length === 0 && current !== undefined)
+        return current;
+    if (/^[1-3]$/.test(value)) {
+        return COMPLETION_SHELLS[Number.parseInt(value, 10) - 1];
+    }
+    if (COMPLETION_SHELLS.includes(value)) {
+        return value;
+    }
+    throw new CompletionWizardError("Choose Bash, Zsh, or Fish by number or name.");
+}
+function activationGuidance(shell, installation, suggested, overview) {
+    const unchanged = "The current shell is unchanged.\n";
+    if (installation.activationPath !== suggested.activationPath) {
+        return `${unchanged}Load the custom startup file from ${shell}: source ${shellQuote(installation.activationPath)}\n`;
+    }
+    return overview.currentShell === shell
+        ? `${unchanged}Restart the current shell to activate completion: exec ${shell}\n`
+        : `${unchanged}Switch this terminal to ${shell} to activate completion: exec ${shell}\n`;
+}
+function pastTense(action) {
+    switch (action) {
+        case "Install": return "installed";
+        case "Refresh": return "refreshed";
+        case "Repair": return "repaired";
+    }
+}
+function label(shell) {
+    return `${shell[0]?.toUpperCase() ?? ""}${shell.slice(1)}`;
+}
+function normalize(value) {
+    return value?.trim().toLowerCase() ?? "";
+}
+function activationIsAutomatic(shell, installation, suggested) {
+    return shell === "fish" && installation.scriptPath === suggested.scriptPath;
+}

package/dist/cli/dynamicCompletion.js

@@ -0,0 +1,48 @@
+import { findChild, ROOT_COMMAND, visibleChildren } from "./commandCatalog.js";
+import { getSelectionCandidates } from "./interactionCandidates.js";
+import { findInteractionPolicy } from "./interactionPolicy.js";
+export async function resolveCompletionCandidates(input) {
+    const words = input.words[0] === "yui" || input.words[0] === "yui-dev"
+        ? input.words.slice(1)
+        : [...input.words];
+    const { node, consumed } = resolveCommand(words);
+    if (consumed === words.length && node.children.length > 0) {
+        return prefix(visibleChildren(node).map((child) => child.name), input.current);
+    }
+    const previous = words.at(-1);
+    if (previous !== undefined && Object.hasOwn(node.optionValues, previous)) {
+        return prefix(node.optionValues[previous] ?? [], input.current);
+    }
+    if (input.current.startsWith("-")) {
+        return prefix(node.options, input.current);
+    }
+    const argumentPosition = words.length;
+    const policy = findInteractionPolicy(node);
+    const selector = policy?.selectors.find((candidate) => selectorApplies(candidate, previous, argumentPosition));
+    if (selector !== undefined) {
+        const set = await getSelectionCandidates(selector, input.ports, words);
+        return prefix(set?.candidates.map((candidate) => candidate.value) ?? [], input.current);
+    }
+    const relative = argumentPosition - (node.path.length - 1);
+    return prefix(node.argumentValues[relative] ?? [], input.current);
+}
+function selectorApplies(selector, previous, argumentPosition) {
+    if (selector.option !== undefined)
+        return selector.option === previous;
+    return selector.argumentIndex === argumentPosition;
+}
+function resolveCommand(words) {
+    let node = ROOT_COMMAND;
+    let consumed = 0;
+    while (consumed < words.length && node.kind !== "leaf") {
+        const child = findChild(node, words[consumed] ?? "");
+        if (child === undefined)
+            break;
+        node = child;
+        consumed += 1;
+    }
+    return { node, consumed };
+}
+function prefix(values, current) {
+    return [...new Set(values)].filter((value) => value.startsWith(current));
+}

package/dist/cli/helpRenderer.js

@@ -0,0 +1,32 @@
+import { visibleCommandSections } from "./commandCatalog.js";
+export function renderCommandHelp(node, version) {
+    const title = node.path.length === 1
+        ? `Yui ${version}`
+        : `Yui ${node.path.slice(1).join(" ")}`;
+    const lines = [title, ""];
+    if (node.summary.length > 0)
+        lines.push(node.summary, "");
+    lines.push("Usage:", ...node.usage.map((usage) => `  ${usage}`));
+    for (const section of visibleCommandSections(node)) {
+        const width = Math.max(...section.entries.map((entry) => entry.name.length));
+        lines.push("", `${section.title}:`, ...section.entries.map((entry) => `  ${entry.name.padEnd(width)}  ${entry.summary}`));
+    }
+    if (node.options.length > 0) {
+        const width = Math.max(...node.options.map((option) => option.length));
+        lines.push("", "Options:", ...node.options.map((option) => `  ${option.padEnd(width)}  ${describeOption(option)}`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function describeOption(option) {
+    const descriptions = {
+        "--agent": "Select an Agent.",
+        "--base": "Set the base Git reference.",
+        "--input": "Set dispatch input.",
+        "--json": "Emit machine-readable JSON.",
+        "--repository": "Select a repository.",
+        "--role": "Select a Task role.",
+        "--summary": "Set summary text.",
+        "--task": "Select a Task."
+    };
+    return descriptions[option] ?? `Set ${option.slice(2).replaceAll("-", " ")}.`;
+}

package/dist/cli/interactionCandidates.js

@@ -0,0 +1,139 @@
+import { orderRoleOptions } from "./roleOptionCatalog.js";
+export async function getSelectionCandidates(selector, ports, args) {
+    switch (selector.provider) {
+        case "tasks":
+            return entities("task", "Select task", (await list(ports, "task.list", {})).filter((task) => selector.statuses === undefined
+                || selector.statuses.includes(stringField(task, "status") ?? "")), ["id", "title", "status"]);
+        case "repositories":
+            return entities("repository", "Select repository", await list(ports, "repository.list", {}), ["id", "name", "path"]);
+        case "configured-agents": {
+            const agents = await list(ports, "agent.list", {});
+            const config = await optionalEntity(ports, "config.get", {});
+            const defaultValue = config === undefined
+                ? undefined
+                : stringField(config, "defaultAgent");
+            const set = entities("agent", "Select Agent", agents.map((agent) => ({
+                ...agent,
+                default: stringField(agent, "id") === defaultValue ? "default" : ""
+            })), ["id", "adapterId", "command", "default"]);
+            return { ...set, defaultValue };
+        }
+        case "global-roles":
+            return entities("global role", "Select global Role", await list(ports, "role.list", {}), ["name", "activeAgentId", "workspace"]);
+        case "jobs":
+            return entities("job", "Select job", await list(ports, "jobs.list", {}), ["id", "type", "status"]);
+        case "input-requests": {
+            const taskId = dependencyValue(selector, args);
+            return entities("input request", taskId === undefined ? "Select input request" : `Select input request: ${taskId}`, (await list(ports, "task.input.list", {
+                ...(taskId === undefined ? {} : { taskId }),
+                all: true
+            })).filter((request) => selector.statuses === undefined
+                || selector.statuses.includes(stringField(request, "status") ?? "")), ["id", "taskId", "status", "question"]);
+        }
+        case "task-roles": {
+            const taskId = dependencyValue(selector, args);
+            if (taskId === undefined)
+                return null;
+            const roles = orderRoleOptions(await list(ports, "task.role.list", { taskId }));
+            return entities("task role", `Select Task role: ${taskId}`, roles, ["name", "kind", "agentId"]);
+        }
+        case "task-decisions": {
+            const taskId = dependencyValue(selector, args);
+            if (taskId === undefined)
+                return null;
+            const decisions = (await list(ports, "task.decision.list", { taskId })).filter((decision) => selector.statuses === undefined
+                || selector.statuses.includes(stringField(decision, "status") ?? ""));
+            return entities("decision", `Select Decision: ${taskId}`, decisions, ["id", "status", "title"]);
+        }
+        case "task-milestones": {
+            const taskId = dependencyValue(selector, args);
+            if (taskId === undefined)
+                return null;
+            return entities("milestone", `Select Milestone: ${taskId}`, await list(ports, "task.milestone.list", { taskId }), ["id", "title", "createdAt"]);
+        }
+        case "task-events": {
+            const taskId = dependencyValue(selector, args);
+            if (taskId === undefined)
+                return null;
+            return entities("event", `Select Event: ${taskId}`, await list(ports, "task.event.list", { taskId }), ["id", "type", "createdAt"]);
+        }
+        case "work-items":
+            return entities("work item", "Select work item", await listAllWorkItems(ports), ["id", "title", "status"]);
+        case "runs":
+            return entities("run", "Select run", await listAllRuns(ports), ["id", "status", "workItemId"]);
+    }
+}
+async function listAllWorkItems(ports) {
+    const tasks = await list(ports, "task.list", {});
+    const groups = await Promise.all(tasks.flatMap((task) => {
+        const taskId = stringField(task, "id");
+        return taskId === undefined ? [] : [list(ports, "task.work.list", { taskId })];
+    }));
+    return groups.flat();
+}
+async function listAllRuns(ports) {
+    const workItems = await listAllWorkItems(ports);
+    const groups = await Promise.all(workItems.flatMap((item) => {
+        const workItemId = stringField(item, "id");
+        return workItemId === undefined ? [] : [list(ports, "task.run.list", { workItemId })];
+    }));
+    return groups.flat();
+}
+async function list(ports, method, params) {
+    const value = await ports.call(method, params);
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+}
+async function optionalEntity(ports, method, params) {
+    try {
+        const value = await ports.call(method, params);
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function dependencyValue(selector, args) {
+    if (selector.dependsOn === undefined)
+        return undefined;
+    const value = args[selector.dependsOn];
+    return value === undefined || value.startsWith("--") ? undefined : value;
+}
+function entities(label, title, input, fields) {
+    const valueField = fields[0] ?? "id";
+    const candidates = input.flatMap((entity) => {
+        const value = stringField(entity, valueField) ?? stringField(entity, "id");
+        if (value === undefined)
+            return [];
+        return [{ value, cells: fields.map((field) => displayField(entity[field])) }];
+    });
+    return {
+        entityLabel: label,
+        title,
+        columns: fields.map((field) => ({
+            header: heading(field),
+            minWidth: Math.min(12, Math.max(3, field.length)),
+            maxWidth: field === "title" || field === "path" ? 48 : 24
+        })),
+        candidates,
+        emptyMessage: `No ${label}s are available.`,
+        overflowHint: `Pass the ${label} explicitly.`
+    };
+}
+function stringField(entity, name) {
+    const value = entity[name];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function displayField(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return "";
+}
+function heading(field) {
+    return `${field[0]?.toUpperCase() ?? ""}${field.slice(1).replaceAll(/([A-Z])/g, " $1")}`;
+}