windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/cli/commands/launch.js

@@ -0,0 +1,152 @@
+// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one.
+import { activateAccount, activeAccount, defaultAccount } from '../../host/accounts.js';
+import { attachTerminal, findUnwatchedSession, requestSession, resetRunDir, waitForReady, waitForSession } from '../../host/channel.js';
+import { describePrune, pruneStorage } from '../../host/cleanup.js';
+import { generateSandbox } from '../../host/generate.js';
+import { findSecretFiles } from '../../host/secrets.js';
+import { checkRepo, saveRepoSnapshot } from '../../host/repo-guard.js';
+import { assertCanLaunch, insideSandbox, isSandboxRunning, probeHost, spawnDetached, startSandbox } from '../../host/platform.js';
+import { ensureTerminal } from '../../host/terminal.js';
+import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
+import { readSandboxStatus } from '../../shared/rundir.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { syncBeforeLaunch, watcherRunning } from '../../sync/watcher.js';
+import { errMsg, fail, sleep } from '../../core/util.js';
+import { askYesNo, resolveRun } from '../../core/workspace.js';
+import { currentGuestDir, sandboxAlive, table } from './context.js';
+/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
+export const attachHere = (ctx, session) => {
+    if (ctx.loaded.config.attach.autoHide && !insideSandbox())
+        void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
+    return attachTerminal(session);
+};
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+const firstBoot = (dataPath) => !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
+const FIRST_BOOT = 'First start for this storage: the sandbox downloads and installs the toolchains, databases and agent this project needs.\n' +
+    'That takes a few minutes, once. Everything is kept, so every later start reuses it and takes seconds. Progress:';
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+const runningSandboxStatus = async (dataPath) => {
+    for (let i = 0; i < 60; i++) {
+        const status = readSandboxStatus(dataPath);
+        if (status)
+            return status;
+        await sleep(1000);
+    }
+    return fail('A Windows Sandbox is running that this tool did not start (or that uses another storage.dataName).', 'Close that sandbox window first, then run sandbox claude again.');
+};
+/** A sandbox is already running: open another agent session in it (new tab inside; optionally attach here). */
+const launchIntoRunning = async (ctx) => {
+    const { options, loaded, dataPath } = ctx;
+    const status = await runningSandboxStatus(dataPath);
+    const ready = status.phase === 'ready' ? status : await waitForReady(dataPath, status.launchId, sandboxAlive);
+    const cwd = currentGuestDir(ctx, ready.workspaceHost, ready.guestWorkspace);
+    const harness = options.harness ?? loaded.config.defaultHarness;
+    // -t with nothing new for the agent: pick up this folder's session if no terminal on this PC shows it (its tab was
+    // closed, or you detached). Someone already attached, --new, or agent arguments: a new session, as before.
+    const reuse = options.terminal && !options.newSession && options.passthrough.length === 0 && loaded.config.attach.reuseSession;
+    const existing = reuse ? await findUnwatchedSession(dataPath, harness, cwd) : null;
+    if (existing) {
+        console.log('Reattaching to ' + harness + ' session ' + existing.id + ' in ' + cwd + ' (no other terminal is attached; --new starts another).');
+        return attachHere(ctx, existing);
+    }
+    console.log('Sandbox already running: starting another ' + harness + ' session in ' + cwd);
+    const session = await waitForSession(dataPath, requestSession(dataPath, harness, options.passthrough, cwd), sandboxAlive);
+    if (options.terminal)
+        return attachHere(ctx, session);
+    console.log('Session ' + session.id + ' opened in a new tab inside the sandbox. Attach here with: sandbox attach ' + session.id + (ready.headless ? '   (headless: sbx-show opens the window)' : ''));
+    return 0;
+};
+const syncSummary = (config, dataPath, workspaceHost) => {
+    try {
+        const s = syncBeforeLaunch(config, dataPath, workspaceHost);
+        return s.history + ' file(s) of history in, claude-mem ' + s.claudeMem;
+    }
+    catch (e) {
+        return 'FAILED: ' + errMsg(e);
+    }
+};
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+const prepare = async (ctx, run) => {
+    const { options, dataPath, storageRoot } = ctx;
+    const { config } = run;
+    const account = options.account ?? defaultAccount(storageRoot);
+    if (account && run.harnessName === 'claude' && account !== activeAccount(dataPath))
+        activateAccount(storageRoot, dataPath, account);
+    const terminal = config.provisioning.terminal.enabled ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false }) : { exe: null, message: 'disabled' };
+    const history = syncSummary(config, dataPath, run.workspaceHost);
+    const guarded = checkRepo(dataPath);
+    if (guarded.length)
+        console.warn('\x1b[33mSECURITY: neutralised ' + guarded.length + ' change(s) the last sandbox made that could run code on this PC (see sandbox status).\x1b[0m');
+    saveRepoSnapshot(dataPath, run.workspaceHost);
+    resetRunDir(dataPath);
+    return { account, terminal: terminal.message, history, pruned: describePrune(pruneStorage(storageRoot)) };
+};
+export const launch = async (ctx, generateOnly = false) => {
+    const { options, loaded, packageRoot, dataPath, storageRoot } = ctx;
+    // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
+    if (loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
+        options.terminal = true;
+    if (!generateOnly && isSandboxRunning()) {
+        if (!options.noAgent)
+            return launchIntoRunning(ctx);
+        // Only one Windows Sandbox can run: "start" on a running one brings its window up instead.
+        console.log('A sandbox is already running' + (showSandboxWindow(storageRoot) ? '; its window is in front now.' : '.') + ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
+        return 0;
+    }
+    const run = await resolveRun({
+        packageRoot, loaded, cwd: process.cwd(), workspace: options.workspace, harness: options.harness, noAgent: options.noAgent,
+        noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases, headless: options.headless,
+        nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
+    });
+    const { config } = run;
+    if (!generateOnly)
+        assertCanLaunch();
+    const prepared = generateOnly ? null : await prepare(ctx, run);
+    const generated = generateSandbox({ packageRoot, run, harnessArgs: options.passthrough, probe: probeHost(config, run.harnessName) });
+    for (const note of run.notes)
+        console.log(note);
+    const secretFiles = config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
+    if (secretFiles.length)
+        console.warn('\x1b[33mHeads-up: the agent can read these files in your workspace, which often hold secrets: ' + secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '') + '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.\x1b[0m');
+    table([
+        ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
+        ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   Network: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
+        ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
+        ...(prepared ? [['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
+        ['Toolchains', Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name, d]) => name + ' (' + d.reason + ')').join(', ') || 'Node only (nothing else used by this project)'],
+        ...(generated.databases.length
+            ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; see hostAccess.forwards)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
+            : [['Databases', 'none needed (databases.<name>.enabled = true adds one)']]),
+        ['Desktop', generated.personalization],
+        ['Claude', generated.profile.staged.length ? generated.profile.staged.join(', ') + (generated.profile.credentials ? '  (INCLUDING YOUR LOGIN)' : '') : 'no settings copied'],
+        ['Secrets', !config.secrets.strip ? 'NOT stripped (secrets.strip is off)' : generated.profile.secretsRemoved.length ? 'kept on this PC: ' + generated.profile.secretsRemoved.join(', ') + '  (secrets.allow lets one through)' : 'none found in what is copied'],
+        ...generated.mappings.slice(3).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest]),
+        ['Generated', generated.wsbPath],
+    ]);
+    if (generateOnly)
+        return 0;
+    startSandbox(generated.wsbPath);
+    // Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently.
+    if (!watcherRunning(dataPath))
+        spawnDetached(ctx.entry, ['_watch', ...(options.config ? ['--config', path.resolve(options.config)] : [])]);
+    // Hiding runs alongside; a failure to find the window must never break the launch or an attach.
+    const hidden = config.sandbox.headless ? hideSandboxWindow(storageRoot).catch(() => false) : null;
+    if (options.terminal || options.noAgent) {
+        console.log(firstBoot(dataPath) ? FIRST_BOOT : 'Waiting for the sandbox (everything it needs is installed already; this takes seconds) ...');
+        await waitForReady(dataPath, generated.launchId, sandboxAlive);
+        // Without an agent there is no session to attach to: the sandbox itself is the result.
+        if (options.noAgent) {
+            console.log('Sandbox ready. Its window has a terminal in ' + config.guestWorkspace + '; from here: sandbox exec -- <command>, sandbox stop.');
+            return 0;
+        }
+        return attachHere(ctx, await waitForSession(dataPath, generated.launchId, sandboxAlive));
+    }
+    if (firstBoot(dataPath))
+        console.log(FIRST_BOOT);
+    if (hidden)
+        console.log(await hidden ? 'Sandbox running headless. Open the window: sbx-show   Attach here: sandbox claude -t' : 'Could not find the sandbox window to hide (it may still be starting); run sandbox hide in a moment.');
+    else
+        console.log('Sandbox starting. ' + run.harnessName + ' opens in Windows Terminal inside it. Attach here any time: sandbox claude -t');
+    return 0;
+};

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

