@iseoane/agent-depot 0.2.0 → 0.2.1

package/dist/src/tui/updates-keys.js

@@ -0,0 +1,95 @@
+import { answerYesNo } from "./mode-keys.js";
+import { pageStep } from "./window.js";
+const SCOPE_KEYS = new Map([["t", "all"], ["p", "project"], ["g", "user-global"]]);
+/** Moves the cursor with the arrows, j/k and paging; returns whether the key was one of them. */
+function moveCursorKey(context, snapshot, input, key) {
+    const last = Math.max(snapshot.entries.length - 1, 0);
+    const { at } = snapshot;
+    if (key.downArrow || input === "j")
+        context.setCursor(Math.min(at + 1, last));
+    else if (key.upArrow || input === "k")
+        context.setCursor(Math.max(at - 1, 0));
+    else if (key.pageDown)
+        context.setCursor(Math.min(at + pageStep(context.height), last));
+    else if (key.pageUp)
+        context.setCursor(Math.max(at - pageStep(context.height), 0));
+    else
+        return false;
+    return true;
+}
+/** Space toggles the highlighted update, `a` selects them all. */
+function selectKey(context, snapshot, input) {
+    if (input === " ") {
+        const entry = snapshot.entries[snapshot.at];
+        if (entry?.kind !== "update")
+            return true;
+        const checked = context.checked();
+        context.setChecked(checked.includes(entry.row.key) ? checked.filter((id) => id !== entry.row.key) : [...checked, entry.row.key]);
+    }
+    else if (input === "a")
+        context.setChecked(snapshot.updatable.map((row) => row.key));
+    else
+        return false;
+    return true;
+}
+/** Right/left unfold and fold the "cannot be checked" rows; Enter toggles the fold or previews the selection. */
+function foldKey(context, snapshot, key) {
+    const entry = snapshot.entries[snapshot.at];
+    if (key.rightArrow) {
+        if (entry?.kind === "summary")
+            context.setShowUnknown(true);
+    }
+    else if (key.leftArrow) {
+        if (entry?.kind === "unknown")
+            context.setCursor(snapshot.updatable.length);
+        if (entry?.kind === "summary" || entry?.kind === "unknown")
+            context.setShowUnknown(false);
+    }
+    else if (key.return) {
+        if (entry?.kind === "summary")
+            context.setShowUnknown(!context.unknownShown());
+        else if (entry?.kind !== "unknown" && snapshot.data)
+            context.startPreview();
+    }
+}
+function handleBrowseKey(context, input, key) {
+    const snapshot = context.latest();
+    if (moveCursorKey(context, snapshot, input, key) || selectKey(context, snapshot, input))
+        return;
+    const scope = SCOPE_KEYS.get(input);
+    if (scope !== undefined)
+        context.changeScope(scope);
+    else if (input === "r")
+        context.recheck();
+    else
+        foldKey(context, snapshot, key);
+}
+function handlePreviewKey(context, mode, input, key) {
+    if (mode.prepared.applicable.length === 0) {
+        if (key.escape || key.return || input === "n")
+            context.cancel();
+        return;
+    }
+    answerYesNo(input, key, () => {
+        if (mode.prepared.nonCanonicalPaths.length > 0)
+            context.setMode({ ...mode, kind: "confirm-paths" });
+        else
+            context.apply(mode.prepared, []);
+    }, context.cancel);
+}
+/** Handles a key in the current Updates mode; `busy` ignores keys. */
+export function handleUpdatesKey(context, mode, input, key) {
+    switch (mode.kind) {
+        case "browse":
+            handleBrowseKey(context, input, key);
+            return;
+        case "preview":
+            handlePreviewKey(context, mode, input, key);
+            return;
+        case "confirm-paths":
+            answerYesNo(input, key, () => context.apply(mode.prepared, mode.prepared.nonCanonicalPaths), context.cancel);
+            return;
+        default:
+            return;
+    }
+}

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

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

package/dist/src/tui/updates-model.js

