@iseoane/agent-depot 0.6.13 → 0.6.14

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

@@ -1,65 +1,48 @@
-import { previewText } from "./updates.js";
+import { quoteText } from "../preview-model.js";
+import { appPlanLines } from "./app-actions.js";
+import { fieldLine, renderPreviewDocument, textLine } from "./preview-render.js";
 export function updateModePreviewLines(mode) {
     switch (mode.kind) {
         case "preview":
-            return [
-                ...mode.prepared.lines,
-                ...mode.prepared.appFailures.map(previewText),
-                ...mode.prepared.packageFailures.map(previewText),
-                ...mode.prepared.failures.map(({ item, message }) => previewText(`Preview failed for ${JSON.stringify(item.id)}: ${message}`)),
-            ];
+            return renderPreviewDocument(mode.prepared.document);
         case "manual":
-            return [
-                { kind: "field", label: "App:", value: mode.plan.entry.recipe?.name ?? mode.plan.entry.file },
-                { kind: "field", label: "Environment:", value: mode.plan.environment },
-                { kind: "field", label: "Working directory:", value: mode.plan.cwd },
-                { kind: "field", label: "Manual:", value: mode.plan.manual ?? "" },
-                ...(mode.reason === undefined ? [] : [previewText(mode.reason)]),
-            ];
+            return [...appPlanLines(mode.plan), ...(mode.reason === undefined ? [] : [textLine(mode.reason)])];
         case "confirm-paths":
             return [
-                previewText("Outside .agents/skills and .claude/skills:"),
-                ...mode.prepared.nonCanonicalPaths.map(({ scope, path }) => ({
-                    kind: "field",
-                    label: "Path:",
-                    value: `[${scope}] ${JSON.stringify(path)}`,
-                })),
+                textLine("Outside .agents/skills and .claude/skills:"),
+                ...mode.prepared.nonCanonicalPaths.map(({ scope, path }) => fieldLine("Path:", `[${scope}] ${quoteText(path)}`)),
             ];
         default:
             return [];
     }
 }
+/**
+ * What else confirming does besides applying: replaced local changes and external commands. Kept to
+ * a bounded length so a narrow footer still fits the question after it; the warnings name every Skill.
+ */
+function previewEffects(prepared) {
+    const replaced = prepared.groups.flatMap((group) => group.applicable.filter((item) => group.overwriteShown.has(item.id)));
+    const commands = prepared.document.sections.flatMap(({ items }) => items.flatMap(({ rows }) => rows.filter((row) => row.kind === "command"))).length;
+    return [
+        ...(replaced.length === 1 ? [`replaces ${replaced[0].selection.path}'s local changes`] : []),
+        ...(replaced.length > 1 ? [`replaces local changes in ${replaced.length} Skills`] : []),
+        ...(commands === 0 ? [] : [`runs ${commands} ${commands === 1 ? "command" : "commands"}`]),
+    ];
+}
 export function updateModePreviewChrome(mode) {
     switch (mode.kind) {
         case "preview": {
             const count = mode.prepared.applicable.length;
-            const question = `Apply ${count} ${count === 1 ? "update" : "updates"}? y/n`;
-            return {
-                title: "Update batch preview",
-                questions: ["Scroll to end before confirming; n cancels.", question],
-                footerRows: 2,
-            };
+            if (count === 0)
+                return { title: "Update batch preview", consequence: "Nothing can be applied.", cancel: "[Enter/Esc] back" };
+            const action = mode.prepared.document.action;
+            return { title: "Update batch preview", action, consequence: [...previewEffects(mode.prepared), `${action}? y/n`].join(" · ") };
         }
         case "manual":
-            return {
-                title: "Manual App update",
-                questions: ["Scroll to end before confirming; n cancels.", "Manual step done, check now? y/n"],
-                footerRows: 2,
-            };
+            return { title: "Manual App update", action: "Check now", consequence: "Manual step done, check now? y/n" };
         case "confirm-paths":
-            return {
-                title: "Confirm replacing non-canonical locations",
-                questions: ["Scroll to end before confirming; n cancels.", "Replace exactly these paths? y/n"],
-                footerRows: 2,
-            };
+            return { title: "Confirm replacing non-canonical locations", action: "Replace these paths", consequence: "Replace exactly these paths? y/n" };
         default:
-            return { title: "Updates", questions: ["Continue? y/n"] };
-    }
-}
-export function updateModeQuestion(mode, reachedEnd) {
-    if (mode.kind === "preview" && mode.prepared.applicable.length === 0) {
-        return "Nothing can be applied. Enter or Esc to go back.";
+            return { title: "Updates" };
     }
-    const chrome = updateModePreviewChrome(mode);
-    return reachedEnd ? chrome.questions.at(-1) ?? "Continue? y/n" : chrome.questions[0] ?? "Scroll to end before confirming; n cancels.";
 }

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

