windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/commands/repair/engine.js

@@ -0,0 +1,127 @@
+// The engine behind doctor and repair: runs the checks in order (grouped), each with its own time limit, tells a hook
+// as each one starts and ends, then applies the fixes you agreed to and looks again to see they worked. Never prints.
+import { errMsg, UserError } from '../../../core/util/index.js';
+import { CHECK_GROUPS, WHILE_RUNNING, } from './types.js';
+export const DEFAULT_TIMEOUT_MS = 20_000;
+export const FIX_TIMEOUT_MS = 120_000;
+class TimedOut extends Error {
+}
+/** Resolves with `work`, or rejects with TimedOut after `ms` (a check that blocks the process cannot be stopped). */
+export function withTimeout(work, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimedOut()), ms);
+        Promise.resolve()
+            .then(work)
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        });
+    });
+}
+/** The checks in the order they are shown: by group, then as listed. */
+export function inGroupOrder(checks) {
+    return [...checks].sort((a, b) => CHECK_GROUPS.indexOf(a.group) - CHECK_GROUPS.indexOf(b.group));
+}
+export function summarize(results) {
+    const count = (status) => results.filter((r) => r.status === status).length;
+    return {
+        total: results.length,
+        ok: count('ok'),
+        fixed: count('fixed'),
+        warn: count('warn'),
+        needsYou: count('needs-you'),
+        skipped: count('skipped'),
+        fixable: results.filter((r) => r.fixable && r.status !== 'fixed').length,
+    };
+}
+const withUserFix = (e) => errMsg(e) + (e instanceof UserError && e.fix ? ' ' + e.fix : '');
+export class HealthRun {
+    env;
+    hooks;
+    limits;
+    findings = new Map();
+    checks;
+    constructor(checks, env, hooks = {}, limits = {}) {
+        this.env = env;
+        this.hooks = hooks;
+        this.limits = limits;
+        this.checks = inGroupOrder(checks);
+    }
+    /** Runs every check without changing anything. */
+    async look() {
+        const results = [];
+        for (const check of this.checks) {
+            if (check.applies && !check.applies(this.env))
+                continue;
+            this.hooks.lookStart?.(check);
+            const result = await this.lookAt(check);
+            results.push(result);
+            this.hooks.lookEnd?.(result);
+        }
+        return results;
+    }
+    /** Applies the fix of every result repair can mend (or only those in `only`), then looks again. */
+    async fix(results, only) {
+        const out = [];
+        for (const result of results) {
+            const check = this.checks.find((c) => c.id === result.id);
+            const finding = this.findings.get(result.id);
+            if (!check?.fix || !finding || !result.fixable || (only && !only.includes(result.id))) {
+                out.push(result);
+                continue;
+            }
+            this.hooks.fixStart?.(result);
+            const after = await this.fixOne(check, finding, result);
+            out.push(after);
+            this.hooks.fixEnd?.(after);
+        }
+        return out;
+    }
+    async lookAt(check) {
+        const started = Date.now();
+        const base = { id: check.id, group: check.group, name: check.name };
+        if (check.needsIdle === 'look' && this.env.running)
+            return { ...base, status: 'skipped', detail: WHILE_RUNNING, fixable: false, ms: 0 };
+        let finding;
+        try {
+            finding = await withTimeout(() => check.run(this.env), check.timeoutMs ?? this.limits.lookMs ?? DEFAULT_TIMEOUT_MS);
+        }
+        catch (e) {
+            const ms = Date.now() - started;
+            if (e instanceof TimedOut)
+                return { ...base, status: 'skipped', detail: 'took too long, skipped', timedOut: true, fixable: false, ms };
+            return { ...base, status: 'needs-you', detail: 'the check failed: ' + withUserFix(e), fixable: false, ms };
+        }
+        this.findings.set(check.id, finding);
+        return {
+            ...base,
+            status: finding.status,
+            detail: finding.detail,
+            means: finding.means,
+            fix: finding.fix,
+            plan: finding.plan,
+            lines: finding.lines,
+            fixable: Boolean(check.fix && finding.plan && finding.status !== 'ok'),
+            ms: Date.now() - started,
+        };
+    }
+    async fixOne(check, finding, result) {
+        if (check.needsIdle && this.env.running)
+            return { ...result, status: 'skipped', detail: WHILE_RUNNING, fixable: false };
+        try {
+            const outcome = await withTimeout(() => check.fix?.(this.env, finding) ?? { done: '' }, this.limits.fixMs ?? FIX_TIMEOUT_MS);
+            const again = await this.lookAt(check);
+            const applied = { done: outcome.done, before: result.detail, after: again.detail };
+            if (again.status === 'ok')
+                return { ...again, status: 'fixed', detail: outcome.done, fixable: false, applied };
+            return { ...again, fixable: false, applied, error: 'it is still not right after the fix' };
+        }
+        catch (e) {
+            const why = e instanceof TimedOut ? 'took too long' : withUserFix(e);
+            return { ...result, status: 'needs-you', error: why, fixable: false, detail: result.detail };
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import { UserError } from '../../../core/util/index.js';
+import { type SystemProbe } from '../../../host/health/index.js';
+import type { Context } from '../context.js';
+import type { RepairEnv } from './types.js';
+/** The settings file in use: --config, AGENT_SANDBOX_CONFIG, else the user's config.json. */
+export declare function configFileOf(ctx: Context): string;
+export declare function buildEnv(ctx: Context, configError?: UserError | null, system?: SystemProbe): RepairEnv;

package/dist/cli/commands/repair/env.js

@@ -0,0 +1,50 @@
+// Builds what the checks read (RepairEnv) for the real PC from the command's context. Tests build their own.
+import path from 'node:path';
+import { loadConfig, machineRoot, userConfigPath, userDir } from '../../../core/config/index.js';
+import { UserError } from '../../../core/util/index.js';
+import { WindowsProbe } from '../../../host/health/index.js';
+import { InstallLayout, InstallRecordFile } from '../../../host/install/index.js';
+import { MIGRATIONS } from '../../../host/migrate/index.js';
+import { isSandboxRunning } from '../../../host/sandbox/index.js';
+import { hostDataFolder } from '../../../host/storage/index.js';
+import { gatherFacts } from '../setup/facts.js';
+/** The settings file in use: --config, AGENT_SANDBOX_CONFIG, else the user's config.json. */
+export function configFileOf(ctx) {
+    return path.resolve(ctx.options.config ?? process.env.AGENT_SANDBOX_CONFIG ?? userConfigPath());
+}
+/** The settings problem to report: the one the context was made without, or a fresh one (the file may have changed). */
+function configProblem(ctx, known) {
+    if (known)
+        return known;
+    try {
+        loadConfig(ctx.options.config);
+        return null;
+    }
+    catch (e) {
+        if (e instanceof UserError)
+            return e;
+        throw e;
+    }
+}
+export function buildEnv(ctx, configError = null, system = new WindowsProbe()) {
+    const layout = InstallLayout.detect(ctx.packageRoot);
+    let facts = null;
+    return {
+        ctx,
+        running: isSandboxRunning(),
+        dataPath: ctx.dataPath,
+        storageRoot: ctx.storageRoot,
+        toolsDir: hostDataFolder(ctx.dataPath, 'tools'),
+        configError: configProblem(ctx, configError),
+        layout,
+        record: layout ? new InstallRecordFile(layout.root).read() : null,
+        machineHome: machineRoot(),
+        userDir: userDir(),
+        configFile: configFileOf(ctx),
+        migrations: MIGRATIONS,
+        userInstallRoot: process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, 'WindowsDevelopmentSandbox') : null,
+        system,
+        now: Date.now,
+        facts: () => (facts ??= gatherFacts(ctx.storageRoot)),
+    };
+}

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

@@ -1,9 +1 @@
-import { UserError } from '../../../core/util/index.js';
-import type { CliOptions } from '../../args.js';
-import { type Context } from '../context.js';
-export declare function 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 function repairCommand(packageRoot: string, entry: string, options: CliOptions): number;
+export { repairCommand, runDoctor, runRepair } from './run.js';

package/dist/cli/commands/repair/index.js

@@ -1,54 +1,2 @@
-// `sandbox repair`: finds and fixes common problems. Each check (checks.ts) either confirms all is well (OK), fixes the
-// problem itself (FIXED), or says what you need to do (NEEDS YOU). Toolchain and run-state fixes wait until no
-// sandbox is running.
-import path from 'node:path';
-import _ from 'lodash';
-import { DEFAULTS, userDir } from '../../../core/config/index.js';
-import { expandPath, UserError } from '../../../core/util/index.js';
-import { createContext } from '../context.js';
-import { printJson, table } from '../../output/index.js';
-import { HealthService } from '../../services/index.js';
-const LABEL = {
-    ok: 'OK',
-    fixed: 'FIXED',
-    'needs-you': 'NEEDS YOU',
-    warn: 'WARNING',
-    skipped: 'SKIPPED',
-};
-export function repair(ctx, configError = null) {
-    const results = new HealthService(ctx).repair(configError);
-    if (printJson(ctx, results))
-        return results.some((r) => r.status === 'needs-you') ? 1 : 0;
-    table(results.map((r) => [LABEL[r.status], r.name, r.detail]));
-    const counts = _.countBy(results, 'status');
-    console.log('\n' +
-        (counts['needs-you']
-            ? counts['needs-you'] + ' thing(s) need you (see NEEDS YOU above).'
-            : 'All good' + (counts.fixed ? ': fixed ' + counts.fixed + ' problem(s).' : '.')));
-    return counts['needs-you'] ? 1 : 0;
-}
-/**
- * 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 function repairCommand(packageRoot, entry, options) {
-    let ctx;
-    try {
-        ctx = createContext(packageRoot, entry, options);
-    }
-    catch (e) {
-        if (!(e instanceof UserError))
-            throw e;
-        const loaded = { config: structuredClone(DEFAULTS), configPath: null, base: userDir() };
-        const storageRoot = expandPath(loaded.config.storage.root, loaded.base);
-        return repair({
-            packageRoot,
-            entry,
-            options,
-            loaded,
-            storageRoot,
-            dataPath: path.join(storageRoot, 'data', loaded.config.storage.dataName),
-        }, e);
-    }
-    return repair(ctx);
-}
+// `sandbox doctor` and `sandbox repair`: one engine, checks by group, live output, fixes after a yes, a repair log.
+export { repairCommand, runDoctor, runRepair } from './run.js';

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

@@ -0,0 +1,17 @@
+import type { CheckResult, Summary } from './types.js';
+/** repair-20261015-093012.log */
+export declare function logName(when: Date): string;
+/** The log's text. `found` is what the first look saw; `final` what is true after the fixes (same list if none). */
+export declare function logText(o: {
+    when: Date;
+    version: string;
+    command: string;
+    found: readonly CheckResult[];
+    final: readonly CheckResult[];
+    summary: Summary;
+}): string;
+/**
+ * Writes the log in <storage>\logs and returns its path, or null when the storage folder does not exist (nothing to
+ * keep a log in) or is not safe to write in. Text from the sandbox is cleaned first.
+ */
+export declare function writeRepairLog(storageRoot: string, text: string, when: Date): string | null;

package/dist/cli/commands/repair/log.js

@@ -0,0 +1,82 @@
+// The repair log: what was found, what was changed, and what each check said before and after. One text file per run in
+// <storage>\logs, so there is a record of exactly what repair did to this PC.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNoLinks, dirExists } from '../../../core/util/index.js';
+import { safeText } from '../../../core/util/index.js';
+import { assertTestWritable } from '../../../host/test-guard.js';
+const two = (n) => String(n).padStart(2, '0');
+/** repair-20261015-093012.log */
+export function logName(when) {
+    return ('repair-' +
+        when.getFullYear() +
+        two(when.getMonth() + 1) +
+        two(when.getDate()) +
+        '-' +
+        two(when.getHours()) +
+        two(when.getMinutes()) +
+        two(when.getSeconds()) +
+        '.log');
+}
+/** The log's text. `found` is what the first look saw; `final` what is true after the fixes (same list if none). */
+export function logText(o) {
+    const lines = [
+        'Repair log ' + o.when.toISOString(),
+        'Version ' + o.version + ', command: ' + o.command,
+        '',
+        'Found:',
+    ];
+    for (const r of o.found)
+        lines.push('  [' +
+            r.status +
+            '] ' +
+            r.group +
+            ' / ' +
+            r.name +
+            ': ' +
+            r.detail +
+            (r.plan ? ' (can fix: ' + r.plan + ')' : ''));
+    const changed = o.final.filter((r) => r.applied || r.error);
+    lines.push('', changed.length ? 'Changed:' : 'Nothing was changed.');
+    for (const r of changed) {
+        lines.push('  ' + r.name + ':');
+        if (r.applied)
+            lines.push('    changed: ' + r.applied.done, '    before:  ' + r.applied.before, '    after:   ' + r.applied.after);
+        if (r.error)
+            lines.push('    problem: ' + r.error);
+    }
+    const s = o.summary;
+    lines.push('', 'Result: ' +
+        s.ok +
+        ' ok, ' +
+        s.fixed +
+        ' fixed, ' +
+        s.warn +
+        ' warnings, ' +
+        s.needsYou +
+        ' need you, ' +
+        s.skipped +
+        ' skipped', '');
+    return lines.join('\n');
+}
+/**
+ * Writes the log in <storage>\logs and returns its path, or null when the storage folder does not exist (nothing to
+ * keep a log in) or is not safe to write in. Text from the sandbox is cleaned first.
+ */
+export function writeRepairLog(storageRoot, text, when) {
+    if (!dirExists(storageRoot))
+        return null;
+    const dir = path.join(storageRoot, 'logs');
+    const file = path.join(dir, logName(when));
+    try {
+        assertNoLinks(storageRoot, dir);
+        assertTestWritable(file);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, safeText(text), 'utf8');
+        return file;
+    }
+    catch {
+        // A log that cannot be written must not undo or hide the repair itself; the caller says there is no log.
+        return null;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { CheckResult, Summary } from './types.js';
+import type { RunHooks } from './engine.js';
+/** Where text goes (the terminal; a test collects it). */
+export interface Out {
+    write(text: string): void;
+}
+/** "12 ok, 2 fixed, 1 needs you": the parts that are zero are left out (except ok). */
+export declare function summaryText(s: Summary): string;
+export declare class HealthPrinter {
+    private readonly out;
+    /** Redraw lines in place (a terminal); otherwise each result is one finished line. */
+    private readonly animate;
+    private group;
+    private live;
+    constructor(out: Out, 
+    /** Redraw lines in place (a terminal); otherwise each result is one finished line. */
+    animate?: boolean);
+    private glyph;
+    private clearLive;
+    private heading;
+    title(text: string): void;
+    /** Hooks for HealthRun: print as the checks run (and, for repair, as the fixes are applied). */
+    hooks(): RunHooks;
+    /** One result: the line, then what it means and what to do when it is not ok. */
+    result(r: CheckResult): void;
+    /** What a fix did, on the line it started. */
+    private fixed;
+    /** What repair will change, listed before it asks. */
+    plan(fixable: readonly CheckResult[]): void;
+    summary(results: readonly CheckResult[], s: Summary): void;
+    line(text: string): void;
+}

package/dist/cli/commands/repair/printer.js

@@ -0,0 +1,132 @@
+// How doctor and repair look: headings per group, one line per result as it finishes (a "Checking ..." line while it
+// runs on a terminal), "What it means" and "Fix" under what is not ok, and the summary. The engine's only printing.
+import { c, canAnimate } from '../../output/index.js';
+const GLYPH = {
+    ok: { tty: '✔', plain: '[ok]', paint: c.green },
+    fixed: { tty: '✔', plain: '[fixed]', paint: c.cyan },
+    warn: { tty: '!', plain: '[!]', paint: c.yellow },
+    'needs-you': { tty: '✘', plain: '[x]', paint: c.red },
+    skipped: { tty: '–', plain: '[-]', paint: c.dim },
+};
+const MAX_LINES = 6;
+/** "12 ok, 2 fixed, 1 needs you": the parts that are zero are left out (except ok). */
+export function summaryText(s) {
+    const parts = [
+        s.ok + ' ok',
+        s.fixed && s.fixed + ' fixed',
+        s.needsYou && s.needsYou + ' ' + (s.needsYou === 1 ? 'needs' : 'need') + ' you',
+        s.warn && s.warn + (s.warn === 1 ? ' warning' : ' warnings'),
+        s.skipped && s.skipped + ' skipped',
+    ];
+    return parts.filter(Boolean).join(', ');
+}
+export class HealthPrinter {
+    out;
+    animate;
+    group = null;
+    live = false;
+    constructor(out, 
+    /** Redraw lines in place (a terminal); otherwise each result is one finished line. */
+    animate = canAnimate(process.env, Boolean(process.stdout.isTTY))) {
+        this.out = out;
+        this.animate = animate;
+    }
+    glyph(status) {
+        const g = GLYPH[status];
+        return g.paint(this.animate ? g.tty : g.plain);
+    }
+    clearLive() {
+        if (this.live)
+            this.out.write('\r\x1b[2K');
+        this.live = false;
+    }
+    heading(group) {
+        if (group === this.group)
+            return;
+        this.group = group;
+        this.out.write('\n' + c.bold(group) + '\n');
+    }
+    title(text) {
+        this.out.write(c.bold(text) + '\n');
+    }
+    /** Hooks for HealthRun: print as the checks run (and, for repair, as the fixes are applied). */
+    hooks() {
+        return {
+            lookStart: (check) => {
+                this.heading(check.group);
+                if (!this.animate)
+                    return;
+                this.live = true;
+                this.out.write('  ' + c.dim('… Checking ' + (check.checking ?? check.name.toLowerCase()) + '…'));
+            },
+            lookEnd: (result) => {
+                this.clearLive();
+                this.result(result);
+            },
+            fixStart: (result) => {
+                this.heading(result.group);
+                if (!this.animate)
+                    return;
+                this.live = true;
+                this.out.write('  ' + c.dim('… Fixing: ' + (result.plan ?? result.name) + '…'));
+            },
+            fixEnd: (result) => {
+                this.clearLive();
+                this.fixed(result);
+            },
+        };
+    }
+    /** One result: the line, then what it means and what to do when it is not ok. */
+    result(r) {
+        this.heading(r.group);
+        const note = r.timedOut ? ' (took too long)' : '';
+        this.out.write('  ' + this.glyph(r.status) + ' ' + c.bold(r.name) + ': ' + r.detail + note + '\n');
+        if (r.status === 'ok')
+            return;
+        if (r.means)
+            this.out.write('      What it means: ' + r.means + '\n');
+        if (r.fixable && r.plan)
+            this.out.write('      Fix: sandbox repair will ' + r.plan + '\n');
+        else if (r.fix)
+            this.out.write('      Fix: ' + r.fix + '\n');
+        for (const line of (r.lines ?? []).slice(0, MAX_LINES))
+            this.out.write('        ' + line + '\n');
+        if ((r.lines?.length ?? 0) > MAX_LINES)
+            this.out.write('        ... and ' + (r.lines.length - MAX_LINES) + ' more\n');
+    }
+    /** What a fix did, on the line it started. */
+    fixed(r) {
+        this.heading(r.group);
+        if (r.status === 'fixed') {
+            this.out.write('  ' + this.glyph('fixed') + ' ' + c.bold(r.name) + ': ' + (r.applied?.done ?? r.detail) + '\n');
+            return;
+        }
+        const prefix = '  ' + this.glyph('needs-you') + ' ' + c.bold(r.name) + ': ';
+        this.out.write(prefix + 'the fix did not work' + (r.error ? ' (' + r.error + ')' : '') + '\n');
+        if (r.fix)
+            this.out.write('      Fix: ' + r.fix + '\n');
+    }
+    /** What repair will change, listed before it asks. */
+    plan(fixable) {
+        this.out.write('\n' + c.bold('Repair will change:') + '\n');
+        fixable.forEach((r, i) => {
+            this.out.write('  ' + (i + 1) + '. ' + r.name + ': ' + (r.plan ?? r.detail) + '\n');
+            for (const line of (r.lines ?? []).slice(0, MAX_LINES))
+                this.out.write('       ' + line + '\n');
+        });
+        this.out.write('Nothing is deleted except leftovers; your settings, logins and projects are never removed.\n');
+    }
+    summary(results, s) {
+        this.clearLive();
+        this.out.write('\n' + c.bold('Summary') + ': ' + summaryText(s) + '\n');
+        const left = results.filter((r) => r.status === 'needs-you');
+        if (left.length) {
+            this.out.write('\n' + c.bold('Still needs you:') + '\n');
+            for (const r of left)
+                this.out.write('  - ' + r.name + ': ' + (r.fix ?? r.detail) + '\n');
+        }
+    }
+    line(text) {
+        this.out.write(text + '\n');
+    }
+}

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

@@ -0,0 +1,33 @@
+import { UserError } from '../../../core/util/index.js';
+import type { CliOptions } from '../../args.js';
+import { type Context } from '../context.js';
+import { HealthPrinter } from './printer.js';
+import type { Check, CheckResult, RepairEnv, Summary } from './types.js';
+/** What both commands find, and what they do about it. */
+export interface HealthReport {
+    readonly found: CheckResult[];
+    readonly final: CheckResult[];
+    readonly summary: Summary;
+    /** Fixes were applied. */
+    readonly changed: boolean;
+}
+interface Plan {
+    /** Fix without asking. */
+    readonly yes: boolean;
+    /** May ask (a terminal, and not --json). */
+    readonly ask: boolean;
+    /** The question asked after the list of what will change. */
+    readonly question: (n: number) => string;
+}
+/** Runs the checks, then (when allowed) the fixes. `printer` is null for --json. */
+export declare function runHealth(env: RepairEnv, printer: HealthPrinter | null, plan: Plan, checks?: readonly Check[], confirmFix?: (question: string) => Promise<boolean>): Promise<HealthReport>;
+/** `sandbox doctor` */
+export declare function runDoctor(ctx: Context): Promise<number>;
+/** `sandbox repair` for a loaded context. */
+export declare function runRepair(ctx: Context, configError?: UserError | null): Promise<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 settings problem as a check of its own.
+ */
+export declare function repairCommand(packageRoot: string, entry: string, options: CliOptions): Promise<number>;
+export {};