@rbbtsn0w/adg 0.1.0-alpha.1 → 0.1.0-beta.2

package/dist/src/commands/install.js

@@ -0,0 +1,257 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { ADAPTER_TARGETS } from "../adapters/index.js";
+import { fromNativeManifest } from "../adapters/reverse.js";
+import { adaptPlugin } from "./adapt.js";
+import { copyPluginDir, writeJson } from "../fsutil.js";
+import { folderHash } from "../hash.js";
+import { packageFilter } from "../package.js";
+import { lockPath, marketplacePath, marketplaceSourcePath, pluginDir } from "../paths.js";
+import { readLock, upsertEntry, writeLock } from "../lock.js";
+import { ADG_MANIFEST_PATH, readManifest } from "../manifest.js";
+import { readMarketplace, upsertMarketplacePlugin, writeMarketplace } from "../marketplace.js";
+import { resolveInstallOrder } from "../deps.js";
+import { cloneGitHub, parseSource, scanNativePlugins, scanPlugins } from "../sources.js";
+import { sameSource, COMPONENT_TYPES } from "../types.js";
+import { pluginContents, presentComponents } from "../components.js";
+import { skillDescriptionLoader } from "../skills.js";
+import { resolveAgents } from "../agents/index.js";
+const HASH_IGNORE = [".claude-plugin", ".codex-plugin"];
+function toPosix(p) {
+    return p.split("\\").join("/");
+}
+/**
+ * Install a single local plugin directory into a plugins directory: copy the
+ * source, generate adapter manifests, compute the folder hash, and update both
+ * .plugin-lock.json and marketplace.json (with denormalized discovery metadata
+ * and an integrity digest).
+ *
+ * Refuses to overwrite a same-named plugin that came from a different upstream
+ * source (cross-marketplace name collision). Only files under `pluginsDir` are
+ * written — sibling files such as AGENTS.md or a global skills/ are untouched.
+ */
+export function installPlugin(opts) {
+    const source = resolve(opts.source);
+    const manifest = readManifest(source);
+    const name = manifest.name;
+    // Local installs stay flat; remote sources derive a per-marketplace dir from
+    // their origin. The default (no origin) is a flat local copy-in.
+    const origin = opts.origin ?? { type: "local", path: `./${toPosix(name)}` };
+    const dest = pluginDir(opts.pluginsDir, name, origin);
+    // When the source already lives at the destination (e.g. adapting an
+    // in-repo reference plugin) skip the copy to avoid copying onto itself.
+    // Only the manifest-declared payload is copied (projections included) — dev
+    // cruft like src/ or test/ never ships.
+    if (resolve(dest) !== source) {
+        copyPluginDir(source, dest, packageFilter(manifest, { includeProjections: true }));
+    }
+    const lockFile = lockPath(opts.pluginsDir);
+    const lock = readLock(lockFile);
+    const prev = lock.plugins[name];
+    if (prev && !sameSource(prev.origin, origin)) {
+        throw new Error(`name collision: "${name}" is already installed from a different source ` +
+            `(${describe(prev.origin)} vs ${describe(origin)}). Rename one to avoid the conflict.`);
+    }
+    // A new selection wins; otherwise keep whatever a prior install recorded so
+    // partial installs survive re-install / `marketplace upgrade`.
+    const selection = opts.selection ?? prev?.selection;
+    const targets = opts.targets ?? [...ADAPTER_TARGETS];
+    const adapted = adaptPlugin(dest, targets, selection).map((r) => r.file);
+    const hash = folderHash(dest, HASH_IGNORE, packageFilter(manifest, { includeProjections: false }));
+    const entry = {
+        origin,
+        version: manifest.version,
+        folderHash: hash,
+    };
+    if (manifest.dependencies?.length) {
+        entry.dependencies = Object.fromEntries(manifest.dependencies.map((d) => [d.name, d.version]));
+    }
+    if (selection)
+        entry.selection = selection;
+    upsertEntry(lock, name, entry, opts.now);
+    writeLock(lockFile, lock);
+    const marketFile = marketplacePath(opts.pluginsDir);
+    const fallbackName = opts.marketplaceName ?? basename(opts.pluginsDir);
+    const market = readMarketplace(marketFile, fallbackName);
+    // marketplace.json is a pure runtime-facing export in the de-facto shape;
+    // version/integrity/provenance live in the lock, not here.
+    upsertMarketplacePlugin(market, {
+        name,
+        source: { source: "local", path: marketplaceSourcePath(opts.pluginsDir, dest) },
+        policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+        ...(manifest.category ? { category: manifest.category } : {}),
+    });
+    writeMarketplace(marketFile, market);
+    return { name, installedTo: dest, folderHash: hash, adapted };
+}
+function describe(s) {
+    switch (s.type) {
+        case "local": return `local:${s.path}`;
+        case "github": return `github:${s.repo}${s.path ? `/${s.path}` : ""}`;
+        case "git": return `git:${s.url}${s.path ? `/${s.path}` : ""}`;
+    }
+}
+/**
+ * Reverse-adapt any native (Claude/Codex) manifests under `root` into
+ * `.agents/.plugin.json`, then return every ADG plugin found. After this the
+ * whole source speaks ADG, so selection and install treat all plugins uniformly.
+ */
+function discoverPlugins(root) {
+    const converted = [];
+    for (const native of scanNativePlugins(root)) {
+        if (native.kind === "adg")
+            continue;
+        const raw = JSON.parse(readFileSync(native.manifestFile, "utf8"));
+        const manifest = fromNativeManifest(raw, native.kind);
+        writeJson(join(native.dir, ADG_MANIFEST_PATH), manifest);
+        converted.push(manifest.name);
+    }
+    return { candidates: scanPlugins(root), converted };
+}
+/** Resolve which discovered plugins to install from the selection options. */
+async function selectPluginNames(opts, candidates, workRoot, converted) {
+    const names = [...candidates.keys()];
+    if (opts.plugins?.length) {
+        const missing = opts.plugins.filter((p) => !candidates.has(p));
+        if (missing.length) {
+            throw new Error(`plugin(s) not found in source: ${missing.join(", ")}.\nAvailable: ${names.join(", ")}`);
+        }
+        return opts.plugins;
+    }
+    if (opts.path) {
+        const target = resolve(join(workRoot, opts.path));
+        const hit = [...candidates.values()].find((c) => resolve(c.dir) === target);
+        if (!hit)
+            throw new Error(`no plugin found at --path ${opts.path}`);
+        return [hit.manifest.name];
+    }
+    if (opts.all || candidates.size === 1)
+        return names;
+    if (opts.selectPlugins) {
+        const convertedSet = new Set(converted);
+        const choices = [...candidates.values()].map((c) => ({
+            name: c.manifest.name,
+            description: c.manifest.description,
+            native: convertedSet.has(c.manifest.name),
+        }));
+        return opts.selectPlugins(choices);
+    }
+    throw new Error(`source "${opts.spec}" contains ${candidates.size} plugins: ${names.join(", ")}.\n` +
+        `Pick with --plugin <name> (repeatable), --all for everything, or run in a terminal to choose interactively.`);
+}
+/**
+ * Decide a partial-install selection for each user-chosen plugin.
+ *
+ * Precedence: explicit flags (--only / --skill) win and apply to every chosen
+ * plugin; otherwise an interactive gate asks whether to install in full, and if
+ * not, a per-plugin component picker runs (skipped for plugins with nothing
+ * meaningful to choose). No selection for a plugin = expose everything.
+ */
+async function resolveSelections(opts, selected, candidates) {
+    const selections = new Map();
+    if (opts.only || opts.skillsSubset) {
+        const flagSelection = {
+            components: opts.only ?? [...COMPONENT_TYPES],
+            ...(opts.skillsSubset ? { skills: opts.skillsSubset } : {}),
+        };
+        for (const name of selected)
+            selections.set(name, flagSelection);
+        return selections;
+    }
+    if (!opts.confirmFull || !opts.selectComponents)
+        return selections; // non-interactive default: full
+    if (await opts.confirmFull(selected))
+        return selections; // user kept everything
+    for (const name of selected) {
+        const cand = candidates.get(name);
+        const contents = pluginContents(cand.dir, cand.manifest);
+        const present = presentComponents(contents);
+        // Nothing meaningful to pick: a lone category with at most one member.
+        if (present.length <= 1 && contents.skills.length <= 1)
+            continue;
+        const skillDescription = skillDescriptionLoader(cand.dir, cand.manifest);
+        selections.set(name, await opts.selectComponents({ name, contents, present, skillDescription }));
+    }
+    return selections;
+}
+/**
+ * The unified install entrypoint. Treats any source as a marketplace: clone or
+ * read it, discover every plugin (ADG plus reverse-adapted native), choose a
+ * subset (--all / --plugin / --path / sole plugin / interactive picker), then
+ * install the selection in dependency-first order.
+ */
+export async function addPlugins(opts) {
+    const parsed = parseSource(opts.spec);
+    let workRoot;
+    let buildOrigin;
+    let cleanup;
+    if (parsed.kind === "local") {
+        workRoot = resolve(parsed.dir);
+        buildOrigin = (dir) => ({ type: "local", path: `./${toPosix(relative(workRoot, dir)) || basename(dir)}` });
+    }
+    else {
+        const ref = opts.ref ?? parsed.ref;
+        const tmp = mkdtempSync(join(tmpdir(), "adg-clone-"));
+        cleanup = () => rmSync(tmp, { recursive: true, force: true });
+        cloneGitHub({ ...parsed, ref }, tmp, { sparse: opts.sparse, runner: opts.gitRunner });
+        workRoot = tmp;
+        buildOrigin = (dir) => ({
+            type: "github",
+            repo: parsed.source,
+            ...(ref ? { ref } : {}),
+            path: toPosix(relative(tmp, dir)) || ".",
+        });
+    }
+    try {
+        const { candidates, converted } = discoverPlugins(workRoot);
+        if (candidates.size === 0) {
+            throw new Error(`no plugin found in "${opts.spec}" (no .agents/.plugin.json, .claude-plugin or .codex-plugin manifest).`);
+        }
+        const selected = await selectPluginNames(opts, candidates, workRoot, converted);
+        if (selected.length === 0)
+            throw new Error("no plugins selected");
+        // Resolve adapter targets after the plugin choice (lets a CLI agent picker
+        // run once we know what's being installed). undefined → installPlugin's all.
+        const targets = opts.targets ?? (opts.selectTargets ? await opts.selectTargets() : undefined);
+        // Partial-install selection per user-chosen plugin (auto-deps install full).
+        const selections = await resolveSelections(opts, selected, candidates);
+        // Dependency-first order across every selected plugin (chains deduped).
+        const order = [];
+        const seen = new Set();
+        for (const name of selected) {
+            const chain = opts.withDeps === false ? [name] : resolveInstallOrder(name, candidates);
+            for (const n of chain) {
+                if (!seen.has(n)) {
+                    seen.add(n);
+                    order.push(n);
+                }
+            }
+        }
+        const installed = [];
+        for (const name of order) {
+            const candidate = candidates.get(name);
+            installed.push(installPlugin({
+                source: candidate.dir,
+                pluginsDir: opts.pluginsDir,
+                origin: buildOrigin(candidate.dir),
+                marketplaceName: opts.marketplaceName,
+                targets,
+                selection: selections.get(name),
+                now: opts.now,
+            }));
+        }
+        // Activate into the selected agents so the plugins are actually usable, not
+        // just recorded/discoverable — each agent enables them via its own CLI.
+        // undefined targets = all registered agents.
+        let agents;
+        if (opts.activate) {
+            const ctx = { pluginsDir: opts.pluginsDir, plugins: installed.map((r) => r.name), scope: opts.scope ?? "project" };
+            agents = (opts.agents ?? resolveAgents(targets)).map((a) => a.activate(ctx));
+        }
+        return { order, installed, converted, available: [...candidates.keys()], agents };
+    }
+    finally {
+        cleanup?.();
+    }
+}

