dsh-agent-plugins-market 0.5.2 → 0.6.0

package/lib/application/details.js

@@ -2,6 +2,9 @@
 import { readFile } from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import { discoverLspEntries, listMdFiles } from '../catalog/surfaces.js';
+import { credentialRefsInServer } from '../runtime/mcp-config.js';
+import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
+import { applyOverride } from '../runtime/mcp-overrides.js';
 import { effectiveSurfaces } from '../model/types.js';
 /** Build the detail response for one normalized suite. */
 export async function buildSuiteDetail(suite, installed, diagnostics, mcpOverrides = {}) {
@@ -21,18 +24,27 @@ export async function buildSuiteDetail(suite, installed, diagnostics, mcpOverrid
         installed: installed !== undefined,
         enabled: installed?.enabled === true,
         surfaceToggles: effectiveSurfaces(installed?.surfaces),
-        mcpOverrides,
+        mcpOverrides: redactMcpOverrides(mcpOverrides),
         skills: suite.skills.map(skill => ({
             name: skill.name,
             description: skill.description,
             ...(skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse }),
             path: skill.file
         })),
-        mcpServers: suite.mcp === undefined ? [] : Object.entries(suite.mcp.servers).map(([key, server]) => ({ key, ...server })),
+        mcpServers: suite.mcp === undefined
+            ? []
+            : Object.entries(suite.mcp.servers).map(([key, server]) => {
+                const effective = applyOverride(server, mcpOverrides[key]);
+                return {
+                    key,
+                    ...redactMcpConfig(server),
+                    credentialRefs: credentialRefsInServer(effective)
+                };
+            }),
         hooks: remoteUrl === undefined ? await hooksPreviews(suite.root) : { count: 0, entries: [] },
         commands: remoteUrl === undefined ? await markdownPreviews(`${suite.root}/commands`) : [],
         agents: remoteUrl === undefined ? await markdownPreviews(`${suite.root}/agents`) : [],
-        lsp: remoteUrl === undefined ? await lspPreviews(suite.root) : [],
+        lsp: remoteUrl === undefined ? await lspDetail(suite) : { servers: [], raw: [] },
         errors: suite.errors,
         mcpErrors: diagnostics.filter(diagnostic => diagnostic.suiteId === suite.id).map(diagnostic => `${diagnostic.serverKey}: ${diagnostic.reason}`)
     };
@@ -125,15 +137,30 @@ async function hooksPreviews(root) {
     }
     return { count: 0, entries: [] };
 }
