windows-development-sandbox 1.7.0 → 1.9.0

package/dist/host/storage/contained/disk-port.js

@@ -0,0 +1,122 @@
+// The only place that touches disks: mounting and dismounting go through native\scripts\mount-contained.ps1 and
+// dismount-contained.ps1 (run elevated through run-elevated.ps1: one Windows permission prompt each), looking goes
+// through check-contained.ps1 (no elevation). Everything above this file works against the `DiskPort` interface, so
+// the tests use a fake and the real scripts are only ever started on a PC.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+import { fail } from '../../../core/util/index.js';
+import { readValid } from '../../../shared/io/index.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { nativeFile, nativeScript } from '../../native.js';
+import { refuseInSelfTest } from '../../test-guard.js';
+const OutcomeSchema = z.object({
+    ok: z.boolean(),
+    message: z.string().max(4000),
+    created: z.boolean().optional(),
+    alreadyMounted: z.boolean().optional(),
+    notes: z
+        .union([z.array(z.string().max(2000)).max(100), z.string().max(2000)])
+        .optional()
+        .transform((v) => (v === undefined ? [] : typeof v === 'string' ? [v] : v)),
+});
+const RealitySchema = z.object({
+    imageExists: z.boolean(),
+    imageBytes: z.number().nonnegative(),
+    mountExists: z.boolean(),
+    mountIsMountPoint: z.boolean(),
+    attached: z.boolean().nullable(),
+});
+const MOUNT_TIMEOUT_MS = 10 * 60_000;
+const LOOK_TIMEOUT_MS = 30_000;
+export const spawnRunner = (file, args, timeoutMs) => new Promise((resolve) => {
+    const child = spawn(file, [...args], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', (d) => (stdout += d.toString('utf8')));
+    child.stderr.on('data', (d) => (stderr += d.toString('utf8')));
+    child.on('error', (e) => {
+        clearTimeout(timer);
+        resolve({ status: null, stdout, stderr: stderr + e.message });
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ status: code, stdout, stderr });
+    });
+});
+export class ScriptDiskPort {
+    run;
+    constructor(run = spawnRunner) {
+        this.run = run;
+    }
+    mount(request) {
+        const { paths } = request;
+        return this.elevated('mount-contained.ps1', {
+            set: paths.set,
+            storageRoot: paths.storageRoot,
+            image: paths.image,
+            mount: paths.mount,
+            userSid: request.userSid,
+            maxGb: request.maxGb,
+            create: request.create,
+        });
+    }
+    dismount(request) {
+        const { paths } = request;
+        return this.elevated('dismount-contained.ps1', {
+            set: paths.set,
+            storageRoot: paths.storageRoot,
+            image: paths.image,
+            mount: paths.mount,
+            userSid: request.userSid,
+        });
+    }
+    async reality(paths) {
+        const out = await this.run(SYSTEM.powershell(), nativeScript('check-contained.ps1', ['-Image', paths.image, '-Mount', paths.mount]), LOOK_TIMEOUT_MS);
+        const parsed = RealitySchema.safeParse(safeJson(out.stdout.trim()));
+        if (out.status !== 0 || !parsed.success)
+            fail('Could not look at the contained storage: ' + (out.stderr.trim() || out.stdout.trim() || 'no answer') + '.', 'Run sandbox doctor.');
+        return parsed.data;
+    }
+    /** One run of an elevated script: the request goes in a file in a private temp folder, the answer comes back so. */
+    async elevated(script, request) {
+        // A test hands in a fake runner; only the real one reaches a disk.
+        if (this.run === spawnRunner)
+            refuseInSelfTest('mount or dismount a disk image');
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-contained-'));
+        try {
+            const file = path.join(dir, 'request.json');
+            const text = JSON.stringify(request, null, 2);
+            fs.writeFileSync(file, text, 'utf8');
+            const sha = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+            const out = await this.run(SYSTEM.powershell(), nativeScript('run-elevated.ps1', ['-Script', nativeFile('scripts', script), '-Json', file, '-Sha256', sha]), MOUNT_TIMEOUT_MS);
+            const answer = readValid(OutcomeSchema, path.join(dir, 'result.json'));
+            if (!answer)
+                return fail(out.status === 1
+                    ? 'Windows did not give permission (the prompt was declined or closed).'
+                    : 'The disk image tool gave no answer' + (out.stderr.trim() ? ': ' + out.stderr.trim() : '.'), 'Run the command again and choose Yes in the Windows prompt.');
+            return {
+                ok: answer.ok,
+                message: answer.message,
+                created: answer.created ?? false,
+                alreadyMounted: answer.alreadyMounted ?? false,
+                notes: answer.notes,
+            };
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/host/storage/contained/index.d.ts

@@ -0,0 +1,9 @@
+export { CONTAINED_FOLDERS, containedMappings, containedPaths, setNameOf, type ContainedFolder } from './layout.js';
+export type { ContainedPaths } from './layout.js';
+export { ContainedStorage, type ContainedDeps, type HolderId, type ReleaseResult } from './contained-storage.js';
+export { ScriptDiskPort, spawnRunner, type DiskPort, type MountRequest, type ScriptOutcome } from './disk-port.js';
+export { containedAvailability, containedFacts, type ContainedFacts } from './check.js';
+export { hostDataFolder, hostDataRoot } from './resolve.js';
+export { writeContainedSetting } from './setting.js';
+export { addHolder, diagnose, markMounted, mountedSets, staleMountNote, pruneHolders, removeHolder, setStateOf, StateFile, type ContainedDiagnosis, type MountReality, } from './state.js';
+export { assertTargetsFree, planTransfer, runTransfer, type TransferPlan, type TransferResult } from './transfer.js';

package/dist/host/storage/contained/index.js

@@ -0,0 +1,8 @@
+export { CONTAINED_FOLDERS, containedMappings, containedPaths, setNameOf } from './layout.js';
+export { ContainedStorage } from './contained-storage.js';
+export { ScriptDiskPort, spawnRunner } from './disk-port.js';
+export { containedAvailability, containedFacts } from './check.js';
+export { hostDataFolder, hostDataRoot } from './resolve.js';
+export { writeContainedSetting } from './setting.js';
+export { addHolder, diagnose, markMounted, mountedSets, staleMountNote, pruneHolders, removeHolder, setStateOf, StateFile, } from './state.js';
+export { assertTargetsFree, planTransfer, runTransfer } from './transfer.js';

package/dist/host/storage/contained/layout.d.ts

@@ -0,0 +1,28 @@
+import type { ResolvedMapping } from '../../../core/types.js';
+/** The folders of the data set that move into the image. Everything else of the data set stays on the PC as it is. */
+export declare const CONTAINED_FOLDERS: readonly ["tools", "state", "logs", "databases", "cache"];
+export type ContainedFolder = (typeof CONTAINED_FOLDERS)[number];
+/** A data set name the scripts accept (same as the dataName setting, so every real name passes). */
+export declare const SET_NAME_RULE: RegExp;
+export interface ContainedPaths {
+    readonly storageRoot: string;
+    readonly set: string;
+    readonly imagesDir: string;
+    readonly mountsDir: string;
+    /** <storage>\images\<set>.vhdx */
+    readonly image: string;
+    /** <storage>\mounts\<set> */
+    readonly mount: string;
+    /** <storage>\mounts\state.json: which sets are mounted and who holds them (never inside an image). */
+    readonly stateFile: string;
+    readonly lockFile: string;
+}
+export declare function containedPaths(storageRoot: string, set: string): ContainedPaths;
+/** The data set's name: the last folder of <storage>\data\<name>. */
+export declare function setNameOf(dataPath: string): string;
+/**
+ * The mappings for a data set with contained storage: the run folder from the data folder on the PC, each contained
+ * folder from the mounted image. The guest sees C:\AgentData\run, \tools, \state, ... exactly as with one mapping of
+ * the whole folder.
+ */
+export declare function containedMappings(dataPath: string, mount: string, guestData: string): ResolvedMapping[];

package/dist/host/storage/contained/layout.js

@@ -0,0 +1,45 @@
+// Where contained storage keeps its files, and how the data set splits when it is on: `run\` stays the plain host
+// folder (the host reads it), the folders listed here live in the disk image and are mapped from inside its mount
+// folder to the very same guest paths the whole data folder had.
+import path from 'node:path';
+import { fail } from '../../../core/util/index.js';
+/** The folders of the data set that move into the image. Everything else of the data set stays on the PC as it is. */
+export const CONTAINED_FOLDERS = ['tools', 'state', 'logs', 'databases', 'cache'];
+/** A data set name the scripts accept (same as the dataName setting, so every real name passes). */
+export const SET_NAME_RULE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function containedPaths(storageRoot, set) {
+    if (!SET_NAME_RULE.test(set))
+        fail('The data set name "' + set + '" cannot be used for contained storage.', 'Use letters, numbers, - and _.');
+    const root = path.resolve(storageRoot);
+    const imagesDir = path.join(root, 'images');
+    const mountsDir = path.join(root, 'mounts');
+    return {
+        storageRoot: root,
+        set,
+        imagesDir,
+        mountsDir,
+        image: path.join(imagesDir, set + '.vhdx'),
+        mount: path.join(mountsDir, set),
+        stateFile: path.join(mountsDir, 'state.json'),
+        lockFile: path.join(mountsDir, 'state.lock'),
+    };
+}
+/** The data set's name: the last folder of <storage>\data\<name>. */
+export function setNameOf(dataPath) {
+    return path.basename(path.resolve(dataPath));
+}
+/**
+ * The mappings for a data set with contained storage: the run folder from the data folder on the PC, each contained
+ * folder from the mounted image. The guest sees C:\AgentData\run, \tools, \state, ... exactly as with one mapping of
+ * the whole folder.
+ */
+export function containedMappings(dataPath, mount, guestData) {
+    return [
+        { host: path.join(dataPath, 'run'), guest: guestData + '\\run', readOnly: false },
+        ...CONTAINED_FOLDERS.map((name) => ({
+            host: path.join(mount, name),
+            guest: guestData + '\\' + name,
+            readOnly: false,
+        })),
+    ];
+}

package/dist/host/storage/contained/resolve.d.ts

@@ -0,0 +1,4 @@
+import { type ContainedFolder } from './layout.js';
+/** The folder that holds tools, state, logs ...: the mount folder while the image is mounted, else the data folder. */
+export declare function hostDataRoot(dataPath: string): string;
+export declare function hostDataFolder(dataPath: string, name: ContainedFolder): string;

package/dist/host/storage/contained/resolve.js

@@ -0,0 +1,30 @@
+// Where the host finds the data set's folders. Plain data folder: <data>\<name>. While contained storage has the image
+// mounted: <storage>\mounts\<set>\<name>, but only when that folder really is another volume (a stale record must
+// never send a write into an empty folder on this PC's own disk).
+import fs from 'node:fs';
+import path from 'node:path';
+import { JsonFile } from '../../../shared/io/index.js';
+import { containedPaths } from './layout.js';
+import { ContainedStateSchema } from './state.js';
+/** The folder that holds tools, state, logs ...: the mount folder while the image is mounted, else the data folder. */
+export function hostDataRoot(dataPath) {
+    try {
+        const set = path.basename(dataPath);
+        const paths = containedPaths(path.dirname(path.dirname(dataPath)), set);
+        if (!fs.existsSync(paths.stateFile))
+            return dataPath;
+        const state = new JsonFile(ContainedStateSchema, paths.stateFile).read();
+        if (!state?.sets[set]?.mounted)
+            return dataPath;
+        if (fs.statSync(paths.mount).dev === fs.statSync(paths.mountsDir).dev)
+            return dataPath;
+        return paths.mount;
+    }
+    catch {
+        // No contained storage here (or an unreadable record): the plain folder is the answer.
+        return dataPath;
+    }
+}
+export function hostDataFolder(dataPath, name) {
+    return path.join(hostDataRoot(dataPath), name);
+}

package/dist/host/storage/contained/setting.d.ts

@@ -0,0 +1 @@
+export declare function writeContainedSetting(configFile: string, value: 'off' | 'vhdx'): void;

package/dist/host/storage/contained/setting.js

@@ -0,0 +1,5 @@
+// Writes storage.contained into the settings file (keeping its comments), the way `storage move` pins storage.root.
+import { setValue } from '../../migrate/migrations/config-file.js';
+export function writeContainedSetting(configFile, value) {
+    setValue(configFile, ['storage', 'contained'], value);
+}

package/dist/host/storage/contained/state.d.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { type ContainedPaths } from './layout.js';
+declare const HolderSchema: z.ZodObject<{
+    id: z.ZodString;
+    pid: z.ZodNumber;
+    since: z.ZodString;
+}, z.core.$strict>;
+export type Holder = z.infer<typeof HolderSchema>;
+declare const SetStateSchema: z.ZodObject<{
+    mounted: z.ZodBoolean;
+    holders: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        pid: z.ZodNumber;
+        since: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SetState = z.infer<typeof SetStateSchema>;
+export declare const ContainedStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sets: z.ZodRecord<z.ZodString, z.ZodObject<{
+        mounted: z.ZodBoolean;
+        holders: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            pid: z.ZodNumber;
+            since: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ContainedState = z.infer<typeof ContainedStateSchema>;
+export declare const EMPTY_STATE: ContainedState;
+export declare function setStateOf(state: ContainedState, set: string): SetState;
+/** Drops the holders whose process is gone (a launch that ended, a watcher that crashed). */
+export declare function pruneHolders(state: ContainedState, set: string, alive: (pid: number) => boolean): ContainedState;
+/** Adds a holder (or refreshes the one with the same id). */
+export declare function addHolder(state: ContainedState, set: string, holder: Holder): ContainedState;
+export declare function removeHolder(state: ContainedState, set: string, id: string): ContainedState;
+export declare function markMounted(state: ContainedState, set: string, mounted: boolean): ContainedState;
+/** What reality looks like, from the status script (check-contained.ps1). */
+export interface MountReality {
+    readonly imageExists: boolean;
+    readonly imageBytes: number;
+    readonly mountExists: boolean;
+    readonly mountIsMountPoint: boolean;
+    /** null: Windows would not say without administrator rights. */
+    readonly attached: boolean | null;
+}
+export type ContainedDiagnosis = {
+    readonly kind: 'ok';
+    readonly mounted: boolean;
+} | {
+    readonly kind: 'in-use';
+} | {
+    readonly kind: 'stale-state';
+} | {
+    readonly kind: 'stale-mount';
+} | {
+    readonly kind: 'image-missing';
+};
+/** Compares the record with what is really mounted. `live` is the number of holders that still run. */
+export declare function diagnose(o: {
+    readonly state: SetState;
+    readonly reality: MountReality;
+    readonly live: number;
+    readonly sandboxRunning: boolean;
+}): ContainedDiagnosis;
+/** The best answer for "is a process alive": signal 0 only checks. */
+export declare function processAlive(pid: number): boolean;
+/** The state file with a lock, so two commands at once never lose each other's change. */
+export declare class StateFile {
+    private readonly paths;
+    private readonly alive;
+    private readonly now;
+    private readonly file;
+    constructor(paths: Pick<ContainedPaths, 'stateFile' | 'lockFile' | 'mountsDir'>, alive?: (pid: number) => boolean, now?: () => number);
+    read(): ContainedState;
+    exists(): boolean;
+    /** Reads, changes and writes under the lock; returns what was written. */
+    update(change: (current: ContainedState) => ContainedState): ContainedState;
+    private locked;
+    private lockIsStale;
+}
+/** The data sets of a storage folder whose image is recorded as mounted (a storage move must wait for these). */
+export declare function mountedSets(storageRoot: string): string[];
+/**
+ * A line for the start of a command when the record says an image is mounted that no running process holds and no
+ * sandbox uses (nothing is looked up on the disk: this is only the record), or null.
+ */
+export declare function staleMountNote(storageRoot: string, set: string, sandboxRunning: boolean, alive?: (pid: number) => boolean): string | null;
+export {};

package/dist/host/storage/contained/state.js

@@ -0,0 +1,166 @@
+// The record of which data sets are mounted and which processes hold them, kept outside the image
+// (<storage>\mounts\state.json): the first launch mounts, a second one that finds it mounted only adds itself, and the
+// last one to let go dismounts. Pure transitions on a plain object, plus the file (with a lock) around them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../../shared/io/index.js';
+import { SET_NAME_RULE } from './layout.js';
+const HolderSchema = z.strictObject({
+    /** What holds the mount: "launch" while a launch starts the sandbox, "watcher" for the background process. */
+    id: z.string().regex(/^[a-z-]{1,20}$/),
+    pid: z.number().int().positive(),
+    since: z.string().max(40),
+});
+const SetStateSchema = z.strictObject({
+    mounted: z.boolean(),
+    holders: z.array(HolderSchema).max(32),
+});
+export const ContainedStateSchema = z.strictObject({
+    version: z.literal(1),
+    sets: z.record(z.string().regex(SET_NAME_RULE), SetStateSchema),
+});
+export const EMPTY_STATE = { version: 1, sets: {} };
+const NONE = { mounted: false, holders: [] };
+export function setStateOf(state, set) {
+    return state.sets[set] ?? NONE;
+}
+function withSet(state, set, next) {
+    return { version: 1, sets: { ...state.sets, [set]: next } };
+}
+/** Drops the holders whose process is gone (a launch that ended, a watcher that crashed). */
+export function pruneHolders(state, set, alive) {
+    const current = setStateOf(state, set);
+    const holders = current.holders.filter((h) => alive(h.pid));
+    return holders.length === current.holders.length ? state : withSet(state, set, { ...current, holders });
+}
+/** Adds a holder (or refreshes the one with the same id). */
+export function addHolder(state, set, holder) {
+    const current = setStateOf(state, set);
+    const holders = [...current.holders.filter((h) => h.id !== holder.id), holder];
+    return withSet(state, set, { ...current, holders });
+}
+export function removeHolder(state, set, id) {
+    const current = setStateOf(state, set);
+    return withSet(state, set, { ...current, holders: current.holders.filter((h) => h.id !== id) });
+}
+export function markMounted(state, set, mounted) {
+    return withSet(state, set, { ...setStateOf(state, set), mounted });
+}
+/** Compares the record with what is really mounted. `live` is the number of holders that still run. */
+export function diagnose(o) {
+    const { state, reality } = o;
+    if (!reality.imageExists)
+        return { kind: 'image-missing' };
+    if (reality.mountIsMountPoint) {
+        if (o.live > 0 || o.sandboxRunning)
+            return { kind: 'in-use' };
+        return { kind: 'stale-mount' };
+    }
+    if (state.mounted)
+        return { kind: 'stale-state' };
+    return { kind: 'ok', mounted: false };
+}
+/** The best answer for "is a process alive": signal 0 only checks. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: it exists but belongs to someone else.
+        return e.code === 'EPERM';
+    }
+}
+const LOCK_STALE_MS = 2 * 60_000;
+const LOCK_WAIT_MS = 8_000;
+const pause = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+/** The state file with a lock, so two commands at once never lose each other's change. */
+export class StateFile {
+    paths;
+    alive;
+    now;
+    file;
+    constructor(paths, alive = processAlive, now = Date.now) {
+        this.paths = paths;
+        this.alive = alive;
+        this.now = now;
+        this.file = new JsonFile(ContainedStateSchema, paths.stateFile);
+    }
+    read() {
+        return this.file.read() ?? EMPTY_STATE;
+    }
+    exists() {
+        return fs.existsSync(this.paths.stateFile);
+    }
+    /** Reads, changes and writes under the lock; returns what was written. */
+    update(change) {
+        return this.locked(() => {
+            const next = change(this.read());
+            this.file.write(next);
+            return next;
+        });
+    }
+    locked(work) {
+        fs.mkdirSync(this.paths.mountsDir, { recursive: true });
+        const deadline = this.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                const fd = fs.openSync(this.paths.lockFile, 'wx');
+                fs.writeSync(fd, String(process.pid));
+                fs.closeSync(fd);
+                break;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+                if (this.lockIsStale()) {
+                    fs.rmSync(this.paths.lockFile, { force: true });
+                    continue;
+                }
+                if (this.now() > deadline)
+                    throw new Error('Another command is changing the contained storage record.');
+                pause(50);
+            }
+        }
+        try {
+            return work();
+        }
+        finally {
+            fs.rmSync(this.paths.lockFile, { force: true });
+        }
+    }
+    lockIsStale() {
+        try {
+            const age = this.now() - fs.statSync(this.paths.lockFile).mtimeMs;
+            const pid = Number.parseInt(fs.readFileSync(this.paths.lockFile, 'utf8'), 10);
+            return age > LOCK_STALE_MS || (Number.isInteger(pid) && pid > 0 && !this.alive(pid));
+        }
+        catch {
+            // Gone between the check and the read: the next try finds out.
+            return false;
+        }
+    }
+}
+/** The data sets of a storage folder whose image is recorded as mounted (a storage move must wait for these). */
+export function mountedSets(storageRoot) {
+    const state = new JsonFile(ContainedStateSchema, path.join(path.resolve(storageRoot), 'mounts', 'state.json')).read();
+    return state
+        ? Object.entries(state.sets)
+            .filter(([, s]) => s.mounted)
+            .map(([name]) => name)
+        : [];
+}
+/**
+ * A line for the start of a command when the record says an image is mounted that no running process holds and no
+ * sandbox uses (nothing is looked up on the disk: this is only the record), or null.
+ */
+export function staleMountNote(storageRoot, set, sandboxRunning, alive = processAlive) {
+    const record = setStateOf(new JsonFile(ContainedStateSchema, path.join(path.resolve(storageRoot), 'mounts', 'state.json')).read() ??
+        EMPTY_STATE, set);
+    if (!record.mounted || sandboxRunning || record.holders.some((h) => alive(h.pid)))
+        return null;
+    return 'Contained storage is still mounted from an earlier sandbox. Run sandbox repair to dismount it (Windows asks for permission).';
+}

package/dist/host/storage/contained/transfer.d.ts

@@ -0,0 +1,24 @@
+import { type Measured, type MoveEstimate, type MoveProgress } from '../move.js';
+export interface TransferFolder {
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+    readonly measured: Measured;
+}
+export interface TransferPlan {
+    readonly folders: readonly TransferFolder[];
+    readonly total: Measured;
+    readonly estimate: MoveEstimate;
+}
+export interface TransferResult {
+    readonly files: number;
+    readonly bytes: number;
+    /** Folders whose original was kept (a link inside, or the folder could not be removed), with the reason. */
+    readonly notes: readonly string[];
+}
+/** What would move: each contained folder that exists in `fromRoot` and holds something, with its size and the time. */
+export declare function planTransfer(fromRoot: string, toRoot: string, freeBytesRoot: string, measure?: (dir: string) => Measured): TransferPlan;
+/** Refuses a target folder that already holds files (nothing is ever merged or overwritten). */
+export declare function assertTargetsFree(plan: TransferPlan): void;
+/** Copies every folder of the plan, checks sizes and counts, then removes the originals. `root` bounds the removal. */
+export declare function runTransfer(plan: TransferPlan, root: string, onProgress?: (p: MoveProgress) => void): Promise<TransferResult>;

package/dist/host/storage/contained/transfer.js

@@ -0,0 +1,121 @@
+// Moving the data set's folders into the image (contained storage on) and back out to plain folders (off). The copy is
+// verified file by file; the originals are removed only after every folder was copied completely, and a link found
+// in a folder is never followed (that folder is then left where it is).
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { freeBytesAt } from '../../../core/disk.js';
+import { fail, isLink } from '../../../core/util/index.js';
+import { safeRemove } from '../../../shared/io/index.js';
+import { estimateMove, measureFolder } from '../move.js';
+import { CONTAINED_FOLDERS } from './layout.js';
+const STREAM_FROM_BYTES = 64 * 1024 * 1024;
+const plainFolder = (dir) => {
+    try {
+        return fs.statSync(dir).isDirectory() && !isLink(dir);
+    }
+    catch {
+        return false;
+    }
+};
+const holdsFiles = (dir) => {
+    try {
+        return fs.readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+};
+/** What would move: each contained folder that exists in `fromRoot` and holds something, with its size and the time. */
+export function planTransfer(fromRoot, toRoot, freeBytesRoot, measure = measureFolder) {
+    const folders = [];
+    for (const name of CONTAINED_FOLDERS) {
+        const from = path.join(fromRoot, name);
+        if (!plainFolder(from) || !holdsFiles(from))
+            continue;
+        folders.push({ name, from, to: path.join(toRoot, name), measured: measure(from) });
+    }
+    const total = {
+        bytes: folders.reduce((n, f) => n + f.measured.bytes, 0),
+        files: folders.reduce((n, f) => n + f.measured.files, 0),
+        partial: folders.some((f) => f.measured.partial),
+    };
+    return { folders, total, estimate: estimateMove(total, false, freeBytesAt(freeBytesRoot)) };
+}
+/** Refuses a target folder that already holds files (nothing is ever merged or overwritten). */
+export function assertTargetsFree(plan) {
+    for (const f of plan.folders)
+        if (fs.existsSync(f.to) && holdsFiles(f.to))
+            fail(f.to + ' already holds files.', 'Move or delete them first, then run the command again.');
+}
+/** Copies every folder of the plan, checks sizes and counts, then removes the originals. `root` bounds the removal. */
+export async function runTransfer(plan, root, onProgress) {
+    assertTargetsFree(plan);
+    const done = { bytes: 0, files: 0, links: 0 };
+    const linkFolders = new Set();
+    let last = 0;
+    const report = (force = false) => {
+        if (!onProgress || (!force && Date.now() - last < 200))
+            return;
+        last = Date.now();
+        onProgress({ bytes: done.bytes, files: done.files });
+    };
+    const walk = async (from, to, folder) => {
+        await fs.promises.mkdir(to, { recursive: true });
+        for (const entry of await fs.promises.readdir(from, { withFileTypes: true })) {
+            const a = path.join(from, entry.name);
+            const b = path.join(to, entry.name);
+            if (entry.isSymbolicLink()) {
+                linkFolders.add(folder);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(a, b, folder);
+                continue;
+            }
+            const stat = await fs.promises.stat(a);
+            if (stat.size >= STREAM_FROM_BYTES)
+                await pipeline(fs.createReadStream(a), fs.createWriteStream(b));
+            else
+                await fs.promises.copyFile(a, b);
+            const copied = await fs.promises.stat(b);
+            if (copied.size !== stat.size)
+                fail('The copy of ' + a + ' has another size than the original.');
+            await fs.promises.utimes(b, stat.atime, stat.mtime);
+            done.bytes += stat.size;
+            done.files++;
+            report();
+        }
+    };
+    for (const f of plan.folders)
+        await walk(f.from, f.to, f.name);
+    report(true);
+    const notes = [];
+    for (const f of plan.folders) {
+        const copied = measureFolder(f.to);
+        if (!f.measured.partial && copied.files < f.measured.files)
+            fail('The copy of ' +
+                f.name +
+                ' has fewer files than the original (' +
+                copied.files +
+                ' of ' +
+                f.measured.files +
+                ').', 'Nothing was removed. Run the command again.');
+    }
+    // Only now, with everything copied, do the originals go.
+    for (const f of plan.folders) {
+        if (linkFolders.has(f.name)) {
+            notes.push(f.from + ' has links in it, which are not copied; it was left where it is.');
+            continue;
+        }
+        try {
+            safeRemove(f.from, root);
+            if (fs.existsSync(f.from))
+                notes.push(f.from + ' could not be removed completely; delete it by hand.');
+        }
+        catch (e) {
+            notes.push(f.from + ' could not be removed (' + (e instanceof Error ? e.message : String(e)) + ').');
+        }
+    }
+    return { files: done.files, bytes: done.bytes, notes };
+}