@iseoane/agent-depot 0.6.13 → 0.6.14

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.14] - 2026-11-12
+
+### Added
+
+- The TUI names the item being installed or updated, with its position in the
+  batch (for example `Updating Skill tdd (2/5)…`); the elapsed time keeps running
+  across items and manual App steps (#104).
+- The Sources view marks each Source as not refreshed, refreshing, refreshed or
+  failed. On start the TUI refreshes registered Git Sources in the background
+  (no prompts, 60 s limit), and previews reuse a successful refresh from the last
+  hour; `r` always refreshes again (#105).
+- Exporting a Profile to an existing file offers to overwrite it after an explicit
+  confirmation; the CLI needs `profile export --out <file> --overwrite` (#107).
+
+### Changed
+
+- Every TUI confirmation uses a shared footer that shows reading progress and what
+  `y` will do; `y` is ignored until the preview has been read to the end
+  (#106, #111, #112, #113, #114).
+- The update batch preview starts with a summary and the collected warnings, then
+  groups Skills, Apps and Packages with version arrows and `$ command` lines (#108).
+- App recipe reviews and App confirmations show a header and one block per step
+  (#109, #110).
+
+### Security
+
+- A `y` that arrives together with other keys (pasted text, held arrows or Page
+  Down) never confirms; it must be pressed on its own (#115).
+- The TUI escapes control and format characters from recipes, Sources, Packages and
+  Host output in every view, so a remote `SKILL.md` or recipe can no longer send
+  terminal escape sequences or disguise a command (#116, #117).
+
 ## [0.6.13] - 2026-11-11
 
 ### Fixed

package/README.md

@@ -971,7 +971,8 @@ independently. Unknown selections and combining a block's inclusion filter with
 `--no-*` flag are errors.
 
 Stdout contains JSON only; stderr shows the preview and exclusion reasons.
-`--out` requires a new file (existing files and symlinks are not replaced).
+`--out` requires a new file unless `--overwrite` is given, which atomically replaces an
+existing regular file; directories and symlinks are never replaced.
 Profiles contain canonical Git URLs with discovery inclusion, individual Skill
 selections with recorded version policies, Hosts and user methods, complete App
 recipes (including recipes for other platforms), and Package selections as

package/dist/src/flow-progress.js

@@ -0,0 +1,6 @@
+const KIND_LABEL = { skill: "Skill", app: "App", package: "Package" };
+/** `Updating Skill tdd (2/5)…`; a batch of one has no position. */
+export function formatProgressLabel(event) {
+    const position = event.total > 1 ? ` (${event.position}/${event.total})` : "";
+    return `${event.verb} ${KIND_LABEL[event.kind]} ${event.name}${position}…`;
+}

package/dist/src/git-source.js

@@ -50,7 +50,14 @@ function gitFailureDetail(result) {
 }
 class NodeGitCommandRunner {
     async run(command, args, options = {}) {
-        const result = await runProcess(command, args, options.cwd === undefined ? {} : { cwd: options.cwd });
+        const result = await runProcess(command, args, {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+        if (result.timedOut) {
+            throw new Error(`git command timed out after ${Math.round((options.timeoutMs ?? 0) / 1000)} s`);
+        }
         if (result.code !== 0) {
             throw new Error(`git command failed: ${gitFailureDetail(result)}`);
         }
@@ -78,6 +85,11 @@ class NodeGitSnapshotCommandRunner {
     }
 }
 const SOURCE_LOCK_TIMEOUT_MS = 30_000;
+/** D2 (I0031): nobody is watching a background refresh, so it must neither prompt nor hang. */
+const BACKGROUND_REFRESH_OPTIONS = Object.freeze({
+    env: Object.freeze({ GIT_TERMINAL_PROMPT: "0" }),
+    timeoutMs: 60_000,
+});
 const SOURCE_LOCK_RETRY_MS = 10;
 /**
  * Clones each Source into a local mirror and refreshes it from the registered
@@ -90,7 +102,7 @@ export class GitSourceAccessAdapter {
         this.cachePath = options.cachePath ?? defaultGitSourceCachePath();
         this.runner = options.runner ?? new NodeGitCommandRunner();
     }
-    async refresh(source) {
+    async refresh(source, options = {}) {
         const expectedId = sourceIdForUrl(source.url);
         if (source.kind !== "git" || source.id !== expectedId) {
             throw new GitSourceAccessError(source, "the Source identity does not match its registered URL");
@@ -102,7 +114,7 @@ export class GitSourceAccessAdapter {
             await assertNoSymlinkPath(this.cachePath, "cache path");
             const release = await acquireSourceLock(`${destination}.lock`);
             try {
-                await this.refreshLocked(source, destination);
+                await this.refreshLocked(source, destination, options.background ? BACKGROUND_REFRESH_OPTIONS : undefined);
             }
             finally {
                 await release();
@@ -116,7 +128,7 @@ export class GitSourceAccessAdapter {
             throw new GitSourceAccessError(source, reason);
         }
     }
-    async refreshLocked(source, destination) {
+    async refreshLocked(source, destination, runOptions) {
         const existing = await pathType(destination);
         if (existing === "symlink") {
             throw new Error("the Source cache path is a symbolic link");
@@ -136,12 +148,12 @@ export class GitSourceAccessAdapter {
                 "--force",
                 gitSourceLocation(source.url).repositoryUrl,
                 "+refs/*:refs/*",
-            ]);
+            ], runOptions);
             return;
         }
         const temporaryDestination = `${destination}.${process.pid}.${randomUUID()}.tmp`;
         try {
-            await this.runner.run("git", ["clone", "--mirror", gitSourceLocation(source.url).repositoryUrl, temporaryDestination]);
+            await this.runner.run("git", ["clone", "--mirror", gitSourceLocation(source.url).repositoryUrl, temporaryDestination], runOptions);
             await assertNoSymlinkPath(temporaryDestination, "cache path");
             if ((await pathType(temporaryDestination)) !== "directory") {
                 throw new Error("Git clone did not create a directory mirror");

package/dist/src/preview-model.js

@@ -0,0 +1,34 @@
+// Anything outside this set could be read differently by a shell, so the argument is shown quoted.
+const PLAIN_ARGUMENT = /^[\w@%+=:,./-]+$/u;
+// What the TUI does not escape itself: spaces other than U+0020, default-ignorable code points that are not control or format, and
+// the zero-width joiner (kept in ordinary text for emoji).
+const NOT_ESCAPED_BY_TUI = /(?! )(?![\p{Cc}\p{Cf}])[\p{Zs}\p{Default_Ignorable_Code_Point}]|\u200D/gu;
+// JSON.stringify leaves these raw; shown as is, a right-to-left override, zero-width space or no-break space can make one argument
+// look like another. A plain space stays: inside the quotes it is what it looks like.
+const INVISIBLE = /(?! )[\p{Cc}\p{Cf}\p{Zs}\p{Default_Ignorable_Code_Point}\u2028\u2029]/gu;
+function quoted(argument, terminal) {
+    // The TUI escapes control and format characters once, when it draws; escaping them here too would show a real RLO as typed text.
+    if (terminal)
+        return quoteText(argument).replace(NOT_ESCAPED_BY_TUI, escapeCharacter);
+    return JSON.stringify(argument).replace(INVISIBLE, escapeCharacter);
+}
+function escapeCharacter(character) {
+    const code = character.codePointAt(0).toString(16);
+    return code.length > 4 ? `\\u{${code}}` : `\\u${code.padStart(4, "0")}`;
+}
+/** `text` in double quotes with quotes and backslashes escaped; control characters stay as they are for the TUI to escape. */
+export function quoteText(text) {
+    return `"${text.replace(/[\\"]/gu, "\\$&")}"`;
+}
+/**
+ * The argv as one shell-like line: arguments with spaces, quotes, shell metacharacters or invisible characters are JSON-quoted.
+ * With `terminal`, control and format characters are left for the TUI's own escaping.
+ */
+export function commandLine(argv, options = {}) {
+    const terminal = options.terminal === true;
+    return argv.map((argument) => PLAIN_ARGUMENT.test(argument) ? argument : quoted(argument, terminal)).join(" ");
+}
+/** Every warning row of the item, in order. */
+export function itemWarnings(item) {
+    return item.rows.flatMap((row) => row.kind === "warning" ? [row.text] : []);
+}

package/dist/src/process-runner.js

@@ -159,6 +159,7 @@ export function runProcess(command, args, options = {}) {
         const sink = childOutputSinks.getStore();
         const child = spawn(invocation.command, [...invocation.args], {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: { ...process.env, ...options.env } }),
             shell: false,
             windowsVerbatimArguments: invocation.windowsVerbatimArguments,
             // Without a capture, stdout is piped only for a sink, and then discarded after it is shown.

package/dist/src/profile-cli.js

@@ -4,10 +4,10 @@ import { applyProfileImport, buildProfileImport } from "./profile-import.js";
 import { serializeProfile } from "./profile.js";
 import { NO_PROGRESS } from "./progress.js";
 import { CliUsageError } from "./usage-error.js";
-export const EXPORT_USAGE = "agent-depot export [--out <file>] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
+export const EXPORT_USAGE = "agent-depot export [--out <file> [--overwrite]] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
 export const IMPORT_USAGE = "agent-depot import <file> [--yes] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
 export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory, packageOperations, progress = NO_PROGRESS) {
-    const { filters, out } = parseProfileOptions(values, false);
+    const { filters, out, overwrite } = parseProfileOptions(values, false);
     const plan = await progress.run("Building Profile export", () => buildProfileExport(operations, apps, {
         ...filters,
         homeDirectory,
@@ -20,7 +20,7 @@ export async function runProfileExport(values, operations, apps, output, diagnos
     if (out === undefined)
         output(content.trimEnd());
     else {
-        await writeProfileExport(out, plan.profile);
+        await writeProfileExport(out, plan.profile, { overwrite });
         diagnostic(`Exported profile to ${out}`);
     }
     return 0;
@@ -30,6 +30,7 @@ function parseProfileOptions(values, importing) {
     const filters = { sources, skills, apps: appNames, packages: packageNames };
     let out;
     let confirmed = false;
+    let overwrite = false;
     for (let index = 0; index < values.length; index++) {
         const option = values[index];
         if (option === "--yes" && importing) {
@@ -37,6 +38,11 @@ function parseProfileOptions(values, importing) {
                 throw new CliUsageError("Duplicate --yes");
             confirmed = true;
         }
+        else if (option === "--overwrite" && !importing) {
+            if (overwrite)
+                throw new CliUsageError("Duplicate --overwrite");
+            overwrite = true;
+        }
         else if (option === "--no-sources")
             filters.noSources = true;
         else if (option === "--no-skills")
@@ -66,7 +72,9 @@ function parseProfileOptions(values, importing) {
         else
             throw new CliUsageError(`Usage: ${importing ? IMPORT_USAGE : EXPORT_USAGE}`);
     }
-    return { filters, out, confirmed };
+    if (overwrite && out === undefined)
+        throw new CliUsageError("--overwrite requires --out");
+    return { filters, out, confirmed, overwrite };
 }
 export async function runProfileImport(values, operations, apps, output, environment = {}, progress = NO_PROGRESS) {
     const file = values[0];

package/dist/src/profile-export.js

@@ -1,8 +1,9 @@
-import { writeFile } from "node:fs/promises";
+import { lstat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { loadAppOwnedSkillFilter } from "./app-owned-skills.js";
 import { sourceIdForUrl } from "./git-source.js";
 import { bundleRoot, describeBundleInSource, describeCoordinates } from "./package-model.js";
+import { writeFileAtomically } from "./atomic-file.js";
 import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
 import { parseProfile, PROFILE_FORMAT, PROFILE_FORMAT_V2, serializeProfile } from "./profile.js";
 import { formatVersionPolicy } from "./skill-install.js";
@@ -219,9 +220,28 @@ export function requireProfileExportSelection(profile) {
         throw new Error("Nothing selected; nothing written.");
     }
 }
-/** Exclusively create an export artifact; never replace a file or follow a symlink. */
-export async function writeProfileExport(file, profile) {
+/** Rejects an existing destination that is not a regular file, such as a directory or symlink. */
+export async function requireOverwritableProfileExport(file) {
+    try {
+        if (!(await lstat(file)).isFile())
+            throw new Error(`${file} is not a regular file; choose another path`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/**
+ * Exclusively create an export artifact unless `overwrite` explicitly allows atomically replacing a
+ * regular file. Neither path follows a symlink: `wx` refuses it and the atomic rename replaces the entry.
+ */
+export async function writeProfileExport(file, profile, options = {}) {
     requireProfileExportSelection(profile);
+    if (options.overwrite) {
+        await requireOverwritableProfileExport(file);
+        await writeFileAtomically(file, serializeProfile(profile));
+        return;
+    }
     try {
         await writeFile(file, serializeProfile(profile), { encoding: "utf8", flag: "wx" });
     }

package/dist/src/skill-update.js

@@ -128,6 +128,7 @@ export async function applyUpdateBatch(selected, options) {
     const items = "updateable" in selected ? selected.updateable : selected;
     const results = [];
     for (const item of items) {
+        options.onItem?.(item, results.length + 1, items.length);
         try {
             const result = await applySkillUpdate(item, options);
             results.push(Object.freeze({ id: item.id, selection: item.selection, status: "updated", result }));

package/dist/src/source-refresh-session.js

@@ -0,0 +1,139 @@
+import { projectSourceOf, resolveProjectSource } from "./sources.js";
+/** ADR 0004 (amended): how long a refresh made by this process stands in for the one a preview needs. */
+const FRESHNESS_WINDOW_MS = 60 * 60 * 1000;
+const BACKGROUND_CONCURRENCY = 2;
+export function createSourceRefreshSession(operations, options = {}) {
+    const now = options.now ?? Date.now;
+    let states = new Map();
+    const inFlight = new Map();
+    const listeners = new Set();
+    const queue = [];
+    let backgroundRunning = 0;
+    const setState = (sourceId, state) => {
+        states = new Map(states).set(sourceId, state);
+        for (const listener of listeners)
+            listener();
+    };
+    // The project refresh carries the Source's own URL, so it also covers Sources missing from the registry.
+    const refreshReally = (source, background) => operations.refreshProjectSource
+        ? operations.refreshProjectSource(projectSourceOf(source), { background })
+        : operations.refreshSource(source.id, { background });
+    const start = (source, background) => {
+        const startedAt = now();
+        setState(source.id, { status: "refreshing", startedAt });
+        const running = refreshReally(source, background).then(() => {
+            inFlight.delete(source.id);
+            setState(source.id, { status: "refreshed", startedAt, finishedAt: now() });
+        }, (error) => {
+            inFlight.delete(source.id);
+            setState(source.id, { status: "failed", startedAt, finishedAt: now(), error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        });
+        inFlight.set(source.id, running);
+        return running;
+    };
+    const isFresh = (sourceId) => {
+        const state = states.get(sourceId);
+        return state?.status === "refreshed" && state.finishedAt !== undefined && now() - state.finishedAt < FRESHNESS_WINDOW_MS;
+    };
+    // Background refreshes cannot prompt and are time-limited (D2), so a user call never joins one:
+    // it waits for it to settle, then reuses its success (unless forced) or refreshes in the foreground.
+    const backgroundRuns = new Set();
+    const userRuns = new Map();
+    const refreshInBackground = (source) => {
+        const running = inFlight.get(source.id);
+        if (running)
+            return running;
+        if (isFresh(source.id))
+            return Promise.resolve();
+        const started = start(source, true);
+        backgroundRuns.add(started);
+        const forget = () => backgroundRuns.delete(started);
+        started.then(forget, forget);
+        return started;
+    };
+    const refreshForUser = (source, force) => {
+        const pending = userRuns.get(source.id);
+        // An unforced call may share any pending run; a forced one only another forced run.
+        if (pending && (pending.force || !force))
+            return pending.run;
+        const run = (async () => {
+            if (pending)
+                await pending.run.catch(() => undefined);
+            // A background refresh may start while this one waits, so wait until none is running.
+            for (let running = inFlight.get(source.id); running; running = inFlight.get(source.id)) {
+                await running.catch(() => undefined);
+            }
+            if (!force && isFresh(source.id))
+                return;
+            await start(source, false);
+        })();
+        const entry = { run, force };
+        userRuns.set(source.id, entry);
+        const forget = () => {
+            if (userRuns.get(source.id) === entry)
+                userRuns.delete(source.id);
+        };
+        run.then(forget, forget);
+        return run;
+    };
+    const drain = () => {
+        while (backgroundRunning < BACKGROUND_CONCURRENCY && queue.length > 0) {
+            const source = queue.shift();
+            backgroundRunning += 1;
+            void refreshInBackground(source)
+                .catch(() => undefined)
+                .finally(() => {
+                backgroundRunning -= 1;
+                drain();
+            });
+        }
+    };
+    return {
+        refresh: (source, refreshOptions = {}) => refreshForUser(source, refreshOptions.force === true),
+        refreshInBackground(sources) {
+            queue.push(...sources);
+            drain();
+        },
+        snapshot: () => states,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        now,
+        stop() {
+            queue.length = 0;
+        },
+        async settled() {
+            while (inFlight.size > 0 || userRuns.size > 0) {
+                await Promise.allSettled([...inFlight.values(), ...[...userRuns.values()].map((entry) => entry.run)]);
+            }
+        },
+    };
+}
+/**
+ * Routes `refreshSource` and `refreshProjectSource` through the session, so previews, Updates and
+ * Packages share and reuse refreshes. Built-in and unregistered ids keep the plain behavior and errors.
+ */
+export function withRefreshSession(operations, session) {
+    const refreshProjectSource = operations.refreshProjectSource;
+    return {
+        ...operations,
+        async refreshSource(sourceId, options) {
+            const source = (await operations.listSources()).find((candidate) => candidate.kind === "git" && candidate.id === sourceId);
+            if (!source)
+                return operations.refreshSource(sourceId, options);
+            await session.refresh(source, options);
+            return source;
+        },
+        ...(refreshProjectSource === undefined ? {} : {
+            async refreshProjectSource(projectSource, options) {
+                const source = resolveProjectSource(projectSource);
+                if (source.kind !== "git")
+                    return refreshProjectSource(projectSource, options);
+                await session.refresh(source, options);
+                return source;
+            },
+        }),
+    };
+}

package/dist/src/sources.js

@@ -72,7 +72,7 @@ export function createSourceOperations(options = {}) {
             const state = await stateStore.load();
             return Object.freeze([BUILT_IN_SOURCE, ...state.gitSources]);
         },
-        async refreshSource(sourceId) {
+        async refreshSource(sourceId, options) {
             if (sourceId === BUILT_IN_SOURCE.id) {
                 throw new BuiltInSourceError();
             }
@@ -81,7 +81,7 @@ export function createSourceOperations(options = {}) {
             if (!source) {
                 throw new SourceNotFoundError(sourceId);
             }
-            await gitAccess.refresh(source);
+            await gitAccess.refresh(source, options);
             return source;
         },
         async removeGitSource(sourceId, installations = []) {
@@ -185,12 +185,12 @@ export function createSourceOperations(options = {}) {
         async resolveProjectSource(projectSource) {
             return resolveProjectSource(projectSource);
         },
-        async refreshProjectSource(projectSource) {
+        async refreshProjectSource(projectSource, options) {
             const source = resolveProjectSource(projectSource);
             if (source.kind === "builtin") {
                 throw new BuiltInSourceError();
             }
-            await gitAccess.refresh(source);
+            await gitAccess.refresh(source, options);
             return source;
         },
         async readInstallationMethod(source, skillPath, previewTree) {

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

@@ -2,7 +2,7 @@ import { HOST_CHOICES } from "./catalog-actions.js";
 import { runInstall } from "./catalog-installs.js";
 import { errorText } from "./batch.js";
 import { defaultAdoptionHosts, findAdoptionCandidates, prepareAdoption } from "./installations.js";
-import { answerYesNo, applyChecklistOutcome, hostChecklistKey, moveCursor, versionInputKey } from "./mode-keys.js";
+import { answerYesNo, applyChecklistOutcome, hostChecklistKey, moveCursor, movePreviewCursor, versionInputKey } from "./mode-keys.js";
 import { busy } from "./working-model.js";
 function cancel(context) {
     context.setMessage({ kind: "ok", text: "Adoption cancelled" });
@@ -49,7 +49,7 @@ async function prepare(context, mode, version) {
         const adoption = await prepareAdoption(context.operations, context.env, mode.entry, mode.skill, { hosts: mode.hosts, version });
         if (!context.isMounted())
             return;
-        context.setMode({ kind: "confirm", entry: mode.entry, skill: mode.skill, adoption });
+        context.setMode({ kind: "confirm", entry: mode.entry, skill: mode.skill, adoption, cursor: 0 });
     }
     catch (error) {
         fail(context, error);
@@ -105,13 +105,32 @@ function handleFixedKey(context, mode, input, key) {
     else if (outcome.kind === "edit")
         context.setMode({ ...mode, value: outcome.value });
 }
+/** What an adoptable preview shows, so the key handler and the panel page the same rows. */
+export function adoptionPreview(mode) {
+    const { prepared } = mode.adoption;
+    const name = mode.entry.name;
+    return {
+        lines: [...prepared.preview, ...(prepared.runsExternalCommand ? ["This install runs an external command (see above)."] : [])],
+        chrome: { title: `Adopt ${name}`, action: `Adopt ${name}`, consequence: `Adopt ${name}? y/n` },
+    };
+}
+/** Pages the preview like the other footer confirmations: `y` answers only once it has all been displayed. */
 function handleConfirmKey(context, mode, input, key) {
     if (!mode.adoption.verdict.adoptable) {
         if (key.escape || key.return || input === "n")
             cancel(context);
         return;
     }
+    const { lines, chrome } = adoptionPreview(mode);
+    const viewport = context.previewGeometry(lines, mode.cursor, chrome);
+    const cursor = movePreviewCursor(mode.cursor, viewport.total, input, key, viewport.height);
+    if (cursor !== undefined) {
+        context.setMode({ ...mode, cursor });
+        return;
+    }
     answerYesNo(input, key, () => {
+        if (!viewport.reachedEnd)
+            return;
         if (mode.adoption.prepared.additionalHostExposure)
             context.setMode({ ...mode, kind: "confirm-exposure" });
         else

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

@@ -1,10 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Text, useWindowSize } from "ink";
+import { Text } from "./safe-text.js";
+import { commandLine } from "../preview-model.js";
 import { PROJECT_HOSTS } from "../project-manifest.js";
 import { errorText, runBatch } from "./batch.js";
+import { isYes } from "./keys.js";
 import { hostChecklistKey, movePreviewCursor } from "./mode-keys.js";
-import { BorderPanel, HostChecklist, PreviewConfirm, Working } from "./panel-parts.js";
-import { previewViewport } from "./preview-window.js";
+import { BorderPanel, HostChecklist, PagedPreview, Working } from "./panel-parts.js";
+import { usePreviewGeometry } from "./preview-window.js";
+import { fieldLine, lineText, span, stepBlockLines, textLine } from "./preview-render.js";
 import { theme } from "./theme.js";
 import { operationStart } from "./working-model.js";
 /** Finished items shown under a running batch; older ones are counted. */
@@ -17,51 +20,57 @@ export function isAppMode(mode) {
 /** Recipe name, falling back to the file identity for invalid recipes. */
 export const appName = (entry) => entry.recipe?.name ?? entry.file;
 function appPreviewChrome(mode) {
-    const title = mode.kind === "app-approve" ? "Recipe approval · does not install"
-        : mode.kind === "app-manual" ? "App manual step" : `App ${mode.plan.action} confirmation`;
-    const question = mode.kind === "app-approve" ? `Approve ${appName(mode.entry)}? y/n · recipe approval does not install the App.`
-        : mode.kind === "app-manual" ? "Manual step done, check now? y/n"
-            : `${mode.plan.action} ${appName(mode.plan.entry)}? y/n`;
-    return { title, questions: [question, "Scroll to end before y; n cancels."], footerRows: 2 };
+    if (mode.kind === "app-approve")
+        return recipeApprovalChrome(mode.entry);
+    if (mode.kind === "app-manual")
+        return { title: "App manual step", action: "Check now", consequence: "Manual step done, check now? y/n" };
+    const { action, entry } = mode.plan;
+    return {
+        title: `App ${action} confirmation`,
+        action: `${action[0].toUpperCase()}${action.slice(1)} ${appName(entry)}`,
+        consequence: `${action} ${appName(entry)}? y/n`,
+    };
+}
+/** Approving a recipe records consent to its commands; it installs nothing. */
+export function recipeApprovalChrome(entry) {
+    return {
+        title: "Recipe approval · does not install",
+        action: `Approve ${appName(entry)}`,
+        consequence: `Approve ${appName(entry)}? y/n · recipe approval does not install the App.`,
+    };
 }
-export function appStepLines(step) {
-    const argv = step.argv;
+/** What confirming an App step does: its name, Host and versions, then the step as one block. */
+export function appPlanLines(plan) {
+    const { previousVersion, latestVersion } = plan;
+    const both = previousVersion !== undefined && latestVersion !== undefined;
     return [
-        ...(argv ? [
-            "argv: [",
-            ...argv.map((argument, index) => `  ${JSON.stringify(argument)}${index < argv.length - 1 ? "," : ""}`),
-            "]",
-            `Executable: ${step.executable ?? `${JSON.stringify(argv[0])} not found in PATH`}`,
-        ] : []),
-        ...(step.manual ? [`Manual: ${step.manual}`] : []),
-        ...(step.declaration ? [step.declaration] : []),
-        ...(step.pattern ? [`Version pattern: ${step.pattern}`] : []),
-        ...(step.environment ? [`Environment: ${step.environment}`] : []),
-        `Working directory: ${step.cwd}`,
-        ...(step.warning ? [step.warning] : []),
+        [
+            span(` App ${appName(plan.entry)} ${plan.action}${plan.host ? ` (${plan.host})` : ""}`, theme.value, true),
+            ...(both ? [span(`  ${previousVersion} → ${latestVersion}`, theme.version)] : []),
+        ],
+        ...(!both && previousVersion !== undefined ? [fieldLine(" Previous version:", previousVersion)] : []),
+        ...(!both && latestVersion !== undefined ? [fieldLine(" Latest version:", latestVersion)] : []),
+        textLine(" "),
+        ...stepBlockLines([{ ...plan, step: plan.host ? `${plan.action}.${plan.host}` : plan.action }]),
     ];
 }
+/** The recipe's identity and approval status, then one block per step. */
 export function appRecipePreviewLines(entry, status, steps) {
     const recipe = entry.recipe;
     return [
-        `File: ${entry.file}`,
-        `Name: ${recipe?.name ?? entry.file}`,
-        `Platform: ${recipe?.platform ?? "all"}`,
-        `Status: ${status}`,
-        ...(recipe?.homepage ? [`Homepage: ${recipe.homepage}`] : []),
-        ...(recipe?.skills ? [`Owned Skills: ${JSON.stringify(recipe.skills)}`] : []),
-        ...steps.flatMap(step => [step.step, ...appStepLines(step)]),
+        [
+            span(` ${appName(entry)}`, theme.value, true),
+            span(`  ${recipe?.platform ?? "all"}`, theme.field),
+            span(`  ● ${status}`, status === "approved" ? theme.success : theme.warning),
+        ],
+        [span(` ${[entry.file, ...(recipe?.homepage ? [recipe.homepage] : [])].join(" · ")}`, theme.legend)],
+        ...(recipe?.skills ? [fieldLine(" Owned Skills:", commandLine(recipe.skills, { terminal: true }))] : []),
+        textLine(" "),
+        ...stepBlockLines(steps),
     ];
 }
 function appPreviewLines(mode) {
-    if (mode.kind === "app-approve")
-        return mode.lines;
-    return [
-        `App: ${appName(mode.plan.entry)} ${mode.plan.action}${mode.plan.host ? ` (${mode.plan.host})` : ""}`,
-        ...(mode.plan.previousVersion ? [`Previous version: ${mode.plan.previousVersion}`] : []),
-        ...(mode.plan.latestVersion ? [`Latest version: ${mode.plan.latestVersion}`] : []),
-        ...appStepLines(mode.plan),
-    ];
+    return mode.kind === "app-approve" ? mode.lines : appPlanLines(mode.plan);
 }
 /** The busy mode of an App step; `previous` is the busy mode this step continues, so the clock keeps running. */
 function appBusy(label, previous, done) {
@@ -182,8 +191,8 @@ export function handleAppKey(context, mode, input, key) {
         }
     }
     else {
-        const lines = appPreviewLines(mode);
-        const viewport = previewViewport(lines, mode.cursor, context.terminalRows, context.terminalColumns, appPreviewChrome(mode));
+        const lines = appPreviewLines(mode).map(lineText);
+        const viewport = context.previewGeometry(lines, mode.cursor, appPreviewChrome(mode));
         const cursor = movePreviewCursor(mode.cursor, viewport.total, input, key, viewport.height);
         if (cursor !== undefined) {
             manage.setMode({ ...mode, cursor });
@@ -197,7 +206,7 @@ export function handleAppKey(context, mode, input, key) {
                 cancel();
             return;
         }
-        if (input !== "y" || !viewport.reachedEnd)
+        if (!isYes(input, key) || !viewport.reachedEnd)
             return;
         if (mode.kind !== "app-approve") {
             void execute(context, mode);
@@ -209,7 +218,7 @@ export function handleAppKey(context, mode, input, key) {
 }
 /** Renders App prompts using the existing checklist and preview-confirm panels. */
 export function AppPanel({ mode }) {
-    const { rows, columns } = useWindowSize();
+    const geometry = usePreviewGeometry();
     if (mode.kind === "app-busy") {
         const done = mode.done ?? [];
         return (_jsxs(BorderPanel, { title: "App lifecycle", children: [_jsx(Working, { label: mode.label, since: mode.startedAt }), done.length > MAX_DONE_LINES ? _jsxs(Text, { color: theme.muted, children: [done.length - MAX_DONE_LINES, " earlier finished"] }) : null, done.slice(-MAX_DONE_LINES).map((line, index) => _jsx(Text, { color: theme.muted, children: line }, index))] }));
@@ -217,8 +226,8 @@ export function AppPanel({ mode }) {
     if (mode.kind === "app-hosts") {
         return (_jsxs(BorderPanel, { title: "App Host steps", children: [_jsx(Text, { children: "Checked = setup. Unchecked = teardown. Wiring is not tracked." }), _jsxs(Text, { children: ["Space/1-", mode.choices.length, " toggle \u00B7 j/k move \u00B7 Enter continue \u00B7 Esc cancel"] }), _jsx(HostChecklist, { choices: mode.choices, cursor: mode.cursor, selected: mode.selected })] }));
     }
-    const lines = appPreviewLines(mode);
+    const styled = appPreviewLines(mode);
+    const lines = styled.map(lineText);
     const chrome = appPreviewChrome(mode);
-    const viewport = previewViewport(lines, mode.cursor, rows || 24, columns || 80, chrome);
-    return (_jsx(PreviewConfirm, { title: chrome.title, lines: lines, cursor: mode.cursor, question: viewport.reachedEnd ? chrome.questions[0] : chrome.questions[1], chrome: chrome }));
+    return _jsx(PagedPreview, { chrome: chrome, lines: lines, styled: styled, viewport: geometry(lines, mode.cursor, chrome) });
 }