windows-development-sandbox 1.0.5 → 1.1.0

package/dist/cli/commands/project.js

@@ -0,0 +1,63 @@
+// Which project of the running sandbox a command is run from. Every command that works on a running sandbox uses
+// these, so they all agree: `locateHere` only looks (attach, sessions, status, restart), `joinHere` also makes the
+// folder a project of the running sandbox when it can without a restart (launch, start, exec, db).
+import path from 'node:path';
+import { askYesNo } from '../../core/prompt.js';
+import { isInsideOrEqual } from '../../core/util.js';
+import { resolveRun } from '../../core/workspace.js';
+import { prepareProject } from '../../host/channel.js';
+import { projectHere, readRegistry } from '../../host/projects.js';
+import { joinRunning } from '../../host/join.js';
+import { working } from '../progress.js';
+import { guestPathFor, sandboxAlive } from './context.js';
+/** The folder the command is about: --workspace, else the current one. */
+export const hereDir = (ctx) => path.resolve(ctx.options.workspace ?? process.cwd());
+/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
+export const locateHere = (ctx, status) => {
+    const dir = hereDir(ctx);
+    const here = projectHere(ctx.storageRoot, dir);
+    if (here)
+        return here;
+    // A sandbox started before projects existed: only its launch folder.
+    if (!readRegistry(ctx.storageRoot) && status && isInsideOrEqual(status.workspaceHost, dir))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace) };
+    return { project: null, guestDir: null };
+};
+/**
+ * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
+ * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
+ * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
+ */
+export const joinHere = async (ctx, status) => {
+    const { options, loaded, packageRoot, storageRoot, dataPath } = ctx;
+    const dir = hereDir(ctx);
+    // A sandbox started before projects existed: only its launch folder (guestPathFor explains why otherwise).
+    if (!readRegistry(storageRoot))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace), spec: null, harness: null, notes: [] };
+    const joined = await joinRunning({
+        storageRoot, dataPath, packageRoot, hostDir: dir, wsbShare: loaded.config.projects.wsbShare,
+        resolve: (root) => resolveRun({
+            packageRoot, loaded, cwd: root, workspace: root, harness: options.harness, noAgent: options.noAgent,
+            noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases,
+            nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
+        }),
+    });
+    const harness = joined.run && joined.run.harnessName !== 'none' ? joined.run.harnessName : null;
+    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes: joined.notes };
+};
+/** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
+export const provisionJoined = async (ctx, joined) => {
+    if (!joined.spec)
+        return;
+    const spec = joined.spec;
+    let step = 'starting';
+    await working(() => 'Setting up ' + spec.name + ' in the running sandbox: ' + step, () => prepareProject(ctx.dataPath, spec, sandboxAlive, (m) => { step = m; }));
+};
+/** joinHere, then (for another project) waits until the sandbox has set it up. */
+export const readyHere = async (ctx, status) => {
+    const joined = await joinHere(ctx, status);
+    for (const note of joined.notes)
+        console.log(note);
+    await provisionJoined(ctx, joined);
+    return joined;
+};

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

@@ -0,0 +1,14 @@
+import { type Context } from './context.js';
+interface Row {
+    folder: string;
+    here: boolean;
+    known: boolean;
+    root: string | null;
+    excluded: boolean;
+    mappedAtStart: boolean;
+    running: string | null;
+}
+/** Every project worth listing: known ones, the running sandbox's, and this folder. */
+export declare const projectRows: (ctx: Context) => Row[];
+export declare const projects: (ctx: Context) => Promise<number>;
+export {};

package/dist/cli/commands/projects.js