@@ -0,0 +1,48 @@
+export const REFRESHING = "Refreshing sources...";
+export const CHECKING = "Checking for updates...";
+export const PHASE_LABEL = { refreshing: REFRESHING, checking: CHECKING };
+/** Names the reasons worth knowing before expanding the collapsed "cannot be checked" row. */
+export function describeUnknownReasons(rows) {
+    const newer = rows.filter((row) => /^installed by a newer agent depot/i.test(row.reason)).length;
+    const pinned = rows.filter((row) => /^pinned to agent depot/i.test(row.reason)).length;
+    const parts = [
+        ...(newer > 0 ? [`${newer} installed by a newer Agent Depot`] : []),
+        ...(pinned > 0 ? [`${pinned} pinned to another Agent Depot`] : []),
+    ];
+    return parts.length === 0 ? "" : ` (${parts.join(", ")})`;
+}
+const matchesScope = (row, filter) => filter === "all" || row.scope === filter;
+/** The rows the list shows for a scope filter and fold state, and the cursor positions they make up. */
+export function viewOf(data, scope, showUnknown) {
+    const shown = (data?.rows ?? []).filter((row) => matchesScope(row, scope));
+    const updatable = shown.filter((row) => row.item.status === "updateable");
+    const unknown = shown.filter((row) => row.item.status === "unknown");
+    const upToDate = shown.filter((row) => row.item.status === "current").length;
+    const entries = [
+        ...updatable.map((row) => ({ kind: "update", row })),
+        ...(unknown.length > 0 ? [{ kind: "summary" }] : []),
+        ...(unknown.length > 0 && showUnknown ? unknown.map((row) => ({ kind: "unknown", row })) : []),
+    ];
+    return { shown, updatable, unknown, upToDate, entries };
+}
+export function describeRefresh(data) {
+    const { attempted, refreshed, failed, unreadable } = data.refresh;
+    if (!attempted)
+        return "sources not fetched again";
+    if (unreadable.length > 0) {
+        return `could not refresh: ${unreadable.map(({ scope, reason }) => `${reason} (${scope})`).join("; ")}; cached data was used`;
+    }
+    if (failed.length > 0) {
+        return `${failed.length} of ${failed.length + refreshed.length} sources could not be refreshed; their current data was used`;
+    }
+    return refreshed.length > 0 ? "sources refreshed" : "no Git sources to refresh";
+}
+/** Data for a check that failed as a whole, so the view can show the reason. */
+export function emptyData(reason, checkedAt) {
+    return {
+        results: [{ scope: "project", error: reason }],
+        rows: [],
+        refresh: { attempted: false, refreshed: [], failed: [], unreadable: [] },
+        checkedAt,
+    };
+}

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

