windows-development-sandbox 1.7.0 → 1.9.0

package/dist/app/kernel/rpc.d.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { type OperationIO } from './io.js';
+/** One call or subscription on the socket (chosen by the browser, unique while it runs). */
+export declare const RpcIdSchema: z.ZodString;
+/** A definition's id (sessions.restart). */
+export declare const DefinitionIdSchema: z.ZodString;
+export declare const CallMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"call">;
+    id: z.ZodString;
+    op: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const AnswerMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    id: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const SubscribeMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"subscribe">;
+    id: z.ZodString;
+    query: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const UnsubscribeMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"unsubscribe">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** Browser -> server. */
+export declare const ClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"call">;
+    id: z.ZodString;
+    op: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    id: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"subscribe">;
+    id: z.ZodString;
+    query: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"unsubscribe">;
+    id: z.ZodString;
+}, z.core.$strict>], "t">;
+export type ClientMessage = z.output<typeof ClientMessageSchema>;
+/** Server -> browser. */
+export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"progress">;
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"log">;
+    id: z.ZodString;
+    text: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        ok: "ok";
+        muted: "muted";
+        warn: "warn";
+        danger: "danger";
+        accent: "accent";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"ask">;
+    id: z.ZodString;
+    question: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"confirm">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        yes: z.ZodOptional<z.ZodString>;
+        danger: z.ZodOptional<z.ZodBoolean>;
+        typed: z.ZodOptional<z.ZodString>;
+        implied: z.ZodOptional<z.ZodBoolean>;
+        noTerminal: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            fix: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"choose">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        choices: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        initial: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        initial: z.ZodOptional<z.ZodString>;
+        allowEmpty: z.ZodOptional<z.ZodBoolean>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"secret">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pathKind: z.ZodEnum<{
+            file: "file";
+            dir: "dir";
+        }>;
+        initial: z.ZodOptional<z.ZodString>;
+        literals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"checklist">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        choices: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        checked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"result">;
+    id: z.ZodString;
+    output: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"error">;
+    id: z.ZodString;
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            cancelled: "cancelled";
+            invalid: "invalid";
+            bug: "bug";
+        }>;
+        message: z.ZodString;
+        fix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"data">;
+    id: z.ZodString;
+    output: z.ZodUnknown;
+}, z.core.$strict>], "t">;
+export type ServerMessage = z.output<typeof ServerMessageSchema>;
+/** Most calls and subscriptions one socket may have open at once. */
+export declare const MAX_OPEN_PER_SOCKET = 32;
+/** What the RPC endpoint needs from the program: the definitions allowed on the web, and a way to run them. */
+export interface RpcHost {
+    /** 'operation' or 'query' when the id is registered and allowed on the web, else undefined. */
+    kind(id: string): 'operation' | 'query' | undefined;
+    /** How often a query is read again while subscribed (undefined: once). */
+    liveMs(id: string): number | undefined;
+    /** Runs an allowed definition (input and output checked). */
+    run(id: string, input: unknown, io: OperationIO): Promise<unknown>;
+}

package/dist/app/kernel/rpc.js