@@ -0,0 +1,146 @@
+// `sandbox projects`: which projects a sandbox can open without a restart. Project roots (whole folders of projects),
+// the projects this tool has started before, and projects.all / projects.exclude. Changes to what is mapped take
+// effect at the next start; a project you start while a sandbox runs joins it when it can (projects.ts in host/).
+import path from 'node:path';
+import { checkbox } from '@inquirer/prompts';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { dirExists, expandPath, fail, isRootPath } from '../../core/util.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { forgetProject, projectMapper, readKnown, readRegistry, rememberProject } from '../../host/projects.js';
+import { isWithin } from '../../shared/projects.js';
+import { c, pageSizeFor, shortenMiddle, termWidth } from '../colors.js';
+import { printJson, table } from './context.js';
+import { hereDir } from './project.js';
+import { addToList, removeFromList, setSetting } from './user-config.js';
+const settings = (ctx) => {
+    const p = ctx.loaded.config.projects;
+    const expand = (list) => list.map((x) => expandPath(x, 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. */
+export const projectRows = (ctx) => {
+    const s = settings(ctx);
+    const registry = isSandboxRunning() ? readRegistry(ctx.storageRoot) : null;
+    const here = hereDir(ctx);
+    const folders = [...readKnown(ctx.storageRoot).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: readKnown(ctx.storageRoot).some((k) => k.host.toLowerCase() === folder.toLowerCase()), root, excluded,
+            mappedAtStart: root !== null || (s.all && !excluded && dirExists(folder)), running: inSandbox ? inSandbox.name + ' (' + inSandbox.mechanism + ')' : null,
+        };
+    });
+};
+const NEXT_START = 'This changes what is mapped from the next start.';
+const runningNote = () => (isSandboxRunning() ? ' The running sandbox keeps what it has; start a project in it (sandbox claude there) and it joins without a restart when it can, or you are offered one.' : '');
+/** A folder for roots: it holds projects, so it must pass the same checks as a workspace and must not be a drive. */
+const checkFolder = (ctx, 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, ctx.packageRoot, ctx.storageRoot);
+    assertSafeMapping(dir, ctx.packageRoot, ctx.storageRoot);
+    return dir;
+};
+const list = (ctx) => {
+    const rows = projectRows(ctx);
+    const s = settings(ctx);
+    if (printJson(ctx, { all: s.all, roots: s.roots, exclude: s.exclude, projects: rows }))
+        return 0;
+    console.log(c.bold('projects.all') + ': ' + (s.all ? 'on (every project below is mapped at every start, except excluded ones)' : 'off') + c.dim('   sandbox projects all on|off'));
+    console.log(c.bold('Roots') + ': ' + (s.roots.length ? s.roots.join(', ') : c.dim('none (sandbox projects roots add <folder>)')));
+    if (!rows.length) {
+        console.log('No projects yet: start one with sandbox claude in its folder.');
+        return 0;
+    }
+    const width = Math.max(20, termWidth() - 46);
+    table([['', 'FOLDER', 'AT START', 'RUNNING SANDBOX'], ...rows.map((r) => [
+            r.here ? '*' : '', shortenMiddle(r.folder, width), r.root ? 'root' : r.excluded ? 'excluded' : r.mappedAtStart ? 'mapped' : '-', r.running ?? '-',
+        ])]);
+    console.log(c.dim('* = this folder.  Choose with: sandbox projects choose'));
+    return 0;
+};
+/** Ticks the projects mapped at every start (turns projects.all on when any is ticked); the rest are excluded. */
+const choose = async (ctx) => {
+    const rows = projectRows(ctx).filter((r) => !r.root);
+    if (!rows.length) {
+        console.log('No projects to choose from yet (projects in a root are always mapped with it). Start one with sandbox claude in its folder.');
+        return 0;
+    }
+    if (!process.stdin.isTTY)
+        fail('sandbox projects choose needs an interactive terminal.', 'Use sandbox projects include|exclude <folder> instead.');
+    const s = settings(ctx);
+    const picked = await checkbox({
+        message: 'Projects mapped at every start, so they open without a restart (every agent in the sandbox can see them):',
+        pageSize: pageSizeFor(rows.length),
+        choices: rows.map((r) => ({ value: r.folder, name: shortenMiddle(r.folder, termWidth() - 12) + (r.here ? c.dim('  (this folder)') : ''), checked: s.all && !r.excluded })),
+    });
+    const exclude = rows.filter((r) => !picked.includes(r.folder)).map((r) => r.folder);
+    setSetting(ctx, ['projects', 'exclude'], [...s.exclude.filter((e) => !rows.some((r) => r.folder.toLowerCase() === e.toLowerCase())), ...exclude]);
+    setSetting(ctx, ['projects', 'all'], picked.length > 0);
+    console.log(picked.length + ' project(s) mapped at every start, ' + exclude.length + ' excluded. ' + NEXT_START + runningNote());
+    return 0;
+};
+export const projects = async (ctx) => {
+    const [action = 'list', value, folder] = ctx.options.positionals;
+    switch (action) {
+        case 'list': return list(ctx);
+        case 'choose': return choose(ctx);
+        case 'add': {
+            const dir = checkFolder(ctx, value, 'a project');
+            rememberProject(ctx.storageRoot, dir);
+            console.log('Added ' + dir + ' to your projects.' + (settings(ctx).all ? ' ' + NEXT_START : ' It is mapped at every start once projects.all is on (sandbox projects all on).'));
+            return 0;
+        }
+        case 'remove': {
+            const dir = path.resolve(value);
+            const forgot = forgetProject(ctx.storageRoot, dir);
+            // The running sandbox forgets it too (its folder stays visible until the sandbox stops, if it was mapped).
+            const registered = isSandboxRunning() ? readRegistry(ctx.storageRoot)?.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);
+            console.log(forgot || registered ? 'Removed ' + dir + ' from your projects (nothing in the folder was touched).' : dir + ' was not in your projects.');
+            return 0;
+        }
+        case 'include':
+        case 'exclude': {
+            const dir = path.resolve(value);
+            const changed = action === 'exclude' ? addToList(ctx, ['projects', 'exclude'], dir) : removeFromList(ctx, ['projects', 'exclude'], dir);
+            if (action === 'include')
+                rememberProject(ctx.storageRoot, dir);
+            console.log((changed ? (action === 'exclude' ? 'Excluded ' : 'Included ') + dir + '. ' + NEXT_START : 'Nothing changed.') + (action === 'include' && !settings(ctx).all ? ' projects.all is off: sandbox projects all on maps your projects at every start.' : '') + (changed ? runningNote() : ''));
+            return 0;
+        }
+        case 'all': {
+            if (value === undefined) {
+                console.log('projects.all is ' + (settings(ctx).all ? 'on' : 'off') + '.');
+                return 0;
+            }
+            setSetting(ctx, ['projects', 'all'], value === 'on');
+            console.log('projects.all is ' + value + '. ' + NEXT_START + (value === 'on' ? ' Every agent in the sandbox can then see all of those projects.' : '') + runningNote());
+            return 0;
+        }
+        case 'roots': {
+            if (!value || value === 'list') {
+                const roots = settings(ctx).roots;
+                console.log(roots.length ? roots.join('\n') : 'No project roots. Add one: sandbox projects roots add <folder>');
+                return 0;
+            }
+            if (value === 'add') {
+                const dir = checkFolder(ctx, folder, 'a project root');
+                const added = addToList(ctx, ['projects', 'roots'], dir);
+                console.log(added ? 'Added the project root ' + dir + ': every project in it (also new ones) opens without a restart. Every agent in the sandbox can see all of them. ' + NEXT_START + runningNote() : dir + ' is a root already.');
+                return 0;
+            }
+            const dir = path.resolve(folder);
+            console.log(removeFromList(ctx, ['projects', 'roots'], dir) ? 'Removed the project root ' + dir + '. ' + NEXT_START : dir + ' was not a root.');
+            return 0;
+        }
+        default: return fail('Unknown projects action "' + action + '".');
+    }
+};

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