@@ -0,0 +1,42 @@
+import { jsxs as _jsxs, Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { rowStyle, theme } from "./theme.js";
+import { CHECKING, describeRefresh, describeUnknownReasons, REFRESHING } from "./updates-model.js";
+import { formatAgo } from "./updates.js";
+import { PreviewLines } from "./panel-parts.js";
+/** What the last check found out: its age, how the sources were refreshed, and what failed. */
+export function CheckStatus({ data, now }) {
+    const errors = data.results.filter((result) => result.error !== undefined);
+    return (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["checked ", formatAgo(now - data.checkedAt), " \u00B7 ", describeRefresh(data)] }), data.refresh.failed.map((failure) => (_jsxs(Text, { color: theme.warning, children: ["refresh failed for ", failure.source, ": ", failure.reason] }, failure.source))), errors.map((result) => _jsxs(Text, { color: theme.error, children: ["Error (", result.scope, "): ", result.error] }, result.scope))] }));
+}
+/** One line of the list: an update, the fold of unassessable items, or one of those when unfolded. */
+export function EntryLine({ entry, selected, checked, view, showUnknown }) {
+    const cursor = selected ? "> " : "  ";
+    if (entry.kind === "summary") {
+        return (_jsxs(Text, { ...rowStyle(selected), color: theme.inactive, children: [cursor, view.unknown.length, " cannot be checked ", showUnknown ? "▾" : "▸", describeUnknownReasons(view.unknown)] }));
+    }
+    const { row } = entry;
+    if (entry.kind === "unknown") {
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { ...rowStyle(selected), children: [cursor, "    ", row.path, "  ", row.scope] }), _jsxs(Text, { color: theme.muted, children: ["        ", row.reason] })] }));
+    }
+    return (_jsxs(Text, { ...rowStyle(selected), children: [cursor, checked ? "[x]" : "[ ]", " ", row.path, "  ", row.scope, "  ", row.policy, "  ", row.installed, " ", "->", " ", row.available] }));
+}
+/** Under the list: the window indicator, what is up to date or selected, and the last result. */
+export function UpdatesFooter({ indicator, upToDate, updatableCount, checkedCount, message }) {
+    return (_jsxs(_Fragment, { children: [indicator ? _jsx(Text, { color: theme.muted, children: indicator }) : null, upToDate > 0 ? _jsxs(Text, { color: theme.muted, children: [upToDate, " up to date"] }) : null, updatableCount > 0 ? _jsxs(Text, { color: theme.muted, children: [checkedCount, " selected"] }) : null, message ? (_jsx(Box, { flexDirection: "column", children: message.lines.map((line, position) => _jsx(Text, { color: message.kind === "error" ? theme.error : theme.success, children: line }, position)) })) : null] }));
+}
+/** The prompt of the preview and confirmation modes; browsing and the check itself show nothing. */
+export function ModePanel({ mode }) {
+    switch (mode.kind) {
+        case "browse":
+            return null;
+        case "busy":
+            return mode.label === REFRESHING || mode.label === CHECKING ? null : _jsx(Text, { children: mode.label });
+        case "preview":
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(PreviewLines, { lines: mode.prepared.lines }), mode.prepared.failures.map(({ item, message }) => (_jsxs(Text, { color: theme.error, children: ["Preview failed for ", JSON.stringify(item.id), ": ", message] }, item.id))), mode.prepared.applicable.length === 0
+                        ? _jsx(Text, { children: "Nothing can be applied. Enter/Esc to go back" })
+                        : _jsxs(Text, { children: ["Apply ", mode.prepared.applicable.length, " ", mode.prepared.applicable.length === 1 ? "update" : "updates", "? y/n"] })] }));
+        case "confirm-paths":
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: theme.warning, children: "Confirm replacing non-canonical locations (outside .agents/skills and .claude/skills):" }), mode.prepared.nonCanonicalPaths.map((location, position) => _jsxs(Text, { color: theme.warning, children: ["  [", location.scope, "] ", JSON.stringify(location.path)] }, position)), _jsx(Text, { children: "Replace exactly these paths? y/n" })] }));
+    }
+}

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