package/dist/src/commands/link.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { adaptPlugin } from "./adapt.js";
+import { listPlugins } from "./list.js";
+import { installedPluginDir } from "../paths.js";
+import { getAgent } from "../agents/index.js";
+/**
+ * Project installed plugins into an agent: (re)generate that agent's manifest
+ * from each plugin (honoring its partial-install selection), then enable the
+ * plugins through the agent's CLI. The pure manifest transform comes from
+ * `ADAPTERS[agent.adaptTarget]`; the enable step is the agent's `activate`.
+ */
+export function linkPlugins(opts) {
+    const agent = opts.agent ?? getAgent(opts.target);
+    const adaptTarget = agent?.adaptTarget ?? opts.target;
+    const actions = [];
+    for (const p of listPlugins(opts.pluginsDir)) {
+        const dir = installedPluginDir(opts.pluginsDir, p.name, p.origin);
+        if (!existsSync(dir))
+            continue;
+        const adapted = adaptPlugin(dir, [adaptTarget], p.selection).map((r) => r.file);
+        actions.push({ name: p.name, adapted });
+    }
+    if (!agent)
+        return { target: opts.target, actions };
+    const res = agent.activate({
+        pluginsDir: opts.pluginsDir,
+        plugins: actions.map((a) => a.name),
+        scope: opts.global ? "user" : "project",
+    });
+    for (const a of actions)
+        if (res.affected.includes(a.name))
+            a.linkedTo = agent.displayName;
+    return { target: opts.target, actions, cliSkipped: res.skipped };
+}