@@ -0,0 +1,8 @@
+import { type Context } from './context.js';
+export declare const sync: (ctx: Context) => number;
+export declare const logs: (ctx: Context) => Promise<number>;
+export declare const clean: (ctx: Context) => number;
+export declare const config: (ctx: Context) => number;
+export declare const doctor: (ctx: Context) => number;
+export declare const claudeHost: (ctx: Context) => number;
+export declare const watcher: (ctx: Context) => Promise<void>;

package/dist/cli/commands/maintenance.js

@@ -0,0 +1,125 @@
+// sync, logs, clean, config, doctor, host-claude and the internal sync watcher.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import _ from 'lodash';
+import { DEFAULTS, userConfigPath, userDir } from '../../core/config.js';
+import { describeOverrides, isTrusted, LOCAL_CONFIG_NAME, normalizeOverrides, readLocalConfig, trustStorePath } from '../../core/local-config.js';
+import { fail, safeText, sleep, writeJson } from '../../core/util.js';
+import { describePrune, pruneStorage } from '../../host/cleanup.js';
+import { doctorRows, hostClaude, isSandboxRunning } from '../../host/platform.js';
+import { readSandboxStatus } from '../../shared/rundir.js';
+import { syncBack, watch } from '../../sync/watcher.js';
+import { table } from './context.js';
+export const sync = (ctx) => {
+    const running = isSandboxRunning();
+    const result = syncBack(ctx.dataPath, !running);
+    console.log('History: ' + result.history + ' item(s) synced back. claude-mem: ' + result.claudeMem + (running ? ' (claude-mem syncs when the sandbox closes)' : ''));
+    return 0;
+};
+const newestLog = (dir) => {
+    if (!fs.existsSync(dir))
+        return null;
+    const logs = fs.readdirSync(dir).filter((f) => /^(guest|daemon|bootstrap)-.*\.log$/.test(f) && fs.lstatSync(path.join(dir, f)).isFile());
+    const newest = _.maxBy(logs, (f) => fs.statSync(path.join(dir, f)).mtimeMs);
+    return newest ? path.join(dir, newest) : null;
+};
+export const logs = async (ctx) => {
+    const dir = path.join(ctx.dataPath, 'logs');
+    const file = newestLog(dir) ?? fail('No sandbox logs yet in ' + dir + '.', 'Logs appear after the first start (sandbox claude).');
+    console.log('== ' + file + ' ==');
+    let printed = 0;
+    // The log is written inside the sandbox: read only its tail, and make it safe for your terminal.
+    const print = () => {
+        const size = fs.statSync(file).size;
+        const from = printed === 0 ? Math.max(0, size - 64 * 1024) : printed;
+        if (size <= from)
+            return;
+        const fd = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(Math.min(size - from, 4 * 1024 * 1024));
+        fs.readSync(fd, buffer, 0, buffer.length, from);
+        fs.closeSync(fd);
+        const text = safeText(buffer.toString('utf8'));
+        process.stdout.write(printed === 0 ? text.split('\n').slice(-120).join('\n') : text);
+        printed = from + buffer.length;
+    };
+    print();
+    while (ctx.options.follow) {
+        await sleep(1000);
+        print();
+    }
+    return 0;
+};
+export const clean = (ctx) => {
+    const running = isSandboxRunning() ? readSandboxStatus(ctx.dataPath)?.launchId : undefined;
+    console.log('Cleanup: ' + describePrune(pruneStorage(ctx.storageRoot, { launchDays: ctx.options.days, keep: _.compact([running]) })));
+    return 0;
+};
+const initConfig = () => {
+    const file = userConfigPath();
+    if (fs.existsSync(file))
+        fail(file + ' already exists.');
+    fs.mkdirSync(path.join(userDir(), 'hooks', 'pre-agent'), { recursive: true });
+    // The schema sits next to the file (a local path), so editors trust it and show docs and autocomplete.
+    writeJson(file, { $schema: './config.schema.json', ...DEFAULTS });
+    console.log('Created ' + file + '. It lists every setting with its default; delete the ones you do not change.');
+    console.log('Your own hook scripts go in ' + path.join(userDir(), 'hooks') + '\\{pre-provision,pre-agent,post-agent}.');
+    console.log('For editor help in every project\'s .sandbox-config.json, run: sandbox config schema');
+    return 0;
+};
+/**
+ * VS Code setting that maps every .sandbox-config.json (and the user config) to the local schema files, so project
+ * files need no "$schema" line and nothing is fetched from the internet (remote schemas need trusting).
+ */
+const printSchemaSettings = () => {
+    const url = (name) => pathToFileURL(path.join(userDir(), name)).href;
+    const setting = {
+        'json.schemas': [
+            { fileMatch: ['**/.sandbox-config.json'], url: url('sandbox-config.schema.json') },
+            { fileMatch: ['**/.agent-sandbox/config.json'], url: url('config.schema.json') },
+        ],
+    };
+    console.log('Add this to your VS Code settings.json (Ctrl+Shift+P > "Preferences: Open User Settings (JSON)"):\n');
+    console.log(JSON.stringify(setting, null, 2).slice(2, -2));
+    console.log('\nThe schema files live in ' + userDir() + ' and are refreshed whenever the sandbox command runs.');
+    return 0;
+};
+/**
+ * `sandbox config check`: the folder's .sandbox-config.json validated and described (risky settings flagged, approval
+ * state), without launching. Fails with the same message a launch would give when the file is not valid.
+ */
+const checkLocalConfig = (ctx) => {
+    const dir = path.resolve(ctx.options.workspace ?? process.cwd());
+    const file = readLocalConfig(dir);
+    if (!file) {
+        console.log('No ' + LOCAL_CONFIG_NAME + ' in ' + dir + '; the sandbox uses your own settings only.');
+        return 0;
+    }
+    const overrides = normalizeOverrides(file.data, dir, file.path);
+    const approved = isTrusted(trustStorePath(ctx.storageRoot), file.path, file.hash);
+    console.log(file.path + ': valid. ' + (approved ? 'Approved (this exact version).' : 'Not approved yet: the next launch asks you.') + '\n');
+    for (const line of describeOverrides(overrides))
+        console.log('  ' + safeText(line));
+    return 0;
+};
+export const config = (ctx) => {
+    const [action = 'show'] = ctx.options.positionals;
+    switch (action) {
+        case 'path':
+            console.log(ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet)');
+            return 0;
+        case 'init': return initConfig();
+        case 'show':
+            console.log(JSON.stringify(ctx.loaded.config, null, 2));
+            return 0;
+        case 'schema': return printSchemaSettings();
+        case 'check': return checkLocalConfig(ctx);
+        default: fail('Unknown config action "' + action + '".', 'Use one of: sandbox config show | path | init | schema | check');
+    }
+};
+export const doctor = (ctx) => {
+    table(doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath));
+    return 0;
+};
+export const claudeHost = (ctx) => hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);
+export const watcher = (ctx) => watch(ctx.dataPath);

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