@@ -0,0 +1,101 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { theme } from "./theme.js";
+import { computeWindow, useListHeight } from "./window.js";
+import { BROWSE } from "./updates-mode.js";
+import { useMirrored } from "./view-state.js";
+import { useUpdatesFlow } from "./updates-flow.js";
+import { handleUpdatesKey } from "./updates-keys.js";
+import { viewOf } from "./updates-model.js";
+import { CheckStatus, EntryLine, ModePanel, UpdatesFooter } from "./updates-panel.js";
+import { useKeys } from "./keys.js";
+const NO_ENVIRONMENT = {};
+/** How often the age of the check is redrawn. */
+const CLOCK_TICK_MS = 10_000;
+export function UpdatesView({ operations, environment, onCapturingChange, listHeight, now }) {
+    const height = useListHeight(listHeight, 9);
+    const env = environment ?? NO_ENVIRONMENT;
+    const clock = now ?? Date.now;
+    // Scope, cursor, fold and selection are mirrored in refs updated first, so keys delivered in one burst act on the latest state.
+    const [scope, scopeRef, setScope] = useMirrored("all");
+    const [cursor, cursorRef, setCursor] = useMirrored(0);
+    const [showUnknown, showUnknownRef, setShowUnknown] = useMirrored(false);
+    const [checked, checkedRef, setChecked] = useMirrored([]);
+    const [mode, setModeState] = useState(BROWSE);
+    // Mirrors the mode synchronously so later keystrokes and the shell never see stale state.
+    const modeRef = useRef(BROWSE);
+    const mounted = useRef(true);
+    const [message, setMessage] = useState();
+    // Only redraws, so "checked 5 min ago" moves on without a key press.
+    const [, setTick] = useState(0);
+    useEffect(() => {
+        mounted.current = true;
+        const timer = setInterval(() => setTick((value) => value + 1), CLOCK_TICK_MS);
+        // A redraw timer alone must never keep the process alive.
+        timer.unref();
+        return () => {
+            mounted.current = false;
+            clearInterval(timer);
+        };
+    }, []);
+    const setMode = useCallback((next) => {
+        modeRef.current = next;
+        onCapturingChange?.(next.kind !== "browse");
+        setModeState(next);
+    }, [onCapturingChange]);
+    const dataRef = useRef(undefined);
+    /** The list, the cursor and the fold as of the latest keystroke. */
+    const latest = () => {
+        const view = viewOf(dataRef.current, scopeRef.current, showUnknownRef.current);
+        return { ...view, data: dataRef.current, at: Math.min(cursorRef.current, Math.max(view.entries.length - 1, 0)) };
+    };
+    const changeScope = (next) => {
+        if (next === scopeRef.current)
+            return;
+        // Selected items that the new filter hides would otherwise be applied unseen.
+        setChecked([]);
+        setCursor(0);
+        setMessage(undefined);
+        setScope(next);
+    };
+    const cancel = () => {
+        setMessage({ kind: "ok", lines: ["Update cancelled"] });
+        setMode(BROWSE);
+    };
+    const { state, load, startPreview, apply } = useUpdatesFlow({
+        operations, env, clock, mounted, checkedRef, latest, setChecked, setCursor, setMode, setMessage,
+    });
+    // Entering the view refreshes the Git sources first, like `r`.
+    useEffect(() => {
+        void load(true);
+    }, [load]);
+    const data = state.status === "ready" ? state.data : undefined;
+    dataRef.current = data;
+    const { shown, updatable, unknown, upToDate, entries } = viewOf(data, scope, showUnknown);
+    const index = Math.min(cursor, Math.max(entries.length - 1, 0));
+    const keyContext = {
+        height,
+        latest,
+        checked: () => checkedRef.current,
+        setChecked,
+        setCursor,
+        unknownShown: () => showUnknownRef.current,
+        setShowUnknown,
+        changeScope,
+        recheck: () => {
+            setMessage(undefined);
+            setShowUnknown(false);
+            void load(true);
+        },
+        startPreview: () => void startPreview(),
+        setMode,
+        cancel,
+        apply: (prepared, confirmedPaths) => void apply(prepared, confirmedPaths),
+    };
+    useKeys((input, key) => handleUpdatesKey(keyContext, modeRef.current, input, key));
+    const window = computeWindow(entries.length, index, height);
+    const view = { shown, updatable, unknown, upToDate, entries };
+    const hasErrors = (data?.results ?? []).some((result) => result.error !== undefined);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: theme.accent, bold: true, children: ["Updates (scope: ", scope, ")  t all \u00B7 p project \u00B7 g user-global"] }), state.status === "loading" ? _jsx(Text, { children: state.label }) : null, data ? _jsx(CheckStatus, { data: data, now: clock() }) : null, data && !hasErrors && shown.length === 0 ? _jsx(Text, { children: "No installations" }) : null, entries.slice(window.start, window.end).map((entry, offset) => (_jsx(EntryLine, { entry: entry, selected: window.start + offset === index, checked: entry.kind === "update" && checked.includes(entry.row.key), view: view, showUnknown: showUnknown }, entry.kind === "summary" ? "summary" : entry.row.key))), _jsx(UpdatesFooter, { indicator: window.indicator, upToDate: upToDate, updatableCount: updatable.length, checkedCount: checked.length, message: message }), _jsx(ModePanel, { mode: mode })] }));
+}

package/dist/src/tui/updates.js