package/dist/src/commands/list.js

@@ -0,0 +1,19 @@
+import { installedPluginDir, lockPath } from "../paths.js";
+import { readLock } from "../lock.js";
+import { readManifest } from "../manifest.js";
+import { exposedContents, pluginContents } from "../components.js";
+/** List plugins recorded in a plugins directory's .plugin-lock.json. */
+export function listPlugins(pluginsDir) {
+    const lock = readLock(lockPath(pluginsDir));
+    return Object.entries(lock.plugins).map(([name, entry]) => {
+        const dir = installedPluginDir(pluginsDir, name, entry.origin);
+        let contents;
+        try {
+            contents = exposedContents(pluginContents(dir, readManifest(dir)), entry.selection);
+        }
+        catch {
+            contents = undefined; // no/invalid manifest on disk — show provenance only
+        }
+        return { name, ...entry, contents };
+    });
+}

package/dist/src/commands/marketplace.js

@@ -0,0 +1,124 @@
+import { lockPath } from "../paths.js";
+import { readLock } from "../lock.js";
+import { addPlugins } from "./install.js";
+import { removePlugin } from "./remove.js";
+/**
+ * A stable key identifying the source a plugin came from. GitHub/git plugins
+ * group by repo/url (the marketplace root, ignoring per-plugin sub-paths);
+ * local installs share a single "(local)" bucket since their original source
+ * directory isn't recoverable for re-sync.
+ */
+export function sourceKey(origin) {
+    switch (origin.type) {
+        case "github":
+            return origin.repo;
+        case "git":
+            return origin.url;
+        case "local":
+            return "(local)";
+    }
+}
+/** True for sources that can be re-fetched (have a recoverable remote spec). */
+function isRemoteKey(key) {
+    return key !== "(local)";
+}
+/** Group installed plugins by source, read straight from the lock. */
+export function marketplaceList(opts) {
+    const lock = readLock(lockPath(opts.pluginsDir));
+    const groups = new Map();
+    for (const [name, entry] of Object.entries(lock.plugins)) {
+        const key = sourceKey(entry.origin);
+        const ref = entry.origin.type === "github" || entry.origin.type === "git" ? entry.origin.ref : undefined;
+        const g = groups.get(key) ?? { ref, installed: [] };
+        g.installed.push(name);
+        if (g.ref === undefined && ref !== undefined)
+            g.ref = ref;
+        groups.set(key, g);
+    }
+    return [...groups.entries()]
+        .map(([source, g]) => ({
+        source,
+        ...(g.ref ? { ref: g.ref } : {}),
+        installed: g.installed.sort(),
+        remote: isRemoteKey(source),
+    }))
+        .sort((a, b) => a.source.localeCompare(b.source));
+}
+/**
+ * Find one source group by key, or throw with the available keys. The error is
+ * scope-aware: it names the scope/path it searched, and — when the source isn't
+ * here but exists globally — suggests re-running with `-g`.
+ */
+function requireGroup(pluginsDir, source, scope) {
+    const groups = marketplaceList({ pluginsDir });
+    const hit = groups.find((g) => g.source === source);
+    if (hit)
+        return hit;
+    const keys = groups.map((g) => g.source).join(", ") || "(none)";
+    const where = scope?.label ? `${scope.label}: ${pluginsDir}` : pluginsDir;
+    let msg = `no installed source "${source}" in ${where}. Known sources: ${keys}`;
+    if (scope?.globalDir && scope.globalDir !== pluginsDir) {
+        const inGlobal = marketplaceList({ pluginsDir: scope.globalDir }).some((g) => g.source === source);
+        if (inGlobal)
+            msg += ` — found in global; did you mean \`-g\`?`;
+    }
+    throw new Error(msg);
+}
+/**
+ * Re-fetch a source and update the plugins installed from it. By default only
+ * already-installed plugins are refreshed; `all` also installs everything new
+ * the source now offers. With no `source`, every remote source is upgraded.
+ */
+export async function marketplaceUpgrade(opts) {
+    const groups = opts.source
+        ? [requireGroup(opts.pluginsDir, opts.source, opts.scope)]
+        : marketplaceList({ pluginsDir: opts.pluginsDir }).filter((g) => g.remote);
+    if (opts.source && !groups[0].remote) {
+        throw new Error(`source "${opts.source}" is local and cannot be re-synced; re-run \`adg plugins add\`.`);
+    }
+    if (groups.length === 0) {
+        throw new Error(`no remote sources installed in ${opts.pluginsDir}`);
+    }
+    const now = opts.now ?? new Date().toISOString();
+    const results = [];
+    for (const group of groups) {
+        const { installed, converted, available } = await addPlugins({
+            spec: group.source,
+            pluginsDir: opts.pluginsDir,
+            ref: group.ref,
+            // Default: refresh what's installed. --all: install everything too.
+            ...(opts.all ? { all: true } : { plugins: group.installed }),
+            targets: opts.targets,
+            marketplaceName: group.source,
+            gitRunner: opts.gitRunner,
+            // Re-activate so the agents pick up the upgraded content, not just the store.
+            activate: opts.activate,
+            scope: opts.agentScope,
+            now,
+        });
+        const installedSet = new Set(group.installed);
+        results.push({
+            source: group.source,
+            updated: installed,
+            converted,
+            available: available.filter((n) => !installedSet.has(n)),
+        });
+    }
+    return results;
+}
+/** Uninstall every plugin that came from a given source (and from the agents). */
+export function marketplaceRemove(opts) {
+    const group = requireGroup(opts.pluginsDir, opts.source, opts.scope);
+    const removed = [];
+    for (const name of group.installed) {
+        removePlugin({
+            pluginsDir: opts.pluginsDir,
+            name,
+            force: opts.force,
+            deactivate: opts.deactivate,
+            scope: opts.agentScope,
+        });
+        removed.push(name);
+    }
+    return { source: opts.source, removed };
+}