@@ -0,0 +1,47 @@
+// The messages of the web UI's RPC socket (/api/rpc), shared by the server and the browser. The browser calls
+// operations and queries by id, answers questions, and subscribes to live queries; the server streams progress, log
+// lines and questions, then a result or an error. A subscription gets `data` whenever the result changes (an `error`
+// does not end it; `unsubscribe` does). The server checks every message against these schemas.
+import { z } from 'zod';
+import { WireErrorSchema } from './errors.js';
+import { QuestionSchema } from './io.js';
+/** One call or subscription on the socket (chosen by the browser, unique while it runs). */
+export const RpcIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+/** A definition's id (sessions.restart). */
+export const DefinitionIdSchema = z
+    .string()
+    .regex(/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)+$/)
+    .max(80);
+const ToneSchema = z.enum(['ok', 'warn', 'danger', 'muted', 'accent']);
+export const CallMessageSchema = z.strictObject({
+    t: z.literal('call'),
+    id: RpcIdSchema,
+    op: DefinitionIdSchema,
+    input: z.unknown(),
+});
+export const AnswerMessageSchema = z.strictObject({ t: z.literal('answer'), id: RpcIdSchema, value: z.unknown() });
+export const SubscribeMessageSchema = z.strictObject({
+    t: z.literal('subscribe'),
+    id: RpcIdSchema,
+    query: DefinitionIdSchema,
+    input: z.unknown(),
+});
+export const UnsubscribeMessageSchema = z.strictObject({ t: z.literal('unsubscribe'), id: RpcIdSchema });
+/** Browser -> server. */
+export const ClientMessageSchema = z.discriminatedUnion('t', [
+    CallMessageSchema,
+    AnswerMessageSchema,
+    SubscribeMessageSchema,
+    UnsubscribeMessageSchema,
+]);
+/** Server -> browser. */
+export const ServerMessageSchema = z.discriminatedUnion('t', [
+    z.strictObject({ t: z.literal('progress'), id: RpcIdSchema, text: z.string() }),
+    z.strictObject({ t: z.literal('log'), id: RpcIdSchema, text: z.string(), tone: ToneSchema.optional() }),
+    z.strictObject({ t: z.literal('ask'), id: RpcIdSchema, question: QuestionSchema }),
+    z.strictObject({ t: z.literal('result'), id: RpcIdSchema, output: z.unknown() }),
+    z.strictObject({ t: z.literal('error'), id: RpcIdSchema, error: WireErrorSchema }),
+    z.strictObject({ t: z.literal('data'), id: RpcIdSchema, output: z.unknown() }),
+]);
+/** Most calls and subscriptions one socket may have open at once. */
+export const MAX_OPEN_PER_SOCKET = 32;

package/dist/app/kernel/text.d.ts

