windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/storage/providers/types.d.ts

@@ -0,0 +1,33 @@
+import type { ResolvedMapping } from '../../../core/types.js';
+/** `folder`: a host folder shared in (it is also one of the plan's mappings). `disk`: an image the engine attaches. */
+export type StorageAttachment = {
+    readonly kind: 'folder';
+    readonly host: string;
+    readonly guest: string;
+    readonly readOnly: boolean;
+} | {
+    readonly kind: 'disk';
+    readonly image: string;
+    readonly guest: string;
+    readonly maxGb: number;
+};
+export interface DataSet {
+    readonly dataPath: string;
+    readonly guest: string;
+}
+export interface PreparedStorage {
+    readonly attachments: readonly StorageAttachment[];
+    /** The folder attachments as mappings, in the order they go in the launch. */
+    readonly mappings: readonly ResolvedMapping[];
+}
+export interface ProviderCheck {
+    readonly available: boolean;
+    readonly reasons: readonly string[];
+    readonly fixes: readonly string[];
+}
+export interface StorageProvider {
+    readonly id: 'folder' | 'vhdx-mounted' | 'vhdx-attached';
+    check(): Promise<ProviderCheck>;
+    prepare(dataSet: DataSet): Promise<PreparedStorage>;
+    release(): Promise<void>;
+}

package/dist/host/storage/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/storage/root.d.ts

@@ -0,0 +1,18 @@
+/** Where the data lived before 1.6: per user, in the profile. Still pinned in config.json when it was there. */
+export declare const OLD_DEFAULT_ROOT = "%LOCALAPPDATA%\\AgentSandbox";
+/** The old per-user default, expanded (null when LOCALAPPDATA is not set). */
+export declare function oldDefaultRoot(env?: NodeJS.ProcessEnv): string | null;
+/** The shared default, expanded: %ProgramData%\AgentSandbox\users\<you>. */
+export declare function sharedDefaultRoot(base?: string): string;
+/** The folder that holds one private storage folder per user. */
+export declare function usersFolder(env?: NodeJS.ProcessEnv): string;
+/** The per-user folder under the users folder that `root` is (or is inside), or null when it is elsewhere. */
+export declare function privateFolderOf(root: string, env?: NodeJS.ProcessEnv): string | null;
+/** A folder with something in it (a missing folder, a file or an empty folder holds no data). */
+export declare function holdsData(dir: string): boolean;
+/**
+ * Creates the storage root when it is missing. Under %ProgramData%\AgentSandbox\users the folder is made private
+ * before anything is written in it (the users folder itself is created as you when no all-users install made it). A
+ * root elsewhere is made private when this call creates it.
+ */
+export declare function ensureStorageRoot(root: string, protect: (dir: string) => void, env?: NodeJS.ProcessEnv): void;

package/dist/host/storage/root.js

