windows-development-sandbox 1.4.0 → 1.4.3

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

@@ -0,0 +1,176 @@
+// The settings screen: two scopes on tabs, your own settings ("All projects", blue) and this folder's
+// .sandbox-config.json ("This project", purple); Tab switches and keeps your place. Every setting is grouped into
+// categories (sidebar), searchable, with its value in both scopes, its default and description. Enter edits (on/off
+// flips at once), r resets. Edits keep the file's comments and formatting, and nothing is saved unless the whole file
+// stays valid.
+import _ from 'lodash';
+import { NEVER_LOOSER } from '../../../core/local-config/index.js';
+import { Text, Theme } from '../../tui/index.js';
+import { AppsCatalogue } from '../apps.js';
+import { CATEGORIES, categoryOf, nameOf } from './categories.js';
+import { formatValue } from './format.js';
+import { ValueEditor } from './value-editor.js';
+const SCOPES = [
+    { scope: 'user', tab: { label: 'All projects', badge: 'YOURS', paint: Theme.scopeGlobal } },
+    { scope: 'project', tab: { label: 'This project', badge: 'PROJECT', paint: Theme.scopeProject } },
+];
+export class SettingsEditor {
+    app;
+    files;
+    scope;
+    dataPath;
+    editor;
+    /** files: your config and this folder's project file; dataPath: where the apps catalogue looks for installed apps. */
+    constructor(app, files, scope = 'user', dataPath = '') {
+        this.app = app;
+        this.files = files;
+        this.scope = scope;
+        this.dataPath = dataPath;
+        this.editor = new ValueEditor(app, {
+            suggestions: (key) => ['defaultHarness', 'harness'].includes(key.join('.'))
+                ? Object.keys(this.file.userConfig().harnesses)
+                : undefined,
+        });
+    }
+    /** The file the current tab edits. */
+    get file() {
+        return this.files[this.scope];
+    }
+    get title() {
+        return 'Settings · ' + (this.file.isProject ? 'This project' : 'All projects');
+    }
+    /** Every editable setting with the category and heading it is shown under. */
+    settings() {
+        return this.file.schema.children().flatMap(([top, node]) => {
+            const category = categoryOf(top);
+            if (!category)
+                return [];
+            const several = category.keys.filter((k) => this.file.schema.child(k)).length > 1;
+            if (!node.isSection)
+                return [
+                    {
+                        key: [top],
+                        node,
+                        category: category.id,
+                        section: several && category.id !== 'general' ? nameOf(top) : undefined,
+                    },
+                ];
+            return node.leaves([top]).map(({ key, node: leaf }) => {
+                const heading = [
+                    several ? nameOf(top) : undefined,
+                    key.length > 2 ? key.slice(1, -1).map(nameOf).join(' › ') : undefined,
+                ]
+                    .filter(Boolean)
+                    .join(' › ');
+                return { key, node: leaf, category: category.id, section: heading || undefined };
+            });
+        });
+    }
+    item(s, config) {
+        const inFile = this.file.valueInFile(s.key);
+        const set = inFile !== undefined;
+        const yours = _.get(config, s.key);
+        const id = s.key.join('.');
+        const project = this.files.project;
+        const inProject = project.schema.leaves().some((l) => l.key.join('.') === id)
+            ? project.valueInFile(s.key)
+            : undefined;
+        const paint = this.file.isProject ? Theme.project : Theme.changed;
+        const value = this.file.isProject && !set
+            ? Theme.muted('all projects: ') + formatValue(yours, 40)
+            : formatValue(this.file.effective(s.key, config));
+        const details = [
+            Theme.muted('Setting       ') + id,
+            Theme.muted('All projects  ') +
+                formatValue(yours, 40) +
+                Theme.muted(this.files.user.valueInFile(s.key) === undefined ? '  (built-in default)' : '  (your file)'),
+            Theme.muted('This project  ') +
+                (inProject === undefined ? Theme.muted('not set') : Theme.project(Text.strip(formatValue(inProject, 40)))),
+            ...(!this.file.isProject ? [Theme.muted('Default       ') + formatValue(this.file.defaultOf(s.key), 40)] : []),
+            ...(this.file.isProject && NEVER_LOOSER.includes(id)
+                ? [Theme.warn(Theme.glyph.lock + ' A project can only make this stricter than your own setting.')]
+                : []),
+        ];
+        return {
+            value: id,
+            label: Text.humanize(s.key[s.key.length - 1]),
+            hint: set ? paint(Text.strip(value)) + ' ' + paint(Theme.glyph.changed) : value,
+            description: s.node.description,
+            details,
+            section: s.section,
+            category: s.category,
+            keywords: id,
+        };
+    }
+    async run() {
+        let focus;
+        let notice;
+        for (;;) {
+            const config = this.file.userConfig();
+            const settings = this.settings();
+            const categories = CATEGORIES.filter((c) => settings.some((s) => s.category === c.id)).map((c) => ({
+                id: c.id,
+                label: c.label,
+                description: c.description,
+            }));
+            const picked = await this.app.list({
+                path: [this.title],
+                tabs: { items: SCOPES.map((x) => x.tab), active: SCOPES.findIndex((x) => x.scope === this.scope) },
+                status: (this.file.isProject ? Theme.project('●') : Theme.accent('●')) +
+                    Theme.muted(' Editing ') +
+                    Text.middle(this.file.file, 80) +
+                    (this.file.exists ? '' : Theme.muted(' (created when you save)')) +
+                    (this.file.isProject
+                        ? Theme.muted('  · only what a project may set; needs your approval at the next launch')
+                        : ''),
+                items: settings.map((s) => this.item(s, config)),
+                categories,
+                startAt: focus,
+                actions: [{ key: 'r', label: this.file.isProject ? 'remove from project' : 'reset to default' }],
+                notice,
+            });
+            notice = undefined;
+            if (picked.kind === 'back')
+                return;
+            // The other tab, on the same setting when that scope has it.
+            if (picked.kind === 'tab') {
+                this.scope = SCOPES[picked.index].scope;
+                continue;
+            }
+            if (picked.kind !== 'pick' && picked.kind !== 'action')
+                continue;
+            if (picked.value === undefined)
+                continue;
+            focus = picked.value;
+            const setting = settings.find((s) => s.key.join('.') === picked.value);
+            if (picked.kind === 'action')
+                notice = this.save(setting.key, undefined, 'reset');
+            else
+                notice = await this.edit(setting, config);
+        }
+    }
+    async edit(s, config) {
+        // The apps list is picked from the catalogue (by category, with sizes), not typed.
+        if (s.key.join('.') === 'apps.install')
+            return new AppsCatalogue(this.app, this.file, this.dataPath).run();
+        const current = this.file.isProject ? (this.file.valueInFile(s.key) ?? _.get(config, s.key)) : _.get(config, s.key);
+        const path = [this.title, ...s.key.slice(0, -1).map(nameOf), Text.humanize(s.key[s.key.length - 1])];
+        const edited = await this.editor.edit(path, s.key, s.node, current);
+        return edited ? this.save(s.key, edited.value, 'save') : undefined;
+    }
+    /** Saves (or resets) one setting and returns the notice to show. */
+    save(key, value, how) {
+        const name = key.join('.');
+        const result = this.file.set(key, value);
+        if (result === 'unchanged')
+            return Theme.muted(how === 'reset' ? name + ' is already the default.' : 'Unchanged.');
+        if (typeof result === 'object')
+            return Theme.error(Theme.glyph.cross + ' Not saved: ' + result.problems.join('; '));
+        // The approval is tied to the file's exact contents, so any change makes the project file need approval again.
+        const after = this.file.isProject
+            ? ' The next launch asks you to approve the project file again.'
+            : ' New sandboxes use it.';
+        return (Theme.ok(Theme.glyph.ok + ' ' + (how === 'reset' ? 'Reset ' + name + '.' : 'Saved ' + name + '.')) +
+            Theme.muted(after));
+    }
+}