@@ -0,0 +1,6 @@
+/** "just now", "5 min ago", "3 h ago", "2 d ago". */
+export declare function ago(then: number | string | Date, now?: number): string;
+/** "1 session", "2 sessions". */
+export declare function plural(n: number, noun: string, many?: string): string;
+/** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+export declare function humanize(key: string): string;

package/dist/app/kernel/text.js

@@ -0,0 +1,57 @@
+// Small text helpers every surface formats with the same way: times as "5 min ago", keys as readable labels, counts
+// with the right noun. Pure (the browser bundle imports them too).
+/** "just now", "5 min ago", "3 h ago", "2 d ago". */
+export function ago(then, now = Date.now()) {
+    const secs = Math.max(0, Math.round((now - new Date(then).getTime()) / 1000));
+    if (Number.isNaN(secs))
+        return '';
+    if (secs < 45)
+        return 'just now';
+    if (secs < 3600)
+        return Math.round(secs / 60) + ' min ago';
+    if (secs < 86400)
+        return Math.round(secs / 3600) + ' h ago';
+    return Math.round(secs / 86400) + ' d ago';
+}
+/** "1 session", "2 sessions". */
+export function plural(n, noun, many = noun + 's') {
+    return n + ' ' + (n === 1 ? noun : many);
+}
+/** Words written in capitals wherever they appear in a key. */
+const UPPER = new Set([
+    'mb',
+    'gb',
+    'cpu',
+    'gpu',
+    'jdk',
+    'sdk',
+    'id',
+    'url',
+    'ui',
+    'npm',
+    'msvc',
+    'uv',
+    'api',
+    'ssh',
+    'vm',
+    'io',
+]);
+/** "harness" is the code's word for an agent; screens say agent. */
+const PLAIN = { harness: 'agent', harnesses: 'agents' };
+/** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+export function humanize(key) {
+    const words = key
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => PLAIN[w.toLowerCase()] ?? w);
+    return words
+        .map((w, i) => {
+        const lower = w.toLowerCase();
+        if (UPPER.has(lower))
+            return w.toUpperCase();
+        return i === 0 ? w[0].toUpperCase() + w.slice(1) : lower;
+    })
+        .join(' ');
+}

package/dist/app/kernel/view.d.ts

@@ -0,0 +1,146 @@
+import type { z } from 'zod';
+import type { OperationDef } from './define.js';
+import type { Field } from './fields.js';
+/** The one palette: the TUI theme and the web colours both map these. */
+export type Tone = 'ok' | 'warn' | 'danger' | 'muted' | 'accent';
+/** A short label the web shows as a pill next to an item ("running"); the menu and the CLI show the hint. */
+export interface Badge {
+    readonly text: string;
+    readonly tone?: Tone;
+}
+/** Where a link goes. Each surface maps a target to what it can do (attach / terminal page / a command to type). */
+export type Target = 
+/** A running session's terminal: the menu attaches, the web opens its terminal page. */
+{
+    readonly kind: 'terminal';
+    readonly session: string;
+}
+/** Start an agent: the menu runs `launch`, the web opens its new-session dialog. */
+ | {
+    readonly kind: 'start-agent';
+    readonly agent: string;
+}
+/** A command line of an area that is not a feature yet: the menu runs it, the web does not offer it. */
+ | {
+    readonly kind: 'command';
+    readonly argv: readonly string[];
+}
+/** Another view. */
+ | {
+    readonly kind: 'view';
+    readonly view: string;
+};
+interface ActionBase {
+    /** The words on a button or a row ("Stop the sandbox…"). */
+    readonly label: string;
+    /** One word for a key bar or an Enter hint ("stop"). */
+    readonly verb?: string;
+    /** The menu key that does it (one letter). */
+    readonly key?: string;
+    /** How long it survives in a narrow key bar: 0 never goes, bigger goes earlier (menu). */
+    readonly importance?: number;
+    readonly description?: string;
+}
+/** Runs an operation with this input (plus the answers to `fields`, asked first). */
+export interface OperationAction extends ActionBase {
+    readonly kind: 'operation';
+    readonly op: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    /** Asks for a confirmation before running (from the operation's `danger`). */
+    readonly danger?: boolean;
+    /** Values to ask for before running; each answer goes into the input under the field's name. */
+    readonly fields?: readonly Field[];
+    /** What `fields` start as (the current value of a setting), by field name. */
+    readonly initial?: Readonly<Record<string, unknown>>;
+}
+export interface LinkAction extends ActionBase {
+    readonly kind: 'link';
+    readonly target: Target;
+}
+export type Action = OperationAction | LinkAction;
+/** One label: value line (a status fact, a setting). */
+export interface Fact {
+    readonly id: string;
+    readonly label: string;
+    readonly value: string;
+    readonly tone?: Tone;
+    readonly description?: string;
+    readonly details?: readonly string[];
+}
+/** A column of a section shown as a table (CLI table, web table); items fill it through `cells`. */
+export interface Column {
+    readonly key: string;
+    readonly label: string;
+}
+/** One entry of a list. */
+export interface Item {
+    readonly id: string;
+    readonly label: string;
+    /** The right-hand text (a state, a value). */
+    readonly hint?: string;
+    readonly tone?: Tone;
+    readonly badges?: readonly Badge[];
+    readonly description?: string;
+    /** Extra lines (the menu's details pane, the CLI's indented lines, the web's card body). */
+    readonly details?: readonly string[];
+    /** A heading inside the section ("This folder's project"). */
+    readonly group?: string;
+    /** Marked as "the one this is about" (the project of this folder): `*` in the CLI. */
+    readonly marked?: boolean;
+    /** The values for the section's columns. */
+    readonly cells?: Readonly<Record<string, string>>;
+    /** What Enter / a click does. */
+    readonly primary?: Action;
+    readonly actions?: readonly Action[];
+    /** Why it cannot be used now. */
+    readonly disabled?: string;
+    /** More words a search finds it by. */
+    readonly keywords?: string;
+}
+/** A line under a section; `only` limits it to one surface (a CLI flag hint). */
+export interface Note {
+    readonly text: string;
+    readonly tone?: Tone;
+    readonly only?: 'cli' | 'menu' | 'web';
+}
+export interface Section {
+    readonly id: string;
+    readonly title?: string;
+    /** A short line next to the title ("2 folders guarded"). */
+    readonly summary?: string;
+    readonly description?: string;
+    readonly facts?: readonly Fact[];
+    readonly items?: readonly Item[];
+    /** Show the items as a table with these columns where a surface can (CLI, web). */
+    readonly columns?: readonly Column[];
+    /** Where `columns` is used: everywhere (default), or only on the command line (the web lists the items in full). */
+    readonly columnsOn?: 'all' | 'cli';
+    readonly actions?: readonly Action[];
+    readonly notes?: readonly Note[];
+}
+/** What a page shows when it has nothing: the text and the next step (the CLI prints `cliText`, naming a command). */
+export interface Empty {
+    readonly title?: string;
+    readonly text: string;
+    readonly action?: Action;
+    readonly cliText?: string;
+}
+export interface Page {
+    readonly title: string;
+    /** One line above everything (whose sandbox this is). */
+    readonly notice?: Note;
+    readonly sections: readonly Section[];
+    /** Actions for the whole page (refresh-like, start). */
+    readonly actions?: readonly Action[];
+    /** Shown instead of the sections when they have no facts and no items. */
+    readonly empty?: Empty;
+}
+/** An action that runs `def` with `input` (typed from its input schema; `fields` may ask for the rest). */
+export declare function action<I extends z.ZodType, O extends z.ZodType>(def: OperationDef<I, O>, input: Partial<z.input<I>>, extra?: Partial<Omit<OperationAction, 'kind' | 'op' | 'input'>>): OperationAction;
+/** An action that goes somewhere. */
+export declare function link(target: Target, label: string, extra?: Partial<Omit<LinkAction, 'kind' | 'target'>>): LinkAction;
+/** Does the page show anything besides its empty state? */
+export declare function pageHasContent(page: Page): boolean;
+/** Every action a page offers, wherever it sits (for parity checks and key bars). */
+export declare function pageActions(page: Page): Action[];
+export {};

