@iseoane/agent-depot 0.2.0 → 0.2.1

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

@@ -0,0 +1,47 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { describeSkills, HOST_CHOICES, SCOPE_CHOICES } from "./catalog-actions.js";
+import { skillKey } from "./catalog-tree.js";
+import { hasUnmanagedCopy } from "./catalog-installs.js";
+import { describeRow, UNMANAGED_MARKER } from "./catalog-tree.js";
+import { HostChecklist, PreviewLines } from "./panel-parts.js";
+import { rowStyle } from "./theme.js";
+import { theme } from "./theme.js";
+/** Scope and counts, the filter line, and why the list may be empty. */
+export function CatalogHeader({ scope, listed, installable, total, filter }) {
+    return (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["Scope: ", scope, "  ", listed, " of ", installable] }), filter.editing || filter.query !== "" ? (_jsxs(Text, { children: ["Filter: ", filter.query, filter.editing ? "_" : ""] })) : null, total === 0 ? _jsx(Text, { children: "No skills" }) : null, total > 0 && installable === 0 ? _jsx(Text, { children: "All skills are installed" }) : null, installable > 0 && listed === 0 ? _jsx(Text, { children: "No matching skills" }) : null] }));
+}
+/** One line of the Catalog tree: cursor, indent, mark box, label and the unmanaged-copy marker. */
+export function CatalogRowLine({ row, selected, marked, installed }) {
+    const { data } = row.node;
+    const isSource = data.kind === "source";
+    return (_jsxs(Text, { ...rowStyle(selected), color: isSource ? theme.group : undefined, children: [selected ? "> " : "  ", "  ".repeat(row.depth), isSource ? "" : marked ? "[x] " : "[ ] ", describeRow(row), data.kind === "skill" && hasUnmanagedCopy(data.skill, installed)
+                ? _jsxs(Text, { color: theme.marker, children: ["  ", UNMANAGED_MARKER] })
+                : null] }));
+}
+/** The prompt of the install flow; browsing shows nothing. */
+export function ActionPanel({ mode }) {
+    switch (mode.kind) {
+        case "browse":
+            return null;
+        case "host":
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Install ", describeSkills(mode.skills), ". Host (space/1-4 toggle, j/k move, Enter continue, Esc cancel):"] }), _jsx(HostChecklist, { choices: HOST_CHOICES, cursor: mode.cursor, selected: mode.selected })] }));
+        case "scope":
+            return _jsxs(Text, { children: ["Scope: ", SCOPE_CHOICES.map((scope, i) => `${i + 1} ${scope}`).join("  "), "  (Esc cancel)"] });
+        case "version":
+            return _jsx(Text, { children: "Version: 1 latest  2 fixed  (Esc cancel)" });
+        case "fixed":
+            return _jsxs(Text, { children: ["Fixed version: ", mode.value, "_  (Enter confirm, Esc cancel)"] });
+        case "confirm-install": {
+            const ready = mode.items.filter((item) => item.prepared !== undefined);
+            const single = mode.items.length === 1;
+            return (_jsxs(Box, { flexDirection: "column", children: [mode.items.map(({ skill, prepared, error }) => prepared === undefined ? (_jsxs(Text, { color: theme.error, children: ["Cannot install ", skill.name, ": ", error] }, skillKey(skill))) : (_jsxs(Box, { flexDirection: "column", children: [single ? null : _jsx(Text, { color: theme.group, children: skill.name }), _jsx(PreviewLines, { lines: prepared.preview })] }, skillKey(skill)))), ready.some((item) => item.prepared?.runsExternalCommand) ? _jsx(Text, { color: theme.warning, children: "This install runs an external command (see above)." }) : null, _jsxs(Text, { children: ["Install ", describeSkills(ready.map((item) => item.skill)), "? y/n"] })] }));
+        }
+        case "confirm-exposure": {
+            const names = mode.items.filter((item) => item.prepared?.additionalHostExposure).map((item) => item.skill.name);
+            return (_jsxs(Text, { color: theme.warning, children: [names.length === 1 ? `An identical ${names[0]} already exists` : `Identical copies of ${names.join(", ")} already exist`, "; adding the missing Host location needs separate confirmation (CLI: --confirm-additional-host). Confirm? y/n"] }));
+        }
+        case "busy":
+            return _jsx(Text, { children: mode.label });
+    }
+}

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

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+import { filterReducer, initialFilter } from "./catalog-filter.js";
+import { loadInstalledSkills, NO_INSTALLED } from "./catalog-installs.js";
+/** Discovers the Skills of one Source, or of all of them, and again whenever those inputs change. */
+export function useCatalogSkills(operations, sourceId, all) {
+    const [state, setState] = useState({ status: "loading" });
+    useEffect(() => {
+        let cancelled = false;
+        if (!operations.discoverSkills) {
+            setState({ status: "error", message: "Discovery is not supported by the configured operations" });
+            return;
+        }
+        setState({ status: "loading" });
+        void (async () => {
+            try {
+                const ids = all || sourceId === undefined
+                    ? (await operations.listSources()).map((source) => source.id)
+                    : [sourceId];
+                const skills = await operations.discoverSkills(ids);
+                if (!cancelled)
+                    setState({ status: "ready", skills });
+            }
+            catch (error) {
+                if (!cancelled)
+                    setState({ status: "error", message: error instanceof Error ? error.message : String(error) });
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [operations, sourceId, all]);
+    return state;
+}
+/** The Skills already installed, loaded on mount and on demand. */
+export function useInstalledSkills(operations, env, mounted) {
+    const [installed, setInstalled] = useState(NO_INSTALLED);
+    const [installedReady, setInstalledReady] = useState(false);
+    const reloadInstalled = useCallback(async () => {
+        const loaded = await loadInstalledSkills(operations, env);
+        if (!mounted.current)
+            return;
+        setInstalled(loaded);
+        setInstalledReady(true);
+    }, [operations, env, mounted]);
+    useEffect(() => {
+        void reloadInstalled();
+    }, [reloadInstalled]);
+    return { installed, installedReady, reloadInstalled };
+}
+/**
+ * The filter box. Its state is mirrored in refs, updated first, so the shell
+ * never sees a stale capturing state and keystrokes delivered in one burst are not lost.
+ */
+export function useCatalogFilter(actionRef, onCapturingChange) {
+    const [filter, dispatchFilter] = useReducer(filterReducer, initialFilter);
+    const filterRef = useRef(initialFilter);
+    // The typed query, so keystrokes delivered in one burst are not lost to stale closures.
+    const typed = useRef("");
+    const queryRef = useRef(filter.query);
+    queryRef.current = filter.query;
+    const dispatch = (event) => {
+        filterRef.current = filterReducer(filterRef.current, event);
+        onCapturingChange?.(filterRef.current.editing || actionRef.current.kind !== "browse");
+        dispatchFilter(event);
+    };
+    const edit = (query, restartList) => {
+        typed.current = query;
+        restartList();
+        dispatch({ type: "edit", query });
+    };
+    const clear = (restartList) => {
+        typed.current = "";
+        queryRef.current = "";
+        restartList();
+        dispatch({ type: "clear" });
+    };
+    const open = () => {
+        typed.current = filterRef.current.query;
+        dispatch({ type: "open" });
+    };
+    const handleEditKey = (input, key, restartList) => {
+        if (key.escape)
+            clear(restartList);
+        else if (key.return)
+            dispatch({ type: "keep" });
+        else if (key.backspace || key.delete)
+            edit(typed.current.slice(0, -1), restartList);
+        else if (input !== "" && !key.ctrl && !key.meta)
+            edit(typed.current + input, restartList);
+    };
+    return { filter, filterRef, queryRef, open, clear, handleEditKey };
+}

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

@@ -0,0 +1,35 @@
+import { defaultExpanded } from "./tree.js";
+const DESCRIPTION_LIMIT = 60;
+export const UNMANAGED_MARKER = "on disk, unmanaged · adopt it from Installations";
+export const skillKey = (skill) => `skill:${skill.sourceId}:${skill.path}`;
+function truncate(text) {
+    return text.length > DESCRIPTION_LIMIT ? `${text.slice(0, DESCRIPTION_LIMIT - 3)}...` : text;
+}
+/** Skills grouped by Source in first-seen order; a Source with no Skills never appears. */
+export function buildTree(skills) {
+    const bySource = new Map();
+    for (const skill of skills)
+        bySource.set(skill.sourceId, [...(bySource.get(skill.sourceId) ?? []), skill]);
+    return [...bySource].map(([sourceId, members]) => ({
+        id: `source:${sourceId}`,
+        data: { kind: "source", sourceId, count: members.length },
+        children: members.map((skill) => ({ id: skillKey(skill), data: { kind: "skill", skill } })),
+    }));
+}
+function allSourceIds(roots) {
+    return new Set(roots.filter((root) => (root.children?.length ?? 0) > 0).map((root) => root.id));
+}
+/** While a filter is set every matching source is open so the matches show; otherwise only the first. */
+export function openByDefault(nodes, query) {
+    return query === "" ? defaultExpanded(nodes) : allSourceIds(nodes);
+}
+export function describeRow(row) {
+    const { data } = row.node;
+    if (data.kind === "source")
+        return `${row.expanded ? "▾" : "▸"} ${data.sourceId} (${data.count})`;
+    return `${data.skill.name}  ${truncate(data.skill.description)}`;
+}
+/** The Skills under the tree's Sources, in display order. */
+export function leavesOf(roots) {
+    return roots.flatMap((root) => (root.children ?? []).flatMap((child) => child.data.kind === "skill" ? [child.data.skill] : []));
+}

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

@@ -0,0 +1,89 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { BROWSE } from "./catalog-actions.js";
+import { handleCatalogBrowseKey } from "./catalog-browse.js";
+import { filterSkills } from "./catalog-filter.js";
+import { handleCatalogActionKey } from "./catalog-flow.js";
+import { isInstalled } from "./catalog-installs.js";
+import { ActionPanel, CatalogHeader, CatalogRowLine } from "./catalog-panel.js";
+import { ListFooter } from "./panel-parts.js";
+import { useCatalogFilter, useCatalogSkills, useInstalledSkills } from "./catalog-state.js";
+import { buildTree, leavesOf, openByDefault, skillKey } from "./catalog-tree.js";
+import { theme } from "./theme.js";
+import { useTreeNavigation } from "./tree-navigation.js";
+import { useMarks, useMounted } from "./view-state.js";
+import { computeWindow, useListHeight } from "./window.js";
+import { useKeys } from "./keys.js";
+const NO_ENVIRONMENT = {};
+export function CatalogView({ operations, sourceId, onCapturingChange, environment, listHeight }) {
+    const height = useListHeight(listHeight, 6);
+    const env = environment ?? NO_ENVIRONMENT;
+    const [all, setAll] = useState(sourceId === undefined);
+    const mounted = useMounted();
+    const marks = useMarks();
+    const [message, setMessage] = useState();
+    const [action, setActionState] = useState(BROWSE);
+    // Mirrors the action mode synchronously, like the filter, so later keystrokes and the shell never see stale state.
+    const actionRef = useRef(BROWSE);
+    const filter = useCatalogFilter(actionRef, onCapturingChange);
+    const state = useCatalogSkills(operations, sourceId, all);
+    const { installed, installedReady, reloadInstalled } = useInstalledSkills(operations, env, mounted);
+    const setAction = (next) => {
+        actionRef.current = next;
+        onCapturingChange?.(filter.filterRef.current.editing || next.kind !== "browse");
+        setActionState(next);
+    };
+    const skills = state.status === "ready" ? state.skills : [];
+    const installable = useMemo(() => skills.filter((skill) => !isInstalled(skill, installed)), [state, installed]);
+    const visible = useMemo(() => filterSkills(installable, filter.filter.query), [installable, filter.filter.query]);
+    const roots = useMemo(() => buildTree(visible), [visible]);
+    const navigation = useTreeNavigation(roots, (nodes) => openByDefault(nodes, filter.queryRef.current));
+    // Discovering again starts the list over.
+    const { restart } = navigation;
+    useEffect(restart, [operations, sourceId, all, restart]);
+    const { rows, index } = navigation;
+    const flow = {
+        operations,
+        env,
+        setAction,
+        setMessage,
+        isMounted: () => mounted.current,
+        keepMarked: marks.setMarked,
+        finish: async (result) => {
+            await reloadInstalled();
+            if (!mounted.current)
+                return;
+            setMessage(result);
+            setAction(BROWSE);
+        },
+    };
+    const browse = {
+        navigation,
+        height,
+        marks,
+        filter,
+        canWiden: sourceId !== undefined,
+        ready: state.status === "ready",
+        toggleAll: () => setAll((value) => !value),
+        setMessage,
+        setAction,
+    };
+    useKeys((input, key) => {
+        const mode = actionRef.current;
+        if (mode.kind !== "browse")
+            handleCatalogActionKey(flow, mode, input, key);
+        else if (filter.filterRef.current.editing)
+            filter.handleEditKey(input, key, navigation.restart);
+        else
+            handleCatalogBrowseKey(browse, input, key);
+    });
+    const scope = all || sourceId === undefined ? "all sources" : sourceId;
+    if (state.status === "loading" || (state.status === "ready" && !installedReady))
+        return _jsx(Text, { children: "Loading skills..." });
+    if (state.status === "error")
+        return _jsxs(Text, { color: theme.error, children: ["Error: ", state.message] });
+    const window = computeWindow(rows.length, index, height);
+    const selectedCount = leavesOf(roots).filter((skill) => marks.marked.has(skillKey(skill))).length;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(CatalogHeader, { scope: scope, listed: visible.length, installable: installable.length, total: skills.length, filter: filter.filter }), rows.slice(window.start, window.end).map((row, offset) => (_jsx(CatalogRowLine, { row: row, selected: window.start + offset === index, marked: marks.marked.has(row.node.id), installed: installed }, row.node.id))), _jsx(ListFooter, { indicator: window.indicator, selectedCount: selectedCount, message: message }), _jsx(ActionPanel, { mode: action })] }));
+}

