@zq-silk/yui 0.0.0

package/dist/commands/taskRoleRuntimeStatus.js

@@ -0,0 +1,152 @@
+export function inspectTaskRoleRuntimeStatuses(taskId, roles, store, panes) {
+    const taskOpenInputRequestCount = store.listInputRequests(taskId)
+        .filter((request) => request.status === "open").length;
+    const panesByRole = new Map();
+    for (const pane of panes) {
+        const current = panesByRole.get(pane.roleName);
+        if (current === undefined || current.dead && !pane.dead)
+            panesByRole.set(pane.roleName, pane);
+    }
+    return roles.map((role) => inspectTaskRoleRuntimeStatus(taskId, role, store, panesByRole.get(role.name), role.name === "leader" ? taskOpenInputRequestCount : 0));
+}
+export function renderTaskRoleRuntimeStatus(status) {
+    const activeRun = status.activeRun === null
+        ? "-"
+        : `${status.activeRun.id} (${status.activeRun.deliveredAt === undefined ? "queued" : "delivered"})`;
+    const activeWork = status.activeWork === null
+        ? "-"
+        : `${status.activeWork.id} (${status.activeWork.status}) ${status.activeWork.title}`;
+    const nativeSession = status.nativeSession === null
+        ? "not recorded"
+        : `${status.nativeSession.nativeSessionId} (${status.nativeSession.status}, ${status.nativeSession.adapterId})`;
+    const tmux = status.tmux.state === "missing"
+        ? "missing"
+        : [
+            status.tmux.state,
+            status.tmux.currentCommand === undefined ? undefined : `command=${status.tmux.currentCommand}`,
+            status.tmux.pid === undefined ? undefined : `pid=${status.tmux.pid}`,
+            status.tmux.target
+        ].filter((value) => value !== undefined).join(", ");
+    const workspaceDetails = status.workspace.managed
+        ? [
+            `  Repository       ${status.workspace.repositoryId}`,
+            `  Branch           ${status.workspace.branch}`,
+            `  Base             ${status.workspace.baseRef} (${status.workspace.baseCommit})`
+        ]
+        : [];
+    return [
+        `Task Role status: ${status.taskId}/${status.roleName}`,
+        "",
+        `  Health           ${status.health}`,
+        `  Reason           ${status.healthReason}`,
+        `  Open inputs      ${status.openInputRequestCount}`,
+        `  Agent            ${status.agentId}`,
+        `  Role state       ${status.role.status}`,
+        `  Active work      ${activeWork}`,
+        `  Active run       ${activeRun}`,
+        `  Native session   ${nativeSession}`,
+        `  tmux pane        ${tmux}`,
+        `  Workspace        ${status.workspace.path}`,
+        ...workspaceDetails
+    ].join("\n").concat("\n");
+}
+export function taskRoleActiveWorkLabel(status) {
+    if (status.activeWork !== null)
+        return `${status.activeWork.id}: ${status.activeWork.title}`;
+    return status.activeRun === null ? "-" : status.activeRun.id;
+}
+export function taskRoleNativeSessionLabel(status) {
+    return status.nativeSession?.status ?? "unbound";
+}
+export function taskRoleOpenInputLabel(status) {
+    return status.roleName === "leader" && status.openInputRequestCount > 0
+        ? String(status.openInputRequestCount)
+        : "-";
+}
+export function taskRoleTmuxLabel(status) {
+    if (status.tmux.state !== "running")
+        return status.tmux.state;
+    return status.tmux.currentCommand === undefined
+        ? "running"
+        : `running (${status.tmux.currentCommand})`;
+}
+function inspectTaskRoleRuntimeStatus(taskId, role, store, pane, openInputRequestCount) {
+    const activeRun = store.getActiveAgentRun(taskId, role.name);
+    const activeWork = activeRun?.workItemId === undefined
+        ? null
+        : store.getWorkItem(taskId, activeRun.workItemId);
+    const sessions = store.getTaskRoleSessionSet(taskId, role.name);
+    const nativeSession = sessions?.sessions[role.activeAgentId] ?? null;
+    const tmux = pane === undefined
+        ? { state: "missing" }
+        : {
+            state: pane.dead ? "exited" : "running",
+            target: pane.target,
+            dead: pane.dead,
+            ...(pane.pid === undefined ? {} : { pid: pane.pid }),
+            currentCommand: pane.currentCommand
+        };
+    const managedWorkspace = store.getRoleWorkspace(taskId, role.name);
+    const workspace = managedWorkspace === null
+        ? { managed: false, path: role.workspace }
+        : { ...managedWorkspace, managed: true };
+    const health = calculateHealth(role, activeRun, nativeSession, tmux, openInputRequestCount);
+    return {
+        taskId,
+        roleName: role.name,
+        agentId: role.activeAgentId,
+        ...health,
+        openInputRequestCount,
+        role,
+        activeRun,
+        activeWork,
+        nativeSession,
+        tmux,
+        workspace
+    };
+}
+function calculateHealth(role, activeRun, nativeSession, tmux, openInputRequestCount) {
+    if (role.status === "failed" || role.status === "exited") {
+        return { health: "failed", healthReason: `persisted Role state is ${role.status}` };
+    }
+    if (nativeSession?.status === "broken") {
+        return { health: "failed", healthReason: "the active native session is broken" };
+    }
+    if (tmux.state === "exited") {
+        return { health: "failed", healthReason: "the tmux pane has exited" };
+    }
+    if (activeRun !== null) {
+        if (role.status !== "running") {
+            return {
+                health: "needs-attention",
+                healthReason: `the active Run conflicts with persisted Role state ${role.status}`
+            };
+        }
+        if (activeRun.deliveredAt !== undefined && tmux.state !== "running") {
+            return { health: "needs-attention", healthReason: "the delivered active Run has no live tmux pane" };
+        }
+    }
+    if (activeRun === null && role.status === "running") {
+        return { health: "needs-attention", healthReason: "the Role is running without an active Run" };
+    }
+    if (nativeSession?.status === "running" && tmux.state !== "running") {
+        return { health: "needs-attention", healthReason: "the native session is running without a live tmux pane" };
+    }
+    if (nativeSession?.status === "stopped" && tmux.state === "running") {
+        return { health: "needs-attention", healthReason: "a stopped native session has a live tmux pane" };
+    }
+    if (role.name === "leader" && openInputRequestCount > 0) {
+        return {
+            health: "blocked-input",
+            healthReason: `${openInputRequestCount} open InputRequest${openInputRequestCount === 1 ? "" : "s"} require user input`
+        };
+    }
+    if (activeRun !== null) {
+        return activeRun.deliveredAt === undefined
+            ? { health: "starting", healthReason: "the active Run is awaiting tmux delivery" }
+            : { health: "running", healthReason: "the active Run has a live tmux pane" };
+    }
+    return tmux.state === "running"
+        ? { health: "ready", healthReason: "the native Agent pane is ready without active work" }
+        : { health: "idle", healthReason: "there is no active work or live tmux pane" };
+}

