dsh-m 0.1.0 → 0.2.0

package/lib/core/npm-integrity.js

@@ -0,0 +1,141 @@
+/**
+ * npm integrity（DESIGN.md §3 基线扩展）：pnpm lockfile v9 的包/version integrity 定位、
+ * 与 npm dist metadata 的比对断言、以及安装失败时的 best-effort manifest/lock 快照恢复。
+ * 只用 Node 内置代码；无法唯一定位 package/version/integrity 时 fail closed。
+ * 不声称 node_modules 与间接依赖已字节级回滚——这是 best-effort dependency rollback。
+ */
+import { readFile, rename, rm, open, mkdir } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { dirname } from 'node:path';
+function unquote(key) {
+    if (key.length >= 2 && ((key.startsWith("'") && key.endsWith("'")) || (key.startsWith('"') && key.endsWith('"')))) {
+        return key.slice(1, -1);
+    }
+    return key;
+}
+/**
+ * 解析 pnpm lockfile v9 的 packages 区块。结构（2 空格缩进层级）：
+ *   packages:
+ *     name@1.2.3:
+ *       resolution: {integrity: sha512-..., tarball: ...}
+ *     '@scope/name@1.2.3(peer@2.0.0)':
+ *       resolution: {...}
+ */
+function parsePackagesSection(lockText) {
+    const lines = lockText.split(/\r?\n/);
+    const versionLine = lines.find((l) => /^lockfileVersion:/.test(l.trim()));
+    const rawVersion = versionLine ? versionLine.split(':').slice(1).join(':').trim().replace(/^['"]|['"]$/g, '') : '';
+    if (rawVersion !== '9.0') {
+        throw new Error(`pnpm lockfile 版本不是 9.0（实际 ${rawVersion || '缺失'}），拒绝解析`);
+    }
+    const packagesIdx = lines.findIndex((l) => l.trim() === 'packages:');
+    if (packagesIdx === -1)
+        return new Map();
+    const entries = new Map();
+    let i = packagesIdx + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        const indent = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            i += 1;
+            continue;
+        }
+        if (indent < 2 || (indent === 0 && trimmed !== ''))
+            break;
+        if (indent !== 2 || !trimmed.endsWith(':')) {
+            i += 1;
+            continue;
+        }
+        const key = unquote(trimmed.slice(0, -1));
+        if (entries.has(key))
+            throw new Error(`pnpm lockfile packages 键重复: ${key}`);
+        // 读取该条目区块直到下一条同级键
+        let integrity = null;
+        i += 1;
+        while (i < lines.length) {
+            const inner = lines[i];
+            const innerIndent = inner.length - inner.trimStart().length;
+            if (inner.trim() !== '' && innerIndent <= 2)
+                break;
+            const m = /(?:^|[,{]\s*)integrity:\s*([^,}\s'"]+)/.exec(inner);
+            if (m && integrity === null)
+                integrity = m[1];
+            i += 1;
+        }
+        entries.set(key, { key, integrity });
+    }
+    return entries;
+}
+/**
+ * 定位 lockfile 中 pkg@version 的 resolution.integrity。
+ * peer suffix（`(peer@x)`）仅在其剥离后唯一时接受；多个候选 integrity 不一致、
+ * lockfile 版本不支持、键重复等一律 throw（fail closed）。找不到返回 null。
+ */
+export function readPnpmLockIntegrity(lockText, pkg, version) {
+    const entries = parsePackagesSection(lockText);
+    const target = `${pkg}@${version}`;
+    const matches = [...entries.values()].filter((entry) => {
+        if (!entry.key.startsWith(target))
+            return false;
+        const rest = entry.key.slice(target.length);
+        return rest === '' || rest.startsWith('(');
+    });
+    if (matches.length === 0)
+        return null;
+    const integrities = new Set(matches.map((m) => m.integrity));
+    if (integrities.size > 1 || (matches.length > 1 && integrities.has(null))) {
+        throw new Error(`无法唯一定位 ${target} 的 integrity（${matches.length} 个候选解析结果不一致），fail closed`);
+    }
+    return matches[0].integrity;
+}
+/** 比对 npm dist integrity 与 lockfile 实际值：缺失或不一致都 throw。 */
+export function assertNpmIntegrity(expected, actual, pkg, version) {
+    if (!expected)
+        throw new Error(`npm metadata 缺少 dist integrity：${pkg}@${version}`);
+    if (!actual)
+        throw new Error(`pnpm lockfile 中找不到 ${pkg}@${version} 的 resolution.integrity`);
+    if (actual !== expected) {
+        throw new Error(`integrity 不一致：${pkg}@${version} 期望 ${expected}，lockfile 实际 ${actual}`);
+    }
+}
+async function atomicWriteFile(path, bytes) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.restore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    const fh = await open(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+    try {
+        await fh.write(bytes);
+        await fh.sync();
+    }
+    finally {
+        await fh.close().catch(() => undefined);
+    }
+    await rm(path, { force: true });
+    await rename(tmp, path);
+}
+/** 记录 profile 关键文件的字节快照（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）。 */
+export async function snapshotFiles(paths) {
+    return Promise.all(paths.map(async (path) => {
+        try {
+            const bytes = await readFile(path);
+            return { path, existed: true, bytes };
+        }
+        catch {
+            return { path, existed: false, bytes: null };
+        }
+    }));
+}
+/**
+ * 恢复快照：原先存在的文件原样写回（原子 rename）；原先不存在的删除安装过程中
+ * 新生成的文件。恢复动作本身失败由调用方汇总报告。
+ */
+export async function restoreSnapshots(snapshots) {
+    for (const snap of snapshots) {
+        if (snap.existed && snap.bytes !== null) {
+            await atomicWriteFile(snap.path, snap.bytes);
+        }
+        else {
+            await rm(snap.path, { force: true });
+        }
+    }
+}

package/lib/core/progress.js

@@ -0,0 +1,113 @@
+/**
+ * pnpm `--reporter=ndjson` 进度解析器。移植自 skillhub ndjson.ts（零依赖）。
+ * stdout 每行一个 JSON 对象；人类可读的回退行由 spawn 层处理。
+ */
+export function emptyProgress() {
+    return {
+        phase: null,
+        done: 0,
+        total: null,
+        currentPackage: null,
+        downloaded: null,
+        size: null,
+        seen: false,
+        error: null,
+    };
+}
+export function createProgressTracker() {
+    const snap = emptyProgress();
+    const seenPackages = new Set();
+    function dedupe(packageId) {
+        if (typeof packageId !== 'string' || packageId === '')
+            return;
+        if (!seenPackages.has(packageId)) {
+            seenPackages.add(packageId);
+            snap.done += 1;
+        }
+    }
+    function feed(line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof event !== 'object' || event === null)
+            return;
+        const msg = event;
+        const name = msg.name;
+        if (typeof name !== 'string')
+            return;
+        if (name === 'pnpm:stage') {
+            const stage = msg.stage;
+            if (stage === 'resolution_started')
+                snap.phase = 'resolving';
+            else if (stage === 'resolution_done')
+                snap.phase = 'downloading';
+            else if (stage === 'importing_started' || stage === 'importing_done')
+                snap.phase = 'linking';
+            snap.seen = true;
+            return;
+        }
+        if (name === 'pnpm:progress') {
+            snap.seen = true;
+            const status = msg.status;
+            if (status === 'resolved') {
+                if (snap.phase === null)
+                    snap.phase = 'resolving';
+                dedupe(msg.packageId);
+            }
+            else if (status === 'fetched' || status === 'found_in_store') {
+                snap.phase = 'downloading';
+                snap.currentPackage = typeof msg.packageId === 'string' ? msg.packageId : snap.currentPackage;
+                dedupe(msg.packageId);
+            }
+            return;
+        }
+        if (name === 'pnpm:fetching-progress') {
+            snap.seen = true;
+            snap.phase = 'downloading';
+            if (typeof msg.packageId === 'string')
+                snap.currentPackage = msg.packageId;
+            if (typeof msg.size === 'number')
+                snap.size = msg.size;
+            if (typeof msg.downloaded === 'number')
+                snap.downloaded = msg.downloaded;
+            dedupe(msg.packageId);
+            return;
+        }
+        if (name === 'pnpm:lifecycle') {
+            snap.seen = true;
+            snap.phase = 'building';
+            const wd = typeof msg.wd === 'string' ? msg.wd : '';
+            const dep = typeof msg.depPath === 'string' ? msg.depPath : '';
+            const base = wd.split(/[\\/]/).filter(Boolean).pop();
+            snap.currentPackage = base ?? (dep !== '' ? dep : snap.currentPackage);
+            return;
+        }
+        if (name === 'pnpm:stats') {
+            if (msg.added !== undefined || msg.removed !== undefined)
+                snap.phase = 'linking';
+            snap.seen = true;
+            return;
+        }
+        if (name === 'pnpm' && msg.level === 'error') {
+            const err = (msg.err ?? {});
+            const message = typeof err.message === 'string' ? err.message : '';
+            if (message !== '')
+                snap.error = message.slice(0, 400);
+        }
+    }
+    function reset() {
+        seenPackages.clear();
+        Object.assign(snap, emptyProgress());
+    }
+    return {
+        get snapshot() {
+            return { ...snap };
+        },
+        feed,
+        reset,
+    };
+}

package/lib/core/registry-check.js

@@ -0,0 +1,111 @@
+import { isReachable } from './httpx.js';
+import { githubLatestTag, npmLatest } from './versions.js';
+const MAX_ISSUES = 100;
+const DEFAULT_CONCURRENCY = 8;
+const MAX_CONCURRENCY = 8;
+const DEFAULT_DEADLINE_MS = 60_000;
+const FIELD_ORDER = ['npm', 'github', 'homepage', 'icon'];
+function normalizeConcurrency(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_CONCURRENCY;
+    return Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(raw)));
+}
+export function defaultRegistryCheckDeps() {
+    return {
+        npmLatest: (pkg, timeoutMs, signal) => npmLatest(pkg, timeoutMs, signal),
+        githubLatestTag: (repo, timeoutMs, signal) => githubLatestTag(repo, timeoutMs, signal),
+        reachable: (url, timeoutMs, signal) => isReachable(url, timeoutMs, signal),
+    };
+}
+function collectProbes(registry, deps) {
+    const probes = [];
+    registry.plugins.forEach((entry, entryIndex) => {
+        const push = (field, run) => {
+            probes.push({ id: entry.id, field, entryIndex, fieldIndex: FIELD_ORDER.indexOf(field), run });
+        };
+        if (entry.source === 'npm' && entry.npm) {
+            push('npm', (t, s) => deps.npmLatest(entry.npm, t, s));
+        }
+        if (entry.github) {
+            push('github', (t, s) => deps.githubLatestTag(entry.github, t, s));
+        }
+        if (entry.homepage) {
+            push('homepage', (t, s) => deps.reachable(entry.homepage, t, s));
+        }
+        if (entry.icon) {
+            push('icon', (t, s) => deps.reachable(entry.icon, t, s));
+        }
+    });
+    return probes;
+}
+/** probe 收敛：deadline 内未 resolve/reject 一律按 timeout 统计，不永久等待。 */
+function raceProbe(task, deadlineAt) {
+    let timer;
+    const timeoutP = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ kind: 'timeout' }), Math.max(1, deadlineAt - Date.now()));
+    });
+    return Promise.race([task, timeoutP]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+export async function checkRegistryEntries(registry, options = {}, deps = defaultRegistryCheckDeps()) {
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const concurrency = normalizeConcurrency(options.concurrency);
+    const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    const signal = options.signal;
+    const deadlineAt = Date.now() + deadlineMs;
+    const probes = collectProbes(registry, deps);
+    const records = [];
+    let checked = 0;
+    let passed = 0;
+    let failed = 0;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const record = (spec, message) => {
+        records.push({ entryIndex: spec.entryIndex, fieldIndex: spec.fieldIndex, issue: { id: spec.id, field: spec.field, message } });
+    };
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            if (aborted || Date.now() >= deadlineAt)
+                return;
+            const index = next;
+            if (index >= probes.length)
+                return;
+            next += 1;
+            const spec = probes[index];
+            checked += 1;
+            const budget = Math.max(1, Math.min(timeoutMs, deadlineAt - Date.now()));
+            const outcome = await raceProbe(spec.run(budget, signal).then((value) => ({ kind: 'value', value }), (error) => ({ kind: 'error', error })), deadlineAt);
+            if (outcome.kind === 'timeout') {
+                failed += 1;
+                record(spec, 'probe 在 deadline 前未收敛');
+            }
+            else if (outcome.kind === 'error') {
+                failed += 1;
+                record(spec, outcome.error instanceof Error ? outcome.error.message : String(outcome.error));
+            }
+            else if (spec.field === 'homepage' || spec.field === 'icon') {
+                if (outcome.value === true)
+                    passed += 1;
+                else {
+                    failed += 1;
+                    record(spec, 'URL 不可达');
+                }
+            }
+            else {
+                passed += 1;
+            }
+        }
+    };
+    const size = Math.min(concurrency, probes.length);
+    await Promise.all(Array.from({ length: size === 0 ? 1 : size }, worker));
+    signal?.removeEventListener('abort', onAbort);
+    records.sort((a, b) => (a.entryIndex - b.entryIndex) || (a.fieldIndex - b.fieldIndex));
+    const issues = records.slice(0, MAX_ISSUES).map((r) => r.issue);
+    return { checked, passed, failed, issues, truncated: records.length > MAX_ISSUES };
+}

