windows-development-sandbox 1.0.5 → 1.4.0

package/dist/host/wsb.d.ts

@@ -0,0 +1,37 @@
+/** Where wsb.exe can be: the Store app's alias, then System32 (never by bare name; cwd is often the workspace). */
+export declare const wsbCandidates: (env?: NodeJS.ProcessEnv) => string[];
+export declare const findWsb: (env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean) => string | null;
+/** The version from `wsb --version` ("0.1.32.0", "wsb 1.2.3+abc"). */
+export declare const parseVersion: (out: string) => string | null;
+/** Subcommand names from `wsb --help` (the lines under "Commands:"). */
+export declare const parseCommands: (help: string) => string[];
+export interface WsbSandbox {
+    id: string;
+    status: string;
+}
+/** `wsb list --raw` (JSON: an array, or an object holding one) or the plain table: the sandboxes and their status. */
+export declare const parseList: (out: string) => WsbSandbox[];
+/** `wsb ip --id <id>`: the first IPv4 address in the output. */
+export declare const parseIp: (out: string) => string | null;
+export interface WsbResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export interface Wsb {
+    exe: string;
+    version: string | null;
+    commands: string[];
+    has: (command: string) => boolean;
+}
+/** The CLI and what it offers, or null on Windows versions without it. */
+export declare const detectWsb: (env?: NodeJS.ProcessEnv) => Wsb | null;
+/** The running sandbox's id: the only running one (with several, none is guessed). */
+export declare const runningSandboxId: (wsb: Wsb) => {
+    id: string | null;
+    error?: string;
+};
+/** Shares a folder of this PC into the running sandbox at `sandboxPath` (read/write unless readOnly). */
+export declare const shareFolder: (wsb: Wsb, id: string, hostPath: string, sandboxPath: string, readOnly?: boolean) => WsbResult;
+export declare const sandboxIp: (wsb: Wsb, id: string) => string | null;

package/dist/host/wsb.js