package/dist/app/kernel/view.js

@@ -0,0 +1,28 @@
+/** An action that runs `def` with `input` (typed from its input schema; `fields` may ask for the rest). */
+export function action(def, input, extra = {}) {
+    return {
+        kind: 'operation',
+        op: def.id,
+        input: input,
+        label: def.title,
+        ...(def.danger ? { danger: true } : {}),
+        ...extra,
+    };
+}
+/** An action that goes somewhere. */
+export function link(target, label, extra = {}) {
+    return { kind: 'link', target, label, ...extra };
+}
+/** Does the page show anything besides its empty state? */
+export function pageHasContent(page) {
+    return page.sections.some((s) => (s.facts?.length ?? 0) > 0 || (s.items?.length ?? 0) > 0);
+}
+/** Every action a page offers, wherever it sits (for parity checks and key bars). */
+export function pageActions(page) {
+    const fromItem = (i) => [...(i.primary ? [i.primary] : []), ...(i.actions ?? [])];
+    return [
+        ...(page.actions ?? []),
+        ...(page.empty?.action ? [page.empty.action] : []),
+        ...page.sections.flatMap((s) => [...(s.actions ?? []), ...(s.items ?? []).flatMap(fromItem)]),
+    ];
+}

package/dist/app/registry.d.ts

@@ -0,0 +1,10 @@
+import type { AppContext } from './context.js';
+import { type AnyDefinition, type Implementation, type OperationIO, type OutputOf, type QueryDef, type RpcHost } from './kernel/index.js';
+export declare const IMPLEMENTATIONS: readonly Implementation<AnyDefinition, AppContext>[];
+export declare function implementationOf(id: string): Implementation<AnyDefinition, AppContext> | undefined;
+/** Runs a definition by id: input checked before, output checked after. */
+export declare function runDefinition(id: string, ctx: AppContext, input: unknown, io: OperationIO): Promise<unknown>;
+/** Reads a query in-process (the menu): typed output, and no questions. */
+export declare function readQuery<D extends QueryDef>(def: D, ctx: AppContext, input?: unknown): Promise<OutputOf<D>>;
+/** What the web server may run: the registered definitions whose surfaces include the web. */
+export declare function createRpcHost(ctx: AppContext): RpcHost;

package/dist/app/registry.js

