windows-development-sandbox 1.4.3 → 1.5.0

package/dist/cli/services/health-service.js

@@ -0,0 +1,120 @@
+// Is this PC (and the sandbox) in good shape: doctor rows, repair checks, the setup checklist. Never prints.
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadConfig } from '../../core/config/index.js';
+import { errMsg, expandPath, fail, isWin, UserError } from '../../core/util/index.js';
+import { detectWsb, doctorRows, insideSandbox, isSandboxRunning } from '../../host/sandbox/index.js';
+import { KnownProjects, ProjectRegistry } from '../../host/projects/index.js';
+import { nativeScript } from '../../host/native.js';
+import { refuseInSelfTest } from '../../host/test-guard.js';
+import { SYSTEM } from '../../shared/system.js';
+import { CHECKS } from '../commands/repair/checks.js';
+import { buildChecks, canEnableFeature } from '../commands/setup/checks.js';
+import { ENABLE_COMMAND, gatherFacts } from '../commands/setup/facts.js';
+/** Runs every check in order; a check that throws is reported, never stops the rest. */
+export function runChecks(env, checks = CHECKS) {
+    return checks.map((check) => {
+        try {
+            return { name: check.name, ...check.run(env) };
+        }
+        catch (e) {
+            const fix = e instanceof UserError && e.fix ? ' ' + e.fix : '';
+            return { name: check.name, status: 'needs-you', detail: 'check failed: ' + errMsg(e) + fix };
+        }
+    });
+}
+export class HealthService {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The table `doctor` shows: [name, detail] rows. */
+    doctor() {
+        const { ctx } = this;
+        const rows = doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath);
+        // Inside a sandbox the feature and "running" rows describe the sandbox itself, and the host rows describe nothing
+        // useful.
+        if (insideSandbox())
+            return [
+                ['Where', 'inside a Windows Sandbox started by this tool (run doctor on your PC to check the PC)'],
+                ...rows.filter(([name]) => name === 'Config file'),
+            ];
+        // Several projects: the roots mapped at every start, what the running sandbox has, and whether wsb share is there.
+        const p = ctx.loaded.config.projects;
+        const registry = isSandboxRunning() ? new ProjectRegistry(ctx.storageRoot).read() : null;
+        const wsb = p.wsbShare ? detectWsb() : null;
+        return [
+            ...rows,
+            [
+                'Project roots',
+                p.roots.length
+                    ? p.roots.map((r) => expandPath(r, ctx.loaded.base)).join(', ')
+                    : 'none (sandbox projects roots add <folder>)',
+            ],
+            [
+                'All projects',
+                p.all
+                    ? 'on: ' +
+                        new KnownProjects(ctx.storageRoot).list().length +
+                        ' known project(s) mapped at every start (' +
+                        p.exclude.length +
+                        ' excluded)'
+                    : 'off',
+            ],
+            ['Projects running', registry ? registry.projects.map((x) => x.name + ' (' + x.mechanism + ')').join(', ') : '-'],
+            [
+                'wsb share',
+                !p.wsbShare
+                    ? 'off (projects.wsbShare)'
+                    : wsb
+                        ? 'available: ' +
+                            wsb.exe +
+                            (wsb.version ? ' ' + wsb.version : '') +
+                            ' (untested; a failure offers a restart instead)'
+                        : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox): folders outside your roots need a restart',
+            ],
+        ];
+    }
+    /** Runs the repair checks (and the fixes they make). A config file that does not load is the first problem. */
+    repair(configError = null) {
+        const { ctx } = this;
+        const env = {
+            ctx,
+            running: isSandboxRunning(),
+            dataPath: ctx.dataPath,
+            storageRoot: ctx.storageRoot,
+            toolsDir: path.join(ctx.dataPath, 'tools'),
+            configError,
+        };
+        // Re-check the config file even when the context loaded (it may have been edited since, or come from --config).
+        if (!env.configError) {
+            try {
+                loadConfig(ctx.options.config);
+            }
+            catch (e) {
+                if (e instanceof UserError)
+                    env.configError = e;
+                else
+                    throw e;
+            }
+        }
+        return runChecks(env);
+    }
+    /** Fails unless this is Windows: Windows Sandbox runs nowhere else. */
+    assertWindows() {
+        if (!isWin)
+            fail('Windows Sandbox only runs on Windows.', 'Run sandbox setup on a Windows 10/11 Pro, Enterprise or Education PC.');
+    }
+    /** The setup checklist for this PC. */
+    setupReport() {
+        const facts = gatherFacts(this.ctx.storageRoot);
+        return { facts, checks: buildChecks(facts), canEnable: canEnableFeature(facts) };
+    }
+    /** Runs the enable command in an elevated PowerShell (Windows asks for permission); true if it worked. */
+    enableFeature() {
+        refuseInSelfTest('turn on Windows features');
+        return (spawnSync(SYSTEM.powershell(), nativeScript('scripts/run-elevated.ps1', ['-Command', ENABLE_COMMAND + ' | Out-Null']), {
+            stdio: 'inherit',
+        }).status === 0);
+    }
+}

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

