windows-development-sandbox 1.10.0 → 1.11.4

package/dist/app/features/vpn/vpn.def.d.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { type Page } from '../../kernel/index.js';
+/** The warnings every VPN user must see (alpha): on every surface. */
+export declare const VPN_WARNINGS: readonly string[];
+/** The steps to get the NordVPN service credentials, in the words of Nord Account (shown before asking). */
+export declare const NORD_STEPS: readonly string[];
+export declare const VpnStatusSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    provider: z.ZodEnum<{
+        nordvpn: "nordvpn";
+        "openvpn-file": "openvpn-file";
+        "wireguard-file": "wireguard-file";
+    }>;
+    protocol: z.ZodEnum<{
+        udp: "udp";
+        tcp: "tcp";
+    }>;
+    country: z.ZodString;
+    killSwitch: z.ZodBoolean;
+    login: z.ZodEnum<{
+        none: "none";
+        saved: "saved";
+        unreadable: "unreadable";
+    }>;
+    loginSavedAt: z.ZodNullable<z.ZodString>;
+    running: z.ZodNullable<z.ZodObject<{
+        level: z.ZodEnum<{
+            ok: "ok";
+            warn: "warn";
+            bad: "bad";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type VpnStatus = z.output<typeof VpnStatusSchema>;
+export declare const vpnStatus: import("../../kernel/define.js").QueryDef<z.ZodObject<{
+    tunnel: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    enabled: z.ZodBoolean;
+    provider: z.ZodEnum<{
+        nordvpn: "nordvpn";
+        "openvpn-file": "openvpn-file";
+        "wireguard-file": "wireguard-file";
+    }>;
+    protocol: z.ZodEnum<{
+        udp: "udp";
+        tcp: "tcp";
+    }>;
+    country: z.ZodString;
+    killSwitch: z.ZodBoolean;
+    login: z.ZodEnum<{
+        none: "none";
+        saved: "saved";
+        unreadable: "unreadable";
+    }>;
+    loginSavedAt: z.ZodNullable<z.ZodString>;
+    running: z.ZodNullable<z.ZodObject<{
+        level: z.ZodEnum<{
+            ok: "ok";
+            warn: "warn";
+            bad: "bad";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, "vpn.status">;
+export declare const vpnLogin: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strict>, z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>, "vpn.login">;
+export declare const vpnLogout: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strict>, z.ZodObject<{
+    deleted: z.ZodBoolean;
+    message: z.ZodString;
+}, z.core.$strip>, "vpn.logout">;
+/** The Settings row of the menu (label, hint, description), from the status. Pure. */
+export declare function vpnLoginRowOf(s: VpnStatus): {
+    label: string;
+    hint: string;
+    description: string;
+};
+/** The status page: the facts, the next step (command line only), the warnings and the login actions. */
+export declare function vpnPage(s: VpnStatus): Page;
+export declare const vpnView: import("../../kernel/define.js").ViewDef<{
+    status: import("../../kernel/define.js").QueryDef<z.ZodObject<{
+        tunnel: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        enabled: z.ZodBoolean;
+        provider: z.ZodEnum<{
+            nordvpn: "nordvpn";
+            "openvpn-file": "openvpn-file";
+            "wireguard-file": "wireguard-file";
+        }>;
+        protocol: z.ZodEnum<{
+            udp: "udp";
+            tcp: "tcp";
+        }>;
+        country: z.ZodString;
+        killSwitch: z.ZodBoolean;
+        login: z.ZodEnum<{
+            none: "none";
+            saved: "saved";
+            unreadable: "unreadable";
+        }>;
+        loginSavedAt: z.ZodNullable<z.ZodString>;
+        running: z.ZodNullable<z.ZodObject<{
+            level: z.ZodEnum<{
+                ok: "ok";
+                warn: "warn";
+                bad: "bad";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, "vpn.status">;
+}, Record<string, never>, "vpn">;

package/dist/app/features/vpn/vpn.def.js

@@ -0,0 +1,174 @@
+// The VPN: its settings, whether a login is saved (never its values), the running tunnel, and saving or deleting the
+// login. Pure: schemas, labels and the view; vpn.run.ts does the work. The login itself is never an input or an output.
+import { z } from 'zod';
+import { action, defineOperation, defineQuery, defineView, } from '../../kernel/index.js';
+import { setSetting } from '../settings/settings.def.js';
+const ProviderSchema = z
+    .enum(['nordvpn', 'openvpn-file', 'wireguard-file'])
+    .describe('Which VPN (setting vpn.provider)');
+const LoginStateSchema = z
+    .enum(['none', 'saved', 'unreadable'])
+    .describe('Whether a login is saved and can be opened by you');
+/** The warnings every VPN user must see (alpha): on every surface. */
+export const VPN_WARNINGS = [
+    'The VPN is an alpha: a tunnel carrying traffic is not confirmed yet (docs/vpn.md lists what still needs checking).',
+    'The agent in the sandbox can read the VPN login (a service login you can revoke) and can turn the tunnel off, because it is the administrator there.',
+    'Free VPNs see all your traffic: use one you trust.',
+];
+/** The steps to get the NordVPN service credentials, in the words of Nord Account (shown before asking). */
+export const NORD_STEPS = [
+    'Sign in at https://my.nordaccount.com with your usual NordVPN e-mail and password.',
+    'Open NordVPN, then "Set up NordVPN manually" (under Advanced settings).',
+    'Verify your e-mail if it asks, then copy the "Service credentials": a user name and a password.',
+    'These are NOT your account password. You can revoke them in the same place whenever you like.',
+];
+export const VpnStatusSchema = z.object({
+    enabled: z.boolean().describe('The VPN is on (setting vpn.enabled)'),
+    provider: ProviderSchema,
+    protocol: z.enum(['udp', 'tcp']).describe('udp or tcp (setting vpn.protocol)'),
+    country: z.string().describe('The NordVPN country; empty = the best server anywhere'),
+    killSwitch: z.boolean().describe('No internet when the tunnel fails (setting vpn.killSwitch)'),
+    login: LoginStateSchema,
+    loginSavedAt: z.string().nullable().describe('When the login was saved (the date and time, never the login)'),
+    running: z
+        .object({
+        level: z.enum(['ok', 'warn', 'bad']).describe('How the tunnel is doing'),
+        text: z.string().describe('What the sandbox reported'),
+    })
+        .nullable()
+        .describe("The running sandbox's tunnel, when one runs with the VPN on"),
+});
+export const vpnStatus = defineQuery({
+    id: 'vpn.status',
+    title: 'VPN',
+    summary: 'the VPN settings, whether a login is saved, and the running tunnel',
+    input: z.object({
+        tunnel: z
+            .boolean()
+            .default(true)
+            .describe('also ask the running sandbox how its tunnel is doing (one request to api.ipify.org)'),
+    }),
+    output: VpnStatusSchema,
+    cli: { name: 'vpn', action: 'status', json: true },
+});
+export const vpnLogin = defineOperation({
+    id: 'vpn.login',
+    title: 'Save the VPN login…',
+    summary: 'save the VPN login (typed hidden, kept encrypted, never printed)',
+    input: z.object({}).strict(),
+    output: z.object({ message: z.string().describe('What happened') }),
+    text: (o) => o.message,
+    cli: { name: 'vpn', action: 'login' },
+});
+export const vpnLogout = defineOperation({
+    id: 'vpn.logout',
+    title: 'Delete the VPN login',
+    summary: 'delete the saved VPN login',
+    input: z.object({}).strict(),
+    output: z.object({
+        deleted: z.boolean().describe('A login was saved and is gone'),
+        message: z.string().describe('What happened'),
+    }),
+    danger: true,
+    text: (o) => o.message,
+    cli: { name: 'vpn', action: 'logout' },
+});
+const PROVIDER_TEXT = {
+    nordvpn: 'NordVPN',
+    'wireguard-file': 'your own WireGuard .conf',
+    'openvpn-file': 'your own .ovpn file',
+};
+const LOGIN_TEXT = {
+    none: 'not saved',
+    saved: 'saved (encrypted)',
+    unreadable: 'cannot be read',
+};
+const LOGIN_TONE = {
+    none: 'warn',
+    saved: 'ok',
+    unreadable: 'danger',
+};
+const RUNNING_TONE = {
+    ok: 'ok',
+    warn: 'warn',
+    bad: 'danger',
+};
+/** The Settings row of the menu (label, hint, description), from the status. Pure. */
+export function vpnLoginRowOf(s) {
+    if (s.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.',
+        };
+    return {
+        label: s.provider === 'nordvpn' ? 'Set NordVPN login…' : 'Set VPN login…',
+        hint: s.login === 'saved' ? 'saved' : s.login === '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(' '),
+    };
+}
+/** The status page: the facts, the next step (command line only), the warnings and the login actions. */
+export function vpnPage(s) {
+    const wireguard = s.provider === 'wireguard-file';
+    const savedDate = s.loginSavedAt ? '  ' + s.loginSavedAt.slice(0, 10) : '';
+    const facts = [
+        s.enabled
+            ? { id: 'vpn', label: 'VPN', value: 'on', tone: 'ok' }
+            : { id: 'vpn', label: 'VPN', value: 'off (applies from the next start)', tone: 'muted' },
+        { id: 'provider', label: 'Provider', value: PROVIDER_TEXT[s.provider] },
+        { id: 'protocol', label: 'Protocol', value: s.protocol },
+        { id: 'country', label: 'Country', value: s.country || 'best available' },
+        s.killSwitch
+            ? { id: 'killSwitch', label: 'Kill switch', value: 'on (no internet if the tunnel fails)' }
+            : { id: 'killSwitch', label: 'Kill switch', value: 'off', tone: 'warn' },
+        wireguard
+            ? { id: 'login', label: 'Login', value: 'not needed (the keys are in your config)', tone: 'muted' }
+            : { id: 'login', label: 'Login', value: LOGIN_TEXT[s.login] + savedDate, tone: LOGIN_TONE[s.login] },
+        ...(s.running
+            ? [
+                {
+                    id: 'running',
+                    label: 'Running now',
+                    value: s.running.text,
+                    tone: RUNNING_TONE[s.running.level],
+                },
+            ]
+            : []),
+    ];
+    const notes = [
+        ...(!wireguard && s.login === 'none'
+            ? [{ text: 'Next: sandbox vpn login', tone: 'muted', only: 'cli' }]
+            : []),
+        ...(s.login === 'unreadable'
+            ? [
+                {
+                    text: 'Only the Windows user that saved it can read it. Save it again: sandbox vpn login',
+                    tone: 'muted',
+                },
+            ]
+            : []),
+        ...VPN_WARNINGS.map((text) => ({ text, tone: 'warn' })),
+    ];
+    // Turning it on or off is the vpn.enabled setting (it applies from the next start).
+    const toggle = action(setSetting, { scope: 'user', key: 'vpn.enabled', value: !s.enabled }, { label: s.enabled ? 'Turn the VPN off' : 'Turn the VPN on', verb: s.enabled ? 'turn off' : 'turn on', key: 'o' });
+    const actions = [
+        toggle,
+        ...(wireguard
+            ? []
+            : [
+                action(vpnLogin, {}, { key: 'v', verb: 'save login' }),
+                ...(s.login !== 'none' ? [action(vpnLogout, {}, { key: 'x', verb: 'delete login' })] : []),
+            ]),
+    ];
+    const section = { id: 'vpn', facts, notes, actions };
+    return { title: 'VPN', sections: [section] };
+}
+export const vpnView = defineView({
+    id: 'vpn',
+    title: 'VPN',
+    summary: "The sandbox's VPN: whether it is on, the saved login, and the tunnel.",
+    queries: { status: vpnStatus },
+    operations: [vpnLogin, vpnLogout, setSetting],
+    build: ({ status }) => vpnPage(status),
+});

package/dist/app/features/vpn/vpn.run.d.ts

@@ -0,0 +1,37 @@
+export declare const vpnStatusRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{
+    tunnel: import("zod").ZodDefault<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    enabled: import("zod").ZodBoolean;
+    provider: import("zod").ZodEnum<{
+        nordvpn: "nordvpn";
+        "openvpn-file": "openvpn-file";
+        "wireguard-file": "wireguard-file";
+    }>;
+    protocol: import("zod").ZodEnum<{
+        udp: "udp";
+        tcp: "tcp";
+    }>;
+    country: import("zod").ZodString;
+    killSwitch: import("zod").ZodBoolean;
+    login: import("zod").ZodEnum<{
+        none: "none";
+        saved: "saved";
+        unreadable: "unreadable";
+    }>;
+    loginSavedAt: import("zod").ZodNullable<import("zod").ZodString>;
+    running: import("zod").ZodNullable<import("zod").ZodObject<{
+        level: import("zod").ZodEnum<{
+            ok: "ok";
+            warn: "warn";
+            bad: "bad";
+        }>;
+        text: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, "vpn.status">, import("../../../cli/commands/context.js").Context>;
+export declare const vpnLoginRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "vpn.login">, import("../../../cli/commands/context.js").Context>;
+export declare const vpnLogoutRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    deleted: import("zod").ZodBoolean;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "vpn.logout">, import("../../../cli/commands/context.js").Context>;

package/dist/app/features/vpn/vpn.run.js

@@ -0,0 +1,54 @@
+// The VPN feature's work: its status (no request to the network when asked not to), saving the login through io.secret
+// (the answers are kept only for the save, never returned, logged or shown), and deleting it after a confirmation.
+import { requireOnPc } from '../../../cli/commands/context.js';
+import { VpnService } from '../../../cli/services/vpn-service.js';
+import { implement } from '../../context.js';
+import { cancelled } from '../../kernel/index.js';
+import { NORD_STEPS, VPN_WARNINGS, vpnLogin, vpnLogout, vpnStatus } from './vpn.def.js';
+export const vpnStatusRun = implement(vpnStatus, async (ctx, input) => new VpnService(ctx).report({ tunnel: input.tunnel }));
+export const vpnLoginRun = implement(vpnLogin, async (ctx, _input, io) => {
+    requireOnPc('vpn login');
+    const service = new VpnService(ctx);
+    if (service.provider === 'wireguard-file')
+        return { message: 'A WireGuard config needs no login: the keys are in the file vpn.configFile points to.' };
+    const nord = service.provider === 'nordvpn';
+    io.log(nord
+        ? 'NordVPN needs its service credentials, not your usual login. To get them:'
+        : 'Type the user name and password your VPN profile asks for.');
+    if (nord)
+        NORD_STEPS.forEach((s, i) => io.log('  ' + (i + 1) + '. ' + s));
+    io.log('What you type is not shown. It is kept encrypted for your Windows user and never printed.', 'muted');
+    // The validators return fixed texts only: what was typed is never echoed back.
+    const username = await io.secret({
+        title: nord ? 'Service user name' : 'User name',
+        validate: (v) => (v.trim() ? true : 'Type the user name.'),
+    });
+    if (username === undefined)
+        cancelled();
+    const password = await io.secret({
+        title: nord ? 'Service password' : 'Password',
+        validate: (v) => (v ? true : 'Type the password.'),
+    });
+    if (password === undefined)
+        cancelled();
+    service.save({ username, password });
+    VPN_WARNINGS.forEach((w) => io.log(w, 'muted'));
+    return { message: 'Saved. Turn the VPN on with: sandbox config set vpn.enabled true' };
+});
+export const vpnLogoutRun = implement(vpnLogout, async (ctx, _input, io) => {
+    requireOnPc('vpn logout');
+    const service = new VpnService(ctx);
+    if (service.loginState() === 'none')
+        return { deleted: false, message: 'No VPN login was saved.' };
+    // The CLI never asked before (a typed logout is the answer); the menu and the web still ask.
+    const yes = await io.confirm({
+        title: 'Delete the saved VPN login?',
+        yes: 'Delete',
+        danger: true,
+        implied: true,
+    });
+    if (!yes)
+        cancelled();
+    service.remove();
+    return { deleted: true, message: 'The saved VPN login is deleted.' };
+});

package/dist/app/features/web/index.d.ts

@@ -0,0 +1,2 @@
+export * from './web.def.js';
+export * from './web.run.js';

package/dist/app/features/web/index.js

@@ -0,0 +1,3 @@
+// The web feature: the web UI server on this PC (start, open, stop, whether it runs). CLI and menu only.
+export * from './web.def.js';
+export * from './web.run.js';

package/dist/app/features/web/web.def.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type Page } from '../../kernel/index.js';
+export declare const WebStatusSchema: z.ZodObject<{
+    running: z.ZodBoolean;
+    port: z.ZodNullable<z.ZodNumber>;
+    address: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WebStatus = z.output<typeof WebStatusSchema>;
+export declare const webStatus: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    running: z.ZodBoolean;
+    port: z.ZodNullable<z.ZodNumber>;
+    address: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, "web.status">;
+export declare const startWeb: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    port: z.ZodNumber;
+    message: z.ZodString;
+}, z.core.$strip>, "web.start">;
+export declare const openWeb: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>, "web.open">;
+export declare const stopWeb: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    stopped: z.ZodBoolean;
+    message: z.ZodString;
+}, z.core.$strip>, "web.stop">;
+/** The web UI's Maintenance category (the menu): running or not, its address, and the three actions. */
+export declare function webPage(o: WebStatus): Page;
+export declare const webView: import("../../kernel/define.js").ViewDef<{
+    status: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+        running: z.ZodBoolean;
+        port: z.ZodNullable<z.ZodNumber>;
+        address: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, "web.status">;
+}, Record<string, never>, "web">;

package/dist/app/features/web/web.def.js

@@ -0,0 +1,90 @@
+// The web UI server on this PC: whether it runs, and start, open and stop it. Pure: schemas, labels and the view;
+// web.run.ts does the work. The web UI cannot control its own server (the page is the web UI), so every definition is
+// CLI and menu only. Nothing here carries the login token: the address the page shows has none.
+import { z } from 'zod';
+import { action, defineOperation, defineQuery, defineView } from '../../kernel/index.js';
+const NOT_ON_WEB = { except: { web: 'the page is the web UI' } };
+export const WebStatusSchema = z.object({
+    running: z.boolean().describe('The web UI server answers'),
+    port: z.number().nullable().describe('Its port on 127.0.0.1, when it runs'),
+    address: z.string().nullable().describe('Its address (without the login token), when it runs'),
+});
+const MessageSchema = z.object({ message: z.string().describe('What happened') });
+export const webStatus = defineQuery({
+    id: 'web.status',
+    title: 'Web UI',
+    summary: 'whether the web UI server runs, and its address',
+    input: z.object({}),
+    output: WebStatusSchema,
+    surfaces: NOT_ON_WEB,
+    text: (o) => o.running && o.port
+        ? 'The web UI is running at http://127.0.0.1:' + o.port + '/ (sandbox web open signs you in).'
+        : 'The web UI is not running (sandbox web start).',
+    cli: { name: 'web', action: 'status', json: true },
+});
+export const startWeb = defineOperation({
+    id: 'web.start',
+    title: 'Start the web UI',
+    summary: 'start the web UI server in the background (this PC only)',
+    input: z.object({}),
+    output: z.object({ port: z.number().describe('Its port'), message: z.string().describe('What happened') }),
+    surfaces: NOT_ON_WEB,
+    text: (o) => o.message,
+    cli: { name: 'web', action: 'start' },
+});
+export const openWeb = defineOperation({
+    id: 'web.open',
+    title: 'Open the web UI',
+    summary: 'start the web UI if needed and open it in your browser, signed in',
+    input: z.object({}),
+    output: MessageSchema,
+    surfaces: NOT_ON_WEB,
+    text: (o) => o.message,
+    cli: { name: 'web', action: 'open' },
+});
+export const stopWeb = defineOperation({
+    id: 'web.stop',
+    title: 'Stop the web UI',
+    summary: 'stop the web UI server',
+    input: z.object({}),
+    output: z.object({
+        stopped: z.boolean().describe('It was running and stopped'),
+        message: z.string().describe('What happened'),
+    }),
+    surfaces: NOT_ON_WEB,
+    text: (o) => o.message,
+    cli: { name: 'web', action: 'stop' },
+});
+/** The web UI's Maintenance category (the menu): running or not, its address, and the three actions. */
+export function webPage(o) {
+    const open = action(openWeb, {}, { key: 'o', verb: 'open' });
+    const start = action(startWeb, {}, { key: 's', verb: 'start' });
+    const stop = action(stopWeb, {}, { key: 'x', verb: 'stop' });
+    return {
+        title: 'Web UI',
+        sections: [
+            {
+                id: 'web',
+                facts: [
+                    {
+                        id: 'running',
+                        label: 'Running',
+                        value: o.running ? 'yes' : 'no',
+                        tone: o.running ? 'ok' : 'muted',
+                    },
+                    ...(o.address ? [{ id: 'address', label: 'Address', value: o.address + '  (this PC only)' }] : []),
+                ],
+                actions: o.running ? [open, stop] : [start, open],
+                notes: [{ text: 'Loopback only, behind a token. Open signs you in.', tone: 'muted' }],
+            },
+        ],
+    };
+}
+export const webView = defineView({
+    id: 'web',
+    title: 'Web UI',
+    summary: 'The web UI server on this PC: start, open, stop.',
+    queries: { status: webStatus },
+    operations: [startWeb, openWeb, stopWeb],
+    build: ({ status }) => webPage(status),
+});

package/dist/app/features/web/web.run.d.ts

@@ -0,0 +1,24 @@
+import { WebControl, type WebState } from '../../../host/web/index.js';
+export declare const START_WAIT_MS = 15000;
+/**
+ * The running server when it is this version's. A server of another version (one left running across an update) is
+ * stopped, so the page and the server always match; a state file without a server is removed.
+ */
+export declare function currentServer(control: WebControl): Promise<WebState | null>;
+/** Whether the web UI runs, and its address without the token. Never returns the state (it holds the token). */
+export declare const webStatusRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    running: import("zod").ZodBoolean;
+    port: import("zod").ZodNullable<import("zod").ZodNumber>;
+    address: import("zod").ZodNullable<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, "web.status">, import("../../../cli/commands/context.js").Context>;
+export declare const startWebRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    port: import("zod").ZodNumber;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "web.start">, import("../../../cli/commands/context.js").Context>;
+export declare const openWebRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "web.open">, import("../../../cli/commands/context.js").Context>;
+export declare const stopWebRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    stopped: import("zod").ZodBoolean;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "web.stop">, import("../../../cli/commands/context.js").Context>;

package/dist/app/features/web/web.run.js

@@ -0,0 +1,93 @@
+// The web feature's work: the server in the background (start, open) and stopping it, and whether it runs. The login
+// token lives in the state file and in the address the browser opens; no output, log, progress line or error carries
+// it. The server itself (`sandbox _web`) stays in cli/commands/web.ts.
+import path from 'node:path';
+import { packageVersion } from '../../../core/package-info.js';
+import { fail, sleep } from '../../../core/util/index.js';
+import { requireOnPc } from '../../../cli/commands/context.js';
+import { spawnDetached } from '../../../host/sandbox/index.js';
+import { openBrowser, WebControl, WebStore } from '../../../host/web/index.js';
+import { implement } from '../../context.js';
+import { openWeb, startWeb, stopWeb, webStatus } from './web.def.js';
+export const START_WAIT_MS = 15000;
+function controlOf(ctx) {
+    return new WebControl(new WebStore(ctx.storageRoot));
+}
+/**
+ * The running server when it is this version's. A server of another version (one left running across an update) is
+ * stopped, so the page and the server always match; a state file without a server is removed.
+ */
+export async function currentServer(control) {
+    const before = await control.status();
+    if (before.running && before.state && before.state.version === packageVersion())
+        return before.state;
+    if (before.running && before.state) {
+        await control.stop(before.state);
+        for (const started = Date.now(); Date.now() - started < START_WAIT_MS; await sleep(300))
+            if (!(await control.status()).running)
+                break;
+    }
+    if (before.state)
+        control.clear();
+    return null;
+}
+/** Starts the background server (when it is not running) and waits until it answers. */
+async function startServer(ctx, io, control) {
+    const running = await currentServer(control);
+    if (running)
+        return {
+            port: running.port,
+            message: 'The web UI is already running on port ' + running.port + '.',
+            wasRunning: true,
+        };
+    const { config } = ctx.loaded;
+    if (!config.web.enabled)
+        io.log('web.enabled is off: this starts the web UI for now only. Set it to true in Settings to keep it allowed.');
+    io.progress('Starting the web UI');
+    const configFile = ctx.options.config;
+    spawnDetached(ctx.entry, ['_web', ...(configFile ? ['--config', path.resolve(configFile)] : [])]);
+    for (const started = Date.now(); Date.now() - started < START_WAIT_MS; await sleep(300)) {
+        const now = await control.status();
+        if (now.running && now.state) {
+            io.log('The web UI is running at http://127.0.0.1:' + now.state.port + '/ (this PC only).');
+            return { port: now.state.port, message: 'Open it already signed in with: sandbox web open', wasRunning: false };
+        }
+    }
+    return fail('The web UI did not start.', 'Run sandbox _web to see why (the port ' + config.web.port + ' may be taken: change web.port).');
+}
+/** Whether the web UI runs, and its address without the token. Never returns the state (it holds the token). */
+export const webStatusRun = implement(webStatus, async (ctx) => {
+    requireOnPc('web');
+    const { running, state } = await controlOf(ctx).status();
+    const port = running && state ? state.port : null;
+    return { running, port, address: port ? 'http://127.0.0.1:' + port + '/' : null };
+});
+export const startWebRun = implement(startWeb, async (ctx, _input, io) => {
+    requireOnPc('web');
+    const started = await startServer(ctx, io, controlOf(ctx));
+    return { port: started.port, message: started.message };
+});
+export const openWebRun = implement(openWeb, async (ctx, _input, io) => {
+    requireOnPc('web');
+    const control = controlOf(ctx);
+    const started = await startServer(ctx, io, control);
+    if (started.wasRunning)
+        io.log(started.message);
+    const { state } = await control.status();
+    if (!state)
+        return fail('The web UI stopped right away.', 'Run sandbox web start again.');
+    openBrowser(control.url(state));
+    return { message: 'Opened in your browser.' };
+});
+export const stopWebRun = implement(stopWeb, async (ctx) => {
+    requireOnPc('web');
+    const control = controlOf(ctx);
+    const { running, state } = await control.status();
+    if (!state)
+        return { stopped: false, message: 'The web UI is not running.' };
+    if (!running || (await control.stop(state)))
+        control.clear();
+    else
+        return fail('The web UI did not stop.', 'End the process ' + state.pid + ' in Task Manager.');
+    return { stopped: true, message: 'The web UI stopped.' };
+});