@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/api.js

@@ -0,0 +1 @@
+export {};

package/lib/archive.d.ts

@@ -0,0 +1 @@
+export declare function unpackZip(zipPath: string, root: string, maxBytes: number, signal?: AbortSignal): Promise<void>;

package/lib/archive.js

@@ -0,0 +1,63 @@
+import yauzl from 'yauzl';
+import { createWriteStream, mkdir, symlink } from "./physical-fs.js";
+import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+export async function unpackZip(zipPath, root, maxBytes, signal) {
+    signal?.throwIfAborted();
+    const zip = await new Promise((yes, no) => yauzl.open(zipPath, { lazyEntries: true, validateEntrySizes: true }, (e, z) => e ? no(e) : yes(z)));
+    const links = [], seen = new Set();
+    let total = 0;
+    const inside = (path) => { const r = relative(root, path); return r !== '' && !r.startsWith('..') && !isAbsolute(r); };
+    try {
+        await new Promise((yes, no) => {
+            zip.on('error', no);
+            zip.on('end', yes);
+            zip.on('entry', (entry) => {
+                void (async () => {
+                    signal?.throwIfAborted();
+                    const path = resolve(root, entry.fileName);
+                    if (!inside(path) || seen.has(path))
+                        throw new Error('ZIP_PATH_INVALID');
+                    seen.add(path);
+                    total += entry.uncompressedSize;
+                    if (total > maxBytes)
+                        throw new Error('EXTRACTED_SIZE_EXCEEDED');
+                    const mode = (entry.externalFileAttributes >>> 16) & 0xffff, type = mode & 0o170000;
+                    if (entry.fileName.endsWith('/')) {
+                        await mkdir(path, { recursive: true, mode: 0o700 });
+                        zip.readEntry();
+                        return;
+                    }
+                    if (type !== 0 && type !== 0o100000 && type !== 0o120000)
+                        throw new Error('ZIP_TYPE_INVALID');
+                    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                    const stream = await new Promise((res, rej) => zip.openReadStream(entry, (e, s) => e ? rej(e) : res(s)));
+                    if (type === 0o120000) {
+                        const chunks = [];
+                        for await (const c of stream) {
+                            signal?.throwIfAborted();
+                            chunks.push(Buffer.from(c));
+                        }
+                        const target = Buffer.concat(chunks).toString('utf8');
+                        if (isAbsolute(target) || !inside(resolve(dirname(path), target)))
+                            throw new Error('ZIP_LINK_INVALID');
+                        links.push({ path, target });
+                    }
+                    else {
+                        await pipeline(stream, createWriteStream(path, { flags: 'wx', mode: mode & 0o111 ? 0o700 : 0o600 }), { signal });
+                    }
+                    zip.readEntry();
+                })().catch(no);
+            });
+            zip.readEntry();
+        });
+        // All ordinary entries are written before symlinks, so no write can traverse an archive symlink.
+        for (const link of links) {
+            signal?.throwIfAborted();
+            await symlink(link.target, link.path);
+        }
+    }
+    finally {
+        zip.close();
+    }
+}

package/lib/auth-status.d.ts

@@ -0,0 +1,3 @@
+import type { LoginState, Provider, Result } from './api.ts';
+import type { CommandResult } from './ports.ts';
+export declare function parseLoginStatus(provider: Provider, result: CommandResult): Result<LoginState>;

package/lib/auth-status.js

@@ -0,0 +1,18 @@
+import { fail, ok } from "./needs.js";
+export function parseLoginStatus(provider, result) {
+    let v;
+    try {
+        v = JSON.parse(result.stdout);
+    }
+    catch {
+        return fail('AUTH_STATUS_INVALID');
+    }
+    if (!v || typeof v !== 'object' || Array.isArray(v) || Object.keys(v).sort().join(',') !== 'exitCode,loggedIn,protocolVersion,provider')
+        return fail('AUTH_STATUS_INVALID');
+    const status = v;
+    if (status.protocolVersion !== 1 || status.provider !== provider || status.exitCode !== result.exitCode || typeof status.loggedIn !== 'boolean' || result.stderr !== '')
+        return fail('AUTH_STATUS_INVALID');
+    if (status.loggedIn ? result.exitCode !== 0 : provider === 'codex' ? result.exitCode !== 1 : result.exitCode !== 0 && result.exitCode !== 1)
+        return fail('AUTH_STATUS_INVALID');
+    return ok({ provider, loggedIn: status.loggedIn });
+}