-async function lspPreviews(root) {
-    const previews = [];
-    for (const entry of await discoverLspEntries(root)) {
-        try {
-            previews.push({ name: entry.name, content: await readPreview(entry.path) });
-        }
-        catch {
-            // Unreadable LSP files are omitted from the detail response.
+/**
+ * The suite's LSP surface: inline-declared `lspServers` (already parsed into
+ * `suite.lsp` at discovery) rendered as structured server previews, plus the
+ * directory-style `.claude-plugin/lsp/*.json` / reverse-domain files as raw
+ * previews. Remote suites (not cloned) carry an empty detail.
+ */
+async function lspDetail(suite) {
+    const servers = Object.values(suite.lsp?.servers ?? {}).map(spec => ({
+        key: spec.key,
+        command: spec.command,
+        args: spec.args,
+        extensions: spec.extensionToLanguage,
+        ...(spec.env === undefined ? {} : { env: spec.env })
+    }));
+    const raw = [];
+    if (suite.remote?.url === undefined) {
+        for (const entry of await discoverLspEntries(suite.root)) {
+            try {
+                raw.push({ name: entry.name, content: await readPreview(entry.path) });
+            }
+            catch {
+                // Unreadable LSP files are omitted from the detail response.
+            }
         }
     }
-    return previews;
+    return { servers, raw };
 }

package/lib/catalog/archive.js

@@ -0,0 +1,341 @@
+/**
+ * Archive source acquisition: HTTPS download, SHA-256 verification, and safe
+ * extraction of zip / tar.gz / tgz / tar payloads into a source checkout.
+ *
+ * The pipeline mirrors the acquisition guarantees of Claude Code's `archive`
+ * plugin source: HTTPS-only by default, a 256 MiB cap, and an optional
+ * SHA-256 pin that doubles as an integrity check. Extraction is guarded
+ * against path traversal (zip-slip): zip entries are name-checked and never
+ * materialized as symlinks, and tar output is walked afterward so no symlink
+ * may point outside the extraction root.
+ *
+ * The same primitives back the git codeload-tarball fallback in
+ * `application/catalog.ts`, which is why extraction and layout normalization
+ * live here instead of inline in the manager.
+ */
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, open, readdir, readFile, readlink, rename, rm, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { Unzip, UnzipInflate } from 'fflate';
+const run = promisify(execFile);
+/** Hard cap on archive download size (mirrors Claude Code's archive limit). */
+export const ARCHIVE_MAX_BYTES = 256 * 1024 * 1024;
+/** Hard cap on the total decompressed bytes one archive may write. */
+export const ARCHIVE_MAX_EXTRACTED_BYTES = 1024 * 1024 * 1024;
+/** Hard cap on the number of files one archive may write. */
+export const ARCHIVE_MAX_ENTRIES = 20_000;
+/** Hard cap on the decompressed size of a single archive entry. */
+export const ARCHIVE_MAX_ENTRY_BYTES = 128 * 1024 * 1024;
+export const DEFAULT_ARCHIVE_TIMEOUT_MS = 180_000;
+/** Classify an archive URL by extension; undefined when unsupported. */
+export function archiveFormatOf(url) {
+    const clean = url.trim().toLowerCase();
+    if (clean.endsWith('.zip'))
+        return 'zip';
+    if (clean.endsWith('.tar.gz') || clean.endsWith('.tgz'))
+        return 'targz';
+    if (clean.endsWith('.tar'))
+        return 'tar';
+    return undefined;
+}
+/** Download the payload to a temp file, enforcing the size cap and digest. */
+export async function downloadArchive(url, tempFile, options = {}) {
+    const trimmed = url.trim();
+    if (options.allowHttp !== true && !trimmed.startsWith('https://')) {
+        throw new Error(`archive source requires an https:// URL: ${trimmed}`);
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_ARCHIVE_TIMEOUT_MS;
+    const response = await fetch(trimmed, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+    if (!response.ok)
+        throw new Error(`archive download failed: HTTP ${response.status} for ${trimmed}`);
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (Number.isFinite(declared) && declared > ARCHIVE_MAX_BYTES) {
+        throw new Error(`archive exceeds the ${ARCHIVE_MAX_BYTES} byte limit: ${declared}`);
+    }
+    const body = response.body;
+    if (body === null)
+        throw new Error(`archive download failed: empty response body for ${trimmed}`);
+    const hash = createHash('sha256');
+    const handle = await open(tempFile, 'w');
+    try {
+        let size = 0;
+        const reader = body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > ARCHIVE_MAX_BYTES) {
+                void reader.cancel();
+                throw new Error(`archive exceeds the ${ARCHIVE_MAX_BYTES} byte limit`);
+            }
+            hash.update(value);
+            await handle.write(value);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    const sha256 = hash.digest('hex');
+    if (options.sha256 !== undefined && options.sha256 !== '' && options.sha256.toLowerCase() !== sha256) {
+        throw new Error(`archive sha256 mismatch: expected ${options.sha256}, got ${sha256}`);
+    }
+    return sha256;
+}
+/**
+ * Acquire one archive source into `dest`: download, verify, extract into a
+ * sibling temp directory, normalize a single top-level wrapper directory,
+ * then swap into `dest`. Returns the payload digest.
+ */
+export async function archiveInstall(url, dest, options = {}) {
+    const format = options.format ?? archiveFormatOf(url);
+    if (format === undefined)
+        throw new Error(`unsupported archive format (expected .zip, .tar.gz, .tgz, or .tar): ${url}`);
+    const parent = resolve(dest, '..');
+    await mkdir(parent, { recursive: true });
+    const stamp = `${process.pid}.${Date.now()}`;
+    const tempFile = join(parent, `.${stamp}.download`);
+    const extractDir = join(parent, `.${stamp}.extract`);
+    try {
+        const sha256 = await downloadArchive(url, tempFile, options);
+        await mkdir(extractDir, { recursive: true });
+        if (format === 'zip') {
+            await extractZip(tempFile, extractDir);
+        }
+        else {
+            await extractTar(tempFile, extractDir, format);
+        }
+        await assertNoEscapingSymlinks(extractDir);
+        const root = await unwrapSingleRoot(extractDir);
+        await rm(dest, { recursive: true, force: true });
+        try {
+            await rename(root, dest);
+        }
+        catch {
+            await copyTree(root, dest);
+        }
+        return { sha256 };
+    }
+    finally {
+        await rm(tempFile, { force: true });
+        await rm(extractDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * Extract a zip payload with per-entry path-traversal guards and resource
+ * limits enforced *during* decompression: the stream feeds a stateful unzip
+ * (never a whole-archive `unzipSync` into memory), and total bytes, entry
+ * count, and per-entry size are counted as data arrives — a zip bomb aborts
+ * the stream before it can exhaust memory or disk. Guard violations set a
+ * failure instead of throwing inside the stream callbacks (a throw from
+ * within fflate's synchronous push recursion overflows the stack); the
+ * chunked feed halts at the next slice.
+ */
+async function extractZip(archiveFile, dest) {
+    const compressed = await readFile(archiveFile);
+    let totalBytes = 0;
+    let entryCount = 0;
+    let failure;
+    const fail = (error) => {
+        failure ??= error;
+    };
+    const unzip = new Unzip();
+    unzip.register(UnzipInflate);
+    const writes = [];
+    unzip.onfile = file => {
+        if (failure !== undefined)
+            return;
+        entryCount += 1;
+        if (entryCount > ARCHIVE_MAX_ENTRIES) {
+            fail(new Error(`archive exceeds the ${ARCHIVE_MAX_ENTRIES} entry limit`));
+            return;
+        }
+        const normalized = file.name.replace(/\\/g, '/');
+        if (normalized === '' || normalized.endsWith('/'))
+            return;
+        try {
+            assertSafeEntryName(normalized);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        const target = join(dest, normalized);
+        if (target !== dest && !target.startsWith(`${dest}/`)) {
+            fail(new Error(`zip entry escapes the extraction root: ${file.name}`));
+            return;
+        }
+        let entryBytes = 0;
+        const chunks = [];
+        file.ondata = (error, data, final) => {
+            if (error !== null) {
+                fail(error);
+                return;
+            }
+            entryBytes += data.byteLength;
+            totalBytes += data.byteLength;
+            if (entryBytes > ARCHIVE_MAX_ENTRY_BYTES) {
+                fail(new Error(`archive entry "${file.name}" exceeds the ${ARCHIVE_MAX_ENTRY_BYTES} byte per-entry limit`));
+                return;
+            }
+            if (totalBytes > ARCHIVE_MAX_EXTRACTED_BYTES) {
+                fail(new Error(`archive exceeds the ${ARCHIVE_MAX_EXTRACTED_BYTES} byte extracted-size limit`));
+                return;
+            }
+            chunks.push(Buffer.from(data));
+            if (final)
+                writes.push(writeZipEntry(target, chunks));
+        };
+        file.start();
+    };
+    // Feed in small slices so the failure flag halts processing promptly.
+    const view = new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.byteLength);
+    const slice = 64 * 1024;
+    for (let offset = 0; offset < view.length && failure === undefined; offset += slice) {
+        unzip.push(view.subarray(offset, Math.min(offset + slice, view.length)), offset + slice >= view.length);
+    }
+    if (failure !== undefined)
+        throw failure;
+    await Promise.all(writes);
+}
+/** Write one buffered zip entry to disk after its data completed inflating. */
+async function writeZipEntry(target, chunks) {
+    await mkdir(resolve(target, '..'), { recursive: true });
+    const handle = await open(target, 'w');
+    try {
+        for (const chunk of chunks)
+            await handle.write(chunk);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function assertSafeEntryName(name) {
+    if (name.startsWith('/') || name === '..' || name.startsWith('../') || name.includes('/../')) {
+        throw new Error(`archive entry escapes the extraction root: ${name}`);
+    }
+}
+/**
+ * Extract a tar / tar.gz payload with the system tar (bsdtar and GNU tar
+ * sanitize member names), then bound what landed on disk: the walk enforces
+ * the total-bytes, entry-count, and per-file limits so a tar bomb cannot
+ * exhaust the disk. The system tar streams to disk, so the cap runs on the
+ * output tree rather than on a decompressed in-memory buffer.
+ */
+async function extractTar(archiveFile, dest, format) {
+    const args = format === 'targz' ? ['-xzf', archiveFile] : ['-xf', archiveFile];
+    args.push('--no-same-owner');
+    await run('tar', args, { cwd: dest, timeout: 120_000 });
+    await assertBoundedTree(dest);
+}
+/** Post-extraction disk bounds shared by tar formats. */
+async function assertBoundedTree(root) {
+    const stack = [root];
+    let entriesSeen = 0;
+    let totalBytes = 0;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let dirents;
+        try {
+            dirents = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of dirents) {
+            const path = join(dir, entry.name);
+            entriesSeen += 1;
+            if (entriesSeen > ARCHIVE_MAX_ENTRIES) {
+                throw new Error(`archive exceeds the ${ARCHIVE_MAX_ENTRIES} entry limit`);
+            }
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(path);
+                continue;
+            }
+            let size = 0;
+            try {
+                size = (await stat(path)).size;
+            }
+            catch {
+                continue;
+            }
+            totalBytes += size;
+            if (size > ARCHIVE_MAX_ENTRY_BYTES) {
+                throw new Error(`archive entry exceeds the ${ARCHIVE_MAX_ENTRY_BYTES} byte per-entry limit: ${entry.name}`);
+            }
+            if (totalBytes > ARCHIVE_MAX_EXTRACTED_BYTES) {
+                throw new Error(`archive exceeds the ${ARCHIVE_MAX_EXTRACTED_BYTES} byte extracted-size limit`);
+            }
+        }
+    }
+}
+/** Walk the extracted tree and reject any symlink whose target resolves outside `root`. */
+async function assertNoEscapingSymlinks(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                // readlink, not readFile: readFile would follow the link and return the
+                // target's *content*, so a link pointing outside the root resolves to a
+                // bogus in-root path and the escape survives extraction.
+                const target = await readlink(path, 'utf8').catch(() => '');
+                const resolved = resolve(dir, target);
+                if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+                    throw new Error(`archive contains a symlink escaping the extraction root: ${entry.name} -> ${target}`);
+                }
+                continue;
+            }
+            if (entry.isDirectory())
+                stack.push(path);
+        }
+    }
+}
+/** Test seam: run the symlink-containment walk against a prepared tree. */
+export const assertNoEscapingSymlinksForTest = assertNoEscapingSymlinks;
+/** If the extraction produced exactly one top-level directory and nothing else, use it as the root. */
+async function unwrapSingleRoot(extractDir) {
+    const entries = await readdir(extractDir, { withFileTypes: true });
+    if (entries.length === 1 && entries[0].isDirectory())
+        return join(extractDir, entries[0].name);
+    return extractDir;
+}
+async function copyTree(from, to) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+        const source = join(from, entry.name);
+        const target = join(to, entry.name);
+        if (entry.isDirectory())
+            await copyTree(source, target);
+        else if (entry.isFile()) {
+            const handle = await open(target, 'w');
+            try {
+                await handle.write(await readFile(source));
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    }
+}
+/** Probe whether a path exists and is a directory. */
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/lib/catalog/git.js

@@ -1,44 +1,117 @@
 /**
- * Git operations for repository sources: clone, pull, head, remove.
+ * Git operations for repository sources: clone, sync, head, remote-url, remove.
  *
  * Every operation runs `git` through `execFile` without a shell, so a source
  * URL or branch can never interpolate into a command string. Failures carry
  * the stderr tail as the message; the manager surfaces them as source errors.
+ *
+ * Network tuning rides one {@link GitOptions} object: a proxy, `insteadOf`
+ * URL rewrites (mirror acceleration), a per-operation timeout, and one
+ * automatic retry for network-flaky clones. Low-speed guards
+ * (`GIT_HTTP_LOW_SPEED_*`) fail a stalled transfer early instead of burning
+ * the whole timeout.
  */
 import { execFile } from 'node:child_process';
 import { rm } from 'node:fs/promises';
 import { promisify } from 'node:util';
 const run = promisify(execFile);
-const DEFAULT_TIMEOUT_MS = 120_000;
-/** Clone a source (depth 1, optional branch) into a not-yet-existing directory. */
-export async function gitClone(url, branch, dest, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    const args = ['clone', '--depth', '1', ...(branch === undefined ? [] : ['--branch', branch]), '--', url, dest];
+export const DEFAULT_GIT_TIMEOUT_MS = 120_000;
+function configArgs(options) {
+    const args = [];
+    if (options.proxy !== undefined && options.proxy !== '') {
+        args.push('-c', `http.proxy=${options.proxy}`, '-c', `https.proxy=${options.proxy}`);
+    }
+    for (const [from, to] of Object.entries(options.insteadOf ?? {})) {
+        if (from === '' || to === '')
+            continue;
+        args.push('-c', `url.${to}.insteadOf=${from}`);
+    }
+    return args;
+}
+function gitEnv() {
+    // Fail early on a stalled transfer; the timeout then catches the remainder.
+    return { ...process.env, GIT_HTTP_LOW_SPEED_LIMIT: '1000', GIT_HTTP_LOW_SPEED_TIME: '30' };
+}
+async function runGit({ args, options, operation, maxBuffer }) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
     try {
-        await run('git', args, { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+        const { stdout } = await run('git', args, { timeout: timeoutMs, maxBuffer: maxBuffer ?? 10 * 1024 * 1024, env: gitEnv() });
+        return stdout;
     }
     catch (error) {
-        throw gitError('clone', error);
+        throw gitError(operation, error);
     }
 }
-/** Fast-forward a checked-out source to its configured branch. */
-export async function gitPull(dir, timeoutMs = DEFAULT_TIMEOUT_MS) {
+/** Clone a source (depth 1, optional branch) into a not-yet-existing directory. */
+export async function gitClone(url, branch, dest, options = {}) {
+    const attempt = () => runGit({
+        args: [...configArgs(options), 'clone', '--depth', '1', '--no-tags', ...(branch === undefined ? [] : ['--branch', branch]), '--', url, dest],
+        options,
+        operation: 'clone'
+    });
+    const retry = options.cloneRetry !== false;
     try {
-        await run('git', ['-C', dir, 'pull', '--ff-only'], { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+        await attempt();
     }
     catch (error) {
-        throw gitError('pull', error);
+        if (!retry)
+            throw error;
+        // One retry: transient network failures are the dominant clone failure
+        // mode; `git clone` cleans its partial target before failing.
+        await attempt();
     }
 }
+/**
+ * Shallow-friendly update: fetch depth 1 into FETCH_HEAD and hard-reset.
+ * `git pull --ff-only` on shallow clones can refuse with history-divergence
+ * errors; fetch+reset is idempotent and always lands on the remote tip. The
+ * local checkout is plugin-managed, so discarding working-tree drift is the
+ * intended semantics.
+ */
+export async function gitSync(dir, branch, options = {}) {
+    const config = configArgs(options);
+    await runGit({ args: [...config, '-C', dir, 'fetch', '--depth', '1', 'origin', branch ?? 'HEAD'], options, operation: 'fetch' });
+    await runGit({ args: [...config, '-C', dir, 'reset', '--hard', 'FETCH_HEAD'], options, operation: 'reset' });
+}
 /** Read the checked-out HEAD commit. */
 export async function gitHead(dir, timeoutMs = 30_000) {
     try {
-        const { stdout } = await run('git', ['-C', dir, 'rev-parse', 'HEAD'], { timeout: timeoutMs });
+        const { stdout } = await run('git', ['-C', dir, 'rev-parse', 'HEAD'], { timeout: timeoutMs, env: gitEnv() });
+        return stdout.trim();
+    }
+    catch (error) {
+        throw gitError('rev-parse', error);
+    }
+}
+/** Read the checked-out branch name (`HEAD` when detached). */
+export async function gitCurrentBranch(dir, timeoutMs = 30_000) {
+    try {
+        const { stdout } = await run('git', ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'], { timeout: timeoutMs, env: gitEnv() });
         return stdout.trim();
     }
     catch (error) {
         throw gitError('rev-parse', error);
     }
 }
+/** Read the checkout's `origin` remote URL; throws when the directory is not a git repository. */
+export async function gitRemoteUrl(dir, timeoutMs = 30_000) {
+    try {
+        const { stdout } = await run('git', ['-C', dir, 'remote', 'get-url', 'origin'], { timeout: timeoutMs, env: gitEnv() });
+        return stdout.trim();
+    }
+    catch (error) {
+        throw gitError('remote', error);
+    }
+}
+/** Point the checkout's `origin` at a new URL (download-region rerouting). */
+export async function gitSetRemoteUrl(dir, url, timeoutMs = 30_000) {
+    try {
+        await run('git', ['-C', dir, 'remote', 'set-url', 'origin', url], { timeout: timeoutMs, env: gitEnv() });
+    }
+    catch (error) {
+        throw gitError('remote', error);
+    }
+}
 /** Remove a source checkout tree entirely. */
 export async function gitRemove(dir) {
     await rm(dir, { recursive: true, force: true });

package/lib/catalog/legacy-root-migration.js

@@ -0,0 +1,51 @@
+/**
+ * One-time migration from the pre-0.5.4 split layout, where suite data and
+ * MCP overrides lived under a sibling `~/.dsh/agent-plugins-data` root: if
+ * that root exists, its `data/` and `overrides/` subtrees move to their
+ * consolidated homes (`<dataRoot>/data` and `<dataRoot>/overrides`, matching
+ * the live resolution) and the emptied sibling is removed. Idempotent — a
+ * missing, empty, or already-migrated legacy root is a no-op — and
+ * best-effort: a filesystem failure leaves both trees in place for a manual
+ * move rather than deleting user data.
+ *
+ * @module
+ */
+import { existsSync } from 'node:fs';
+import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Migrate `data/` and `overrides/` from the legacy sibling root, if present. */
+export async function migrateLegacyDataRoot(legacyRoot, dataRoot) {
+    if (!existsSync(legacyRoot))
+        return;
+    let entries = [];
+    try {
+        entries = await readdir(legacyRoot);
+    }
+    catch {
+        // Unreadable legacy root: leave everything for a manual move.
+        return;
+    }
+    for (const subtree of ['data', 'overrides']) {
+        const from = join(legacyRoot, subtree);
+        if (!entries.includes(subtree) || !existsSync(from))
+            continue;
+        const to = join(dataRoot, subtree);
+        if (existsSync(to)) {
+            // Merge into an existing target: copy contents, then drop the source.
+            await mkdir(to, { recursive: true });
+            for (const entry of await readdir(from)) {
+                await cp(join(from, entry), join(to, entry), { recursive: true, force: false, errorOnExist: false });
+            }
+            await rm(from, { recursive: true, force: true });
+        }
+        else {
+            await mkdir(dataRoot, { recursive: true });
+            await cp(from, to, { recursive: true });
+            await rm(from, { recursive: true, force: true });
+        }
+    }
+    // Remove the legacy root only when nothing else remains inside it.
+    const remaining = await readdir(legacyRoot).catch(() => ['keep']);
+    if (remaining.length === 0)
+        await rm(legacyRoot, { recursive: true, force: true });
+}