@lidtop/loadout 0.3.0 → 0.3.2

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;