u1s1-cli 1.14.6 → 1.15.1

package/dist/agents/prefs.js

@@ -0,0 +1,96 @@
+/**
+ * 用户给官方原版客户端(claude / codex)定的偏好,存在 ~/.u1s1/config.json:
+ *
+ *   "agents": {
+ *     "claude": { "model": "<模型 id>", "autoUpdate": false },
+ *     "codex":  { "model": "<模型 id>" }
+ *   }
+ *
+ *   model       默认模型。启动时还在网关下发的阵容里就用它,不在了退回网关默认并提示一次
+ *               (提示过的 id 记在 modelNotice,同一个 id 不重复提示)。缺省 = 跟随网关默认。
+ *   autoUpdate  每天查一次新版、下次启动前更新。缺省 = 开。关掉后版本刹车照样生效
+ *               (见 runtime.ts planRuntime 的 update_required)。
+ *
+ * 由 `u1s1 config` 改(config-command.ts),启动流程(launch.ts)读。只改这几个键,config.json
+ * 其余内容原样保留。
+ */
+import { readRawConfigFile, updateRawConfigFile } from "../config.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,199}$/;
+/** 用户能填的模型 id:不带空白、引号等(会原样写进 TOML / JSON)。 */
+export function isModelId(value) {
+    return typeof value === "string" && MODEL_ID_RE.test(value);
+}
+export function readAgentPrefs(agent, raw = readRawConfigFile()) {
+    const all = raw?.["agents"];
+    const own = isRecord(all) ? all[agent] : undefined;
+    if (!isRecord(own))
+        return { autoUpdate: true };
+    return {
+        ...(isModelId(own["model"]) ? { model: own["model"] } : {}),
+        autoUpdate: own["autoUpdate"] !== false,
+        ...(isModelId(own["modelNotice"]) ? { modelNotice: own["modelNotice"] } : {}),
+    };
+}
+export function saveAgentPrefs(agent, patch) {
+    updateRawConfigFile((file) => {
+        const all = isRecord(file["agents"]) ? { ...file["agents"] } : {};
+        const own = isRecord(all[agent]) ? { ...all[agent] } : {};
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined)
+                continue;
+            if (value === null)
+                delete own[key];
+            else
+                own[key] = value;
+        }
+        // 自动更新开着是默认,不必写出来
+        if (own["autoUpdate"] === true)
+            delete own["autoUpdate"];
+        // 用户换了模型或清掉了偏好:旧的提示记录没用了
+        if (patch.model !== undefined && patch.modelNotice === undefined)
+            delete own["modelNotice"];
+        if (Object.keys(own).length)
+            all[agent] = own;
+        else
+            delete all[agent];
+        if (Object.keys(all).length)
+            file["agents"] = all;
+        else
+            delete file["agents"];
+    });
+}
+/** 纯函数:用户偏好在阵容里就用它,否则网关默认。 */
+export function chooseAgentModel(config, preferred) {
+    if (preferred && config.models.some((m) => m.id === preferred))
+        return { model: preferred };
+    return { model: config.defaultModel, ...(preferred ? { missing: preferred } : {}) };
+}
+/**
+ * 启动时选模型。用户选的模型不在阵容里时退回网关默认,同一个 id 只提示一次;
+ * 它回到阵容后清掉提示记录(再消失时会再提示)。偏好本身不删:模型可能只是暂时下架。
+ */
+export function resolveLaunchModel(agent, config, deps = {}) {
+    const prefs = deps.prefs ?? readAgentPrefs(agent);
+    const choice = chooseAgentModel(config, prefs.model);
+    const save = deps.save ?? ((patch) => {
+        try {
+            saveAgentPrefs(agent, patch);
+        }
+        catch {
+            // config.json 写不进去不挡启动,最多下次再提示一次
+        }
+    });
+    if (choice.missing) {
+        if (prefs.modelNotice !== choice.missing) {
+            deps.notify?.(choice.missing, choice.model);
+            save({ modelNotice: choice.missing });
+        }
+    }
+    else if (prefs.modelNotice) {
+        save({ modelNotice: null });
+    }
+    return choice.model;
+}