@@ -0,0 +1,59 @@
+import { UserError } from '../../core/util.js';
+import type { CliOptions } from '../args.js';
+import { type Context } from './context.js';
+export type RepairStatus = 'ok' | 'fixed' | 'needs-you' | 'warn' | 'skipped';
+export interface RepairResult {
+    name: string;
+    status: RepairStatus;
+    detail: string;
+}
+export interface RepairEnv {
+    ctx: Context;
+    running: boolean;
+    dataPath: string;
+    storageRoot: string;
+    toolsDir: string;
+    configError: UserError | null;
+}
+export interface RepairCheck {
+    name: string;
+    run: (env: RepairEnv) => Omit<RepairResult, 'name'>;
+}
+/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
+export declare const findStagingLeftovers: (toolsDir: string) => string[];
+/**
+ * A toolchain folder and the program it must contain. `versions` means one folder per installed version (tools\go\1.23.2);
+ * `match` limits which version folders count (tools\nvm also holds settings and nvm.exe).
+ */
+export interface ToolRule {
+    folder: string;
+    exe: string[];
+    versions?: boolean;
+    match?: RegExp;
+}
+export declare const TOOL_RULES: ToolRule[];
+/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
+export declare const findHalfInstalled: (toolsDir: string, rules?: ToolRule[]) => {
+    path: string;
+    missing: string;
+}[];
+/**
+ * Every link or junction under `root` (the links themselves; nothing behind them is visited). Before descending into
+ * a folder its real path must still be inside root: a folder swapped for a junction between two looks is not followed.
+ */
+export declare const findLinks: (root: string) => string[];
+/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
+export declare const resolvedVersionsValid: (text: string) => boolean;
+/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
+export declare const globalPackages: (json: string) => string[];
+export declare const pidAlive: (pid: number) => boolean;
+/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
+export declare const deadPidFiles: (runDir: string, alive?: (pid: number) => boolean) => string[];
+/** Runs every check in order; a check that throws is reported, never stops the rest. */
+export declare const runChecks: (env: RepairEnv, checks?: RepairCheck[]) => RepairResult[];
+export declare const repair: (ctx: Context, configError?: UserError | null) => number;
+/**
+ * Entry point that works even when the config file is broken (createContext would throw): falls back to the built-in
+ * defaults so the other checks still run, and reports the config problem as the first check.
+ */
+export declare const repairCommand: (packageRoot: string, entry: string, options: CliOptions) => number;