@@ -0,0 +1,101 @@
+// The Windows Sandbox command line (wsb.exe), Windows 11 24H2+ with the updated Windows Sandbox. Used only where it
+// adds something the .wsb file cannot: `wsb share` puts a folder into the RUNNING sandbox. Launching always stays on
+// the .wsb path, which works on every Windows version. UNTESTED: the machines this was built on predate the CLI, so
+// every call is checked and any failure falls back (the caller offers a restart instead), with the error shown.
+// Syntax from Microsoft's docs (learn.microsoft.com, "Windows Sandbox command line"):
+//   wsb start [--id <id>] [-c|--config <xml>]   wsb list [--raw]   wsb ip --id <id>   wsb stop --id <id>
+//   wsb share --id <id> -f|--host-path <host> -s|--sandbox-path <sandbox> [-w|--allow-write]
+//   wsb exec --id <id> -c <command> -r System|ExistingLogin [-d <dir>]   wsb connect --id <id>   --raw = JSON output
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { refuseInSelfTest } from './test-guard.js';
+const GUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const MAX_OUTPUT = 1024 * 1024;
+/** Where wsb.exe can be: the Store app's alias, then System32 (never by bare name; cwd is often the workspace). */
+export const wsbCandidates = (env = process.env) => [
+    env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, 'Microsoft', 'WindowsApps', 'wsb.exe') : '',
+    path.join(env.SystemRoot ?? env.WINDIR ?? 'C:\\Windows', 'System32', 'wsb.exe'),
+].filter(Boolean);
+export const findWsb = (env = process.env, exists = fs.existsSync) => process.platform === 'win32' || exists !== fs.existsSync ? wsbCandidates(env).find((p) => exists(p)) ?? null : null;
+// ---- parsing (pure; the tests feed it recorded output) ---------------------------------------------------------
+/** The version from `wsb --version` ("0.1.32.0", "wsb 1.2.3+abc"). */
+export const parseVersion = (out) => /\d+\.\d+(?:\.\d+){0,2}/.exec(out)?.[0] ?? null;
+/** Subcommand names from `wsb --help` (the lines under "Commands:"). */
+export const parseCommands = (help) => {
+    const lines = help.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^\s*commands:\s*$/i.test(l));
+    if (start < 0)
+        return [];
+    const names = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\S/.test(line) && line.trim())
+            break;
+        const m = /^\s{1,8}([a-z][a-z-]*)\b/.exec(line);
+        if (m)
+            names.push(m[1].toLowerCase());
+    }
+    return names;
+};
+/** `wsb list --raw` (JSON: an array, or an object holding one) or the plain table: the sandboxes and their status. */
+export const parseList = (out) => {
+    const fromObject = (o) => {
+        if (!o || typeof o !== 'object')
+            return null;
+        const entries = Object.entries(o);
+        const id = entries.find(([k, v]) => /^id$/i.test(k) && typeof v === 'string' && GUID.test(v))?.[1];
+        const status = entries.find(([k]) => /^(status|state)$/i.test(k))?.[1];
+        return id ? { id: GUID.exec(id)[0], status: typeof status === 'string' ? status : 'unknown' } : null;
+    };
+    try {
+        const parsed = JSON.parse(out);
+        const list = Array.isArray(parsed) ? parsed : Object.values(parsed).find(Array.isArray) ?? [parsed];
+        return list.map(fromObject).filter((s) => s !== null);
+    }
+    catch { /* the table */ }
+    return out.split(/\r?\n/).flatMap((line) => {
+        const id = GUID.exec(line)?.[0];
+        if (!id)
+            return [];
+        return [{ id, status: /\brunning\b/i.test(line) ? 'Running' : /\bstopped\b/i.test(line) ? 'Stopped' : 'unknown' }];
+    });
+};
+/** `wsb ip --id <id>`: the first IPv4 address in the output. */
+export const parseIp = (out) => /\b(?:\d{1,3}\.){3}\d{1,3}\b/.exec(out)?.[0] ?? null;
+const call = (exe, args, timeoutMs = 60000) => {
+    const r = spawnSync(exe, args, { encoding: 'utf8', windowsHide: true, timeout: timeoutMs, maxBuffer: MAX_OUTPUT });
+    const stdout = String(r.stdout ?? '').slice(0, MAX_OUTPUT);
+    const stderr = String(r.stderr ?? '').slice(0, MAX_OUTPUT);
+    if (r.error)
+        return { ok: false, stdout, stderr, error: r.error.message };
+    return { ok: r.status === 0, stdout, stderr, ...(r.status === 0 ? {} : { error: (stderr || stdout).trim().split(/\r?\n/).slice(-3).join(' ') || 'exit code ' + r.status }) };
+};
+/** The CLI and what it offers, or null on Windows versions without it. */
+export const detectWsb = (env = process.env) => {
+    const exe = findWsb(env);
+    if (!exe)
+        return null;
+    const version = parseVersion(call(exe, ['--version'], 15000).stdout);
+    const help = call(exe, ['--help'], 15000);
+    const commands = parseCommands(help.stdout + '\n' + help.stderr);
+    // An unreadable help text is not proof of anything: assume the documented commands.
+    const known = commands.length ? commands : ['start', 'list', 'exec', 'stop', 'share', 'connect', 'ip'];
+    return { exe, version, commands: known, has: (c) => known.includes(c) };
+};
+/** The running sandbox's id: the only running one (with several, none is guessed). */
+export const runningSandboxId = (wsb) => {
+    const listed = call(wsb.exe, ['list', '--raw'], 20000);
+    const all = parseList(listed.ok ? listed.stdout : call(wsb.exe, ['list'], 20000).stdout);
+    const running = all.filter((s) => !/stopped/i.test(s.status));
+    if (running.length === 1)
+        return { id: running[0].id };
+    return { id: null, error: running.length ? running.length + ' sandboxes are running (wsb list); cannot tell which one is ours' : 'wsb list shows no running sandbox (one started from a .wsb file may not be listed)' };
+};
+/** Shares a folder of this PC into the running sandbox at `sandboxPath` (read/write unless readOnly). */
+export const shareFolder = (wsb, id, hostPath, sandboxPath, readOnly = false) => {
+    refuseInSelfTest('share a folder into Windows Sandbox');
+    if (!GUID.test(id))
+        return { ok: false, stdout: '', stderr: '', error: 'not a sandbox id: ' + id };
+    return call(wsb.exe, ['share', '--id', id, '-f', hostPath, '-s', sandboxPath, ...(readOnly ? [] : ['--allow-write'])]);
+};
+export const sandboxIp = (wsb, id) => (GUID.test(id) ? parseIp(call(wsb.exe, ['ip', '--id', id], 15000).stdout) : null);