@@ -0,0 +1,2 @@
+import { type RepairCheck } from './types.js';
+export declare const CHECKS: RepairCheck[];

package/dist/cli/commands/{repair.js → repair/checks.js}

@@ -1,131 +1,22 @@
-// `sandbox repair`: finds and fixes common problems. Each check is a small function in CHECKS; it either confirms
-// all is well (OK), fixes the problem itself (FIXED), or says what you need to do (NEEDS YOU). Nothing under the data
-// folder is followed through a link, and toolchain/run-state fixes wait until no sandbox is running.
+// The repair checks, in the order they run. Each either confirms all is well, fixes the problem itself, or says what
+// you need to do. Nothing under the data folder is followed through a link.
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import _ from 'lodash';
-import { z } from 'zod';
-import { DEFAULTS, loadConfig, userDir } from '../../core/config.js';
-import { assertNoLinks, dirExists, errMsg, expandPath, fileExists, isLink, isWin, removeLink, UserError } from '../../core/util.js';
-import { resetRunDir } from '../../host/channel.js';
-import { isSandboxRunning, sandboxFeatureInstalled } from '../../host/platform.js';
-import { listSessions, runPaths, scanRequests } from '../../shared/rundir.js';
-import { createContext, printJson, table } from './context.js';
-import { humanBytes, removeTree } from './data.js';
-const GB = 1024 ** 3;
-const LABEL = { ok: 'OK', fixed: 'FIXED', 'needs-you': 'NEEDS YOU', warn: 'WARNING', skipped: 'SKIPPED' };
-const ok = (detail) => ({ status: 'ok', detail });
-const whileRunning = { status: 'skipped', detail: 'a sandbox is running and may be using it; run repair again once it is closed' };
+import { GB, freeBytesAt, humanBytes } from '../../../core/disk.js';
+import { assertTestWritable } from '../../../shared/test-guard.js';
+import { assertNoLinks, fileExists, isLink, isWin, removeLink } from '../../../core/util.js';
+import { resetRunDir } from '../../../host/channel.js';
+import { sandboxFeatureInstalled } from '../../../host/platform.js';
+import { listSessions, runPaths, scanRequests } from '../../../shared/rundir.js';
+import { removeTree } from '../data/remove.js';
+import { deadPidFiles, findHalfInstalled, findLinks, findStagingLeftovers, globalPackages, resolvedVersionsValid } from './finders.js';
+import { ok, whileRunning } from './types.js';
 const rel = (root, p) => path.relative(root, p) || '.';
