codex-slot 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@
 
 [中文文档](./docs/zh-CN.md)
 
-## Features
+## Overview
 
 - Reuse the official `~/.codex` login state
 - Manage multiple accounts or workspaces as separate slots
@@ -30,15 +30,16 @@ GitHub installation from the repository URL is not supported.
 
 ## Quick Start
 
-Import your current Codex login state:
+1. Import your current Codex login state:
 
 ```bash
 codex-slot import current ~
 ```
 
 `import` copies the official login state into `~/.cslot/homes/<name>` instead of referencing the source HOME directly.
+`current` is only an example slot name, not a built-in account.
 
-Check latest usage:
+2. Check the latest usage:
 
 ```bash
 codex-slot status
@@ -62,7 +63,7 @@ If you only want a non-interactive snapshot of the current state:
 codex-slot status --no-interactive
 ```
 
-Start the local proxy:
+3. Start the local proxy:
 
 ```bash
 codex-slot start
@@ -80,12 +81,34 @@ codex-slot start
 ```bash
 codex-slot add <name>
 codex-slot del <name>
+codex-slot rename <oldName> <newName>
 codex-slot import <name> [HOME]
 codex-slot status
 codex-slot start [--port <port>]
 codex-slot stop
 ```
 
+Common patterns:
+
+- `cslot import work ~/workspace-home`
+- `cslot rename work work-main`
+- `cslot start`
+
+## Architecture
+
+The project is intentionally split by responsibility:
+
+- `src/cli.ts`: CLI bootstrap and command registration only
+- `src/account-commands.ts`: account import, login, remove command handlers
+- `src/account-commands.ts`: also owns slot rename command handling
+- `src/service-control.ts`: background service lifecycle management
+- `src/status-command.ts`: usage refresh output and interactive toggle UI
+- `src/codex-config.ts`: managed `~/.codex/config.toml` apply/restore logic
+- `src/account-store.ts`, `src/usage-sync.ts`, `src/scheduler.ts`, `src/status.ts`: core domain and runtime logic
+- `src/text.ts`: shared bilingual text and locale-independent formatting helpers
+
+This keeps the CLI entry thin while preserving stable behavior in the lower-level modules.
+
 ## How `status` Works
 
 `codex-slot status` does not render stale data from the official `registry.json` cache.
@@ -99,23 +122,22 @@ Instead it:
 
 ## Managed Codex Config
 
-`codex-slot start` writes or updates a provider block like this, based on the current `~/.cslot/config.yaml`:
+`codex-slot start` writes or updates a managed provider block like this, based on the current `~/.cslot/config.yaml`:
 
 ```toml
 [model_providers.cslot]
 name = "cslot"
 base_url = "http://127.0.0.1:4389/v1"
-http_headers = { Authorization = "Bearer cslot-defaultkey" }
+http_headers = { Authorization = "Bearer <your-local-api-key>" }
 wire_api = "responses"
 ```
 
 Behavior:
 
-- If global `model_provider` or `# model_provider = ...` exists, it is normalized to `model_provider = "cslot"`
-- If `[model_providers.cslot]` already exists, only that provider block is replaced with the fresh one above
+- A managed marker block is inserted for `model_provider = "cslot"` and `[model_providers.cslot]`
+- On `cslot stop`, the original `model_provider` line and original `[model_providers.cslot]` block are restored from the saved snapshot
 - Other providers and settings in `config.toml` are left untouched
 - If you start with `--port`, the port is saved to `~/.cslot/config.yaml`
-- `cslot stop` comments out the active `model_provider = "cslot"` line and keeps the rest of the file unchanged
 
 ## Data Directory
 
@@ -126,8 +148,6 @@ Behavior:
 - `~/.cslot/cslot.pid`
 - `~/.cslot/logs/service.log`
 
-If you previously used `~/.codexsw`, it is migrated automatically.
-
 ## Limit Handling
 
 - Weekly limit: blocked until the weekly reset time
@@ -136,8 +156,8 @@ If you previously used `~/.codexsw`, it is migrated automatically.
 
 ## Repository
 