@@ -0,0 +1,159 @@
+import { formatVersionPolicy } from "../skill-install.js";
+import { applyConfirmedUpdates, describeUpdatePreview, loadUpdates, previewUpdateCandidates, readScopeInstallations, } from "../update-flow.js";
+import { formatVersionEvidence } from "./installations.js";
+/** Every scope the view can assess, in display order. */
+export const UPDATE_SCOPES = ["project", "user-global"];
+const STATUS_LABEL = {
+    updateable: "update available",
+    current: "up to date",
+    unknown: "cannot assess",
+};
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function scopeInput(operations, environment, scope) {
+    return {
+        scope,
+        operations,
+        ...(environment.homeDirectory === undefined ? {} : { homeDirectory: environment.homeDirectory }),
+        ...(environment.projectRoot === undefined ? {} : { projectRoot: environment.projectRoot }),
+        ...(environment.sourceAccess === undefined ? {} : { sourceAccess: environment.sourceAccess }),
+        ...(environment.projectManifestStore === undefined ? {} : { projectManifestStore: environment.projectManifestStore }),
+        ...(environment.installationOptions?.fileSystem === undefined ? {} : { installationFileSystem: environment.installationOptions.fileSystem }),
+    };
+}
+/** Refreshes through the project-source operation the install flow uses; a registered Source is refreshed by id otherwise. */
+async function refreshOne(operations, source) {
+    if (operations.refreshProjectSource) {
+        await operations.refreshProjectSource(source);
+        return;
+    }
+    const registered = (await operations.listSources()).find((candidate) => candidate.kind === "git" && candidate.url === source.url);
+    if (!registered)
+        throw new Error("the Source is not registered, so it cannot be refreshed here");
+    await operations.refreshSource(registered.id);
+}
+/** Refreshes every distinct Git source the installations use, one at a time; the built-in source is skipped. */
+async function refreshSources(operations, selections) {
+    const distinct = new Map();
+    for (const { source } of selections) {
+        if (source.kind === "external" && "url" in source)
+            distinct.set(`${source.url}\u0000${source.ref ?? ""}`, source);
+    }
+    const refreshed = [];
+    const failed = [];
+    for (const source of distinct.values()) {
+        const label = source.ref === undefined ? source.url : `${source.url}@${source.ref}`;
+        try {
+            await refreshOne(operations, source);
+            refreshed.push(label);
+        }
+        catch (error) {
+            failed.push({ source: label, reason: errorText(error) });
+        }
+    }
+    return { attempted: true, refreshed, failed, unreadable: [] };
+}
+/**
+ * Refreshes the Git sources involved (unless told otherwise), then runs the
+ * same assessment `update check` performs for every scope. A source that
+ * fails to refresh is reported and the check still uses its current data.
+ * Changes nothing but the Source caches.
+ */
+export async function loadUpdateRows(operations, environment, options) {
+    let refresh = { attempted: false, refreshed: [], failed: [], unreadable: [] };
+    if (options.refresh) {
+        options.onPhase?.("refreshing");
+        const unreadable = [];
+        const installations = await Promise.all(UPDATE_SCOPES.map((scope) => readScopeInstallations(scopeInput(operations, environment, scope)).catch((error) => {
+            unreadable.push({ scope, reason: errorText(error) });
+            return [];
+        })));
+        refresh = { ...(await refreshSources(operations, installations.flat())), unreadable };
+    }
+    options.onPhase?.("checking");
+    const results = await Promise.all(UPDATE_SCOPES.map(async (scope) => {
+        try {
+            return { scope, loaded: await loadUpdates(scopeInput(operations, environment, scope)) };
+        }
+        catch (error) {
+            return { scope, error: errorText(error) };
+        }
+    }));
+    const rows = results.flatMap(({ scope, loaded }) => (loaded?.assessment.items ?? []).map((item) => ({
+        key: `${scope}:${item.id}`,
+        scope,
+        item,
+        path: item.selection.path,
+        policy: formatVersionPolicy(item.selection.version),
+        installed: formatVersionEvidence(item.selection.installation?.resolvedVersion),
+        available: item.currentVersion === undefined ? "?" : formatVersionEvidence(item.currentVersion),
+        status: STATUS_LABEL[item.status],
+        reason: item.reason,
+    })));
+    return { results, rows, refresh, checkedAt: (options.now ?? Date.now)() };
+}
+/** `just now`, `42s ago`, `5 min ago`, `2 h ago`. */
+export function formatAgo(elapsedMs) {
+    const seconds = Math.floor(Math.max(elapsedMs, 0) / 1000);
+    if (seconds < 5)
+        return "just now";
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    return `${Math.floor(minutes / 60)} h ago`;
+}
+/** Plan step: previews the selection from the assessed snapshots, scope by scope. Changes nothing. */
+export async function prepareUpdates(data, selected) {
+    const groups = [];
+    const lines = [];
+    const failures = [];
+    for (const { scope, loaded } of data.results) {
+        const items = selected.filter((row) => row.scope === scope).map((row) => row.item);
+        if (!loaded || items.length === 0)
+            continue;
+        const { context } = loaded;
+        const outcome = await previewUpdateCandidates(items, context);
+        lines.push(...outcome.plans.flatMap((plan) => describeUpdatePreview(plan, scope, context.projectRoot, "prompt")));
+        failures.push(...outcome.failures);
+        groups.push({
+            scope,
+            loaded,
+            applicable: outcome.plans.map((plan) => plan.item),
+            nonCanonicalPaths: outcome.nonCanonicalPaths,
+            overwriteShown: new Set(outcome.plans.filter((plan) => plan.overwriteRequired).map((plan) => plan.item.id)),
+        });
+    }
+    return {
+        groups,
+        lines,
+        applicable: groups.flatMap((group) => group.applicable),
+        failures,
+        nonCanonicalPaths: groups.flatMap((group) => group.nonCanonicalPaths.map((location) => ({ scope: group.scope, path: location }))),
+    };
+}
+/**
+ * Applies exactly the previewed items, scope by scope. Confirming the preview
+ * confirms overwriting and external commands; a non-canonical path is applied
+ * only when the caller passes it (with its scope) after the separate confirmation.
+ * A Skill that became locally modified after the preview fails instead of being overwritten.
+ */
+export async function runUpdates(prepared, confirmedPaths) {
+    const updated = [];
+    const failedLines = [];
+    for (const group of prepared.groups) {
+        const result = await applyConfirmedUpdates(group.applicable, group.loaded.context, confirmedPaths
+            .filter((confirmed) => confirmed.scope === group.scope && group.nonCanonicalPaths.includes(confirmed.path))
+            .map((confirmed) => confirmed.path), group.overwriteShown);
+        updated.push(...result.updated.map((item) => `Updated ${item.selection.path}`));
+        failedLines.push(...result.failed.map((item) => `Failed ${item.selection.path}: ${item.error ?? "unknown error"}`));
+    }
+    const previewFailed = prepared.failures.map(({ item, message }) => `Failed ${item.selection.path}: preview failed: ${message}`);
+    const failed = failedLines.length + previewFailed.length;
+    return {
+        failed,
+        lines: [...updated, ...failedLines, ...previewFailed, `Update summary: ${updated.length} updated, ${failed} failed`],
+    };
+}

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