-// ---- pure helpers (exported for tests) ----
-/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
-export const findStagingLeftovers = (toolsDir) => {
-    const isStaging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
-    const realChildren = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((n) => path.join(dir, n)) : []);
-    return realChildren(toolsDir).flatMap((p) => (isStaging(path.basename(p)) ? [p] : isLink(p) ? [] : realChildren(p).filter((c) => isStaging(path.basename(c)))));
-};
-export const TOOL_RULES = [
-    { folder: 'nvm', exe: ['nvm.exe'] },
-    { folder: 'nvm', exe: ['node.exe'], versions: true, match: /^v\d+\.\d+\.\d+$/ },
-    { folder: 'node', exe: ['node.exe'] },
-    { folder: 'git', exe: ['bin', 'bash.exe'] },
-    { folder: 'dotnet', exe: ['dotnet.exe'] },
-    { folder: 'go', exe: ['bin', 'go.exe'], versions: true },
-    { folder: 'java', exe: ['bin', 'java.exe'], versions: true },
-    { folder: 'python', exe: ['python.exe'], versions: true },
-];
-/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
-export const findHalfInstalled = (toolsDir, rules = TOOL_RULES) => {
-    const realDir = (p) => dirExists(p) && !isLink(p);
-    const staging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
-    return rules.flatMap((rule) => {
-        const base = path.join(toolsDir, rule.folder);
-        if (!realDir(base))
-            return [];
-        const folders = rule.versions
-            ? fs.readdirSync(base).filter((n) => !staging(n) && (!rule.match || rule.match.test(n))).map((n) => path.join(base, n)).filter(realDir)
-            : [base];
-        return folders.filter((f) => !fileExists(path.join(f, ...rule.exe))).map((f) => ({ path: f, missing: path.join(...rule.exe) }));
-    });
-};
-/**
- * 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 const findLinks = (root) => {
-    if (isLink(root))
-        return [root];
-    const real = (p) => { try {
-        return fs.realpathSync.native(p).toLowerCase();
-    }
-    catch {
-        return '';
-    } };
-    const top = real(root);
-    const inside = (p) => { const r = real(p); return r !== '' && (r === top || r.startsWith(top + path.sep)); };
-    const walk = (dir) => {
-        if (!inside(dir))
-            return [];
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return [];
-        }
-        return entries.flatMap((d) => {
-            const p = path.join(dir, d.name);
-            if (d.isSymbolicLink() || isLink(p))
-                return [p];
-            return d.isDirectory() ? walk(p) : [];
-        });
-    };
-    return dirExists(root) ? walk(root) : [];
-};
-const ResolvedVersions = z.record(z.string(), z.unknown());
-/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
-export const resolvedVersionsValid = (text) => {
-    try {
-        return ResolvedVersions.safeParse(JSON.parse(text.replace(/^/, ''))).success;
-    }
-    catch {
-        return false;
-    }
-};
-const NpmList = z.object({ dependencies: z.record(z.string(), z.unknown()).optional() });
-/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
-export const globalPackages = (json) => {
-    try {
-        return Object.keys(NpmList.parse(JSON.parse(json)).dependencies ?? {});
-    }
-    catch {
-        return [];
-    }
-};
-const Pid = z.coerce.number().int().positive();
-export const pidAlive = (pid) => { try {
-    process.kill(pid, 0);
-    return true;
-}
-catch (e) {
-    return e.code === 'EPERM';
-} };
-/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
-export const deadPidFiles = (runDir, alive = pidAlive) => (dirExists(runDir) ? fs.readdirSync(runDir) : [])
-    .filter((n) => /^watcher-.*\.pid$/i.test(n))
-    .map((n) => path.join(runDir, n))
-    .filter((f) => { try {
-    const pid = Pid.safeParse(fs.readFileSync(f, 'utf8').trim());
-    return !pid.success || !alive(pid.data);
-}
-catch {
-    return false;
-} });
-// ---- checks ----
 /** Fails (throws) unless every folder from the data folder to `p` is real. */
 const guard = (env, p) => assertNoLinks(path.dirname(env.dataPath), p);