package/lib/core/registry-controller.js

@@ -0,0 +1,321 @@
+/**
+ * Registry settings controller（DESIGN.md §4）：active config / configured address /
+ * pending / config phase 与真实 active registry 的分离。
+ * - 外部 settings 写入进入同一串行 queue，异步加载用 generation fence 防旧结果覆盖新结果；
+ * - `rejected` 只属于 config phase，不污染 loaded 的真实 source/status；
+ * - apply：candidate 校验成功 → store.update → 原子切换 active → commitActiveSource；
+ * - 最近一次 accepted address 通过 host cache metadata 跨重启保存，无效持久化值自动回滚。
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cacheDir } from './env.js';
+import { commitActiveSource, loadDefaultRegistry, loadRegistry, loadRegistryCandidate, parseRegistryAddress, } from './registry.js';
+export class RegistryConfigError extends Error {
+    errors;
+    constructor(message, errors = []) {
+        super(message);
+        this.name = 'RegistryConfigError';
+        this.errors = errors;
+    }
+}
+const ACCEPTED_SOURCE_FILE = 'active-source.json';
+/** 读取 host accepted-source metadata（损坏/缺失返回 null）。 */
+export async function readAcceptedSourceMetadata() {
+    try {
+        const raw = JSON.parse(await readFile(join(cacheDir(), 'host', ACCEPTED_SOURCE_FILE), 'utf8'));
+        if (!raw || typeof raw !== 'object')
+            return null;
+        if (raw.version !== 1 || raw.namespace !== 'host')
+            return null;
+        if (typeof raw.configuredAddress !== 'string' || typeof raw.cacheKey !== 'string')
+            return null;
+        if (typeof raw.savedAt !== 'string')
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function trimAddress(raw) {
+    return typeof raw === 'string' ? raw.trim() : '';
+}
+function placeholderLoaded(configuredAddress) {
+    return {
+        configuredAddress,
+        activeAddress: null,
+        source: configuredAddress === '' ? 'default-cache' : 'custom-unavailable',
+        status: 'unavailable',
+        isDefault: configuredAddress === '',
+        stale: false,
+        fetchedAt: null,
+        errors: [],
+        count: 0,
+        registry: { version: 1, plugins: [] },
+    };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function createRegistryController(initial = {}) {
+    // config 是共享对象：host.ts 把它传给 tools/API，controller 原地更新字段实现 live 生效
+    const config = { ...initial };
+    let activeConfigAddress = trimAddress(initial.registryUrl);
+    let loaded = placeholderLoaded(activeConfigAddress);
+    let pendingAddress = null;
+    let configStatus = 'loading';
+    let configErrors = [];
+    let warnings = [];
+    let generation = 0;
+    let disposed = false;
+    let store = null;
+    let queue = Promise.resolve();
+    let bootstrapPromise = null;
+    let lastSelfWrite = null;
+    let unwatch = null;
+    function enqueue(task) {
+        if (disposed)
+            return Promise.reject(new Error('registry controller 已 disposed'));
+        const run = queue.then(() => {
+            const gen = ++generation;
+            return task(gen);
+        });
+        queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    function adopt(gen, nextRegistryUrl, candidate) {
+        if (disposed || gen !== generation)
+            return false;
+        config.registryUrl = nextRegistryUrl;
+        activeConfigAddress = candidate.configuredAddress;
+        loaded = candidate;
+        pendingAddress = null;
+        configErrors = [];
+        configStatus = 'ready';
+        return true;
+    }
+    function snapshotInternal() {
+        return {
+            configuredAddress: trimAddress(config.registryUrl),
+            activeConfigAddress,
+            pendingAddress,
+            configStatus,
+            configErrors: [...configErrors],
+            warnings: [...warnings],
+            loaded,
+        };
+    }
+    async function rollbackPersist(value) {
+        if (!store)
+            return false;
+        lastSelfWrite = value;
+        try {
+            await store.update({ registryUrl: value });
+            return true;
+        }
+        catch (err) {
+            warnings.push(`回滚持久化配置失败：${errorMessage(err)}；将在下次启动再次尝试`);
+            lastSelfWrite = null;
+            return false;
+        }
+    }
+    function candidateFor(rawAddress, signal) {
+        return loadRegistryCandidate({ ...config, registryUrl: rawAddress }, { namespace: 'host', signal });
+    }
+    const bootstrap = async () => {
+        await enqueue(async (gen) => {
+            const source = store ? store.get() : initial;
+            config.timeoutMs = source.timeoutMs;
+            config.cacheTtlMin = source.cacheTtlMin;
+            const raw = trimAddress(source.registryUrl);
+            const attempt = await loadRegistry({ ...config, registryUrl: raw }, { namespace: 'host' });
+            if (disposed || gen !== generation)
+                return;
+            if (attempt.status !== 'unavailable') {
+                adopt(gen, raw, attempt);
+                return;
+            }
+            // 持久化 custom 不可达：先试 accepted address（含其 cache），无 accepted 则默认
+            configErrors = [...attempt.errors];
+            const accepted = await readAcceptedSourceMetadata();
+            const recoverAddress = accepted && accepted.configuredAddress !== raw ? accepted.configuredAddress : '';
+            const recovered = await loadRegistry({ ...config, registryUrl: recoverAddress }, { namespace: 'host', force: true });
+            if (disposed || gen !== generation)
+                return;
+            if (recovered.status !== 'unavailable') {
+                adopt(gen, recoverAddress, recovered);
+                configStatus = 'rejected';
+                configErrors = [...attempt.errors];
+                pendingAddress = null;
+                warnings.push(`持久化 registry 地址不可用，已回滚到${recoverAddress === '' ? '默认清单' : recoverAddress}`);
+                await rollbackPersist(recoverAddress);
+            }
+            else {
+                // 连恢复都失败：接受 unavailable 现实，config 标记 rejected
+                loaded = recovered;
+                activeConfigAddress = recovered.configuredAddress;
+                config.registryUrl = recoverAddress;
+                configStatus = 'rejected';
+            }
+        });
+    };
+    function startBootstrap() {
+        if (!bootstrapPromise) {
+            bootstrapPromise = bootstrap().catch((err) => {
+                if (!disposed) {
+                    configStatus = 'unavailable';
+                    configErrors = [errorMessage(err)];
+                }
+            });
+        }
+        return bootstrapPromise;
+    }
+    function handleExternalWatch(next) {
+        if (disposed)
+            return Promise.resolve();
+        const raw = trimAddress(next.registryUrl);
+        if (lastSelfWrite !== null && raw === lastSelfWrite) {
+            lastSelfWrite = null;
+            return Promise.resolve();
+        }
+        if (raw === trimAddress(config.registryUrl) && configStatus === 'ready')
+            return Promise.resolve();
+        return enqueue(async (gen) => {
+            let candidate;
+            try {
+                candidate = await candidateFor(raw);
+            }
+            catch (err) {
+                candidate = { ...placeholderLoaded(raw), errors: [errorMessage(err)] };
+            }
+            if (disposed || gen !== generation)
+                return;
+            if (candidate.status !== 'unavailable') {
+                adopt(gen, raw, candidate);
+                const nextConfig = { ...config, registryUrl: raw, timeoutMs: next.timeoutMs, cacheTtlMin: next.cacheTtlMin };
+                config.timeoutMs = nextConfig.timeoutMs;
+                config.cacheTtlMin = nextConfig.cacheTtlMin;
+                try {
+                    const commit = await commitActiveSource(parseRegistryAddress(raw), 'host');
+                    if (commit.warning)
+                        warnings.push(commit.warning);
+                }
+                catch {
+                    /* commit 失败不改变已采纳的 active */
+                }
+                return;
+            }
+            // 外部无效值：保持旧 active，回滚持久化值
+            configStatus = 'rejected';
+            configErrors = [...candidate.errors];
+            pendingAddress = raw;
+            const rolledBack = await rollbackPersist(trimAddress(config.registryUrl));
+            if (rolledBack)
+                pendingAddress = null;
+        }).then(() => undefined, () => undefined);
+    }
+    function attachStore(s) {
+        if (disposed)
+            throw new Error('registry controller 已 disposed');
+        store = s;
+        unwatch?.();
+        unwatch = s.watch((next) => {
+            void handleExternalWatch(next);
+        });
+        void startBootstrap();
+    }
+    function ensureReady(opts) {
+        void opts;
+        return startBootstrap();
+    }
+    async function snapshot(opts = {}) {
+        await startBootstrap();
+        if (opts.force) {
+            await enqueue(async (gen) => {
+                const attempt = await loadRegistry(config, { namespace: 'host', force: true, signal: opts.signal });
+                if (disposed || gen !== generation)
+                    return;
+                loaded = attempt;
+                activeConfigAddress = attempt.configuredAddress;
+            });
+        }
+        return snapshotInternal();
+    }
+    function loadDefault(opts = {}) {
+        return loadDefaultRegistry(config, { namespace: 'host', force: opts?.force, signal: opts?.signal });
+    }
+    function apply(rawAddress, opts = {}) {
+        return enqueue(async (gen) => {
+            const trimmed = String(rawAddress ?? '').trim();
+            let address;
+            try {
+                address = parseRegistryAddress(trimmed);
+            }
+            catch (err) {
+                configStatus = 'rejected';
+                pendingAddress = trimmed || null;
+                configErrors = [errorMessage(err)];
+                throw new RegistryConfigError(errorMessage(err), [errorMessage(err)]);
+            }
+            let candidate;
+            try {
+                candidate = await candidateFor(trimmed, opts.signal);
+            }
+            catch (err) {
+                if (disposed || gen !== generation)
+                    return snapshotInternal();
+                configStatus = 'rejected';
+                pendingAddress = trimmed || null;
+                configErrors = [errorMessage(err)];
+                throw new RegistryConfigError(errorMessage(err), [errorMessage(err)]);
+            }
+            if (disposed || gen !== generation)
+                return snapshotInternal();
+            if (candidate.status === 'unavailable') {
+                configStatus = 'rejected';
+                pendingAddress = trimmed || null;
+                configErrors = [...candidate.errors];
+                throw new RegistryConfigError('registry 地址校验失败', candidate.errors);
+            }
+            if (store) {
+                lastSelfWrite = trimmed;
+                try {
+                    await store.update({ registryUrl: trimmed });
+                }
+                catch (err) {
+                    lastSelfWrite = null;
+                    configStatus = 'pending';
+                    pendingAddress = trimmed;
+                    configErrors = [errorMessage(err)];
+                    throw new RegistryConfigError(`配置校验成功但写入设置失败：${errorMessage(err)}`, [errorMessage(err)]);
+                }
+            }
+            adopt(gen, trimmed, candidate);
+            try {
+                const commit = await commitActiveSource(address, 'host');
+                if (commit.warning)
+                    warnings.push(commit.warning);
+            }
+            catch (err) {
+                warnings.push(`accepted-source 提交异常：${errorMessage(err)}`);
+            }
+            return snapshotInternal();
+        });
+    }
+    function dispose() {
+        disposed = true;
+        unwatch?.();
+        unwatch = null;
+        store = null;
+    }
+    const controller = {
+        config,
+        attachStore,
+        ensureReady,
+        snapshot,
+        loadDefault,
+        apply,
+        dispose,
+    };
+    return controller;
+}