windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/menu/add-agent.js

@@ -0,0 +1,168 @@
+// "Add an agent": a few questions (how it installs, its name, its package or program) that end in a new entry of
+// `harnesses` in your own config file. It is written at once, unless harnesses has unsaved changes in Settings (then
+// it joins them). Everything else about the agent (arguments, login folders ...) is edited in Settings > Agents &
+// sessions.
+import { DEFAULTS } from '../../core/config/index.js';
+import { HarnessSchema, NameSchema, describeIssues } from '../../core/schema/index.js';
+import { fail } from '../../core/util/index.js';
+import { askPath } from './settings/ask-path.js';
+/** Nothing wrong with the name (true), or what is wrong. Pure. */
+export function agentNameProblem(name, taken) {
+    const typed = name.trim();
+    if (!typed)
+        return 'Type a name.';
+    const parsed = NameSchema.safeParse(typed);
+    if (!parsed.success)
+        return 'Use letters, numbers, - and _ only.';
+    if (taken.some((t) => t.toLowerCase() === typed.toLowerCase()))
+        return typed + ' is an agent already.';
+    return true;
+}
+/** The command a package usually provides: "@scope/my-agent@latest" gives "my-agent". Pure. */
+export function commandFromPackage(pkg) {
+    const version = pkg.lastIndexOf('@');
+    const bare = version > 0 ? pkg.slice(0, version) : pkg;
+    return (bare.split(/[\\/]/).pop() ?? '').replace(/[^A-Za-z0-9._-]/g, '');
+}
+/** The config entry for a new agent. Pure. */
+export function newAgent(source, what, command, hostDir = 'auto') {
+    const common = { arguments: [], environment: {} };
+    if (source === 'npm')
+        return { ...common, npmPackage: what, npmBin: command };
+    if (source === 'uv')
+        return { ...common, uvPackage: what, uvBin: command };
+    return { ...common, hostExecutable: what, hostDir };
+}
+/** What `harnesses` should say with `name` taken out. Pure. */
+export function withoutAgent(current, name) {
+    const rest = { ...(current && typeof current === 'object' ? current : {}) };
+    delete rest[name];
+    return rest;
+}
+/** Writes a setting to your config file now, or adds it to the unsaved changes when it has some already. */
+export function writeOrStage(file, draft, key, value) {
+    if (draft.has(file, key)) {
+        draft.stage(file, key, value);
+        return { saved: false };
+    }
+    const result = file.set(key, value);
+    if (typeof result === 'object')
+        fail('It could not be saved: ' + result.problems.join('; '));
+    return { saved: true };
+}
+/** What `harnesses` should say with `name` added to what is staged or in the file now. Pure. */
+export function withAgent(current, name, harness) {
+    return { ...(current && typeof current === 'object' ? current : {}), [name]: harness };
+}
+/** The staged value of a setting, else what your own file says (what `harnesses` or `defaultHarness` will be). */
+function current(file, draft, key) {
+    return draft.has(file, key) ? draft.value(file, key) : file.valueInFile(key);
+}
+/** Makes `name` the agent that starts by default (written now, or joined to unsaved changes to that setting). */
+export function makeDefaultAgent(file, draft, name) {
+    return writeOrStage(file, draft, ['defaultHarness'], name);
+}
+/** Takes an agent you added out of your settings (the built-in ones are not removable). */
+export function removeAgent(file, draft, name) {
+    if (name in DEFAULTS.harnesses)
+        fail(name + ' is built in, so it cannot be removed.');
+    const key = ['harnesses'];
+    const standing = current(file, draft, ['defaultHarness']) ?? file.userConfig().defaultHarness;
+    if (standing === name)
+        fail(name + ' is the default agent.', 'Make another agent the default first.');
+    const rest = withoutAgent(current(file, draft, key), name);
+    // Nothing of your own left: the setting goes (the built-in agents need no line).
+    return writeOrStage(file, draft, key, Object.keys(rest).length ? rest : undefined);
+}
+export class AddAgent {
+    app;
+    file;
+    draft;
+    taken;
+    constructor(app, file, draft, 
+    /** Every agent that exists now (the new name must be different). */
+    taken) {
+        this.app = app;
+        this.file = file;
+        this.draft = draft;
+        this.taken = taken;
+    }
+    /** Asks, then adds the agent. Undefined when you backed out. */
+    async run() {
+        const path = ['Agents', 'Add an agent'];
+        const source = await this.app.choose(path, 'How does the agent get into the sandbox?', [
+            {
+                value: 'npm',
+                label: 'An npm package',
+                description: 'Installed inside the sandbox with npm once and kept (e.g. @openai/codex).',
+            },
+            {
+                value: 'uv',
+                label: 'A Python package',
+                description: 'Installed inside the sandbox with uv once and kept (e.g. aider-chat).',
+            },
+            {
+                value: 'host',
+                label: 'A program on this PC',
+                description: 'An .exe copied from this PC into the sandbox (looked up on PATH and in ~/.local/bin).',
+            },
+        ]);
+        if (!source)
+            return undefined;
+        const name = await this.app.text({
+            path,
+            label: 'Name of the agent',
+            about: ['What you type after "sandbox", e.g. sandbox <name>. Letters, numbers, - and _.'],
+            validate: (v) => agentNameProblem(v, this.taken),
+        });
+        if (!name)
+            return undefined;
+        if (source === 'host') {
+            const exe = await askPath(this.app, {
+                path,
+                title: 'Choose the program (.exe)',
+                about: ['The agent program on this PC. It is copied into the sandbox. A bare file name is looked up on PATH.'],
+                kind: 'file',
+                validate: (v) => (v.trim() ? true : 'Choose a file.'),
+            });
+            if (!exe)
+                return undefined;
+            const slash = Math.max(exe.lastIndexOf('\\'), exe.lastIndexOf('/'));
+            const dir = slash > 0 ? exe.slice(0, slash) : 'auto';
+            return this.add(name.trim(), newAgent('host', exe.slice(slash + 1), '', dir));
+        }
+        const what = await this.app.text({
+            path,
+            label: source === 'npm' ? 'npm package' : 'Python package',
+            about: [
+                source === 'npm'
+                    ? 'The package to install, optionally with a version: @scope/name or name@latest.'
+                    : 'The package for `uv tool install`.',
+            ],
+            validate: (v) => (v.trim() ? true : 'Type it.'),
+        });
+        if (!what)
+            return undefined;
+        const command = await this.app.text({
+            path,
+            label: 'Command',
+            about: ['The command the package provides; it is what runs inside the sandbox.'],
+            initial: commandFromPackage(what.trim()),
+            validate: (v) => (/^[A-Za-z0-9._-]+$/.test(v.trim()) ? true : 'Letters, numbers, . - and _ only.'),
+        });
+        if (!command)
+            return undefined;
+        return this.add(name.trim(), newAgent(source, what.trim(), command.trim()));
+    }
+    /** Validates and writes (or stages) the entry. */
+    add(name, harness) {
+        const checked = HarnessSchema.safeParse(harness);
+        if (!checked.success)
+            fail('That agent is not valid: ' + describeIssues(checked.error).join('; '));
+        const key = ['harnesses'];
+        return {
+            name,
+            ...writeOrStage(this.file, this.draft, key, withAgent(current(this.file, this.draft, key), name, harness)),
+        };
+    }
+}

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