@@ -0,0 +1,50 @@
+import { invoke, NO_QUESTIONS, onSurface, } from './kernel/index.js';
+import { hideWindowRun, sandboxStatusRun, showWindowRun, stopSandboxRun } from './features/sandbox/index.js';
+import { listSessionsRun, restartSessionsRun } from './features/sessions/index.js';
+import { getSettingRun, listSettingsRun, resetSettingRun, setSettingRun } from './features/settings/index.js';
+export const IMPLEMENTATIONS = [
+    sandboxStatusRun,
+    showWindowRun,
+    hideWindowRun,
+    stopSandboxRun,
+    listSessionsRun,
+    restartSessionsRun,
+    listSettingsRun,
+    getSettingRun,
+    setSettingRun,
+    resetSettingRun,
+];
+export function implementationOf(id) {
+    return IMPLEMENTATIONS.find((i) => i.def.id === id);
+}
+/** Runs a definition by id: input checked before, output checked after. */
+export function runDefinition(id, ctx, input, io) {
+    const impl = implementationOf(id);
+    if (!impl)
+        throw new Error('No implementation for ' + id);
+    return invoke(impl, ctx, input, io);
+}
+/** Reads a query in-process (the menu): typed output, and no questions. */
+export async function readQuery(def, ctx, input = {}) {
+    return (await runDefinition(def.id, ctx, input, NO_QUESTIONS));
+}
+/** What the web server may run: the registered definitions whose surfaces include the web. */
+export function createRpcHost(ctx) {
+    const allowed = (id) => {
+        const impl = implementationOf(id);
+        return impl && onSurface(impl.def, 'web') ? impl : undefined;
+    };
+    return {
+        kind: (id) => allowed(id)?.def.kind,
+        liveMs: (id) => {
+            const def = allowed(id)?.def;
+            return def?.kind === 'query' ? def.live?.everyMs : undefined;
+        },
+        run: (id, input, io) => {
+            const impl = allowed(id);
+            if (!impl)
+                throw new Error('Not allowed on the web: ' + id);
+            return invoke(impl, ctx, input, io);
+        },
+    };
+}

package/dist/cli/args.d.ts