-const CHECKS = [
+export const CHECKS = [
     {
         name: 'Config file',
         run: (env) => (env.configError
@@ -183,6 +74,7 @@ const CHECKS = [
                 return ok('clean.');
             if (env.running)
                 return ok('a sandbox is running; kept.');
+            assertTestWritable(file);
             fs.rmSync(file, { force: true });
             return { status: 'fixed', detail: 'removed the saved hidden-window list from a sandbox that is no longer running.' };
         },
@@ -193,8 +85,10 @@ const CHECKS = [
             const dead = deadPidFiles(path.join(env.storageRoot, 'run'));
             if (!dead.length)
                 return ok('no stale watcher records.');
-            for (const f of dead)
+            for (const f of dead) {
+                assertTestWritable(f);
                 fs.rmSync(f, { force: true });
+            }
             return { status: 'fixed', detail: 'removed ' + dead.length + ' record(s) of a history sync watcher that is no longer running (the next launch starts a new one).' };
         },
     },
@@ -241,6 +135,7 @@ const CHECKS = [
             }
             if (fs.statSync(file).size < 4 * 1024 * 1024 && resolvedVersionsValid(fs.readFileSync(file, 'utf8')))
                 return ok('valid.');
+            assertTestWritable(file);
             fs.rmSync(file, { force: true });
             return { status: 'fixed', detail: 'tools\\resolved-versions.json was damaged; removed it (versions are looked up again on the next start).' };
         },
@@ -264,69 +159,12 @@ const CHECKS = [
     {
         name: 'Free disk',
         run: (env) => {
-            let at = path.resolve(env.storageRoot);
-            while (!fs.existsSync(at) && path.dirname(at) !== at)
-                at = path.dirname(at);
-            let free;
-            try {
-                const s = fs.statfsSync(at);
-                free = s.bavail * s.bsize;
-            }
-            catch {
+            const free = freeBytesAt(env.storageRoot);
+            if (free === null)
                 return { status: 'skipped', detail: 'could not check the drive of ' + env.storageRoot };
-            }
             if (free >= 20 * GB)
                 return ok(humanBytes(free) + ' free.');
             return { status: 'warn', detail: humanBytes(free) + ' free on the drive of ' + env.storageRoot + (free < 5 * GB ? ': toolchains need several GB.' : ': getting low.') + ' See what is stored with: sandbox data, and free space with: sandbox data clean <target>' };
         },
     },
 ];
-/** Runs every check in order; a check that throws is reported, never stops the rest. */
-export const runChecks = (env, checks = CHECKS) => checks.map((check) => {
-    try {
-        return { name: check.name, ...check.run(env) };
-    }
-    catch (e) {
-        return { name: check.name, status: 'needs-you', detail: 'check failed: ' + errMsg(e) + (e instanceof UserError && e.fix ? ' ' + e.fix : '') };
-    }
-});
-export const repair = (ctx, configError = null) => {
-    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;
-        }
-    }
-    const results = runChecks(env);
-    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 const 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);
-};