@@ -1,8 +1,43 @@
-import { type AppEntry } from '../../shared/apps/index.js';
+import { type AppCategory, type AppEntry } from '../../shared/apps/index.js';
 import { type Category, type ListItem } from '../tui/index.js';
-import type { ConfigFile } from './settings/config-file.js';
+import type { ConfigFile } from '../../app/features/settings/index.js';
 import type { Draft } from './settings/draft.js';
 export declare const CUSTOM = "@custom:";
+/** The catalogue has many small categories; the menu shows these few groups so the navigation stays short. */
+export declare const APP_GROUPS: readonly [{
+    readonly id: "editors";
+    readonly label: "Editors & docs";
+    readonly description: "Code and text editors (VS Code is on by default), plus diagrams and document conversion.";
+    readonly members: readonly ["editors", "diagrams"];
+}, {
+    readonly id: "clients";
+    readonly label: "DB & API clients";
+    readonly description: "GUIs for the sandbox databases, tools to send HTTP, REST and GraphQL requests, and to inspect traffic.";
+    readonly members: readonly ["databases", "api", "network"];
+}, {
+    readonly id: "tools";
+    readonly label: "Git & utilities";
+    readonly description: "Git GUIs and terminal UIs, archives, file search and comparing, process tools, and decompilers.";
+    readonly members: readonly ["git", "utilities", "reversing"];
+}, {
+    readonly id: "cli";
+    readonly label: "Command-line & cloud";
+    readonly description: "Small developer tools (JSON, search, builds, media ...) and tools for clouds and Kubernetes.";
+    readonly members: readonly ["cli", "cloud"];
+}, {
+    readonly id: "play";
+    readonly label: "Browsers & games";
+    readonly description: "Browsers for testing web apps, and game engines and editors (they draw with OpenGL on the CPU).";
+    readonly members: readonly ["browsers", "gamedev"];
+}];
+/** The group an app category is shown under. */
+export declare function groupOf(category: AppCategory): string;
+/** The row in Apps that opens the "request an app" issue form (its id is not an app). */
+export declare const REQUEST_APP = "@request-app";
+/** This project's new-issue page on GitHub. */
+export declare const ISSUES_URL = "https://github.com/JoshDiDuca/windows-development-sandbox/issues/new";
+/** The new-issue address with a title and a body to fill in (the page needs no login to show it). */
+export declare function requestAppUrl(): string;
 export declare class AppsModel {
     private readonly file;
     private readonly dataPath;
@@ -29,6 +64,6 @@ export declare class AppsModel {
     /** Stages the ticks of the list: only what differs from the saved file is kept in the draft. */
     stageTicks(draft: Draft, ticked: readonly string[]): void;
 }
-/** For the Start tab and notices: "12 apps chosen". */
+/** For notices: "12 apps chosen". */
 export declare function appsSummary(file: ConfigFile): string;
 export declare function appLabel(id: string): string;

package/dist/cli/menu/apps.js

@@ -4,10 +4,71 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
-import { APP_CATEGORIES, APPS } from '../../shared/apps/index.js';
+import { APPS } from '../../shared/apps/index.js';
 import { Text, Theme } from '../tui/index.js';
 export const CUSTOM = '@custom:';
+/** The catalogue has many small categories; the menu shows these few groups so the navigation stays short. */
+export const APP_GROUPS = [
+    {
+        id: 'editors',
+        label: 'Editors & docs',
+        description: 'Code and text editors (VS Code is on by default), plus diagrams and document conversion.',
+        members: ['editors', 'diagrams'],
+    },
+    {
+        id: 'clients',
+        label: 'DB & API clients',
+        description: 'GUIs for the sandbox databases, tools to send HTTP, REST and GraphQL requests, and to inspect traffic.',
+        members: ['databases', 'api', 'network'],
+    },
+    {
+        id: 'tools',
+        label: 'Git & utilities',
+        description: 'Git GUIs and terminal UIs, archives, file search and comparing, process tools, and decompilers.',
+        members: ['git', 'utilities', 'reversing'],
+    },
+    {
+        id: 'cli',
+        label: 'Command-line & cloud',
+        description: 'Small developer tools (JSON, search, builds, media ...) and tools for clouds and Kubernetes.',
+        members: ['cli', 'cloud'],
+    },
+    {
+        id: 'play',
+        label: 'Browsers & games',
+        description: 'Browsers for testing web apps, and game engines and editors (they draw with OpenGL on the CPU).',
+        members: ['browsers', 'gamedev'],
+    },
+];
+/** The group an app category is shown under. */
+export function groupOf(category) {
+    return APP_GROUPS.find((g) => g.members.includes(category))?.id ?? 'tools';
+}
 const INSTALL = ['apps', 'install'];
+/** The row in Apps that opens the "request an app" issue form (its id is not an app). */
+export const REQUEST_APP = '@request-app';
+/** This project's new-issue page on GitHub. */
+export const ISSUES_URL = 'https://github.com/JoshDiDuca/windows-development-sandbox/issues/new';
+/** The new-issue address with a title and a body to fill in (the page needs no login to show it). */
+export function requestAppUrl() {
+    const body = [
+        '**App name:**',
+        '',
+        '**Where to get it** (GitHub releases page or a direct download link):',
+        '',
+        '**What it is for:**',
+        '',
+        '**Command-line tool or desktop app?**',
+        '',
+        '**Does it need a GPU, a license or an account?**',
+    ].join('\n');
+    const query = [
+        ['title', 'App request: '],
+        ['body', body],
+        ['labels', 'app-request'],
+    ];
+    return ISSUES_URL + '?' + query.map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&');
+}
 export class AppsModel {
     file;
     dataPath;
@@ -21,7 +82,7 @@ export class AppsModel {
     }
     categories() {
         return [
-            ...APP_CATEGORIES,
+            ...APP_GROUPS.map(({ id, label, description }) => ({ id, label, description })),
             ...(this.file.isProject
                 ? []
                 : [
@@ -81,13 +142,15 @@ export class AppsModel {
             ...(entry.needs?.includes('mesa')
                 ? [Theme.muted('Graphics  ') + 'OpenGL on the CPU (Mesa) is added for it']
                 : []),
-            ...(entry.fullGitOnly ? [Theme.warn('Needs provisioning.git.access "full" (it pushes with its own git).')] : []),
+            ...(entry.fullGitOnly
+                ? [Theme.warn('Needs full git access (Settings > Projects & setup > Git): it pushes with its own git.')]
+                : []),
             ...(entry.setting ? [Theme.muted('Setting   ') + entry.setting] : []),
         ];
         return {
             value: entry.id,
             label: entry.name,
-            category: entry.category,
+            category: groupOf(entry.category),
             description: entry.about,
             details: notes,
             keywords: entry.id,
@@ -98,6 +161,18 @@ export class AppsModel {
     items(draft) {
         return [
             ...this.entries().map((a) => this.item(a, draft)),
+            ...(this.file.isProject
+                ? []
+                : [
+                    {
+                        value: REQUEST_APP,
+                        label: 'Request an app…',
+                        category: 'custom',
+                        description: 'Not in the list? Press r: your browser opens a prefilled request on GitHub (' + ISSUES_URL + ').',
+                        hint: Theme.muted('press r'),
+                        disabled: 'Press r to open the request form on GitHub.',
+                    },
+                ]),
             ...Object.entries(this.custom(draft)).map(([id, a]) => ({
                 value: CUSTOM + id,
                 label: a.name,
@@ -128,7 +203,7 @@ export class AppsModel {
             draft.stage(this.file, INSTALL, wanted.length || this.file.isProject ? wanted : undefined);
     }
 }
-/** For the Start tab and notices: "12 apps chosen". */
+/** For notices: "12 apps chosen". */
 export function appsSummary(file) {
     const config = file.userConfig();
     const n = config.apps.install.length + Object.keys(config.apps.custom).length;

package/dist/cli/menu/command-fields.d.ts

@@ -1,4 +1,5 @@
 import { type ArgSpec, type OptionSpec } from '../manifest.js';
+import type { PathKind } from '../../app/kernel/index.js';
 /** What an option accepts, checked while typing (undefined = fine). */
 export declare function optionProblem(o: OptionSpec, v: string): string | undefined;
 export type Field = {
@@ -13,3 +14,20 @@ export type Field = {
 } | {
     kind: 'extra';
 };
+/** The name of an option in the form: its plain label, else the flag made readable (never the raw flag). */
+export declare function optionLabel(o: OptionSpec): string;
+/** The name of an argument in the form. */
+export declare function argLabel(a: ArgSpec): string;
+/** A summary as a sentence for the top of the form: "(beta) your sandbox ..." reads "Beta: your sandbox ...". */
+export declare function plainSummary(summary: string): string;
+/**
+ * A description for the form. A leading "(rename)" / "(save)" names the action it belongs to: the form only asks it for
+ * that action, so the prefix is dropped. Any other prefix "(claude)" becomes "For claude: ...".
+ */
+export declare function plainDescription(text: string, actions: readonly string[]): string;
+/** The action a description names with a leading "(action)", when it is one of `actions`. */
+export declare function actionOf(text: string, actions: readonly string[]): string | undefined;
+/** A folder or file option (a placeholder of dir / file), or one known by name. */
+export declare function optionPathKind(o: OptionSpec): PathKind | undefined;
+/** A folder or file argument; `first` is the answer to the command's first argument (the action). */
+export declare function argPathKind(a: ArgSpec, command: string, first: string): PathKind | undefined;

package/dist/cli/menu/command-fields.js

@@ -1,6 +1,9 @@
+// What the command form knows about a field: what to call it, how its description reads once the form is filtered by
+// action, and what kind of value it takes (a folder, a file, a number ...). Pure, so the form and its tests share it.
 import fs from 'node:fs';
 import path from 'node:path';
 import { splitArgs } from '../args.js';
+import { Text } from '../tui/index.js';
 import { validNodeSpec, validPythonSpec } from '../validate.js';
 /** What an option accepts, checked while typing (undefined = fine). */
 export function optionProblem(o, v) {
@@ -21,3 +24,61 @@ export function optionProblem(o, v) {
     }
     return undefined;
 }
+/** Plain names for arguments whose own name is a code word. */
+const ARG_LABELS = {
+    id: 'Session',
+    action: 'What to do',
+    targets: 'What to delete',
+    suite: 'Test suites',
+    value: 'Value',
+    folder: 'Folder',
+    command: 'Command',
+};
+/** The name of an option in the form: its plain label, else the flag made readable (never the raw flag). */
+export function optionLabel(o) {
+    return o.label ?? Text.humanize(o.flag.replace(/^--/, ''));
+}
+/** The name of an argument in the form. */
+export function argLabel(a) {
+    return ARG_LABELS[a.name] ?? Text.humanize(a.name);
+}
+const upper = (text) => text.replace(/^./, (c) => c.toUpperCase());
+/** A summary as a sentence for the top of the form: "(beta) your sandbox ..." reads "Beta: your sandbox ...". */
+export function plainSummary(summary) {
+    const beta = /^\((beta)\)\s*(.*)$/i.exec(summary);
+    return upper(beta ? 'Beta: ' + beta[2] : summary) + '.';
+}
+/**
+ * A description for the form. A leading "(rename)" / "(save)" names the action it belongs to: the form only asks it for
+ * that action, so the prefix is dropped. Any other prefix "(claude)" becomes "For claude: ...".
+ */
+export function plainDescription(text, actions) {
+    const m = /^\(([^)]+)\)\s*(.*)$/.exec(text);
+    if (!m)
+        return upper(text);
+    const [, tag, rest] = m;
+    return actions.includes(tag.split(/[ /]/)[0]) ? upper(rest) : 'For ' + tag + ': ' + rest;
+}
+/** The action a description names with a leading "(action)", when it is one of `actions`. */
+export function actionOf(text, actions) {
+    const tag = /^\(([^)\s/]+)[^)]*\)/.exec(text)?.[1];
+    return tag && actions.includes(tag) ? tag : undefined;
+}
+/** A folder or file option (a placeholder of dir / file), or one known by name. */
+export function optionPathKind(o) {
+    if (o.value === 'dir' || o.value === 'folder' || o.flag === '--restore')
+        return 'dir';
+    if (o.value === 'file' || o.flag === '--config')
+        return 'file';
+    return undefined;
+}
+/** A folder or file argument; `first` is the answer to the command's first argument (the action). */
+export function argPathKind(a, command, first) {
+    if (['folder', 'dir', 'directory'].includes(a.name))
+        return 'dir';
+    if (['file', 'path'].includes(a.name))
+        return 'file';
+    if (command === 'projects' && a.name === 'value' && ['add', 'remove', 'include', 'exclude'].includes(first))
+        return 'dir';
+    return undefined;
+}

package/dist/cli/menu/command-form.d.ts

@@ -10,9 +10,12 @@ export declare class CommandForm {
     /** Answers by field id (arg:<name>, opt:<flag>, json, extra). */
     private readonly values;
     constructor(app: App, ctx: Context, spec: CommandSpec, preset?: string[]);
+    /** The actions the command's first argument offers (account: save, use, rename ...). */
+    private actions;
     /** Values a choices list names, filled in from config and the running sandbox. */
     private choices;
     private first;
+    private valueOf;
     /** Options the form may ask for at all (advanced ones included). */
     private askable;
     private hiddenCount;
@@ -25,7 +28,26 @@ export declare class CommandForm {
     private item;
     /** Shows the form until you run the command (its argv) or go back (null). */
     run(): Promise<string[] | null>;
+    private isSwitch;
+    /** Sets (or, with no value, clears) a field's answer. */
+    private set;
+    /** The kind of path a field takes (a folder or a file), if it is one. */
+    private pathKind;
+    /** A name that does not exist yet (the new login's name): typed, not picked. */
+    private freeText;
+    /** The values to pick from for a field with a fixed or looked-up set of answers. */
+    private options;
+    /** Changes one field with the input that fits it. Returns a notice to show (when there is something to say). */
     private edit;
+    /** Is the problem with a picked path (true = fine)? Moving or switching the data folder has its own rules. */
+    private pathProblem;
+    /** Several folders or files (--script ...): a list to add to, change and remove from. */
+    private pathList;
+    /** projects remove / include / exclude pick from the known projects (or any folder); add takes a folder. */
+    private projectAction;
+    private projectFolder;
+    /** Nothing to pick from (no saved logins, no running session): say what to do, in the form, without an error. */
+    private nothingToChoose;
     /** `data clean` targets, ticked from a list with their sizes (never "all": that is typed on purpose). */
     private dataTargets;
 }