package/dist/completion/completionInstaller.js

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dataError } from "../errors/cliError.js";
+import { activationBlock, activationEnd, activationIsAutomatic, activationStart, completionMarker, managedCompletionScript } from "./completionState.js";
+export function installCompletion(store, shell, installation, env, identity, activate) {
+    validateInstallation(installation);
+    writeManagedScript(shell, installation.scriptPath, identity);
+    const config = store.getConfig();
+    store.saveConfig({
+        ...config,
+        completionInstallations: {
+            ...config.completionInstallations,
+            [shell]: installation
+        }
+    });
+    if (!activationIsAutomatic(shell, installation, env, identity) && activate) {
+        writeActivationBlock(shell, installation, identity);
+    }
+}
+export function uninstallCompletion(store, shell, identity) {
+    const config = store.getConfig();
+    const installation = config.completionInstallations?.[shell];
+    if (installation === undefined)
+        return;
+    assertManagedScriptRemovable(shell, installation.scriptPath, identity);
+    assertActivationRemovable(shell, installation, identity);
+    removeManagedScript(shell, installation.scriptPath, identity);
+    removeActivationBlock(shell, installation, identity);
+    const installations = { ...config.completionInstallations };
+    delete installations[shell];
+    store.saveConfig({
+        ...config,
+        completionInstallations: Object.keys(installations).length === 0
+            ? undefined
+            : installations
+    });
+}
+function assertManagedScriptRemovable(shell, path, identity) {
+    if (!existsSync(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isFile()
+        || stat.isSymbolicLink()
+        || !readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+        throw dataError(`Refusing to remove unmanaged completion script: ${path}`);
+    }
+}
+function assertActivationRemovable(shell, installation, identity) {
+    const path = installation.activationPath;
+    if (!existsSync(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw dataError(`Refusing to modify unsafe activation file: ${path}`);
+    }
+    const contents = readFileSync(path, "utf8");
+    const starts = occurrences(contents, activationStart(shell, identity));
+    const ends = occurrences(contents, activationEnd(shell, identity));
+    if (starts !== ends || starts > 1) {
+        throw dataError(`Refusing to remove ambiguous Yui activation block: ${path}`);
+    }
+}
+function writeManagedScript(shell, path, identity) {
+    if (existsSync(path)) {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw dataError(`Refusing to overwrite unsafe completion script: ${path}`);
+        }
+        if (!readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+            throw dataError(`Refusing to overwrite unmanaged completion script: ${path}`);
+        }
+    }
+    writeAtomic(path, managedCompletionScript(shell, identity), 0o644);
+}
+function writeActivationBlock(shell, installation, identity) {
+    const path = installation.activationPath;
+    let contents = "";
+    let mode = 0o644;
+    if (existsSync(path)) {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw dataError(`Refusing to modify unsafe activation file: ${path}`);
+        }
+        contents = readFileSync(path, "utf8");
+        mode = stat.mode & 0o777;
+    }
+    const start = activationStart(shell, identity);
+    const end = activationEnd(shell, identity);
+    const starts = occurrences(contents, start);
+    const ends = occurrences(contents, end);
+    if (starts > 1 || ends > 1 || starts !== ends) {
+        throw dataError(`Refusing to modify ambiguous Yui activation block: ${path}`);
+    }
+    const block = activationBlock(shell, installation, identity);
+    const next = starts === 1
+        ? replaceManagedBlock(contents, start, end, block)
+        : `${contents}${contents.length === 0 || contents.endsWith("\n") ? "" : "\n"}${block}\n`;
+    writeAtomic(path, next, mode);
+}
+function removeManagedScript(shell, path, identity) {
+    if (!existsSync(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isFile()
+        || stat.isSymbolicLink()
+        || !readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+        throw dataError(`Refusing to remove unmanaged completion script: ${path}`);
+    }
+    rmSync(path);
+}
+function removeActivationBlock(shell, installation, identity) {
+    const path = installation.activationPath;
+    if (!existsSync(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw dataError(`Refusing to modify unsafe activation file: ${path}`);
+    }
+    const contents = readFileSync(path, "utf8");
+    const start = activationStart(shell, identity);
+    const end = activationEnd(shell, identity);
+    const starts = occurrences(contents, start);
+    const ends = occurrences(contents, end);
+    if (starts !== ends || starts > 1) {
+        throw dataError(`Refusing to remove ambiguous Yui activation block: ${path}`);
+    }
+    if (starts === 0)
+        return;
+    const blockStart = contents.indexOf(start);
+    const blockEnd = contents.indexOf(end, blockStart) + end.length;
+    let next = `${contents.slice(0, blockStart)}${contents.slice(blockEnd)}`;
+    if (next.startsWith("\n"))
+        next = next.slice(1);
+    if (next.endsWith("\n\n"))
+        next = next.slice(0, -1);
+    writeAtomic(path, next, stat.mode & 0o777);
+}
+function writeAtomic(path, contents, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = join(dirname(path), `.${randomUUID()}.yui-pending`);
+    try {
+        writeFileSync(temp, contents, { mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function replaceManagedBlock(contents, start, end, block) {
+    const from = contents.indexOf(start);
+    const to = contents.indexOf(end, from);
+    if (from < 0 || to < from)
+        throw dataError("Invalid Yui activation block.");
+    return `${contents.slice(0, from)}${block}${contents.slice(to + end.length)}`;
+}
+function occurrences(contents, value) {
+    return contents.split(value).length - 1;
+}
+function validateInstallation(installation) {
+    if (!isAbsolute(installation.scriptPath) || !isAbsolute(installation.activationPath)) {
+        throw dataError("Completion script and activation paths must be absolute.");
+    }
+    if (resolve(installation.scriptPath) === resolve(installation.activationPath)) {
+        throw dataError("Completion script and activation paths must be different.");
+    }
+}

package/dist/completion/completionPort.js

@@ -0,0 +1 @@
+export {};

package/dist/completion/completionState.js

@@ -0,0 +1,137 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { renderCompletion } from "../cli/completion.js";
+import { dataError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+export const COMPLETION_SHELLS = Object.freeze(["bash", "zsh", "fish"]);
+export function currentCompletionShell(env) {
+    const value = basename(env.SHELL ?? "").toLowerCase();
+    return COMPLETION_SHELLS.includes(value)
+        ? value
+        : undefined;
+}
+export function suggestedCompletionInstallation(shell, env, identity) {
+    const home = absoluteEnvRoot("HOME", env.HOME);
+    if (shell === "bash") {
+        const data = env.XDG_DATA_HOME === undefined
+            ? join(home, ".local", "share")
+            : absoluteEnvRoot("XDG_DATA_HOME", env.XDG_DATA_HOME);
+        return {
+            scriptPath: join(data, "bash-completion", "completions", identity),
+            activationPath: join(home, ".bashrc")
+        };
+    }
+    if (shell === "zsh") {
+        const zshRoot = env.ZDOTDIR === undefined
+            ? home
+            : absoluteEnvRoot("ZDOTDIR", env.ZDOTDIR);
+        return {
+            scriptPath: join(zshRoot, ".zfunc", `_${identity}`),
+            activationPath: join(zshRoot, ".zshrc")
+        };
+    }
+    const config = env.XDG_CONFIG_HOME === undefined
+        ? join(home, ".config")
+        : absoluteEnvRoot("XDG_CONFIG_HOME", env.XDG_CONFIG_HOME);
+    return {
+        scriptPath: join(config, "fish", "completions", `${identity}.fish`),
+        activationPath: join(config, "fish", "config.fish")
+    };
+}
+export function inspectCompletionStates(config, env, identity) {
+    const current = currentCompletionShell(env);
+    return COMPLETION_SHELLS.map((shell) => {
+        const installation = config.completionInstallations?.[shell];
+        if (installation === undefined) {
+            return {
+                shell,
+                status: "Not installed",
+                action: "Install",
+                current: shell === current
+            };
+        }
+        const installed = completionScriptIsCurrent(shell, installation, identity)
+            && completionActivationIsCurrent(shell, installation, env, identity);
+        return {
+            shell,
+            status: installed ? "Installed" : "Needs repair",
+            action: installed ? "Refresh" : "Repair",
+            current: shell === current,
+            installation
+        };
+    });
+}
+export function renderCompletionStateTable(states, width = defaultTableWidth()) {
+    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),
+        shellLabel(state.shell),
+        state.status,
+        state.action,
+        state.current ? "yes" : "",
+        state.installation?.scriptPath ?? ""
+    ]), width);
+}
+export function managedCompletionScript(shell, identity) {
+    return `${completionMarker(shell, identity)}\n${renderCompletion(shell, identity)}`;
+}
+export function completionMarker(shell, identity) {
+    return `# yui-completion: managed shell=${shell} identity=${identity} format=1`;
+}
+export function activationBlock(shell, installation, identity) {
+    const start = activationStart(shell, identity);
+    const end = activationEnd(shell, identity);
+    const source = `source ${shellQuote(installation.scriptPath)}`;
+    const functionName = basename(installation.scriptPath);
+    const body = shell === "zsh"
+        ? `fpath=(${shellQuote(dirname(installation.scriptPath))} $fpath)\nautoload -Uz compinit\n(( $+functions[compdef] )) || compinit\nautoload -Uz -- ${shellQuote(functionName)}\ncompdef ${shellQuote(functionName)} ${shellQuote(identity)}`
+        : source;
+    return `${start}\n${body}\n${end}`;
+}
+export function activationStart(shell, identity) {
+    return `# >>> yui completion shell=${shell} identity=${identity} >>>`;
+}
+export function activationEnd(shell, identity) {
+    return `# <<< yui completion shell=${shell} identity=${identity} <<<`;
+}
+export function activationIsAutomatic(shell, installation, env, identity) {
+    return shell === "fish"
+        && installation.scriptPath === suggestedCompletionInstallation(shell, env, identity).scriptPath;
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function completionScriptIsCurrent(shell, installation, identity) {
+    return safeRegularFile(installation.scriptPath)
+        && readFileSync(installation.scriptPath, "utf8") === managedCompletionScript(shell, identity);
+}
+export function completionActivationIsCurrent(shell, installation, env, identity) {
+    if (activationIsAutomatic(shell, installation, env, identity))
+        return true;
+    if (!safeRegularFile(installation.activationPath))
+        return false;
+    const contents = readFileSync(installation.activationPath, "utf8");
+    const block = activationBlock(shell, installation, identity);
+    return contents.split(block).length === 2;
+}
+function safeRegularFile(path) {
+    if (!existsSync(path))
+        return false;
+    const stat = lstatSync(path);
+    return stat.isFile() && !stat.isSymbolicLink();
+}
+function absoluteEnvRoot(name, value) {
+    if (value === undefined || value.length === 0 || !isAbsolute(value)) {
+        throw dataError(`${name} must be an absolute path for completion installation.`);
+    }
+    return resolve(value);
+}
+function shellLabel(shell) {
+    return `${shell[0]?.toUpperCase() ?? ""}${shell.slice(1)}`;
+}

package/dist/completion/completionWizard.js

@@ -0,0 +1,125 @@
+import { resolve } from "node:path";
+import { usageError } from "../errors/cliError.js";
+import { installCompletion, uninstallCompletion } from "./completionInstaller.js";
+import { COMPLETION_SHELLS, activationBlock, activationIsAutomatic, currentCompletionShell, inspectCompletionStates, renderCompletionStateTable, shellQuote, suggestedCompletionInstallation } from "./completionState.js";
+export async function runCompletionWizard(operation, store, env, identity, question, options = {}) {
+    const states = inspectCompletionStates(store.getConfig(), env, identity);
+    const current = currentCompletionShell(env);
+    let shell;
+    if (options.shell === undefined) {
+        const defaultSelection = options.defaultSelection ?? "current-shell";
+        const defaultHint = defaultSelection === "skip"
+            ? " [skip]"
+            : current === undefined ? "" : ` [${current}]`;
+        const skipHint = defaultSelection === "skip" ? "" : " (or skip)";
+        const answer = await question(`${renderCompletionStateTable(states, options.width)}\n`
+            + `Choose shell by number or name${defaultHint}${skipHint}: `);
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === "skip" || (normalized.length === 0 && defaultSelection === "skip")) {
+            return `Completion ${operation} skipped.\n`;
+        }
+        shell = parseSelection(answer, current);
+    }
+    else {
+        shell = options.shell;
+    }
+    const state = states.find((candidate) => candidate.shell === shell);
+    if (state === undefined)
+        throw usageError("Completion shell selection is invalid.");
+    if (operation === "uninstall") {
+        if (state.installation === undefined) {
+            return `Completion ${shell} is not installed.\n`;
+        }
+        const confirm = normalize(await question(`Remove managed ${shell} completion?\n`
+            + `Script: ${state.installation.scriptPath}\n`
+            + `Activation: ${state.installation.activationPath}\n`
+            + "Remove now? [y/N]: "));
+        if (confirm !== "y" && confirm !== "yes") {
+            return `Completion ${shell} uninstall skipped.\n`;
+        }
+        uninstallCompletion(store, shell, identity);
+        return `Completion ${shell} uninstalled.\n`;
+    }
+    const suggested = state.installation
+        ?? suggestedCompletionInstallation(shell, env, identity);
+    const automatic = activationIsAutomatic(shell, suggested, env, identity);
+    const decision = normalize(await question(`Selected: ${shell} (${state.action})\n`
+        + `Script: ${suggested.scriptPath}\n`
+        + `Activation: ${suggested.activationPath}`
+        + `${automatic ? " (automatic)" : " (managed startup block)"}\n`
+        + "Install using these paths? [Y/n/customize]: "));
+    if (decision === "n" || decision === "no") {
+        return `Completion ${shell} installation skipped.\n`;
+    }
+    let installation = suggested;
+    let customized = false;
+    if (decision === "customize") {
+        const scriptPath = resolve((await question(`Completion script path [${suggested.scriptPath}]: `)).trim()
+            || suggested.scriptPath);
+        const activationPath = resolve((await question(`Activation file path [${suggested.activationPath}]: `)).trim()
+            || suggested.activationPath);
+        installation = { scriptPath, activationPath };
+        customized = true;
+    }
+    else if (decision !== "" && decision !== "y" && decision !== "yes") {
+        throw usageError("Choose Y, n, or customize.");
+    }
+    const needsActivation = !activationIsAutomatic(shell, installation, env, identity);
+    let activate = false;
+    let activationReady = !needsActivation;
+    if (needsActivation) {
+        const activationAnswer = normalize(await question(`${activationBlock(shell, installation, identity)}\n`
+            + `Update ${installation.activationPath} with the managed Yui block? [Y/n]: `));
+        if (activationAnswer !== ""
+            && activationAnswer !== "y"
+            && activationAnswer !== "yes"
+            && activationAnswer !== "n"
+            && activationAnswer !== "no") {
+            throw usageError("Choose Y or n.");
+        }
+        activate = activationAnswer === ""
+            || activationAnswer === "y"
+            || activationAnswer === "yes";
+        activationReady = activate || (!customized && state.status === "Installed");
+    }
+    installCompletion(store, shell, installation, env, identity, activate);
+    if (!activationReady) {
+        return `Completion ${shell} script installed; activation still required.\n`;
+    }
+    const result = `Completion ${shell} ${pastTense(state.action)}.\n`;
+    return needsActivation
+        ? `${result}${activationGuidance(shell, installation, env, identity)}`
+        : result;
+}
+function activationGuidance(shell, installation, env, identity) {
+    const unchanged = "The current shell is unchanged.\n";
+    const defaultActivationPath = suggestedCompletionInstallation(shell, env, identity).activationPath;
+    if (installation.activationPath !== defaultActivationPath) {
+        return `${unchanged}From a ${shell} session, load the custom activation file: source ${shellQuote(installation.activationPath)}\n`;
+    }
+    return currentCompletionShell(env) === 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 parseSelection(value, current) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0 && current !== undefined)
+        return current;
+    if (/^[1-3]$/.test(normalized)) {
+        return COMPLETION_SHELLS[Number.parseInt(normalized, 10) - 1];
+    }
+    if (COMPLETION_SHELLS.includes(normalized)) {
+        return normalized;
+    }
+    throw usageError("Choose Bash, Zsh, or Fish by number or name.");
+}
+function pastTense(action) {
+    switch (action) {
+        case "Install": return "installed";
+        case "Refresh": return "refreshed";
+        case "Repair": return "repaired";
+    }
+}
+function normalize(value) {
+    return value?.trim().toLowerCase() ?? "";
+}

package/dist/completion/fileCompletionManager.js

@@ -0,0 +1,51 @@
+import { installCompletion } from "./completionInstaller.js";
+import { COMPLETION_SHELLS, completionActivationIsCurrent, completionScriptIsCurrent, currentCompletionShell, suggestedCompletionInstallation } from "./completionState.js";
+/** FileTaskStore-backed completion port used by the interactive CLI wizard. */
+export class FileCompletionManager {
+    #store;
+    #env;
+    #identity;
+    constructor(store, env, identity) {
+        this.#store = store;
+        this.#env = { ...env };
+        this.#identity = identity;
+    }
+    inspect() {
+        const config = this.#store.getConfig();
+        const currentShell = currentCompletionShell(this.#env);
+        const states = COMPLETION_SHELLS.map((shell) => {
+            const suggested = suggestedCompletionInstallation(shell, this.#env, this.#identity);
+            const stored = config.completionInstallations?.[shell];
+            const installation = stored ?? suggested;
+            const scriptCurrent = completionScriptIsCurrent(shell, installation, this.#identity);
+            const activationCurrent = completionActivationIsCurrent(shell, installation, this.#env, this.#identity);
+            const status = scriptCurrent && activationCurrent
+                ? "Installed"
+                : stored === undefined ? "Not installed" : "Needs repair";
+            const action = status === "Installed"
+                ? "Refresh"
+                : status === "Needs repair" ? "Repair" : "Install";
+            return Object.freeze({
+                shell,
+                status,
+                action,
+                current: shell === currentShell,
+                configured: stored !== undefined,
+                activationCurrent,
+                installation,
+                suggested
+            });
+        });
+        return Object.freeze({
+            identity: this.#identity,
+            ...(currentShell === undefined ? {} : { currentShell }),
+            states: Object.freeze(states)
+        });
+    }
+    install(request) {
+        installCompletion(this.#store, request.shell, request.installation, this.#env, this.#identity, request.activate);
+    }
+}
+export function resolveCliIdentity(env) {
+    return env.YUI_CLI_NAME === "yui-dev" ? "yui-dev" : "yui";
+}

package/dist/config/yuiConfig.js

@@ -0,0 +1,17 @@
+export const DEFAULT_RECONCILIATION_INTERVAL_SECONDS = 30;
+export const MIN_RECONCILIATION_INTERVAL_SECONDS = 5;
+export const MAX_RECONCILIATION_INTERVAL_SECONDS = 300;
+/**
+ * Resolves the durable Yui setting used for periodic full reconciliation.
+ * Command-triggered scans remain immediate and do not use this interval.
+ */
+export function reconciliationIntervalMilliseconds(value) {
+    const seconds = value ?? DEFAULT_RECONCILIATION_INTERVAL_SECONDS;
+    if (typeof seconds !== "number"
+        || !Number.isSafeInteger(seconds)
+        || seconds < MIN_RECONCILIATION_INTERVAL_SECONDS
+        || seconds > MAX_RECONCILIATION_INTERVAL_SECONDS) {
+        throw new TypeError("reconciliationIntervalSeconds must be an integer from 5 to 300.");
+    }
+    return seconds * 1_000;
+}