-- GitHub: https://github.com/openxiaobu/cslot
-- Issues: https://github.com/openxiaobu/cslot/issues
+- GitHub: https://github.com/openxiaobu/codex-slot
+- Issues: https://github.com/openxiaobu/codex-slot/issues
 
 ## Development
 

package/dist/account-commands.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAccountImport = handleAccountImport;
+exports.handleAccountLogin = handleAccountLogin;
+exports.handleAccountRemove = handleAccountRemove;
+exports.handleAccountRemoveCommand = handleAccountRemoveCommand;
+exports.handleAccountRename = handleAccountRename;
+const account_service_1 = require("./app/account-service");
+const text_1 = require("./text");
+/**
+ * 将已有的 Codex HOME 目录中的登录态复制到 cslot 自己的隔离目录并纳入管理。
+ *
+ * @param name 本地账号标识，等同于配置中的槽位名。
+ * @param codexHome 现有 HOME 目录；若未传则默认使用当前用户 HOME。
+ * @returns 无返回值。
+ * @throws 当源目录缺少必要认证文件时抛出异常。
+ */
+function handleAccountImport(name, codexHome) {
+    const { account, sourceHome } = (0, account_service_1.importAccount)(name, codexHome);
+    console.log((0, text_1.bi)(`账号已导入: ${account.id}`, `Account imported: ${account.id}`));
+    console.log((0, text_1.bi)(`来源 HOME: ${sourceHome}`, `Source HOME: ${sourceHome}`));
+    console.log((0, text_1.bi)(`已复制到: ${account.codex_home}`, `Copied to: ${account.codex_home}`));
+}
+/**
+ * 执行隔离登录流程，将账号录入到 cslot 管理目录。
+ *
+ * @param name 本地账号标识，等同于配置中的槽位名。
+ * @returns Promise，成功时输出账号目录信息。
+ * @throws 当登录流程失败或认证状态不完整时抛出异常。
+ */
+async function handleAccountLogin(name) {
+    const home = await (0, account_service_1.loginAccount)(name);
+    console.log((0, text_1.bi)(`登录完成，账号目录: ${home}`, `Login completed. Account home: ${home}`));
+}
+/**
+ * 删除配置中的账号项。
+ *
+ * @param name 本地账号标识，等同于配置中的槽位名。
+ * @returns 无返回值。
+ * @throws 当账号不存在时抛出异常。
+ */
+function handleAccountRemove(name) {
+    const removed = (0, account_service_1.removeAccount)(name);
+    if (!removed) {
+        throw new Error((0, text_1.bi)(`未找到账号 ${name}`, `Account not found: ${name}`));
+    }
+    console.log((0, text_1.bi)(`已删除账号配置: ${removed.id}`, `Removed account config: ${removed.id}`));
+}
+/**
+ * `del` 子命令入口：在未提供 name 时先展示当前已录入账号列表，便于选择。
+ *
+ * @param name 可选的账号标识；留空时仅打印账号列表和删除示例。
+ * @returns 无返回值。
+ * @throws 当指定账号不存在时透传删除异常。
+ */
+function handleAccountRemoveCommand(name) {
+    if (!name) {
+        const accounts = (0, account_service_1.listAccounts)();
+        if (accounts.length === 0) {
+            console.log((0, text_1.bi)("当前没有已录入账号。", "No managed accounts found."));
+            return;
+        }
+        console.log((0, text_1.bi)("当前已录入账号（name）：", "Managed accounts (name):"));
+        for (const account of accounts) {
+            if (account.email) {
+                console.log(`- ${account.id} (${account.email})`);
+            }
+            else {
+                console.log(`- ${account.id}`);
+            }
+        }
+        console.log("");
+        console.log((0, text_1.bi)("请使用以下命令删除指定账号，例如：", "Use the following command to remove a specific account, for example:"));
+        console.log("  codex-slot del <name>");
+        return;
+    }
+    handleAccountRemove(name);
+}
+/**
+ * 重命名已有受管槽位。
+ *
+ * @param oldName 原槽位名。
+ * @param newName 新槽位名。
+ * @returns 无返回值。
+ * @throws 当旧槽位不存在、新槽位已存在或目录迁移失败时抛出异常。
+ */
+function handleAccountRename(oldName, newName) {
+    const renamed = (0, account_service_1.renameAccount)(oldName, newName);
+    console.log((0, text_1.bi)(`已重命名账号: ${oldName} -> ${newName}`, `Renamed account: ${oldName} -> ${newName}`));
+    console.log((0, text_1.bi)(`当前目录: ${renamed.codex_home}`, `Current home: ${renamed.codex_home}`));
+}