@@ -0,0 +1,42 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/** True while the view is mounted, so async work never updates an unmounted view. */
+export function useMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return mounted;
+}
+/** Marks by node id. The ref is updated first so keys in one burst see every mark. */
+export function useMarks() {
+    const [marked, setMarkedState] = useState(new Set());
+    const markedRef = useRef(new Set());
+    const setMarked = useCallback((next) => {
+        markedRef.current = next;
+        setMarkedState(next);
+    }, []);
+    return { marked, markedRef, setMarked };
+}
+/** `marks` with `id` added, or removed when it was marked. */
+export function toggledMark(marks, id) {
+    const next = new Set(marks);
+    if (!next.delete(id))
+        next.add(id);
+    return next;
+}
+/**
+ * State mirrored in a ref that is updated first, so keys delivered in one burst
+ * act on the latest value. The setter is stable.
+ */
+export function useMirrored(initial) {
+    const [value, setValue] = useState(initial);
+    const ref = useRef(initial);
+    const set = useCallback((next) => {
+        ref.current = next;
+        setValue(next);
+    }, []);
+    return [value, ref, set];
+}

package/dist/src/tui/window.js

@@ -0,0 +1,31 @@
+import { useStdout } from "ink";
+/** Rows assumed when the terminal size is unknown (for example under test renderers). */
+export const FALLBACK_TERMINAL_ROWS = 24;
+/** Lines the shell itself uses: title, tab bar, separator and footer hint. */
+export const APP_CHROME_ROWS = 4;
+const MINIMUM_ROWS = 3;
+/** The slice of a list that fits in `height` rows while keeping `selected` visible (roughly centred). */
+export function computeWindow(total, selected, height) {
+    const size = Math.max(Math.floor(height), 1);
+    if (total <= size)
+        return { start: 0, end: total, indicator: undefined };
+    const bounded = Math.min(Math.max(selected, 0), total - 1);
+    const start = Math.min(Math.max(bounded - Math.floor(size / 2), 0), total - size);
+    const end = start + size;
+    return { start, end, indicator: `${start + 1}–${end} of ${total}` };
+}
+/** How far PgUp/PgDn move the selection. */
+export function pageStep(height) {
+    return Math.max(Math.floor(height), 1);
+}
+/**
+ * Rows available to a list: the terminal height minus the shell chrome and the
+ * view's own `reserved` lines. `override` fixes the height for tests.
+ */
+export function useListHeight(override, reserved) {
+    const { stdout } = useStdout();
+    if (override !== undefined)
+        return Math.max(override, 1);
+    const rows = stdout.rows ?? FALLBACK_TERMINAL_ROWS;
+    return Math.max(rows - APP_CHROME_ROWS - reserved, MINIMUM_ROWS);
+}

