dshmarket 1.2.2 → 1.2.3

package/lib/routes.js

@@ -1,426 +1,24 @@
 /**
- * HTTP routes bridging the browser market UI to the host: registry fallback,
- * installed-plugin listing, and the install executor.
+ * HTTP routes bridging the browser market UI to the host. This layer only
+ * parses requests, calls the service modules, and serializes responses —
+ * process spawning lives in dsh-cli.ts, filesystem reads in profile.ts,
+ * orchestration in install.ts / themes.ts / updates.ts.
  *
  * Security: the install route executes a shell command, so it accepts only
  * same-origin POSTs and only sources present in the curated registry.
  */
-import { spawn } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { loadRegistry } from './registry.js';
-import { cleanHotDir, hotMount, hotUnmount, listHotMounts, mountClientOnlyDeps, readDisabledThemes, writeDisabledThemes, } from './hot.js';
+import { cleanHotDir, hotMount, hotUnmount, listHotMounts, mountClientOnlyDeps, readDisabledThemes, } from './hot.js';
 import { exportLogs, logEvent } from './log.js';
+import { BOOT_ID, probePnpm, progress, provisionPnpm, runDshPlugin } from './dsh-cli.js';
+import { profileDir, readInstalled, readInstalledVersion, readLockCommits } from './profile.js';
+import { findInstalledAlias, installTargetFor } from './sources.js';
+import { isStaleUpdate, retargetCollections, validateAddedPlugins, withHoistRecovery } from './install.js';
+import { checkUpdates, invalidateUpdates } from './updates.js';
+import { createThemeManager } from './themes.js';
+import { readJsonBody, sameOrigin, sendJson } from './http.js';
 const PROFILE_RE = /^[A-Za-z0-9_-]+$/;