package/dist/src/tui/environment.js

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

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

@@ -0,0 +1,114 @@
+import { startBulkHostAddition, startBulkUninstall } from "./bulk-actions.js";
+import { skillOf, sourceIdOf } from "./installations.js";
+import { leavesOf, targetOf } from "./installations-tree.js";
+import { startHostAddition, startUninstall } from "./manage-actions.js";
+import { startUnmanagedRemoval } from "./unmanaged-actions.js";
+import { navigateTree } from "./tree-navigation.js";
+import { toggleNode } from "./tree.js";
+import { toggledMark } from "./view-state.js";
+/** Why a key does nothing on a group row. */
+const GROUP_ROW_MESSAGE = {
+    A: "Adoption is not available for group rows",
+    u: "Uninstall is not available for group rows",
+    h: "Host changes are not available for group rows",
+    i: "Host changes are not available for group rows",
+};
+/** The marked leaves in display order; marks whose rows no longer exist are ignored. */
+function markedTargets(context) {
+    const roots = context.navigation.latestRoots();
+    return leavesOf(roots).filter((node) => context.marks.markedRef.current.has(node.id)).flatMap((node) => targetOf(node) ?? []);
+}
+function markRow(context, row) {
+    if (!row)
+        return;
+    if (row.node.data.kind === "group") {
+        context.setMessage({ kind: "error", text: "Mark skills, not group rows" });
+        return;
+    }
+    context.setMessage(undefined);
+    context.marks.setMarked(toggledMark(context.marks.markedRef.current, row.node.id));
+}
+/** `a`: marks every listed leaf, or unmarks them when they are all marked already. */
+function markAllListed(context, visible) {
+    const { markedRef, setMarked } = context.marks;
+    const leaves = visible.filter((candidate) => candidate.node.data.kind !== "group").map((candidate) => candidate.node.id);
+    if (leaves.length === 0) {
+        context.setMessage({ kind: "error", text: "There are no skills to select" });
+        return;
+    }
+    context.setMessage(undefined);
+    const all = leaves.every((id) => markedRef.current.has(id));
+    setMarked(all
+        ? new Set([...markedRef.current].filter((id) => !leaves.includes(id)))
+        : new Set([...markedRef.current, ...leaves]));
+}
+function actOnUnmanaged(context, group, input, key) {
+    if (input === "u")
+        startUnmanagedRemoval(context.manage, group);
+    else if (input === "A" || key.return)
+        context.startAdoption(group);
+    else
+        context.setMessage({ kind: "error", text: "Host changes are not available for unmanaged skills" });
+}
+function actOnInstallation(context, data, item, input, key) {
+    if (input === "A" || key.return) {
+        context.setMessage({ kind: "error", text: "Adoption applies to unmanaged skills; u uninstalls and h adds hosts here" });
+        return;
+    }
+    if (item.row.scope === "project") {
+        context.setMessage({ kind: "error", text: input === "u" ? "Project uninstall is not supported" : "Project installations are managed with the CLI" });
+        return;
+    }
+    const sourceId = sourceIdOf(item.row.selection, data.sources);
+    if (sourceId === undefined) {
+        context.setMessage({ kind: "error", text: "The Source of this installation is no longer registered" });
+        return;
+    }
+    const skill = skillOf(item.row, sourceId);
+    if (input === "u")
+        startUninstall(context.manage, skill);
+    else
+        startHostAddition(context.manage, skill);
+}
+/** `A`, Enter, `u`, `h` and `i` on the highlighted row. */
+function actOnRow(context, snapshot, row, input, key) {
+    const { data } = context;
+    if (!row || !data)
+        return;
+    const item = row.node.data;
+    if (item.kind === "group") {
+        if (key.return)
+            context.navigation.setExpanded(toggleNode(snapshot.open, row));
+        else
+            context.setMessage({ kind: "error", text: GROUP_ROW_MESSAGE[input] });
+        return;
+    }
+    context.setMessage(undefined);
+    if (item.kind === "unmanaged")
+        actOnUnmanaged(context, item.group, input, key);
+    else
+        actOnInstallation(context, data, item, input, key);
+}
+/** Keys while browsing: navigation, marks, bulk actions and the per-row actions. */
+export function handleBrowseKey(context, input, key) {
+    const snapshot = context.navigation.latest();
+    if (navigateTree(context.navigation, snapshot, context.height, input, key))
+        return;
+    const row = snapshot.visible[snapshot.at];
+    const rowAction = input === "A" || key.return || input === "u" || input === "h" || input === "i";
+    if (input === " ")
+        markRow(context, row);
+    else if (input === "a")
+        markAllListed(context, snapshot.visible);
+    else if ((input === "u" || input === "h" || input === "i") && context.data && markedTargets(context).length > 0) {
+        // Marks, including those on collapsed rows, turn the action into a bulk one.
+        context.setMessage(undefined);
+        const targets = markedTargets(context);
+        if (input === "u")
+            void startBulkUninstall(context.manage, targets);
+        else
+            startBulkHostAddition(context.manage, targets);
+    }
+    else if (rowAction)
+        actOnRow(context, snapshot, row, input, key);
+}