package/dist/src/unmanaged-removal.js

@@ -0,0 +1,57 @@
+import { assertManagedInstallationRecordsUnchanged } from "./skill-removal.js";
+import { inspectUserGlobalSkillRemoval, removeUserGlobalSkill, removeUserGlobalSymlink, } from "./user-global-skill-inventory.js";
+/** The preview lines the CLI prints under each exact unmanaged path it will delete. */
+export function describeUnmanagedRemoval(inspection) {
+    return [
+        `  remove exact path ${JSON.stringify(inspection.path)}`,
+        "    WARNING: this is a permanent deletion; Agent Depot will not retain a backup",
+        "    WARNING: recovery through Agent Depot requires a resolvable Source and is not guaranteed",
+    ];
+}
+/** Preview lines for a symbolic link: only the link is removed, never what it points to. */
+export function describeUnmanagedSymlinkRemoval(inspection) {
+    return [
+        `  remove symbolic link ${JSON.stringify(inspection.path)} -> ${JSON.stringify(inspection.target)}`,
+        "    only the link is removed; the path it points to is kept",
+    ];
+}
+/** Rechecks the records and the inspected tree, then permanently deletes one unmanaged Skill directory. */
+export async function removeInspectedUnmanagedSkill(context, inspection, expectedManagedInstallations) {
+    const { operations, homeDirectory } = context;
+    const latestManagedInstallations = await operations.listUserGlobalInstallations();
+    assertManagedInstallationRecordsUnchanged(expectedManagedInstallations, latestManagedInstallations);
+    const latestInspection = await inspectUserGlobalSkillRemoval(inspection.path, {
+        homeDirectory,
+        managedInstallations: latestManagedInstallations,
+    });
+    assertUnmanagedInspectionUnchanged(inspection, latestInspection);
+    await removeUserGlobalSkill(inspection, {
+        homeDirectory,
+        managedInstallations: latestManagedInstallations,
+        readManagedInstallations: async () => operations.listUserGlobalInstallations(),
+        expectedManagedInstallations,
+    });
+}
+/** Rechecks the records and the inspected link, then unlinks only the link. */
+export async function removeInspectedUnmanagedSymlink(context, inspection, expectedManagedInstallations) {
+    const { operations, homeDirectory } = context;
+    const latestManagedInstallations = await operations.listUserGlobalInstallations();
+    assertManagedInstallationRecordsUnchanged(expectedManagedInstallations, latestManagedInstallations);
+    await removeUserGlobalSymlink(inspection, {
+        homeDirectory,
+        managedInstallations: latestManagedInstallations,
+        readManagedInstallations: async () => operations.listUserGlobalInstallations(),
+        expectedManagedInstallations,
+    });
+}
+/** Removes the inspected unmanaged Skills in order; the first failure stops the run, as in the CLI. */
+export async function removeInspectedUnmanagedSkills(context, inspections, expectedManagedInstallations) {
+    for (const inspection of inspections) {
+        await removeInspectedUnmanagedSkill(context, inspection, expectedManagedInstallations);
+    }
+}
+function assertUnmanagedInspectionUnchanged(expected, actual) {
+    if (expected.name !== actual.name || expected.path !== actual.path || expected.identity !== actual.identity || expected.digest !== actual.digest) {
+        throw new Error(`The inspected unmanaged Skill changed before deletion: ${JSON.stringify(expected.path)}; no path was changed`);
+    }
+}