package/dist/cli/commands/{repair.d.ts → repair/finders.d.ts}

@@ -1,24 +1,3 @@
-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[];
 /**
@@ -49,11 +28,3 @@ 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;

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

@@ -0,0 +1,108 @@
+// Pure finders the repair checks use (exported for tests): they look, they never change anything.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { dirExists, fileExists, isLink } from '../../../core/util.js';
+/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
+export const findStagingLeftovers = (toolsDir) => {
+    const isStaging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    const realChildren = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((n) => path.join(dir, n)) : []);
+    return realChildren(toolsDir).flatMap((p) => (isStaging(path.basename(p)) ? [p] : isLink(p) ? [] : realChildren(p).filter((c) => isStaging(path.basename(c)))));
+};
+export const TOOL_RULES = [
+    { folder: 'nvm', exe: ['nvm.exe'] },
+    { folder: 'nvm', exe: ['node.exe'], versions: true, match: /^v\d+\.\d+\.\d+$/ },
+    { folder: 'node', exe: ['node.exe'] },
+    { folder: 'git', exe: ['bin', 'bash.exe'] },
+    { folder: 'dotnet', exe: ['dotnet.exe'] },
+    { folder: 'go', exe: ['bin', 'go.exe'], versions: true },
+    { folder: 'java', exe: ['bin', 'java.exe'], versions: true },
+    { folder: 'python', exe: ['python.exe'], versions: true },
+];
+/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
+export const findHalfInstalled = (toolsDir, rules = TOOL_RULES) => {
+    const realDir = (p) => dirExists(p) && !isLink(p);
+    const staging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    return rules.flatMap((rule) => {
+        const base = path.join(toolsDir, rule.folder);
+        if (!realDir(base))
+            return [];
+        const folders = rule.versions
+            ? fs.readdirSync(base).filter((n) => !staging(n) && (!rule.match || rule.match.test(n))).map((n) => path.join(base, n)).filter(realDir)
+            : [base];
+        return folders.filter((f) => !fileExists(path.join(f, ...rule.exe))).map((f) => ({ path: f, missing: path.join(...rule.exe) }));
+    });
+};
+/**
+ * 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 const findLinks = (root) => {
+    if (isLink(root))
+        return [root];
+    const real = (p) => { try {
+        return fs.realpathSync.native(p).toLowerCase();
+    }
+    catch {
+        return '';
+    } };
+    const top = real(root);
+    const inside = (p) => { const r = real(p); return r !== '' && (r === top || r.startsWith(top + path.sep)); };
+    const walk = (dir) => {
+        if (!inside(dir))
+            return [];
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        return entries.flatMap((d) => {
+            const p = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(p))
+                return [p];
+            return d.isDirectory() ? walk(p) : [];
+        });
+    };
+    return dirExists(root) ? walk(root) : [];
+};
+const ResolvedVersions = z.record(z.string(), z.unknown());
+/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
+export const resolvedVersionsValid = (text) => {
+    try {
+        return ResolvedVersions.safeParse(JSON.parse(text.replace(/^/, ''))).success;
+    }
+    catch {
+        return false;
+    }
+};
+const NpmList = z.object({ dependencies: z.record(z.string(), z.unknown()).optional() });
+/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
+export const globalPackages = (json) => {
+    try {
+        return Object.keys(NpmList.parse(JSON.parse(json)).dependencies ?? {});
+    }
+    catch {
+        return [];
+    }
+};
+const Pid = z.coerce.number().int().positive();
+export const pidAlive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
+export const deadPidFiles = (runDir, alive = pidAlive) => (dirExists(runDir) ? fs.readdirSync(runDir) : [])
+    .filter((n) => /^watcher-.*\.pid$/i.test(n))
+    .map((n) => path.join(runDir, n))
+    .filter((f) => { try {
+    const pid = Pid.safeParse(fs.readFileSync(f, 'utf8').trim());
+    return !pid.success || !alive(pid.data);
+}
+catch {
+    return false;
+} });

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

@@ -0,0 +1,12 @@
+import { UserError } from '../../../core/util.js';
+import type { CliOptions } from '../../args.js';
+import { type Context } from '../context.js';
+import type { RepairCheck, RepairEnv, RepairResult } from './types.js';
+/** 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;