windows-development-sandbox 1.4.3 → 1.5.0

package/dist/host/migrate/backup.js

@@ -0,0 +1,92 @@
+// Copies of what a migration is about to change, in <storageRoot>\backups\migrate-<from>-<to>-<stamp>\, so a failed run
+// can put every file and folder back byte for byte. Data sets are never copied (they can be gigabytes and the
+// migrations do not change them), and links are refused (the sandbox can plant them).
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertNoLinks, fail, isInsideOrEqual, isLink } from '../../core/util/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+const ManifestSchema = z.object({
+    entries: z.array(z.object({ original: z.string(), copy: z.string(), existed: z.boolean() })),
+});
+const stamp = () => {
+    const d = new Date();
+    const two = (n) => String(n).padStart(2, '0');
+    return (d.getFullYear() +
+        two(d.getMonth() + 1) +
+        two(d.getDate()) +
+        two(d.getHours()) +
+        two(d.getMinutes()) +
+        two(d.getSeconds()));
+};
+/** True if the folder holds a link anywhere inside it (the copy would follow or recreate it). */
+function containsLink(dir) {
+    return fs.readdirSync(dir, { withFileTypes: true }).some((entry) => {
+        const full = path.join(dir, entry.name);
+        if (entry.isSymbolicLink() || isLink(full))
+            return true;
+        return entry.isDirectory() && containsLink(full);
+    });
+}
+export class MigrationBackup {
+    storageRoot;
+    folder;
+    manifest;
+    constructor(storageRoot, folder) {
+        this.storageRoot = storageRoot;
+        this.folder = folder;
+        this.manifest = new JsonFile(ManifestSchema, path.join(folder, 'manifest.json'));
+    }
+    /** A new, empty backup folder for a run from one version to another (never an existing one). */
+    static create(storageRoot, from, to) {
+        const base = path.join(storageRoot, 'backups', 'migrate-' + from + '-' + to + '-' + stamp());
+        let folder = base;
+        for (let n = 2; fs.existsSync(folder); n++)
+            folder = base + '-' + n;
+        return new MigrationBackup(storageRoot, folder);
+    }
+    /** An existing backup folder (for restoring it). Only folders under the storage root's backups are accepted. */
+    static open(storageRoot, folder) {
+        if (!isInsideOrEqual(path.join(storageRoot, 'backups'), folder))
+            fail('Refusing to restore ' + folder + ': it is not a backup folder under ' + storageRoot + '.');
+        return new MigrationBackup(storageRoot, folder);
+    }
+    get path() {
+        return this.folder;
+    }
+    /** Copies each existing file or folder (and records the ones that do not exist yet, to remove them on restore). */
+    save(paths) {
+        const dataRoot = path.join(this.storageRoot, 'data');
+        const entries = this.manifest.read()?.entries ?? [];
+        for (const target of paths) {
+            if (isInsideOrEqual(dataRoot, target))
+                fail('Refusing to back up ' + target + ': data sets are never copied.', 'A migration must not change a data set.');
+            assertNoLinks(path.dirname(target), target);
+            const existed = fs.existsSync(target);
+            const copy = path.join(this.folder, 'files', entries.length + '-' + path.basename(target));
+            if (existed) {
+                if (fs.statSync(target).isDirectory() && containsLink(target))
+                    fail('Refusing to back up ' + target + ': it holds a link (possible escape attempt from the sandbox).');
+                fs.mkdirSync(path.dirname(copy), { recursive: true });
+                fs.cpSync(target, copy, { recursive: true, verbatimSymlinks: true });
+            }
+            entries.push({ original: target, copy, existed });
+        }
+        this.manifest.write({ entries });
+    }
+    /** Puts every saved path back: copies restored, paths that did not exist before removed again. Last saved first. */
+    restore() {
+        const saved = this.manifest.read();
+        if (!saved)
+            fail('The backup ' + this.folder + ' has no readable manifest.', 'Restore its files by hand, or report it.');
+        for (const entry of [...saved.entries].reverse()) {
+            fs.rmSync(entry.original, { recursive: true, force: true });
+            if (!entry.existed)
+                continue;
+            if (!fs.existsSync(entry.copy))
+                fail('The backup is missing ' + entry.copy + '.', 'Report this: the backup is damaged.');
+            fs.mkdirSync(path.dirname(entry.original), { recursive: true });
+            fs.cpSync(entry.copy, entry.original, { recursive: true, verbatimSymlinks: true });
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export type { Migration, MigrationContext, MigrationScope } from './migration.js';
+export { MigrationMarker, type Marker } from './marker.js';
+export { MigrationBackup } from './backup.js';
+export { MigrationRunner, type MigrationReport } from './runner.js';
+export { MIGRATIONS } from './registry.js';

package/dist/host/migrate/index.js

@@ -0,0 +1,4 @@
+export { MigrationMarker } from './marker.js';
+export { MigrationBackup } from './backup.js';
+export { MigrationRunner } from './runner.js';
+export { MIGRATIONS } from './registry.js';

package/dist/host/migrate/marker.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const MIGRATION_ID: RegExp;
+declare const MarkerSchema: z.ZodObject<{
+    lastVersion: z.ZodString;
+    applied: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        at: z.ZodString;
+        backup: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Marker = z.infer<typeof MarkerSchema>;
+export declare class MigrationMarker {
+    private readonly store;
+    constructor(userDir: string);
+    get file(): string;
+    read(): Marker;
+    record(id: string, backup: string | null): void;
+    setVersion(version: string): void;
+    has(id: string): boolean;
+}
+export {};

package/dist/host/migrate/marker.js

@@ -0,0 +1,49 @@
+// The record of which migrations ran: <userDir>\migrations.json. A missing file means nothing has run yet (older than
+// 1.5); a file that is there but unreadable stops the run rather than re-running everything.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { fail } from '../../core/util/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+export const MIGRATION_ID = /^[a-z0-9-]{1,80}$/;
+const MAX_APPLIED = 500;
+const MarkerSchema = z.object({
+    lastVersion: z.string(),
+    applied: z
+        .array(z.object({ id: z.string().regex(MIGRATION_ID), at: z.string(), backup: z.string().nullable() }))
+        .max(MAX_APPLIED),
+});
+export class MigrationMarker {
+    store;
+    constructor(userDir) {
+        this.store = new JsonFile(MarkerSchema, path.join(userDir, 'migrations.json'));
+    }
+    get file() {
+        return this.store.file;
+    }
+    read() {
+        if (!fs.existsSync(this.store.file))
+            return { lastVersion: '0.0.0', applied: [] };
+        const marker = this.store.read();
+        if (!marker)
+            fail('The migrations record ' + this.store.file + ' is not readable.', 'Rename or delete that file (your settings are not changed); the next start checks each change again.');
+        return marker;
+    }
+    record(id, backup) {
+        if (!MIGRATION_ID.test(id))
+            fail('Migration id "' + id + '" is not kebab-case.');
+        const marker = this.read();
+        if (marker.applied.length >= MAX_APPLIED)
+            fail('The migrations record has ' + MAX_APPLIED + ' entries.', 'Report this: the record needs pruning.');
+        this.store.write({
+            ...marker,
+            applied: [...marker.applied, { id, at: new Date().toISOString(), backup }],
+        });
+    }
+    setVersion(version) {
+        this.store.write({ ...this.read(), lastVersion: version });
+    }
+    has(id) {
+        return this.read().applied.some((entry) => entry.id === id);
+    }
+}

package/dist/host/migrate/migration.d.ts

@@ -0,0 +1,26 @@
+export type MigrationScope = 'user' | 'machine';
+export interface MigrationContext {
+    /** The storage root, e.g. %LOCALAPPDATA%\AgentSandbox. */
+    readonly storageRoot: string;
+    /** The config folder, ~/.agent-sandbox. */
+    readonly userDir: string;
+    /** The user's config.json, if there is one. */
+    readonly configPath: string | null;
+    readonly sandboxRunning: () => boolean;
+}
+export interface Migration {
+    /** Kebab-case, unique, e.g. '2026-10-unpin-config-defaults'. */
+    readonly id: string;
+    /** The version the change first shipped in. */
+    readonly introducedIn: string;
+    readonly scope: MigrationScope;
+    /** Waits while a sandbox runs (it may read the files this changes). */
+    readonly needsIdleSandbox: boolean;
+    /** One line: what it changes (shown by a dry run). */
+    readonly summary: string;
+    /** Idempotent check: is there anything to do? */
+    applies(ctx: MigrationContext): boolean;
+    /** Files and folders it will change; they are backed up first. */
+    touches(ctx: MigrationContext): readonly string[];
+    run(ctx: MigrationContext, note: (line: string) => void): Promise<void>;
+}

package/dist/host/migrate/migration.js

@@ -0,0 +1,3 @@
+// What a migration is: one numbered change to what is stored on this PC, with a cheap check for whether it still has to
+// run and a list of what it will touch (backed up before it runs).
+export {};

package/dist/host/migrate/migrations/config-file.d.ts

@@ -0,0 +1,8 @@
+import { type DefaultsSnapshot } from '../snapshots.js';
+export type Json = Record<string, unknown>;
+/** The parsed file, or null when it is missing or not valid JSON with comments (then there is nothing to recognise). */
+export declare function readFileObject(file: string | null): Json | null;
+/** The snapshots of a full `config init` file: every top-level key of the snapshot is in the file. */
+export declare function fullSnapshots(file: Json): DefaultsSnapshot[];
+/** Removes these values from the file, comments and the rest untouched, noting `why: <key>` for each. */
+export declare function removeValues(file: string, paths: readonly string[][], why: string, note: (line: string) => void): void;

package/dist/host/migrate/migrations/config-file.js

@@ -0,0 +1,28 @@
+// Reading and editing a config.json (JSON with comments) for the migrations: removing a value keeps every comment.
+import fs from 'node:fs';
+import { applyEdits, modify, parse } from 'jsonc-parser';
+import _ from 'lodash';
+import { writeFileAtomic } from '../../../shared/io/index.js';
+import { DEFAULTS_SNAPSHOTS } from '../snapshots.js';
+const FORMAT = { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } };
+/** The parsed file, or null when it is missing or not valid JSON with comments (then there is nothing to recognise). */
+export function readFileObject(file) {
+    if (!file || !fs.existsSync(file))
+        return null;
+    const errors = [];
+    const value = parse(fs.readFileSync(file, 'utf8'), errors, { allowTrailingComma: true });
+    return errors.length === 0 && _.isPlainObject(value) ? value : null;
+}
+/** The snapshots of a full `config init` file: every top-level key of the snapshot is in the file. */
+export function fullSnapshots(file) {
+    return DEFAULTS_SNAPSHOTS.filter((snapshot) => Object.keys(snapshot.defaults).every((key) => key in file));
+}
+/** Removes these values from the file, comments and the rest untouched, noting `why: <key>` for each. */
+export function removeValues(file, paths, why, note) {
+    let text = fs.readFileSync(file, 'utf8');
+    for (const path of paths) {
+        text = applyEdits(text, modify(text, path, undefined, FORMAT));
+        note(why + ': ' + path.join('.'));
+    }
+    writeFileAtomic(file, text);
+}

package/dist/host/migrate/migrations/follow-machine-storage.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from '../migration.js';
+export declare const followMachineStorage: Migration;

package/dist/host/migrate/migrations/follow-machine-storage.js

@@ -0,0 +1,36 @@
+// An all-users install keeps everyone's data under %ProgramData%\AgentSandbox (its machine config says where), so a
+// sandbox can be shared. A config.json written by an old `config init` pins storage.root to the old per-user default,
+// which wins over the machine config. Removes that pin, and only that: a storage.root you chose yourself stays.
+import _ from 'lodash';
+import { DEFAULTS, machineConfigPath } from '../../../core/config/index.js';
+import { fullSnapshots, readFileObject, removeValues } from './config-file.js';
+const ROOT = ['storage', 'root'];
+/** True when the machine config sets the storage folder and the user's file only pins a default of an old init. */
+function pinnedOverMachine(configPath) {
+    const machine = readFileObject(machineConfigPath());
+    if (!machine || !_.has(machine, ROOT))
+        return false;
+    const file = readFileObject(configPath);
+    if (!file || !_.has(file, ROOT))
+        return false;
+    const value = _.get(file, ROOT);
+    const defaults = [_.get(DEFAULTS, ROOT), ...fullSnapshots(file).map((s) => _.get(s.defaults, ROOT))];
+    return defaults.some((d) => _.isEqual(d, value));
+}
+export const followMachineStorage = {
+    id: '2026-10-follow-machine-storage',
+    introducedIn: '1.5.0',
+    scope: 'user',
+    needsIdleSandbox: true,
+    summary: "Under an all-users install, removes the storage folder an old 'config init' pinned, so the shared one is used.",
+    applies(ctx) {
+        return pinnedOverMachine(ctx.configPath);
+    },
+    touches(ctx) {
+        return ctx.configPath ? [ctx.configPath] : [];
+    },
+    async run(ctx, note) {
+        if (ctx.configPath && pinnedOverMachine(ctx.configPath))
+            removeValues(ctx.configPath, [ROOT], 'Now follows the all-users install', note);
+    },
+};

package/dist/host/migrate/migrations/unpin-config-defaults.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from '../migration.js';
+export declare const unpinConfigDefaults: Migration;

package/dist/host/migrate/migrations/unpin-config-defaults.js

@@ -0,0 +1,41 @@
+// The first real migration. `config init` used to write every default into config.json, so files from 1.0.x pin values
+// that have since changed (the toolchains now follow 'auto'). Removes the leaves that still hold an old default and
+// differ from today's, so they follow the current default; anything the user changed stays, comments included.
+import _ from 'lodash';
+import { DEFAULTS } from '../../../core/config/index.js';
+import { fullSnapshots, readFileObject, removeValues } from './config-file.js';
+/** Paths of the leaves of a JSON object (arrays and scalars are leaves). */
+function leafPaths(value, prefix = []) {
+    if (!_.isPlainObject(value))
+        return prefix.length ? [prefix] : [];
+    return Object.entries(value).flatMap(([key, child]) => leafPaths(child, [...prefix, key]));
+}
+/** Leaves that still hold an old default (from a full snapshot) and differ from today's default. */
+function pinnedLeaves(file) {
+    const snapshots = fullSnapshots(file);
+    return leafPaths(file).filter((path) => {
+        const value = _.get(file, path);
+        return (_.has(DEFAULTS, path) &&
+            !_.isEqual(value, _.get(DEFAULTS, path)) &&
+            snapshots.some((snapshot) => _.has(snapshot.defaults, path) && _.isEqual(_.get(snapshot.defaults, path), value)));
+    });
+}
+export const unpinConfigDefaults = {
+    id: '2026-10-unpin-config-defaults',
+    introducedIn: '1.5.0',
+    scope: 'user',
+    needsIdleSandbox: false,
+    summary: "Removes config.json values an old 'config init' pinned to that version's default, so they follow today's.",
+    applies(ctx) {
+        const file = readFileObject(ctx.configPath);
+        return file !== null && pinnedLeaves(file).length > 0;
+    },
+    touches(ctx) {
+        return ctx.configPath ? [ctx.configPath] : [];
+    },
+    async run(ctx, note) {
+        const parsed = readFileObject(ctx.configPath);
+        if (ctx.configPath && parsed)
+            removeValues(ctx.configPath, pinnedLeaves(parsed), 'Now follows the default', note);
+    },
+};

package/dist/host/migrate/registry.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from './migration.js';
+export declare const MIGRATIONS: readonly Migration[];

package/dist/host/migrate/registry.js

@@ -0,0 +1,3 @@
+import { followMachineStorage } from './migrations/follow-machine-storage.js';
+import { unpinConfigDefaults } from './migrations/unpin-config-defaults.js';
+export const MIGRATIONS = [unpinConfigDefaults, followMachineStorage];

package/dist/host/migrate/runner.d.ts

@@ -0,0 +1,21 @@
+import { MigrationMarker } from './marker.js';
+import type { Migration, MigrationContext } from './migration.js';
+export interface MigrationReport {
+    readonly applied: string[];
+    readonly postponed: string[];
+}
+export declare class MigrationRunner {
+    private readonly migrations;
+    private readonly ctx;
+    private readonly marker;
+    constructor(migrations: readonly Migration[], ctx: MigrationContext, marker?: MigrationMarker);
+    /** Not recorded as applied, and still needed (applies() is checked now). */
+    pending(): Migration[];
+    run(version: string, note: (line: string) => void): Promise<MigrationReport>;
+    /** Puts a backup made by an earlier run back (only folders under the storage root's backups). */
+    restore(backupPath: string): void;
+    /** One line per pending migration, for a dry run. */
+    planText(): string[];
+    private backup;
+    private recover;
+}

package/dist/host/migrate/runner.js

@@ -0,0 +1,67 @@
+// Runs the migrations that have not run yet, in list order. Each one is backed up first and recorded only when it
+// succeeds; a failure puts its backup back and stops the run, so the next start tries again from the same place.
+import { errMsg, fail } from '../../core/util/index.js';
+import { MigrationBackup } from './backup.js';
+import { MigrationMarker } from './marker.js';
+export class MigrationRunner {
+    migrations;
+    ctx;
+    marker;
+    constructor(migrations, ctx, marker = new MigrationMarker(ctx.userDir)) {
+        this.migrations = migrations;
+        this.ctx = ctx;
+        this.marker = marker;
+    }
+    /** Not recorded as applied, and still needed (applies() is checked now). */
+    pending() {
+        const done = new Set(this.marker.read().applied.map((entry) => entry.id));
+        return this.migrations.filter((migration) => !done.has(migration.id) && migration.applies(this.ctx));
+    }
+    async run(version, note) {
+        const applied = [];
+        const postponed = [];
+        for (const migration of this.pending()) {
+            if (migration.needsIdleSandbox && this.ctx.sandboxRunning()) {
+                note('Postponed ' + migration.id + ' until no sandbox runs.');
+                postponed.push(migration.id);
+                continue;
+            }
+            const touched = migration.touches(this.ctx);
+            const backup = touched.length ? this.backup(touched, version) : null;
+            try {
+                await migration.run(this.ctx, note);
+            }
+            catch (e) {
+                fail('Updating your saved settings failed (' + migration.id + '): ' + errMsg(e), this.recover(backup) + ' Run sandbox migrate to try again, or report it.');
+            }
+            this.marker.record(migration.id, backup?.path ?? null);
+            applied.push(migration.id);
+        }
+        this.marker.setVersion(version);
+        return { applied, postponed };
+    }
+    /** Puts a backup made by an earlier run back (only folders under the storage root's backups). */
+    restore(backupPath) {
+        MigrationBackup.open(this.ctx.storageRoot, backupPath).restore();
+    }
+    /** One line per pending migration, for a dry run. */
+    planText() {
+        return this.pending().map((migration) => migration.id + ': ' + migration.summary);
+    }
+    backup(touched, version) {
+        const backup = MigrationBackup.create(this.ctx.storageRoot, this.marker.read().lastVersion, version);
+        backup.save(touched);
+        return backup;
+    }
+    recover(backup) {
+        if (!backup)
+            return 'Nothing was changed.';
+        try {
+            backup.restore();
+            return 'Your files are back as they were (backup: ' + backup.path + ').';
+        }
+        catch (e) {
+            return 'Putting your files back failed too (' + errMsg(e) + '); copy them back from ' + backup.path + ' by hand.';
+        }
+    }
+}

package/dist/host/migrate/snapshots.d.ts

@@ -0,0 +1,6 @@
+export interface DefaultsSnapshot {
+    readonly version: string;
+    readonly rev: string;
+    readonly defaults: Readonly<Record<string, unknown>>;
+}
+export declare const DEFAULTS_SNAPSHOTS: readonly DefaultsSnapshot[];