@bolloon/bolloon-agent 0.4.28 → 0.4.29

package/dist/utils/version-info.js

@@ -0,0 +1,510 @@
+/**
+ * version-info.ts — **版本身份的唯一事实来源** (Phase 0/1, 2026-09-19)
+ *
+ * 为什么需要它: 此前"我是什么版本"有 4 处各写一遍 (cli-entry 读 package.json、
+ * bin/bolloon.cjs 硬编码 `0.1.1`、scripts/version_check.py 写死 `0.3.7`、
+ * postinstall 写死 `0.1.12`), 4 处就会给出 4 个答案。这里把
+ *   「包版本 / 构建时间 / git commit / 安装方式 / 安装目录 / 入口 / 上流 / 更新通道」
+ * 收敛成一个 `VersionInfo`, 所有出口 (`--version` / `--version --verbose` /
+ * `--version --json` / doctor / 更新检查 / 安装脚本) 都只读它。
+ *
+ * 边界 (冻结): 本模块**只读** —— 不写配置、不装包、不决定是否更新。
+ * 写入与决策分别在 `update-state.ts` (状态落盘) 与 `update-manager.ts` (计划/执行)。
+ *
+ * 安装方式语义 (与脚本侧同一份枚举):
+ *   npm-global       npm 全局安装 (`npm i -g`), 可自动更新
+ *   npm-local        装在某个项目的 node_modules 里 (非全局), 交给该项目的包管理
+ *   source-git       git 检出 + 自建 (dist 已产出), 更新走 git pull + build
+ *   release-binary   解压的发行包 (带 RELEASE.json 标记)
+ *   development      开发目录 (携带 .git 的源码树 / 被 npm link 进全局 / tsx 直跑)
+ *   unknown          认不出来 → 一律不自动更新
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { resolveBolloonHome } from '../setup/setup-store.js';
+import { renderRuntimeLines } from './runtime-bootstrap.js';
+export const PKG_NAME = '@bolloon/bolloon-agent';
+export const CONSTRAINT_PKG_NAME = '@bolloon/constraint-runtime';
+/** npm registry (可用 BOLLOON_NPM_REGISTRY 指向镜像/内网; 末尾斜杠统一去掉) */
+export const NPM_REGISTRY_BASE = (process.env.BOLLOON_NPM_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
+export const UPSTREAM_REPO = 'https://github.com/logos-42/bolloon';
+export const INSTALL_METHODS = [
+    'npm-global', 'npm-local', 'source-git', 'release-binary', 'development', 'unknown',
+];
+export const UPDATE_SOURCES = ['npm', 'github-release', 'git', 'unknown'];
+export const UPDATE_CHANNELS = ['stable', 'beta', 'dev'];
+/** 发行通道: 环境变量 > 配置 > stable。npm 只有 `latest` (stable) 一个 dist-tag, beta/dev 暂走同一标签。 */
+export function resolveUpdateChannel(explicit) {
+    const raw = (explicit || process.env.BOLLOON_UPDATE_CHANNEL || '').trim().toLowerCase();
+    if (raw === 'stable' || raw === 'beta' || raw === 'dev')
+        return raw;
+    return 'stable';
+}
+/** dist-tag 映射: stable → latest; beta/dev 暂与 stable 同源 (明说, 不假装有独立通道)。 */
+export function distTagForChannel(channel) {
+    return channel === 'beta' ? 'beta' : 'latest';
+}
+// ── 包根定位 ────────────────────────────────────────────────────────────────
+/**
+ * 从当前模块 URL 定位**运行中的**包根。
+ * Node 默认解析软链 (preserveSymlinks=false) → npm link 场景下这里拿到的是**真实源码目录**,
+ * 这正是"开发目录不能被误判成全局安装"的基础。
+ */
+export function packageRootFrom(moduleUrl) {
+    const file = fileURLToPath(moduleUrl);
+    return path.resolve(path.dirname(file), '..', '..');
+}
+export function readPackageAt(root) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+        return { name: raw.name, version: raw.version, raw };
+    }
+    catch {
+        return null;
+    }
+}
+// ── 运行入口 ────────────────────────────────────────────────────────────────
+export function buildTimeOf(file) {
+    if (!file)
+        return null;
+    try {
+        return fs.statSync(file).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+function whichBin(name) {
+    const pathEnv = process.env.PATH || '';
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const p = path.join(dir, name);
+        try {
+            if (fs.existsSync(p))
+                return p;
+        }
+        catch {
+            // 忽略
+        }
+    }
+    return null;
+}
+/** npm 全局根 (`npm root -g`), 拿不到返回 null (npm 不在 PATH / 超时)。 */
+export function npmGlobalRoot() {
+    try {
+        const out = execFileSync('npm', ['root', '-g'], { encoding: 'utf-8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
+        const v = out.trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** npm 全局前缀 (`npm prefix -g`), 用于算 bin 目录。 */
+export function npmGlobalPrefix() {
+    try {
+        const out = execFileSync('npm', ['prefix', '-g'], { encoding: 'utf-8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
+        const v = out.trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+function npmVersion() {
+    try {
+        return execFileSync('npm', ['--version'], { encoding: 'utf-8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function pythonVersion() {
+    for (const bin of ['python3', 'python']) {
+        try {
+            const out = execFileSync(bin, ['-V'], { encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            if (out)
+                return out;
+        }
+        catch {
+            // 继续
+        }
+    }
+    return null;
+}
+export function isNpmGlobalPackageDir(pkgRoot) {
+    const norm = pkgRoot.replace(/\\/g, '/');
+    return /\/lib\/node_modules\/@bolloon\/bolloon-agent$/.test(norm)
+        || /\/node_modules\/@bolloon\/bolloon-agent$/.test(norm) && norm.includes('/npm-global/');
+}
+function looksLikeGitCheckout(dir) {
+    try {
+        return fs.existsSync(path.join(dir, '.git'));
+    }
+    catch {
+        return false;
+    }
+}
+function isWritable(p) {
+    try {
+        fs.accessSync(p, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 两个路径是否指向同一处 (软链也算同一处)。 */
+function samePath(a, b) {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return path.resolve(a) === path.resolve(b);
+    }
+}
+/**
+ * 识别当前运行的是哪种安装。
+ *
+ * 判定顺序 (先具体后兜底):
+ *   1. 全局 npm 包目录里是**软链**, 且链到 git 检出 → `development` (npm link: 全局入口 ≠ 发行安装)
+ *   2. 包根在 `<npm root -g>` 里 → `npm-global`
+ *   3. 包根在任意 `node_modules/<PKG_NAME>` (非全局) → `npm-local`
+ *   4. 包根是 git 检出 → `source-git`
+ *   5. 包根有 RELEASE.json 标记 → `release-binary`
+ *   6. 其余 → `unknown`
+ */
+export function detectInstallation(opts = {}) {
+    const packageRoot = path.resolve(opts.packageRoot || currentPackageRoot());
+    const globalRoot = npmGlobalRoot();
+    const globalPrefix = npmGlobalPrefix();
+    const expectedGlobalDir = globalRoot ? path.join(globalRoot, '@bolloon', 'bolloon-agent') : null;
+    const binCandidates = [
+        globalPrefix ? path.join(globalPrefix, 'bin', 'bolloon') : null,
+        whichBin('bolloon'),
+    ].filter((p) => !!p);
+    const binPath = binCandidates.find((p) => { try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    } }) || null;
+    let linked = false;
+    let linkTarget = null;
+    let linkedReal = null;
+    if (expectedGlobalDir) {
+        try {
+            if (fs.lstatSync(expectedGlobalDir).isSymbolicLink()) {
+                linked = true;
+                linkTarget = path.resolve(path.dirname(expectedGlobalDir), fs.readlinkSync(expectedGlobalDir));
+                linkedReal = fs.realpathSync(expectedGlobalDir);
+            }
+        }
+        catch {
+            // 不存在 / 无权限
+        }
+    }
+    const gitCheckout = looksLikeGitCheckout(packageRoot);
+    const inGlobal = !!expectedGlobalDir && fs.existsSync(path.join(expectedGlobalDir, 'package.json'))
+        && samePath(expectedGlobalDir, packageRoot);
+    const posixPath = packageRoot.replace(/\\/g, '/');
+    /**
+     * npm 的**全局布局**就是 `<prefix>/lib/node_modules/<pkg>`
+     * (homebrew / nvm / 自定义 prefix 都一样)。`npm root -g` 拿不到或与安装时的 prefix
+     * 不一致时 (真装一遍的验收里就遇到过: 安装用 prefix=X, 查询时 npm 从别的 HOME 解析出 Y),
+     * 只看 `npm root -g` 会把它误判成 `npm-local`。这里按布局兜底。
+     * 对照: 项目内局部依赖是 `<proj>/node_modules/<pkg>` (没有 `lib/`), 仍是 npm-local。
+     */
+    const globalLayout = /\/lib\/node_modules\/@bolloon\/bolloon-agent$/.test(posixPath);
+    const inAnyNodeModules = /[\\/]node_modules[\\/]@bolloon[\\/]bolloon-agent$/.test(posixPath);
+    const hasReleaseMarker = fs.existsSync(path.join(packageRoot, 'RELEASE.json'));
+    let method;
+    let reason;
+    if (linked && linkedReal && samePath(linkedReal, packageRoot) && gitCheckout) {
+        // npm link: 全局入口指向开发源码 → 这不是发行安装
+        method = 'development';
+        reason = `npm 全局目录是软链, 指向开发源码 (${linkTarget || packageRoot}) — 不是发行安装`;
+    }
+    else if (inGlobal && !gitCheckout) {
+        method = 'npm-global';
+        reason = `包根位于 npm 全局目录 ${expectedGlobalDir}`;
+    }
+    else if (inGlobal && gitCheckout) {
+        method = 'source-git';
+        reason = '包根位于 npm 全局目录, 但本身就是 git 检出 (就地发布)';
+    }
+    else if (globalLayout && !gitCheckout) {
+        method = 'npm-global';
+        reason = `包根符合 npm 全局布局 <prefix>/lib/node_modules/${PKG_NAME} (prefix=${posixPath.replace('/lib/node_modules/' + PKG_NAME, '')})`;
+    }
+    else if (inAnyNodeModules) {
+        method = 'npm-local';
+        reason = '包根位于某个项目的 node_modules (非全局)';
+    }
+    else if (gitCheckout) {
+        method = 'source-git';
+        reason = '包根是 git 检出';
+    }
+    else if (hasReleaseMarker) {
+        method = 'release-binary';
+        reason = '包根带 RELEASE.json 标记 (解压的发行包)';
+    }
+    else {
+        method = 'unknown';
+        reason = `无法从 ${packageRoot} 判定安装方式`;
+    }
+    const updateSource = method === 'npm-global' || method === 'npm-local' ? 'npm'
+        : method === 'source-git' || method === 'development' ? 'git'
+            : 'unknown';
+    // 自动更新的硬条件: 走 npm 通道 + npm 全局 + 目标目录可写
+    const autoUpdatable = (method === 'npm-global') && isWritable(packageRoot);
+    return {
+        method,
+        packageRoot,
+        installDir: packageRoot,
+        binPath,
+        entryPath: resolveEntryPath(packageRoot),
+        writable: isWritable(packageRoot),
+        linked,
+        linkTarget,
+        updateSource,
+        autoUpdatable,
+        reason,
+    };
+}
+/** 被 node 真正加载的入口 (`dist/cli-entry.js`), 找不到时回退到模块自身。 */
+function resolveEntryPath(packageRoot) {
+    const fromArgv = process.argv[1] ? path.resolve(process.argv[1]) : null;
+    if (fromArgv && fromArgv.startsWith(packageRoot))
+        return fromArgv;
+    const dist = path.join(packageRoot, 'dist', 'cli-entry.js');
+    if (fs.existsSync(dist))
+        return dist;
+    const idx = path.join(packageRoot, 'dist', 'index.js');
+    if (fs.existsSync(idx))
+        return idx;
+    return packageRoot; // 找不到入口就如实报包根, 不编路径
+}
+/**
+ * 当前包根目录 —— ESM(Node) 与 CJS(Electron) 双上下文都能用。
+ *
+ * **刻意不用 import.meta**: `tsconfig.electron.json` 是 `module: CommonJS`,
+ * 只要本文件被 electron 主进程链路 (electron.ts -> auto-update -> update-manager -> version-info)
+ * 引到, 用了 import.meta 就 TS1343 编译失败 —— 这个坑平时看不见, 只有
+ * `npm publish` (prepublishOnly -> build:all -> build:electron) 才会走 electron 编译。
+ */
+export function currentPackageRoot() {
+    const climb = (start) => {
+        let dir = path.resolve(start);
+        for (let i = 0; i < 8; i++) {
+            const pkg = path.join(dir, 'package.json');
+            if (fs.existsSync(pkg)) {
+                try {
+                    const j = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+                    if (j && j.name === PKG_NAME)
+                        return dir;
+                }
+                catch { /* 读不了就当没有, 继续往上 */ }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    };
+    // (1) 进程入口 (CLI = dist/cli-entry.js, 脚本, electron 主进程)
+    const fromArgv = process.argv[1] ? climb(path.dirname(process.argv[1])) : null;
+    if (fromArgv)
+        return fromArgv;
+    // (2) CJS 上下文能直接拿 __dirname —— 包在 new Function 里, 避免 ESM 编译期报"未定义"
+    try {
+        const dir = new Function('return typeof __dirname === "string" ? __dirname : null')();
+        const hit = dir ? climb(dir) : null;
+        if (hit)
+            return hit;
+    }
+    catch { /* ESM 下这里拿不到 __dirname, 正常 */ }
+    // (3) 调用栈里的本文件绝对路径 (ESM 也能拿到)
+    try {
+        const stack = new Error().stack || '';
+        const m = stack.match(/(?:file:\/\/)?(\/[^\s()]*version-info\.(?:js|mjs|cjs|ts)):\d+:\d+/);
+        if (m) {
+            const hit = climb(path.dirname(m[1]));
+            if (hit)
+                return hit;
+        }
+    }
+    catch { /* 拿不到就退到 cwd */ }
+    // (4) 仓库里直接跑 (开发态)
+    return climb(process.cwd()) || process.cwd();
+}
+export function gitFactsAt(dir) {
+    if (!looksLikeGitCheckout(dir))
+        return { commit: null, dirty: null, branch: null };
+    try {
+        const commit = execFileSync('git', ['-C', dir, 'rev-parse', '--short=7', 'HEAD'], { encoding: 'utf-8', timeout: 6000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+        let dirty = null;
+        try {
+            const st = execFileSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf-8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
+            dirty = st.trim().length > 0;
+        }
+        catch {
+            dirty = null;
+        }
+        let branch = null;
+        try {
+            branch = execFileSync('git', ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf-8', timeout: 6000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+        }
+        catch {
+            branch = null;
+        }
+        return { commit, dirty, branch };
+    }
+    catch {
+        return { commit: null, dirty: null, branch: null };
+    }
+}
+export function collectVersionInfo(opts = {}) {
+    const packageRoot = path.resolve(opts.packageRoot || currentPackageRoot());
+    const pkg = readPackageAt(packageRoot);
+    const install = detectInstallation({ packageRoot, home: opts.home });
+    const home = opts.home || resolveBolloonHome();
+    const git = opts.light ? { commit: null, dirty: null, branch: null } : gitFactsAt(packageRoot);
+    const channel = resolveUpdateChannel(opts.channel);
+    const gitHeadFromPkg = pkg?.raw?.gitHead;
+    let gitCommit = git.commit;
+    let gitCommitSource = 'git';
+    if (!gitCommit && gitHeadFromPkg) {
+        gitCommit = String(gitHeadFromPkg).slice(0, 7);
+        gitCommitSource = 'package.json';
+    }
+    if (!gitCommit)
+        gitCommitSource = 'unknown';
+    return {
+        schema: 'bolloon-version/1',
+        packageName: pkg?.name || PKG_NAME,
+        packageVersion: pkg?.version || 'unknown',
+        buildTime: buildTimeOf(install.entryPath),
+        buildTimeSource: 'entry-mtime',
+        gitCommit,
+        gitBranch: git.branch,
+        gitDirty: git.dirty,
+        gitCommitSource,
+        nodeVersion: process.version.replace(/^v/, ''),
+        npmVersion: opts.light ? null : npmVersion(),
+        pythonVersion: opts.light ? null : pythonVersion(),
+        platform: os.platform(),
+        arch: os.arch(),
+        installMethod: install.method,
+        installDir: install.installDir,
+        entryPath: install.entryPath,
+        binPath: install.binPath,
+        configDir: home,
+        channel,
+        upstream: UPSTREAM_REPO,
+        registry: `${NPM_REGISTRY_BASE}/${PKG_NAME}`,
+        updateSource: install.updateSource,
+        autoUpdatable: install.autoUpdatable,
+        installReason: install.reason,
+        update: opts.update ?? null,
+        runtime: opts.runtime ?? null,
+        runtimeConfigBacked: opts.runtimeConfigBacked ?? false,
+    };
+}
+// ── 渲染 (三种输出读同一份 VersionInfo) ─────────────────────────────────────
+function fmtTime(iso) {
+    if (!iso)
+        return '未记录';
+    try {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime()))
+            return '未记录';
+        const pad = (n) => String(n).padStart(2, '0');
+        return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+    }
+    catch {
+        return '未记录';
+    }
+}
+/** 一句话更新结论 (普通版 + verbose 共用, 保证两处不会说两套话) */
+export function describeUpdateLine(info) {
+    const u = info.update;
+    if (!u || !u.lastCheckStatus || !u.lastCheckAt)
+        return '更新检查: 尚未检查 (运行 bolloon update)';
+    switch (u.lastCheckStatus) {
+        case 'up_to_date': return '更新检查: 已是最新';
+        case 'update_available': return `更新检查: 有新版可用 (${u.latestVersion || '未知'})`;
+        case 'check_skipped': return '更新检查: 已跳过 (使用缓存)';
+        case 'offline': return '更新检查: 离线 — 无法访问 npm registry (不等于最新)';
+        case 'registry_unavailable': return `更新检查: registry 不可用${u.lastCheckReason ? ` (${u.lastCheckReason})` : ''} (不等于最新)`;
+        case 'local_version_unknown': return '更新检查: 读不到本地版本 — 不判断是否有更新';
+        case 'unsupported_installation': return '更新检查: 当前安装方式不支持自动更新';
+        default: return `更新检查: ${u.lastCheckStatus}`;
+    }
+}
+export function renderVersionText(info, opts = {}) {
+    if (opts.verbose) {
+        const lines = [
+            `Bolloon Agent v${info.packageVersion} (verbose)`,
+            `包名:        ${info.packageName}`,
+            `构建时间:    ${fmtTime(info.buildTime)} (${info.buildTimeSource === 'entry-mtime' ? '入口文件 mtime' : info.buildTimeSource})`,
+            `Git commit:  ${info.gitCommit || 'unknown'}${info.gitDirty ? ' (dirty)' : info.gitDirty === false ? ' (clean)' : ''}  [来源: ${info.gitCommitSource}]`,
+            `Git 分支:    ${info.gitBranch || 'unknown'}`,
+            `Node.js:     ${info.nodeVersion}`,
+            `npm:         ${info.npmVersion || 'unknown'}`,
+            `Python:      ${info.pythonVersion || 'unknown'}`,
+            `平台:        ${info.platform} ${info.arch}`,
+            `安装方式:    ${info.installMethod}${info.installReason ? `  (${info.installReason})` : ''}`,
+            `安装目录:    ${info.installDir}`,
+            `运行入口:    ${info.entryPath}`,
+            `bin shim:    ${info.binPath || 'unknown'}`,
+            `配置目录:    ${info.configDir}`,
+            `更新通道:    ${info.channel}`,
+            `更新来源:    ${info.updateSource}${info.autoUpdatable ? '' : ' (不支持自动更新)'}`,
+            `上游地址:    ${info.upstream}`,
+            `registry:    ${info.registry}`,
+            describeUpdateLine(info),
+            `上次检查:    ${fmtTime(info.update?.lastCheckAt)}`,
+        ];
+        if (info.update?.lastUpdate) {
+            const lu = info.update.lastUpdate;
+            lines.push(`最近更新:    ${fmtTime(lu.at)} ${lu.from} → ${lu.to} [${lu.status}]${lu.reason ? ` ${lu.reason}` : ''}`);
+        }
+        else {
+            lines.push('最近更新:    无记录');
+        }
+        if (info.update?.needsRestart)
+            lines.push('需要重启:    是 (新版已就位, 重启后生效)');
+        if (info.runtime) {
+            lines.push('');
+            lines.push(...renderRuntimeLines(info.runtime, { verbose: true, configBacked: info.runtimeConfigBacked }));
+        }
+        return lines.join('\n');
+    }
+    // 普通版: 给人看, 简洁但完整 (含安装位置/方式/通道/上游/是否最新)
+    const lines = [
+        `Bolloon Agent v${info.packageVersion}`,
+        `安装方式: ${info.installMethod}`,
+        `安装目录: ${info.installDir}`,
+        `运行入口: ${info.binPath || info.entryPath}`,
+        `更新通道: ${info.channel}`,
+        `Node.js: ${info.nodeVersion}`,
+        `平台: ${info.platform} ${info.arch}`,
+        `上游提交: ${info.gitCommit || 'unknown'}`,
+        describeUpdateLine(info),
+        `上次检查: ${fmtTime(info.update?.lastCheckAt)}`,
+    ];
+    if (info.runtime) {
+        lines.push('');
+        lines.push(...renderRuntimeLines(info.runtime, { verbose: false, configBacked: info.runtimeConfigBacked }));
+    }
+    return lines.join('\n');
+}
+export function renderVersionJson(info) {
+    return JSON.stringify(info, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.4.28",
+  "version": "0.4.29",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli-entry.js",