@iseoane/agent-depot 0.2.0 → 0.2.1

package/dist/src/tui/bulk-actions.js

@@ -0,0 +1,243 @@
+import { PROJECT_HOSTS } from "../project-manifest.js";
+import { assertManagedInstallationRecordsUnchanged } from "../skill-removal.js";
+import { errorText, runBatch } from "./batch.js";
+import { missingHosts, prepareHostAddition, prepareUninstall, runHostAddition, runUninstall, UNINSTALL_REFUSALS, } from "./catalog-installs.js";
+import { answerYesNo, applyChecklistOutcome, hostChecklistKey } from "./mode-keys.js";
+import { skillOf, sourceIdOf } from "./installations.js";
+import { prepareUnmanagedRemoval, runUnmanagedRemoval } from "./unmanaged-actions.js";
+export const BULK_KINDS = ["bulk-hosts", "confirm-bulk-uninstall", "confirm-bulk-hosts", "confirm-bulk-exposure"];
+const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+function skip(target, label, reason) {
+    return { id: target.id, label, reason };
+}
+function labelOf(target) {
+    const { leaf } = target;
+    if (leaf.kind === "unmanaged")
+        return leaf.group.name;
+    return leaf.row.scope === "project" ? `${leaf.row.selection.path} (project)` : leaf.row.selection.path;
+}
+/** Reads the records once, so every item of the batch is checked against the same state. */
+async function listRecords(operations) {
+    return operations.listUserGlobalInstallations ? operations.listUserGlobalInstallations() : [];
+}
+/**
+ * Drift check before an item: the records must be exactly what the previous items were expected to leave.
+ * The baseline only ever advances by the change an item made, so an outside change is never absorbed.
+ */
+async function assertNoDrift(operations, expected) {
+    const actual = await listRecords(operations);
+    try {
+        assertManagedInstallationRecordsUnchanged(expected, actual);
+    }
+    catch {
+        throw new Error("The installation records changed outside this batch since the previous item; this item was left untouched");
+    }
+}
+const sameRecord = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+/** Plan step of a bulk uninstall: prepares each marked leaf with its shared plan, or records why it is skipped. */
+export async function prepareBulkUninstall(context, targets) {
+    const { operations, env, installed } = context;
+    const installations = await listRecords(operations);
+    const items = [];
+    const skipped = [];
+    for (const target of targets) {
+        const label = labelOf(target);
+        const { leaf } = target;
+        try {
+            if (leaf.kind === "unmanaged") {
+                items.push({ kind: "unmanaged", id: target.id, label, prepared: await prepareUnmanagedRemoval(operations, env, leaf.group, leaf.group.locations) });
+                continue;
+            }
+            if (leaf.row.scope === "project") {
+                skipped.push(skip(target, label, UNINSTALL_REFUSALS["project-only"]));
+                continue;
+            }
+            const sourceId = sourceIdOf(leaf.row.selection, installed.sources);
+            if (sourceId === undefined) {
+                skipped.push(skip(target, label, "The Source of this installation is no longer registered"));
+                continue;
+            }
+            const skill = skillOf(leaf.row, sourceId);
+            const prepared = await prepareUninstall(operations, env, skill, installed);
+            if (prepared.kind === "ready")
+                items.push({ kind: "managed", id: target.id, label, skill, prepared });
+            else
+                skipped.push(skip(target, label, UNINSTALL_REFUSALS[prepared.kind]));
+        }
+        catch (error) {
+            skipped.push(skip(target, label, errorText(error)));
+        }
+    }
+    return { items, skipped, installations };
+}
+function resultOf(outcomes, skipped) {
+    const lines = [...outcomes.map((outcome) => outcome.line), ...skipped.map(({ label, reason }) => `Skipped ${label}: ${reason}`)];
+    return {
+        message: { kind: outcomes.some((outcome) => !outcome.ok) ? "error" : "ok", text: lines.join("\n") },
+        applied: outcomes.filter((outcome) => outcome.ok).map((outcome) => outcome.item.id),
+    };
+}
+/** Execute step: each item is rechecked and applied on its own against the records the previous items were expected to leave. */
+export async function runBulkUninstall(plan, operations, env) {
+    let expected = plan.installations;
+    const outcomes = await runBatch(plan.items, async (item) => {
+        await assertNoDrift(operations, expected);
+        if (item.kind === "unmanaged") {
+            const result = await runUnmanagedRemoval({ ...item.prepared, installations: expected }, operations, env);
+            if (result.kind === "error")
+                throw new Error(result.text);
+            return result.text;
+        }
+        await runUninstall({ ...item.prepared, installations: expected }, operations, env);
+        // Only the record this item removed moves the baseline the next item is checked against.
+        expected = expected.filter((record) => !item.prepared.plan.selections.some((removed) => sameRecord(removed, record)));
+        return `Removed ${item.label}`;
+    }, (item, error) => (item.kind === "unmanaged" ? errorText(error) : `Failed ${item.label}: ${errorText(error)}`));
+    return resultOf(outcomes, plan.skipped);
+}
+/** Managed user-global leaves that can gain hosts, and the leaves that cannot with their reasons. */
+export function classifyHostTargets(context, targets) {
+    const ready = [];
+    const skipped = [];
+    for (const target of targets) {
+        const label = labelOf(target);
+        const { leaf } = target;
+        if (leaf.kind === "unmanaged") {
+            skipped.push(skip(target, label, "Host changes are not available for unmanaged skills"));
+        }
+        else if (leaf.row.scope === "project") {
+            skipped.push(skip(target, label, "Project installations are managed with the CLI"));
+        }
+        else if (missingHosts(leaf.row.selection).length === 0) {
+            skipped.push(skip(target, label, "already has every host"));
+        }
+        else {
+            const sourceId = sourceIdOf(leaf.row.selection, context.installed.sources);
+            if (sourceId === undefined)
+                skipped.push(skip(target, label, "The Source of this installation is no longer registered"));
+            else
+                ready.push({ id: target.id, label, skill: skillOf(leaf.row, sourceId), hosts: leaf.row.selection.hosts });
+        }
+    }
+    return { ready, skipped };
+}
+/** Plan step after the checklist: each item adds only the chosen hosts it lacks. */
+export async function prepareBulkHostAddition(context, targets, alreadySkipped, chosen) {
+    const { operations, env, installed } = context;
+    const installations = await listRecords(operations);
+    const items = [];
+    const skipped = [...alreadySkipped];
+    for (const target of targets) {
+        const lacking = chosen.filter((host) => !target.hosts.includes(host));
+        if (lacking.length === 0) {
+            skipped.push({ id: target.id, label: target.label, reason: `already has ${chosen.join(", ")}` });
+            continue;
+        }
+        try {
+            items.push({ id: target.id, label: target.label, prepared: await prepareHostAddition(operations, env, target.skill, installed, lacking) });
+        }
+        catch (error) {
+            skipped.push({ id: target.id, label: target.label, reason: errorText(error) });
+        }
+    }
+    return { items, skipped, installations };
+}
+/** Execute step: the single exposure confirmation covers every item; each one is rechecked on its own. */
+export async function runBulkHostAddition(plan, operations, env) {
+    let expected = plan.installations;
+    const outcomes = await runBatch(plan.items, async (item) => {
+        await assertNoDrift(operations, expected);
+        const line = await runHostAddition({ ...item.prepared, installations: expected }, operations, env);
+        // Only the record this item updated moves the baseline the next item is checked against.
+        const { selection, updated } = item.prepared.plan;
+        expected = expected.map((record) => (sameRecord(record, selection) ? updated : record));
+        return line;
+    }, (item, error) => `Failed ${item.label}: ${errorText(error)}`);
+    return resultOf(outcomes, plan.skipped);
+}
+function cancel(context, text) {
+    context.setMessage({ kind: "ok", text });
+    context.browse();
+}
+/** Runs a prepare step in the busy mode; a plan with items goes to its confirmation, otherwise the reasons are reported. */
+async function preparePlan(context, label, prepare, confirmation) {
+    context.setMode({ kind: "busy", label });
+    try {
+        const plan = await prepare();
+        if (!context.isMounted())
+            return;
+        if (plan.items.length === 0) {
+            context.setMessage({ kind: "error", text: plan.skipped.map(({ label: name, reason }) => `Skipped ${name}: ${reason}`).join("\n") });
+            context.browse();
+            return;
+        }
+        context.setMode(confirmation(plan));
+    }
+    catch (error) {
+        if (!context.isMounted())
+            return;
+        context.setMessage({ kind: "error", text: errorText(error) });
+        context.browse();
+    }
+}
+/** `u` with marks: prepares every marked leaf, then asks once. */
+export function startBulkUninstall(context, targets) {
+    return preparePlan(context, `Preparing uninstall of ${count(targets.length, "item")}...`, () => prepareBulkUninstall(context, targets), (plan) => ({ kind: "confirm-bulk-uninstall", plan }));
+}
+/** `h` with marks: asks the hosts once, for the union of what the eligible items lack. */
+export function startBulkHostAddition(context, targets) {
+    const { ready, skipped } = classifyHostTargets(context, targets);
+    const choices = PROJECT_HOSTS.filter((host) => ready.some((target) => !target.hosts.includes(host)));
+    if (ready.length === 0) {
+        context.setMessage({ kind: "error", text: skipped.map(({ label, reason }) => `Skipped ${label}: ${reason}`).join("\n") });
+        return;
+    }
+    context.setMessage(undefined);
+    context.setMode({ kind: "bulk-hosts", targets: ready, skipped, choices, cursor: 0, selected: [] });
+}
+function prepareHosts(context, mode) {
+    return preparePlan(context, `Preparing host change of ${count(mode.targets.length, "item")}...`, () => prepareBulkHostAddition(context, mode.targets, mode.skipped, mode.selected), (plan) => ({ kind: "confirm-bulk-hosts", plan }));
+}
+async function apply(context, label, action) {
+    context.setMode({ kind: "busy", label });
+    let result;
+    try {
+        result = await action();
+    }
+    catch (error) {
+        result = { message: { kind: "error", text: errorText(error) }, applied: [] };
+    }
+    context.unmark(result.applied);
+    await context.finish(result.message);
+}
+/** Handles a key in a bulk mode; returns false for any other mode. */
+export function handleBulkKey(context, mode, input, key) {
+    const current = mode;
+    const { operations, env } = context;
+    switch (current.kind) {
+        case "bulk-hosts": {
+            applyChecklistOutcome(hostChecklistKey(current, current.choices, input, key), {
+                cancel: () => cancel(context, "Add hosts cancelled"),
+                update: (state) => context.setMode({ ...current, ...state }),
+                submit: () => void prepareHosts(context, current),
+                setMessage: context.setMessage,
+            });
+            return true;
+        }
+        case "confirm-bulk-uninstall":
+            answerYesNo(input, key, () => {
+                void apply(context, `Removing ${count(current.plan.items.length, "item")}...`, () => runBulkUninstall(current.plan, operations, env));
+            }, () => cancel(context, "Uninstall cancelled"));
+            return true;
+        case "confirm-bulk-hosts":
+            answerYesNo(input, key, () => context.setMode({ kind: "confirm-bulk-exposure", plan: current.plan }), () => cancel(context, "Add hosts cancelled"));
+            return true;
+        case "confirm-bulk-exposure":
+            answerYesNo(input, key, () => {
+                void apply(context, `Changing hosts of ${count(current.plan.items.length, "item")}...`, () => runBulkHostAddition(current.plan, operations, env));
+            }, () => cancel(context, "Add hosts cancelled"));
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/src/tui/catalog-actions.js

@@ -0,0 +1,9 @@
+import { PROJECT_HOSTS } from "../project-manifest.js";
+/** Host choices in checklist order; labels use the project's host identifiers. */
+export const HOST_CHOICES = PROJECT_HOSTS;
+export const SCOPE_CHOICES = ["project", "user-global"];
+/** `beta` for one Skill, `3 skills` for a batch. */
+export function describeSkills(skills) {
+    return skills.length === 1 ? skills[0].name : `${skills.length} skills`;
+}
+export const BROWSE = { kind: "browse" };

package/dist/src/tui/catalog-browse.js

@@ -0,0 +1,59 @@
+import { leavesOf, skillKey } from "./catalog-tree.js";
+import { navigateTree } from "./tree-navigation.js";
+import { toggleNode } from "./tree.js";
+import { toggledMark } from "./view-state.js";
+/** Space: marks the highlighted Skill for a batch install. */
+function markRow(context, row) {
+    if (row.node.data.kind !== "skill") {
+        context.setMessage({ kind: "error", text: "Mark skills, not source rows" });
+        return;
+    }
+    context.setMessage(undefined);
+    context.marks.setMarked(toggledMark(context.marks.markedRef.current, row.node.id));
+}
+/** `a`: marks every listed Skill, or clears the marks when they are all marked already. */
+function markAllListed(context) {
+    const { markedRef, setMarked } = context.marks;
+    const leaves = leavesOf(context.navigation.latestRoots());
+    if (leaves.length === 0) {
+        context.setMessage({ kind: "error", text: "There are no skills to select" });
+        return;
+    }
+    context.setMessage(undefined);
+    setMarked(leaves.every((skill) => markedRef.current.has(skillKey(skill))) ? new Set() : new Set(leaves.map(skillKey)));
+}
+/** `i`: installs the marked Skills that are listed, or the highlighted one. */
+function chooseHosts(context, row) {
+    // Only what is listed installs: marks on Skills hidden by the filter are ignored.
+    const marked = leavesOf(context.navigation.latestRoots())
+        .filter((skill) => context.marks.markedRef.current.has(skillKey(skill)));
+    const highlighted = row.node.data.kind === "skill" ? [row.node.data.skill] : [];
+    const chosen = marked.length > 0 ? marked : highlighted;
+    if (chosen.length === 0) {
+        context.setMessage({ kind: "error", text: "Install is not available for source rows; highlight a skill or mark some with space" });
+        return;
+    }
+    context.setMessage(undefined);
+    context.setAction({ kind: "host", skills: chosen, cursor: 0, selected: [] });
+}
+/** Keys while browsing the Catalog: navigation, filter, marks and starting an install. */
+export function handleCatalogBrowseKey(context, input, key) {
+    const snapshot = context.navigation.latest();
+    if (navigateTree(context.navigation, snapshot, context.height, input, key))
+        return;
+    const row = snapshot.visible[snapshot.at];
+    if (key.return && row)
+        context.navigation.setExpanded(toggleNode(snapshot.open, row));
+    else if (input === "/")
+        context.filter.open();
+    else if (key.escape && context.filter.filterRef.current.query !== "")
+        context.filter.clear(context.navigation.restart);
+    else if (input === "s" && context.canWiden)
+        context.toggleAll();
+    else if (input === " " && row)
+        markRow(context, row);
+    else if (input === "a")
+        markAllListed(context);
+    else if (input === "i" && context.ready && row)
+        chooseHosts(context, row);
+}

package/dist/src/tui/catalog-filter.js

@@ -0,0 +1,20 @@
+export const initialFilter = { editing: false, query: "" };
+export function filterReducer(state, event) {
+    switch (event.type) {
+        case "open":
+            return { ...state, editing: true };
+        case "edit":
+            return state.editing ? { editing: true, query: event.query } : state;
+        case "keep":
+            return { ...state, editing: false };
+        case "clear":
+            return initialFilter;
+    }
+}
+/** Case-insensitive match on name and description. */
+export function filterSkills(skills, query) {
+    const needle = query.trim().toLowerCase();
+    if (needle === "")
+        return skills;
+    return skills.filter((skill) => skill.name.toLowerCase().includes(needle) || skill.description.toLowerCase().includes(needle));
+}

package/dist/src/tui/catalog-flow.js

@@ -0,0 +1,107 @@
+import { BROWSE, describeSkills, HOST_CHOICES, SCOPE_CHOICES } from "./catalog-actions.js";
+import { prepareInstall, runInstall } from "./catalog-installs.js";
+import { skillKey } from "./catalog-tree.js";
+import { errorText, runBatch } from "./batch.js";
+import { answerYesNo, applyChecklistOutcome, hostChecklistKey, versionInputKey } from "./mode-keys.js";
+function cancel(context) {
+    context.setMessage({ kind: "ok", text: "Install cancelled" });
+    context.setAction(BROWSE);
+}
+async function startInstall(context, skills, choice) {
+    context.setAction({ kind: "busy", label: `Refreshing source and preparing install of ${describeSkills(skills)}...` });
+    const items = [];
+    for (const skill of skills) {
+        try {
+            items.push({ skill, prepared: await prepareInstall(context.operations, context.env, skill, choice) });
+        }
+        catch (error) {
+            items.push({ skill, error: errorText(error) });
+        }
+    }
+    if (!context.isMounted())
+        return;
+    if (items.every((item) => item.prepared === undefined)) {
+        const text = items.length === 1 ? items[0].error : items.map((item) => `Failed ${item.skill.name}: ${item.error}`).join("\n");
+        context.setMessage({ kind: "error", text });
+        context.setAction(BROWSE);
+        return;
+    }
+    context.setAction({ kind: "confirm-install", items });
+}
+/** Applies the prepared items one by one; a failure is reported for that item and the rest still run. */
+async function confirmInstall(context, items, exposure) {
+    context.setAction({ kind: "busy", label: `Installing ${describeSkills(items.map((item) => item.skill))}...` });
+    const outcomes = await runBatch(items, async ({ prepared, error }) => {
+        if (prepared === undefined)
+            throw new Error(error);
+        return (await runInstall(prepared, context.operations, exposure && prepared.additionalHostExposure)).join(" ");
+    }, ({ skill }, caught) => `Failed ${skill.name}: ${errorText(caught)}`);
+    const lines = outcomes.map((outcome) => outcome.line);
+    const failed = new Set(outcomes.filter((outcome) => !outcome.ok).map((outcome) => skillKey(outcome.item.skill)));
+    // Installed Skills leave the list; only the failed ones stay marked for another try.
+    context.keepMarked(failed);
+    await context.finish({ kind: failed.size > 0 ? "error" : "ok", text: lines.join("\n") });
+}
+function handleHostKey(context, mode, input, key) {
+    applyChecklistOutcome(hostChecklistKey(mode, HOST_CHOICES, input, key), {
+        cancel: () => cancel(context),
+        update: (state) => context.setAction({ ...mode, ...state }),
+        submit: (hosts) => context.setAction({ kind: "scope", skills: mode.skills, hosts }),
+        setMessage: context.setMessage,
+    });
+}
+function handleScopeKey(context, mode, input, key) {
+    const scope = SCOPE_CHOICES[Number(input) - 1];
+    if (key.escape)
+        cancel(context);
+    else if (scope)
+        context.setAction({ kind: "version", skills: mode.skills, hosts: mode.hosts, scope });
+}
+function handleVersionKey(context, mode, input, key) {
+    if (key.escape)
+        cancel(context);
+    else if (input === "1")
+        void startInstall(context, mode.skills, { hosts: mode.hosts, scope: mode.scope, version: { policy: "latest" } });
+    else if (input === "2")
+        context.setAction({ ...mode, kind: "fixed", value: "" });
+}
+function handleFixedKey(context, mode, input, key) {
+    const outcome = versionInputKey(mode.value, input, key);
+    if (outcome.kind === "cancel")
+        cancel(context);
+    else if (outcome.kind === "submit") {
+        void startInstall(context, mode.skills, { hosts: mode.hosts, scope: mode.scope, version: { policy: "fixed", version: mode.value } });
+    }
+    else if (outcome.kind === "edit")
+        context.setAction({ ...mode, value: outcome.value });
+}
+/** Handles a key in one of the install modes; `browse` and `busy` ignore keys. */
+export function handleCatalogActionKey(context, mode, input, key) {
+    switch (mode.kind) {
+        case "host":
+            handleHostKey(context, mode, input, key);
+            return;
+        case "scope":
+            handleScopeKey(context, mode, input, key);
+            return;
+        case "version":
+            handleVersionKey(context, mode, input, key);
+            return;
+        case "fixed":
+            handleFixedKey(context, mode, input, key);
+            return;
+        case "confirm-install":
+            answerYesNo(input, key, () => {
+                if (mode.items.some((item) => item.prepared?.additionalHostExposure))
+                    context.setAction({ ...mode, kind: "confirm-exposure" });
+                else
+                    void confirmInstall(context, mode.items, false);
+            }, () => cancel(context));
+            return;
+        case "confirm-exposure":
+            answerYesNo(input, key, () => void confirmInstall(context, mode.items, true), () => cancel(context));
+            return;
+        default:
+            return;
+    }
+}

package/dist/src/tui/catalog-installs.js

@@ -0,0 +1,189 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { defaultProjectManifestPath, parseProjectManifest, PROJECT_HOSTS, ProjectManifestStore, } from "../project-manifest.js";
+import { defaultProjectSkillTreeAccess, executeSingleInstall, needsAdditionalHostExposure, outputSingleInstallPreview, planSingleInstall, } from "../skill-install.js";
+import { executeHostAddition, executeHostRemoval, planHostAddition, planHostRemoval, } from "../skill-hosts.js";
+import { executeSkillRemoval, planSkillRemoval, SkillSelectionError, userGlobalRemovalOptions, } from "../skill-removal.js";
+import { scanUserGlobalSkillInventory } from "../user-global-skill-inventory.js";
+export const NO_INSTALLED = { global: [], project: [], sources: [], unmanagedNames: new Set() };
+function homeOf(environment) {
+    return path.resolve(environment.homeDirectory ?? homedir());
+}
+function manifestStoreOf(environment) {
+    return environment.projectManifestStore ??
+        new ProjectManifestStore(defaultProjectManifestPath(path.resolve(environment.projectRoot ?? process.cwd())));
+}
+/** Loads user-global and project installations; anything unavailable or unreadable yields no markers. */
+export async function loadInstalledSkills(operations, environment) {
+    const [global, project, sources] = await Promise.all([
+        operations.listUserGlobalInstallations?.().catch(() => []) ?? [],
+        manifestStoreOf(environment).load().then((manifest) => manifest.skills, () => []),
+        operations.listSources().catch(() => []),
+    ]);
+    const unmanagedNames = await scanUserGlobalSkillInventory({ homeDirectory: homeOf(environment), managedInstallations: global }).then((inventory) => new Set([...inventory.unmanaged, ...inventory.symlinks].map((entry) => entry.name)), () => new Set());
+    return { global, project, sources, unmanagedNames };
+}
+/** Whether an unmanaged copy with the Skill's directory name exists on disk (the name an install would use). */
+export function hasUnmanagedCopy(skill, installed) {
+    return installed.unmanagedNames.has(path.posix.basename(skill.path));
+}
+function matchesSource(source, sourceId, sources) {
+    if (source.kind === "builtin")
+        return source.id === sourceId;
+    if (!("url" in source))
+        return false;
+    return sources.some((candidate) => candidate.kind === "git" && candidate.id === sourceId && candidate.url === source.url);
+}
+function recordsFor(records, skill, sources) {
+    return records.filter((record) => record.path === skill.path && matchesSource(record.source, skill.sourceId, sources));
+}
+/** Whether the Skill is installed user-global or in the project manifest (same Source and path). */
+export function isInstalled(skill, installed) {
+    return [installed.global, installed.project].some((records) => recordsFor(records, skill, installed.sources).length > 0);
+}
+/** Plan step: refreshes the Source, resolves and inspects the install and renders the same preview the CLI prints. */
+export async function prepareInstall(operations, environment, skill, choice) {
+    const request = {
+        scope: choice.scope,
+        sourceId: skill.sourceId,
+        skillPath: skill.path,
+        hosts: choice.hosts,
+        version: choice.version,
+        // Confirming the preview is the review the CLI asks for with --portable-v1.
+        portableV1: true,
+        // Planning with confirmed set refreshes a Git Source before resolving, so
+        // the preview shows exactly what y installs (the CLI does this on --yes).
+        confirmed: true,
+        overwrite: false,
+        confirmAdditionalHostExposure: false,
+    };
+    const sourceAccess = environment.sourceAccess ?? defaultProjectSkillTreeAccess();
+    const base = { operations, sourceAccess, environment };
+    let plan;
+    let manifestStore;
+    if (choice.scope === "user-global") {
+        if (!operations.listUserGlobalInstallations || !operations.addUserGlobalInstallation) {
+            throw new Error("Configured Source operations cannot manage user-global installation state");
+        }
+        plan = await planSingleInstall(request, {
+            ...base,
+            root: homeOf(environment),
+            existing: await operations.listUserGlobalInstallations(),
+            recordedIn: "user-global state",
+        });
+    }
+    else {
+        manifestStore = manifestStoreOf(environment);
+        plan = await planSingleInstall(request, {
+            ...base,
+            root: path.resolve(environment.projectRoot ?? process.cwd()),
+            existing: (await manifestStore.load()).skills,
+            recordedIn: manifestStore.path,
+        });
+    }
+    const lines = [];
+    outputSingleInstallPreview(plan, (line) => lines.push(line));
+    // The TUI confirms interactively, so the CLI's --yes wording does not apply.
+    const preview = lines.filter((line) => !line.startsWith("  confirmation:"));
+    const additionalHostExposure = needsAdditionalHostExposure(plan.inspection, choice.hosts);
+    if (additionalHostExposure) {
+        preview.push("  ADDITIONAL HOST EXPOSURE: an identical Skill already exists; installing adds the missing Host location (equivalent to --confirm-additional-host) and needs a separate confirmation");
+    }
+    return { plan, manifestStore, preview, runsExternalCommand: plan.resolved.method !== undefined, additionalHostExposure };
+}
+/** Execute step: installs and persists the record; returns the result lines. */
+export async function runInstall(prepared, operations, confirmAdditionalHostExposure = false) {
+    const lines = [];
+    const { manifestStore } = prepared;
+    const plan = confirmAdditionalHostExposure
+        ? { ...prepared.plan, request: { ...prepared.plan.request, confirmAdditionalHostExposure: true } }
+        : prepared.plan;
+    const persist = manifestStore
+        ? async (record) => {
+            // Read at persist time: a batch installs several Skills, and each record must keep the ones saved before it.
+            const current = (await manifestStore.load()).skills;
+            await manifestStore.save(parseProjectManifest({ version: 1, skills: [...current, record] }));
+        }
+        : (record) => operations.addUserGlobalInstallation(record);
+    await executeSingleInstall(plan, persist, (line) => lines.push(line));
+    return lines;
+}
+/** Why a preparation that is not `ready` refuses, in the words the TUI shows. */
+export const UNINSTALL_REFUSALS = {
+    unsupported: "Uninstall is not supported by the configured operations",
+    "not-installed": "Skill is not installed",
+    "project-only": "Project uninstall is not supported",
+};
+/** Plan step for removing the highlighted Skill's user-global installation. */
+export async function prepareUninstall(operations, environment, skill, installed) {
+    if (!operations.listUserGlobalInstallations || !operations.removeUserGlobalInstallations) {
+        return { kind: "unsupported" };
+    }
+    const installations = await operations.listUserGlobalInstallations();
+    const matches = recordsFor(installations, skill, installed.sources);
+    if (matches.length === 0) {
+        return { kind: recordsFor(installed.project, skill, installed.sources).length > 0 ? "project-only" : "not-installed" };
+    }
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    const record = matches[0];
+    const plan = await planSkillRemoval([record], options);
+    const scopeNote = `  removes the whole user-global installation, from hosts: ${record.hosts.join(", ")}`;
+    return { kind: "ready", plan: { ...plan, preview: [...plan.preview, scopeNote] }, installations };
+}
+/** Execute step: rechecks the plan, then removes files and records. */
+export async function runUninstall(prepared, operations, environment) {
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    await executeSkillRemoval(prepared.plan, operations, options, prepared.installations);
+}
+/** The user-global record of the Skill, when it is installed there. */
+export function globalRecord(skill, installed) {
+    return recordsFor(installed.global, skill, installed.sources)[0];
+}
+/** Hosts a user-global record does not serve yet, in checklist order. */
+export function missingHosts(record) {
+    return PROJECT_HOSTS.filter((host) => !record.hosts.includes(host));
+}
+/** Reads the current records so a host change never acts on a stale checklist. */
+async function currentGlobalRecord(operations, skill, installed) {
+    if (!operations.listUserGlobalInstallations || !operations.updateUserGlobalInstallation || !operations.removeUserGlobalInstallations) {
+        throw new Error("Configured Source operations cannot manage user-global installation state");
+    }
+    const installations = await operations.listUserGlobalInstallations();
+    const record = recordsFor(installations, skill, installed.sources)[0];
+    if (!record)
+        throw new Error("Skill is not installed");
+    return { record, installations };
+}
+/** A selection problem is a normal message for the TUI, like any other failed step. */
+function asMessage(error) {
+    throw error instanceof SkillSelectionError ? new Error(error.message) : error;
+}
+/** Plan step for exposing an installed user-global Skill to more hosts. */
+export async function prepareHostAddition(operations, environment, skill, installed, hosts) {
+    const { record, installations } = await currentGlobalRecord(operations, skill, installed);
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    const plan = await planHostAddition(record, hosts, options).catch(asMessage);
+    return { plan, installations, preview: plan.preview };
+}
+/** Execute step: the TUI's separate exposure confirmation stands in for `--confirm-additional-host`. */
+export async function runHostAddition(prepared, operations, environment) {
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    await executeHostAddition(prepared.plan, operations, options, prepared.installations, true);
+    return `Added hosts ${prepared.plan.hosts.join(", ")} to ${prepared.plan.selection.path}`;
+}
+/** Plan step for removing some hosts of a user-global Skill; removing all of them is a full removal. */
+export async function prepareHostRemoval(operations, environment, skill, installed, hosts) {
+    const { record, installations } = await currentGlobalRecord(operations, skill, installed);
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    const plan = await planHostRemoval(record, hosts, options).catch(asMessage);
+    return { plan, installations, preview: plan.kind === "full" ? plan.plan.preview : plan.preview };
+}
+/** Execute step: rechecks, removes only the chosen hosts' locations, then reconciles the record. */
+export async function runHostRemoval(prepared, operations, environment, skill) {
+    const options = userGlobalRemovalOptions(homeOf(environment), environment.installationOptions);
+    await executeHostRemoval(prepared.plan, operations, options, prepared.installations);
+    const { plan } = prepared;
+    return plan.kind === "full"
+        ? `Removed ${skill.name} (${skill.path})`
+        : `Removed hosts ${plan.removed.join(", ")} from ${plan.selection.path}`;
+}