package/dist/agents/runtime.d.ts

@@ -0,0 +1,354 @@
+import { existsSync } from "node:fs";
+import type { SiteId } from "../site.js";
+interface ParsedVersion {
+    nums: [number, number, number];
+    pre?: string;
+}
+export declare function parseVersion(value: string | undefined | null): ParsedVersion | undefined;
+export declare function isVersion(value: unknown): value is string;
+/** 规范化:去掉前导 v、首尾空白;不是版本号返回 undefined。 */
+export declare function normalizeVersion(value: unknown): string | undefined;
+/** semver 比较(预发布段按标识符逐段比,数字段小于字母段;够用,不处理 build metadata)。 */
+export declare function compareVersions(a: string, b: string): number;
+/** `claude --version` 之类的输出 → 版本号(取第一个形如 x.y.z 的片段)。 */
+export declare function versionFromOutput(output: string): string | undefined;
+export interface RuntimeBrake {
+    minVersion?: string;
+    maxTestedVersion?: string;
+    blockedVersions: string[];
+}
+export declare const NO_BRAKE: RuntimeBrake;
+/** 网关 runtime 字段 → RuntimeBrake;非法值按「没设」处理(blocked 里的非法项丢弃)。 */
+export declare function brakeFromApi(runtime: unknown): RuntimeBrake;
+export type BrakeVerdict = "ok" | "blocked" | "below_min" | "above_max_tested";
+/**
+ * 安装与运行用同一套规则:blocked 不装不用、低于 min 不装不用、高于 max_tested 不装不用。
+ * 后台把 max_tested 调低,已装的更高版本下次启动时就会被换下来(见 planRuntime)。
+ */
+export declare function checkBrake(version: string, brake: RuntimeBrake): BrakeVerdict;
+export declare const allowedByBrake: (v: string, brake: RuntimeBrake) => boolean;
+/**
+ * 自动更新 / 首次安装的目标:候选(官方 latest、网关的 max_tested 等)里刹车允许安装的最高版本。
+ * latest 超过 max_tested 时自然退到 max_tested(它是测过的版本,必然已发布)。
+ */
+export declare function bestInstallTarget(candidates: Array<string | undefined>, brake: RuntimeBrake): string | undefined;
+export type ManagedAgent = "claude" | "codex";
+export declare const MANAGED_AGENTS: readonly ManagedAgent[];
+export declare function isManagedAgent(value: unknown): value is ManagedAgent;
+/** 平台二进制所在的 npm 包:装进 node_modules 的目录名,以及它在 npm 源上的名字和版本。 */
+export interface PlatformPackageRef {
+    /** node_modules 下的目录名(lockfile 的键) */
+    dir: string;
+    /** npm 源上的包名(npm 别名时与 dir 不同) */
+    name: string;
+    /** npm 源上的版本 */
+    version: string;
+}
+export interface AgentRuntimeSpec {
+    agent: ManagedAgent;
+    /** 官方 npm 包 */
+    npmPackage: string;
+    /** 用户机器上可能已有的同名命令 */
+    command: string;
+    /** 指定可执行文件路径的环境变量(最高优先级) */
+    binEnv: string;
+    /** 探测版本时指向启动器自己目录的环境变量,免得碰到用户自己的配置目录 */
+    configDirEnv: string;
+    /** 探测版本时额外设的环境(关掉自动更新之类) */
+    probeEnv: Readonly<Record<string, string>>;
+    /** 平台二进制包;不支持的系统/架构返回 undefined */
+    platformPackage: (version: string, platform: NodeJS.Platform, arch: string, musl: boolean) => PlatformPackageRef | undefined;
+    /** 可执行文件在 node_modules 下的相对路径(posix 写法);不支持的系统/架构返回 undefined */
+    binInNodeModules: (platform: NodeJS.Platform, arch: string, musl: boolean) => string | undefined;
+}
+/**
+ * 官方包的 bin 就是 `bin/claude.exe`(各平台同名):postinstall 把对应平台的原生二进制
+ * 复制到这里。直接起这个文件,不经 node_modules/.bin 的 shell 包装(Windows 上是 .cmd)。
+ * 平台包名与官方 install.cjs 的 PLATFORMS 表一致。
+ */
+export declare const CLAUDE_RUNTIME: AgentRuntimeSpec;
+/**
+ * Codex:主包 `@openai/codex` 只有一个 JS 入口 `bin/codex.js`,平台二进制在 optionalDependencies 里,
+ * 以 npm 别名装进来(`@openai/codex-darwin-arm64` → `npm:@openai/codex@<版本>-darwin-arm64`)。
+ * 直接起平台包里的原生二进制,不经 codex.js(那层只是找二进制、设几个「由 npm 管理」的环境变量,
+ * 让它提示用 npm 升级;更新由启动器管,不需要)。原生二进制按自己所在目录找 rg 等附带文件。
+ */
+export declare const CODEX_RUNTIME: AgentRuntimeSpec;
+export declare function runtimeSpec(agent: ManagedAgent): AgentRuntimeSpec;
+export interface RuntimePaths {
+    /** ~/.u1s1/agents/<agent> */
+    root: string;
+    runtimeDir: string;
+    stateFile: string;
+    npmCache: string;
+}
+export declare function runtimePaths(agentsRoot: string, agent: ManagedAgent): RuntimePaths;
+export declare function versionDir(paths: RuntimePaths, version: string): string;
+export declare function managedBinPath(paths: RuntimePaths, spec: AgentRuntimeSpec, version: string): string;
+export interface RuntimeState {
+    /** 启动器管理的、当前使用的版本(runtime/<版本> 已装好且验证过) */
+    current?: string;
+    /** `u1s1 agents pin` 锁定的版本 */
+    pinned?: string;
+    /** 上次查官方最新版的时间(ms) */
+    lastCheckAt?: number;
+    /** 上次查到的官方 latest */
+    latest?: string;
+    /** 每日检查算出的待更新版本:下次启动前安装 */
+    pending?: string;
+}
+export declare function readRuntimeState(paths: RuntimePaths): RuntimeState;
+export declare function writeRuntimeState(paths: RuntimePaths, state: RuntimeState): void;
+export declare function updateRuntimeState(paths: RuntimePaths, patch: Partial<RuntimeState>): RuntimeState;
+/** runtime/ 下已装好的版本(目录名是版本号、可执行文件存在),从新到旧。 */
+export declare function installedVersions(paths: RuntimePaths, spec: AgentRuntimeSpec, exists?: typeof existsSync): string[];
+export type RuntimeSource = "env" | "managed" | "path";
+export interface FoundRuntime {
+    source: RuntimeSource;
+    bin: string;
+    version: string;
+}
+/**
+ * PATH 里找命令。Windows 只认 .exe:npm 全局装出来的 claude.cmd 要经 shell 才能起,
+ * 参数转义有坑(CVE-2024-27980 之后 Node 也不再直接 spawn .cmd),不值得冒险。
+ */
+export declare function findOnPath(command: string, opts: {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    exists?: (p: string) => boolean;
+}): string | undefined;
+/**
+ * 跑 `<bin> --version` 取版本。环境里去掉密钥、关掉自动更新;配置目录(CLAUDE_CONFIG_DIR /
+ * CODEX_HOME)指到启动器自己的目录,免得探测用户自己装的客户端时碰到用户的 ~/.claude、~/.codex。
+ */
+export declare function probeVersion(bin: string, configDir?: string, spec?: AgentRuntimeSpec): string | undefined;
+/** 版本高于 max_tested、这次没用上的那份客户端(给用户解释为什么换版本 / 另装一份)。 */
+export interface SkippedRuntime extends FoundRuntime {
+    maxTestedVersion: string;
+}
+export type RuntimePlan = {
+    action: "use";
+    runtime: FoundRuntime;
+    pinIgnored?: string;
+    skipped?: SkippedRuntime[];
+} | {
+    action: "install";
+    version: string;
+    reason: "first" | "update" | "pin" | "blocked" | "below_min" | "above_max_tested";
+    /** 安装失败时可以退回的版本(没有 = 必须装成功才能启动) */
+    fallback?: FoundRuntime;
+    /** 第一次从官方下载:要先征得用户同意 */
+    needsConsent: boolean;
+    pinIgnored?: string;
+    skipped?: SkippedRuntime[];
+} | {
+    action: "error";
+    /** update_required:自动更新关着,托管的当前版本过不了刹车,要用户自己更新(u1s1 agents install) */
+    code: "env_bin_unusable" | "env_bin_brake" | "no_version" | "update_required";
+    verdict?: BrakeVerdict;
+    bin?: string;
+    version?: string;
+};
+export interface PlanInput {
+    brake: RuntimeBrake;
+    state: RuntimeState;
+    /** 环境变量指定的可执行文件;version 为 undefined 表示跑不起来 */
+    envBin?: () => Promise<{
+        bin: string;
+        version?: string;
+    } | undefined>;
+    /** 启动器管理的当前版本(state.current 且可执行文件在) */
+    managed: () => Promise<FoundRuntime | undefined>;
+    /** 已装好的托管版本列表 */
+    installed: () => string[];
+    /** 用户机器上已有的命令 */
+    onPath: () => Promise<FoundRuntime | undefined>;
+    /** 官方 latest(只在需要时才查) */
+    latest: () => Promise<string | undefined>;
+    /**
+     * 自动更新(`u1s1 config set <客户端>.auto-update off` 关掉;缺省开)。关着时不装每日检查记下的
+     * 新版;托管的当前版本过不了刹车(停用、低于最低版本、高于已验证的最高版本)也不替用户换,
+     * 返回 update_required。pin、首次下载、`u1s1 agents install` 都是用户自己的动作,不受影响。
+     */
+    autoUpdate?: boolean;
+}
+/**
+ * 查找顺序:环境变量 → ~/.u1s1/agents/<客户端>(pin 优先) → PATH 里已有的同名命令 → 下载。
+ * 只做决定、不做 I/O 副作用;所有探测都是惰性的,用不到的不跑。
+ *
+ * 高于 max_tested 的版本一律不用:u1s1 自己装的换成不超过上限的版本(装不上不退回,没有
+ * fallback);环境变量指定的和 PATH 里的不替用户动,接着往下找 / 另装一份,并在 skipped 里说明。
+ */
+export declare function planRuntime(input: PlanInput): Promise<RuntimePlan>;
+export interface NpmCommand {
+    command: string;
+    /** 放在 npm 参数前面(用 node 直接跑 npm-cli.js 时是脚本路径) */
+    prefixArgs: string[];
+    source: "bundled" | "path";
+}
+/**
+ * npm 查找顺序:
+ *   1. 随运行本 CLI 的 Node 一起的 npm(官方 Node 发行包的布局):
+ *        Linux/macOS: <node 所在目录>/../lib/node_modules/npm/bin/npm-cli.js
+ *        Windows:     <node.exe 所在目录>/node_modules/npm/bin/npm-cli.js
+ *      便携包里 node 在 ~/.u1s1/node/bin/node(Windows ~/.u1s1/node/node.exe),所以打包时
+ *      npm 放到 ~/.u1s1/node/lib/node_modules/npm(Windows ~/.u1s1/node/node_modules/npm)。
+ *      用当前 Node(process.execPath)直接跑 npm-cli.js,不依赖 PATH、不经 shell。
+ *   2. PATH 里的 npm。Windows 上 npm.cmd 旁边的 node_modules/npm/bin/npm-cli.js,
+ *      同样用 node 直接跑(不 spawn .cmd)。
+ */
+export declare function findNpm(opts: {
+    execPath: string;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    exists?: (p: string) => boolean;
+}): NpmCommand | undefined;
+/** 中国站走国内 npm 镜像(同一份包,带完整性校验);U1S1_NPM_REGISTRY 可覆盖。 */
+export declare function npmRegistryFor(site: SiteId, env?: NodeJS.ProcessEnv): string;
+/** npm 的平台二进制子包在 node_modules 下的目录名。 */
+export declare function platformPackage(spec: AgentRuntimeSpec, platform?: NodeJS.Platform, arch?: string, musl?: boolean): string | undefined;
+/** 某个版本的平台二进制子包(目录名 + npm 源上的名字与版本)。 */
+export declare function platformPackageRef(spec: AgentRuntimeSpec, version: string, platform?: NodeJS.Platform, arch?: string, musl?: boolean): PlatformPackageRef | undefined;
+export interface PackageMeta {
+    version: string;
+    integrity?: string;
+    tarball?: string;
+    unpackedSize?: number;
+}
+export declare function fetchPackageMeta(registry: string, pkg: string, tag: string, fetchImpl?: typeof fetch): Promise<PackageMeta | undefined>;
+export declare function fetchLatestVersion(registry: string, pkg: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/**
+ * 压缩包大小。npm 源对 HEAD 不一定给 content-length(registry.npmjs.org 就不给),
+ * 用只取 1 字节的 Range 请求读 content-range 里的总长;国内镜像会 302 到 CDN,fetch 自动跟随。
+ */
+export declare function downloadSize(url: string | undefined, fetchImpl?: typeof fetch): Promise<number | undefined>;
+export interface DownloadInfo {
+    agent: ManagedAgent;
+    npmPackage: string;
+    version: string;
+    registry: string;
+    /** 压缩包下载量(字节),拿不到为 undefined */
+    downloadBytes?: number;
+    /** 解压后占用(字节) */
+    unpackedBytes?: number;
+}
+export declare class RuntimeInstallError extends Error {
+    readonly code: "declined" | "no_npm" | "npm_failed" | "verify_failed" | "unsupported_platform";
+    readonly detail?: string | undefined;
+    /** 这次安装本来是要换下这些超出 max_tested 的版本(ensureAgentRuntime 填,给调用方说明后果) */
+    skipped?: SkippedRuntime[];
+    constructor(code: "declined" | "no_npm" | "npm_failed" | "verify_failed" | "unsupported_platform", message: string, detail?: string | undefined);
+}
+export interface InstallHooks {
+    /** 首次下载前征得同意;返回 false = 用户拒绝 */
+    consent?: (info: DownloadInfo) => Promise<boolean>;
+    /** 进度与阶段提示(写 stderr) */
+    log: (line: string) => void;
+    /** 进度行(同一行刷新;非 TTY 时可不实现) */
+    progress?: (downloadedBytes: number, totalBytes: number | undefined) => void;
+    /** 文案(i18n 在调用方) */
+    text: InstallText;
+}
+export interface InstallText {
+    noNpm: () => string;
+    npmFailed: (attempt: number, max: number) => string;
+    retrying: (seconds: number) => string;
+    verifyFailed: (detail: string) => string;
+    declined: () => string;
+    unsupported: () => string;
+    installing: (version: string) => string;
+    installed: (version: string) => string;
+    /** 已有的某份客户端高于 max_tested、这次不用它时的说明;不给就不说明(桌面端自己处理 skipped) */
+    overMaxTested?: (skipped: SkippedRuntime) => string;
+}
+export interface InstallOptions {
+    spec: AgentRuntimeSpec;
+    paths: RuntimePaths;
+    version: string;
+    registry: string;
+    needsConsent: boolean;
+    hooks: InstallHooks;
+    /** 测试注入 */
+    npm?: NpmCommand;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+    /** 校验时跑 --version 用的隔离配置目录(CLAUDE_CONFIG_DIR / CODEX_HOME) */
+    probeConfigDir?: string;
+}
+/**
+ * 装一个确切版本:npm install 到暂存目录 → 校验(锁文件里的 integrity 与 registry 元数据一致、
+ * 可执行文件报出的版本号就是目标版本)→ 整目录改名成 runtime/<版本>。中途失败不影响已装的版本。
+ */
+export declare function installRuntime(opts: InstallOptions): Promise<FoundRuntime>;
+/**
+ * 完整性校验。npm 自己已按 registry 元数据里的 integrity 校验过每个压缩包;这里再确认
+ * 装进来的正是我们要的那两个包、那个版本(锁文件条目与刚取的元数据一致),
+ * 且可执行文件能跑、报出的就是目标版本(postinstall 没装上平台二进制时这里会失败)。
+ */
+export declare function verifyStaging(input: {
+    spec: AgentRuntimeSpec;
+    staging: string;
+    version: string;
+    platPkg: string;
+    /** 平台包在 npm 源上的版本(npm 别名时带平台后缀,如 0.167.2-darwin-arm64);默认同 version */
+    platVersion?: string;
+    mainMeta?: PackageMeta;
+    platMeta?: PackageMeta;
+    probe?: (bin: string) => string | undefined;
+}): string | undefined;
+export declare function npmInstallArgs(o: {
+    staging: string;
+    cache: string;
+    spec: string;
+    registry: string;
+}): string[];
+/** npm 的子进程环境:去掉密钥;当前 Node 所在目录放到 PATH 最前,postinstall 的 `node install.cjs` 用的就是它。 */
+export declare function npmEnv(base: NodeJS.ProcessEnv, execPath: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+/**
+ * 每天最多查一次官方最新版;算出刹车允许的目标版本高于当前托管版本时记为 pending,
+ * 下次启动前安装(planRuntime 的 update 分支)。pin 了就不记 pending。
+ */
+export declare function dailyUpdateCheck(input: {
+    paths: RuntimePaths;
+    brake: RuntimeBrake;
+    now: number;
+    latest: () => Promise<string | undefined>;
+    force?: boolean;
+}): Promise<RuntimeState>;
+export interface EnsureRuntimeOptions {
+    brake: RuntimeBrake;
+    site: SiteId;
+    /** ~/.u1s1/agents;测试与桌面端可覆盖 */
+    agentsRoot: string;
+    hooks: InstallHooks;
+    /** 探测版本时给子进程的 CLAUDE_CONFIG_DIR / CODEX_HOME 隔离目录(须已存在) */
+    probeConfigDir?: string;
+    env?: NodeJS.ProcessEnv;
+    /** 测试注入:替换真正的下载安装 */
+    install?: (opts: InstallOptions) => Promise<FoundRuntime>;
+    /** 见 PlanInput.autoUpdate;缺省开 */
+    autoUpdate?: boolean;
+}
+export interface EnsuredRuntime extends FoundRuntime {
+    /** pin 的版本被刹车挡住、已忽略 */
+    pinIgnored?: string;
+    /** 高于 max_tested、这次没用上的客户端 */
+    skipped?: SkippedRuntime[];
+    /** 安装失败、退回到旧版本时的错误 */
+    installError?: RuntimeInstallError;
+}
+export declare class RuntimePlanError extends Error {
+    readonly plan: Extract<RuntimePlan, {
+        action: "error";
+    }>;
+    constructor(plan: Extract<RuntimePlan, {
+        action: "error";
+    }>);
+}
+/**
+ * 找到(必要时下载或更新)可用的客户端运行时。CLI(`u1s1 claude` / `u1s1 codex`)与桌面端共用。
+ * 失败抛 RuntimePlanError(刹车/版本问题)或 RuntimeInstallError(下载问题)。
+ */
+export declare function ensureAgentRuntime(agent: ManagedAgent, opts: EnsureRuntimeOptions): Promise<EnsuredRuntime>;
+export {};