package/dist/account-store.js

@@ -16,6 +16,7 @@ exports.findManagedAccount = findManagedAccount;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("./config");
+const text_1 = require("./text");
 /**
  * 读取指定账号 HOME 下的 `.codex` 目录。
  *
@@ -87,10 +88,10 @@ function cloneCodexAuthState(sourceHome, targetHome) {
     const sourceAccountsDir = node_path_1.default.join(sourceCodexDir, "accounts");
     const sourceRegistryPath = node_path_1.default.join(sourceAccountsDir, "registry.json");
     if (!node_fs_1.default.existsSync(sourceAuthPath)) {
-        throw new Error(`来源目录缺少 auth.json: ${sourceAuthPath}`);
+        throw new Error((0, text_1.bi)(`来源目录缺少 auth.json: ${sourceAuthPath}`, `Source directory is missing auth.json: ${sourceAuthPath}`));
     }
     if (!node_fs_1.default.existsSync(sourceRegistryPath)) {
-        throw new Error(`来源目录缺少 registry.json: ${sourceRegistryPath}`);
+        throw new Error((0, text_1.bi)(`来源目录缺少 registry.json: ${sourceRegistryPath}`, `Source directory is missing registry.json: ${sourceRegistryPath}`));
     }
     node_fs_1.default.mkdirSync(targetCodexDir, { recursive: true });
     node_fs_1.default.mkdirSync(node_path_1.default.join(targetCodexDir, "accounts"), { recursive: true });

package/dist/app/account-service.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importAccount = importAccount;
+exports.loginAccount = loginAccount;
+exports.removeAccount = removeAccount;
+exports.listAccounts = listAccounts;
+exports.renameAccount = renameAccount;
+const node_fs_1 = __importDefault(require("node:fs"));
+const account_store_1 = require("../account-store");
+const config_1 = require("../config");
+const login_1 = require("../login");
+const state_1 = require("../state");
+const text_1 = require("../text");
+/**
+ * 导入指定 HOME 下的官方 Codex 登录态到受管槽位。
+ *
+ * @param slotName 本地槽位名。
+ * @param codexHome 可选源 HOME；未传时默认当前用户 HOME。
+ * @returns 导入后的受管账号配置与源路径信息。
+ * @throws 当源目录缺少必要认证文件或写入失败时抛出异常。
+ */
+function importAccount(slotName, codexHome) {
+    const sourceHome = codexHome ? (0, config_1.expandHome)(codexHome) : process.env.HOME ?? "";
+    const managedHome = (0, config_1.getManagedHome)(slotName);
+    (0, account_store_1.cloneCodexAuthState)(sourceHome, managedHome);
+    return {
+        account: (0, account_store_1.registerManagedAccount)(slotName, managedHome),
+        sourceHome
+    };
+}
+/**
+ * 通过隔离 HOME 调起官方 `codex login` 完成单账号登录。
+ *
+ * @param slotName 本地槽位名。
+ * @returns Promise，成功时返回登录后的账号 HOME 目录。
+ * @throws 当登录失败或登录态不完整时抛出异常。
+ */
+async function loginAccount(slotName) {
+    return await (0, login_1.loginManagedAccount)(slotName);
+}
+/**
+ * 删除指定受管槽位。
+ *
+ * @param slotName 本地槽位名。
+ * @returns 被删除的账号配置；不存在时返回 `null`。
+ * @throws 无显式抛出。
+ */
+function removeAccount(slotName) {
+    return (0, account_store_1.removeManagedAccount)(slotName);
+}
+/**
+ * 列出当前所有受管账号配置。
+ *
+ * @returns 当前配置中的账号列表。
+ * @throws 当配置读取失败时抛出异常。
+ */
+function listAccounts() {
+    return (0, config_1.loadConfig)().accounts;
+}
+/**
+ * 重命名受管槽位，并同步迁移与账号标识绑定的本地状态。
+ *
+ * 业务规则：
+ * 1. 若账号 HOME 使用默认槽位目录，则一并重命名目录路径。
+ * 2. 若账号 HOME 是自定义路径，则仅更新账号标识，不强改目录。
+ * 3. `state.json` 中与账号标识绑定的 usage/block 缓存会同步迁移。
+ *
+ * @param oldName 原槽位名。
+ * @param newName 新槽位名。
+ * @returns 重命名后的账号配置。
+ * @throws 当旧槽位不存在、新槽位已存在或目录迁移失败时抛出异常。
+ */
+function renameAccount(oldName, newName) {
+    const config = (0, config_1.loadConfig)();
+    const index = config.accounts.findIndex((item) => item.id === oldName);
+    if (index < 0) {
+        throw new Error((0, text_1.bi)(`未找到账号 ${oldName}`, `Account not found: ${oldName}`));
+    }
+    if (config.accounts.some((item) => item.id === newName)) {
+        throw new Error((0, text_1.bi)(`账号 ${newName} 已存在`, `Account already exists: ${newName}`));
+    }
+    const currentAccount = config.accounts[index];
+    const defaultOldHome = (0, config_1.getManagedHome)(oldName);
+    const defaultNewHome = (0, config_1.getManagedHome)(newName);
+    let nextHome = currentAccount.codex_home;
+    if (currentAccount.codex_home === defaultOldHome) {
+        if (node_fs_1.default.existsSync(defaultNewHome)) {
+            throw new Error((0, text_1.bi)(`目标槽位目录已存在: ${defaultNewHome}`, `Target slot directory already exists: ${defaultNewHome}`));
+        }
+        // 只有默认槽位目录才一起迁移，避免误移动用户手工指定的 HOME。
+        if (node_fs_1.default.existsSync(defaultOldHome)) {
+            node_fs_1.default.renameSync(defaultOldHome, defaultNewHome);
+        }
+        nextHome = defaultNewHome;
+    }
+    const renamedAccount = {
+        ...currentAccount,
+        id: newName,
+        name: newName,
+        codex_home: nextHome
+    };
+    config.accounts[index] = renamedAccount;
+    (0, config_1.saveConfig)(config);
+    const state = (0, state_1.loadState)();
+    if (state.account_blocks[oldName]) {
+        state.account_blocks[newName] = state.account_blocks[oldName];
+        delete state.account_blocks[oldName];
+    }
+    if (state.usage_cache[oldName]) {
+        state.usage_cache[newName] = {
+            ...state.usage_cache[oldName],
+            accountId: newName
+        };
+        delete state.usage_cache[oldName];
+    }
+    (0, state_1.saveState)(state);
+    return renamedAccount;
+}