package/lib/cache.d.ts

@@ -0,0 +1,21 @@
+import type { Result } from './api.ts';
+import { type ComponentProgress } from './component-download.ts';
+export interface HelperSettings {
+    source: string;
+    cacheDir: string;
+    sha256: string;
+    maxDownloadBytes: number;
+    maxExtractedBytes: number;
+    executable: string;
+}
+interface CacheIo {
+    download: (source: string) => Promise<Response>;
+    unpack: (zip: string, dir: string, maxBytes: number) => Promise<void>;
+}
+export declare function ensureHelper(s: HelperSettings | undefined, io?: {
+    download: CacheIo['download'];
+    unpack?: CacheIo['unpack'];
+    signal?: AbortSignal;
+    onProgress?: (progress: ComponentProgress) => void;
+}): Promise<Result<string>>;
+export {};

package/lib/cache.js

@@ -0,0 +1,156 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { open, lstat, readFile, writeFile, readdir, readlink, realpath, rename, rm, mkdir } from "./physical-fs.js";
+import { join, isAbsolute, relative } from 'node:path';
+import { dependency, fail, ok, need } from "./needs.js";
+import { ComponentDownloadError } from "./component-download.js";
+import { privateDirectory } from "./private-files.js";
+import { unpackZip } from "./archive.js";
+async function treeHash(root) {
+    const hash = createHash('sha256');
+    const walk = async (dir) => {
+        for (const name of (await readdir(dir)).sort()) {
+            const p = join(dir, name), s = await lstat(p), rel = relative(root, p);
+            hash.update(rel + '\0' + (s.mode & 0o777) + '\0');
+            if (s.isDirectory())
+                await walk(p);
+            else if (s.isSymbolicLink()) {
+                const dest = await realpath(p);
+                if (!dest.startsWith(root + '/'))
+                    throw new Error('CACHE_LINK_ESCAPE');
+                hash.update(await readlink(p));
+            }
+            else if (s.isFile())
+                hash.update(await readFile(p));
+            else
+                throw new Error('CACHE_TYPE_INVALID');
+        }
+    };
+    await walk(root);
+    return hash.digest('hex');
+}
+function valid(s) {
+    try {
+        return new URL(s.source).protocol === 'https:' && !new URL(s.source).username && !new URL(s.source).password && isAbsolute(s.cacheDir) && /^[a-f0-9]{64}$/.test(s.sha256) && Number.isSafeInteger(s.maxDownloadBytes) && s.maxDownloadBytes > 0 && Number.isSafeInteger(s.maxExtractedBytes) && s.maxExtractedBytes > 0 && !isAbsolute(s.executable) && !s.executable.split('/').includes('..') && s.executable !== '';
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureHelper(s, io) {
+    if (!s || !valid(s))
+        return fail('SETTINGS_REQUIRED');
+    if (!io?.download)
+        return dependency('组件官方地址的直接HTTPS下载通道');
+    const final = join(s.cacheDir, s.sha256), payload = join(final, 'runtime'), executable = join(payload, s.executable);
+    let temp, receivedBytes = 0, totalBytes = null;
+    const emit = (phase, errorCode) => io.onProgress?.({ phase, receivedBytes, totalBytes, ...errorCode ? { errorCode } : {} });
+    const cancelled = () => { if (io.signal?.aborted)
+        throw new ComponentDownloadError('COMPONENT_DOWNLOAD_CANCELLED'); };
+    try {
+        cancelled();
+        await privateDirectory(s.cacheDir);
+        let existing = false;
+        try {
+            const st = await lstat(final);
+            if (st.isSymbolicLink() || !st.isDirectory())
+                throw new ComponentDownloadError('COMPONENT_CACHE_INVALID');
+            existing = true;
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (existing) {
+            const receipt = JSON.parse(await readFile(join(final, 'receipt.json'), 'utf8'));
+            if (receipt.sha256 !== s.sha256 || receipt.treeHash !== await treeHash(payload))
+                throw new ComponentDownloadError('COMPONENT_CACHE_INVALID');
+            const file = await lstat(executable);
+            if (!file.isFile() || (file.mode & 0o100) === 0)
+                throw new ComponentDownloadError('COMPONENT_CACHE_INVALID');
+            cancelled();
+            emit('ready');
+            return ok(executable);
+        }
+        temp = join(s.cacheDir, 'download-' + randomUUID());
+        await mkdir(temp, { mode: 0o700 });
+        const archive = join(temp, 'electron.zip');
+        emit('downloading');
+        const response = await io.download(s.source);
+        cancelled();
+        if (!response.ok || !response.body)
+            throw new ComponentDownloadError('COMPONENT_DOWNLOAD_RESPONSE');
+        const length = response.headers.get('content-length');
+        if (length !== null) {
+            const n = Number(length);
+            if (!/^\d+$/.test(length) || !Number.isSafeInteger(n) || n < 0)
+                throw new ComponentDownloadError('COMPONENT_DOWNLOAD_LENGTH_INVALID');
+            totalBytes = n;
+            if (n > s.maxDownloadBytes) {
+                await response.body.cancel();
+                throw new ComponentDownloadError('COMPONENT_DOWNLOAD_SIZE');
+            }
+        }
+        emit('downloading');
+        const file = await open(archive, 'wx', 0o600), hash = createHash('sha256');
+        let total = 0;
+        try {
+            for await (const chunk of response.body) {
+                cancelled();
+                total += chunk.byteLength;
+                receivedBytes = total;
+                if (total > s.maxDownloadBytes)
+                    throw new ComponentDownloadError('COMPONENT_DOWNLOAD_SIZE');
+                hash.update(chunk);
+                await file.write(chunk);
+                emit('downloading');
+            }
+        }
+        finally {
+            await file.close();
+        }
+        cancelled();
+        emit('verifying');
+        if (hash.digest('hex') !== s.sha256)
+            throw new ComponentDownloadError('COMPONENT_SHA256_MISMATCH');
+        const runtime = join(temp, 'runtime');
+        await privateDirectory(runtime);
+        emit('unpacking');
+        cancelled();
+        if (io.unpack)
+            await io.unpack(archive, runtime, s.maxExtractedBytes);
+        else
+            await unpackZip(archive, runtime, s.maxExtractedBytes, io.signal);
+        cancelled();
+        let unpacked = 0;
+        const measure = async (dir) => { for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const p = join(dir, entry.name);
+            if (entry.isDirectory())
+                await measure(p);
+            else if (entry.isFile())
+                unpacked += (await lstat(p)).size;
+            if (unpacked > s.maxExtractedBytes)
+                throw new Error('EXTRACTED_SIZE_EXCEEDED');
+        } };
+        await measure(runtime);
+        const exe = join(runtime, s.executable), st = await lstat(exe);
+        if (!st.isFile() || (st.mode & 0o100) === 0)
+            throw new ComponentDownloadError('COMPONENT_EXECUTABLE_INVALID');
+        await writeFile(join(temp, 'receipt.json'), JSON.stringify({ sha256: s.sha256, treeHash: await treeHash(runtime) }), { mode: 0o600 });
+        await rm(archive);
+        cancelled();
+        await rename(temp, final);
+        temp = undefined;
+        cancelled();
+        emit('ready');
+        return ok(executable);
+    }
+    catch (error) {
+        const code = io.signal?.aborted ? 'COMPONENT_DOWNLOAD_CANCELLED' : error instanceof ComponentDownloadError ? error.message : 'COMPONENT_CACHE_IO';
+        emit(code === 'COMPONENT_DOWNLOAD_CANCELLED' ? 'cancelled' : 'failed', code);
+        return { ok: false, error: { ...need('LOGIN_FAILED'), requires: '登录组件从官方地址下载并通过完整校验；未重试或换源', officialReason: code } };
+    }
+    finally {
+        if (temp)
+            await rm(temp, { recursive: true, force: true });
+    }
+}

package/lib/component-download.d.ts

@@ -0,0 +1,32 @@
+export type ComponentPhase = 'idle' | 'downloading' | 'verifying' | 'unpacking' | 'ready' | 'failed' | 'cancelled';
+export interface ComponentProgress {
+    phase: ComponentPhase;
+    receivedBytes: number;
+    totalBytes: number | null;
+    errorCode?: string;
+}
+export interface ComponentDownloadState extends ComponentProgress {
+    instanceId: string;
+    revision: number;
+    attemptId: string | null;
+    lastProgressAt?: number;
+    sourceLabel?: string;
+    sourceId?: string;
+}
+export declare function createComponentProgress(now?: () => number): {
+    getState: () => ComponentDownloadState;
+    onState(fn: () => void): () => void;
+    cancel(attemptId: string): boolean;
+    begin(source?: {
+        id: string;
+        label: string;
+    }, cancel?: () => void): {
+        attemptId: `${string}-${string}-${string}-${string}-${string}`;
+        update: (progress: ComponentProgress) => void;
+    };
+};
+export type ComponentProgressStore = ReturnType<typeof createComponentProgress>;
+export declare class ComponentDownloadError extends Error {
+    constructor(code: string);
+}
+export declare function downloadComponent(source: string, signal: AbortSignal, maxRedirects: number): Promise<Response>;

package/lib/component-download.js

@@ -0,0 +1,76 @@
+import https from 'node:https';
+import { Readable } from 'node:stream';
+import { randomUUID } from 'node:crypto';
+export function createComponentProgress(now = Date.now) {
+    let state = { instanceId: randomUUID(), revision: 0, attemptId: null, phase: 'idle', receivedBytes: 0, totalBytes: null };
+    const listeners = new Set();
+    let cancelDownload;
+    return { getState: () => structuredClone(state), onState(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; }, cancel(attemptId) { if (state.attemptId !== attemptId || !['downloading', 'verifying', 'unpacking'].includes(state.phase) || !cancelDownload)
+            return false; const cancel = cancelDownload; cancelDownload = undefined; cancel(); return true; }, begin(source, cancel) { cancelDownload = cancel; const attemptId = randomUUID(); const update = (progress) => { if (state.attemptId !== attemptId)
+            return; if (['ready', 'failed', 'cancelled'].includes(progress.phase))
+            cancelDownload = undefined; state = { ...progress, lastProgressAt: progress.receivedBytes > state.receivedBytes ? now() : state.lastProgressAt, ...(source ? { sourceLabel: source.label, sourceId: source.id } : {}), instanceId: state.instanceId, revision: state.revision + 1, attemptId }; for (const fn of listeners)
+            fn(); }; state = { ...state, attemptId, receivedBytes: 0, lastProgressAt: now() }; update({ phase: 'downloading', receivedBytes: 0, totalBytes: null }); return { attemptId, update }; } };
+}
+export class ComponentDownloadError extends Error {
+    constructor(code) { super(code); this.name = 'ComponentDownloadError'; }
+}
+const sourceUrl = (source) => { let u; try {
+    u = new URL(source);
+}
+catch {
+    throw new ComponentDownloadError('COMPONENT_SOURCE_INVALID');
+} if (u.protocol !== 'https:' || u.username || u.password)
+    throw new ComponentDownloadError('COMPONENT_SOURCE_INVALID'); return u; };
+// 仅固定组件供给。不接收OAuth URL、ProxyLease、认证头或cookie；不读取系统/N代理。
+export async function downloadComponent(source, signal, maxRedirects) {
+    if (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0)
+        throw new ComponentDownloadError('COMPONENT_REDIRECT_LIMIT_INVALID');
+    let url = sourceUrl(source);
+    for (let redirects = 0;; redirects++) {
+        if (signal.aborted)
+            throw new ComponentDownloadError('COMPONENT_DOWNLOAD_CANCELLED');
+        const response = await new Promise((yes, no) => {
+            const req = https.request(url, { signal, headers: { Accept: 'application/octet-stream' } }, yes);
+            req.once('error', () => no(new ComponentDownloadError(signal.aborted ? 'COMPONENT_DOWNLOAD_CANCELLED' : 'COMPONENT_DOWNLOAD_NETWORK')));
+            req.end();
+        });
+        const status = response.statusCode ?? 0;
+        if ([301, 302, 303, 307, 308].includes(status)) {
+            const location = response.headers.location;
+            response.destroy();
+            if (redirects >= maxRedirects)
+                throw new ComponentDownloadError('COMPONENT_REDIRECT_LIMIT');
+            if (!location)
+                throw new ComponentDownloadError('COMPONENT_REDIRECT_INVALID');
+            try {
+                url = sourceUrl(new URL(location, url).href);
+            }
+            catch {
+                throw new ComponentDownloadError('COMPONENT_REDIRECT_INVALID');
+            }
+            continue;
+        }
+        if (status !== 200) {
+            response.destroy();
+            throw new ComponentDownloadError('COMPONENT_DOWNLOAD_HTTP_' + status);
+        }
+        const headers = new Headers();
+        for (const name of ['content-length', 'content-type']) {
+            const v = response.headers[name];
+            if (typeof v === 'string')
+                headers.set(name, v);
+        }
+        const reader = Readable.toWeb(response).getReader();
+        const body = new ReadableStream({ async pull(controller) { try {
+                const part = await reader.read();
+                if (part.done)
+                    controller.close();
+                else
+                    controller.enqueue(part.value);
+            }
+            catch {
+                controller.error(new ComponentDownloadError(signal.aborted ? 'COMPONENT_DOWNLOAD_CANCELLED' : 'COMPONENT_DOWNLOAD_BODY'));
+            } }, cancel: reason => reader.cancel(reason) });
+        return new Response(body, { status, headers });
+    }
+}

package/lib/component-source.d.ts

@@ -0,0 +1,52 @@
+export declare const COMPONENT_SOURCES: Readonly<{
+    github: {
+        label: string;
+        source: "https://github.com/electron/electron/releases/download/v44.0.0/electron-v44.0.0-darwin-arm64.zip";
+    };
+    npmmirror: {
+        label: string;
+        source: string;
+    };
+}>;
+export type ComponentSourceId = keyof typeof COMPONENT_SOURCES;
+export declare const DEFAULT_SOURCE_REASON = "\u9ED8\u8BA4\u9009\u62E9 npmmirror\uFF1A\u4E2D\u56FD\u955C\u50CF\u53EF\u907F\u5F00\u90E8\u5206\u7F51\u7EDC\u4E0B\u65E0\u6CD5\u8BBF\u95EE\u7684 GitHub \u53D1\u5E03\u6587\u4EF6 CDN\uFF1B\u672A\u81EA\u52A8\u6D4B\u901F\u6216\u5931\u8D25\u6362\u6E90\u3002";
+export declare const preset: (id: unknown) => id is ComponentSourceId;
+interface Options {
+    profileDir?: string;
+    metadataMaxBytes: number;
+    source?: string;
+    sha256?: string;
+    reason: string;
+    busy: () => boolean;
+}
+export declare function createComponentSources(options: Options): {
+    ready: Promise<void>;
+    getState: () => {
+        changing: boolean;
+        instanceId: `${string}-${string}-${string}-${string}-${string}`;
+        revision: number;
+        phase: "loading" | "ready" | "blocked";
+        selectedId: string;
+        selectedLabel: string;
+        reason: string;
+        version: string;
+        sha256: string | null;
+        errorCode: string | null;
+        selectionErrorCode: string | null;
+        choices: {
+            id: string;
+            label: string;
+        }[];
+    };
+    onState(fn: () => void): () => void;
+    resolve: () => Promise<{
+        source: string;
+        id: string;
+        label: string;
+        reason: string;
+    }>;
+    select: (id: unknown) => Promise<void>;
+    dispose(): Promise<void>;
+};
+export type ComponentSources = ReturnType<typeof createComponentSources>;
+export {};

package/lib/component-source.js

@@ -0,0 +1,146 @@
+import { join, isAbsolute, resolve } from 'node:path';
+import { lstat, realpath, open, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { privateDirectory, readPrivate } from "./private-files.js";
+import { ELECTRON_PIN } from "./defaults.js";
+import { ComponentDownloadError } from "./component-download.js";
+export const COMPONENT_SOURCES = Object.freeze({
+    github: { label: 'GitHub 官方源', source: ELECTRON_PIN.source },
+    npmmirror: { label: 'npmmirror 镜像（Electron 官方文档列出）', source: 'https://npmmirror.com/mirrors/electron/44.0.0/electron-v44.0.0-darwin-arm64.zip' },
+});
+export const DEFAULT_SOURCE_REASON = '默认选择 npmmirror：中国镜像可避开部分网络下无法访问的 GitHub 发布文件 CDN；未自动测速或失败换源。';
+export const preset = (id) => typeof id === 'string' && Object.hasOwn(COMPONENT_SOURCES, id);
+export function createComponentSources(options) {
+    let selected = Object.entries(COMPONENT_SOURCES).find(([, v]) => v.source === options.source)?.[0];
+    let state = { instanceId: randomUUID(), revision: 0, phase: 'loading', selectedId: selected ?? 'custom', selectedLabel: selected ? COMPONENT_SOURCES[selected].label : '管理员自定义源', reason: options.reason, version: '44.0.0', sha256: options.sha256 ?? null, errorCode: null, selectionErrorCode: null, choices: Object.entries(COMPONENT_SOURCES).map(([id, v]) => ({ id, label: v.label })) };
+    let source = options.source, disposed = false, changing = false;
+    const listeners = new Set();
+    const pending = new Set();
+    function error(code) { throw new ComponentDownloadError(code); }
+    const notify = () => { if (!disposed) {
+        state = { ...state, revision: state.revision + 1 };
+        for (const fn of listeners)
+            fn();
+    } };
+    const blocked = (code) => { state = { ...state, phase: 'blocked', errorCode: code }; notify(); };
+    const directory = options.profileDir ? join(options.profileDir, 'ai-workbench-connect') : undefined;
+    const file = directory ? join(directory, 'component-source.json') : undefined;
+    const checkPin = () => { if (options.sha256 !== ELECTRON_PIN.sha256)
+        error('COMPONENT_PIN_MISMATCH'); };
+    async function canonical() { if (!options.profileDir || !directory || !isAbsolute(options.profileDir) || await realpath(options.profileDir) !== resolve(options.profileDir))
+        error('COMPONENT_SOURCE_PROFILE_REQUIRED'); await privateDirectory(directory); if (await realpath(directory) !== resolve(directory))
+        error('COMPONENT_SOURCE_STATE_INVALID'); }
+    const ready = (async () => {
+        try {
+            if (!file)
+                error('COMPONENT_SOURCE_PROFILE_REQUIRED');
+            if (!source)
+                error('COMPONENT_SOURCE_INVALID');
+            const initialUrl = new URL(source);
+            if (initialUrl.protocol !== 'https:' || initialUrl.username || initialUrl.password)
+                error('COMPONENT_SOURCE_INVALID');
+            await canonical();
+            try {
+                const stat = await lstat(file);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+                    error('COMPONENT_SOURCE_STATE_INVALID');
+                const saved = JSON.parse(await readPrivate(file, options.metadataMaxBytes));
+                if (saved.schemaVersion !== 1 || !preset(saved.sourceId))
+                    error('COMPONENT_SOURCE_STATE_INVALID');
+                const savedId = saved.sourceId;
+                selected = savedId;
+                source = COMPONENT_SOURCES[savedId].source;
+                state = { ...state, selectedId: savedId, selectedLabel: COMPONENT_SOURCES[savedId].label, reason: '沿用你在本设置节保存的下载源；未自动切源。' };
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+            if (!source)
+                error('COMPONENT_SOURCE_INVALID');
+            const url = new URL(source);
+            if (url.protocol !== 'https:' || url.username || url.password)
+                error('COMPONENT_SOURCE_INVALID');
+            state = { ...state, phase: 'ready' };
+            notify();
+        }
+        catch (e) {
+            blocked(e instanceof ComponentDownloadError ? e.message : 'COMPONENT_SOURCE_STATE_INVALID');
+        }
+    })();
+    async function resolveSource() { await ready; if (disposed)
+        error('COMPONENT_SOURCE_DISPOSED'); if (state.phase === 'blocked')
+        error(state.errorCode); if (changing)
+        error('COMPONENT_SOURCE_BUSY'); if (selected)
+        checkPin(); return { source: source, id: state.selectedId, label: state.selectedLabel, reason: state.reason }; }
+    function select(id) {
+        const task = (async () => {
+            if (!preset(id))
+                error('COMPONENT_SOURCE_INVALID');
+            if (disposed)
+                error('COMPONENT_SOURCE_DISPOSED');
+            if (changing || options.busy())
+                error('COMPONENT_SOURCE_BUSY');
+            changing = true;
+            notify();
+            let temp;
+            try {
+                await ready;
+                if (disposed)
+                    error('COMPONENT_SOURCE_DISPOSED');
+                if (state.phase === 'blocked')
+                    error(state.errorCode);
+                if (options.busy())
+                    error('COMPONENT_SOURCE_BUSY');
+                checkPin();
+                await canonical();
+                const data = JSON.stringify({ schemaVersion: 1, sourceId: id });
+                if (!Number.isSafeInteger(options.metadataMaxBytes) || Buffer.byteLength(data) > options.metadataMaxBytes)
+                    error('COMPONENT_SOURCE_STATE_INVALID');
+                temp = join(directory, '.component-source-' + randomUUID());
+                const handle = await open(temp, 'wx', 0o600);
+                try {
+                    await handle.writeFile(data);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                if (disposed)
+                    error('COMPONENT_SOURCE_DISPOSED');
+                if (options.busy())
+                    error('COMPONENT_SOURCE_BUSY');
+                await rename(temp, file);
+                temp = undefined;
+                const parent = await open(directory, 'r');
+                try {
+                    await parent.sync();
+                }
+                finally {
+                    await parent.close();
+                }
+                selected = id;
+                source = COMPONENT_SOURCES[id].source;
+                state = { ...state, selectedId: id, selectedLabel: COMPONENT_SOURCES[id].label, reason: '你在本设置节显式选择并保存了此下载源；未自动切源。', errorCode: null, selectionErrorCode: null };
+            }
+            catch (e) {
+                if (!(e instanceof ComponentDownloadError)) {
+                    blocked('COMPONENT_SOURCE_STATE_INVALID');
+                    error('COMPONENT_SOURCE_STATE_INVALID');
+                }
+                state = { ...state, selectionErrorCode: e.message };
+                throw e;
+            }
+            finally {
+                if (temp)
+                    await rm(temp, { force: true });
+                changing = false;
+                notify();
+            }
+        })();
+        pending.add(task);
+        void task.then(() => pending.delete(task), () => pending.delete(task));
+        return task;
+    }
+    return { ready, getState: () => structuredClone({ ...state, changing }), onState(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; }, resolve: resolveSource, select, async dispose() { disposed = true; listeners.clear(); await ready; await Promise.allSettled([...pending]); } };
+}

package/lib/components.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentSources } from './component-source.ts';
+import type { ComponentProgressStore } from './component-download.ts';
+import type { Context } from '@deepseek-ai/cordis';
+export interface ComponentInventory {
+    network: string;
+    connect: string;
+    claude: string;
+    codex?: string;
+}
+export declare function registerComponents(ctx: Context, inventory?: ComponentInventory, temporaryDataParent?: string, component?: ComponentProgressStore, sources?: ComponentSources, observationIntervalMs?: number): void;