hunter-mate 0.1.7 → 0.1.11

package/dist/commands/server.d.ts

@@ -1,8 +1,20 @@
 import { Command } from 'commander';
+type StartLock = 'acquired' | 'busy' | 'stolen';
+/** FID-093:导出供单测覆盖竞态/残留锁语义 */
+export declare function acquireStartLock(): StartLock;
+/**
+ * server.log 无界增长曾达 800M+ 挤占用户磁盘(FID-068)。
+ * 后台 daemon 启动前按大小轮转:超过 HM_LOG_MAX_BYTES(默认 50MB)时
+ * server.log → server.log.1 → …保留最近 LOG_KEEP_FILES 份,最旧丢弃。
+ * 纯 fs 实现,Windows 兼容(rename 前先清目标,Windows 不允许覆盖已有文件)。
+ */
+export declare function rotateLogIfNeeded(logFile: string, maxBytes?: number, keep?: number): boolean;
 declare function tryReadPid(): number | null;
 export { tryReadPid };
 /** 定位 server 包根（dist 优先，ts-node 开发模式兜底）；找不到返回 null */
 export declare function findServerRoot(): string | null;
+/** 探活:server /health 是否可访问(短超时,永不 throw)。导出供 version.ts 重启编排复核 */
+export declare function probeServerHealth(url: string, timeoutMs?: number): Promise<boolean>;
 /** 对应 ChromePilot start: 启动本地 NestJS Server（提供 REST + WebSocket + SPA） */
 export declare function runStart(opts: {
     port?: number;

package/dist/commands/server.js

@@ -3,13 +3,69 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'child_process';
-import { loadConfig, saveConfig } from '../config.js';
+import { loadConfig, saveConfig, resolveDataDir } from '../config.js';
 import { killGracefullySync } from '../utils/proc.js';
 import { findBundledAssets } from '../bundled-assets.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PID_FILE = () => path.join(process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.', '.hunter-mate', 'server.pid');
+/** server.pid 等运行时文件随数据目录走(FID-071:dataDir 可配置后 server 状态文件一并迁移) */
+const PID_FILE = () => path.join(resolveDataDir(), 'server.pid');
 const LOG_FILE = () => PID_FILE().replace(/server\.pid$/, 'server.log');
 const WATCHDOG_PID_FILE = () => PID_FILE().replace(/server\.pid$/, 'watchdog.pid');
+/**
+ * FID-093:启动单飞锁。N 个 CLI 进程并发 auto-start(如多个 agent 同时跑
+ * extension 命令)时,旧逻辑各自 spawn watchdog——即便 watchdog 单例加固后
+ * 多实例会被拒,也会留下一地被误写的 pid 文件与误导性的"启动失败"输出。
+ * 持锁者完成 spawn + health 探测期间,其他进程改为等待并复用结果。
+ * 锁残留(持锁进程崩溃)按 mtime 判 stale 抢占。
+ */
+const START_LOCK_FILE = () => path.join(resolveDataDir(), 'server-start.lock');
+const START_LOCK_STALE_MS = 90_000;
+/** FID-093:导出供单测覆盖竞态/残留锁语义 */
+export function acquireStartLock() {
+    const write = () => {
+        try {
+            const fd = fs.openSync(START_LOCK_FILE(), 'wx'); // 原子 O_CREAT|O_EXCL
+            try {
+                fs.writeFileSync(fd, String(process.pid));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (write())
+        return 'acquired';
+    try {
+        if (Date.now() - fs.statSync(START_LOCK_FILE()).mtimeMs > START_LOCK_STALE_MS) {
+            fs.unlinkSync(START_LOCK_FILE());
+            if (write())
+                return 'stolen';
+        }
+    }
+    catch { /* 竞态:他人同时清理/占用,让出 */ }
+    return 'busy';
+}
+function releaseStartLock() {
+    try {
+        fs.unlinkSync(START_LOCK_FILE());
+    }
+    catch { /* ignore */ }
+}
+function watchdogAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function tryReadPidFile(file) {
     try {
         const raw = fs.readFileSync(file, 'utf-8').trim();
@@ -29,6 +85,38 @@ function cleanPidFile(file) {
     }
     catch { /* ignore */ }
 }
+const LOG_MAX_BYTES = () => Number(process.env.HM_LOG_MAX_BYTES || 50 * 1024 * 1024);
+const LOG_KEEP_FILES = 3;
+/**
+ * server.log 无界增长曾达 800M+ 挤占用户磁盘(FID-068)。
+ * 后台 daemon 启动前按大小轮转:超过 HM_LOG_MAX_BYTES(默认 50MB)时
+ * server.log → server.log.1 → …保留最近 LOG_KEEP_FILES 份,最旧丢弃。
+ * 纯 fs 实现,Windows 兼容(rename 前先清目标,Windows 不允许覆盖已有文件)。
+ */
+export function rotateLogIfNeeded(logFile, maxBytes = LOG_MAX_BYTES(), keep = LOG_KEEP_FILES) {
+    try {
+        if (!fs.existsSync(logFile))
+            return false;
+        if (fs.statSync(logFile).size <= maxBytes)
+            return false;
+        for (let i = keep - 1; i >= 1; i--) {
+            const src = `${logFile}.${i}`;
+            const dest = `${logFile}.${i + 1}`;
+            if (!fs.existsSync(src))
+                continue;
+            try {
+                fs.unlinkSync(dest);
+            }
+            catch { /* dest 不存在时忽略 */ }
+            fs.renameSync(src, dest);
+        }
+        fs.renameSync(logFile, `${logFile}.1`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function tryReadPid() {
     const pid = tryReadPidFile(PID_FILE());
     if (pid)
@@ -55,8 +143,8 @@ export function findServerRoot() {
     }
     return null;
 }
-/** 探活:server /health 是否可访问(短超时,永不 throw) */
-async function probeServerHealth(url, timeoutMs = 1500) {
+/** 探活:server /health 是否可访问(短超时,永不 throw)。导出供 version.ts 重启编排复核 */
+export async function probeServerHealth(url, timeoutMs = 1500) {
     try {
         const res = await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeoutMs) });
         return res.ok;
@@ -78,6 +166,42 @@ export async function runStart(opts) {
     const url = `http://${host}:${port}`;
     // 启动过程中的告警说明(会拼进最终返回 msg,保证用户看得见)
     const notes = [];
+    // FID-093 单飞:另一进程正在启动时等待复用,不再并发起 watchdog
+    const lock = acquireStartLock();
+    if (lock === 'busy') {
+        const deadline = Date.now() + 35_000;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 1000));
+            if (await probeServerHealth(url)) {
+                return {
+                    started: true,
+                    pid: null,
+                    url,
+                    msg: 'server 已由另一个 hunter-mate 进程启动完成(启动锁被持有,本次复用其结果)',
+                };
+            }
+        }
+        return {
+            started: false,
+            pid: null,
+            url,
+            msg: '另一个 hunter-mate 进程持有 server 启动锁,且 35s 内 /health 未就绪。请执行 hunter-mate doctor 排查。',
+        };
+    }
+    if (lock === 'stolen') {
+        notes.push('⚠ 检测到残留的 server-start.lock(持有进程疑似崩溃),已按 stale 抢占继续启动');
+    }
+    try {
+        return await runStartLocked(opts, { url, port, host, notes });
+    }
+    finally {
+        releaseStartLock();
+    }
+}
+/** 单飞锁内的实际启动逻辑(锁外逻辑见 runStart) */
+async function runStartLocked(opts, ctx) {
+    const { url, port, host, notes } = ctx;
+    const config = loadConfig();
     const existing = tryReadPid();
     if (existing) {
         // pid 文件存在 ≠ server 存活。pid 可能被系统中其他进程复用
@@ -94,9 +218,42 @@ export async function runStart(opts) {
             }
             return { started: false, pid: existing, url, msg: `server already running (pid=${existing})` };
         }
-        // stale pid:进程号存活但不是我们的 server(或 server 已僵死)。清理后继续启动,
-        // 不 kill —— 那个进程可能属于别的程序(误杀 foreign 进程红线)。
-        notes.push(`⚠ 检测到 stale server.pid (pid=${existing}):该进程存活但 ${url}/health 无响应,` +
+        // FID-093:探活失败≠server 死了。机器抖动(构建/多实例抢 CPU)会让单次
+        // /health 超时,旧逻辑直接当 stale 清文件重拉 → 活 server 被孤儿化,
+        // 新实例 EADDRINUSE 崩溃循环(2026-09-10 23:13 实机复现)。先给 grace 窗口
+        // 复探:进程仍存活且 /health 恢复 → 按已运行处理,绝不双实例。
+        let recovered = false;
+        const graceDeadline = Date.now() + 10_000;
+        while (Date.now() < graceDeadline) {
+            await new Promise((r) => setTimeout(r, 1000));
+            const pidAlive = (() => {
+                try {
+                    process.kill(existing, 0);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            })();
+            if (!pidAlive)
+                break; // 真死了,走正常启动
+            if (await probeServerHealth(url)) {
+                recovered = true;
+                break;
+            }
+        }
+        if (recovered) {
+            return {
+                started: false,
+                pid: existing,
+                url,
+                msg: `server already running (pid=${existing}; /health 曾短暂无响应,grace 窗口内恢复,未拉起新实例)`,
+            };
+        }
+        // stale pid:进程号存活但 grace 后仍无响应(疑似僵死或被其他进程复用)。清理后继续启动,
+        // 不 kill —— 那个进程可能属于别的程序(误杀 foreign 进程红线);
+        // 若它其实占了 34570 端口,新实例会因 EADDRINUSE 显式崩溃退出,不静默。
+        notes.push(`⚠ 检测到 stale server.pid (pid=${existing}):该进程存活但 ${url}/health 在 10s grace 窗口内持续无响应,` +
             `疑似 pid 被其他进程复用,已忽略并继续启动`);
         cleanPidFile(PID_FILE());
     }
@@ -131,6 +288,8 @@ export async function runStart(opts) {
         ...process.env,
         PORT: String(port),
         HOST: host,
+        // FID-071: server 所有数据落点(db/备份/runtime.json/artifacts)由 CLI 的数据目录决定
+        HM_DATA_DIR: resolveDataDir(),
     };
     const nodeArgs = [];
     if (entry.endsWith('.ts')) {
@@ -148,6 +307,8 @@ export async function runStart(opts) {
     const logDir = path.dirname(LOG_FILE());
     if (!fs.existsSync(logDir))
         fs.mkdirSync(logDir, { recursive: true });
+    // 后台 daemon 启动前轮转 server.log(超 50MB 保留 3 份),防止无界增长挤占磁盘
+    rotateLogIfNeeded(LOG_FILE());
     // 后台模式由独立 watchdog 进程托管 server,实现崩溃后自动重启
     const watchdogEntry = path.resolve(__dirname, '../watchdog.js');
     if (!fs.existsSync(watchdogEntry)) {
@@ -163,6 +324,7 @@ export async function runStart(opts) {
         HM_SERVER_ENTRY: entry,
         HM_SERVER_LOG: LOG_FILE(),
         HM_SERVER_NODE_ARGS: nodeArgs.join(','),
+        HM_DATA_DIR: resolveDataDir(),
         PORT: String(port),
         HOST: host,
     };
@@ -173,8 +335,9 @@ export async function runStart(opts) {
         windowsHide: true,
     });
     wd.unref();
-    if (wd.pid)
-        fs.writeFileSync(WATCHDOG_PID_FILE(), String(wd.pid));
+    // FID-093:不再由 CLI 覆写 watchdog.pid——watchdog 进程原子自注册(acquireWatchdogLock),
+    // 并发启动的败者若覆写会把胜者 pid 覆盖成将死进程,runStop 从此找不到活 watchdog。
+    // 就绪探测改为直接探 spawn 出的 watchdog 进程是否存活(比 pid 文件更直接)。
     // 等待 server health 就绪。窗口给足:NestJS 全量路由映射 + TypeORM schema 同步
     // 在慢机/Windows 上实测 10-15s,原 8s 会在 route mapping 阶段误报"未就绪"
     // (server 实际 3 秒后就绪,watchdog 会保活,误报只会误导用户)。
@@ -191,8 +354,8 @@ export async function runStart(opts) {
             }
         }
         catch { /* server 尚未监听,继续轮询 */ }
-        // watchdog 自身退出说明启动参数/入口有问题
-        if (!tryReadPidFile(WATCHDOG_PID_FILE()))
+        // watchdog 自身退出说明启动参数/入口有问题(含单例锁被占,另一 watchdog 在保活)
+        if (!watchdogAlive(wd.pid ?? null))
             break;
     }
     if (!ready) {
@@ -240,14 +403,15 @@ export async function runStop() {
     const wdPid = tryReadPidFile(WATCHDOG_PID_FILE());
     if (wdPid) {
         if (!healthy) {
-            // server 不响应时不杀 watchdog pid(可能已被其他进程复用),只清理 pid 文件
-            cleanPidFile(WATCHDOG_PID_FILE());
-            cleanPidFile(PID_FILE());
+            // server 不响应时不杀 watchdog pid(可能已被其他进程复用)——红线不动;
+            // FID-093:也不清 pid 文件——进程可能还活着,清了等于孤儿化注册表,
+            // 后续 auto-start 会再拉一个实例造成双 server(EADDRINUSE 崩溃循环)。
+            // 文件留在原地,runStart 的 grace 复探会正确处理。
             return {
                 stopped: false,
                 pid: wdPid,
                 msg: `✗ server 无响应(${url}/health 不可达),watchdog pid=${wdPid} 未杀(疑似 stale pid,` +
-                    `可能已被其他进程复用)。已清理 pid 文件;如确有残留进程请手工确认后 kill`,
+                    `可能已被其他进程复用)。pid 文件保留以便复探;如确认是僵死进程请手工 kill`,
             };
         }
         const ok = killGracefullySync(wdPid);
@@ -270,13 +434,13 @@ export async function runStop() {
     if (!pid)
         return { stopped: false, pid: null, msg: 'no server.pid found or process dead' };
     if (!healthy) {
-        // pid 存活但 server 不响应:不 kill(可能复用了别人的 pid),只清 pid 文件
-        cleanPidFile(PID_FILE());
+        // pid 存活但 server 不响应:不 kill(可能复用了别人的 pid)红线不动;
+        // FID-093:同样保留 pid 文件(进程可能还活着,清了会孤儿化注册表)
         return {
             stopped: false,
             pid,
             msg: `✗ pid=${pid} 存活但 server 无响应,未发送 kill 信号(疑似 stale pid,` +
-                `可能属于其他进程)。已清理 pid 文件;如确认是僵死 server 请手工 kill`,
+                `可能属于其他进程)。pid 文件保留以便复探;如确认是僵死 server 请手工 kill`,
         };
     }
     const ok = killGracefullySync(pid);

package/dist/commands/status.d.ts

@@ -1,8 +1,11 @@
 import { Command } from 'commander';
+import { TokenIssuer } from '../keychain.js';
 import { InstalledVersions, SystemVersions } from '@hunter-mate/shared';
 export interface StatusResult {
     version: string;
     loggedIn: boolean;
+    /** token 签发方(hmh#43):saas 签发的 token 会被本地 server 拒绝 */
+    tokenIssuer?: TokenIssuer;
     server: 'running' | 'not running' | 'unknown';
     serverUrl: string;
     extensionCount: number;
@@ -15,6 +18,7 @@ export interface StatusResult {
     }>;
     installed?: InstalledVersions;
     live?: SystemVersions | null;
+    dataDir: string;
 }
 export declare function runStatus(): Promise<StatusResult>;
 export declare const statusCommand: Command;

package/dist/commands/status.js

@@ -1,13 +1,14 @@
 import { Command } from 'commander';
 import axios from 'axios';
 import { i18n } from '../i18n/index.js';
-import { loadConfig } from '../config.js';
-import { getToken } from '../keychain.js';
+import { loadConfig, resolveDataDir } from '../config.js';
+import { getTokenInfo } from '../keychain.js';
 import { readInstalledVersions, fetchLiveVersions } from '../version.js';
 import { getCliLogger } from '../logger.js';
 export async function runStatus() {
     const config = loadConfig();
-    const token = await getToken();
+    const tokenInfo = await getTokenInfo();
+    const token = tokenInfo?.token ?? null;
     let serverStatus = 'unknown';
     let extensions = [];
     let live = null;
@@ -28,15 +29,18 @@ export async function runStatus() {
         serverStatus = 'not running';
         getCliLogger().warn('status:server-not-running', { serverUrl: config.serverUrl });
     }
+    const installed = readInstalledVersions();
     return {
-        version: '0.1.0',
+        version: installed.cli ?? '0.0.0',
         loggedIn: !!token,
+        tokenIssuer: tokenInfo?.issuer,
         server: serverStatus,
         serverUrl: config.serverUrl,
         extensionCount: extensions.length,
         extensions,
-        installed: readInstalledVersions(),
+        installed,
         live,
+        dataDir: resolveDataDir(),
     };
 }
 export const statusCommand = new Command('status')
@@ -49,8 +53,14 @@ export const statusCommand = new Command('status')
         return;
     }
     console.log(`${i18n.t('status.cli')}: ${status.version}`);
-    console.log(`${i18n.t('status.loggedIn')}: ${status.loggedIn ? 'yes' : 'no'}`);
+    const loggedInText = status.loggedIn
+        ? status.tokenIssuer === 'saas'
+            ? 'yes (SaaS 签发 — 本地 server 会拒绝,启动 server 后请重新登录)'
+            : 'yes'
+        : 'no';
+    console.log(`${i18n.t('status.loggedIn')}: ${loggedInText}`);
     console.log(`${i18n.t('status.server')}: ${status.server} (${status.serverUrl})`);
+    console.log(`dataDir: ${status.dataDir}`);
     // 版本一致性: 磁盘(期望) vs 运行中
     if (status.installed) {
         const inst = status.installed;

package/dist/commands/update.js

@@ -2,29 +2,28 @@ import { Command } from 'commander';
 import axios from 'axios';
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveDataDir } from '../config.js';
 import { getToken } from '../keychain.js';
 import { i18n } from '../i18n/index.js';
 import { getCliLogger } from '../logger.js';
 import chalk from 'chalk';
 import { readInstalledVersions, ensureRuntimeConsistency } from '../version.js';
 import { isDevLinked, npmLatestVersion, npmSelfUpdate } from '../updater.js';
-const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const RULES_DIR = path.join(HOME, '.hunter-mate', 'rules');
-const VERSION_FILE = path.join(RULES_DIR, 'version.json');
+const RULES_DIR = () => path.join(resolveDataDir(), 'rules');
+const VERSION_FILE = () => path.join(RULES_DIR(), 'version.json');
 function loadLocalVersion() {
-    if (!fs.existsSync(VERSION_FILE))
+    if (!fs.existsSync(VERSION_FILE()))
         return null;
     try {
-        return JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+        return JSON.parse(fs.readFileSync(VERSION_FILE(), 'utf-8'));
     }
     catch {
         return null;
     }
 }
 function saveLocalVersion(version) {
-    fs.mkdirSync(RULES_DIR, { recursive: true });
-    fs.writeFileSync(VERSION_FILE, JSON.stringify({ version, updatedAt: new Date().toISOString() }, null, 2));
+    fs.mkdirSync(RULES_DIR(), { recursive: true });
+    fs.writeFileSync(VERSION_FILE(), JSON.stringify({ version, updatedAt: new Date().toISOString() }, null, 2));
 }
 export async function runUpdate() {
     const config = loadConfig();

package/dist/config.d.ts

@@ -5,9 +5,28 @@ export interface HunterMateConfig {
     saasUrl: string;
     lang: string;
     watchFolder?: string;
+    /**
+     * 重数据目录(数据库/日志/缓存/扩展/CLI 安装树等),不含 config.json 本身。
+     * 通过 `hunter-mate migrate-data-dir <dir>` 迁移;留空表示默认 ~/.hunter-mate。
+     */
+    dataDir?: string;
+    /**
+     * hunter-mate-harness 仓绝对路径(外部 adapters overlay 真相源)。
+     * `hunter-mate adapter sync` 读取;env HUNTER_MATE_HARNESS_PATH 优先级更高。 @fid FID-081-adapter-overlay-suite
+     */
+    harnessPath?: string;
 }
 export declare const CONFIG_DIR: () => string;
 export declare const CONFIG_FILE: () => string;
+/**
+ * 重数据目录解析(FID-071):
+ * HM_DATA_DIR(env,进程级覆盖,CLI spawn server 时注入) > config.dataDir(用户配置) > 默认 CONFIG_DIR。
+ * config.json 本身始终留在 CONFIG_DIR(KB 级不迁移),保证任何时刻都能定位配置。
+ * 注意:每次调用都实时读取(不缓存),config --data-dir 写入后同一进程内立即生效。
+ */
+export declare function resolveDataDir(): string;
+/** resolveDataDir 的别名,语义化表达"数据目录"(与 CONFIG_DIR 配置目录区分) */
+export declare const DATA_DIR: typeof resolveDataDir;
 /**
  * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
  * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
@@ -43,4 +62,6 @@ export declare function saveConfig(config: Partial<HunterMateConfig>): {
     saasUrl: string;
     lang: string;
     watchFolder?: string;
+    dataDir?: string;
+    harnessPath?: string;
 };

package/dist/config.js

@@ -4,6 +4,29 @@ import { createJsonConfigStore } from '@chromepilot/kit';
 const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
 export const CONFIG_DIR = () => path.join(HOME(), '.hunter-mate');
 export const CONFIG_FILE = () => path.join(CONFIG_DIR(), 'config.json');
+/**
+ * 重数据目录解析(FID-071):
+ * HM_DATA_DIR(env,进程级覆盖,CLI spawn server 时注入) > config.dataDir(用户配置) > 默认 CONFIG_DIR。
+ * config.json 本身始终留在 CONFIG_DIR(KB 级不迁移),保证任何时刻都能定位配置。
+ * 注意:每次调用都实时读取(不缓存),config --data-dir 写入后同一进程内立即生效。
+ */
+export function resolveDataDir() {
+    if (process.env.HM_DATA_DIR && process.env.HM_DATA_DIR.trim()) {
+        return path.resolve(process.env.HM_DATA_DIR);
+    }
+    try {
+        const raw = store.load();
+        if (raw && typeof raw.dataDir === 'string' && raw.dataDir.trim()) {
+            return path.resolve(raw.dataDir);
+        }
+    }
+    catch {
+        /* 配置不可读时回落默认目录 */
+    }
+    return CONFIG_DIR();
+}
+/** resolveDataDir 的别名,语义化表达"数据目录"(与 CONFIG_DIR 配置目录区分) */
+export const DATA_DIR = resolveDataDir;
 /**
  * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
  * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
@@ -70,6 +93,10 @@ export function ensureConfigDir() {
     if (!fs.existsSync(CONFIG_DIR())) {
         fs.mkdirSync(CONFIG_DIR(), { recursive: true });
     }
+    const dataDir = resolveDataDir();
+    if (dataDir !== CONFIG_DIR() && !fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+    }
 }
 export function loadConfig() {
     const raw = store.load();

package/dist/extension-sync.d.ts

@@ -0,0 +1,35 @@
+/** 定位 CLI 内置 extension dist(npm 包 assets 优先,monorepo 并列路径兜底) */
+export declare function resolveBuiltinExtensionDist(): string | null;
+export interface ExtensionArtifactsCompare {
+    /** 上游 = CLI 包内置产物目录;npm 包缺资产时为 null */
+    source: string | null;
+    /** 下游 = ~/.hunter-mate/extension */
+    target: string;
+    sourceChecksum: string | null;
+    targetChecksum: string | null;
+    sourceVersion: string | null;
+    targetVersion: string | null;
+    /** source 存在且 target 存在且 checksum 不同(上游升级了/下游被改过) */
+    stale: boolean;
+}
+export declare function compareExtensionArtifacts(targetDir?: string): ExtensionArtifactsCompare;
+export interface ExtensionSyncResult {
+    synced: boolean;
+    reason: string;
+    copied: number;
+    removed: number;
+    fromVersion?: string;
+    toVersion?: string;
+}
+/**
+ * 同步内置扩展产物到目标目录。
+ * - source 缺失(monorepo 未构建/npm 包缺资产)→ no-op
+ * - target 缺失 → 默认 no-op(首次安装走 hunter-mate install 引导);
+ *   install 命令传 ensureTarget=true 创建
+ * - target 是软链(dev 模式)→ no-op,保护开发链
+ * - checksum 一致 → no-op;不一致 → 剪枝(删目标多余文件)+复制
+ */
+export declare function syncExtensionArtifacts(opts?: {
+    target?: string;
+    ensureTarget?: boolean;
+}): ExtensionSyncResult;