@@ -0,0 +1,12 @@
+export { AccountsService, type AccountRef, type AccountsContext, type AgentAccounts } from './accounts-service.js';
+export { AgentCommandsService, type AgentCommand, type AgentCommandsStatus } from './agent-commands-service.js';
+export { DataService, type CleanOutcome, type CleanPlan, type DataReport, type SizedTarget } from './data-service.js';
+export { resolveCleanTargets, type CleanTarget } from './data-targets.js';
+export { DatabasesService, parseDatabaseList, type DatabaseAction, type DatabaseRow } from './databases-service.js';
+export { autoMigrates, continuesAfterFailedMigration, MigrateService, type MigrateContext, type MigrateResult, } from './migrate-service.js';
+export { NPM_UPDATE_COMMAND, UpdateService, runsAsSystem, type CheckResult, type UpdateServiceOptions, type UpdateStatus, type UpdateTaskPort, } from './update-service.js';
+export { LogsService, type LogFile } from './logs-service.js';
+export { HealthService, runChecks, type SetupReport } from './health-service.js';
+export { ProjectsService, type ProjectRow, type ProjectSettings, type ProjectsListing } from './projects-service.js';
+export { SandboxService, type OtherSession, type ProjectInfo, type SandboxReport, type SandboxState, type StopPlan, } from './sandbox-service.js';
+export { SessionsService, projectOf, viewerText, type ListedSession, type RestartScope } from './sessions-service.js';

package/dist/cli/services/index.js

@@ -0,0 +1,12 @@
+export { AccountsService } from './accounts-service.js';
+export { AgentCommandsService } from './agent-commands-service.js';
+export { DataService } from './data-service.js';
+export { resolveCleanTargets } from './data-targets.js';
+export { DatabasesService, parseDatabaseList } from './databases-service.js';
+export { autoMigrates, continuesAfterFailedMigration, MigrateService, } from './migrate-service.js';
+export { NPM_UPDATE_COMMAND, UpdateService, runsAsSystem, } from './update-service.js';
+export { LogsService } from './logs-service.js';
+export { HealthService, runChecks } from './health-service.js';
+export { ProjectsService } from './projects-service.js';
+export { SandboxService, } from './sandbox-service.js';
+export { SessionsService, projectOf, viewerText } from './sessions-service.js';

package/dist/cli/services/logs-service.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from '../commands/context.js';
+export interface LogFile {
+    readonly name: string;
+    readonly path: string;
+    readonly bytes: number;
+    /** Last written (ms). */
+    readonly modified: number;
+}
+export declare class LogsService {
+    private readonly ctx;
+    constructor(ctx: Pick<Context, 'dataPath'>);
+    private dir;
+    /** Log files, newest first. */
+    files(): LogFile[];
+    /** The newest log, or a UserError when there is none yet. */
+    newest(): string;
+    /**
+     * What was written to `file` since offset `from` (0 = the end of the log), as text safe for a terminal, and where
+     * to continue from. Null when nothing new.
+     */
+    read(file: string, from: number): {
+        text: string;
+        next: number;
+    } | null;
+}

