@lidtop/loadout 0.3.1 → 0.3.2

package/README.md

@@ -13,11 +13,11 @@ npm install -g @lidtop/loadout
 loadout
 ```
 
-Pick your kits, select **Review changes**, and confirm. Inside a provider, choose **Back to providers** to keep browsing with your selections preserved. Run `loadout` again to change your selection.
+Pick your kits and select **Review changes**. Any kit questions and downloads happen automatically, then one compact review shows your kit changes and file totals for Repository and Global. Expand **Unchanged** to inspect your complete selection, or choose **View files** to browse paths and diffs. Choose **Apply changes** to save, or **Back to kits** to edit your selection. Inside a provider, choose **Back to providers** to keep browsing with your selections preserved. Run `loadout` again to change your selection.
 
 The destination selector above the tabs shows **Repository** in cyan (this repository only) and **Global** in magenta (your user configuration across repositories). Active controls and selection markers follow the destination's color. Press **Tab** to switch destinations instantly, or **Shift+Tab** to cycle backward. **←/→** switches between the Kits, Browse, and Installed sections. Each destination keeps its own selections, provider, search, and cursor position, ready to browse as soon as you switch. A **\*** marks destinations with unapplied selections; **Review changes** includes the session's changes across both. Descriptions appear beneath every provider and kit, with dependency or update notes when needed.
 
-Press **Esc** at a setup question or review prompt to return to the picker with your selections and position preserved. Press **Esc twice quickly** or **Ctrl+C** to cancel setup.
+Press **Esc** from review, questions, or downloads to return to your kits. Inside file details, **Esc** returns to the previous view. Your kit choices, completed answers, and picker position are preserved; completed downloads are reused during the session and file plans are rebuilt before review. In review, **↑/↓** scroll and **Tab** moves between actions. Press **Ctrl+C** to cancel setup, or **Esc twice quickly** from the picker. Nothing is applied until you choose **Apply changes**.
 
 Conflicting project instructions are skipped with a warning; the kit’s skills still install.
 

package/dist/cli.js

@@ -5,10 +5,9 @@ import { readFileSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import { discover } from './catalog.js';
 import { initialize } from './init.js';
-import { interactive, confirmApply, selectUpdates, confirmRetry, confirmAdoption, } from './interactive.js';
-import { apply, applyAll, hasChanges, plan } from './storage.js';
+import { interactive } from './setup.js';
+import { apply, hasChanges, plan } from './storage.js';
 import { renderWithExternal } from './external.js';
-import { DownloadCancelledError } from './retry.js';
 import { loadTarget } from './targets.js';
 import { configure, disableKits, reasons, resolveKits, setAnswers, } from './resolve.js';
 import { kitSource } from './schema.js';
@@ -134,54 +133,9 @@ async function generate(catalog, state, opts) {
 }
 async function setup() {
     const { targets, initial } = interactiveTargets();
-    await interactive(targets, initial, { review: reviewSelections });
-}
-async function reviewSelections(configured) {
     const offline = program.opts().offline;
-    const plans = [];
-    for (const { target, state } of configured) {
-        const catalog = target.catalog;
-        console.log(`\n${target.label} · ${target.root}`);
-        const update = await selectUpdates(catalog, state, offline);
-        const rendered = await renderWithExternal(catalog, state, {
-            offline,
-            update,
-            retry: confirmRetry,
-            onRetry: (id) => console.log(`Retrying ${id}…`),
-            onFetch: (id, source) => console.log(`Fetching ${id} from ${source.repo}…`),
-        });
-        for (const id of resolveKits(catalog, state.selected)) {
-            const kit = catalog.kits.get(id);
-            if (kit.external) {
-                const source = update.includes(id)
-                    ? kit.external
-                    : (kit.pinned ?? kit.external);
-                console.log(`${id}: ${source.repo}@${source.ref.slice(0, 12)} · license: ${source.license}`);
-            }
-        }
-        const result = plan(catalog, state, rendered, { adopt: true });
-        preview(result, update.length > 0 || !!result.adopted?.length);
-        if (result.adopted?.length && !(await confirmAdoption(result.adopted)))
-            throw new DownloadCancelledError();
-        plans.push(result);
-    }
-    if (!plans.some(hasChanges))
-        return;
-    const scopes = configured
-        .filter((_, index) => hasChanges(plans[index]))
-        .map(({ target }) => target.label);
-    if (await confirmApply(undefined, scopes)) {
-        applyAll(plans);
-        console.log('\nYour loadout is ready.');
-        for (const result of plans) {
-            if (!result.skippedInstructions?.length)
-                continue;
-            console.log(result.root);
-            showSkipped(result);
-        }
-    }
-    else
-        console.log('Cancelled. No kit selections or agent outputs saved.');
+    await interactive(targets, initial, { offline });
+    console.log('\nYour loadout is ready.');
 }
 program.action(setup);
 program

package/dist/external.d.ts

@@ -33,6 +33,7 @@ declare const storeSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type Snapshot = z.infer<typeof snapshotSchema>;
+export type SnapshotCache = Map<string, Snapshot>;
 export type ExternalStore = z.infer<typeof storeSchema>;
 export type FetchBytes = (url: string, limit: number, signal?: AbortSignal) => Promise<Buffer>;
 export declare function readExternal(root: string): {
@@ -47,5 +48,8 @@ export declare function renderWithExternal(catalog: Catalog, state: State, optio
     onFetch?: (id: string, source: ExternalSource) => void;
     onRetry?: (id: string) => void;
     retry?: (id: string, error: Error) => Promise<boolean>;
+    signal?: AbortSignal;
+    cache?: SnapshotCache;
+    onReady?: (id: string) => void;
 }): Promise<Rendered>;
 export {};

package/dist/external.js

@@ -30,6 +30,12 @@ const storeSchema = z
     kits: z.record(idSchema, snapshotSchema),
 })
     .strict();
+const sourceKey = (source) => JSON.stringify({
+    repo: source.repo,
+    ref: source.ref,
+    license: source.license,
+    skills: [...source.skills].sort(),
+});
 export function readExternal(root) {
     const raw = readOptional(root, '.loadout-personal/external.json');
     return {
@@ -215,6 +221,7 @@ async function download(source, get) {
     return complete;
 }
 export async function renderWithExternal(catalog, state, options = {}) {
+    options.signal?.throwIfAborted();
     const result = render(catalog, state);
     const enabled = resolveKits(catalog, state.selected);
     const { raw, store } = readExternal(catalog.root);
@@ -222,34 +229,46 @@ export async function renderWithExternal(catalog, state, options = {}) {
         if (!enabled.includes(id) || !catalog.kits.get(id)?.external)
             throw new Error(`Cannot update ${id}: choose an enabled external kit.`);
     for (const id of enabled) {
+        options.signal?.throwIfAborted();
         const kit = catalog.kits.get(id);
         const source = kit.external;
-        if (!source)
+        if (!source) {
+            options.onReady?.(id);
             continue;
+        }
         let snapshot = Object.hasOwn(store.kits, id) ? store.kits[id] : undefined;
         const unchanged = snapshot && sameSource(snapshot.source, source);
         if (!snapshot ||
             (options.update?.includes(id) && !(options.offline && unchanged))) {
-            if (options.offline)
+            const cached = options.cache?.get(sourceKey(source));
+            if (!cached && options.offline)
                 throw new Error(`${id} is not available at the requested revision offline. Run without --offline once to fetch it.`);
-            options.onFetch?.(id, source);
-            snapshot = await retryDownload(async () => {
-                const controller = new AbortController();
-                const requests = new Map();
-                const get = (url, limit) => {
-                    if (!requests.has(url))
-                        requests.set(url, (options.fetch ?? fetchBytes)(url, limit, controller.signal));
-                    return requests.get(url);
-                };
-                try {
-                    return await download(source, get);
-                }
-                finally {
-                    controller.abort();
-                    await Promise.allSettled(requests.values());
-                    requests.clear();
-                }
-            }, options.retry ? (error) => options.retry(id, error) : undefined, () => options.onRetry?.(id));
+            if (!cached)
+                options.onFetch?.(id, source);
+            snapshot =
+                cached ??
+                    (await retryDownload(async () => {
+                        const controller = new AbortController();
+                        const requests = new Map();
+                        const get = (url, limit) => {
+                            if (!requests.has(url))
+                                requests.set(url, (options.fetch ?? fetchBytes)(url, limit, options.signal
+                                    ? AbortSignal.any([options.signal, controller.signal])
+                                    : controller.signal));
+                            return requests.get(url);
+                        };
+                        try {
+                            return await download(source, get);
+                        }
+                        finally {
+                            controller.abort();
+                            await Promise.allSettled(requests.values());
+                            requests.clear();
+                        }
+                    }, options.retry ? (error) => options.retry(id, error) : undefined, () => options.onRetry?.(id), options.signal));
+            options.signal?.throwIfAborted();
+            validateSnapshot(snapshot, id);
+            options.cache?.set(sourceKey(source), snapshot);
             store.kits[id] = snapshot;
         }
         validateSnapshot(snapshot, id);
@@ -271,6 +290,7 @@ export async function renderWithExternal(catalog, state, options = {}) {
                 });
             }
         }
+        options.onReady?.(id);
     }
     if (raw || Object.keys(store.kits).length)
         result.external = {

package/dist/interactive.d.ts

@@ -1,15 +1,16 @@
 import { checkbox, confirm, select } from '@inquirer/prompts';
-import { type Catalog, type State } from './schema.js';
-import { type TargetSelection } from './picker.js';
+import { type Answer, type Catalog, type State } from './schema.js';
 import { type Target } from './targets.js';
-type PromptContext = NonNullable<Parameters<typeof confirm>[1]>;
-export declare function interactive(targets: Target[], initial?: number, options?: {
-    context?: PromptContext;
-    review?: (selections: TargetSelection[], context?: PromptContext) => Promise<void>;
-}): Promise<TargetSelection[]>;
-export declare function configureSelection(target: Target, state: State, context?: Parameters<typeof confirm>[1]): Promise<State>;
+export type PromptContext = NonNullable<Parameters<typeof confirm>[1]>;
+export declare class BackNavigation extends Error {
+}
+export declare function configureSelection(target: Target, state: State, context?: Parameters<typeof confirm>[1], onAnswer?: (kit: string, key: string, answer: Answer) => void): Promise<State>;
 export declare function confirmApply(context?: PromptContext, scopes?: string[]): Promise<boolean>;
-export declare function selectUpdates(catalog: Catalog, state: State, offline?: boolean, context?: Parameters<typeof checkbox>[1]): Promise<string[]>;
+export declare function selectUpdates(catalog: Catalog, state: State, offline?: boolean, context?: Parameters<typeof checkbox>[1], options?: {
+    message?: string;
+    selected?: string[];
+    quiet?: boolean;
+}): Promise<string[]>;
 export declare function confirmRetry(id: string, error: Error, context?: Parameters<typeof select>[1]): Promise<boolean>;
-export declare function confirmAdoption(paths: string[], context?: Parameters<typeof confirm>[1]): Promise<boolean>;
-export {};
+export declare function confirmAdoption(paths: string[], context?: Parameters<typeof confirm>[1], scope?: string): Promise<boolean>;
+export declare function retryReview(error: unknown, context?: PromptContext): Promise<boolean>;

package/dist/interactive.js

@@ -1,10 +1,9 @@
 import { checkbox, confirm, select } from '@inquirer/prompts';
 import { configure } from './resolve.js';
-import { validAnswer } from './schema.js';
-import { targetPicker, } from './picker.js';
+import { validAnswer, } from './schema.js';
 import { availableUpdates, updateDescription } from './updates.js';
 import { prepareInput } from './terminal.js';
-class BackToPicker extends Error {
+export class BackNavigation extends Error {
 }
 async function backPrompt(prompt, context = {}) {
     const input = context.input ?? process.stdin;
@@ -12,7 +11,7 @@ async function backPrompt(prompt, context = {}) {
     const controller = new AbortController();
     const back = (_text, key) => {
         if (key.name === 'escape')
-            controller.abort(new BackToPicker());
+            controller.abort(new BackNavigation());
     };
     input.on('keypress', back);
     try {
@@ -24,7 +23,7 @@ async function backPrompt(prompt, context = {}) {
         });
     }
     catch (error) {
-        if (error instanceof Error && error.cause instanceof BackToPicker)
+        if (error instanceof Error && error.cause instanceof BackNavigation)
             throw error.cause;
         throw error;
     }
@@ -32,30 +31,9 @@ async function backPrompt(prompt, context = {}) {
         input.off('keypress', back);
     }
 }
-export async function interactive(targets, initial = 0, options = {}) {
-    if (!options.context && (!process.stdin.isTTY || !process.stdout.isTTY))
-        throw new Error('Interactive setup needs a terminal. Use loadout enable <kit>, then loadout apply.');
-    const session = {};
-    for (;;) {
-        const chosen = await targetPicker({ targets, initial, session }, options.context);
-        try {
-            const configured = [];
-            for (const { target, state } of chosen) {
-                const value = await configureSelection(target, state, options.context);
-                configured.push({ target, state: value });
-            }
-            await options.review?.(configured, options.context);
-            return configured;
-        }
-        catch (error) {
-            if (!(error instanceof BackToPicker))
-                throw error;
-        }
-    }
-}
-export async function configureSelection(target, state, context) {
+export async function configureSelection(target, state, context, onAnswer) {
     const change = new Map();
-    return configure(target.catalog, state, async (kit, key, question, value) => {
+    const ask = async (kit, key, question, value) => {
         if (!change.has(kit)) {
             const hasSaved = Object.entries(target.catalog.kits.get(kit).questions).some(([name, q]) => validAnswer(q, state.answers[kit]?.[name]));
             change.set(kit, hasSaved
@@ -76,6 +54,11 @@ export async function configureSelection(target, state, context) {
             choices: question.choices.map((v) => ({ name: v, value: v })),
             default: typeof value === 'string' ? value : undefined,
         }, context), context);
+    };
+    return configure(target.catalog, state, async (kit, key, question, value) => {
+        const answer = await ask(kit, key, question, value);
+        onAnswer?.(kit, key, answer);
+        return answer;
     });
 }
 export async function confirmApply(context, scopes = []) {
@@ -86,20 +69,23 @@ export async function confirmApply(context, scopes = []) {
         default: true,
     }, context), context);
 }
-export async function selectUpdates(catalog, state, offline = false, context) {
+export async function selectUpdates(catalog, state, offline = false, context, options = {}) {
     const updates = availableUpdates(catalog, state.selected);
     if (!updates.length)
         return [];
     if (offline) {
-        console.log(`${updates.length} catalog update(s) available. Run loadout online to review them; keeping saved versions.`);
+        if (!options.quiet)
+            console.log(`${updates.length} catalog update(s) available. Run loadout online to review them; keeping saved versions.`);
         return [];
     }
     return backPrompt((context) => checkbox({
-        message: 'Catalog updates available · choose kits to update (Enter skips)',
+        message: options.message ??
+            'Catalog updates available · choose kits to update (Enter skips)',
         choices: updates.map((kit) => ({
             name: kit.id,
             value: kit.id,
             description: updateDescription(kit),
+            checked: options.selected?.includes(kit.id) ?? false,
         })),
         required: false,
     }, context), context);
@@ -113,9 +99,25 @@ export async function confirmRetry(id, error, context) {
         ],
     }, context), context);
 }
-export async function confirmAdoption(paths, context) {
+export async function confirmAdoption(paths, context, scope) {
     return backPrompt((context) => confirm({
-        message: `Keep existing content and let Loadout manage ${paths.join(', ')}? Originals will be restored when disabled.`,
+        message: `${scope ? `${scope} · ` : ''}Keep existing content and let Loadout manage ${paths.join(', ')}? Originals will be restored when disabled.`,
         default: true,
     }, context), context);
 }
+export async function retryReview(error, context) {
+    try {
+        return await backPrompt((context) => select({
+            message: `Could not finish: ${error instanceof Error ? error.message : String(error)}`,
+            choices: [
+                { name: 'Try again', value: true },
+                { name: 'Back to kits', value: false },
+            ],
+        }, context), context);
+    }
+    catch (failure) {
+        if (failure instanceof BackNavigation)
+            return false;
+        throw failure;
+    }
+}

package/dist/prepare.d.ts

@@ -0,0 +1,10 @@
+import { type PromptContext } from './interactive.js';
+import { type ReviewTarget, type PreparedTarget } from './review.js';
+type Progress = (scope: number, message: string) => void;
+type Retry = (scope: number, id: string, error: Error) => Promise<boolean>;
+type Config = {
+    selections: ReviewTarget[];
+    run: (progress: Progress, retry: Retry, signal: AbortSignal) => Promise<PreparedTarget[]>;
+};
+export declare function prepareScreen(config: Config, context?: PromptContext): Promise<PreparedTarget[]>;
+export {};

package/dist/prepare.js

@@ -0,0 +1,92 @@
+import { createPrompt, isEnterKey, useEffect, useKeypress, useRef, useState, } from '@inquirer/core';
+import { styleText } from 'node:util';
+import { BackNavigation } from './interactive.js';
+import { wrapReviewText, } from './review.js';
+// A single live screen owns all network activity, including retry decisions.
+const progressScreen = createPrompt((config, done) => {
+    const [statuses, setStatuses] = useState(config.selections.map(() => 'Waiting'));
+    const [failure, setFailure] = useState();
+    const [active, setActive] = useState(0);
+    const [visible, setVisible] = useState(false);
+    const controller = useRef(new AbortController());
+    const pending = useRef(undefined);
+    useEffect(() => {
+        let mounted = true;
+        // Cached and local kits go straight to review without flashing a screen.
+        const timer = setTimeout(() => setVisible(true), 150);
+        const signal = controller.current.signal;
+        const progress = (scope, message) => {
+            if (mounted)
+                setStatuses((previous) => previous.map((value, index) => (index === scope ? message : value)));
+        };
+        const retry = (scope, id, error) => new Promise((resolve, reject) => {
+            signal.throwIfAborted();
+            const abort = () => {
+                pending.current = undefined;
+                reject(signal.reason);
+            };
+            signal.addEventListener('abort', abort, { once: true });
+            pending.current = (value) => {
+                signal.removeEventListener('abort', abort);
+                pending.current = undefined;
+                setFailure(undefined);
+                resolve(value);
+            };
+            setActive(0);
+            setFailure({ scope, id, error });
+        });
+        void config.run(progress, retry, signal).then((prepared) => {
+            if (mounted)
+                done({ prepared });
+        }, (error) => {
+            if (mounted)
+                done({ error });
+        });
+        return () => {
+            mounted = false;
+            clearTimeout(timer);
+            controller.current.abort(new BackNavigation());
+        };
+    }, []);
+    useKeypress((key) => {
+        if (key.name === 'escape') {
+            controller.current.abort(new BackNavigation());
+            done({ error: new BackNavigation() });
+        }
+        else if (failure) {
+            if (key.name === 'up' || key.name === 'down')
+                setActive(active === 0 ? 1 : 0);
+            else if (isEnterKey(key)) {
+                if (active === 0)
+                    pending.current?.(true);
+                else {
+                    controller.current.abort(new BackNavigation());
+                    done({ error: new BackNavigation() });
+                }
+            }
+        }
+    });
+    const width = Math.max(20, (process.stdout.columns || 80) - 4);
+    if (!visible && !failure)
+        return '';
+    return [
+        ...config.selections.map(({ target }, index) => `  ${styleText(target.global ? 'magenta' : 'cyan', target.label)} · ${wrapReviewText(statuses[index], width - target.label.length - 3)[0]}`),
+        ...(failure
+            ? [
+                ...wrapReviewText(`${config.selections[failure.scope].target.label} · ${failure.id}: ${failure.error.message}`, width).map((line) => `  ${line}`),
+                `  ${active === 0 ? '›' : ' '} [ Retry download ]`,
+                `  ${active === 1 ? '›' : ' '} [ Back to kits ]`,
+            ]
+            : []),
+        '  Esc back · Ctrl+C cancel',
+    ].join('\n');
+});
+export async function prepareScreen(config, context) {
+    const result = await progressScreen(config, {
+        ...context,
+        clearPromptOnDone: true,
+    });
+    if ('error' in result)
+        throw result.error;
+    return result.prepared;
+}

package/dist/retry.d.ts

@@ -1,4 +1,4 @@
 export declare class DownloadCancelledError extends Error {
     constructor();
 }
-export declare function retryDownload<T>(attempt: () => Promise<T>, retry?: (error: Error) => Promise<boolean>, onRetry?: () => void): Promise<T>;
+export declare function retryDownload<T>(attempt: () => Promise<T>, retry?: (error: Error) => Promise<boolean>, onRetry?: () => void, signal?: AbortSignal): Promise<T>;

package/dist/retry.js

@@ -4,13 +4,15 @@ export class DownloadCancelledError extends Error {
         this.name = 'DownloadCancelledError';
     }
 }
-export async function retryDownload(attempt, retry, onRetry) {
+export async function retryDownload(attempt, retry, onRetry, signal) {
     for (;;) {
         for (let tries = 0; tries < 2; tries++) {
             try {
+                signal?.throwIfAborted();
                 return await attempt();
             }
             catch (failure) {
+                signal?.throwIfAborted();
                 const error = failure instanceof Error ? failure : new Error(String(failure));
                 if (tries === 0) {
                     onRetry?.();

package/dist/review.d.ts

@@ -0,0 +1,35 @@
+import { type TargetSelection } from './picker.js';
+import { type PromptContext } from './interactive.js';
+import { type Change, type Plan } from './storage.js';
+export type ReviewTarget = TargetSelection & {
+    update: string[];
+    plan?: Plan;
+};
+export type PreparedTarget = ReviewTarget & {
+    plan: Plan;
+};
+export type ReviewAction = 'back' | 'apply' | 'done';
+type Row = {
+    text: string;
+    scope?: number;
+    heading?: boolean;
+    warning?: boolean;
+    expand?: number;
+    file?: Change;
+};
+export type KitReview = {
+    id: string;
+    effect: 'Add' | 'Remove' | 'Update' | 'Configure' | 'Keep';
+    notes: string[];
+    unchanged: boolean;
+};
+export declare function selectionSummary({ target, state, update, }: ReviewTarget): KitReview[];
+export declare function reviewRows(selections: ReviewTarget[], expanded: number[]): Row[];
+export declare function wrapReviewText(value: string, width: number): string[];
+type ReviewConfig = {
+    selections: ReviewTarget[];
+    columns?: number;
+    rows?: number;
+};
+export declare function reviewScreen(config: ReviewConfig, context?: PromptContext): Promise<ReviewAction>;
+export {};

package/dist/review.js

@@ -0,0 +1,346 @@
+import { createPrompt, isEnterKey, isSpaceKey, useEffect, useKeypress, useState, } from '@inquirer/core';
+import { createTwoFilesPatch } from 'diff';
+import { stripVTControlCharacters, styleText } from 'node:util';
+import stringWidth from 'string-width';
+import { kitSource } from './schema.js';
+import { reasons, resolveKits } from './resolve.js';
+import { hasChanges } from './storage.js';
+import { suspendEscapeCancellation } from './terminal.js';
+// Compare effective kits, not just checkboxes: a deselected dependency may stay enabled.
+export function selectionSummary({ target, state, update, }) {
+    const catalog = target.catalog;
+    const saved = target.state ?? { schemaVersion: 1, selected: [], answers: {} };
+    const old = new Set([
+        ...resolveKits(catalog, saved.selected.filter((id) => catalog.kits.has(id) && catalog.kits.get(id)?.ready !== false)),
+        ...saved.selected,
+    ]);
+    const next = new Set(resolveKits(catalog, state.selected));
+    return [...new Set([...old, ...next])].sort().map((id) => {
+        const kit = catalog.kits.get(id);
+        const explicitChanged = saved.selected.includes(id) !== state.selected.includes(id);
+        const answerKeys = Object.keys(kit?.questions ?? {}).sort();
+        const configured = next.has(id) &&
+            answerKeys.some((key) => saved.answers[id]?.[key] !== state.answers[id]?.[key]);
+        const effect = !next.has(id)
+            ? 'Remove'
+            : !old.has(id)
+                ? 'Add'
+                : update.includes(id)
+                    ? 'Update'
+                    : configured
+                        ? 'Configure'
+                        : 'Keep';
+        const notes = [];
+        if (next.has(id) && !state.selected.includes(id))
+            notes.push(`${saved.selected.includes(id) ? 'still required' : 'dependency'} of ${reasons(catalog, state.selected, id).join(', ')}`);
+        else if (effect === 'Keep' && explicitChanged)
+            notes.push('chosen directly');
+        if (effect === 'Update' && kit?.external)
+            notes.push(`${kit.pinned?.ref.slice(0, 7) ?? 'saved'} → ${kit.external.ref.slice(0, 7)}`);
+        if (next.has(id))
+            for (const key of answerKeys) {
+                const answer = state.answers[id]?.[key];
+                if (answer !== undefined)
+                    notes.push(`${key === 'placement' ? 'Install as' : key.replaceAll('-', ' ')}: ${answer}`);
+            }
+        if (kit && kitSource(kit) !== 'Repository')
+            notes.push(kitSource(kit));
+        return {
+            id,
+            effect,
+            notes,
+            unchanged: effect === 'Keep' && !explicitChanged,
+        };
+    });
+}
+const outputChanges = (plan) => plan.changes.filter((change) => change.kind !== 'unchanged' &&
+    !change.path.startsWith('.loadout-personal/'));
+export function reviewRows(selections, expanded) {
+    const rows = [];
+    const summaries = selections.map(selectionSummary);
+    if (!selections.some(({ plan }) => plan && hasChanges(plan)))
+        rows.push({ text: 'No changes to apply' });
+    selections.forEach(({ target, plan }, scope) => {
+        const kits = summaries[scope];
+        rows.push({
+            text: `${target.label} · ${target.root}`,
+            scope,
+            heading: true,
+        });
+        const changed = kits.filter((kit) => !kit.unchanged);
+        const unchanged = kits.filter((kit) => kit.unchanged);
+        const kitRow = (kit) => ({
+            text: `  ${kit.effect.padEnd(9)} ${kit.id}${kit.notes.length ? ` · ${kit.notes.join(' · ')}` : ''}`,
+            scope,
+        });
+        rows.push(...changed.map(kitRow));
+        if (unchanged.length) {
+            rows.push({
+                text: `  ${expanded.includes(scope) ? '▾' : '▸'} Unchanged (${unchanged.length})`,
+                scope,
+                expand: scope,
+            });
+            if (expanded.includes(scope))
+                rows.push(...unchanged.map(kitRow));
+        }
+        if (!kits.length)
+            rows.push({ text: '  No kits selected', scope });
+        if (plan) {
+            const changes = outputChanges(plan);
+            const counts = ['create', 'update', 'delete'].flatMap((kind) => {
+                const count = changes.filter((change) => change.kind === kind).length;
+                return count
+                    ? [`${count} ${kind === 'delete' ? 'remove' : kind}`]
+                    : [];
+            });
+            if (counts.length)
+                rows.push({ text: `  Files: ${counts.join(' · ')}`, scope });
+            else if (hasChanges(plan))
+                rows.push({ text: '  Settings only', scope });
+            if (plan.adopted?.length)
+                rows.push({
+                    text: `  Existing content kept: ${plan.adopted.join(', ')}`,
+                    scope,
+                });
+            for (const skipped of plan.skippedInstructions ?? [])
+                rows.push({
+                    text: `  Skipped instructions · ${skipped.kits.join(', ')}: ${skipped.reason} (${skipped.paths.join(', ')})`,
+                    scope,
+                    warning: true,
+                });
+            for (const id of plan.kitsWithoutOutputs ?? [])
+                rows.push({
+                    text: `  ${id}: no agent outputs will be applied`,
+                    scope,
+                    warning: true,
+                });
+        }
+        rows.push({ text: '' });
+    });
+    return rows;
+}
+function fileRows(selections) {
+    return selections.flatMap(({ target, state, update, plan }, scope) => {
+        const rows = [
+            { text: `${target.label} · ${target.root}`, scope, heading: true },
+        ];
+        for (const id of resolveKits(target.catalog, state.selected)) {
+            const kit = target.catalog.kits.get(id);
+            if (!kit.external)
+                continue;
+            const source = update.includes(id)
+                ? kit.external
+                : (kit.pinned ?? kit.external);
+            rows.push({
+                text: `${id}: ${source.repo}@${source.ref} · license: ${source.license}`,
+                scope,
+            });
+        }
+        const files = plan ? outputChanges(plan) : [];
+        rows.push(...files.map((file) => ({
+            text: `${file.kind === 'create' ? '+' : file.kind === 'delete' ? '-' : '~'} ${file.path}`,
+            scope,
+            file,
+        })));
+        if (!files.length)
+            rows.push({ text: 'No agent file changes', scope });
+        rows.push({ text: '' });
+        return rows;
+    });
+}
+function diffRows(row) {
+    const file = row.file;
+    const before = file.before?.content ?? Buffer.alloc(0);
+    const after = file.after?.content ?? Buffer.alloc(0);
+    const header = { text: file.path, scope: row.scope, heading: true };
+    if (before.equals(after))
+        return [header, { text: 'File mode changed; content is unchanged.' }];
+    if (before.length + after.length > 200_000 ||
+        before.includes(0) ||
+        after.includes(0))
+        return [
+            header,
+            { text: 'Binary or large content; inspect the source for details.' },
+        ];
+    return [
+        header,
+        ...createTwoFilesPatch(`a/${file.path}`, `b/${file.path}`, before.toString('utf8'), after.toString('utf8'), undefined, undefined, { context: 3 })
+            .split('\n')
+            .map((text) => ({ text, scope: row.scope })),
+    ];
+}
+export function wrapReviewText(value, width) {
+    const text = stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f]/g, ' ');
+    const lines = [];
+    let line = '';
+    for (const character of text) {
+        if (line && stringWidth(line + character) > width) {
+            lines.push(line);
+            line = '';
+        }
+        line += character;
+    }
+    lines.push(line);
+    return lines;
+}
+const screen = createPrompt((config, done) => {
+    const [expanded, setExpanded] = useState([]);
+    const [view, setView] = useState('summary');
+    const [diff, setDiff] = useState([]);
+    const [active, setActive] = useState(undefined);
+    const [lastContent, setLastContent] = useState(0);
+    const [summaryCursor, setSummaryCursor] = useState(0);
+    const [fileCursor, setFileCursor] = useState(0);
+    const [size, setSize] = useState({
+        columns: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+    });
+    useEffect(() => {
+        const resize = () => setSize({
+            columns: process.stdout.columns || 80,
+            rows: process.stdout.rows || 24,
+        });
+        process.stdout.on('resize', resize);
+        return () => {
+            process.stdout.off('resize', resize);
+        };
+    }, []);
+    const width = Math.max(16, (config.columns ?? size.columns) - 4);
+    const changed = config.selections.some(({ plan }) => plan && hasChanges(plan));
+    const actions = view !== 'summary'
+        ? [
+            {
+                label: view === 'diff' ? 'Back to files' : 'Back to review',
+                value: 'close',
+            },
+        ]
+        : [
+            { label: 'Back to kits', value: 'back' },
+            { label: 'View files', value: 'files' },
+            {
+                label: changed ? 'Apply changes' : 'Done',
+                value: changed ? 'apply' : 'done',
+            },
+        ];
+    const content = view === 'diff'
+        ? diff
+        : view === 'files'
+            ? fileRows(config.selections)
+            : reviewRows(config.selections, expanded);
+    const rows = content.flatMap((row) => wrapReviewText(row.text, width - 2).map((text, index) => ({
+        ...row,
+        text,
+        ...(index ? { expand: undefined, file: undefined } : {}),
+    })));
+    const cursor = Math.min(active ?? rows.length + actions.length - 1, rows.length + actions.length - 1);
+    const focus = (index) => {
+        setActive(index);
+        if (index < rows.length)
+            setLastContent(index);
+    };
+    const pageSize = Math.min(rows.length, Math.max(2, (config.rows ?? size.rows) - actions.length - 5));
+    const start = Math.max(0, Math.min((cursor < rows.length ? cursor : lastContent) - Math.floor(pageSize / 2), rows.length - pageSize));
+    const back = () => {
+        if (view === 'diff') {
+            setView('files');
+            setActive(fileCursor);
+        }
+        else if (view === 'files') {
+            setView('summary');
+            setActive(summaryCursor);
+        }
+        else
+            done('back');
+    };
+    useKeypress((key, rl) => {
+        rl.clearLine(0);
+        if (key.name === 'escape') {
+            back();
+            return;
+        }
+        if (key.name === 'tab') {
+            const index = cursor < rows.length
+                ? key.shift
+                    ? actions.length
+                    : -1
+                : cursor - rows.length;
+            setActive(rows.length +
+                ((index + (key.shift ? -1 : 1) + actions.length) % actions.length));
+        }
+        else if (key.name === 'home')
+            focus(0);
+        else if (key.name === 'end')
+            setActive(rows.length + actions.length - 1);
+        else if (['up', 'down', 'pageup', 'pagedown'].includes(key.name)) {
+            const step = key.name.startsWith('page') ? pageSize : 1;
+            const backwards = key.name === 'up' || key.name === 'pageup';
+            const length = rows.length + actions.length;
+            focus((cursor + ((backwards ? -step : step) % length) + length) % length);
+        }
+        else if (isEnterKey(key) || isSpaceKey(key)) {
+            const action = actions[cursor - rows.length];
+            if (action?.value === 'close')
+                back();
+            else if (action?.value === 'files') {
+                setSummaryCursor(cursor);
+                setView('files');
+                setActive(0);
+                setLastContent(0);
+            }
+            else if (action)
+                done(action.value);
+            else {
+                const row = rows[cursor];
+                if (row?.expand !== undefined)
+                    setExpanded(expanded.includes(row.expand)
+                        ? expanded.filter((scope) => scope !== row.expand)
+                        : [...expanded, row.expand]);
+                if (row?.file) {
+                    setFileCursor(cursor);
+                    setDiff(diffRows(row));
+                    setView('diff');
+                    setActive(0);
+                    setLastContent(0);
+                }
+            }
+        }
+    });
+    const accent = (text) => styleText(config.selections.every(({ target }) => target.global)
+        ? 'magenta'
+        : 'cyan', text);
+    const title = view === 'files'
+        ? 'Files · Enter to inspect a diff'
+        : view === 'diff'
+            ? 'File diff'
+            : 'Review changes';
+    const page = rows.slice(start, start + pageSize).map((row, index) => {
+        const global = row.scope !== undefined && config.selections[row.scope]?.target.global;
+        const text = row.warning
+            ? styleText('yellow', row.text)
+            : row.heading
+                ? styleText(global ? 'magenta' : 'cyan', styleText('bold', row.text))
+                : row.text;
+        return `  ${start + index === cursor ? styleText(global ? 'magenta' : 'cyan', '›') : ' '} ${text}`;
+    });
+    return [
+        `  ${accent(styleText('bold', title))}`,
+        '',
+        ...page,
+        ...actions.map((action, index) => `  ${cursor === rows.length + index ? accent('›') : ' '} ${cursor === rows.length + index ? accent(`[ ${action.label} ]`) : `[ ${action.label} ]`}`),
+        `  ${styleText('dim', `↑↓ move · Tab actions · Enter select · Esc back${rows.length > pageSize ? ` · ${start + 1}–${Math.min(start + pageSize, rows.length)}/${rows.length}` : ''}`)}`,
+        '\u001b[?25l',
+    ]
+        .map((line) => stringWidth(line) > width + 4
+        ? wrapReviewText(line, width + 4)[0]
+        : line)
+        .join('\n');
+});
+export async function reviewScreen(config, context) {
+    const restore = suspendEscapeCancellation(context?.input ?? process.stdin);
+    try {
+        return await screen(config, { ...context, clearPromptOnDone: true });
+    }
+    finally {
+        restore();
+    }
+}

package/dist/setup.d.ts

@@ -0,0 +1,9 @@
+import { type TargetSelection } from './picker.js';
+import { type PromptContext } from './interactive.js';
+import { type FetchBytes } from './external.js';
+import { type Target } from './targets.js';
+export declare function interactive(targets: Target[], initial?: number, options?: {
+    context?: PromptContext;
+    offline?: boolean;
+    fetch?: FetchBytes;
+}): Promise<TargetSelection[]>;

package/dist/setup.js

@@ -0,0 +1,120 @@
+import { targetPicker, } from './picker.js';
+import { BackNavigation, configureSelection, confirmAdoption, selectUpdates, retryReview, } from './interactive.js';
+import { renderWithExternal, } from './external.js';
+import { applyAll, plan } from './storage.js';
+import { reviewScreen, } from './review.js';
+import { prepareScreen } from './prepare.js';
+import { suspendEscapeCancellation } from './terminal.js';
+export async function interactive(targets, initial = 0, options = {}) {
+    if (!options.context && (!process.stdin.isTTY || !process.stdout.isTTY))
+        throw new Error('Interactive setup needs a terminal. Use loadout enable <kit>, then loadout apply.');
+    const session = {};
+    const drafts = new Map();
+    const cache = new Map();
+    const context = { ...options.context, clearPromptOnDone: true };
+    for (;;) {
+        const chosen = await targetPicker({ targets, initial, session }, context);
+        const selections = chosen.map(({ target, state }) => {
+            const previous = drafts.get(target);
+            const draft = {
+                target,
+                state: structuredClone({
+                    ...state,
+                    answers: previous?.state.answers ?? state.answers,
+                }),
+                update: previous?.update ?? [],
+            };
+            drafts.set(target, draft);
+            return draft;
+        });
+        for (const [target, draft] of drafts) {
+            if (selections.some((selection) => selection.target === target))
+                continue;
+            // The picker omits inactive scopes whose checkboxes match saved state.
+            // They can still have draft answers, but must use the latest checkboxes.
+            draft.state.selected = [
+                ...(session.snapshot?.selections[targets.indexOf(target)] ??
+                    draft.state.selected),
+            ];
+            if (draft.update.length ||
+                JSON.stringify(draft.state.answers) !==
+                    JSON.stringify(target.state?.answers ?? {}))
+                selections.push(draft);
+        }
+        selections.sort((a, b) => targets.indexOf(a.target) - targets.indexOf(b.target));
+        const restoreEscape = suspendEscapeCancellation(context.input ?? process.stdin);
+        try {
+            for (;;) {
+                try {
+                    // Finish questions for every destination before starting any downloads.
+                    for (const selection of selections) {
+                        const { target, state } = selection;
+                        selection.state = await configureSelection(target, state, context, (kit, key, answer) => {
+                            state.answers[kit] ??= {};
+                            state.answers[kit][key] = answer;
+                        });
+                        selection.update = await selectUpdates(target.catalog, selection.state, options.offline, context, {
+                            message: `${target.label} · Choose catalog updates (Enter keeps your choices)`,
+                            selected: selection.update,
+                            quiet: true,
+                        });
+                    }
+                    const prepared = await prepareScreen({
+                        selections,
+                        run: async (progress, retry, signal) => {
+                            const prepared = [];
+                            for (const [scope, selection] of selections.entries()) {
+                                const { target, state, update } = selection;
+                                progress(scope, 'Preparing kits…');
+                                const rendered = await renderWithExternal(target.catalog, state, {
+                                    offline: options.offline,
+                                    fetch: options.fetch,
+                                    update,
+                                    cache,
+                                    signal,
+                                    onFetch: (id) => progress(scope, `Downloading ${id}…`),
+                                    onRetry: (id) => progress(scope, `Retrying ${id}…`),
+                                    onReady: (id) => progress(scope, `${id} · Ready`),
+                                    retry: (id, error) => retry(scope, id, error),
+                                });
+                                signal.throwIfAborted();
+                                progress(scope, 'Checking file changes…');
+                                prepared.push({
+                                    ...selection,
+                                    plan: plan(target.catalog, state, rendered, {
+                                        adopt: true,
+                                    }),
+                                });
+                                progress(scope, 'Ready');
+                            }
+                            return prepared;
+                        },
+                    }, context);
+                    for (const { target, plan } of prepared) {
+                        if (plan.adopted?.length &&
+                            !(await confirmAdoption(plan.adopted, context, target.label)))
+                            throw new BackNavigation();
+                    }
+                    const action = await reviewScreen({ selections: prepared }, context);
+                    if (action === 'back')
+                        break;
+                    if (action === 'apply')
+                        applyAll(prepared.map(({ plan }) => plan));
+                    return selections.map(({ target, state }) => ({ target, state }));
+                }
+                catch (failure) {
+                    if (failure instanceof BackNavigation)
+                        break;
+                    if (failure instanceof Error &&
+                        ['ExitPromptError', 'AbortPromptError'].includes(failure.name))
+                        throw failure;
+                    if (!(await retryReview(failure, context)))
+                        break;
+                }
+            }
+        }
+        finally {
+            restoreEscape();
+        }
+    }
+}

package/dist/terminal.d.ts

@@ -1 +1,2 @@
+export declare function suspendEscapeCancellation(input: NodeJS.ReadableStream): () => void;
 export declare function prepareInput(input: NodeJS.ReadableStream): void;

package/dist/terminal.js

@@ -1,6 +1,18 @@
 import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
-const prepared = new WeakSet();
+const prepared = new WeakMap();
+// Review has a back stack: consecutive Escapes navigate rather than cancel.
+export function suspendEscapeCancellation(input) {
+    prepareInput(input);
+    const state = prepared.get(input);
+    const cancel = state.cancel;
+    state.cancel = false;
+    state.lastEscape = undefined;
+    return () => {
+        state.cancel = cancel;
+        state.lastEscape = undefined;
+    };
+}
 export function prepareInput(input) {
     if (prepared.has(input))
         return;
@@ -15,16 +27,16 @@ export function prepareInput(input) {
     });
     decoder.close();
     output.end();
-    let lastEscape;
+    const state = { cancel: true, lastEscape: undefined };
     input.on('keypress', (_text, key) => {
-        if (key.name !== 'escape') {
-            lastEscape = undefined;
+        if (key.name !== 'escape' || !state.cancel) {
+            state.lastEscape = undefined;
             return;
         }
         const now = performance.now();
         if (key.sequence === '\u001b\u001b' ||
-            (lastEscape !== undefined && now - lastEscape <= 500)) {
-            lastEscape = undefined;
+            (state.lastEscape !== undefined && now - state.lastEscape <= 500)) {
+            state.lastEscape = undefined;
             // Use the same cancellation path as Ctrl+C, including later prompts.
             input.emit('keypress', '\u0003', {
                 name: 'c',
@@ -35,7 +47,7 @@ export function prepareInput(input) {
             });
         }
         else
-            lastEscape = now;
+            state.lastEscape = now;
     });
-    prepared.add(input);
+    prepared.set(input, state);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lidtop/loadout",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Choose and manage agent instruction and skill kits for repositories and your home directory.",
   "type": "module",
   "bin": {