@kisev/agentomatic 12.0.1-dev.130.g78ea8685c8d4 → 12.0.1-dev.132.g6d50bbe22d9e

package/dist/cli-output.d.ts

@@ -6,18 +6,22 @@ import type { DoctorReport } from "./doctor.js";
 import type { Scope } from "./lifecycle.js";
 type DisplayPlan = InstallerPlan | AgentProfilePlan;
 export declare function terminalSafe(value: string): string;
+export declare function colorEnabled(env?: NodeJS.ProcessEnv, isTTY?: boolean | undefined): boolean;
 export declare function renderPlan(plan: DisplayPlan, options: {
     applied: boolean;
     applyHint?: string;
     hint?: string;
+    color?: boolean;
 }): string;
+export declare function renderConfigNoop(plan: ConfigSetupPlan, color?: boolean): string;
 export declare function renderConfigSetup(plan: ConfigSetupPlan, options: {
     applied: boolean;
     applyHint?: string;
     hint?: string;
+    color?: boolean;
 }): string;
-export declare function renderCriticsTable(inventory: AgentInventory): string;
-export declare function renderFixedRoles(inventory: AgentInventory): string;
+export declare function renderCriticsTable(inventory: AgentInventory, color?: boolean): string;
+export declare function renderFixedRoles(inventory: AgentInventory, color?: boolean): string;
 export declare function renderInventory(inventory: AgentInventory): string;
 export declare function shellCommand(arguments_: readonly string[]): string;
 export declare function scopeArguments(scope: Scope): [] | ["--global"];

package/dist/cli-output.js

@@ -34,6 +34,36 @@ export function terminalSafe(value) {
     })
         .join("");
 }
