@nvae/llmswitch 1.2.0 → 1.3.0

package/dist/utils/file-lock.js

@@ -0,0 +1,149 @@
+/**
+ * Cross-process advisory file lock.
+ *
+ * Used to serialise read-modify-write on the gateway's shared JSON state
+ * (rate-limit counters, usage accounting). `llms gateway serve` and the
+ * daemon can run at the same time, and both write those files with
+ * atomic-replace — without a lock they silently clobber each other's whole
+ * file.
+ *
+ * Locking is best-effort by design: `tryWithFileLock` returns a miss instead of
+ * blocking forever, so bookkeeping can degrade rather than stall live traffic.
+ */
+import { readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { ensureDir } from "./fs.js";
+const DEFAULT_TIMEOUT_MS = 500;
+const DEFAULT_STALE_MS = 5_000;
+const DEFAULT_SPIN_MS = 10;
+function sleepSync(ms) {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function readLockId(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return typeof raw.id === "string" ? raw.id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A lock is reclaimable when its owner is gone. A dead owner can never release
+ * the lock, so that case is reclaimed immediately; when ownership cannot be
+ * determined we fall back to an age check that trusts whichever of the file
+ * mtime or the recorded timestamp looks older.
+ */
+function reclaimable(path, staleMs) {
+    let record = {};
+    let readable = false;
+    try {
+        record = JSON.parse(readFileSync(path, "utf8"));
+        readable = true;
+    }
+    catch {
+        // Unreadable lock file: fall back to the age check below.
+    }
+    if (readable && typeof record.pid === "number") {
+        return !pidAlive(record.pid);
+    }
+    let fileAge = Number.POSITIVE_INFINITY;
+    try {
+        fileAge = Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return true;
+    }
+    const recordedAge = typeof record.at === "number"
+        ? Date.now() - record.at
+        : Number.NEGATIVE_INFINITY;
+    return Math.max(fileAge, recordedAge) > staleMs;
+}
+function makeLock(path, id) {
+    return {
+        release() {
+            try {
+                if (readLockId(path) === id)
+                    unlinkSync(path);
+            }
+            catch {
+                // Already released or reclaimed.
+            }
+        },
+    };
+}
+/**
+ * Acquire `path` as a lock, or return null when it stays busy past the timeout.
+ */
+export function acquireFileLock(path, options = {}, now = Date.now()) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const spinMs = options.spinMs ?? DEFAULT_SPIN_MS;
+    const id = randomBytes(8).toString("hex");
+    const payload = JSON.stringify({ id, pid: process.pid, at: now });
+    const deadline = now + timeoutMs;
+    // The directory may not exist yet on a fresh install; without this the
+    // exclusive create below fails with ENOENT and persistence never engages.
+    try {
+        ensureDir(dirname(path));
+    }
+    catch {
+        return null;
+    }
+    for (;;) {
+        try {
+            writeFileSync(path, payload, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            return makeLock(path, id);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return null;
+        }
+        if (reclaimable(path, staleMs)) {
+            try {
+                const tmp = `${path}.${id}.tmp`;
+                writeFileSync(tmp, payload, { encoding: "utf8", mode: 0o600 });
+                renameSync(tmp, path);
+                if (readLockId(path) === id)
+                    return makeLock(path, id);
+            }
+            catch {
+                // Someone else won the race; fall through and retry.
+            }
+        }
+        if (Date.now() >= deadline)
+            return null;
+        sleepSync(spinMs);
+    }
+}
+/**
+ * Run `fn` under the lock. When the lock cannot be taken, `onMiss` decides the
+ * fallback (default: run `fn` anyway — callers that must not block traffic).
+ */
+export function tryWithFileLock(path, fn, options = {}, now = Date.now()) {
+    const lock = acquireFileLock(path, options, now);
+    if (!lock) {
+        if (options.onMiss)
+            return options.onMiss();
+        return fn();
+    }
+    try {
+        return fn();
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/utils/fs.js

@@ -1,4 +1,4 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync, } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 export function ensureDir(dir) {
@@ -6,31 +6,152 @@ export function ensureDir(dir) {
 }
 export function atomicWriteFile(filePath, content, mode = 0o600) {
     ensureDir(dirname(filePath));
-    const tmp = join(dirname(filePath), `.${randomBytes(8).toString("hex")}.tmp`);
-    writeFileSync(tmp, content, { encoding: "utf8", mode });
+    const dir = dirname(filePath);
+    // 同目录写临时文件再 rename，保证替换是原子的。前缀固定，便于清理历史残留。
+    const tmp = join(dir, `${TMP_PREFIX}${randomBytes(8).toString("hex")}.tmp`);
     try {
-        chmodSync(tmp, mode);
+        writeFileSync(tmp, content, { encoding: "utf8", mode });
+        try {
+            chmodSync(tmp, mode);
+        }
+        catch {
+            // Windows may ignore mode; continue.
+        }
+        renameSync(tmp, filePath);
     }
-    catch {
-        // Windows may ignore mode; continue.
+    catch (err) {
+        // 失败时不要把临时文件留在用户目录里——它可能含明文密钥。
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch {
+            // ignore
+        }
+        throw err;
     }
-    renameSync(tmp, filePath);
     try {
         chmodSync(filePath, mode);
     }
     catch {
         // ignore
     }
+    pruneStaleTempFiles(dir);
+}
+const TMP_PREFIX = ".llmswitch-";
+const TMP_STALE_MS = 60 * 60 * 1000;
+/**
+ * Write several files as one unit.
+ *
+ * Adapters often have to update two files together (Codex: config.toml + .env;
+ * OpenCode: opencode.json + auth.json). Writing them one by one means a failure
+ * on the second leaves the tool pointing at a provider whose credentials were
+ * never written. On failure we restore every file already written back to its
+ * previous content, or delete it if it did not exist before.
+ *
+ * Callers must build all contents *before* calling this, so that a build-time
+ * throw also leaves nothing half-applied.
+ */
+export function writeFilesAtomically(writes) {
+    const done = [];
+    try {
+        for (const write of writes) {
+            const previous = existsSync(write.path)
+                ? readFileSync(write.path, "utf8")
+                : null;
+            atomicWriteFile(write.path, write.content, write.mode);
+            done.push({ path: write.path, previous });
+        }
+    }
+    catch (err) {
+        for (const entry of done.reverse()) {
+            try {
+                if (entry.previous === null)
+                    unlinkSync(entry.path);
+                else
+                    atomicWriteFile(entry.path, entry.previous);
+            }
+            catch {
+                // 回滚只能尽力而为；原始错误更重要，继续抛出。
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Sweep temp files left behind by a process that died between write and rename.
+ * They can contain plaintext API keys, so they must not accumulate in
+ * ~/.claude, ~/.codex or ~/.config/opencode.
+ */
+function pruneStaleTempFiles(dir) {
+    try {
+        const now = Date.now();
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith(TMP_PREFIX) || !name.endsWith(".tmp"))
+                continue;
+            const full = join(dir, name);
+            if (now - statSync(full).mtimeMs < TMP_STALE_MS)
+                continue;
+            unlinkSync(full);
+        }
+    }
+    catch {
+        // Best effort only; never fail a write because cleanup failed.
+    }
 }
+/** Keep at most this many backups per label, newest first. */
+const MAX_BACKUPS_PER_LABEL = 10;
 export function backupFile(sourcePath, backupDir, label) {
     if (!existsSync(sourcePath))
         return undefined;
     ensureDir(backupDir);
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const dest = join(backupDir, `${label}-${stamp}.bak`);
+    const dest = uniqueBackupPath(backupDir, label);
     copyFileSync(sourcePath, dest);
+    try {
+        chmodSync(dest, 0o600);
+    }
+    catch {
+        // ignore
+    }
+    // 备份里含明文 API Key，且每次 apply/deactivate 都会产生一份。
+    // 不设上限的话既会无限占盘，也会让历史密钥永久堆积。
+    pruneBackups(backupDir, label);
     return dest;
 }
+/**
+ * ISO timestamps only have millisecond resolution, and two backups of the same
+ * label can easily land in the same millisecond (apply writes config + env
+ * back to back). Without a tiebreaker the second copy silently overwrites the
+ * first. The suffix is zero-padded so lexicographic order stays time order.
+ */
+function uniqueBackupPath(backupDir, label) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const base = join(backupDir, `${label}-${stamp}`);
+    if (!existsSync(`${base}.bak`))
+        return `${base}.bak`;
+    for (let i = 1; i < 1000; i++) {
+        const candidate = `${base}-${String(i).padStart(3, "0")}.bak`;
+        if (!existsSync(candidate))
+            return candidate;
+    }
+    return `${base}-${randomBytes(4).toString("hex")}.bak`;
+}
+function pruneBackups(backupDir, label) {
+    try {
+        const prefix = `${label}-`;
+        const files = readdirSync(backupDir)
+            .filter((name) => name.startsWith(prefix) && name.endsWith(".bak"))
+            // 文件名里的时间戳是 ISO 且定长，字典序即时间序。
+            .sort()
+            .reverse();
+        for (const name of files.slice(MAX_BACKUPS_PER_LABEL)) {
+            unlinkSync(join(backupDir, name));
+        }
+    }
+    catch {
+        // Best effort only.
+    }
+}
 export function maskSecret(value) {
     if (!value)
         return "(empty)";
@@ -38,3 +159,60 @@ export function maskSecret(value) {
         return "****";
     return `${value.slice(0, 4)}…${value.slice(-4)}`;
 }
+/**
+ * Read + parse a config file we do not own, turning parser failures into an
+ * actionable Chinese error instead of a raw SyntaxError. A single stray comma in
+ * the user's own ~/.claude/settings.json must not take the whole CLI down with
+ * an unreadable stack trace.
+ */
+export function readStructuredFile(path, parser, opts) {
+    if (!existsSync(path))
+        return opts.fallback();
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`无法读取${opts.label}「${path}」：${msg}`);
+    }
+    // 空文件（或只有空白）按“尚未配置”处理，而不是解析失败。
+    if (!text.trim())
+        return opts.fallback();
+    try {
+        return parser(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`${opts.label}「${path}」解析失败：${msg}。` +
+            `请修复该文件的语法，或将其移走后重试（本工具会在写入前自动备份）。`);
+    }
+}
+/** True only for a real `{...}` object (not null, not an array). */
+export function isPlainObject(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value));
+}
+/**
+ * Spread-safe accessor for a nested table inside someone else's config file.
+ * If the key holds a non-object (array/string/number), we must not spread it —
+ * that silently produces a garbage structure like {"0":"a","1":"b"}.
+ */
+export function plainObjectAt(container, key) {
+    const value = container[key];
+    return isPlainObject(value) ? value : {};
+}
+/**
+ * Read a string map (e.g. an `env` block), dropping non-string values instead of
+ * carrying them into a Record<string, string> that the type system trusts.
+ */
+export function stringRecordAt(container, key) {
+    const source = plainObjectAt(container, key);
+    const out = {};
+    for (const [k, v] of Object.entries(source)) {
+        if (typeof v === "string")
+            out[k] = v;
+        else if (typeof v === "number" || typeof v === "boolean")
+            out[k] = String(v);
+    }
+    return out;
+}

package/dist/utils/model-metadata.js

@@ -1,7 +1,15 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { requestWithNodeTransport } from "../bridge/transport.js";
+import { atomicWriteFile } from "./fs.js";
+import { getAppConfigRoot } from "./paths.js";
 export const MODEL_METADATA_SOURCE = "https://models.lonae.com";
 const DEFAULT_ENDPOINT = `${MODEL_METADATA_SOURCE}/api/v1/models`;
 const PAGE_SIZE = 1000;
+/** Hard cap on pagination; see fetchModelMetadata. */
+const MAX_PAGES = 50;
+/** Metadata changes slowly, so a day-old cache is fine and saves a round trip. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 /** Trailing date stamp, e.g. "-20250219" in "claude-3-7-sonnet-20250219". */
 const DATE_SUFFIX_RE = /-?\d{8}$/;
 /**
@@ -151,10 +159,18 @@ export function collectModelMeta(catalog, models) {
 export async function fetchModelMetadata(options = {}) {
     const endpoint = options.endpoint || DEFAULT_ENDPOINT;
     const timeoutMs = options.timeoutMs ?? 15_000;
+    // 每次选模型都联网拉全量元数据太重，先看本地缓存。
+    if (!options.force) {
+        const cached = readMetadataCache(endpoint);
+        if (cached)
+            return parseModelMetadata({ data: cached });
+    }
     const rows = [];
     let total = Infinity;
     let page = 1;
-    while (rows.length < total) {
+    // 页数上限：meta.total 若谎报偏大、而上游又持续返回非空页，
+    // 没有这个上限就会一直翻页下去。
+    while (rows.length < total && page <= MAX_PAGES) {
         const url = `${endpoint}${endpoint.includes("?") ? "&" : "?"}page_size=${PAGE_SIZE}&page=${page}`;
         const payload = await requestJson(url, options.proxy, timeoutMs);
         const batch = payload && typeof payload === "object"
@@ -169,8 +185,45 @@ export async function fetchModelMetadata(options = {}) {
         total = typeof totalRaw === "number" && totalRaw > 0 ? totalRaw : rows.length;
         page += 1;
     }
+    if (rows.length > 0)
+        writeMetadataCache(endpoint, rows);
     return parseModelMetadata({ data: rows });
 }
+export function getModelMetadataCachePath() {
+    return join(getAppConfigRoot(), "model-metadata-cache.json");
+}
+function readMetadataCache(endpoint) {
+    const path = getModelMetadataCachePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw?.version !== 1 || raw.endpoint !== endpoint)
+            return null;
+        if (!Array.isArray(raw.rows) || raw.rows.length === 0)
+            return null;
+        if (Date.now() - raw.fetchedAt > CACHE_TTL_MS)
+            return null;
+        return raw.rows;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMetadataCache(endpoint, rows) {
+    try {
+        const payload = {
+            version: 1,
+            endpoint,
+            fetchedAt: Date.now(),
+            rows,
+        };
+        atomicWriteFile(getModelMetadataCachePath(), JSON.stringify(payload) + "\n");
+    }
+    catch {
+        // 缓存失败不影响本次结果。
+    }
+}
 async function requestJson(url, proxy, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nvae/llmswitch",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI to switch LLM providers and models for Claude Code, Codex, and OpenCode",
   "type": "module",
   "bin": {
@@ -19,7 +19,11 @@
     "start": "bun run ./src/index.ts",
     "test": "bun test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "bun run typecheck && bun run build"
+    "lint": "biome lint src test scripts",
+    "lint:fix": "biome lint --write src test scripts",
+    "format": "biome format --write src test scripts",
+    "verify": "bun run typecheck && bun run lint && bun test",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun run build"
   },
   "engines": {
     "node": ">=20"
@@ -45,6 +49,7 @@
     "socks-proxy-agent": "8.0.5"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.3.14",
     "@types/bun": "^1.2.19",
     "@types/node": "^24.0.0",
     "typescript": "^5.8.3"