@@ -0,0 +1,77 @@
+// The storage root (everything kept between sandboxes): where the old and the new default are, which folders may hold
+// saved data, and the one place that creates the root (private when it is under %ProgramData%\AgentSandbox\users).
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS, machineRoot } from '../../core/config/index.js';
+import { expandPath, fail, isInsideOrEqual, isLink } from '../../core/util/index.js';
+/** Where the data lived before 1.6: per user, in the profile. Still pinned in config.json when it was there. */
+export const OLD_DEFAULT_ROOT = '%LOCALAPPDATA%\\AgentSandbox';
+/** The old per-user default, expanded (null when LOCALAPPDATA is not set). */
+export function oldDefaultRoot(env = process.env) {
+    return env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, 'AgentSandbox') : null;
+}
+/** The shared default, expanded: %ProgramData%\AgentSandbox\users\<you>. */
+export function sharedDefaultRoot(base = process.cwd()) {
+    return expandPath(DEFAULTS.storage.root, base);
+}
+/** The folder that holds one private storage folder per user. */
+export function usersFolder(env = process.env) {
+    return path.join(machineRoot(env), 'users');
+}
+/** The per-user folder under the users folder that `root` is (or is inside), or null when it is elsewhere. */
+export function privateFolderOf(root, env = process.env) {
+    const users = usersFolder(env);
+    const resolved = path.resolve(root);
+    if (!isInsideOrEqual(users, resolved) || resolved.toLowerCase() === path.resolve(users).toLowerCase())
+        return null;
+    const first = path.relative(path.resolve(users), resolved).split(path.sep)[0];
+    return path.join(users, first);
+}
+/** A folder with something in it (a missing folder, a file or an empty folder holds no data). */
+export function holdsData(dir) {
+    try {
+        return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates the storage root when it is missing. Under %ProgramData%\AgentSandbox\users the folder is made private
+ * before anything is written in it (the users folder itself is created as you when no all-users install made it). A
+ * root elsewhere is made private when this call creates it.
+ */
+export function ensureStorageRoot(root, protect, env = process.env) {
+    const priv = privateFolderOf(root, env);
+    if (fs.existsSync(root)) {
+        // Made by hand and still empty: private before anything lands in it.
+        if (priv && !holdsData(root))
+            protect(priv);
+        return;
+    }
+    if (!priv) {
+        // A root of your own choosing is made private too, but only when this call creates it (never an existing folder,
+        // so a tree that already holds files is not walked) and never a drive root.
+        const created = fs.mkdirSync(root, { recursive: true });
+        if (created && path.dirname(path.resolve(root)) !== path.resolve(root)) {
+            try {
+                protect(root);
+            }
+            catch {
+                // Drives without permissions (FAT, some network shares) cannot be made private: the folder is still used.
+            }
+        }
+        return;
+    }
+    fs.mkdirSync(path.dirname(priv), { recursive: true });
+    if (isLink(path.dirname(priv)))
+        fail('The folder ' + path.dirname(priv) + ' is a link.', 'Remove the link first.');
+    fs.mkdirSync(priv, { recursive: true });
+    try {
+        protect(priv);
+    }
+    catch (e) {
+        fail('Could not make ' + priv + ' private: ' + (e instanceof Error ? e.message : String(e)), 'Run sandbox storage move <folder> to keep your data somewhere else, or report this.');
+    }
+    fs.mkdirSync(root, { recursive: true });
+}

package/dist/host/tools/conpty.js

@@ -3,12 +3,13 @@ import path from 'node:path';
 import { downloader, extractArchive, fetchJson, moveIntoPlace, stagingFolder } from '../../shared/download/index.js';
 import { safeRemove } from '../../shared/io/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
 import { z } from 'zod';
 import { assertNoLinks, errMsg, fileExists } from '../../core/util/index.js';
 // ---- conpty.dll -----------------------------------------------------------------------------------------------------
 /** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
 export function conptyDir(dataPath) {
-    return path.join(dataPath, 'tools', 'conpty');
+    return path.join(hostDataFolder(dataPath, 'tools'), 'conpty');
 }
 const NUGET_CONPTY = 'https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/';
 const NugetVersionsSchema = z.object({ versions: z.array(z.string()) });
@@ -22,7 +23,7 @@ const NugetCatalogSchema = z.object({ packageHash: z.string(), packageHashAlgori
 export async function ensureConpty(dataPath, refresh) {
     const dir = conptyDir(dataPath);
     assertTestWritable(dir);
-    assertNoLinks(dataPath, dir);
+    assertNoLinks(hostDataRoot(dataPath), dir);
     if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')) && !refresh)
         return 'cached';
     const arch = process.arch === 'arm64' ? 'arm64' : 'x64';

package/dist/host/tools/windows-terminal.d.ts

@@ -17,6 +17,8 @@ declare const TerminalSettingsSchema: z.ZodObject<{
  * survive turning pwsh off and on). Pure: returns null when nothing changes.
  */
 export declare function withPwshProfile(settings: z.output<typeof TerminalSettingsSchema>, visible: boolean): z.output<typeof TerminalSettingsSchema> | null;
+/** settings.json that makes new tabs read the current environment; null when it already does. Pure. */
+export declare function withReloadEnvironment(settings: z.output<typeof TerminalSettingsSchema>): z.output<typeof TerminalSettingsSchema> | null;
 /**
  * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
  * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,

package/dist/host/tools/windows-terminal.js

@@ -3,12 +3,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { downloader, githubAsset } from '../../shared/download/index.js';
-import { safeRemove } from '../../shared/io/index.js';
+import { safeRemove, writeFileAtomic } from '../../shared/io/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
+import { applyEdits, modify } from 'jsonc-parser';
 import { z } from 'zod';
 import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../../core/util/index.js';
 export function terminalDir(dataPath) {
-    return path.join(dataPath, 'tools', 'terminal');
+    return path.join(hostDataFolder(dataPath, 'tools'), 'terminal');
 }
 export function terminalExe(dataPath) {
     return path.join(terminalDir(dataPath), 'WindowsTerminal.exe');
@@ -66,6 +68,13 @@ export function withPwshProfile(settings, visible) {
         list[at] = { ...list[at], hidden: !visible };
     return { ...settings, profiles: { ...profiles, list } };
 }
+/** settings.json that makes new tabs read the current environment; null when it already does. Pure. */
+export function withReloadEnvironment(settings) {
+    const compatibility = settings.compatibility;
+    if (compatibility?.reloadEnvironmentVariables === true)
+        return null;
+    return { ...settings, compatibility: { ...compatibility, reloadEnvironmentVariables: true } };
+}
 /**
  * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
  * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
@@ -74,13 +83,14 @@ export function withPwshProfile(settings, visible) {
 export function syncPwshProfile(dataPath, allowed) {
     const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
     assertTestWritable(file);
-    assertNoLinks(dataPath, file);
+    assertNoLinks(hostDataRoot(dataPath), file);
     if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
         return;
-    const visible = allowed && fileExists(path.join(dataPath, 'tools', 'pwsh', 'pwsh.exe'));
+    const visible = allowed && fileExists(path.join(hostDataFolder(dataPath, 'tools'), 'pwsh', 'pwsh.exe'));
     let parsed;
+    const text = fs.readFileSync(file, 'utf8');
     try {
-        const result = TerminalSettingsSchema.safeParse(parseJsonc(fs.readFileSync(file, 'utf8'), file));
+        const result = TerminalSettingsSchema.safeParse(parseJsonc(text, file));
         if (!result.success)
             return;
         parsed = result.data;
@@ -88,9 +98,18 @@ export function syncPwshProfile(dataPath, allowed) {
     catch {
         return;
     }
-    const next = withPwshProfile(parsed, visible);
-    if (next)
-        writeJson(file, next);
+    const withProfile = withPwshProfile(parsed, visible);
+    if (withProfile) {
+        writeJson(file, withReloadEnvironment(withProfile) ?? withProfile);
+        return;
+    }
+    // Only the reload switch is missing: set that one value in the text, so comments and the layout stay.
+    if (withReloadEnvironment(parsed)) {
+        const edits = modify(text, ['compatibility', 'reloadEnvironmentVariables'], true, {
+            formattingOptions: { insertSpaces: true, tabSize: 4 },
+        });
+        writeFileAtomic(file, applyEdits(text, edits));
+    }
 }
 export async function ensureTerminal(dataPath, refresh, options = {}) {
     const result = await installTerminal(dataPath, refresh);
@@ -112,9 +131,9 @@ const installTerminal = async (dataPath, refresh) => {
     const settings = path.join(dir, 'settings');
     // downloader.archive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also
     // when the download fails). One still parked from an interrupted earlier run is the one to keep.
-    const parked = path.join(dataPath, 'tools', 'terminal-settings.parked');
-    assertNoLinks(dataPath, settings);
-    assertNoLinks(dataPath, parked);
+    const parked = path.join(hostDataFolder(dataPath, 'tools'), 'terminal-settings.parked');
+    assertNoLinks(hostDataRoot(dataPath), settings);
+    assertNoLinks(hostDataRoot(dataPath), parked);
     if (fileExists(exe) && !refresh)
         return { exe, message: 'cached' };
     try {
@@ -140,7 +159,7 @@ const installTerminal = async (dataPath, refresh) => {
                 fs.renameSync(parked, settings);
             }
             const settingsFile = path.join(settings, 'settings.json');
-            assertNoLinks(dataPath, settingsFile);
+            assertNoLinks(hostDataRoot(dataPath), settingsFile);
             if (fileExists(path.join(dir, '.portable')) && !fs.existsSync(settingsFile))
                 writeJson(settingsFile, SETTINGS);
         }

package/dist/host/update/index.d.ts

@@ -1,6 +1,6 @@
 export { type ReleaseInfo, type ReleaseSource, GithubReleases, FolderFeed, RELEASE_REPO } from './release-source.js';
 export { type SkipReason, type UpdateDecision, type DecisionInput, decideUpdate, isTooSoon } from './decision.js';
 export { UpdateStateFile, type UpdateState } from './update-state.js';
-export { updateNotice, type UpdateNotice } from './notice.js';
+export { updateNotice, autoOffText, type UpdateNotice } from './notice.js';
 export { UpdateLock } from './update-lock.js';
 export { Updater, type UpdateResult, type RunOptions, type UpdaterOptions } from './updater.js';

package/dist/host/update/index.js

@@ -1,6 +1,6 @@
 export { GithubReleases, FolderFeed, RELEASE_REPO } from './release-source.js';
 export { decideUpdate, isTooSoon } from './decision.js';
 export { UpdateStateFile } from './update-state.js';
-export { updateNotice } from './notice.js';
+export { updateNotice, autoOffText } from './notice.js';
 export { UpdateLock } from './update-lock.js';
 export { Updater } from './updater.js';

package/dist/host/update/notice.d.ts

@@ -4,6 +4,8 @@ export interface UpdateNotice {
     /** Identifies the outcome: the same key is never shown to the same user twice. */
     key: string;
 }
+/** What a user is told when a failed install was undone and automatic updates were switched off. */
+export declare function autoOffText(failedVersion: string, current: string): string;
 /**
  * `current` is the version that runs now. A success is announced while it is still the current version; a blocked
  * failure while the current version is older than the one that failed. When both exist, the newer outcome wins.

package/dist/host/update/notice.js

@@ -1,6 +1,14 @@
 // The one-line notice a user sees on their next command after an update ran without them: it worked, or it failed and
 // the old version stayed. Each user sees each outcome once (the caller remembers the key). Pure.
 import { compareVersions } from '../install/layout.js';
+/** What a user is told when a failed install was undone and automatic updates were switched off. */
+export function autoOffText(failedVersion, current) {
+    return ('The update to ' +
+        failedVersion +
+        ' failed and was undone (you are on ' +
+        current +
+        '). Automatic updates are off; turn them back on in Maintenance > Updates or with sandbox update --auto on.');
+}
 /**
  * `current` is the version that runs now. A success is announced while it is still the current version; a blocked
  * failure while the current version is older than the one that failed. When both exist, the newer outcome wins.
@@ -10,8 +18,12 @@ export function updateNotice(state, current, seenKey) {
     const done = state.lastResult;
     if (done?.ok && done.version === current)
         candidates.push({ at: done.at, notice: { key: 'ok@' + done.at, text: 'Updated to ' + done.version + '.' } });
+    const off = state.autoOff;
+    if (off && compareVersions(off.version, current) > 0)
+        candidates.push({ at: off.at, notice: { key: 'auto-off@' + off.at, text: autoOffText(off.version, current) } });
     const failed = state.failed;
-    if (failed && compareVersions(failed.version, current) > 0)
+    // The automatic-updates-off notice already tells about this failure.
+    if (failed && compareVersions(failed.version, current) > 0 && off?.version !== failed.version)
         candidates.push({
             at: failed.at,
             notice: {

package/dist/host/update/update-state.d.ts

@@ -7,6 +7,12 @@ declare const StateSchema: z.ZodObject<{
         at: z.ZodString;
         reason: z.ZodString;
     }, z.core.$strip>>;
+    autoOff: z.ZodOptional<z.ZodObject<{
+        version: z.ZodString;
+        current: z.ZodString;
+        reason: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>>;
     lastResult: z.ZodOptional<z.ZodObject<{
         version: z.ZodString;
         ok: z.ZodBoolean;

package/dist/host/update/update-state.js

@@ -7,6 +7,8 @@ const StateSchema = z.object({
     lastCheck: z.string().optional(),
     previous: z.string().optional(),
     failed: z.object({ version: z.string(), at: z.string(), reason: z.string() }).optional(),
+    /** Why automatic updates were switched off: `version` failed to install and `current` was put back. */
+    autoOff: z.object({ version: z.string(), current: z.string(), reason: z.string(), at: z.string() }).optional(),
     lastResult: z.object({ version: z.string(), ok: z.boolean(), at: z.string() }).optional(),
 });
 export class UpdateStateFile {

package/dist/host/update/updater.d.ts

@@ -7,6 +7,10 @@ export interface UpdaterOptions {
     /** How long to wait between two looks at GitHub (not for `force`). */
     minHoursBetweenChecks?: number;
     downloader?: Downloader;
+    /** The scheduled task of an all-users install: removed when a failed install turns automatic updates off. */
+    task?: {
+        remove(): void;
+    } | null;
 }
 export interface RunOptions {
     /** A sandbox runs on this PC: its files are in use, so nothing is installed. */
@@ -29,6 +33,10 @@ export type UpdateResult = {
     version: string;
     reason: string;
     blocked: boolean;
+    /** The previous version is active again (pointers and shims), or was never left. */
+    rolledBack: boolean;
+    /** This failure switched automatic updates off (they were on). */
+    autoUpdateOff: boolean;
 };
 export declare class Updater {
     private readonly layout;
@@ -37,12 +45,23 @@ export declare class Updater {
     private readonly now;
     private readonly minHours;
     private readonly downloader;
+    private readonly task;
     constructor(layout: InstallLayout, source?: ReleaseSource, options?: UpdaterOptions);
     /** Looks for a newer release (unless the time gate says not yet) and installs it if it is verified. */
     run(options: RunOptions): Promise<UpdateResult>;
     /** Points the shims back at the version the last successful update replaced. Returns that version. */
     rollback(): string;
     private install;
+    /** The commands a version's package.json declares, or null when it cannot be read. */
+    private binsOf;
+    /** Puts the previous version's pointers and shims back and drops shims only the new one had. False: it failed. */
+    private restore;
+    /**
+     * Switches automatic updates off in install.json (the scheduled task of an all-users install does nothing without
+     * it) and removes that task when this process may; a failure to remove it is not an error. Remembers why, for the
+     * notice. True when automatic updates were on.
+     */
+    private turnAutoUpdateOff;
     /** A release tarball: a local feed file is copied, GitHub is downloaded; either way the sha256 must match. */
     private download;
     /** The extracted package must be this package, at this version. Returns its commands. */

package/dist/host/update/updater.js

@@ -1,7 +1,7 @@
 // Installs a newer release next to the active one, checks that it starts (directly and through the shim), and only then
-// moves the pointers to it. Any failure leaves the active version as it was and deletes what was made. A fault of the
-// release itself (BadRelease) records the version as failed: it is not tried again until a newer one exists. Anything
-// else (the network, a locked file) is retried by the next check. A rollback moves the pointers back.
+// moves the pointers to it. Any failure puts the previous version back (pointers and shims) and deletes what was made.
+// A fault of the release itself (BadRelease) records the version as failed: it is not tried again until a newer one
+// exists. A failed install also turns automatic updates off (`turnAutoUpdateOff`). A rollback moves the pointers back.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -14,6 +14,7 @@ import { SYSTEM } from '../../shared/system.js';
 import { safeRemove } from '../../shared/io/index.js';
 import { testWriteRefusal } from '../../shared/test-guard.js';
 import { refuseInSelfTest } from '../test-guard.js';
+import { InstallRecordFile } from '../install/install-record.js';
 import { readBins, writeShims } from '../install/shims.js';
 import { decideUpdate } from './decision.js';
 import { GithubReleases } from './release-source.js';
@@ -38,6 +39,7 @@ export class Updater {
     now;
     minHours;
     downloader;
+    task;
     constructor(layout, source = new GithubReleases(), options = {}) {
         this.layout = layout;
         this.source = source;
@@ -45,6 +47,7 @@ export class Updater {
         this.now = options.now ?? (() => new Date());
         this.minHours = options.minHoursBetweenChecks ?? 24;
         this.downloader = options.downloader ?? new Downloader();
+        this.task = options.task ?? null;
     }
     /** Looks for a newer release (unless the time gate says not yet) and installs it if it is verified. */
     async run(options) {
@@ -78,6 +81,10 @@ export class Updater {
             fail('There is no earlier version to go back to.', 'Only a version an update replaced can be restored.');
         if (!this.layout.installedVersions().includes(target))
             fail(target + ' is no longer installed.', 'Install it again with the installer.');
+        // The shims of the target first (it may have other commands), then the pointers.
+        const bins = this.binsOf(target);
+        if (bins)
+            writeShims(this.layout, bins);
         this.layout.setActive(target, node);
         // The version we leave is now the one a second rollback returns to.
         this.state.update((s) => ({ ...s, previous: current }));
@@ -87,32 +94,42 @@ export class Updater {
         const version = release.version;
         const archive = path.join(this.layout.root, 'staging', version + '.tgz');
         const work = this.layout.versionDir(version) + '.staging';
-        let activated = false;
+        const previousBins = this.binsOf(current);
+        let downloaded = false;
+        let shimsWritten = false;
+        let pointersMoved = false;
+        let newBins = {};
         try {
             await this.download(release, archive);
+            downloaded = true;
             safeRemove(work, this.layout.versionsDir);
             await extractArchive(archive, work).catch((e) => {
                 throw new BadRelease('The release archive could not be unpacked: ' + errMsg(e));
             });
-            const bins = this.checkPackage(work, version);
+            newBins = this.checkPackage(work, version);
             moveIntoPlace(work, this.layout.versionDir(version));
-            writeShims(this.layout, bins);
+            shimsWritten = true;
+            writeShims(this.layout, newBins);
             this.checkEntry(version, node);
+            pointersMoved = true;
             this.layout.setActive(version, node);
-            activated = true;
             this.checkShim(version);
         }
         catch (e) {
             const reason = errMsg(e);
-            if (activated)
-                this.layout.setActive(current, node);
+            const changed = pointersMoved || shimsWritten;
+            const rolledBack = changed ? this.restore(current, node, previousBins, newBins, pointersMoved) : true;
             this.discard(work, version);
             const blocked = e instanceof BadRelease;
             if (blocked)
                 this.recordFailure(version, reason);
             else
                 this.recordAttempt(version, false);
-            return { kind: 'failed', version, reason, blocked };
+            // A plain network error before anything arrived changed nothing and says nothing about this release: the next
+            // check tries again. Every other failure is a failure of the install itself, so the machine must stop trying
+            // by itself until the user turns updates back on.
+            const autoUpdateOff = blocked || downloaded ? this.turnAutoUpdateOff(version, current, reason) : false;
+            return { kind: 'failed', version, reason, blocked, rolledBack, autoUpdateOff };
         }
         finally {
             try {
@@ -125,6 +142,65 @@ export class Updater {
         this.finish(version, current);
         return { kind: 'installed', version, previous: current };
     }
+    /** The commands a version's package.json declares, or null when it cannot be read. */
+    binsOf(version) {
+        try {
+            return readBins(JSON.parse(fs.readFileSync(path.join(this.layout.packageDir(version), 'package.json'), 'utf8')));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Puts the previous version's pointers and shims back and drops shims only the new one had. False: it failed. */
+    restore(current, node, previousBins, newBins, pointersMoved) {
+        let ok = true;
+        try {
+            if (pointersMoved)
+                this.layout.setActive(current, node);
+        }
+        catch {
+            ok = false;
+        }
+        try {
+            if (previousBins) {
+                writeShims(this.layout, previousBins);
+                for (const name of Object.keys(newBins))
+                    if (!(name in previousBins))
+                        for (const file of [name + '.cmd', name])
+                            fs.rmSync(path.join(this.layout.binDir, file), { force: true });
+            }
+        }
+        catch {
+            ok = false;
+        }
+        return ok;
+    }
+    /**
+     * Switches automatic updates off in install.json (the scheduled task of an all-users install does nothing without
+     * it) and removes that task when this process may; a failure to remove it is not an error. Remembers why, for the
+     * notice. True when automatic updates were on.
+     */
+    turnAutoUpdateOff(version, current, reason) {
+        const record = new InstallRecordFile(this.layout.root);
+        const wasOn = record.read()?.autoUpdate === true;
+        try {
+            record.setAutoUpdate(false);
+        }
+        catch {
+            // The record is unwritable: a blocked version is still not retried, so the failure does not repeat.
+        }
+        try {
+            this.task?.remove();
+        }
+        catch {
+            // Needs admin: the task runs, sees autoUpdate false in install.json and does nothing.
+        }
+        if (wasOn) {
+            const at = this.now().toISOString();
+            this.state.update((s) => ({ ...s, autoOff: { version, current, reason, at } }));
+        }
+        return wasOn;
+    }
     /** A release tarball: a local feed file is copied, GitHub is downloaded; either way the sha256 must match. */
     async download(release, archive) {
         fs.mkdirSync(path.dirname(archive), { recursive: true });
@@ -170,7 +246,7 @@ export class Updater {
     /** The version starts with the private Node and prints its own version number. */
     checkEntry(version, node) {
         const entry = path.join(this.layout.packageDir(version), ENTRY);
-        const run = spawnSync(this.layout.nodeExe(node), [entry, '--version'], {
+        const run = spawnSync(this.layout.nodeExe(node), [entry, '--version', '--short'], {
             encoding: 'utf8',
             windowsHide: true,
             timeout: CHECK_MS,
@@ -187,7 +263,7 @@ export class Updater {
     checkShim(version) {
         const shim = path.join(this.layout.binDir, 'sandbox.cmd');
         // /s takes off the outer quotes, so the quoted path (Program Files has a space) needs a pair around the whole line.
-        const run = spawnSync(SYSTEM.cmd(), ['/d', '/s', '/c', '""' + shim + '" --version"'], {
+        const run = spawnSync(SYSTEM.cmd(), ['/d', '/s', '/c', '""' + shim + '" --version --short"'], {
             encoding: 'utf8',
             windowsHide: true,
             windowsVerbatimArguments: true,

package/dist/host/vpn/index.d.ts

@@ -0,0 +1,4 @@
+export { VpnLogin, loginProblem, type LoginState, type VpnCredentials } from './login.js';
+export { fetchBounded, findCountry, nordProfile, recommendedServer, type Fetcher, type NordServer } from './nordvpn.js';
+export { prepareVpn, vpnNotes, wireguardFileProblem, type PrepareOptions } from './prepare.js';
+export { hostPublicIp, readVpnLine, vpnLine, type VpnLine } from './status.js';

package/dist/host/vpn/index.js

@@ -0,0 +1,4 @@
+export { VpnLogin, loginProblem } from './login.js';
+export { fetchBounded, findCountry, nordProfile, recommendedServer } from './nordvpn.js';
+export { prepareVpn, vpnNotes, wireguardFileProblem } from './prepare.js';
+export { hostPublicIp, readVpnLine, vpnLine } from './status.js';

package/dist/host/vpn/login.d.ts

@@ -0,0 +1,24 @@
+import { type VpnProvider } from '../../core/schema/index.js';
+import { SecretStore } from '../secrets/index.js';
+export interface VpnCredentials {
+    readonly username: string;
+    readonly password: string;
+}
+/** What `sandbox vpn status` may say about the login: never the values. */
+export type LoginState = 'none' | 'saved' | 'unreadable';
+/** The login must go on two lines of a file for OpenVPN, so no line breaks or other control characters. */
+export declare function loginProblem(c: VpnCredentials): string | null;
+export declare class VpnLogin {
+    private readonly storageRoot;
+    private readonly secrets;
+    constructor(storageRoot: string, secrets?: SecretStore);
+    private file;
+    /** Encrypts and saves the login (replacing an earlier one). */
+    save(provider: VpnProvider, login: VpnCredentials): void;
+    /** The login, decrypted. Only the launch calls this. */
+    read(provider: VpnProvider): VpnCredentials | null;
+    /** Whether a login is saved and can be decrypted by this Windows user (the values are never returned). */
+    state(provider: VpnProvider): LoginState;
+    savedAt(provider: VpnProvider): string | null;
+    remove(provider: VpnProvider): boolean;
+}