+// ANSI styling is opt-in per call so tests can force either form; the CLI uses
+// the environment default, which disables color on non-TTY output and NO_COLOR.
+export function colorEnabled(env = process.env, isTTY = process.stdout.isTTY) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "")
+        return env.FORCE_COLOR !== "0";
+    return Boolean(isTTY);
+}
+function paint(color, code, text) {
+    return color && code ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+// One glyph per operation keeps the summary readable even with color off; the
+// matching ANSI code is applied only when color is enabled.
+const OPERATION_STYLES = {
+    create: { symbol: "▸", code: "32" },
+    update: { symbol: "●", code: "36" },
+    remove: { symbol: "■", code: "31" },
+    "archive-pending": { symbol: "■", code: "33" },
+    conflict: { symbol: "✗", code: "31" },
+    missing: { symbol: "✗", code: "33" },
+    unchanged: { symbol: "◻", code: "2" },
+};
+const MARKS = {
+    ok: "✓",
+    bad: "✗",
+    change: "▸",
+    item: "●",
+    pending: "◻",
+};
 function groupFor(path) {
     if (path.startsWith("agents/"))
         return "Agents";
@@ -53,10 +83,13 @@ function actionName(action) {
         reconcile: "Repair selected agents",
     }[action];
 }
-function operationSummary(operations) {
+function operationSummary(operations, color) {
     return OPERATIONS.map((operation) => {
         const count = operations.filter((item) => item.operation === operation).length;
-        return count ? `${operation} ${count}` : undefined;
+        if (!count)
+            return undefined;
+        const spec = OPERATION_STYLES[operation];
+        return paint(color, spec.code, `${spec.symbol} ${operation} ${count}`);
     })
         .filter(Boolean)
         .join(", ");
@@ -67,7 +100,7 @@ function shortPath(path, group) {
     const value = path.slice(path.indexOf("/") + 1);
     return terminalSafe(value.endsWith(".md") || value.endsWith(".js") ? value.slice(0, -3) : value);
 }
-function detailLines(operations) {
+function detailLines(operations, color) {
     const lines = [];
     for (const group of GROUPS) {
         const grouped = operations.filter((item) => groupFor(item.path) === group && item.operation !== "unchanged");
@@ -79,7 +112,8 @@ function detailLines(operations) {
                 : shortPath(item.path, group));
             const visible = operation === "conflict" ? values : values.slice(0, 8);
             const rest = values.length - visible.length;
-            lines.push(`  ${group}/${operation}: ${visible.join(", ")}${rest ? ` (+${rest} more)` : ""}`);
+            const spec = OPERATION_STYLES[operation];
+            lines.push(`  ${paint(color, spec.code, spec.symbol)} ${group}/${operation}: ${visible.join(", ")}${rest ? ` (+${rest} more)` : ""}`);
         }
     }
     return lines;
@@ -91,9 +125,10 @@ function migrationSummary(operations) {
         : undefined;
 }
 export function renderPlan(plan, options) {
+    const color = options.color ?? colorEnabled();
     const version = "package_version" in plan ? ` @kisev/agentomatic ${plan.package_version}` : "";
     const lines = [
-        `${actionName(plan.action)}${version} (${plan.scope})`,
+        paint(color, "1", `${actionName(plan.action)}${version} (${plan.scope})`),
         `Target: ${terminalSafe(plan.root)}`,
         ...("selection" in plan
             ? [
@@ -102,72 +137,88 @@ export function renderPlan(plan, options) {
             ]
             : []),
         "",
-        options.applied ? "Applied changes:" : "Planned changes:",
+        paint(color, "1", options.applied ? "Applied changes:" : "Planned changes:"),
     ];
     for (const group of GROUPS) {
         const operations = plan.operations.filter((item) => groupFor(item.path) === group);
         if (operations.length)
-            lines.push(`  ${group}: ${operationSummary(operations)}`);
+            lines.push(`  ${paint(color, "1", group)}: ${operationSummary(operations, color)}`);
     }
     const migration = migrationSummary(plan.operations);
     if (migration)
         lines.push(migration);
-    const details = detailLines(plan.operations);
+    const details = detailLines(plan.operations, color);
     if (details.length)
-        lines.push("", "Details:", ...details);
+        lines.push("", paint(color, "1", "Details:"), ...details);
     const conflicts = plan.operations.filter((item) => item.operation === "conflict").length;
-    lines.push("", `Conflicts: ${conflicts || "none"}`);
+    lines.push("", `Conflicts: ${conflicts ? paint(color, "31", `${MARKS.bad} ${conflicts}`) : paint(color, "32", `${MARKS.ok} none`)}`);
     const restartNote = "restart the host session so the deployed roles and settings load";
     lines.push(plan.requires_restart
-        ? `${options.applied ? "Restart required" : "Restart after apply"}: yes — ${restartNote}`
-        : `${options.applied ? "Restart required" : "Restart after apply"}: no`);
+        ? `${options.applied ? "Restart required" : "Restart after apply"}: ${paint(color, "33", `${MARKS.ok} yes`)} — ${restartNote}`
+        : `${options.applied ? "Restart required" : "Restart after apply"}: ${paint(color, "2", `${MARKS.pending} no`)}`);
     if (!options.applied && options.applyHint)
-        lines.push("", "Apply (repeat non-interactively):", `  ${options.applyHint}`);
+        lines.push("", paint(color, "1", "Apply (repeat non-interactively):"), `  ${options.applyHint}`);
     if (options.applied && options.hint)
-        lines.push("", "Next:", `  ${options.hint}`);
+        lines.push("", paint(color, "1", "Next:"), `  ${options.hint}`);
     return `${lines.join("\n")}\n`;
 }
+export function renderConfigNoop(plan, color = colorEnabled()) {
+    return [
+        paint(color, "1", `Integration configuration @kisev/agentomatic ${plan.package_version} (${plan.scope})`),
+        `Root: ${terminalSafe(plan.root)}`,
+        "",
+        paint(color, "32", `${MARKS.ok} No configuration changes are required.`),
+        "",
+    ].join("\n");
+}
 export function renderConfigSetup(plan, options) {
+    const color = options.color ?? colorEnabled();
     const lines = [
-        `Integration configuration @kisev/agentomatic ${plan.package_version} (${plan.scope})`,
+        paint(color, "1", `Integration configuration @kisev/agentomatic ${plan.package_version} (${plan.scope})`),
         `Root: ${terminalSafe(plan.root)}`,
         "",
     ];
     if (plan.targets.length)
-        lines.push("Targets:", ...plan.targets.map((item) => `  ${item.target}: ${terminalSafe(item.path)} (${item.exists ? "existing" : "new"})`));
+        lines.push(paint(color, "1", "Targets:"), ...plan.targets.map((item) => `  ${item.target}: ${terminalSafe(item.path)} ${paint(color, "2", `(${item.exists ? "existing" : "new"})`)}`));
     else
         lines.push("Targets: none");
     const fragments = plan.operations.filter((item) => item.fragment !== "file");
     if (plan.dependency)
         lines.push("", `Dependency: ${plan.dependency.status} ${plan.dependency.name}@${plan.dependency.version}`, "  Provisioning may access npm and update package.json, package-lock.json, and node_modules.");
     if (fragments.length) {
-        lines.push("", options.applied ? "Applied fragments:" : "Planned fragments:", ...fragments.map((item) => `  ${item.target}/${item.fragment}: ${item.operation}${item.reason ? ` (${terminalSafe(item.reason)})` : ""}`));
+        lines.push("", paint(color, "1", options.applied ? "Applied fragments:" : "Planned fragments:"), ...fragments.map((item) => {
+            const spec = OPERATION_STYLES[item.operation];
+            const badge = spec
+                ? `${paint(color, spec.code, spec.symbol)} `
+                : `${paint(color, "33", MARKS.change)} `;
+            return `  ${badge}${item.target}/${item.fragment}: ${item.operation}${item.reason ? ` (${terminalSafe(item.reason)})` : ""}`;
+        }));
     }
     if (plan.skipped_fragments.length)
-        lines.push("", "Skipped fragments:", ...plan.skipped_fragments.map((item) => `  ${item.fragment}: ${terminalSafe(item.reason)}`));
-    const conflicts = plan.operations.filter((item) => item.operation === "conflict");
-    lines.push("", `Conflicts: ${conflicts.length || "none"}`);
+        lines.push("", paint(color, "1", "Skipped fragments:"), ...plan.skipped_fragments.map((item) => `  ${item.fragment}: ${terminalSafe(item.reason)}`));
+    const conflicts = plan.operations.filter((item) => item.operation === "conflict").length;
+    lines.push("", `Conflicts: ${conflicts ? paint(color, "31", `${MARKS.bad} ${conflicts}`) : paint(color, "32", `${MARKS.ok} none`)}`);
     lines.push(plan.requires_restart
-        ? `${options.applied ? "Restart required" : "Restart after apply"}: yes — restart the host session so the merged presets load`
-        : `${options.applied ? "Restart required" : "Restart after apply"}: no`);
+        ? `${options.applied ? "Restart required" : "Restart after apply"}: ${paint(color, "33", `${MARKS.ok} yes`)} — restart the host session so the merged presets load`
+        : `${options.applied ? "Restart required" : "Restart after apply"}: ${paint(color, "2", `${MARKS.pending} no`)}`);
     if (!options.applied) {
         if (!plan.confirmable)
-            lines.push("", "No configuration changes are required.");
+            lines.push("", paint(color, "32", "No configuration changes are required."));
         else if (options.applyHint)
-            lines.push("", "Apply (repeat non-interactively):", `  ${options.applyHint}`);
+            lines.push("", paint(color, "1", "Apply (repeat non-interactively):"), `  ${options.applyHint}`);
     }
     if (options.applied && options.hint)
-        lines.push("", "Next:", `  ${options.hint}`);
+        lines.push("", paint(color, "1", "Next:"), `  ${options.hint}`);
     return `${lines.join("\n")}\n`;
 }
-function table(rows) {
+function table(rows, color = false) {
     const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column]?.length ?? 0)));
-    return rows.map((row) => row
+    return rows.map((row, index) => paint(color && index === 0, "1", row
         .map((value, column) => value.padEnd(widths[column]))
         .join("  ")
-        .trimEnd());
+        .trimEnd()));
 }