package/dist/app/config-service.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConfig = describeConfig;
+exports.mutateConfig = mutateConfig;
+exports.applyCodexProviderConfig = applyCodexProviderConfig;
+const config_1 = require("../config");
+const codex_config_1 = require("../codex-config");
+const cli_helpers_1 = require("../cli-helpers");
+/**
+ * 返回当前本地配置的只读快照，供 CLI 或其他调用方展示。
+ *
+ * @returns 当前配置快照与默认 Codex 配置路径。
+ * @throws 当配置读取失败时抛出异常。
+ */
+function describeConfig() {
+    return {
+        config: (0, config_1.loadConfig)(),
+        codexConfigPath: (0, codex_config_1.getDefaultCodexConfigPath)()
+    };
+}
+/**
+ * 按输入选项修改本地配置，并返回本次变更摘要。
+ *
+ * @param input 配置修改输入；字段缺失表示不修改该项。
+ * @returns 最新配置快照与已应用的变更列表。
+ * @throws 当端口非法或配置写入失败时抛出异常。
+ */
+function mutateConfig(input) {
+    const config = (0, config_1.loadConfig)();
+    const updates = [];
+    if (input.host) {
+        config.server.host = input.host;
+        updates.push(`host=${config.server.host}`);
+    }
+    if (input.port) {
+        config.server.port = (0, cli_helpers_1.parsePort)(input.port);
+        updates.push(`port=${config.server.port}`);
+    }
+    if (input.apiKey) {
+        config.server.api_key = input.apiKey;
+        updates.push("api_key=已手动设置");
+    }
+    else if (input.regenApiKey) {
+        config.server.api_key = (0, codex_config_1.generateServerApiKey)();
+        updates.push("api_key=已重新生成");
+    }
+    if (updates.length > 0) {
+        (0, config_1.saveConfig)(config);
+    }
+    return { config, updates };
+}
+/**
+ * 将当前受管 provider 配置写入指定的 Codex `config.toml`。
+ *
+ * @param targetPath 可选目标路径；未传时写入默认全局路径。
+ * @returns 实际写入的目标文件路径。
+ * @throws 当配置接管写入失败时抛出异常。
+ */
+function applyCodexProviderConfig(targetPath) {
+    return (0, codex_config_1.applyManagedCodexConfig)(targetPath);
+}

