windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/menu/share-settings.js

@@ -0,0 +1,112 @@
+// The "Export settings…" and "Import settings…" rows in Settings > General: pick a file, then (for an import) read the
+// diff of what would change and say yes once. Same rules as sandbox config export / import.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../../core/config/index.js';
+import { errMsg } from '../../core/util/index.js';
+import { applyImport, DEFAULT_EXPORT, readImport, writeExport } from '../commands/maintenance/config-share.js';
+import { Theme } from '../tui/index.js';
+import { askPath } from './settings/ask-path.js';
+import { diffText, skippedLine } from './settings/index.js';
+/** The rows' ids in the settings list. */
+export const EXPORT_SETTINGS = '@export-settings';
+export const IMPORT_SETTINGS = '@import-settings';
+export function shareSettingsRows() {
+    return [
+        {
+            value: EXPORT_SETTINGS,
+            label: 'Export settings…',
+            hint: '.json',
+            description: 'Write the settings you changed to a .json file you can share with a team. Secrets, the data folder and folders or files of this PC are left out.',
+        },
+        {
+            value: IMPORT_SETTINGS,
+            label: 'Import settings…',
+            hint: '.json',
+            description: 'Read a settings file someone shared, see what it would change, and apply it once you say yes. Secrets, the data folder and paths in it are never taken.',
+        },
+    ];
+}
+export class ShareSettingsFlow {
+    app;
+    ctx;
+    constructor(app, ctx) {
+        this.app = app;
+        this.ctx = ctx;
+    }
+    /** Your settings as they are on disk now (the menu may have saved changes since it started). */
+    fresh() {
+        return { ...this.ctx, loaded: loadConfig(this.ctx.loaded.configPath ?? undefined) };
+    }
+    /** Returns the notice to show (undefined when cancelled). */
+    async export() {
+        const where = ['Settings', 'Export settings'];
+        try {
+            const file = await askPath(this.app, {
+                path: where,
+                title: 'Where to write the settings file',
+                about: ['Only what differs from the defaults is written; secrets and paths of this PC are left out.'],
+                initial: path.resolve(DEFAULT_EXPORT),
+                kind: 'file',
+                validate: (p) => (p.toLowerCase().endsWith('.json') ? true : 'The file name should end in .json.'),
+            });
+            if (!file)
+                return undefined;
+            const exists = path.resolve(file);
+            const replace = fs.existsSync(exists);
+            if (replace &&
+                !(await this.app.confirm({ path: where, question: exists + ' exists. Replace it?', initial: false })))
+                return undefined;
+            const skipped = writeExport(this.fresh(), file, false, replace);
+            return (Theme.ok(Theme.glyph.ok + ' Wrote ' + exists + '.') +
+                (skipped.length ? Theme.muted(' Left out: ' + skipped.join(', ') + '.') : ''));
+        }
+        catch (e) {
+            return Theme.error(Theme.glyph.cross + ' ' + errMsg(e));
+        }
+    }
+    async import() {
+        const where = ['Settings', 'Import settings'];
+        try {
+            const file = await askPath(this.app, {
+                path: where,
+                title: 'Which settings file',
+                about: ['A file made by Export settings (or sandbox config export).'],
+                kind: 'file',
+            });
+            if (!file)
+                return undefined;
+            const ctx = this.fresh();
+            const plan = readImport(ctx, file);
+            const lines = [
+                ...(plan.changes.length
+                    ? [
+                        plan.changes.length + ' setting' + (plan.changes.length === 1 ? '' : 's') + ' would change:',
+                        '',
+                        ...diffText(plan.lines),
+                    ]
+                    : ['Nothing to change: your settings already match the file.']),
+                ...(plan.skipped.length
+                    ? ['', 'Not imported (never taken from a file):', ...plan.skipped.map((s) => skippedLine(s))]
+                    : []),
+            ];
+            if (!plan.changes.length) {
+                await this.app.message({ path: where, lines });
+                return Theme.muted('Nothing changed.');
+            }
+            const yes = await this.app.confirm({
+                path: where,
+                question: 'Change your settings like this?',
+                about: lines,
+                initial: false,
+            });
+            if (!yes)
+                return Theme.muted('Nothing changed.');
+            const n = applyImport(ctx, plan);
+            return Theme.ok(Theme.glyph.ok + ' Imported ' + n + ' setting' + (n === 1 ? '' : 's') + '.');
+        }
+        catch (e) {
+            return Theme.error(Theme.glyph.cross + ' ' + errMsg(e));
+        }
+    }
+}