@@ -1,8 +1,9 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Box, Text, useWindowSize } from "ink";
+import { Box } from "ink";
+import { Text } from "./safe-text.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { theme } from "./theme.js";
-import { previewViewport } from "./preview-window.js";
+import { usePreviewGeometry } from "./preview-window.js";
 import { computeWindow, useListHeight } from "./window.js";
 import { BROWSE } from "./updates-mode.js";
 import { defaultExpanded } from "./tree.js";
@@ -11,7 +12,7 @@ import { useUpdatesFlow } from "./updates-flow.js";
 import { handleUpdatesKey } from "./updates-keys.js";
 import { entryId, viewOf } from "./updates-model.js";
 import { CheckStatus, EntryLine, ModePanel, UpdatesFooter } from "./updates-panel.js";
-import { previewLineText } from "./updates.js";
+import { lineText } from "./preview-render.js";
 import { updateModePreviewChrome, updateModePreviewLines } from "./updates-preview.js";
 import { useKeys } from "./keys.js";
 import { BorderPanel, Working } from "./panel-parts.js";
@@ -20,7 +21,6 @@ const NO_ENVIRONMENT = {};
 const CLOCK_TICK_MS = 10_000;
 export function UpdatesView({ operations, environment, onCapturingChange, listHeight, now }) {
     const height = useListHeight(listHeight, 9);
-    const { rows: terminalRows, columns: terminalColumns } = useWindowSize();
     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.
@@ -73,7 +73,7 @@ export function UpdatesView({ operations, environment, onCapturingChange, listHe
     const { state, load, startPreview, apply } = useUpdatesFlow({
         operations, env, clock, mounted, checkedRef, latest, setChecked, setCursor, setMode, modeRef, setMessage,
     });
-    // Entering the view refreshes the Git sources first, like `r`.
+    // Entering the view refreshes the Git sources first, like `r`, but may reuse a recent refresh (ADR 0004).
     useEffect(() => {
         void load(true);
     }, [load]);
@@ -81,10 +81,8 @@ export function UpdatesView({ operations, environment, onCapturingChange, listHe
     dataRef.current = data;
     const { shown, updatable, unknown, upToDate, entries } = viewOf(data, scope, showUnknown, expanded);
     const index = Math.min(cursor, Math.max(entries.length - 1, 0));
-    const previewGeometry = (current) => {
-        const cursor = "cursor" in current ? current.cursor : 0;
-        return previewViewport(updateModePreviewLines(current).map(previewLineText), cursor, terminalRows || 24, terminalColumns || 80, updateModePreviewChrome(current));
-    };
+    const geometry = usePreviewGeometry();
+    const previewGeometry = (current) => geometry(updateModePreviewLines(current).map(lineText), "cursor" in current ? current.cursor : 0, updateModePreviewChrome(current));
     const keyContext = {
         height,
         now: clock,
@@ -105,7 +103,7 @@ export function UpdatesView({ operations, environment, onCapturingChange, listHe
         recheck: () => {
             setMessage(undefined);
             setShowUnknown(false);
-            void load(true);
+            void load(true, true);
         },
         startPreview: () => void startPreview(),
         setMode,

package/dist/src/tui/updates.js

@@ -1,10 +1,12 @@
 import { checkAppUpdates, createAppOperations } from "../app-flow.js";
-import { displayPackageSelection, selectionKey } from "../package-model.js";
+import { displayPackageCoordinates, displayPackageSelection, selectionKey } from "../package-model.js";
 import { formatVersionPolicy } from "../skill-install.js";
-import { applyConfirmedUpdates, describeUpdatePreview, loadUpdates, previewUpdateCandidates, readScopeInstallations, } from "../update-flow.js";
+import { sourceIdForUrl } from "../git-source.js";
+import { applyConfirmedUpdates, loadUpdates, previewUpdateCandidates, readScopeInstallations, skillUpdatePreviewItem, } from "../update-flow.js";
 import { packageOperationsOf } from "./environment.js";
 import { formatVersionEvidence } from "./installations.js";
-import { installedEvidenceLabel, packagePlanLines, packageStatusLabel, packageVersionLabel, recordedVersionLabel } from "./package-rows.js";
+import { describePackageComponent, installedEvidenceLabel, packageStatusLabel, packageVersionLabel, recordedVersionLabel } from "./package-rows.js";
+import { quoteText } from "../preview-model.js";
 /** Every scope the view can assess, in display order. */
 export const UPDATE_SCOPES = ["project", "user-global"];
 const APP_STATUS_LABEL = {
@@ -32,18 +34,18 @@ function scopeInput(operations, environment, scope) {
     };
 }
 /** Refreshes through the project-source operation the install flow uses; a registered Source is refreshed by id otherwise. */
-async function refreshOne(operations, source) {
+async function refreshOne(operations, source, options) {
     if (operations.refreshProjectSource) {
-        await operations.refreshProjectSource(source);
+        await operations.refreshProjectSource(source, options);
         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);
+    await operations.refreshSource(registered.id, options);
 }
 /** Refreshes every distinct Git source the installations use, one at a time; the built-in source is skipped. */
-async function refreshSources(operations, selections) {
+async function refreshSources(operations, selections, options, session) {
     const distinct = new Map();
     for (const { source } of selections) {
         if (source.kind === "external" && "url" in source)
@@ -51,17 +53,24 @@ async function refreshSources(operations, selections) {
     }
     const refreshed = [];
     const failed = [];
+    const startedAt = session?.now();
+    let reusedAt;
     for (const source of distinct.values()) {
         const label = source.ref === undefined ? source.url : `${source.url}@${source.ref}`;
         try {
-            await refreshOne(operations, source);
+            await refreshOne(operations, source, options);
             refreshed.push(label);
+            // A refresh that finished before this check began was reused, not made now.
+            const finishedAt = session?.snapshot().get(sourceIdForUrl(source.url))?.finishedAt;
+            if (startedAt !== undefined && finishedAt !== undefined && finishedAt < startedAt) {
+                reusedAt = Math.min(reusedAt ?? finishedAt, finishedAt);
+            }
         }
         catch (error) {
             failed.push({ source: label, reason: errorText(error) });
         }
     }
-    return { attempted: true, refreshed, failed, unreadable: [] };
+    return { attempted: true, refreshed, failed, unreadable: [], ...(reusedAt === undefined ? {} : { reusedAt }) };
 }
 /**
  * Refreshes the Git sources involved (unless told otherwise), then runs the
@@ -80,7 +89,7 @@ export async function loadUpdateRows(operations, environment, options) {
             unreadable.push({ scope, reason: errorText(error) });
             return [];
         })));
-        refresh = { ...(await refreshSources(operations, installations.flat())), unreadable };
+        refresh = { ...(await refreshSources(operations, installations.flat(), { force: options.force === true }, environment.refreshSession)), unreadable };
     }
     options.onPhase?.("checking");
     const results = await Promise.all(UPDATE_SCOPES.map(async (scope) => {
@@ -163,11 +172,50 @@ export function formatAgo(elapsedMs) {
         return `${minutes} min ago`;
     return `${Math.floor(minutes / 60)} h ago`;
 }
-export function previewText(text) {
-    return { kind: "text", text };
+const PROJECT_WARNING = /^ {2}WARNING: /u;
+function counted(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
-export function previewLineText(line) {
-    return line.kind === "field" ? `${line.label} ${line.value}` : line.text;
+function appPreviewItem(plan) {
+    const rows = [];
+    if (plan.argv) {
+        rows.push({ kind: "command", argv: plan.argv, cwd: plan.cwd, ...(plan.executable === undefined ? {} : { executable: plan.executable }) });
+        if (plan.executable === undefined)
+            rows.push({ kind: "warning", text: `${quoteText(plan.argv[0])} not found in PATH` });
+    }
+    else {
+        rows.push({ kind: "field", label: "Working directory", value: plan.cwd });
+    }
+    if (plan.manual)
+        rows.push({ kind: "field", label: "Manual", value: plan.manual });
+    if (plan.warning)
+        rows.push({ kind: "warning", text: plan.warning });
+    return {
+        title: plan.entry.recipe?.name ?? plan.entry.file,
+        version: { from: plan.previousVersion ?? "unknown", to: plan.latestVersion ?? "unknown" },
+        rows,
+    };
+}
+/** The frozen plan with every fact the approval covers: origin, inventory, commands, blast radius and approval state. */
+function packagePreviewItem(row, { plan, approval }) {
+    const { descriptor, selection } = plan;
+    const rows = [
+        { kind: "field", label: "Coordinates", value: displayPackageSelection(selection) },
+        { kind: "field", label: "Origin", value: `manifest ${plan.origin.manifestDigest.slice(0, 12)}${plan.origin.resolvedCommit === undefined ? "" : `  commit ${plan.origin.resolvedCommit.slice(0, 7)}`}` },
+        { kind: "field", label: `Components (${descriptor.components.length})`, value: "" },
+        ...descriptor.components.map((component) => ({ kind: "text", text: describePackageComponent(component), indent: 1 })),
+    ];
+    if (plan.commands.length === 0) {
+        rows.push({ kind: "text", text: "This action runs no host command." }, { kind: "field", label: "Working directory", value: plan.cwd });
+    }
+    plan.commands.forEach((command, position) => rows.push({ kind: "field", label: `Step ${position + 1}`, value: command.purpose }, { kind: "command", argv: [command.executable, ...command.args], executable: command.resolvedPath ?? command.executable, cwd: plan.cwd }));
+    rows.push({ kind: "field", label: "Blast radius", value: plan.affects.map((coordinates) => displayPackageCoordinates(selection.source, coordinates)).join(", ") }, { kind: "field", label: "Approval", value: approval }, ...plan.warnings.map((warning) => ({ kind: "warning", text: warning })), ...(approval === "needs approval" ? [{ kind: "text", text: "This apply approves the declaration above." }] : []));
+    return {
+        title: descriptor.name,
+        detail: selection.host,
+        version: { from: recordedVersionLabel(row.check.installed), to: packageVersionLabel(descriptor.version) },
+        rows,
+    };
 }
 /** Plan step: previews the selection from the assessed snapshots, scope by scope. Changes nothing. */
 export async function prepareUpdates(data, selected) {
@@ -176,16 +224,28 @@ export async function prepareUpdates(data, selected) {
     const appFailures = [];
     const packagePlans = [];
     const packageFailures = [];
-    const lines = [];
     const failures = [];
+    const context = [];
+    const warnings = [];
+    const skillItems = [];
+    const appItems = [];
+    const packageItems = [];
     for (const { scope, loaded } of data.results) {
-        const items = selected.filter((row) => row.kind !== "app" && row.kind !== "package" && row.scope === scope).map((row) => row.item);
-        if (!loaded || items.length === 0)
+        const rows = selected.filter((row) => row.kind === "skill" && row.scope === scope);
+        if (!loaded || rows.length === 0)
             continue;
-        const { context } = loaded;
-        const outcome = await previewUpdateCandidates(items, context);
-        lines.push(...loaded.projectTarget.map(previewText));
-        lines.push(...outcome.plans.flatMap((plan) => describeUpdatePreview(plan, scope, context.projectRoot, "prompt").map(previewText)));
+        const outcome = await previewUpdateCandidates(rows.map((row) => row.item), loaded.context);
+        for (const line of loaded.projectTarget) {
+            if (PROJECT_WARNING.test(line))
+                warnings.push(line.replace(PROJECT_WARNING, ""));
+            else
+                context.push(line);
+        }
+        for (const plan of outcome.plans) {
+            const row = rows.find((candidate) => candidate.item === plan.item);
+            const item = skillUpdatePreviewItem(plan, scope, loaded.context.projectRoot, "prompt");
+            skillItems.push(row === undefined ? item : { ...item, version: { from: row.installed, to: row.available } });
+        }
         failures.push(...outcome.failures);
         groups.push({
             scope,
@@ -201,10 +261,7 @@ export async function prepareUpdates(data, selected) {
         try {
             const plan = await data.apps.planLifecycle(row.check.entry, "update", undefined, row.check);
             appPlans.push(plan);
-            lines.push({ kind: "field", label: "Environment:", value: plan.environment }, previewText(row.path), { kind: "field", label: "Version:", value: `${plan.previousVersion} -> ${plan.latestVersion ?? "unknown"}` }, ...(plan.argv ? [
-                { kind: "field", label: "argv:", value: JSON.stringify(plan.argv) },
-                { kind: "field", label: "Executable:", value: plan.executable ?? `${JSON.stringify(plan.argv[0])} not found in PATH` },
-            ] : []), ...(plan.manual ? [{ kind: "field", label: "Manual:", value: plan.manual }] : []), { kind: "field", label: "Working directory:", value: plan.cwd }, ...(plan.warning ? [previewText(plan.warning)] : []));
+            appItems.push(appPreviewItem(plan));
         }
         catch (error) {
             appFailures.push(`Failed ${row.path}: preview failed: ${errorText(error)}`);
@@ -217,19 +274,35 @@ export async function prepareUpdates(data, selected) {
             const plan = await data.packages.planLifecycle(row.check.installed.selection, "update");
             const approval = await data.packages.approvalStatus(row.check.installed.selection, "update");
             packagePlans.push({ plan, approval });
-            lines.push(...packagePlanLines(plan, approval).map(previewText));
-            if (approval === "needs approval")
-                lines.push(previewText("This apply approves the declaration above."));
+            packageItems.push(packagePreviewItem(row, { plan, approval }));
         }
         catch (error) {
             packageFailures.push(`Failed ${row.path}: preview failed: ${errorText(error)}`);
         }
     }
+    const applicable = [...groups.flatMap((group) => group.applicable), ...appPlans, ...packagePlans.map(({ plan }) => plan)];
+    const sections = [
+        { heading: "SKILLS", items: skillItems, noun: "Skill" },
+        { heading: "APPS", items: appItems, noun: "App" },
+        { heading: "PACKAGES", items: packageItems, noun: "Package" },
+    ].filter(({ items }) => items.length > 0);
+    const environments = new Set([...appPlans, ...packagePlans.map(({ plan }) => plan)].map((plan) => plan.environment));
     return {
         groups, apps: data.apps, appPlans, appFailures,
         packages: data.packages, packagePlans, packageFailures,
-        lines,
-        applicable: [...groups.flatMap((group) => group.applicable), ...appPlans, ...packagePlans.map(({ plan }) => plan)],
+        document: {
+            action: `Apply ${counted(applicable.length, "update")}`,
+            summary: sections.map(({ items, noun }) => counted(items.length, noun)).join(" · "),
+            context: [...context, ...[...environments].map((environment) => `Environment: ${environment}`)],
+            warnings,
+            sections: sections.map(({ heading, items }) => ({ heading, items })),
+            failures: [
+                ...failures.map(({ item, message }) => `${item.selection.path}: ${message}`),
+                ...appFailures,
+                ...packageFailures,
+            ],
+        },
+        applicable,
         failures,
         nonCanonicalPaths: groups.flatMap((group) => group.nonCanonicalPaths.map((location) => ({ scope: group.scope, path: location }))),
     };
@@ -242,17 +315,27 @@ export async function prepareUpdates(data, selected) {
  * answer (or absent callback) cancels and clears pending update evidence.
  * A Skill that became locally modified after the preview fails instead of being overwritten.
  */
-export async function runUpdates(prepared, confirmedPaths, confirmManual) {
+export async function runUpdates(prepared, confirmedPaths, confirmManual, 
+/** Called before each Skill, App and Package runs, numbered across the whole batch. */
+onProgress) {
     const updated = [];
     const failedLines = [];
+    const packagePlans = prepared.packagePlans ?? [];
+    const total = prepared.groups.reduce((sum, group) => sum + group.applicable.length, 0) + prepared.appPlans.length + packagePlans.length;
+    let position = 0;
+    const started = (kind, name) => {
+        position += 1;
+        onProgress?.({ kind, name, position, total, verb: "Updating" });
+    };
     for (const group of prepared.groups) {
-        const result = await applyConfirmedUpdates(group.applicable, group.loaded.context, confirmedPaths
+        const result = await applyConfirmedUpdates(group.applicable, { ...group.loaded.context, onItem: (item) => started("skill", item.selection.path) }, 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"}`));
     }
     for (const plan of prepared.appPlans) {
+        started("app", plan.entry.recipe.name);
         const name = `App: ${plan.entry.recipe.name}`;
         try {
             const apps = prepared.apps;
@@ -276,7 +359,8 @@ export async function runUpdates(prepared, confirmedPaths, confirmManual) {
             failedLines.push(`Failed ${name}: ${errorText(error)}`);
         }
     }
-    for (const { plan, approval } of prepared.packagePlans ?? []) {
+    for (const { plan, approval } of packagePlans) {
+        started("package", plan.descriptor.name);
         const name = `Package: ${plan.descriptor.name} (${plan.selection.host}) from ${displayPackageSelection(plan.selection)}`;
         try {
             const packages = prepared.packages;

package/dist/src/update-flow.js

@@ -67,28 +67,44 @@ export async function previewUpdateCandidates(selected, context) {
     }
     return { plans, failures, nonCanonicalPaths };
 }
-/** The preview `update apply` prints for one candidate. */
-export function describeUpdatePreview(plan, scope, projectRoot, wording = "flags") {
-    const lines = [
-        `Preview: update Skill ${JSON.stringify(plan.selection.path)} from ${plan.source.id} (scope: ${scope})`,
-        `  target: ${plan.target}`,
-    ];
+/** One candidate's preview: target, warnings to confirm, proposed changes and any external command. */
+export function skillUpdatePreviewItem(plan, scope, projectRoot, wording) {
+    const rows = [{ kind: "field", label: "target", value: plan.target }];
     if (plan.nonCanonicalPath !== undefined) {
         const relative = relativeProjectPath(projectRoot, plan.nonCanonicalPath);
-        lines.push(wording === "flags"
-            ? `  WARNING: non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); --yes together with --confirm-path ${relative} explicitly confirms replacing this exact path`
-            : `  WARNING: non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); a separate confirmation of this exact path is required to replace it`);
+        rows.push({ kind: "warning", text: wording === "flags"
+                ? `non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); --yes together with --confirm-path ${relative} explicitly confirms replacing this exact path`
+                : `non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); a separate confirmation of this exact path is required to replace it` });
     }
-    lines.push(`  proposed changes: replace ${plan.snapshot.files.length} managed files and persist the new version/content baseline`);
+    rows.push({ kind: "field", label: "proposed changes", value: `replace ${plan.snapshot.files.length} managed files and persist the new version/content baseline` });
     if (plan.overwriteRequired) {
-        lines.push(wording === "flags"
-            ? "  WARNING: the installed Skill has local modifications; --yes explicitly confirms replacing them"
-            : "  WARNING: the installed Skill has local modifications; confirming replaces them");
+        rows.push({ kind: "warning", text: wording === "flags"
+                ? "the installed Skill has local modifications; --yes explicitly confirms replacing them"
+                : "the installed Skill has local modifications; confirming replaces them" });
     }
     if (plan.methodPreview) {
-        lines.push(`  external command: argv=${JSON.stringify(plan.methodPreview.argv)}`, `  external cwd: ${JSON.stringify(plan.methodPreview.cwd)}`, `  external target: ${JSON.stringify(plan.methodPreview.target)}`, "  declared changes:", ...plan.methodPreview.declaredChanges.map((change) => `    ${change}`), `  WARNING: ${plan.methodPreview.warning}`);
+        rows.push({ kind: "command", argv: plan.methodPreview.argv, cwd: plan.methodPreview.cwd }, { kind: "field", label: "external target", value: JSON.stringify(plan.methodPreview.target) }, { kind: "field", label: "declared changes", value: "" }, ...plan.methodPreview.declaredChanges.map((change) => ({ kind: "text", text: change, indent: 1 })), { kind: "warning", text: plan.methodPreview.warning });
+    }
+    return { title: plan.selection.path, detail: `${plan.source.id} · ${scope}`, rows };
+}
+/** How `update apply` prints one row of a Skill preview item. */
+function cliPreviewRow(row) {
+    switch (row.kind) {
+        case "field": return [`  ${row.label}:${row.value === "" ? "" : ` ${row.value}`}`];
+        case "text": return [`  ${"  ".repeat(row.indent ?? 0)}${row.text}`];
+        case "warning": return [`  WARNING: ${row.text}`];
+        case "command": return [
+            `  external command: argv=${JSON.stringify(row.argv)}`,
+            ...(row.cwd === undefined ? [] : [`  external cwd: ${JSON.stringify(row.cwd)}`]),
+        ];
     }
-    return lines;
+}
+/** The preview `update apply` prints for one candidate. */
+export function describeUpdatePreview(plan, scope, projectRoot, wording = "flags") {
+    return [
+        `Preview: update Skill ${JSON.stringify(plan.selection.path)} from ${plan.source.id} (scope: ${scope})`,
+        ...skillUpdatePreviewItem(plan, scope, projectRoot, wording).rows.flatMap(cliPreviewRow),
+    ];
 }
 /**
  * `--yes` alone never confirms a repository-controlled non-canonical location:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",