package/dist/cli/services/logs-service.js

@@ -0,0 +1,54 @@
+// The sandbox's own logs (written inside the sandbox, so never read through links). Returns data, never prints.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { assertNoLinks, fail, safeText } from '../../core/util/index.js';
+const LOG_NAME = /^(guest|daemon|bootstrap)-.*\.log$/;
+/** Only the end of a log is read: the sandbox writes it. */
+const FIRST_READ_BYTES = 64 * 1024;
+const MAX_CHUNK_BYTES = 4 * 1024 * 1024;
+export class LogsService {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    dir() {
+        const dir = path.join(this.ctx.dataPath, 'logs');
+        assertNoLinks(this.ctx.dataPath, dir);
+        return dir;
+    }
+    /** Log files, newest first. */
+    files() {
+        const dir = this.dir();
+        if (!fs.existsSync(dir))
+            return [];
+        const found = fs
+            .readdirSync(dir)
+            .filter((f) => LOG_NAME.test(f) && fs.lstatSync(path.join(dir, f)).isFile())
+            .map((name) => {
+            const stat = fs.statSync(path.join(dir, name));
+            return { name, path: path.join(dir, name), bytes: stat.size, modified: stat.mtimeMs };
+        });
+        return _.orderBy(found, 'modified', 'desc');
+    }
+    /** The newest log, or a UserError when there is none yet. */
+    newest() {
+        return (this.files()[0]?.path ??
+            fail('No sandbox logs yet in ' + path.join(this.ctx.dataPath, 'logs') + '.', 'Logs appear after the first start (sandbox claude).'));
+    }
+    /**
+     * What was written to `file` since offset `from` (0 = the end of the log), as text safe for a terminal, and where
+     * to continue from. Null when nothing new.
+     */
+    read(file, from) {
+        const size = fs.statSync(file).size;
+        const start = from === 0 ? Math.max(0, size - FIRST_READ_BYTES) : from;
+        if (size <= start)
+            return null;
+        const fd = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(Math.min(size - start, MAX_CHUNK_BYTES));
+        fs.readSync(fd, buffer, 0, buffer.length, start);
+        fs.closeSync(fd);
+        return { text: safeText(buffer.toString('utf8')), next: start + buffer.length };
+    }
+}

package/dist/cli/services/migrate-service.d.ts

@@ -0,0 +1,29 @@
+import { type Migration } from '../../host/migrate/index.js';
+/** Where the saved settings are: the storage root, the config folder and the config file (if any). */
+export interface MigrateContext {
+    readonly storageRoot: string;
+    readonly userDir: string;
+    readonly configPath: string | null;
+}
+export interface MigrateResult {
+    readonly applied: readonly string[];
+    readonly postponed: readonly string[];
+}
+export declare class MigrateService {
+    private readonly version;
+    private readonly marker;
+    private readonly runner;
+    constructor(where: MigrateContext, version?: string, migrations?: readonly Migration[], sandboxRunning?: () => boolean);
+    /** The version that last brought the settings up to date (one small file). */
+    lastVersion(): string;
+    /** The settings were last updated by another version than this one. */
+    versionChanged(): boolean;
+    /** One line per change still to make. */
+    plan(): string[];
+    run(note: (line: string) => void): Promise<MigrateResult>;
+    restore(backup: string): void;
+}
+/** Does this command update the saved settings before it runs (when the version changed)? Never inside a sandbox. */
+export declare function autoMigrates(command: string, inSandbox: boolean): boolean;
+/** On failure the command still runs only for these: they are how you find out what is wrong. */
+export declare function continuesAfterFailedMigration(command: string): boolean;

package/dist/cli/services/migrate-service.js