package/dist/src/tui/installations-mode.js

@@ -0,0 +1 @@
+export const BROWSE = { kind: "browse" };

package/dist/src/tui/installations-panel.js

@@ -0,0 +1,27 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { HOST_CHOICES } from "./catalog-actions.js";
+import { ManagePanel } from "./manage-panel.js";
+import { HostChecklist, PreviewLines } from "./panel-parts.js";
+import { theme } from "./theme.js";
+/** The prompt of the adoption and manage modes; browsing shows nothing. */
+export function ModePanel({ mode }) {
+    switch (mode.kind) {
+        case "browse":
+            return null;
+        case "pick":
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Adopt ", mode.entry.name, ": several Source Skills match. j/k move, Enter select, Esc cancel:"] }), mode.candidates.map((skill, position) => (_jsxs(Text, { children: [position === mode.cursor ? "> " : "  ", skill.path, "  ", skill.sourceId] }, `${skill.sourceId}:${skill.path}`)))] }));
+        case "host":
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Adopt ", mode.entry.name, " as ", mode.skill.path, ". Host (space/1-4 toggle, j/k move, Enter continue, Esc cancel):"] }), _jsx(HostChecklist, { choices: HOST_CHOICES, cursor: mode.cursor, selected: mode.selected })] }));
+        case "version":
+            return _jsx(Text, { children: "Version: 1 latest  2 fixed  (Esc cancel)" });
+        case "fixed":
+            return _jsxs(Text, { children: ["Fixed version: ", mode.value, "_  (Enter confirm, Esc cancel)"] });
+        case "confirm":
+            return mode.adoption.verdict.adoptable ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(PreviewLines, { lines: mode.adoption.prepared.preview }), mode.adoption.prepared.runsExternalCommand ? _jsx(Text, { color: theme.warning, children: "This install runs an external command (see above)." }) : null, _jsxs(Text, { children: ["Adopt ", mode.entry.name, "? y/n"] })] })) : (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: theme.error, children: mode.adoption.verdict.reason }), _jsx(Text, { children: "Enter/Esc to go back" })] }));
+        case "confirm-exposure":
+            return (_jsxs(Text, { color: theme.warning, children: ["Adopting ", mode.entry.name, " adds the missing Host location and exposes it to more hosts; this needs separate confirmation (CLI: --confirm-additional-host). Confirm? y/n"] }));
+        default:
+            return _jsx(ManagePanel, { mode: mode });
+    }
+}