package/dist/cli/menu/settings/{editors.d.ts → value-editor.d.ts}

@@ -1,11 +1,9 @@
-import { App } from '../../tui/index.js';
-import { SchemaNode } from './schema-node.js';
+import { type App } from '../../tui/index.js';
+import { type SchemaNode } from './schema-node.js';
 /** The new value, or undefined when you backed out without changing anything. */
 export type Edited = {
     value: unknown;
 } | undefined;
-/** A value in one short line, for the right-hand column. */
-export declare const formatValue: (value: unknown, max?: number) => string;
 /** Optional extra knowledge: values to suggest for some settings (the configured agents for defaultHarness). */
 export interface EditorHints {
     suggestions?: (key: string[]) => string[] | undefined;
@@ -19,12 +17,3 @@ export declare class ValueEditor {
     private suggest;
     private json;
 }
-/** One object as a form: each field with its value, Enter to change it, r to clear an optional one. */
-export declare class ObjectEditor {
-    private readonly app;
-    private readonly path;
-    private readonly node;
-    private readonly editor;
-    constructor(app: App, path: string[], node: SchemaNode, editor: ValueEditor);
-    run(start: Record<string, unknown>, isNew?: boolean): Promise<Edited>;
-}

package/dist/cli/menu/settings/value-editor.js

@@ -0,0 +1,137 @@
+// Editing one value with the screen that fits it: on/off flips, choices are picked from a list, numbers and text are
+// typed and checked as you type, lists and maps get an editor of their own (add, change, remove), and objects (a
+// mapped folder, an agent) open as a small form. JSON is only the last resort for shapes none of these fit.
+import _ from 'lodash';
+import { Text } from '../../tui/index.js';
+import { choiceLabel } from './format.js';
+import { StringListEditor } from './collections/string-list-editor.js';
+import { MapEditor } from './collections/map-editor.js';
+import { ObjectListEditor } from './collections/object-list-editor.js';
+import { ObjectMapEditor } from './collections/object-map-editor.js';
+import { ObjectEditor } from './object-editor.js';
+export class ValueEditor {
+    app;
+    hints;
+    constructor(app, hints = {}) {
+        this.app = app;
+        this.hints = hints;
+    }
+    async edit(path, key, node, current) {
+        const about = node.description ? [node.description] : [];
+        const suggestions = this.hints.suggestions?.(key);
+        if (suggestions?.length && node.type === 'string')
+            return this.suggest(path, key, node, current, suggestions);
+        switch (node.editor) {
+            case 'boolean':
+                return { value: !(current ?? false) };
+            case 'choice':
+                return this.pick(path, node, current, node.choiceValues);
+            case 'union': {
+                const open = node.openOption;
+                const custom = '@custom';
+                const picked = await this.app.choose(path, node.description ?? '', [
+                    ...node.choiceValues.map((v) => ({ value: v, label: choiceLabel(v) })),
+                    ...(open
+                        ? [
+                            {
+                                value: custom,
+                                label: 'Custom ' + open.type + '…',
+                                description: 'Type a ' + open.type + ' of your own.',
+                            },
+                        ]
+                        : []),
+                ], node.choiceValues.includes(current) ? current : open && current !== undefined ? custom : undefined);
+                if (picked === undefined)
+                    return undefined;
+                return picked === custom && open
+                    ? this.edit(path, key, open, node.choiceValues.includes(current) ? undefined : current)
+                    : { value: picked };
+            }
+            case 'number': {
+                const range = node.min !== undefined || node.max !== undefined
+                    ? ' (' + (node.min ?? '…') + ' to ' + (node.max ?? '…') + ')'
+                    : '';
+                const typed = await this.app.text({
+                    path,
+                    label: Text.humanize(key[key.length - 1]) + range,
+                    about,
+                    initial: current === undefined ? '' : String(current),
+                    validate: (v) => (v.trim() === '' || !Number.isFinite(Number(v)) ? 'Enter a number.' : node.check(Number(v))),
+                });
+                return typed === undefined ? undefined : { value: Number(typed) };
+            }
+            case 'string': {
+                const typed = await this.app.text({
+                    path,
+                    label: Text.humanize(key[key.length - 1]),
+                    about,
+                    initial: typeof current === 'string' ? current : '',
+                    allowEmpty: node.check('') === true,
+                    validate: (v) => node.check(v),
+                });
+                return typed === undefined ? undefined : { value: typed };
+            }
+            case 'choice-list': {
+                const ticked = Array.isArray(current) ? current : [];
+                const picked = await this.app.list({
+                    path,
+                    intro: node.description,
+                    multi: true,
+                    items: node.element.choices.map((v) => ({ value: v, label: String(v), checked: ticked.includes(v) })),
+                });
+                return picked.kind === 'multi' ? { value: picked.values } : undefined;
+            }
+            case 'string-list':
+                return new StringListEditor(this.app, path, node, this).run(Array.isArray(current) ? current : []);
+            case 'string-map':
+                return new MapEditor(this.app, path, node, this).run(_.isPlainObject(current) ? current : {});
+            case 'object-list':
+                return new ObjectListEditor(this.app, path, node, this).run(Array.isArray(current) ? current : []);
+            case 'object-map':
+                return new ObjectMapEditor(this.app, path, node, this).run(_.isPlainObject(current) ? current : {});
+            case 'object':
+                return new ObjectEditor(this.app, path, node, this).run(_.isPlainObject(current) ? current : node.initial());
+            default:
+                return this.json(path, key, node, current);
+        }
+    }
+    async pick(path, node, current, values) {
+        const picked = await this.app.choose(path, node.description ?? '', values.map((v) => ({ value: v, label: choiceLabel(v) })), current);
+        return picked === undefined ? undefined : { value: picked };
+    }
+    async suggest(path, key, node, current, suggestions) {
+        const other = '@other';
+        const picked = await this.app.choose(path, node.description ?? '', [
+            ...suggestions.map((s) => ({ value: s, label: s })),
+            { value: other, label: 'Other…', description: 'Type a name that is not in the list.' },
+        ], typeof current === 'string' ? current : undefined);
+        if (picked === undefined)
+            return undefined;
+        if (picked !== other)
+            return { value: picked };
+        const typed = await this.app.text({
+            path,
+            label: Text.humanize(key[key.length - 1]),
+            initial: typeof current === 'string' ? current : '',
+            validate: (v) => node.check(v),
+        });
+        return typed === undefined ? undefined : { value: typed };
+    }
+    async json(path, key, node, current) {
+        const typed = await this.app.text({
+            path,
+            label: Text.humanize(key[key.length - 1]) + ' (JSON)',
+            about: node.description ? [node.description] : [],
+            initial: current === undefined ? '' : JSON.stringify(current),
+            validate: (v) => {
+                try {
+                    return node.check(JSON.parse(v));
+                }
+                catch {
+                    return 'This is not valid JSON.';
+                }
+            },
+        });
+        return typed === undefined ? undefined : { value: JSON.parse(typed) };
+    }
+}

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

@@ -1,15 +1,15 @@
 import type { Context } from '../commands/context.js';
-import { App } from '../tui/index.js';
+import { type App } from '../tui/index.js';
 /** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
-export declare const candidateFolders: (ctx: Context, cwd?: string) => string[];
+export declare function candidateFolders(ctx: Context, cwd?: string): string[];
 /** The command line for several sessions: one --session per (agent, folder), with the shared options. */
-export declare const severalAgentsArgv: (sessions: {
+export declare function severalAgentsArgv(sessions: {
     harness: string;
     folder: string;
 }[], o: {
     headless: boolean;
     attachFirst: boolean;
-}) => string[];
+}): string[];
 export declare class SeveralAgents {
     private readonly app;
     private readonly ctx;

package/dist/cli/menu/several.js

@@ -3,25 +3,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { assertSafeWorkspace } from '../../core/safe-paths.js';
-import { errMsg, expandPath } from '../../core/util.js';
-import { readKnown } from '../../host/projects.js';
-import { isWithin } from '../../shared/projects.js';
+import { errMsg, expandPath } from '../../core/util/index.js';
+import { KnownProjects } from '../../host/projects/index.js';
+import { isWithin } from '../../shared/paths/index.js';
 import { commandLine } from '../history.js';
 import { Text, Theme } from '../tui/index.js';
 /** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
-export const candidateFolders = (ctx, cwd = process.cwd()) => {
+export function candidateFolders(ctx, cwd = process.cwd()) {
     const roots = ctx.loaded.config.projects.roots.map((r) => expandPath(r, ctx.loaded.base));
-    const inRoots = roots.flatMap((r) => { try {
-        return fs.readdirSync(r, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.')).slice(0, 200).map((e) => path.join(r, e.name));
-    }
-    catch {
-        return [];
-    } });
-    const all = [path.resolve(cwd), ...readKnown(ctx.storageRoot).map((k) => k.host), ...inRoots];
+    const inRoots = roots.flatMap((r) => {
+        try {
+            return fs
+                .readdirSync(r, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.'))
+                .slice(0, 200)
+                .map((e) => path.join(r, e.name));
+        }
+        catch {
+            return [];
+        }
+    });
+    const all = [path.resolve(cwd), ...new KnownProjects(ctx.storageRoot).list().map((k) => k.host), ...inRoots];
     return all.filter((f, i) => all.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i && fs.existsSync(f));
-};
+}
 /** The command line for several sessions: one --session per (agent, folder), with the shared options. */
-export const severalAgentsArgv = (sessions, o) => ['launch', ...sessions.flatMap((s) => ['--session', s.harness + '@' + s.folder]), ...(o.headless ? ['--headless'] : []), ...(o.attachFirst ? ['-t'] : [])];
+export function severalAgentsArgv(sessions, o) {
+    return [
+        'launch',
+        ...sessions.flatMap((s) => ['--session', s.harness + '@' + s.folder]),
+        ...(o.headless ? ['--headless'] : []),
+        ...(o.attachFirst ? ['-t'] : []),
+    ];
+}
 const ADD = '@add';
 export class SeveralAgents {
     app;
@@ -39,7 +52,9 @@ export class SeveralAgents {
         const sessions = [];
         for (const folder of folders) {
             const picked = await this.app.list({
-                path: [...this.path, path.basename(folder)], intro: 'Agents for ' + folder + ' (one session each). Space ticks, Enter continues.', multi: true,
+                path: [...this.path, path.basename(folder)],
+                intro: 'Agents for ' + folder + ' (one session each). Space ticks, Enter continues.',
+                multi: true,
                 items: agents.map((a) => ({ value: a, label: a, checked: a === this.ctx.loaded.config.defaultHarness })),
             });
             if (picked.kind !== 'multi')
@@ -48,7 +63,12 @@ export class SeveralAgents {
         }
         if (!sessions.length)
             return null;
-        const headless = await this.app.confirm({ path: this.path, question: 'Hide the sandbox window (headless)?', about: ['sandbox show brings it back.'], initial: this.ctx.loaded.config.sandbox.headless });
+        const headless = await this.app.confirm({
+            path: this.path,
+            question: 'Hide the sandbox window (headless)?',
+            about: ['sandbox show brings it back.'],
+            initial: this.ctx.loaded.config.sandbox.headless,
+        });
         const attach = await this.app.choose(this.path, 'Attach this terminal to one of them? Each session also has a tab inside the sandbox; sandbox attach shows any of them later.', [
             { value: -1, label: 'None' },
             ...sessions.map((s, i) => ({ value: i, label: s.harness + ' in ' + Text.middle(s.folder, 60) })),
@@ -60,8 +80,21 @@ export class SeveralAgents {
         const argv = severalAgentsArgv(ordered, { headless, attachFirst: attach >= 0 });
         const projects = [...new Set(sessions.map((s) => path.basename(s.folder)))];
         const go = await this.app.confirm({
-            path: this.path, question: 'Start them?',
-            about: ['One sandbox with ' + sessions.length + ' session' + (sessions.length === 1 ? '' : 's') + ': ' + ordered.map((s) => s.harness + ' in ' + path.basename(s.folder)).join(', ') + '. Maps ' + projects.join(' and ') + '.', '', '$ ' + commandLine(argv)],
+            path: this.path,
+            question: 'Start them?',
+            about: [
+                'One sandbox with ' +
+                    sessions.length +
+                    ' session' +
+                    (sessions.length === 1 ? '' : 's') +
+                    ': ' +
+                    ordered.map((s) => s.harness + ' in ' + path.basename(s.folder)).join(', ') +
+                    '. Maps ' +
+                    projects.join(' and ') +
+                    '.',
+                '',
+                '$ ' + commandLine(argv),
+            ],
         });
         return go ? argv : null;
     }
@@ -69,9 +102,16 @@ export class SeveralAgents {
         const here = path.resolve(process.cwd());
         const candidates = candidateFolders(this.ctx);
         const picked = await this.app.list({
-            path: this.path, intro: 'Which projects? Each gets its own sessions; all of them are mapped into one sandbox. Space ticks, Enter continues.', multi: true,
+            path: this.path,
+            intro: 'Which projects? Each gets its own sessions; all of them are mapped into one sandbox. Space ticks, Enter continues.',
+            multi: true,
             items: [
-                ...candidates.map((f) => ({ value: f, label: Text.middle(f, 90), hint: isWithin(f, here) && isWithin(here, f) ? Theme.muted('this folder') : undefined, checked: f.toLowerCase() === here.toLowerCase() })),
+                ...candidates.map((f) => ({
+                    value: f,
+                    label: Text.middle(f, 90),
+                    hint: isWithin(f, here) && isWithin(here, f) ? Theme.muted('this folder') : undefined,
+                    checked: f.toLowerCase() === here.toLowerCase(),
+                })),
                 { value: ADD, label: '+ Another folder…' },
             ],
         });
@@ -80,7 +120,8 @@ export class SeveralAgents {
         const folders = picked.values.filter((f) => f !== ADD);
         if (picked.values.includes(ADD)) {
             const extra = await this.app.text({
-                path: this.path, label: 'Folder to add',
+                path: this.path,
+                label: 'Folder to add',
                 validate: (v) => {
                     const dir = path.resolve(v.trim());
                     if (!v.trim() || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory())

package/dist/cli/{colors.d.ts → output/colors.d.ts}

@@ -1,5 +1,5 @@
 /** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
-export declare const colorEnabled: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
+export declare function colorEnabled(env: NodeJS.ProcessEnv, isTTY: boolean): boolean;
 export declare const c: {
     bold: (text: string) => string;
     dim: (text: string) => string;
@@ -9,16 +9,16 @@ export declare const c: {
     cyan: (text: string) => string;
 };
 /** Removes colour codes (for measuring or comparing text). */
-export declare const stripAnsi: (text: string) => string;
+export declare function stripAnsi(text: string): string;
 /** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
-export declare const shorten: (text: string, max: number) => string;
+export declare function shorten(text: string, max: number): string;
 /** Cuts the middle out of a long path or id so both ends stay readable. */
-export declare const shortenMiddle: (text: string, max: number) => string;
+export declare function shortenMiddle(text: string, max: number): string;
 /** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
-export declare const ago: (then: number | string | Date, now?: number) => string;
+export declare function ago(then: number | string | Date, now?: number): string;
 /** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
-export declare const termWidth: () => number;
+export declare function termWidth(): number;
 /** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
-export declare const clearScreen: () => void;
+export declare function clearScreen(): void;
 /** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
-export declare const pageSizeFor: (wanted: number) => number;
+export declare function pageSizeFor(wanted: number): number;

package/dist/cli/{colors.js → output/colors.js}

@@ -1,29 +1,41 @@
 // ANSI colours for terminal output (one place, so menus, errors and warnings agree).
-// Colour is on only for a terminal that wants it: not with NO_COLOR, TERM=dumb or piped output; FORCE_COLOR turns it on.
+// Colour is on only for a terminal that wants it: not with NO_COLOR, TERM=dumb or piped output; FORCE_COLOR turns it
+// on.
 /** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
-export const colorEnabled = (env, isTTY) => {
+export function colorEnabled(env, isTTY) {
     if (env.NO_COLOR)
         return false;
     if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '')
         return env.FORCE_COLOR !== '0' && env.FORCE_COLOR !== 'false';
     return isTTY && env.TERM !== 'dumb';
+}
+const paint = (code) => (text) => colorEnabled(process.env, Boolean(process.stdout.isTTY)) ? '\x1b[' + code + 'm' + text + '\x1b[0m' : text;
+export const c = {
+    bold: paint(1),
+    dim: paint(2),
+    red: paint(31),
+    green: paint(32),
+    yellow: paint(33),
+    cyan: paint(36),
 };
-const paint = (code) => (text) => (colorEnabled(process.env, Boolean(process.stdout.isTTY)) ? '\x1b[' + code + 'm' + text + '\x1b[0m' : text);
-export const c = { bold: paint(1), dim: paint(2), red: paint(31), green: paint(32), yellow: paint(33), cyan: paint(36) };
 /** Removes colour codes (for measuring or comparing text). */
-export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+export function stripAnsi(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
 /** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
-export const shorten = (text, max) => (max < 2 || text.length <= max ? text : text.slice(0, max - 1) + '…');
+export function shorten(text, max) {
+    return max < 2 || text.length <= max ? text : text.slice(0, max - 1) + '…';
+}
 /** Cuts the middle out of a long path or id so both ends stay readable. */
-export const shortenMiddle = (text, max) => {
+export function shortenMiddle(text, max) {
     if (max < 5 || text.length <= max)
         return text;
     const keep = max - 1;
     const head = Math.ceil(keep / 2);
     return text.slice(0, head) + '…' + text.slice(text.length - (keep - head));
-};
+}
 /** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
-export const ago = (then, now = Date.now()) => {
+export function ago(then, now = Date.now()) {
     const secs = Math.max(0, Math.round((now - new Date(then).getTime()) / 1000));
     if (secs < 45)
         return 'just now';
@@ -32,11 +44,17 @@ export const ago = (then, now = Date.now()) => {
     if (secs < 86400)
         return Math.round(secs / 3600) + ' h ago';
     return Math.round(secs / 86400) + ' d ago';
-};
+}
 /** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
-export const termWidth = () => Math.max(40, process.stdout.columns ?? 80);
+export function termWidth() {
+    return Math.max(40, process.stdout.columns ?? 80);
+}
 /** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
-export const clearScreen = () => { if (process.stdout.isTTY)
-    process.stdout.write('\x1b[2J\x1b[3J\x1b[H'); };
+export function clearScreen() {
+    if (process.stdout.isTTY)
+        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+}
 /** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
-export const pageSizeFor = (wanted) => Math.max(5, Math.min(wanted, (process.stdout.rows ?? 30) - 6));
+export function pageSizeFor(wanted) {
+    return Math.max(5, Math.min(wanted, (process.stdout.rows ?? 30) - 6));
+}

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

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './progress.js';
+export * from './print.js';

package/dist/cli/output/index.js

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './progress.js';
+export * from './print.js';

package/dist/cli/output/print.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '../commands/context.js';
+/** Prints rows as aligned columns (the last column is not padded). */
+export declare function table(rows: string[][]): void;
+/** Prints `value` as JSON when --json was given; returns whether it did. */
+export declare function printJson(ctx: Context, value: unknown): boolean;

package/dist/cli/output/print.js

@@ -0,0 +1,14 @@
+import _ from 'lodash';
+/** Prints rows as aligned columns (the last column is not padded). */
+export function table(rows) {
+    const widths = _.range(_.max(rows.map((r) => r.length)) ?? 0).map((i) => _.max(rows.map((r) => (r[i] ?? '').length)) ?? 0);
+    for (const row of rows)
+        console.log(row.map((cell, i) => (i === row.length - 1 ? cell : _.padEnd(cell, widths[i] + 2))).join(''));
+}
+/** Prints `value` as JSON when --json was given; returns whether it did. */
+export function printJson(ctx, value) {
+    // JSON.stringify leaves C1 controls (U+0080-U+009F) as they are; text from the sandbox must not reach a terminal raw.
+    if (ctx.options.json)
+        console.log(JSON.stringify(value, null, 2).replace(/[\u0080-\u009f]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0')));
+    return ctx.options.json;
+}

package/dist/cli/output/progress.d.ts

@@ -0,0 +1,24 @@
+/** Can a line be redrawn in place? */
+export declare function canAnimate(env: NodeJS.ProcessEnv, isTTY: boolean): boolean;
+/** "12 s", "2 min 5 s". */
+export declare function elapsed(ms: number): string;
+/** One line of progress: `line` is shown, `key` changes when it is worth a new plain line, `what` names what runs. */
+export interface Progressing {
+    line: string;
+    key: string;
+    what: string;
+}
+/**
+ * Follows long work (a sandbox's boot): on a terminal one line redrawn in place with the time so far; without one a
+ * plain line each time `key` changes. When nothing changes for `stallMs` it says so (stall(what, ms)). A failure first
+ * prints where it stopped, then rethrows.
+ */
+export declare function follow<T>(show: () => Progressing, work: () => Promise<T>, o: {
+    stallMs?: number;
+    stall: (what: string, ms: number) => string;
+}): Promise<T>;
+/**
+ * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
+ * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.
+ */
+export declare function working<T>(message: string | (() => string), work: () => Promise<T> | T, enabled?: boolean): Promise<T>;