@@ -0,0 +1,43 @@
+// Bringing the saved settings up to date with this version: the logic behind `sandbox migrate`, the automatic run at
+// the start of a command and the Maintenance row. Returns data, never prints.
+import { MIGRATIONS, MigrationMarker, MigrationRunner } from '../../host/migrate/index.js';
+import { isSandboxRunning } from '../../host/sandbox/index.js';
+import { packageVersion } from '../../core/package-info.js';
+export class MigrateService {
+    version;
+    marker;
+    runner;
+    constructor(where, version = packageVersion(), migrations = MIGRATIONS, sandboxRunning = isSandboxRunning) {
+        this.version = version;
+        this.marker = new MigrationMarker(where.userDir);
+        this.runner = new MigrationRunner(migrations, { ...where, sandboxRunning }, this.marker);
+    }
+    /** The version that last brought the settings up to date (one small file). */
+    lastVersion() {
+        return this.marker.read().lastVersion;
+    }
+    /** The settings were last updated by another version than this one. */
+    versionChanged() {
+        return this.lastVersion() !== this.version;
+    }
+    /** One line per change still to make. */
+    plan() {
+        return this.runner.planText();
+    }
+    async run(note) {
+        return this.runner.run(this.version, note);
+    }
+    restore(backup) {
+        this.runner.restore(backup);
+    }
+}
+/** Commands that never update the settings first: they must work whatever state the settings are in. */
+const NO_AUTO_MIGRATION = ['self-test', 'migrate', 'update', '_watch'];
+/** Does this command update the saved settings before it runs (when the version changed)? Never inside a sandbox. */
+export function autoMigrates(command, inSandbox) {
+    return !inSandbox && !NO_AUTO_MIGRATION.includes(command);
+}
+/** On failure the command still runs only for these: they are how you find out what is wrong. */
+export function continuesAfterFailedMigration(command) {
+    return command === 'doctor' || command === 'migrate' || command === 'update';
+}

package/dist/cli/services/projects-service.d.ts

@@ -0,0 +1,56 @@
+import type { Context } from '../commands/context.js';
+export interface ProjectRow {
+    readonly folder: string;
+    readonly here: boolean;
+    readonly known: boolean;
+    readonly root: string | null;
+    readonly excluded: boolean;
+    readonly mappedAtStart: boolean;
+    readonly running: string | null;
+}
+/** projects.all, roots and exclude, with the folders expanded. */
+export interface ProjectSettings {
+    readonly all: boolean;
+    readonly roots: string[];
+    readonly exclude: string[];
+}
+export interface ProjectsListing extends ProjectSettings {
+    readonly projects: ProjectRow[];
+}
+export declare class ProjectsService {
+    private readonly ctx;
+    constructor(ctx: Context);
+    settings(): ProjectSettings;
+    /** Every project worth listing: known ones, the running sandbox's, and this folder. */
+    rows(): ProjectRow[];
+    list(): ProjectsListing;
+    /** Remembers a project folder (it must pass the same checks as a workspace). Returns the folder. */
+    add(folder: string): string;
+    /** Forgets a project, in the running sandbox too (its folder stays visible until the sandbox stops). */
+    forget(folder: string): {
+        dir: string;
+        removed: boolean;
+    };
+    /** Excludes a folder from the projects mapped at every start. True when that changed anything. */
+    exclude(folder: string): boolean;
+    /** Includes a folder again (and remembers it). True when it was excluded before. */
+    include(folder: string): boolean;
+    /** Maps every project at every start (or none). */
+    setAll(on: boolean): void;
+    /** Adds a project root (a folder of projects). Returns the folder and whether it was new. */
+    addRoot(folder: string): {
+        dir: string;
+        added: boolean;
+    };
+    removeRoot(folder: string): {
+        dir: string;
+        removed: boolean;
+    };
+    /** Maps the ticked projects at every start (projects.all on when any is ticked); the rest are excluded. */
+    choose(rows: readonly ProjectRow[], picked: readonly string[]): {
+        mapped: number;
+        excluded: number;
+    };
+    /** A folder for roots: it holds projects, so it must pass the same checks as a workspace and must not be a drive. */
+    private checkFolder;
+}

package/dist/cli/services/projects-service.js