package/dist/cli/menu/shell.d.ts

@@ -1,4 +1,4 @@
-import type { App, FrameParts, Key, Screen, Size, Step, TabsState } from '../tui/index.js';
+import type { App, Category, FrameParts, Key, NavState, Screen, Size, Step } from '../tui/index.js';
 import type { Draft, DraftResult } from './settings/draft.js';
 /** Why the shell closed. */
 export type ShellExit = {
@@ -14,20 +14,45 @@ export type ShellExit = {
     kind: 'view';
     file: string;
 };
-/** One tab. */
+/** Where one section was left: its open category and its search. */
+export interface ScreenView {
+    readonly category?: string;
+    readonly search?: string;
+}
+/** Which section the menu shows, and where each section was left (by section name). */
+export interface MenuView {
+    readonly section: number;
+    readonly screens: Readonly<Record<string, ScreenView>>;
+}
+/** One section of the menu. */
 export interface Page {
     readonly label: string;
-    /** This page stages changes in the Draft (its tab is marked while something is unsaved). */
+    /** This page stages changes in the Draft (its section is marked while something is unsaved). */
     readonly stages: boolean;
-    /** Typing goes into a search box: digits are text, not tab numbers. */
+    /** Typing goes into a search box: digits are text, not section numbers. */
     readonly capturing: boolean;
-    /** The tab was opened (or the shell came back from a command): load what it shows again. */
+    /** The categories listed under the section while it is open (none: the section is one list). */
+    categories(): readonly Category[];
+    /** The id of the open category. */
+    readonly category: string | undefined;
+    /** The data is still loading: its categories are not known yet (a category asked for opens when they are). */
+    readonly loading?: boolean;
+    /** The search typed in the list ('' or missing: none). */
+    readonly search?: string;
+    /** Types a search into the list (the menu opens on the one it was left on). */
+    restoreSearch?(text: string): void;
+    /** Opens a category (the navigation moved onto it). */
+    selectCategory(id: string): Promise<void>;
+    /** Whether the list has the keyboard (its highlight is softer while the navigation has it). */
+    setFocus(list: boolean): void;
+    /** The section was opened (or the shell came back from a command): load what it shows again. */
     open(): Promise<void>;
     render(size: Size): FrameParts;
+    /** A `quit` from the page means "Esc with nothing left to close": the shell moves to the navigation. */
     handle(key: Key): Promise<Step<ShellExit>> | Step<ShellExit>;
 }
-/** The tab names, in order. Number keys 1-7 open them. */
-export declare const TAB_LABELS: readonly ["Start", "Sessions", "Sandbox", "Apps", "Settings", "Accounts", "Maintenance"];
+/** The section names, in order. Number keys 1-7 open them. */
+export declare const SECTION_LABELS: readonly ["Agents", "Sessions", "Sandbox", "Apps", "Settings", "Accounts", "Maintenance"];
 export declare class Shell implements Screen<ShellExit> {
     private readonly app;
     readonly pages: readonly Page[];
@@ -35,20 +60,38 @@ export declare class Shell implements Screen<ShellExit> {
     /** Told after a save (the menu applies settings that act on this PC) and returns a note to add. */
     private readonly afterSave;
     private active;
+    private focus;
     private notice;
+    /** Where each section was left, by name; a section takes its entry the first time it opens in this shell. */
+    private readonly screens;
+    private readonly restored;
     constructor(app: App, pages: readonly Page[], draft: Draft, 
     /** Told after a save (the menu applies settings that act on this PC) and returns a note to add. */
     afterSave?: (result: DraftResult) => string | undefined);
     get page(): Page;
-    tabs(): TabsState;
-    /** Opens a tab by index (loads its data). */
+    /** Which pane has the keyboard. */
+    get focused(): 'nav' | 'list';
+    nav(): NavState;
+    /** Notes where the open section is (its category and search). */
+    private remember;
+    /** The section that is open and where every section was left (the menu opens there again, also in a later run). */
+    view(): MenuView;
+    /** Opens the section a view names and puts each section back where it was (what is gone is ignored). */
+    restore(view: MenuView): Promise<void>;
+    /** Opens a section by index (loads its data); the first time, it goes back to the category and search it had. */
     openTab(index: number): Promise<void>;
-    /** Loads the open tab again (after a command ran). */
+    /** Puts the keyboard in the navigation or in the list. */
+    setFocus(focus: 'nav' | 'list'): void;
+    /** Loads the open section again (after a command ran). */
     reload(): Promise<void>;
     render(size: Size): FrameParts;
     /** Writes the staged changes; the notice says what happened. */
     save(): string;
     handle(key: Key): Promise<Step<ShellExit>>;
+    /** A key while the navigation has the keyboard. */
+    private navKey;
+    /** One stop up or down the tree: the categories of the open section, then the next section. */
+    private move;
     /** Leaving with unsaved changes asks what to do with them. */
     private leave;
 }

package/dist/cli/menu/shell.js

@@ -1,13 +1,24 @@
 import { Theme } from '../tui/index.js';
-/** The tab names, in order. Number keys 1-7 open them. */
-export const TAB_LABELS = ['Start', 'Sessions', 'Sandbox', 'Apps', 'Settings', 'Accounts', 'Maintenance'];
+/** The section names, in order. Number keys 1-7 open them. */
+export const SECTION_LABELS = ['Agents', 'Sessions', 'Sandbox', 'Apps', 'Settings', 'Accounts', 'Maintenance'];
+const NAV_KEYS = [
+    ['↑↓', 'move', 1],
+    ['→', 'open', 1],
+    ['1-7', 'jump', 4],
+    ['/', 'search', 6],
+    ['esc', 'quit', 0],
+];
 export class Shell {
     app;
     pages;
     draft;
     afterSave;
     active = 0;
+    focus = 'list';
     notice;
+    /** Where each section was left, by name; a section takes its entry the first time it opens in this shell. */
+    screens = new Map();
+    restored = new Set();
     constructor(app, pages, draft, 
     /** Told after a save (the menu applies settings that act on this PC) and returns a note to add. */
     afterSave = () => undefined) {
@@ -15,24 +26,72 @@ export class Shell {
         this.pages = pages;
         this.draft = draft;
         this.afterSave = afterSave;
-        app.tabs = () => this.tabs();
+        app.nav = () => this.nav();
     }
     get page() {
         return this.pages[this.active];
     }
-    tabs() {
+    /** Which pane has the keyboard. */
+    get focused() {
+        return this.focus;
+    }
+    nav() {
         const unsaved = this.draft.count() > 0;
+        const current = this.page.category;
         return {
-            tabs: this.pages.map((p) => ({ label: p.label, marked: p.stages && unsaved })),
+            sections: this.pages.map((p, i) => ({
+                label: p.label,
+                marked: p.stages && unsaved,
+                categories: i === this.active ? p.categories().map((c) => ({ label: c.label, current: c.id === current })) : [],
+            })),
             active: this.active,
+            focused: this.focus === 'nav',
         };
     }
-    /** Opens a tab by index (loads its data). */
+    /** Notes where the open section is (its category and search). */
+    remember() {
+        // A section that was never opened here keeps what the last run knew about it.
+        if (!this.restored.has(this.active))
+            return;
+        const { category, search } = this.page;
+        if (category || search)
+            this.screens.set(this.page.label, { category, search: search || undefined });
+        else
+            this.screens.delete(this.page.label);
+    }
+    /** The section that is open and where every section was left (the menu opens there again, also in a later run). */
+    view() {
+        this.remember();
+        return { section: this.active, screens: Object.fromEntries(this.screens) };
+    }
+    /** Opens the section a view names and puts each section back where it was (what is gone is ignored). */
+    async restore(view) {
+        this.restored.clear();
+        for (const [label, screen] of Object.entries(view.screens))
+            this.screens.set(label, screen);
+        await this.openTab(view.section);
+    }
+    /** Opens a section by index (loads its data); the first time, it goes back to the category and search it had. */
     async openTab(index) {
+        this.remember();
         this.active = Math.max(0, Math.min(this.pages.length - 1, index));
+        this.page.setFocus(this.focus === 'list');
         await this.page.open();
+        if (this.restored.has(this.active))
+            return;
+        this.restored.add(this.active);
+        const wanted = this.screens.get(this.page.label);
+        if (wanted?.category && (this.page.loading || this.page.categories().some((c) => c.id === wanted.category)))
+            await this.page.selectCategory(wanted.category);
+        if (wanted?.search)
+            this.page.restoreSearch?.(wanted.search);
     }
-    /** Loads the open tab again (after a command ran). */
+    /** Puts the keyboard in the navigation or in the list. */
+    setFocus(focus) {
+        this.focus = focus;
+        this.page.setFocus(focus === 'list');
+    }
+    /** Loads the open section again (after a command ran). */
     reload() {
         return this.page.open();
     }
@@ -40,11 +99,14 @@ export class Shell {
         const parts = this.page.render(size);
         const unsaved = this.draft.count();
         const status = parts.status ?? this.app.status();
+        const category = this.page.categories().find((c) => c.id === this.page.category);
+        const keys = this.focus === 'nav' ? NAV_KEYS : parts.keys;
         return {
             ...parts,
+            path: parts.path.length ? parts.path : [this.page.label, ...(category ? [category.label] : [])],
             status: unsaved ? Theme.changed('unsaved: ' + unsaved) + '   ' + status : status,
             notice: this.notice ?? parts.notice,
-            keys: unsaved ? [['ctrl+s', 'save (' + unsaved + ')', 0], ...parts.keys] : parts.keys,
+            keys: unsaved ? [['ctrl+s', 'save (' + unsaved + ')', 0], ...keys] : keys,
         };
     }
     /** Writes the staged changes; the notice says what happened. */
@@ -75,11 +137,54 @@ export class Shell {
                 await this.openTab(index);
             return;
         }
+        if (this.focus === 'nav')
+            return this.navKey(key);
         const step = await this.page.handle(key);
-        if (step && step.done.kind === 'quit')
-            return this.leave();
+        if (step && step.done.kind === 'quit') {
+            // Esc (or Left) in the list: nothing left to close there, so go to the navigation.
+            this.setFocus('nav');
+            return;
+        }
         return step;
     }
+    /** A key while the navigation has the keyboard. */
+    async navKey(key) {
+        if (key.name === 'up' || key.name === 'down') {
+            await this.move(key.name === 'up' ? -1 : 1);
+            return;
+        }
+        if (key.name === 'right' || key.name === 'return') {
+            this.setFocus('list');
+            return;
+        }
+        if (key.name === 'escape')
+            return this.leave();
+        // The scopes of Settings and Apps switch from anywhere; "/" starts a search in the list.
+        if (key.name === 'tab')
+            return this.page.handle(key);
+        if (key.text === '/') {
+            this.setFocus('list');
+            return this.page.handle(key);
+        }
+        return;
+    }
+    /** One stop up or down the tree: the categories of the open section, then the next section. */
+    async move(by) {
+        const categories = this.page.categories();
+        const at = categories.findIndex((c) => c.id === this.page.category);
+        const next = at + by;
+        if (categories.length && next >= 0 && next < categories.length) {
+            await this.page.selectCategory(categories[next].id);
+            return;
+        }
+        const section = this.active + by;
+        if (section < 0 || section >= this.pages.length)
+            return;
+        await this.openTab(section);
+        const entered = this.page.categories();
+        if (entered.length)
+            await this.page.selectCategory(entered[by === 1 ? 0 : entered.length - 1].id);
+    }
     /** Leaving with unsaved changes asks what to do with them. */
     async leave() {
         const count = this.draft.count();

package/dist/cli/menu/views.d.ts

@@ -0,0 +1,7 @@
+import type { AnyView } from '../../app/kernel/index.js';
+import type { SECTION_LABELS } from './shell.js';
+export interface MenuViewPlace {
+    readonly view: AnyView;
+    readonly section: (typeof SECTION_LABELS)[number];
+}
+export declare const MENU_VIEWS: readonly MenuViewPlace[];

package/dist/cli/menu/views.js

@@ -0,0 +1,11 @@
+// The shared core's views the menu shows, and in which section (the parity self-test reads this list: an operation or
+// query is reachable in the menu when a view here offers it). Settings is drawn by its own page over the same rows,
+// because the menu stages changes until Ctrl+S.
+import { sandboxView } from '../../app/features/sandbox/index.js';
+import { sessionsView } from '../../app/features/sessions/index.js';
+import { settingsView } from '../../app/features/settings/index.js';
+export const MENU_VIEWS = [
+    { view: sessionsView, section: 'Sessions' },
+    { view: sandboxView, section: 'Sandbox' },
+    { view: settingsView, section: 'Settings' },
+];

package/dist/cli/menu/vpn-login.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from '../commands/context.js';
+import { type App } from '../tui/index.js';
+/** The row's id in the settings list. */
+export declare const VPN_LOGIN = "@vpn-login";
+export declare function vpnLoginRow(ctx: Context): {
+    label: string;
+    hint: string;
+    description: string;
+};
+export declare class VpnLoginFlow {
+    private readonly app;
+    private readonly ctx;
+    constructor(app: App, ctx: Context);
+    /** Returns the notice to show (undefined when cancelled). */
+    run(): Promise<string | undefined>;
+}

package/dist/cli/menu/vpn-login.js

@@ -0,0 +1,74 @@
+import { VPN_WARNINGS } from '../commands/vpn.js';
+import { NORD_STEPS, VpnService } from '../services/index.js';
+import { Theme } from '../tui/index.js';
+/** The row's id in the settings list. */
+export const VPN_LOGIN = '@vpn-login';
+export function vpnLoginRow(ctx) {
+    const service = new VpnService(ctx);
+    const nord = service.provider === 'nordvpn';
+    if (service.provider === 'wireguard-file')
+        return {
+            label: 'VPN login',
+            hint: 'not needed',
+            description: 'A WireGuard file carries its own keys (vpn.configFile): there is no login to set.',
+        };
+    const state = service.loginState();
+    return {
+        label: nord ? 'Set NordVPN login…' : 'Set VPN login…',
+        hint: state === 'saved' ? 'saved' : state === 'unreadable' ? 'cannot be read' : 'not saved',
+        description: 'The login the VPN uses (for NordVPN the service credentials from Nord Account > NordVPN > Set up NordVPN manually, not your account password). Typed hidden, kept encrypted for your Windows user, never shown. ' +
+            VPN_WARNINGS.join(' '),
+    };
+}
+export class VpnLoginFlow {
+    app;
+    ctx;
+    constructor(app, ctx) {
+        this.app = app;
+        this.ctx = ctx;
+    }
+    /** Returns the notice to show (undefined when cancelled). */
+    async run() {
+        const service = new VpnService(this.ctx);
+        const nord = service.provider === 'nordvpn';
+        if (service.provider === 'wireguard-file')
+            return 'A WireGuard file carries its own keys: no login is needed.';
+        const path = ['Settings', 'Network', 'VPN login'];
+        await this.app.message({
+            path,
+            title: nord ? 'NordVPN service credentials' : 'VPN login',
+            lines: [
+                ...(nord
+                    ? ['To find them:', ...NORD_STEPS.map((s, i) => i + 1 + '. ' + s)]
+                    : ['The user name and password your VPN profile asks for.']),
+                '',
+                'What you type next is hidden, kept encrypted for your Windows user and never shown again.',
+                '',
+                ...VPN_WARNINGS,
+            ],
+        });
+        const username = await this.app.text({
+            path,
+            label: nord ? 'Service user name' : 'User name',
+            masked: true,
+            validate: (v) => (v.trim() ? true : 'Type the user name.'),
+        });
+        if (username === undefined)
+            return undefined;
+        const password = await this.app.text({
+            path,
+            label: nord ? 'Service password' : 'Password',
+            masked: true,
+            validate: (v) => (v ? true : 'Type the password.'),
+        });
+        if (password === undefined)
+            return undefined;
+        try {
+            service.save({ username, password });
+        }
+        catch (e) {
+            return Theme.error(Theme.glyph.cross + ' ' + (e instanceof Error ? e.message : String(e)));
+        }
+        return Theme.ok(Theme.glyph.ok + ' The VPN login is saved (encrypted). Turn the VPN on under Settings > Network.');
+    }
+}

package/dist/cli/operations/handler.d.ts

@@ -0,0 +1,6 @@
+import { type AnyDefinition } from '../../app/kernel/index.js';
+import type { Handler } from '../commands/registry.js';
+/** The command for a definition. */
+export declare function definitionHandler(def: AnyDefinition): Handler;
+/** The command a parsed command line runs when it is one of the shared core's, else undefined. */
+export declare function operationHandler(command: string, positionals: readonly string[]): Handler | undefined;

package/dist/cli/operations/handler.js

@@ -0,0 +1,61 @@
+// Runs a definition as a command: its input from the command line, its questions on the terminal, and its output as
+// --json, as the definition's one-line text, or as the page of the view that shows it. A declined question prints
+// "Nothing changed." and exits 1, as the commands always have.
+import { VIEWS } from '../../app/features/defs.js';
+import { runDefinition } from '../../app/registry.js';
+import { Cancelled } from '../../app/kernel/index.js';
+import { printJson, printPage } from '../output/index.js';
+import { cliInput, definitionFor } from './input.js';
+import { cliIO } from './io-cli.js';
+/** The view that shows only this query (its page is the command's text output). */
+function viewOf(def) {
+    for (const view of VIEWS) {
+        const entries = Object.entries(view.queries);
+        if (entries.length === 1 && entries[0][1] === def)
+            return { view, name: entries[0][0] };
+    }
+    return undefined;
+}
+/** Prints what a definition returned, the way its command shows it. */
+function printOutput(def, output, input) {
+    if (def.text) {
+        const text = def.text(output);
+        if (text)
+            console.log(text);
+        return;
+    }
+    const shown = viewOf(def);
+    if (shown)
+        printPage(shown.view.build({ [shown.name]: output }, input));
+    else
+        console.log(JSON.stringify(output, null, 2));
+}
+/** The command for a definition. */
+export function definitionHandler(def) {
+    return async (ctx) => {
+        const input = cliInput(def, ctx.options);
+        const { io, close } = cliIO(ctx.options);
+        try {
+            const output = await runDefinition(def.id, ctx, input, io);
+            close();
+            if (def.cli?.json && ctx.options.json) {
+                printJson(ctx, def.cli.shapeJson ? def.cli.shapeJson(output) : output);
+                return 0;
+            }
+            printOutput(def, output, def.input.parse(input));
+            return 0;
+        }
+        catch (e) {
+            close();
+            if (!(e instanceof Cancelled))
+                throw e;
+            console.log(e.message);
+            return 1;
+        }
+    };
+}
+/** The command a parsed command line runs when it is one of the shared core's, else undefined. */
+export function operationHandler(command, positionals) {
+    const def = definitionFor(command, positionals);
+    return def ? definitionHandler(def) : undefined;
+}

package/dist/cli/operations/index.d.ts

@@ -0,0 +1,4 @@
+export { definitionHandler, operationHandler } from './handler.js';
+export { cliInput, definitionFor } from './input.js';
+export { cliIO } from './io-cli.js';
+export { actionDefinitions, commandDefinitions, commandSpecOf, inputField, withActions, withOperationCommands, } from './spec.js';

package/dist/cli/operations/index.js

@@ -0,0 +1,5 @@
+// The command line of the shared core: commands from definitions, their input, their terminal IO and their output.
+export { definitionHandler, operationHandler } from './handler.js';
+export { cliInput, definitionFor } from './input.js';
+export { cliIO } from './io-cli.js';
+export { actionDefinitions, commandDefinitions, commandSpecOf, inputField, withActions, withOperationCommands, } from './spec.js';

package/dist/cli/operations/input.d.ts

@@ -0,0 +1,6 @@
+import type { AnyDefinition } from '../../app/kernel/index.js';
+import type { CliOptions } from '../args.js';
+/** The definition a command runs: its own command, or an action of a hand-written one (`config get`). */
+export declare function definitionFor(command: string, positionals: readonly string[]): AnyDefinition | undefined;
+/** The input a command line gives a definition (fields not on the line are left to the schema's defaults). */
+export declare function cliInput(def: AnyDefinition, options: CliOptions): Record<string, unknown>;

package/dist/cli/operations/input.js

@@ -0,0 +1,37 @@
+// Which definition a parsed command line runs, and its input: positional arguments and flags mapped to input fields by
+// the definition's CLI hint (zod then checks them like any other input).
+import { DEFINITIONS } from '../../app/features/defs.js';
+import { fail } from '../../core/util/index.js';
+import { inputField } from './spec.js';
+/** The definition a command runs: its own command, or an action of a hand-written one (`config get`). */
+export function definitionFor(command, positionals) {
+    return DEFINITIONS.find((d) => d.cli?.name === command && (d.cli.action === undefined || d.cli.action === positionals[0]));
+}
+/** commander's attribute name for a long flag: --keep-old -> keepOld. */
+function attribute(flag) {
+    return flag.replace(/^--/, '').replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
+}
+/** The input a command line gives a definition (fields not on the line are left to the schema's defaults). */
+export function cliInput(def, options) {
+    const hint = def.cli;
+    if (!hint)
+        return {};
+    const positionals = hint.action ? options.positionals.slice(1) : options.positionals;
+    const names = hint.positional ?? [];
+    const missing = names.slice(positionals.length).filter((name) => !inputField(def, name).optional);
+    if (missing.length)
+        fail('Missing ' + missing.join(' and ') + '.', 'Usage: sandbox ' + [hint.name, hint.action, ...names.map((n) => '<' + n + '>')].filter(Boolean).join(' '));
+    const input = {};
+    names.forEach((name, i) => {
+        if (positionals[i] !== undefined)
+            input[name] = positionals[i];
+    });
+    for (const [name, flag] of Object.entries(hint.flags ?? {})) {
+        if (!flag)
+            continue;
+        const value = (flag.shownAs ? options.raw[attribute(flag.shownAs)] : undefined) ?? options.raw[attribute(flag.flag)];
+        if (value !== undefined)
+            input[name] = value;
+    }
+    return input;
+}

package/dist/cli/operations/io-cli.d.ts

@@ -0,0 +1,7 @@
+import type { OperationIO } from '../../app/kernel/index.js';
+import type { CliOptions } from '../args.js';
+/** An OperationIO for one command; close() removes a progress line still shown. */
+export declare function cliIO(options: CliOptions): {
+    io: OperationIO;
+    close: () => void;
+};