@@ -3,6 +3,8 @@ export interface CliOptions {
     command: string;
     positionals: string[];
     passthrough: string[];
+    /** The options as commander parsed them, by attribute name (operation commands build their input from these). */
+    raw: Readonly<Record<string, unknown>>;
     config?: string;
     workspace?: string;
     harness?: string;
@@ -25,12 +27,15 @@ export interface CliOptions {
     accountTo?: string;
     noRestart: boolean;
     follow: boolean;
+    crash: boolean;
     json: boolean;
     yes: boolean;
     /** sessions --wide: also the folder column. */
     wide: boolean;
     /** storage move: keep the old folder (copy instead of rename). */
     keepOld: boolean;
+    /** config export: keep folders and files of this PC in the file. */
+    withPaths: boolean;
     timeout: number;
     days: number;
     /** restart: every session, not only this folder's project's. */

package/dist/cli/args.js

@@ -186,6 +186,7 @@ export function parseCli(argv, wrapper = false) {
         command: name === 'start' ? 'launch' : name,
         positionals: forAgent || name === 'exec' ? [] : operands,
         passthrough: forAgent || name === 'exec' ? operands : [],
+        raw: o,
         config: o.config,
         workspace: o.workspace,
         harness: o.harness ?? (name !== 'account' && typeof o.agent === 'string' ? o.agent : undefined),
@@ -209,10 +210,12 @@ export function parseCli(argv, wrapper = false) {
         accountTo: name === 'account' && typeof o.to === 'string' ? o.to : undefined,
         noRestart: o.restart === false,
         follow: Boolean(o.follow),
+        crash: Boolean(o.crash),
         json: Boolean(o.json),
         yes: Boolean(o.yes),
         wide: Boolean(o.wide),
         keepOld: Boolean(o.keepOld),
+        withPaths: Boolean(o.withPaths),
         all: Boolean(o.all),
         sessions: (o.session ?? []).map((s) => parseSessionWant(s)),
         timeout: o.timeout ?? 600,
@@ -243,6 +246,7 @@ function defaults() {
         command: '',
         positionals: [],
         passthrough: [],
+        raw: {},
         scripts: [],
         databases: [],
         terminal: false,
@@ -254,6 +258,7 @@ function defaults() {
         fromHost: false,
         noRestart: false,
         follow: false,
+        crash: false,
         dryRun: false,
         fix: false,
         auto: false,
@@ -264,6 +269,7 @@ function defaults() {
         yes: false,
         wide: false,
         keepOld: false,
+        withPaths: false,
         all: false,
         sessions: [],
         timeout: 600,

package/dist/cli/commands/engine.d.ts

@@ -0,0 +1,2 @@
+import type { Context } from './context.js';
+export declare function engine(ctx: Context): Promise<number>;

package/dist/cli/commands/engine.js

@@ -0,0 +1,60 @@
+// `sandbox engine`: the engine in use and, for each engine, what it can do and whether this PC can run it.
+import { fail } from '../../core/util/index.js';
+import { engineReports } from '../../host/engines/index.js';
+import { c, printJson, table } from '../output/index.js';
+const CAPABILITY_NAMES = {
+    desktop: 'desktop window',
+    gpu: 'GPU',
+    clipboard: 'clipboard',
+    audio: 'audio',
+    video: 'camera',
+    printers: 'printers',
+    liveFolderAdd: 'add folders while running',
+    attachedDisks: 'attached disks',
+    multipleInstances: 'several at once',
+    hvsocket: 'Hyper-V sockets',
+};
+/** sandbox engine check <engine>: the reasons and the exact commands, in plain words. Nothing is run or changed. */
+async function checkEngine(ctx, name) {
+    const report = (await engineReports(ctx.loaded.config)).find((r) => r.id === name);
+    if (!report)
+        return fail('Unknown engine: ' + name, 'Use windows-sandbox or hcs.');
+    if (printJson(ctx, report))
+        return report.check.available ? 0 : 1;
+    if (report.check.available) {
+        console.log(c.green(name + ' can be used on this PC.'));
+        if (name === 'hcs')
+            console.log('HCS is in alpha: starting it is not enabled yet (docs/design/engines.md).');
+        return 0;
+    }
+    console.log(c.yellow(name + ' cannot be used on this PC yet:'));
+    report.check.reasons.forEach((reason, i) => {
+        console.log('\n  ' + (i + 1) + '. ' + reason);
+        console.log('     To fix: ' + (report.check.fixes[i] ?? 'see docs/design/engines.md'));
+    });
+    console.log('\nNothing was changed. These commands change Windows, so they are yours to run (or not).');
+    return 1;
+}
+export async function engine(ctx) {
+    const [action = 'show', name = 'hcs'] = ctx.options.positionals;
+    if (action === 'check')
+        return checkEngine(ctx, name);
+    const reports = await engineReports(ctx.loaded.config);
+    const using = reports.find((r) => r.inUse);
+    if (printJson(ctx, { engine: using?.id, engines: reports }))
+        return 0;
+    console.log('Engine in use: ' + (using?.id ?? ctx.loaded.config.sandbox.engine) + '  (setting: sandbox.engine)');
+    for (const report of reports) {
+        console.log('\n' + report.id + (report.inUse ? '  (in use)' : ''));
+        console.log('  ' + (report.check.available ? c.green('can be used on this PC') : c.yellow('cannot be used yet')));
+        for (const reason of report.check.reasons)
+            console.log('  ' + reason);
+        for (const fix of report.check.fixes)
+            console.log('  Fix: ' + fix);
+        table(Object.entries(CAPABILITY_NAMES).map(([key, name]) => [
+            '  ' + name,
+            report.capabilities[key] ? 'yes' : 'no',
+        ]));
+    }
+    return 0;
+}

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

@@ -4,7 +4,7 @@ export { setup } from './setup/index.js';
 export { data } from './data/index.js';
 export { storage, storageBeforeCommand } from './storage/index.js';
 export { repairCommand } from './repair/index.js';
-export { attach, db, exec, hide, show, restart, stop, sessions, status } from './sessions/index.js';
+export { attach, db, exec } from './sessions/index.js';
 export { account } from './accounts.js';
 export { resume } from './resume.js';
 export { projects } from './projects/index.js';

package/dist/cli/commands/index.js

@@ -4,7 +4,7 @@ export { setup } from './setup/index.js';
 export { data } from './data/index.js';
 export { storage, storageBeforeCommand } from './storage/index.js';
 export { repairCommand } from './repair/index.js';
-export { attach, db, exec, hide, show, restart, stop, sessions, status } from './sessions/index.js';
+export { attach, db, exec } from './sessions/index.js';
 export { account } from './accounts.js';
 export { resume } from './resume.js';
 export { projects } from './projects/index.js';