@@ -0,0 +1,111 @@
+// Projects a sandbox can open without a restart: roots, known projects, include/exclude. Returns data, never prints.
+import path from 'node:path';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { dirExists, expandPath, fail, isRootPath } from '../../core/util/index.js';
+import { isSandboxRunning } from '../../host/sandbox/index.js';
+import { KnownProjects, projectMapper, ProjectRegistry } from '../../host/projects/index.js';
+import { isWithin } from '../../shared/paths/index.js';
+import { hereDir } from '../commands/projects/here.js';
+import { addToList, removeFromList, setSetting } from '../commands/user-config.js';
+export class ProjectsService {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    settings() {
+        const p = this.ctx.loaded.config.projects;
+        const expand = (list) => list.map((x) => expandPath(x, this.ctx.loaded.base));
+        return { all: p.all, roots: expand(p.roots), exclude: expand(p.exclude) };
+    }
+    /** Every project worth listing: known ones, the running sandbox's, and this folder. */
+    rows() {
+        const { ctx } = this;
+        const s = this.settings();
+        const registry = isSandboxRunning() ? new ProjectRegistry(ctx.storageRoot).read() : null;
+        const here = hereDir(ctx);
+        const known = new KnownProjects(ctx.storageRoot).list();
+        const folders = [...known.map((k) => k.host), ...(registry?.projects.map((p) => p.host) ?? [])];
+        const unique = folders.filter((f, i) => folders.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i);
+        return unique.map((folder) => {
+            const root = s.roots.find((r) => isWithin(r, folder)) ?? null;
+            const excluded = s.exclude.some((e) => isWithin(e, folder));
+            const inSandbox = registry?.projects.find((p) => p.host.toLowerCase() === folder.toLowerCase());
+            return {
+                folder,
+                here: isWithin(folder, here),
+                known: known.some((k) => k.host.toLowerCase() === folder.toLowerCase()),
+                root,
+                excluded,
+                mappedAtStart: root !== null || (s.all && !excluded && dirExists(folder)),
+                running: inSandbox ? inSandbox.name + ' (' + inSandbox.mechanism + ')' : null,
+            };
+        });
+    }
+    list() {
+        const s = this.settings();
+        return { all: s.all, roots: s.roots, exclude: s.exclude, projects: this.rows() };
+    }
+    /** Remembers a project folder (it must pass the same checks as a workspace). Returns the folder. */
+    add(folder) {
+        const dir = this.checkFolder(folder, 'a project');
+        new KnownProjects(this.ctx.storageRoot).remember(dir);
+        return dir;
+    }
+    /** Forgets a project, in the running sandbox too (its folder stays visible until the sandbox stops). */
+    forget(folder) {
+        const { ctx } = this;
+        const dir = path.resolve(folder);
+        const forgot = new KnownProjects(ctx.storageRoot).forget(dir);
+        const registered = isSandboxRunning()
+            ? new ProjectRegistry(ctx.storageRoot)
+                .read()
+                ?.projects.find((p) => !p.primary && p.host.toLowerCase() === dir.toLowerCase())
+            : undefined;
+        if (registered)
+            projectMapper({ storageRoot: ctx.storageRoot, packageRoot: ctx.packageRoot, wsbShare: false }).unregister(registered.name);
+        return { dir, removed: forgot || Boolean(registered) };
+    }
+    /** Excludes a folder from the projects mapped at every start. True when that changed anything. */
+    exclude(folder) {
+        return addToList(this.ctx, ['projects', 'exclude'], path.resolve(folder));
+    }
+    /** Includes a folder again (and remembers it). True when it was excluded before. */
+    include(folder) {
+        const dir = path.resolve(folder);
+        const changed = removeFromList(this.ctx, ['projects', 'exclude'], dir);
+        new KnownProjects(this.ctx.storageRoot).remember(dir);
+        return changed;
+    }
+    /** Maps every project at every start (or none). */
+    setAll(on) {
+        setSetting(this.ctx, ['projects', 'all'], on);
+    }
+    /** Adds a project root (a folder of projects). Returns the folder and whether it was new. */
+    addRoot(folder) {
+        const dir = this.checkFolder(folder, 'a project root');
+        return { dir, added: addToList(this.ctx, ['projects', 'roots'], dir) };
+    }
+    removeRoot(folder) {
+        const dir = path.resolve(folder);
+        return { dir, removed: removeFromList(this.ctx, ['projects', 'roots'], dir) };
+    }
+    /** Maps the ticked projects at every start (projects.all on when any is ticked); the rest are excluded. */
+    choose(rows, picked) {
+        const s = this.settings();
+        const exclude = rows.filter((r) => !picked.includes(r.folder)).map((r) => r.folder);
+        setSetting(this.ctx, ['projects', 'exclude'], [...s.exclude.filter((e) => !rows.some((r) => r.folder.toLowerCase() === e.toLowerCase())), ...exclude]);
+        setSetting(this.ctx, ['projects', 'all'], picked.length > 0);
+        return { mapped: picked.length, excluded: exclude.length };
+    }
+    /** A folder for roots: it holds projects, so it must pass the same checks as a workspace and must not be a drive. */
+    checkFolder(folder, what) {
+        const dir = path.resolve(folder);
+        if (!dirExists(dir))
+            fail('The folder ' + dir + ' does not exist.', 'Check the path.');
+        if (isRootPath(dir))
+            fail('A whole drive cannot be ' + what + ': ' + dir, 'Use the folder that holds your projects, e.g. F:\\Code.');
+        assertSafeWorkspace(dir, this.ctx.packageRoot, this.ctx.storageRoot);
+        assertSafeMapping(dir, this.ctx.packageRoot, this.ctx.storageRoot);
+        return dir;
+    }
+}