package/dist/src/tui/installations-rows.js

@@ -0,0 +1,11 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from "ink";
+import { describeDetails, describeLinks, describeNode, markersOf } from "./installations-tree.js";
+import { rowStyle, theme } from "./theme.js";
+/** One line of the Installations tree: cursor, indent, mark box, label and the leaf's details. */
+export function TreeRowLine({ row, selected, marked }) {
+    const item = row.node.data;
+    const leaf = !row.expandable && item.kind !== "group";
+    const prefix = `${selected ? "> " : "  "}${"  ".repeat(row.depth)}${leaf ? (marked ? "[x] " : "[ ] ") : ""}`;
+    return (_jsxs(Text, { ...rowStyle(selected), color: item.kind === "group" ? theme.group : undefined, children: [prefix, describeNode(row), item.kind === "installation" ? (_jsxs(Text, { color: theme.marker, children: ["  ", describeDetails(item.row), markersOf(item.row) === "" ? "" : `  ${markersOf(item.row)}`] })) : null, item.kind === "unmanaged" && describeLinks(item.group) !== "" ? (_jsxs(Text, { color: theme.marker, children: ["  ", describeLinks(item.group)] })) : null] }));
+}

package/dist/src/tui/installations-tree.js

@@ -0,0 +1,68 @@
+/** Managed installations of one scope, grouped by Source in first-seen order. */
+function sourceNodes(scope, rows) {
+    const bySource = new Map();
+    for (const row of rows)
+        bySource.set(row.source, [...(bySource.get(row.source) ?? []), row]);
+    return [...bySource].map(([source, members]) => ({
+        id: `source:${scope}:${source}`,
+        data: { kind: "group", label: `${source} (${members.length})` },
+        children: members.map((row) => ({
+            id: `installation:${scope}:${source}:${row.selection.installation?.path ?? row.selection.path}`,
+            data: { kind: "installation", row },
+        })),
+    }));
+}
+/** Scope, then Source, then Skills; Unmanaged is its own group. Counts come from data already loaded. */
+export function buildTree(data) {
+    const roots = [];
+    if (data.global !== undefined) {
+        roots.push({
+            id: "scope:user-global",
+            data: { kind: "group", label: `Managed (user-global) (${data.global.length})` },
+            children: sourceNodes("user-global", data.global),
+        });
+    }
+    roots.push({
+        id: "scope:project",
+        data: { kind: "group", label: `Managed (project) (${data.project.length})` },
+        children: sourceNodes("project", data.project),
+    });
+    roots.push({
+        id: "scope:unmanaged",
+        data: { kind: "group", label: `Unmanaged (user-global) (${data.unmanaged.length})` },
+        children: data.unmanaged.map((group) => ({ id: `unmanaged:${group.name}`, data: { kind: "unmanaged", group } })),
+    });
+    return roots;
+}
+/** Version, policy and hosts of a leaf; `adopted` / `modified` only when true (the legend explains them). */
+export function describeDetails({ selection, policy, installed }) {
+    return `${installed} (${policy})  [${selection.hosts.join(", ")}]`;
+}
+export function markersOf({ adopted, modified }) {
+    return [adopted ? "adopted" : "", modified ? "modified" : ""].filter((flag) => flag !== "").join(" ");
+}
+/** Every leaf of the tree in display order, whether or not its group is open. */
+export function leavesOf(roots) {
+    return roots.flatMap((node) => (node.children === undefined ? (node.data.kind === "group" ? [] : [node]) : leavesOf(node.children)));
+}
+export function targetOf(node) {
+    const { data } = node;
+    if (data.kind === "installation")
+        return { id: node.id, leaf: { kind: "installation", row: data.row } };
+    if (data.kind === "unmanaged")
+        return { id: node.id, leaf: { kind: "unmanaged", group: data.group } };
+    return undefined;
+}
+export function describeNode(row) {
+    const { data } = row.node;
+    if (data.kind === "group")
+        return `${row.expandable ? (row.expanded ? "▾" : "▸") : " "} ${data.label}`;
+    if (data.kind === "installation")
+        return data.row.selection.path;
+    return `${data.group.name} [${data.group.hosts.join(", ")}]`;
+}
+/** `symlink → <target>` for the locations that are links, one entry per distinct target. */
+export function describeLinks(group) {
+    const targets = [...new Set(group.locations.flatMap((location) => location.linkTarget === undefined ? [] : [location.linkTarget]))];
+    return targets.length === 0 ? "" : `symlink → ${targets.join(", ")}`;
+}