package/dist/app/service-lifecycle-service.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunningPid = getRunningPid;
+exports.startManagedService = startManagedService;
+exports.stopManagedService = stopManagedService;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const codex_config_1 = require("../codex-config");
+const cli_helpers_1 = require("../cli-helpers");
+const config_1 = require("../config");
+/**
+ * 判断后台服务当前是否在运行。
+ *
+ * @returns 运行中的 PID；未运行时返回 `null`。
+ * @throws 无显式抛出。
+ */
+function getRunningPid() {
+    const pidPath = (0, config_1.getPidPath)();
+    if (!node_fs_1.default.existsSync(pidPath)) {
+        return null;
+    }
+    const raw = node_fs_1.default.readFileSync(pidPath, "utf8").trim();
+    const pid = Number(raw);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        node_fs_1.default.rmSync(pidPath, { force: true });
+        return null;
+    }
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        node_fs_1.default.rmSync(pidPath, { force: true });
+        return null;
+    }
+}
+/**
+ * 解析后台服务启动入口，兼容源码运行与构建产物运行两种场景。
+ *
+ * @returns 可直接传给 `spawn` 的命令与参数前缀。
+ * @throws 无显式抛出。
+ */
+function resolveServeEntrypoint() {
+    const serveBasePath = node_path_1.default.resolve(__dirname, "..", "serve");
+    if (node_path_1.default.extname(__filename) === ".ts") {
+        return {
+            command: process.platform === "win32" ? "npx.cmd" : "npx",
+            args: ["tsx", `${serveBasePath}.ts`]
+        };
+    }
+    return {
+        command: process.execPath,
+        args: [`${serveBasePath}.js`]
+    };
+}
+/**
+ * 启动后台服务，并在需要时将端口写回本地配置。
+ *
+ * @param portOverride 可选端口文本；传入时会先校验并落盘到配置。
+ * @returns 启动结果，包含是否已在运行、最终端口、PID 和日志路径。
+ * @throws 当端口非法、接管配置失败或子进程启动失败时抛出异常。
+ */
+function startManagedService(portOverride) {
+    const config = (0, config_1.loadConfig)();
+    const port = portOverride ? (0, cli_helpers_1.parsePort)(portOverride) : config.server.port;
+    if (portOverride) {
+        config.server.port = port;
+        (0, config_1.saveConfig)(config);
+    }
+    const runningPid = getRunningPid();
+    if (runningPid) {
+        return {
+            alreadyRunning: true,
+            pid: runningPid,
+            port,
+            logPath: (0, config_1.getServiceLogPath)()
+        };
+    }
+    (0, codex_config_1.applyManagedCodexConfig)();
+    const logPath = (0, config_1.getServiceLogPath)();
+    const logFd = node_fs_1.default.openSync(logPath, "a");
+    const serveEntrypoint = resolveServeEntrypoint();
+    const child = (0, node_child_process_1.spawn)(serveEntrypoint.command, [...serveEntrypoint.args, "--port", String(port)], {
+        detached: true,
+        stdio: ["ignore", logFd, logFd]
+    });
+    child.unref();
+    node_fs_1.default.writeFileSync((0, config_1.getPidPath)(), `${child.pid}\n`, "utf8");
+    return {
+        alreadyRunning: false,
+        pid: child.pid ?? 0,
+        port,
+        logPath
+    };
+}
+/**
+ * 停止后台服务，并恢复被接管的 Codex 配置。
+ *
+ * @returns 停止结果；若服务未运行则仅执行配置恢复。
+ * @throws 当进程终止失败时透传底层异常。
+ */
+function stopManagedService() {
+    const pid = getRunningPid();
+    if (!pid) {
+        (0, codex_config_1.deactivateManagedCodexConfig)();
+        return { stoppedPid: null };
+    }
+    process.kill(pid, "SIGTERM");
+    node_fs_1.default.rmSync((0, config_1.getPidPath)(), { force: true });
+    (0, codex_config_1.deactivateManagedCodexConfig)();
+    return { stoppedPid: pid };
+}