package/dist/cli/services/sandbox-service.d.ts

@@ -0,0 +1,78 @@
+import type { SandboxStatus, SessionStatus } from '../../core/types.js';
+import type { Registry, RegistryEntry } from '../../host/projects/index.js';
+import type { Context } from '../commands/context.js';
+/** What is known about one project of the running sandbox. */
+export interface ProjectInfo {
+    readonly name: string;
+    readonly host: string;
+    readonly guest: string;
+    readonly mechanism: RegistryEntry['mechanism'];
+    readonly here: boolean;
+    readonly setup: {
+        readonly phase: string;
+        readonly message: string;
+    };
+    readonly databases: {
+        readonly database: string;
+        readonly port: number;
+        readonly state: string;
+    }[];
+    readonly sessions: {
+        readonly id: string;
+        readonly harness: string;
+        readonly viewers: string;
+        readonly started: string;
+    }[];
+    readonly repoGuard: string[];
+}
+export interface SandboxState {
+    readonly running: boolean;
+    readonly phase: string;
+    readonly message: string | undefined;
+    readonly headless: boolean | undefined;
+    /** When the sandbox started (ms), if known. */
+    readonly startedAt: number | null;
+    readonly daemon: string;
+    readonly account: string | null;
+    readonly syncWatcher: boolean;
+}
+export interface OtherSession {
+    readonly id: string;
+    readonly harness: string;
+    readonly cwd: string;
+}
+export interface SandboxReport {
+    readonly sandbox: SandboxState;
+    readonly here: {
+        readonly folder: string;
+        readonly project: string | null;
+        readonly guest: string | null;
+    };
+    readonly roots: Registry['roots'];
+    readonly projects: ProjectInfo[];
+    readonly otherSessions: OtherSession[];
+    readonly repoGuard: {
+        readonly guarded: number;
+        readonly findings: string[];
+    };
+}
+/** What stopping would end: every project's sessions, and the ones outside this folder's project. */
+export interface StopPlan {
+    readonly sandbox: SandboxStatus;
+    readonly running: SessionStatus[];
+    readonly others: SessionStatus[];
+}
+export declare class SandboxService {
+    private readonly ctx;
+    constructor(ctx: Context);
+    isRunning(): boolean;
+    /** Everything `status` shows. Text that comes from the sandbox goes through safeText. */
+    status(): Promise<SandboxReport>;
+    /** Brings the sandbox window to the front. */
+    showWindow(): void;
+    hideWindow(): Promise<void>;
+    /** What stopping ends. Fails when this sandbox was not started by this tool. */
+    stopPlan(): StopPlan;
+    /** Asks the sandbox to shut down (history and claude-mem sync back when it closes). */
+    shutdown(sandbox: SandboxStatus): Promise<void>;
+}