package/dist/src/tui/installations-view.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { loadInstallations } from "./installations.js";
+import { BROWSE } from "./installations-mode.js";
+import { errorText } from "./batch.js";
+import { handleAdoptionKey, startAdoption } from "./adoption-actions.js";
+import { handleBrowseKey } from "./installations-browse.js";
+import { handleManageKey } from "./manage-actions.js";
+import { ModePanel } from "./installations-panel.js";
+import { TreeRowLine } from "./installations-rows.js";
+import { buildTree, leavesOf, markersOf } from "./installations-tree.js";
+import { ListFooter } from "./panel-parts.js";
+import { useTreeNavigation } from "./tree-navigation.js";
+import { defaultExpanded } from "./tree.js";
+import { theme } from "./theme.js";
+import { useMarks, useMounted } from "./view-state.js";
+import { computeWindow, useListHeight } from "./window.js";
+import { useKeys } from "./keys.js";
+const NO_ENVIRONMENT = {};
+const LEGEND = "adopted: tracked in place · modified: changed on disk";
+export function InstallationsView({ operations, environment, onCapturingChange, listHeight }) {
+    const height = useListHeight(listHeight, 7);
+    const env = environment ?? NO_ENVIRONMENT;
+    const [state, setState] = useState({ status: "loading" });
+    const [mode, setModeState] = useState(BROWSE);
+    // Mirrors the mode synchronously so later keystrokes and the shell never see stale state.
+    const modeRef = useRef(BROWSE);
+    const marks = useMarks();
+    const mounted = useMounted();
+    const [message, setMessage] = useState();
+    const setMode = (next) => {
+        modeRef.current = next;
+        onCapturingChange?.(next.kind !== "browse");
+        setModeState(next);
+    };
+    const reload = useCallback(async () => {
+        try {
+            const data = await loadInstallations(operations, env);
+            if (mounted.current)
+                setState({ status: "ready", data });
+        }
+        catch (error) {
+            if (mounted.current)
+                setState({ status: "error", message: errorText(error) });
+        }
+    }, [operations, env, mounted]);
+    useEffect(() => {
+        void reload();
+    }, [reload]);
+    const data = state.status === "ready" ? state.data : undefined;
+    const roots = useMemo(() => (data ? buildTree(data) : []), [data]);
+    const navigation = useTreeNavigation(roots, defaultExpanded);
+    const { rows, index } = navigation;
+    const installed = useMemo(() => ({
+        global: (data?.global ?? []).map((row) => row.selection),
+        project: (data?.project ?? []).map((row) => row.selection),
+        sources: data?.sources ?? [],
+        unmanagedNames: new Set(),
+    }), [data]);
+    const manage = {
+        operations,
+        env,
+        installed,
+        setMode,
+        browse: () => setMode(BROWSE),
+        setMessage,
+        isMounted: () => mounted.current,
+        unmark: (ids) => marks.setMarked(new Set([...marks.markedRef.current].filter((id) => !ids.includes(id)))),
+        finish: async (result) => {
+            await reload();
+            if (!mounted.current)
+                return;
+            setMessage(result);
+            setMode(BROWSE);
+        },
+    };
+    const adoption = {
+        operations,
+        env,
+        setMode,
+        browse: manage.browse,
+        setMessage,
+        isMounted: manage.isMounted,
+        reload,
+    };
+    const browse = {
+        navigation,
+        height,
+        marks,
+        data,
+        manage,
+        startAdoption: (group) => void startAdoption(adoption, group),
+        setMessage,
+    };
+    useKeys((input, key) => {
+        const current = modeRef.current;
+        if (current.kind === "browse")
+            handleBrowseKey(browse, input, key);
+        else if (!handleManageKey(manage, current, input, key))
+            handleAdoptionKey(adoption, current, input, key);
+    });
+    if (state.status === "loading")
+        return _jsx(Text, { children: "Loading installations..." });
+    if (state.status === "error")
+        return _jsxs(Text, { color: theme.error, children: ["Error: ", state.message] });
+    const ready = state.data;
+    const window = computeWindow(rows.length, index, height);
+    const listed = rows.slice(window.start, window.end);
+    const selectedCount = leavesOf(roots).filter((node) => marks.marked.has(node.id)).length;
+    // The legend explains the markers, so it shows only while a rendered row carries one.
+    const legendNeeded = listed.some((row) => row.node.data.kind === "installation" && markersOf(row.node.data.row) !== "");
+    return (_jsxs(Box, { flexDirection: "column", children: [ready.global === undefined ? _jsx(Text, { children: "User-global installations are not supported by the configured operations" }) : null, ready.projectError === undefined ? null : _jsxs(Text, { color: theme.error, children: ["Error: ", ready.projectError] }), listed.map((row, offset) => (_jsx(TreeRowLine, { row: row, selected: window.start + offset === index, marked: marks.marked.has(row.node.id) }, row.node.id))), _jsx(ListFooter, { indicator: window.indicator, selectedCount: selectedCount, message: message }), legendNeeded ? _jsx(Text, { color: theme.muted, children: LEGEND }) : null, _jsx(ModePanel, { mode: mode })] }));
+}