-const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
-/**
- * Argv re-invoking the CLI that launched this host process, so installs work
- * whether dsh runs from a global bin, a local install, or repo source
- * (`node --import tsx/esm .../bin.ts`). Falls back to a PATH `dsh`.
- *
- * Installs run through node:child_process, not ctx.shell: the shell service is
- * the agent's sandboxed executor and denies writes to the profile directory.
- */
-function dshArgv() {
-    const entry = process.argv[1];
-    if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
-        // Absolute paths are required: source launches (`pnpm dsh`) pass a
-        // relative entry, which the child resolves against its OWN cwd and dies
-        // with MODULE_NOT_FOUND (#13). cwd near the entry keeps execArgv imports
-        // (tsx/esm) resolvable on source launches.
-        const abs = resolve(entry);
-        return { file: process.execPath, args: [...process.execArgv, abs], cwd: dirname(abs), viaShell: false };
-    }
-    // Bare `dsh` is a .cmd shim on Windows that only a shell can start (#13).
-    return { file: 'dsh', args: [], cwd: undefined, viaShell: winCmdShim };
-}
-/** Whether `pnpm` resolves on PATH; success is cached, absence is re-probed. */
-let pnpmReady = false;
-/**
- * Windows npm/corepack/pnpm are `.cmd` shims. Node's `spawn` without a shell
- * cannot start them (ENOENT / EINVAL). Same pattern as dsh's `plugin` forwarder.
- */
-const winCmdShim = process.platform === 'win32';
-/**
- * Kill a spawned child and, on Windows, its whole process tree — `kill()`
- * there only terminates the wrapper, leaving pnpm children running.
- * (Contributed in #7 by @mraing.)
- */
-function killChild(child) {
-    if (process.platform === 'win32' && child.pid !== undefined) {
-        try {
-            spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' });
-            return;
-        }
-        catch { /* fall through */ }
-    }
-    child.kill('SIGKILL');
-}
-function probePnpm() {
-    if (pnpmReady)
-        return Promise.resolve(true);
-    return new Promise((resolvePromise) => {
-        const child = spawn('pnpm', ['--version'], { stdio: 'ignore', shell: winCmdShim });
-        child.on('error', () => resolvePromise(false));
-        child.on('close', (code) => {
-            pnpmReady = code === 0;
-            resolvePromise(pnpmReady);
-        });
-    });
-}
-function runQuiet(file, args, timeoutMs) {
-    return new Promise((resolvePromise) => {
-        const child = spawn(file, args, {
-            env: { ...process.env, CI: 'true' },
-            stdio: ['ignore', 'pipe', 'pipe'],
-            shell: winCmdShim,
-        });
-        let output = '';
-        const timer = setTimeout(() => killChild(child), timeoutMs);
-        const collect = (chunk) => { output = (output + chunk.toString()).slice(-8 * 1024); };
-        child.stdout.on('data', collect);
-        child.stderr.on('data', collect);
-        child.on('error', (error) => { clearTimeout(timer); resolvePromise({ code: 127, output: error.message }); });
-        child.on('close', (code) => { clearTimeout(timer); resolvePromise({ code, output }); });
-    });
-}
-/**
- * Provision pnpm without user involvement: corepack (ships with Node) first,
- * a global npm install as fallback.
- * @returns true when `pnpm --version` succeeds afterwards.
- */
-async function provisionPnpm() {
-    const corepack = await runQuiet('corepack', ['enable', 'pnpm'], 60 * 1000);
-    logEvent(corepack.code === 0 ? 'info' : 'warn', 'setup-pnpm', `corepack enable: exit=${String(corepack.code)} ${corepack.output.slice(-200)}`);
-    if (await probePnpm())
-        return true;
-    const npm = await runQuiet('npm', ['install', '-g', 'pnpm'], 3 * 60 * 1000);
-    logEvent(npm.code === 0 ? 'info' : 'error', 'setup-pnpm', `npm -g: exit=${String(npm.code)} ${npm.output.slice(-200)}`);
-    return probePnpm();
-}
-const progress = { active: false, target: '', startedAt: 0, lastLine: '' };
-/** Identifies this host process; the client scopes its pending-restart flags to it. */
-const BOOT_ID = `${String(process.pid)}-${String(Date.now())}`;
-function trackProgress(chunk) {
-    const lines = chunk.split('\n').map(l => l.trim()).filter(l => l !== '');
-    if (lines.length > 0)
-        progress.lastLine = lines[lines.length - 1].slice(0, 200);
-}
-/**
- * Central allowlist for every spawn target, regardless of which route built
- * it (defense in depth on top of per-route validation — the win32 bare-dsh
- * fallback runs through a shell). Suggested in #16 by @anupamme.
- */
-const TARGET_RE = /^[A-Za-z0-9@:./_#+-]+$/;
-function runDshPlugin(profile, pluginArgs) {
-    const { file, args, cwd, viaShell } = dshArgv();
-    // pnpm 9 refuses to add at a workspace root without -w (#17); pnpm 10/11
-    // accept the flag as a no-op there, so it is safe to pass always.
-    if (pluginArgs[0] === 'add' || pluginArgs[0] === 'remove') {
-        pluginArgs = [pluginArgs[0], '-w', ...pluginArgs.slice(1)];
-    }
-    const target = pluginArgs[pluginArgs.length - 1] ?? '';
-    if (!TARGET_RE.test(target)) {
-        logEvent('error', 'install', `unsafe plugin target rejected: ${JSON.stringify(target)}`);
-        return Promise.resolve({ exitCode: 1, timedOut: false, stdout: '', stderr: `unsafe plugin target rejected: ${JSON.stringify(target)}` });
-    }
-    progress.active = true;
-    progress.target = target;
-    progress.startedAt = Date.now();
-    progress.lastLine = '';
-    return new Promise((resolvePromise) => {
-        const child = spawn(file, [...args, 'plugin', '--profile', profile, ...pluginArgs], {
-            cwd,
-            // pnpm v10 blocks forever on a silent interactive prompt without a TTY
-            // (observed on re-add over a pinned git spec); CI mode forces it to act
-            // or fail instead of asking.
-            env: { ...process.env, CI: 'true' },
-            stdio: ['ignore', 'pipe', 'pipe'],
-            shell: viaShell,
-        });
-        let stdout = '';
-        let stderr = '';
-        let timedOut = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            killChild(child);
-        }, INSTALL_TIMEOUT_MS);
-        child.stdout.on('data', (chunk) => {
-            const text = chunk.toString();
-            stdout = (stdout + text).slice(-256 * 1024);
-            trackProgress(text);
-        });
-        child.stderr.on('data', (chunk) => {
-            const text = chunk.toString();
-            stderr = (stderr + text).slice(-64 * 1024);
-            trackProgress(text);
-        });
-        child.on('error', (error) => {
-            clearTimeout(timer);
-            progress.active = false;
-            resolvePromise({ exitCode: 127, timedOut: false, stdout, stderr: `${stderr}\n${error.message}` });
-        });
-        child.on('close', (code) => {
-            clearTimeout(timer);
-            progress.active = false;
-            resolvePromise({ exitCode: code, timedOut, stdout, stderr });
-        });
-    });
-}
-function sendJson(response, status, payload) {
-    response.writeHead(status, {
-        'cache-control': 'no-store',
-        'content-type': 'application/json; charset=utf-8',
-    });
-    response.end(JSON.stringify(payload));
-}
-function sameOrigin(request) {
-    const origin = request.headers.origin;
-    const host = request.headers.host;
-    if (origin === undefined || host === undefined)
-        return false;
-    try {
-        return new URL(origin).host === host;
-    }
-    catch {
-        return false;
-    }
-}
-async function readJsonBody(request) {
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buffer.length;
-        if (size > 4096)
-            throw new Error('request body too large');
-        chunks.push(buffer);
-    }
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-}
-function profileDir(profile) {
-    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
-    return join(home, 'profiles', profile);
-}
-/** Community dependencies of the profile (official in-box scope filtered out). */
-function readInstalled(profile) {
-    try {
-        const manifest = JSON.parse(readFileSync(join(profileDir(profile), 'package.json'), 'utf8'));
-        const installed = {};
-        for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
-            if (!name.startsWith('@deepseek-ai/'))
-                installed[name] = spec;
-        }
-        return installed;
-    }
-    catch {
-        return {};
-    }
-}
-/** GitHub `owner/repo` for a registry URL, or null when it is not a GitHub repo URL. */
-/**
- * Parse a registry source url: a github repo, optionally with a
- * `/tree/<branch>/<subpath>` suffix (how the curated list links monorepo
- * subpackages, e.g. dsh-plugins#theme-gallery).
- */
-function parseSourceUrl(url) {
-    const m = /^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\/tree\/[^/]+\/(.+?))?\/?$/.exec(url);
-    if (m === null || !REPO_RE.test(m[1]))
-        return null;
-    const subpath = m[2] ?? null;
-    if (subpath !== null && !/^[A-Za-z0-9_./-]+$/.test(subpath))
-        return null;
-    return { repo: m[1], subpath };
-}
-function repoOf(url) {
-    return parseSourceUrl(url)?.repo ?? null;
-}
-/** Pinned commit per `owner/repo` from the profile lockfile's codeload tarball URLs. */
-function readLockCommits(profile) {
-    const commits = new Map();
-    try {
-        const lock = readFileSync(join(profileDir(profile), 'pnpm-lock.yaml'), 'utf8');
-        for (const m of lock.matchAll(/codeload\.github\.com\/([^/\s]+\/[^/\s]+)\/tar\.gz\/([0-9a-f]{40})/g)) {
-            commits.set(m[1].toLowerCase(), m[2]);
-        }
-    }
-    catch { /* no lockfile — no git installs to report */ }
-    return commits;
-}
-/**
- * Some registry entries point at collection repos whose actual plugin lives
- * in a subdirectory — the root has no package.json, and pnpm installs the
- * bare fileset with exit 0. Detect that junk install, drop it, and re-add
- * each plugin subdirectory through pnpm's `#path:` selector.
- * @returns overall success (true when nothing needed retargeting).
- */
-/**
- * True when the package's declared entry artifact actually exists — github
- * source checkouts of build-required plugins ship no lib/, and promoting one
- * into the bundle layer bricks the next boot (ERR_MODULE_NOT_FOUND kills the
- * whole profile, #18).
- */
-function entryArtifactExists(dir) {
-    try {
-        const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-        const candidates = [];
-        if (typeof manifest.main === 'string')
-            candidates.push(manifest.main);
-        const rootExport = typeof manifest.exports === 'string'
-            ? manifest.exports
-            : manifest.exports?.['.'];
-        if (typeof rootExport === 'string')
-            candidates.push(rootExport);
-        else if (rootExport !== null && typeof rootExport === 'object') {
-            for (const value of Object.values(rootExport))
-                if (typeof value === 'string')
-                    candidates.push(value);
-        }
-        if (candidates.length === 0)
-            candidates.push('index.js');
-        return candidates.some(rel => existsSync(join(dir, rel)));
-    }
-    catch {
-        return false;
-    }
-}
-/** True when the installed package's manifest declares a dsh plugin surface. */
-function hasDshManifest(dir) {
-    try {
-        const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-        return manifest.dsh !== undefined;
-    }
-    catch {
-        return false;
-    }
-}
-/** Plugin subdirectories (depth 2) of a collection checkout, as relative paths. */
-function pluginSubdirs(root) {
-    const found = [];
-    let level1 = [];
-    try {
-        level1 = readdirSync(root, { withFileTypes: true })
-            .filter(dirent => dirent.isDirectory() && /^[A-Za-z0-9_.-]+$/.test(dirent.name) && dirent.name !== 'node_modules')
-            .map(dirent => dirent.name);
-    }
-    catch {
-        return found;
-    }
-    for (const sub of level1) {
-        if (hasDshManifest(join(root, sub))) {
-            found.push(sub);
-            continue;
-        }
-        try {
-            for (const inner of readdirSync(join(root, sub), { withFileTypes: true })) {
-                if (!inner.isDirectory() || !/^[A-Za-z0-9_.-]+$/.test(inner.name) || inner.name === 'node_modules')
-                    continue;
-                if (hasDshManifest(join(root, sub, inner.name)))
-                    found.push(`${sub}/${inner.name}`);
-            }
-        }
-        catch { /* unreadable level — skip */ }
-        if (found.length >= 8)
-            break;
-    }
-    return found.slice(0, 8);
-}
-async function retargetCollections(profile, before, target) {
-    if (!target.startsWith('github:'))
-        return true;
-    // A collection checkout: no root package.json at all, or a root manifest
-    // that declares no dsh surface (workspace roots are usually also private
-    // with no entry point — #18).
-    const junk = Object.keys(readInstalled(profile)).filter((name) => {
-        if (before.has(name))
-            return false;
-        const root = join(profileDir(profile), 'node_modules', name);
-        if (!existsSync(join(root, 'package.json')))
-            return true;
-        return !hasDshManifest(root);
-    });
-    let allOk = true;
-    for (const name of junk) {
-        const root = join(profileDir(profile), 'node_modules', name);
-        const candidates = pluginSubdirs(root);
-        logEvent('info', 'install', `${name}: collection repo (root declares no dsh manifest); plugins inside: ${candidates.join(', ') || 'none'}`);
-        await runDshPlugin(profile, ['remove', name]);
-        if (candidates.length === 0) {
-            allOk = false;
-            continue;
-        }
-        for (const sub of candidates) {
-            const result = await runDshPlugin(profile, ['add', `${target}#path:/${sub}`]);
-            if (result.exitCode !== 0 || result.timedOut) {
-                allOk = false;
-                logEvent('error', 'install', `${target}#path:/${sub}: exit=${String(result.exitCode)}${result.timedOut ? ' TIMEOUT' : ''} — ${(result.stderr || result.stdout).slice(-220)}`);
-            }
-        }
-    }
-    return allOk;
-}
-function readInstalledVersion(profile, name) {
-    try {
-        const manifest = JSON.parse(readFileSync(join(profileDir(profile), 'node_modules', name, 'package.json'), 'utf8'));
-        return manifest.version ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-const UPDATES_TTL_MS = 30 * 60 * 1000;
-let updatesCache = null;
-async function fetchJson(url) {
-    const res = await fetch(url, {
-        headers: { accept: 'application/json', 'user-agent': 'dsh-market' },
-        signal: AbortSignal.timeout(4000),
-    });
-    if (!res.ok)
-        throw new Error(`HTTP ${res.status}`);
-    return res.json();
-}
-/** Per-plugin update checks; a failed check reports no update rather than failing the listing. */
-async function checkUpdates(profile, force = false) {
-    if (!force && updatesCache && Date.now() - updatesCache.at < UPDATES_TTL_MS)
-        return updatesCache.data;
-    const installed = readInstalled(profile);
-    const lockCommits = readLockCommits(profile);
-    const result = {};
-    await Promise.all(Object.entries(installed).map(async ([name, spec]) => {
-        const version = readInstalledVersion(profile, name);
-        if (spec.startsWith('link:') || spec.startsWith('file:')) {
-            result[name] = { kind: 'linked', version, current: null, latest: null, updateAvailable: false };
-            return;
-        }
-        const gh = /^(?:github:)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:#.*)?$/.exec(spec);
-        try {
-            if (spec.startsWith('github:') && gh !== null) {
-                const current = lockCommits.get(gh[1].toLowerCase()) ?? null;
-                const head = (await fetchJson(`https://api.github.com/repos/${gh[1]}/commits/HEAD`));
-                const latest = typeof head.sha === 'string' ? head.sha : null;
-                result[name] = {
-                    kind: 'github', version, current, latest,
-                    updateAvailable: current !== null && latest !== null && current !== latest,
-                };
-            }
-            else {
-                const meta = (await fetchJson(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`));
-                const latest = typeof meta.version === 'string' ? meta.version : null;
-                result[name] = {
-                    kind: 'npm', version, current: version, latest,
-                    updateAvailable: version !== null && latest !== null && version !== latest,
-                };
-            }
-        }
-        catch {
-            result[name] = { kind: spec.startsWith('github:') ? 'github' : 'npm', version, current: null, latest: null, updateAvailable: false };
-        }
-    }));
-    updatesCache = { at: Date.now(), data: result };
-    return result;
-}
 /**
  * Register the market's HTTP routes.
  * @param host - Acquired webServer + shell services.
@@ -434,11 +32,12 @@ export function mountMarketRoutes(host, config) {
     // Boot-time wipe: stale hot-mount inputs from a previous session must never
     // survive into a composition where the bundle layer already covers them.
     cleanHotDir(profileDir(config.profile));
+    // The user's persisted theme choice; activateTheme mutates and writes it.
+    const disabledThemes = readDisabledThemes(profileDir(config.profile));
+    const themes = createThemeManager(host, config.profile, disabledThemes);
     // Client-only packages (dsh.client without dsh.bundle) are invisible to the
     // bundle layer in every boot; the market shim-mounts them so their client
     // bundles are actually served.
-    // The user's persisted theme choice; activateTheme mutates and writes it.
-    const disabledThemes = readDisabledThemes(profileDir(config.profile));
     void mountClientOnlyDeps(host, profileDir(config.profile)).then(async (mounted) => {
         if (mounted.length > 0)
             logEvent('info', 'boot', `client-only shims mounted: ${mounted.join(', ')}`);
@@ -446,7 +45,7 @@ export function mountMarketRoutes(host, config) {
         // from get live-disabled again (bundle trees are in-memory, so the
         // disable never persists on its own).
         for (const name of disabledThemes) {
-            if (await setEntryDisabled(name, true))
+            if (await themes.setEntryDisabled(name, true))
                 logEvent('info', 'boot', `theme kept off: ${name}`);
         }
     });
@@ -456,92 +55,11 @@ export function mountMarketRoutes(host, config) {
     host.on?.('internal/plugin', (fiber) => {
         const name = fiber.entry?.options?.name;
         if (name !== undefined && disabledThemes.has(name))
-            void setEntryDisabled(name, true);
+            void themes.setEntryDisabled(name, true);
     });
     let installing = false;
-    /** Installed package names classified as themes by the registry's theme category. */
-    async function installedThemeNames(profile) {
-        const names = new Set();
-        try {
-            const { registry } = await loadRegistry();
-            const themeEntries = registry.plugins.filter(p => p.category === 'theme');
-            const themeNames = new Set(themeEntries.map(p => p.name));
-            const themeRepos = new Set(themeEntries.map(p => repoOf(p.url)).filter((r) => r !== null).map(r => r.toLowerCase()));
-            for (const [name, spec] of Object.entries(readInstalled(profile))) {
-                if (themeNames.has(name)) {
-                    names.add(name);
-                    continue;
-                }
-                const match = /github:([^#\s]+)/.exec(String(spec).toLowerCase());
-                if (match !== null && themeRepos.has(match[1]))
-                    names.add(name);
-            }
-        }
-        catch { /* registry unavailable — nothing classifies as a theme */ }
-        return names;
-    }
-    /**
-     * Live-toggle a bundle-layer plugin through its loader entry. Bundle trees
-     * are in-memory (write is a no-op), so this never touches any file — the
-     * market persists the choice itself and replays it at boot.
-     * @returns true when a matching live entry was found and updated.
-     */
-    async function setEntryDisabled(name, disabledFlag) {
-        let found = false;
-        for (const entry of host.loader.entries()) {
-            if (entry.options.name !== name)
-                continue;
-            // A disable can land while the entry's init is still in flight: the
-            // options flip but the finishing init brings the fiber up anyway, and a
-            // plain re-update no-ops on the empty diff. Force the update and verify
-            // the live state, retrying until reality matches the flag.
-            for (let attempt = 0; attempt < 3; attempt++) {
-                try {
-                    await entry.update({ disabled: disabledFlag ? true : null }, false, true);
-                    found = true;
-                }
-                catch (error) {
-                    logEvent('warn', 'toggle', `${name}: entry update failed — ${error instanceof Error ? error.message : String(error)}`);
-                    break;
-                }
-                const live = entry.fiber !== undefined;
-                if (live !== disabledFlag)
-                    break;
-                await new Promise(resolvePromise => setTimeout(resolvePromise, 200));
-            }
-            logEvent('info', 'toggle', `${name} -> ${disabledFlag ? 'off' : 'on'}: fiber=${String(entry.fiber !== undefined)}`);
-        }
-        if (!found)
-            logEvent('info', 'toggle', `${name}: no loader entry matched`);
-        return found;
-    }
-    /**
-     * Make `name` the one active theme: deactivate every other installed theme
-     * (market hot mounts unmount; bundle-layer entries live-disable) and bring
-     * it up. The choice persists in state.json and is replayed at boot.
-     */
-    async function activateTheme(name) {
-        const dir = profileDir(config.profile);
-        const themes = await installedThemeNames(config.profile);
-        for (const other of themes) {
-            if (other === name)
-                continue;
-            if (listHotMounts().includes(other)) {
-                await hotUnmount(other);
-                disabledThemes.add(other);
-            }
-            else if (await setEntryDisabled(other, true)) {
-                disabledThemes.add(other);
-            }
-        }
-        disabledThemes.delete(name);
-        writeDisabledThemes(dir, disabledThemes);
-        if (listHotMounts().includes(name))
-            return true;
-        if (await setEntryDisabled(name, false))
-            return true;
-        return hotMount(host, dir, name);
-    }
+    /** Every plugin command goes through the pnpm-drift recovery wrapper (#20). */
+    const runPlugin = (profile, args) => withHoistRecovery(runDshPlugin, profile, args);
     const disposers = [
         host.webServer.register({
             kind: 'exact',
@@ -594,12 +112,12 @@ export function mountMarketRoutes(host, config) {
                     const body = (await readJsonBody(request));
                     const name = typeof body.name === 'string' ? body.name : '';
                     const installed = readInstalled(config.profile);
-                    const themes = await installedThemeNames(config.profile);
-                    if (installed[name] === undefined || !themes.has(name)) {
+                    const themeNames = await themes.installedThemeNames();
+                    if (installed[name] === undefined || !themeNames.has(name)) {
                         sendJson(response, 400, { error: 'not an installed theme' });
                         return;
                     }
-                    const activated = await activateTheme(name);
+                    const activated = await themes.activateTheme(name);
                     logEvent(activated ? 'info' : 'error', 'use-skin', `${name}: ${activated ? 'active' : 'failed'}`);
                     sendJson(response, activated ? 200 : 502, { ok: activated, live: listHotMounts() });
                 }
@@ -695,6 +213,7 @@ export function mountMarketRoutes(host, config) {
                 try {
                     const body = (await readJsonBody(request));
                     const name = typeof body.name === 'string' ? body.name : '';
+                    const force = body.force === true;
                     const spec = readInstalled(config.profile)[name];
                     if (spec === undefined) {
                         sendJson(response, 400, { error: 'plugin is not installed' });
@@ -713,29 +232,32 @@ export function mountMarketRoutes(host, config) {
                     const beforeCommit = repoKey !== null ? readLockCommits(config.profile).get(repoKey) ?? null : null;
                     installing = true;
                     try {
-                        const result = await runDshPlugin(config.profile, ['add', target]);
+                        // force: the user chose to install a fresh release without the
+                        // default one-day safety wait; scoped to this single command.
+                        const addArgs = force ? ['add', '--config.minimumReleaseAge=0', target] : ['add', target];
+                        const result = await runPlugin(config.profile, addArgs);
                         let ok = result.exitCode === 0 && !result.timedOut;
                         let stale = false;
                         if (ok) {
-                            // pnpm's minimumReleaseAge silently keeps the old version and
-                            // exits 0 when the new release is "too young" (#13) — a clean
-                            // exit alone does not mean the update happened.
-                            const afterVersion = readInstalledVersion(config.profile, name);
-                            const afterCommit = repoKey !== null ? readLockCommits(config.profile).get(repoKey) ?? null : null;
-                            stale = isGit
-                                ? beforeCommit !== null && afterCommit === beforeCommit
-                                : beforeVersion !== null && afterVersion === beforeVersion;
+                            stale = isStaleUpdate({
+                                isGit,
+                                beforeVersion,
+                                afterVersion: readInstalledVersion(config.profile, name),
+                                beforeCommit,
+                                afterCommit: repoKey !== null ? readLockCommits(config.profile).get(repoKey) ?? null : null,
+                            });
                             if (stale)
                                 ok = false;
                         }
                         if (ok)
-                            updatesCache = null;
+                            invalidateUpdates();
                         const staleError = stale
-                            ? `still v${beforeVersion ?? beforeCommit?.slice(0, 7) ?? '?'} after the update — pnpm 的 minimumReleaseAge 安全策略会暂时拦下发布不久的新版本（静默保留旧版且返回成功）。请稍后再试；着急可调整 profile pnpm-workspace.yaml 的 minimumReleaseAge / pnpm's minimumReleaseAge holds back very fresh releases; retry later or tune it in the profile's pnpm-workspace.yaml`
+                            ? '这个新版本刚发布不久。为了安全，系统默认会等它发布满一天后再安装——刚发布的版本偶尔会被发现问题然后撤回。可以明天再试，或点「立即更新」不再等待。 / This version was just released; for safety, installs normally wait about a day after a release. Try again tomorrow, or click "Update now" to install it right away.'
                             : null;
                         logEvent(ok ? 'info' : 'error', 'update', `${name} -> ${target} exit=${String(result.exitCode)}${result.timedOut ? ' TIMEOUT' : ''}${stale ? ' STALE(minimumReleaseAge?)' : ''}${ok ? '' : ` stderr=${result.stderr.slice(-300)}`}`);
                         sendJson(response, ok ? 200 : 502, {
                             ok,
+                            stale: stale || undefined,
                             error: staleError ?? undefined,
                             exitCode: result.exitCode,
                             timedOut: result.timedOut,
@@ -807,11 +329,11 @@ export function mountMarketRoutes(host, config) {
                     }
                     installing = true;
                     try {
-                        const result = await runDshPlugin(config.profile, ['remove', name]);
+                        const result = await runPlugin(config.profile, ['remove', name]);
                         const ok = result.exitCode === 0 && !result.timedOut;
                         let hot = false;
                         if (ok) {
-                            updatesCache = null;
+                            invalidateUpdates();
                             hot = await hotUnmount(name);
                         }
                         logEvent(ok ? 'info' : 'error', 'uninstall', `${name} exit=${String(result.exitCode)}${ok ? ` live-removed=${String(hot)}` : ` stderr=${result.stderr.slice(-300)}`}`);
@@ -863,59 +385,48 @@ export function mountMarketRoutes(host, config) {
                         sendJson(response, 400, { error: 'plugin is not in the curated registry' });
                         return;
                     }
-                    const source = parseSourceUrl(entry.url);
-                    if (source === null) {
+                    const target = installTargetFor(entry);
+                    if (target === null) {
                         sendJson(response, 400, { error: 'unsupported source url' });
                         return;
                     }
-                    const repo = source.repo;
-                    // Registry tarballs beat full-repo GitHub downloads: smaller,
-                    // prebuilt, and CDN/mirror served. The npm name comes from our
-                    // curated registry, which only maps repo-verified packages.
-                    const NPM_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
-                    const target = typeof entry.npm === 'string' && NPM_NAME_RE.test(entry.npm)
-                        ? entry.npm
-                        : source.subpath !== null
-                            ? `github:${repo}#path:/${source.subpath}`
-                            : `github:${repo}`;
+                    // Duplicate guard (#27): the same plugin listed under another name
+                    // (an alias entry pointing at the same repo) must never install
+                    // twice — two loader entries with one id brick the next boot.
+                    // Monorepo subpath entries (distinct plugins in one repo) pass:
+                    // their entry urls differ by subpath and identity is name-based.
+                    const aliasOf = findInstalledAlias(entry, readInstalled(config.profile));
+                    if (aliasOf !== null) {
+                        logEvent('warn', 'install-rejected', `${entry.name}: same plugin already installed as ${aliasOf}`);
+                        sendJson(response, 400, { error: `已以「${aliasOf}」安装过同一个插件，无需重复安装 / this plugin is already installed as "${aliasOf}"` });
+                        return;
+                    }
                     installing = true;
                     try {
                         const before = new Set(Object.keys(readInstalled(config.profile)));
-                        const result = await runDshPlugin(config.profile, ['add', target]);
+                        const result = await runPlugin(config.profile, ['add', target]);
                         let ok = result.exitCode === 0 && !result.timedOut;
                         if (ok)
-                            updatesCache = null;
+                            invalidateUpdates();
                         if (ok) {
                             // Collection repos (e.g. skin monorepos) install as a junk
                             // fileset with no root package.json; retarget to the real
                             // plugin subdirectories via pnpm's #path: selector.
-                            ok = await retargetCollections(config.profile, before, target);
+                            ok = await retargetCollections(runPlugin, config.profile, before, target);
                         }
                         // Fake-success guard (#18): a clean exit that added nothing
-                        // installable must not read as success — and a plugin whose entry
-                        // artifact is missing (source-only checkout, build blocked) would
-                        // brick the next boot, so it is removed on the spot.
+                        // installable must not read as success. Runs even when
+                        // retargeting partially failed — a broken piece that slipped in
+                        // must never survive to brick the next boot.
                         let notAPlugin = false;
                         let removedBroken = [];
-                        // Runs even when retargeting partially failed — a broken piece
-                        // that slipped in must never survive to brick the next boot.
                         if (result.exitCode === 0 && !result.timedOut) {
-                            const addedNow = Object.keys(readInstalled(config.profile)).filter(n => !before.has(n));
-                            const keep = [];
-                            for (const n of addedNow) {
-                                const dir = join(profileDir(config.profile), 'node_modules', n);
-                                if (hasDshManifest(dir) && entryArtifactExists(dir)) {
-                                    keep.push(n);
-                                }
-                                else {
-                                    removedBroken.push(n);
-                                    await runDshPlugin(config.profile, ['remove', n]);
-                                }
-                            }
+                            const validated = await validateAddedPlugins(runPlugin, config.profile, before);
+                            removedBroken = validated.removedBroken;
                             if (removedBroken.length > 0) {
                                 logEvent('warn', 'install', `${target}: removed uninstallable pieces (no dsh manifest or missing build artifacts): ${removedBroken.join(', ')}`);
                             }
-                            if (keep.length === 0) {
+                            if (validated.keep.length === 0) {
                                 ok = false;
                                 notAPlugin = true;
                                 logEvent('error', 'install', `${target}: nothing installable survived validation`);
@@ -935,7 +446,7 @@ export function mountMarketRoutes(host, config) {
                                 hot = true;
                                 for (const name of added) {
                                     const live = entry.category === 'theme'
-                                        ? await activateTheme(name)
+                                        ? await themes.activateTheme(name)
                                         : await hotMount(host, profileDir(config.profile), name);
                                     if (!live)
                                         hot = false;