-export function renderCriticsTable(inventory) {
+export function renderCriticsTable(inventory, color = colorEnabled()) {
     // The panel keeps the package-owned fixed critic (`critic`) apart from the
     // additional `critic-*` pool entries and points at the canonical overview.
     const critics = inventory.profiles.filter((profile) => profile.ownership !== "user-owned" &&
@@ -178,31 +229,32 @@ export function renderCriticsTable(inventory) {
     const rows = [
         ["NAME", "MODEL", "VARIANT", "PROVIDER"],
         ...critics.map((profile) => [
-            terminalSafe(profile.name),
+            `${profile.name === "critic" ? MARKS.item : MARKS.change} ${terminalSafe(profile.name)}`,
             terminalSafe(profile.model ?? "default (host)"),
             terminalSafe(profile.variant ?? "-"),
             terminalSafe(profile.model?.split("/", 1)[0] ?? "-"),
         ]),
     ];
-    return (`Critics:\n${table(rows).join("\n")}\n` +
+    const head = paint(color, "1", "Critics:");
+    return (`${head}\n${table(rows, color).join("\n")}\n` +
         `Pool: additional critics are optional specialist profiles (` +
         `${pool.length ? pool.map((profile) => terminalSafe(profile.name)).join(", ") : "none"}); ` +
         "the fixed critic always deploys with the package.\n");
 }
-export function renderFixedRoles(inventory) {
+export function renderFixedRoles(inventory, color = colorEnabled()) {
     const roles = inventory.profiles.filter((profile) => profile.ownership !== "user-owned" &&
         FIXED_AGENT_ROLES.includes(profile.name));
     const rows = [
         ["NAME", "MODEL", "VARIANT"],
         ...roles.map((profile) => [
-            terminalSafe(profile.name),
+            `${MARKS.item} ${terminalSafe(profile.name)}`,
             terminalSafe(profile.model ?? "default (host)"),
             terminalSafe(profile.variant ?? "-"),
         ]),
     ];
     return [
-        "Fixed roles (all six belong to the package; models and critic composition: agentomatic configure agent):",
-        ...table(rows),
+        paint(color, "1", "Fixed roles (all six belong to the package; models and critic composition: agentomatic configure agent):"),
+        ...table(rows, color),
         "",
     ].join("\n");
 }

package/dist/command-cli.js

@@ -9,8 +9,8 @@ import { CATALOG } from "./catalog.js";
 import { skillsInstallerSpec } from "./package-metadata.js";
 import { LifecycleError } from "./lifecycle.js";
 import { previewDependencyRemoval, removeDependency, planDependency } from "./self-install.js";
-import { selectOption, selectOptions, promptText, confirmQuestion } from "./terminal-wizard.js";
-import { renderPlan, renderInventory, renderCriticsTable, renderFixedRoles, renderDoctor, renderConfigSetup, renderReconcile, terminalSafe, shellCommand, scopeArguments, } from "./cli-output.js";
+import { selectOption, selectOptions, promptText, confirmQuestion, runWizard, isBack, } from "./terminal-wizard.js";
+import { renderPlan, renderInventory, renderCriticsTable, renderFixedRoles, renderDoctor, renderConfigSetup, renderConfigNoop, renderReconcile, terminalSafe, shellCommand, scopeArguments, } from "./cli-output.js";
 let diagnostics;
 let machineOutput = false;
 let diagnosticJSON = false;
@@ -304,7 +304,21 @@ function conflicts(operations) {
     if (blocked.length)
         fail("conflict", `Plan blocked; preserved paths: ${blocked.map((operation) => operation.path).join(", ")}. Inspect doctor; restore recorded bytes or resolve ownership before retrying.`);
 }
-async function integrationSelection(options, presetsOnly = false) {
+const CONNECTION_CHOICES = [
+    "Keep current connection",
+    "Connect and pin this package version",
+    "Disconnect agentomatic",
+];
+function presetFragments(targets, filter) {
+    return CONFIG_FRAGMENTS.filter((fragment) => !["core-plugin", "core-disable"].includes(fragment.name) &&
+        fragment.targets.some((target) => targets.includes(target)) &&
+        (!filter || filter.has(fragment.name))).map((fragment) => fragment.name);
+}
+function applicablePresets(fragments, targets) {
+    return fragments.filter((name) => !["core-plugin", "core-disable"].includes(name) &&
+        CONFIG_FRAGMENTS.find((fragment) => fragment.name === name)?.targets.some((target) => targets.includes(target)));
+}
+async function integrationSelection(options, presetsOnly = false, filter) {
     if (options.targets !== undefined || options.fragments !== undefined) {
         if (options.targets === undefined || options.fragments === undefined)
             fail("invalid_input", "Supply both --targets and --fragments");
@@ -314,30 +328,60 @@ async function integrationSelection(options, presetsOnly = false) {
         });
     }
     const defaults = await defaultConfigSelection(options.scope);
-    const targets = value(await selectOptions("Agent harnesses to configure", options.scope === "project" ? ["opencode"] : CONFIG_TARGETS, defaults.targets, CONFIG_TARGETS.map((target) => TARGET_DESCRIPTIONS[target])));
-    if (!targets.length)
-        return { targets, fragments: [] };
+    const scopedTargets = options.scope === "project" ? ["opencode"] : [...CONFIG_TARGETS];
+    const targetChoices = filter?.targets
+        ? scopedTargets.filter((target) => filter.targets.includes(target))
+        : scopedTargets;
+    const fragmentFilter = filter?.fragments ? new Set(filter.fragments) : undefined;
+    const steps = [
+        {
+            run: async (state, back) => {
+                const result = await selectOptions("Agent harnesses to configure", targetChoices, state.targets.filter((target) => targetChoices.includes(target)), targetChoices.map((target) => TARGET_DESCRIPTIONS[target]), process.stdin, process.stderr, back);
+                if (isBack(result))
+                    return result;
+                return { ...state, targets: value(result) };
+            },
+        },
+        {
+            enabled: (state) => !presetsOnly && state.targets.includes("opencode") && (filter?.connection ?? true),
+            run: async (state, back) => {
+                const result = await selectOption("OpenCode plugin connection", CONNECTION_CHOICES, process.stdin, process.stderr, state.connection, undefined, back);
+                if (isBack(result))
+                    return result;
+                return { ...state, connection: value(result) };
+            },
+        },
+        {
+            enabled: (state) => presetFragments(state.targets, fragmentFilter).length > 0,
+            run: async (state, back) => {
+                const available = presetFragments(state.targets, fragmentFilter);
+                const result = await selectOptions("Application presets to merge", available, state.fragments.filter((fragment) => available.includes(fragment)), available.map((name) => CONFIG_FRAGMENTS.find((fragment) => fragment.name === name)?.description), process.stdin, process.stderr, back);
+                if (isBack(result))
+                    return result;
+                return { ...state, fragments: value(result) };
+            },
+        },
+    ];
+    const state = await runWizard({
+        targets: filter?.targets ? [...filter.targets] : defaults.targets,
+        connection: 0,
+        fragments: filter?.fragments
+            ? [...filter.fragments]
+            : applicablePresets(defaults.fragments, defaults.targets),
+    }, steps);
+    if (!state.targets.length)
+        return { targets: [], fragments: [] };
     const connection = [];
-    if (!presetsOnly && targets.includes("opencode")) {
-        const choice = value(await selectOption("OpenCode plugin connection", [
-            "Keep current connection",
-            "Connect and pin this package version",
-            "Disconnect agentomatic",
-        ]));
-        if (choice === 1)
-            connection.push("core-plugin");
-        if (choice === 2)
-            connection.push("core-disable");
-    }
-    const available = CONFIG_FRAGMENTS.filter((fragment) => !["core-plugin", "core-disable"].includes(fragment.name) &&
-        fragment.targets.some((target) => targets.includes(target))).map((fragment) => fragment.name);
-    const fragments = value(await selectOptions("Application presets to merge", available, defaults.fragments.filter((fragment) => available.includes(fragment)), available.map((name) => CONFIG_FRAGMENTS.find((fragment) => fragment.name === name)?.description)));
+    if (state.connection === 1)
+        connection.push("core-plugin");
+    if (state.connection === 2)
+        connection.push("core-disable");
     return normalizeConfigSelection(options.scope, {
-        targets,
-        fragments: [...connection, ...fragments],
+        targets: state.targets,
+        fragments: [...connection, ...applicablePresets(state.fragments, state.targets)],
     });
 }
-async function modelSelection(options, name, current) {
+async function modelSelection(options, name, current, allowBack = false) {
     validateAgentName(name);
     if (options.model) {
         const model = validateModel(options.model.includes("/") ? options.model : `${options.provider ?? ""}/${options.model}`);
@@ -362,42 +406,102 @@ async function modelSelection(options, name, current) {
             ...(current.variant ? ["Clear variant"] : []),
         ]
         : ["Change model"];
-    const choice = choices[value(await selectOption(`Agent: ${name}`, choices))];
-    if (choice.startsWith("Keep current"))
+    const changing = (state) => state.manual === null && state.choice === "Change model";
+    const candidates = (state) => state.models.filter((model) => model.startsWith(`${state.providers[state.provider]}/`));
+    const state = await runWizard({
+        choice: choices[0],
+        provider: 0,
+        model: 0,
+        variant: 0,
+        models: [],
+        providers: [],
+        variants: null,
+        manual: null,
+    }, [
+        {
+            run: async (current_, canBack) => {
+                const result = await selectOption(`Agent: ${name}`, choices, process.stdin, process.stderr, Math.max(0, choices.indexOf(current_.choice)), undefined, allowBack || canBack);
+                if (isBack(result))
+                    return result;
+                return { ...current_, choice: choices[value(result)] };
+            },
+        },
+        {
+            // The catalog is fetched on the provider screen (after the model
+            // choice), so the catalog-unavailable fallback keeps its exact order.
+            enabled: changing,
+            run: async (current_, canBack) => {
+                const fallback = async () => {
+                    process.stderr.write("Start opencode in another terminal to browse models, or enter provider/model manually\n");
+                    const model = validateModel(value(await promptText("Model (provider/model)")));
+                    const answer = await promptText(current?.variant ? "Variant (empty keeps current)" : "Variant (optional)");
+                    const variant = (answer ? validateVariant(answer) : current?.variant) ?? null;
+                    return { ...current_, manual: { model, variant } };
+                };
+                let providers = current_.providers;
+                let models = current_.models;
+                if (!models.length) {
+                    try {
+                        models = await availableModels();
+                    }
+                    catch (error) {
+                        if (!(error instanceof LifecycleError && error.code === "catalog_unavailable"))
+                            throw error;
+                        return fallback();
+                    }
+                    providers = [...new Set(models.map((model) => model.split("/", 1)[0]))].sort();
+                }
+                const result = await selectOption("Provider", providers, process.stdin, process.stderr, Math.min(current_.provider, providers.length - 1), undefined, canBack);
+                if (isBack(result))
+                    return result;
+                const provider = value(result);
+                return { ...current_, models, providers, provider, model: 0, variants: null };
+            },
+        },
+        {
+            enabled: (current_) => changing(current_) && current_.models.length > 0,
+            run: async (current_, canBack) => {
+                const available = candidates(current_);
+                const result = await selectOption("Model", available, process.stdin, process.stderr, Math.min(current_.model, available.length - 1), undefined, canBack);
+                if (isBack(result))
+                    return result;
+                const model = value(result);
+                const variants = await availableModelVariants(available[model]);
+                const variant = variants && current?.variant ? Math.max(0, variants.indexOf(current.variant) + 1) : 0;
+                return { ...current_, model, variants, variant };
+            },
+        },
+        {
+            enabled: (current_) => changing(current_) && current_.variants !== null && current_.variants.length > 0,
+            run: async (current_, canBack) => {
+                const variants = current_.variants;
+                const labels = variants.map((item) => item === current?.variant ? `${item} (default)` : item);
+                const result = await selectOption("Variant", ["(none)", ...labels], process.stdin, process.stderr, Math.min(current_.variant, labels.length), undefined, canBack);
+                if (isBack(result))
+                    return result;
+                return { ...current_, variant: value(result) };
+            },
+        },
+    ]);
+    if (state.manual)
+        return { action: "model-set", name, ...state.manual };
+    if (state.choice.startsWith("Keep current"))
         return { action: "model-set", name, model: current.model, variant: current.variant ?? null };
-    if (choice === "Clear variant")
+    if (state.choice === "Clear variant")
         return { action: "model-set", name, model: current.model, variant: null };
-    try {
-        const models = await availableModels();
-        const providers = [...new Set(models.map((model) => model.split("/", 1)[0]))].sort();
-        const provider = providers[value(await selectOption("Provider", providers))];
-        const candidates = models.filter((model) => model.startsWith(`${provider}/`));
-        const model = candidates[value(await selectOption("Model", candidates))];
-        const variants = await availableModelVariants(model);
-        let variant = null;
-        if (variants === null) {
-            // The variants metadata is unavailable: say so honestly and accept a
-            // manual variant instead of degrading the whole model selection.
-            process.stderr.write("Model variants are unknown (variants metadata unavailable); enter one manually or leave it empty.\n");
-            const answer = await promptText(current?.variant ? "Variant (empty keeps current)" : "Variant (optional)");
-            variant = (answer ? validateVariant(answer) : current?.variant) ?? null;
-        }
-        else if (variants.length) {
-            const labels = variants.map((item) => item === current?.variant ? `${item} (default)` : item);
-            const choice = value(await selectOption("Variant", ["(none)", ...labels], undefined, undefined, current?.variant ? variants.indexOf(current.variant) + 1 : 0));
-            variant = choice === 0 ? null : (variants[choice - 1] ?? null);
-        }
-        return { action: "model-set", name, model, variant };
-    }
-    catch (error) {
-        if (!(error instanceof LifecycleError && error.code === "catalog_unavailable"))
-            throw error;
-        process.stderr.write("Start opencode in another terminal to browse models, or enter provider/model manually\n");
-        const model = validateModel(value(await promptText("Model (provider/model)")));
+    const chosen = candidates(state)[state.model];
+    let variant = null;
+    if (state.variants === null) {
+        // The variants metadata is unavailable: say so honestly and accept a
+        // manual variant instead of degrading the whole model selection.
+        process.stderr.write("Model variants are unknown (variants metadata unavailable); enter one manually or leave it empty.\n");
         const answer = await promptText(current?.variant ? "Variant (empty keeps current)" : "Variant (optional)");
-        const variant = (answer ? validateVariant(answer) : current?.variant) ?? null;
-        return { action: "model-set", name, model, variant };
+        variant = (answer ? validateVariant(answer) : current?.variant) ?? null;
     }
+    else if (state.variants.length) {
+        variant = state.variant === 0 ? null : (state.variants[state.variant - 1] ?? null);
+    }
+    return { action: "model-set", name, model: chosen, variant };
 }
 async function profileDraft(options, names) {
     const inventory = await listAgentProfiles(options.scope);
@@ -407,15 +511,20 @@ async function profileDraft(options, names) {
     const changes = [];
     while (true) {
         const actions = ["Configure model", "Add critic", "Remove additional critic", "Done"];
-        const action = actions[value(await selectOption("Agent models and critics (changes are staged until confirmation)", actions, process.stdin, process.stderr, 3))];
+        const actionIndex = value(await selectOption("Agent models and critics (changes are staged until confirmation)", actions, process.stdin, process.stderr, 3));
+        if (isBack(actionIndex))
+            fail("cancelled", "Wizard cancelled; no changes applied");
+        const action = actions[actionIndex];
         if (action === "Done")
             return changes;
         if (action === "Add critic") {
             const name = await promptCriticName();
             if (records.has(name))
                 fail("profile_exists", `Profile already exists: ${name}`);
-            const request = { ...(await modelSelection(options, name)), action: "critic-add" };
-            changes.push(request);
+            const request = await modelSelection(options, name, undefined, true);
+            if (isBack(request))
+                continue;
+            changes.push({ ...request, action: "critic-add" });
             names.push(name);
             records.set(name, {
                 name,
@@ -433,14 +542,19 @@ async function profileDraft(options, names) {
                 process.stderr.write("No eligible profiles; choose another action.\n");
                 continue;
             }
-            const name = candidates[value(await selectOption("Agent", candidates))];
+            const selected = await selectOption("Agent", candidates, process.stdin, process.stderr, 0, undefined, true);
+            if (isBack(selected))
+                continue;
+            const name = candidates[value(selected)];
             if (action === "Remove additional critic") {
                 changes.push({ action: "critic-remove", name });
                 names = names.filter((candidate) => candidate !== name);
                 records.delete(name);
             }
             else {
-                const request = await modelSelection(options, name, records.get(name));
+                const request = await modelSelection(options, name, records.get(name), true);
+                if (isBack(request))
+                    continue;
                 changes.push(request);
                 records.set(name, {
                     ...records.get(name),
@@ -483,11 +597,41 @@ async function componentSelection(options) {
         return { ...saved, agents, core_activation: options.core ?? saved.core_activation };
     }
     process.stderr.write(`Portable skills are installed separately through the skills CLI (npx --yes ${skillsInstallerSpec()} add https://kisev.github.io/skills --agent opencode --copy). Selecting an adapter does not install its skill.\nAll six fixed agent roles deploy as one package; set their models or add critics with \`agentomatic configure agent\` afterwards.\n`);
-    const commands = value(await selectOptions("Skill command adapters", SKILL_COMMANDS, defaults.commands, commandHints()));
-    const plugins = value(await selectOptions("Optional plugins", SELECTABLE_PLUGINS, defaults.plugins, SELECTABLE_PLUGINS.map((plugin) => PLUGIN_DESCRIPTIONS[plugin])));
-    const core_activation = options.core ??
-        value(await confirmQuestion("Connect the OpenCode plugin and pin its npm dependency?", process.stdin, process.stderr, defaults.core_activation));
-    return normalizeSelection({ commands: commands ?? [], agents, plugins, core_activation });
+    const state = await runWizard({
+        commands: defaults.commands,
+        plugins: defaults.plugins,
+        core_activation: defaults.core_activation,
+    }, [
+        {
+            run: async (current, back) => {
+                const result = await selectOptions("Skill command adapters", SKILL_COMMANDS, current.commands, commandHints(), process.stdin, process.stderr, back);
+                if (isBack(result))
+                    return result;
+                return { ...current, commands: value(result) };
+            },
+        },
+        {
+            run: async (current, back) => {
+                const result = await selectOptions("Optional plugins", SELECTABLE_PLUGINS, current.plugins, SELECTABLE_PLUGINS.map((plugin) => PLUGIN_DESCRIPTIONS[plugin]), process.stdin, process.stderr, back);
+                if (isBack(result))
+                    return result;
+                return { ...current, plugins: value(result) };
+            },
+        },
+        {
+            run: async (current) => ({
+                ...current,
+                core_activation: options.core ??
+                    value(await confirmQuestion("Connect the OpenCode plugin and pin its npm dependency?", process.stdin, process.stderr, current.core_activation)),
+            }),
+        },
+    ]);
+    return normalizeSelection({
+        commands: state.commands ?? [],
+        agents,
+        plugins: state.plugins,
+        core_activation: state.core_activation,
+    });
 }
 async function deploy(options, repair = false) {
     const selection = repair
@@ -659,9 +803,50 @@ function partial(options, error, completed, next, requiresRestart = false) {
 }
 class ReportedError extends Error {
 }
+function configDivergence(plan) {
+    const changed = plan.operations.filter((operation) => operation.operation === "create" || operation.operation === "update");
+    const conflicts = plan.operations.some((operation) => operation.operation === "conflict");
+    const targets = CONFIG_TARGETS.filter((target) => changed.some((operation) => operation.target === target));
+    const fragments = CONFIG_FRAGMENTS.map((fragment) => fragment.name).filter((name) => changed.some((operation) => operation.fragment === name));
+    const connection = changed.some((operation) => operation.fragment === "core-plugin" || operation.fragment === "core-disable");
+    return { targets, fragments, connection, conflicts, changes: changed.length };
+}
 async function configureIntegration(options) {
     requireApply(options);
-    const selection = await integrationSelection(options);
+    const supplied = options.targets !== undefined || options.fragments !== undefined;
+    let selection;
+    if (supplied) {
+        selection = await integrationSelection(options);
+    }
+    else {
+        if (!tty())
+            fail("terminal_required", "configure integration outside a terminal requires --targets and --fragments");
+        // Diff before the first screen: an already-satisfied state asks nothing.
+        const defaults = await defaultConfigSelection(options.scope);
+        const baseline = await previewConfigSetup(defaults, options.scope, undefined, undefined, false, false);
+        const divergence = configDivergence(baseline);
+        const dependency = !options.noDependency &&
+            defaults.targets.includes("opencode") &&
+            defaults.fragments.includes("core-plugin")
+            ? planDependency(options.scope)
+            : undefined;
+        const settled = !dependency || dependency.status === "satisfied" || dependency.status === "manual";
+        if (divergence.changes === 0 && !divergence.conflicts && settled) {
+            if (options.json)
+                json({ status: "ok", applied: false, plan: baseline, noop: true });
+            else {
+                process.stdout.write(renderConfigNoop(baseline));
+                await epilogue(options, false);
+                process.stdout.write("Done: nothing to apply.\n");
+            }
+            return;
+        }
+        selection = await integrationSelection(options, false, {
+            targets: divergence.targets.length ? divergence.targets : undefined,
+            fragments: divergence.fragments,
+            connection: divergence.connection,
+        });
+    }
     const plan = await previewConfigSetup(selection, options.scope, undefined, undefined, !options.noDependency);
     if (!options.json)
         process.stdout.write(renderConfigSetup(plan, {
@@ -697,8 +882,10 @@ async function configureIntegration(options) {
                 requires_restart: result.requires_restart,
             });
         else {
-            process.stdout.write(renderConfigSetup(result, { applied: true }));
             await epilogue(options, false);
+            process.stdout.write(result.requires_restart
+                ? "Done: configuration applied; restart the host session.\n"
+                : "Done: configuration applied.\n");
         }
     }
     catch (error) {
@@ -880,6 +1067,8 @@ async function run(args) {
             "Agent models and critics",
             "Application connection and presets",
         ]));
+        if (isBack(selected))
+            fail("cancelled", "Wizard cancelled; no changes applied");
         topic = routes[selected];
     }
     if (topic === "install" || topic === "configure components" || topic === "maintenance repair") {
@@ -965,10 +1154,14 @@ async function run(args) {
             // configure agent on a fresh critic-<name> adds the critic: one command
             // covers model-set for existing profiles and critic-add for new critics.
             const request = await modelSelection(options, name, undefined);
+            if (isBack(request))
+                fail("cancelled", "Wizard cancelled; no changes applied");
             await profileChange(options, { ...request, action: "critic-add" });
             return;
         }
         const request = await modelSelection(options, name, existing);
+        if (isBack(request))
+            fail("cancelled", "Wizard cancelled; no changes applied");
         await profileChange(options, { ...request, action: "model-set" });
         return;
     }

package/dist/terminal-wizard.d.ts

@@ -1,5 +1,15 @@
 import type { Readable, Writable } from "node:stream";
-export declare function selectOption(label: string, options: readonly string[], stdin?: Readable, stderr?: Writable, initial?: number): Promise<number | null>;
-export declare function selectOptions(label: string, options: readonly string[], initialSelected?: readonly string[], hints?: readonly (string | undefined)[], stdin?: Readable, stderr?: Writable): Promise<string[] | null>;
+export declare const BACK: unique symbol;
+export type BackSignal = typeof BACK;
+export declare function isBack(value: unknown): value is BackSignal;
+export type WizardStep<T> = {
+    enabled?: (state: T) => boolean;
+    run: (state: T, back: boolean) => Promise<T | BackSignal>;
+};
+export declare function runWizard<T>(initial: T, steps: ReadonlyArray<WizardStep<T>>): Promise<T>;
+export declare function truncateLine(value: string, width: number): string;
+export declare function optionLabel(name: string, description: string | undefined, columns: number): string;
+export declare function selectOption(label: string, options: readonly string[], stdin?: Readable, stderr?: Writable, initial?: number, descriptions?: readonly (string | undefined)[], back?: boolean): Promise<number | null | BackSignal>;
+export declare function selectOptions(label: string, options: readonly string[], initialSelected?: readonly string[], descriptions?: readonly (string | undefined)[], stdin?: Readable, stderr?: Writable, back?: boolean): Promise<string[] | null | BackSignal>;
 export declare function promptText(label: string, stdin?: Readable, stderr?: Writable): Promise<string | null>;
 export declare function confirmQuestion(label: string, stdin?: Readable, stderr?: Writable, initialValue?: boolean): Promise<boolean | null>;

package/dist/terminal-wizard.js

@@ -1,5 +1,41 @@
 import * as clack from "@clack/prompts";
 import { InstallerError } from "./installer.js";
+// Sentinel returned when the user chooses the "Back" item; `runWizard` steps
+// back to the previous enabled screen and restores the saved answer.
+export const BACK = Symbol("wizard-back");
+export function isBack(value) {
+    return value === BACK;
+}
+const BACK_VALUE = "$__agentomatic_back__";
+const BACK_LABEL = "← Back";
+export async function runWizard(initial, steps) {
+    const enabled = (index, state) => !steps[index].enabled || steps[index].enabled(state);
+    let state = initial;
+    let index = 0;
+    while (index < steps.length) {
+        if (!enabled(index, state)) {
+            index += 1;
+            continue;
+        }
+        let previous = index - 1;
+        while (previous >= 0 && !enabled(previous, state))
+            previous -= 1;
+        const result = await steps[index].run(state, previous >= 0);
+        if (result === BACK) {
+            if (previous < 0)
+                continue;
+            index = previous;
+            continue;
+        }
+        state = result;
+        index += 1;
+    }
+    return state;
+}
+const DEFAULT_COLUMNS = 80;
+// clack renders a guide and a state marker ("│  ◻ ") before the label; keep the
+// composed label inside the remaining terminal columns so it never wraps.
+const LABEL_RESERVE = 8;
 function interactiveStreams(stdin, stderr) {
     if (!isTTY(stdin) || !isTTY(stderr))
         throw new InstallerError("terminal_required", "This operation requires an interactive terminal");
@@ -13,24 +49,55 @@ function validateOptions(options) {
     if (new Set(options).size !== options.length)
         throw new InstallerError("invalid_input", "Interactive selector options must be unique");
 }
-export async function selectOption(label, options, stdin = process.stdin, stderr = process.stderr, initial = 0) {
+function terminalColumns(stderr) {
+    const columns = stderr.columns;
+    return Number.isFinite(columns) && (columns ?? 0) > 0 ? columns : DEFAULT_COLUMNS;
+}
+// Long single-line values are cut to the terminal width with a trailing
+// ellipsis; the description is never silently dropped for a normal terminal.
+export function truncateLine(value, width) {
+    if (width <= 1)
+        return "…";
+    return [...value].length <= width ? value : `${[...value].slice(0, width - 1).join("")}…`;
+}
+// Every option label carries its data-driven description so the text is
+// visible on every line, not only under the cursor (clack renders `hint` for
+// the focused option only).
+export function optionLabel(name, description, columns) {
+    const combined = description ? `${name} — ${description}` : name;
+    return truncateLine(combined, Math.max(12, columns - LABEL_RESERVE));
+}
+function backOption() {
+    return { value: BACK_VALUE, label: BACK_LABEL };
+}
+export async function selectOption(label, options, stdin = process.stdin, stderr = process.stderr, initial = 0, descriptions, back = false) {
     interactiveStreams(stdin, stderr);
     validateOptions(options);
+    const columns = terminalColumns(stderr);
+    const entries = options.map((option, index) => ({
+        value: String(index),
+        label: optionLabel(option, descriptions?.[index], columns),
+    }));
+    if (back)
+        entries.push(backOption());
     const value = await clack.select({
         message: label,
-        options: options.map((option, index) => ({ value: index, label: option })),
-        initialValue: Math.max(0, Math.min(initial, options.length - 1)),
+        options: entries,
+        initialValue: String(Math.max(0, Math.min(initial, options.length - 1))),
         input: stdin,
         output: stderr,
     });
     if (clack.isCancel(value))
         return null;
-    return value;
+    if (value === BACK_VALUE)
+        return BACK;
+    return Number(value);
 }
 // The multiselect contract: each option carries a data-driven description and
 // the message states the all/none controls, so every group is self-explanatory.
+// SIMPLIFY: Back is a normal option, so the all/none key also selects it -> upgrade to a dedicated Back key if clack exposes one.
 const MULTISELECT_CONTROLS = " (move: up/down; toggle: space; all/none: a; enter confirms)";
-export async function selectOptions(label, options, initialSelected = [], hints, stdin = process.stdin, stderr = process.stderr) {
+export async function selectOptions(label, options, initialSelected = [], descriptions, stdin = process.stdin, stderr = process.stderr, back = false) {
     interactiveStreams(stdin, stderr);
     validateOptions(options);
     const allowed = new Set(options);
@@ -38,13 +105,16 @@ export async function selectOptions(label, options, initialSelected = [], hints,
         if (!allowed.has(value))
             throw new InstallerError("invalid_input", `Unknown initial selector option: ${value}`);
     }
+    const columns = terminalColumns(stderr);
+    const entries = options.map((option, index) => ({
+        value: option,
+        label: optionLabel(option, descriptions?.[index], columns),
+    }));
+    if (back)
+        entries.push(backOption());
     const value = await clack.multiselect({
         message: `${label}${MULTISELECT_CONTROLS}`,
-        options: options.map((option, index) => ({
-            value: option,
-            label: option,
-            ...(hints?.[index] ? { hint: hints[index] } : {}),
-        })),
+        options: entries,
         initialValues: [...initialSelected],
         required: false,
         input: stdin,
@@ -52,7 +122,10 @@ export async function selectOptions(label, options, initialSelected = [], hints,
     });
     if (clack.isCancel(value))
         return null;
-    return value;
+    const selected = value;
+    if (selected.includes(BACK_VALUE))
+        return BACK;
+    return selected;
 }
 export async function promptText(label, stdin = process.stdin, stderr = process.stderr) {
     interactiveStreams(stdin, stderr);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/agentomatic",
-  "version": "12.0.1-dev.130.g78ea8685c8d4",
+  "version": "12.0.1-dev.132.g6d50bbe22d9e",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "homepage": "https://github.com/kisev/skills#readme",
   "bugs": {
@@ -50,12 +50,12 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@kisev/safe-fs": "12.0.1-dev.130.g78ea8685c8d4",
+    "@kisev/safe-fs": "12.0.1-dev.132.g6d50bbe22d9e",
     "commander": "15.0.0",
     "zod": "4.1.8"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.24",
+    "@opencode/plugin": "2.0.25",
     "@types/node": "22.15.30",
     "typescript": "7.0.2"
   },