package/dist/app/status-service.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshStatusSnapshot = refreshStatusSnapshot;
+exports.getStatusSnapshot = getStatusSnapshot;
+exports.persistAccountEnabledState = persistAccountEnabledState;
+const config_1 = require("../config");
+const scheduler_1 = require("../scheduler");
+const status_1 = require("../status");
+const usage_sync_1 = require("../usage-sync");
+/**
+ * 刷新全部账号额度并返回最新状态快照。
+ *
+ * @returns Promise，成功时返回状态列表、摘要和当前选中账号名。
+ * @throws 当额度刷新失败时透传底层异常。
+ */
+async function refreshStatusSnapshot() {
+    await (0, usage_sync_1.refreshAllAccountUsage)();
+    return getStatusSnapshot();
+}
+/**
+ * 读取当前状态快照但不主动刷新远端额度。
+ *
+ * @returns 当前状态列表、摘要和当前选中账号名。
+ * @throws 当本地配置或状态读取失败时抛出异常。
+ */
+function getStatusSnapshot() {
+    const statuses = (0, status_1.collectAccountStatuses)();
+    const selected = (0, scheduler_1.pickBestAccount)();
+    return {
+        statuses,
+        selectedName: selected?.account.name ?? null,
+        summary: (0, status_1.summarizeAccountStatuses)(statuses)
+    };
+}
+/**
+ * 将交互式界面中的启用状态修改写回配置文件。
+ *
+ * @param accounts 用户在交互界面中调整后的账号数组。
+ * @returns 无返回值。
+ * @throws 当配置写入失败时抛出异常。
+ */
+function persistAccountEnabledState(accounts) {
+    const latest = (0, config_1.loadConfig)();
+    for (const account of accounts) {
+        const index = latest.accounts.findIndex((item) => item.id === account.id);
+        if (index >= 0) {
+            latest.accounts[index].enabled = account.enabled;
+        }
+    }
+    (0, config_1.saveConfig)(latest);
+}

package/dist/cli-helpers.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCliVersion = getCliVersion;
+exports.parsePort = parsePort;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const text_1 = require("./text");
+/**
+ * 读取当前 CLI 的发布版本号，优先与 npm 包元数据保持一致。
+ *
+ * @returns 当前包版本号；当 `package.json` 不可读或字段缺失时返回 `0.0.0`。
+ * @throws 无显式抛出；内部异常会被吞掉并回退到默认版本号。
+ */
+function getCliVersion() {
+    try {
+        const packageJsonPath = node_path_1.default.resolve(__dirname, "../package.json");
+        const packageJsonContent = node_fs_1.default.readFileSync(packageJsonPath, "utf8");
+        const packageJson = JSON.parse(packageJsonContent);
+        if (typeof packageJson.version === "string" && packageJson.version.trim().length > 0) {
+            return packageJson.version;
+        }
+    }
+    catch {
+        // 读取失败时使用保底版本，避免 `-V` 命令直接异常退出。
+    }
+    return "0.0.0";
+}
+/**
+ * 校验并解析端口参数，避免将非法值写入配置或用于启动服务。
+ *
+ * @param rawPort 命令行传入的端口文本。
+ * @returns 合法的监听端口。
+ * @throws 当端口为空、非数字或超出合法范围时抛出异常。
+ */
+function parsePort(rawPort) {
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error((0, text_1.bi)(`非法端口: ${rawPort}`, `Invalid port: ${rawPort}`));
+    }
+    return port;
+}