package/dist/src/commands/migrate.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { lockPath, marketplacePath, marketplaceSourcePath, pluginDir } from "../paths.js";
+import { readLock } from "../lock.js";
+import { readMarketplace, upsertMarketplacePlugin, writeMarketplace } from "../marketplace.js";
+/**
+ * Migrate a flat plugins directory to the per-marketplace nested layout.
+ *
+ * For every locked plugin, move `<pluginsDir>/<name>` to the origin-derived
+ * `<pluginsDir>/<segment>/<name>` (remote sources only; local installs stay
+ * flat) and rewrite its marketplace.json `source.path` to match. Idempotent:
+ * plugins already at their target path are reported as unchanged.
+ */
+export function migrateLayout(pluginsDir) {
+    const lock = readLock(lockPath(pluginsDir));
+    const moved = [];
+    const unchanged = [];
+    const missing = [];
+    const marketFile = marketplacePath(pluginsDir);
+    const market = readMarketplace(marketFile, "");
+    let marketDirty = false;
+    for (const [name, entry] of Object.entries(lock.plugins)) {
+        const flat = join(pluginsDir, name);
+        const target = pluginDir(pluginsDir, name, entry.origin);
+        if (target === flat) {
+            unchanged.push(name);
+            continue;
+        }
+        if (existsSync(target)) {
+            // Already migrated; nothing to move, but make sure the export agrees.
+            if (rewriteMarketplacePath(market, name, pluginsDir, target))
+                marketDirty = true;
+            unchanged.push(name);
+            continue;
+        }
+        if (!existsSync(flat)) {
+            missing.push(name);
+            continue;
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(flat, target);
+        if (rewriteMarketplacePath(market, name, pluginsDir, target))
+            marketDirty = true;
+        moved.push({ name, from: flat, to: target });
+    }
+    if (marketDirty)
+        writeMarketplace(marketFile, market);
+    return { moved, unchanged, missing };
+}
+/** Point a marketplace entry's `source.path` at the plugin's on-disk dir. */
+function rewriteMarketplacePath(market, name, pluginsDir, dir) {
+    const existing = market.plugins.find((p) => p.name === name);
+    if (!existing)
+        return false;
+    const path = marketplaceSourcePath(pluginsDir, dir);
+    if (existing.source.path === path)
+        return false;
+    upsertMarketplacePlugin(market, { ...existing, source: { ...existing.source, path } });
+    return true;
+}

package/dist/src/commands/multiselect-skills.js

@@ -0,0 +1,103 @@
+import { MultiSelectPrompt } from "@clack/core";
+import pc from "picocolors";
+/**
+ * A skills multiselect with an on-demand description toggle. `@clack/prompts`'
+ * `multiselect` can't intercept extra keys, so this builds directly on
+ * `@clack/core`'s `MultiSelectPrompt` and replicates clack's chrome, adding a
+ * `d` key that lazily loads and inlines each skill's description as a hint.
+ *
+ * Descriptions are read only while the toggle is on (and cached by the loader),
+ * so a list of many skills costs nothing until the user actually asks for them.
+ */
+// Match @clack/prompts' unicode-aware glyphs so the picker is visually seamless.
+const unicode = process.platform !== "win32" ||
+    Boolean(process.env.WT_SESSION) ||
+    process.env.TERM_PROGRAM === "vscode" ||
+    process.env.TERM === "xterm-256color";
+const g = (a, b) => (unicode ? a : b);
+const S_BAR = g("│", "|");
+const S_BAR_END = g("└", "—");
+const S_STEP_ACTIVE = g("◆", "*");
+const S_STEP_SUBMIT = g("◇", "o");
+const S_STEP_CANCEL = g("■", "x");
+const S_CHECK_ACTIVE = g("◻", "[•]");
+const S_CHECK_SELECTED = g("◼", "[+]");
+const S_CHECK_INACTIVE = g("◻", "[ ]");
+/** Format one option row, appending the description as a dim hint when present. */
+export function formatSkillRow(label, hint, kind) {
+    const tail = hint ? `  ${pc.dim(hint)}` : "";
+    switch (kind) {
+        case "active":
+            return `${pc.cyan(S_CHECK_ACTIVE)} ${label}${tail}`;
+        case "active-selected":
+            return `${pc.green(S_CHECK_SELECTED)} ${label}${tail}`;
+        case "selected":
+            return `${pc.green(S_CHECK_SELECTED)} ${pc.dim(label)}${tail}`;
+        default:
+            return `${pc.dim(S_CHECK_INACTIVE)} ${pc.dim(label)}`;
+    }
+}
+/**
+ * Build the rendered option rows. Descriptions are resolved only when
+ * `showDesc` is true, so the picker performs zero SKILL.md reads until the user
+ * presses `d`. Exported as the pure core of the picker for direct testing.
+ */
+export function buildSkillRows(options, state) {
+    return options.map((o, i) => {
+        const sel = state.selected.includes(o.value);
+        const active = i === state.cursor;
+        const hint = state.showDesc ? state.loadDescription(o.value) : undefined;
+        const kind = active && sel ? "active-selected" : sel ? "selected" : active ? "active" : "inactive";
+        return formatSkillRow(o.label, hint, kind);
+    });
+}
+/** Resolves to the chosen values, or a cancel symbol (use `isCancel` to detect). */
+export function multiselectSkills(opts) {
+    let showDesc = false;
+    const symbol = (state) => {
+        if (state === "submit")
+            return pc.green(S_STEP_SUBMIT);
+        if (state === "cancel")
+            return pc.red(S_STEP_CANCEL);
+        return pc.cyan(S_STEP_ACTIVE);
+    };
+    const footer = () => pc.dim(`space ${pc.gray("toggle")} · a ${pc.gray("all")} · d ${pc.gray(showDesc ? "hide" : "show")} descriptions`);
+    const prompt = new MultiSelectPrompt({
+        input: opts.input,
+        output: opts.output,
+        options: opts.options,
+        initialValues: opts.initialValues,
+        required: true,
+        validate(value) {
+            if (this.required && Array.isArray(value) && value.length === 0) {
+                return "Please select at least one option.";
+            }
+            return undefined;
+        },
+        render() {
+            const head = `${pc.gray(S_BAR)}\n${symbol(this.state)}  ${opts.message}\n`;
+            if (this.state === "submit" || this.state === "cancel") {
+                const chosen = this.options
+                    .filter((o) => this.value.includes(o.value))
+                    .map((o) => pc.dim(o.label))
+                    .join(pc.dim(", "));
+                return `${head}${pc.gray(S_BAR)}  ${chosen || pc.dim("none")}`;
+            }
+            const rows = buildSkillRows(this.options, {
+                cursor: this.cursor,
+                selected: this.value,
+                showDesc,
+                loadDescription: opts.loadDescription,
+            }).join(`\n${pc.cyan(S_BAR)}  `);
+            return `${head}${pc.cyan(S_BAR)}  ${rows}\n${pc.cyan(S_BAR)}  ${footer()}\n${pc.cyan(S_BAR_END)}\n`;
+        },
+    });
+    // `a` (toggle-all) is bound by MultiSelectPrompt itself; `d` is free for us.
+    // Touching showDesc here re-renders on the same keypress (onKeypress renders
+    // after emitting "key"), so the first `d` press shows descriptions at once.
+    prompt.on("key", (c) => {
+        if (c === "d")
+            showDesc = !showDesc;
+    });
+    return prompt.prompt();
+}