@jesonliu/lark-claudecode-bridge 1.0.4 → 1.0.6

package/dist/lark-cli-manager.d.ts

@@ -74,15 +74,22 @@ export interface LarkCliSkillDetect {
     /** 命中的 skill 目录名（首个） */
     name?: string;
 }
+/** skill 目录扫描的注入点（测试用）；缺省读真实文件系统 */
+export interface SkillDirFs {
+    exists(p: string): boolean;
+    readdir(d: string): string[];
+}
 /**
- * 检测飞书官方 SKILL 是否已装（默认 ~/.claude/skills，与安装动作同源）。
+ * 列出已装的飞书官方 SKILL 目录名（默认 ~/.claude/skills，与安装动作同源）。
  * 判据：目录名命中 feishu/lark **且** 内含 SKILL.md（防同名散目录误报）。
  * managed 会话的可见性由 bridgeUserSkills() 启动桥接保证，这里不查托管目录。
+ *
+ * 以扫盘而非解析 `npx skills add` 的输出来确定「装了什么」：那份输出是带 ANSI 的
+ * 进度表，既难读也不可靠；目录才是既成事实。
  */
-export declare function detectLarkCliSkill(skillsDir?: string, fs?: {
-    exists(p: string): boolean;
-    readdir(d: string): string[];
-}): Promise<LarkCliSkillDetect>;
+export declare function listLarkCliSkills(skillsDir?: string, fs?: SkillDirFs): Promise<string[]>;
+/** 检测飞书官方 SKILL 是否已装：取扫盘结果的首个（保持既有返回结构不变） */
+export declare function detectLarkCliSkill(skillsDir?: string, fs?: SkillDirFs): Promise<LarkCliSkillDetect>;
 export interface InstallSkillOpts {
     /** 覆盖 npx 执行（测试注入）；缺省真实 runNpx */
     runNpxFn?: (args: string[], timeoutMs: number) => Promise<string>;
@@ -103,17 +110,22 @@ export declare function installLarkCliSkill(timeoutMs?: number, opts?: InstallSk
  * detail 的两个来源（error.subtype / reason）实测均含 not_configured 字样。
  */
 export declare function needsLarkCliConfig(auth: LarkCliAuthStatus): boolean;
+export interface StartupCheckDeps {
+    detect(): Promise<LarkCliDetect>;
+    detectSkill(): Promise<LarkCliSkillDetect>;
+    log(msg: string): void;
+}
 /**
- * 核心编排（依赖注入可测）：已装 → 直接返回；未装 → install → 复检；
- * install 抛错 → warn 后返回未装态，**绝不抛出**（桥接器启动不能被外部工具安装失败拖垮）
+ * 启动时的飞书 CLI 检查（依赖注入可测）——**只探测，绝不安装**。
+ *
+ * 安装统一下沉到 Web 配置页（用户决策）：启动时静默装会让用户对安装过程无感，
+ * 也就跳过了官方流程的后三步（SKILL / config init / auth login）——等打开配置页时
+ * CLI 已就绪却从未配置过飞书应用，直接卡在「未授权」而无从下手；用户此时若自己点
+ * 「安装」，还会和后台那次抢 npm 文件锁。这里只把现状与去处讲清楚。
+ *
+ * **绝不抛出**：桥接器启动不能被外部工具的探测异常拖垮。
  */
-export declare function ensureLarkCliFlow(deps: {
-    detect(): Promise<LarkCliDetect>;
-    install(log?: (msg: string) => void): Promise<string>;
-    log?: (msg: string) => void;
-}): Promise<LarkCliDetect>;
-/** 生产入口：console 反馈（[lark-cli] 前缀），后台异步调用（lcb start 里 void + catch） */
-export declare function ensureLarkCli(): Promise<LarkCliDetect>;
+export declare function checkLarkCliAtStartup(deps?: Partial<StartupCheckDeps>): Promise<LarkCliDetect>;
 export type LarkCliAuthState = 'authorized' | 'unauthorized' | 'unknown';
 export interface LarkCliAuthStatus {
     state: LarkCliAuthState;
@@ -269,7 +281,7 @@ export declare function cmdEscapeArg(s: string): string;
  * cwd 设为专用 tmp 子目录：lark-cli 的写路径允许根是 cwd / /tmp / ~/files（实测 cwd 生效），
  * 故 -o 用相对名即可落进允许根。
  */
-export declare function defaultMakeQr(url: string, runner?: AuthRunner, log?: (m: string) => void, tmpDir?: string): Promise<string | undefined>;
+export declare function defaultMakeQr(url: string, runner?: AuthRunner, log?: (m: string) => void, tmpDir?: string, fileName?: string): Promise<string | undefined>;
 export interface LarkCliDeviceDeps {
     runner: AuthRunner;
     finishRunner: AuthRunner;
@@ -292,6 +304,107 @@ export declare function startLarkCliDeviceAuth(opts?: {
     regenerate?: boolean;
     deps?: Partial<LarkCliDeviceDeps>;
 }): Promise<LarkCliDeviceSessionInfo>;
+export type LarkCliConfigState = 'pending' | 'done' | 'failed' | 'expired' | 'none';
+export interface LarkCliConfigSessionInfo {
+    ok: boolean;
+    state?: LarkCliConfigState;
+    verificationUrl?: string;
+    userCode?: string;
+    qrDataUrl?: string;
+    reused?: boolean;
+    error?: string;
+    /** 未安装——让前端把用户导到「安装」入口而不是干瞪眼 */
+    hint?: 'install';
+}
+/**
+ * 子进程最小结构（便于测试注入假实现）。
+ * 真实实现由 defaultConfigSpawn 把 node 的 ChildProcess 收窄成它。
+ */
+export interface LarkCliConfigChild {
+    stdout: {
+        on(ev: 'data', cb: (chunk: Buffer) => void): unknown;
+    } | null;
+    stderr: {
+        on(ev: 'data', cb: (chunk: Buffer) => void): unknown;
+    } | null;
+    on(ev: 'exit', cb: (code: number | null) => void): unknown;
+    on(ev: 'error', cb: (err: Error) => void): unknown;
+}
+export interface LarkCliConfigDeps {
+    spawn: (file: string, args: string[], opts: {
+        windowsHide: boolean;
+        env: NodeJS.ProcessEnv;
+    }) => LarkCliConfigChild;
+    detect(): Promise<LarkCliDetect>;
+    checkAuth(): Promise<LarkCliAuthStatus>;
+    makeQr(url: string): Promise<string | undefined>;
+    now(): number;
+    log(msg: string): void;
+}
+/**
+ * 纯函数（可测）：从 `config init --new` 的输出里提取授权链接。
+ *
+ * **真实输出形态尚未用真机钉死**（本机已配置，直接跑不带 --name 的 config init 会覆盖它；
+ * 抓取步骤见 docs/e2e-checklist.md 的「页面内配置应用」一节），因此解析刻意宽容，
+ * 三层依次退让，保证形态猜错时也只是退化成更弱的匹配、而不是彻底解析不出来：
+ *   ① JSON（兼容 {ok,data} 信封与 verification_uri / console_url 等字段别名）
+ *   ② 裸 URL（从散文里抓首个 http(s) 链接）
+ *   ③ 折行 URL（输出方按显示宽度插了换行时的尽力补救）
+ *
+ * **URL 一律视为 opaque string**：不编码、不解码、不重拼 query——lark-cli 内置 skill 明文要求。
+ */
+export declare function extractConfigUrl(text: string): string | undefined;
+export interface LarkCliConfigOutcome {
+    phase: 'done' | 'failed' | 'expired';
+    error?: string;
+}
+/**
+ * 纯函数（可测）：配置子进程结束后判定结果。
+ *
+ * **正向判据优先于退出码**：以「应用是否真的配置上了」为准（`!needsLarkCliConfig(authAfter)`），
+ * 而不是退出码——退出码 0 却什么都没配上，比直接报错更糟（用户以为配好了，下一步授权必然失败）。
+ *
+ * 判据还必须是**明确的**探测结果：`unknown`（探测失败）不算已配置，否则一次探测抖动
+ * 就会把没配上的机器报成配好了——这与 decideDeviceFinishOutcome 的「反向兜底绝不能有」同源。
+ */
+export declare function decideConfigOutcome(a: {
+    exitCode: number | null;
+    output: string;
+    spawnError?: string;
+    authAfter?: LarkCliAuthStatus;
+}): LarkCliConfigOutcome;
+/** 内存态查询（零副作用、亚毫秒）——撑住前端 2s 轮询 */
+export declare function getLarkCliConfigStatus(now?: number): LarkCliConfigSessionInfo;
+/**
+ * 放弃当前配置会话（改用终端 / 新一轮发起前）。
+ * **不 kill 子进程**——与 abandonLarkCliDeviceSession 同源：Windows 上
+ * cmd → node → lark-cli.exe 的进程树 kill 会留孤儿，靠 gen 失配丢弃结果即可，
+ * 孤儿最多空转到 registration 过期后自行退出。
+ */
+export declare function abandonLarkCliConfigSession(): void;
+/** 重置配置会话状态（测试用） */
+export declare function resetLarkCliConfigState(): void;
+/** 生产 spawn：stdin 接 /dev/null——官方要求「后台运行」，此路无人在终端应答交互输入 */
+export declare const defaultConfigSpawn: (file: string, args: string[], opts: {
+    windowsHide: boolean;
+    env: NodeJS.ProcessEnv;
+}) => LarkCliConfigChild;
+/**
+ * 发起「配置应用」流程（页面二维码的主入口）。
+ *
+ * 四道闸与 startLarkCliDeviceAuth 同构：
+ *   ① 幂等复用：pending 会话直接返回（挡住刷新页面 / 关弹窗再开）
+ *   ② in-flight 合并：并发调用 await 同一个 promise（挡住双击）
+ *   ③ regenerate：用户显式要求时才新建
+ *   ④ gen 代号：新建时 +1，在飞的老子进程靠它丢弃过期结果
+ *
+ * 与设备流的一处**有意不同**：没有「剩余不足 X 秒就换新」——CLI 不吐有效期，
+ * 我们也就无从编造倒计时；会话的终结一律由子进程退出（或 CONFIG_URL_WAIT_MS 兜底）驱动。
+ */
+export declare function startLarkCliConfigFlow(opts?: {
+    regenerate?: boolean;
+    deps?: Partial<LarkCliConfigDeps>;
+}): Promise<LarkCliConfigSessionInfo>;
 export type LarkCliOp = 'install' | 'update' | 'auth' | 'config' | 'skill';
 export interface LarkCliActionResult {
     ok: boolean;
@@ -301,6 +414,8 @@ export interface LarkCliActionResult {
     terminal?: string;
     scriptPath?: string;
     output?: string;
+    /** skill op 专用：装完后扫盘得到的 SKILL 名单（前端列清单用，比 npx 原始输出可靠） */
+    skills?: string[];
     /** 为何没用终端（降级说明，前端展示用） */
     reason?: string;
     error?: string;
@@ -312,6 +427,8 @@ export interface LarkCliActionDeps {
     install(): Promise<string>;
     /** SKILL 静默安装（op:'skill'）；缺省真实 installLarkCliSkill */
     installSkill(): Promise<string>;
+    /** SKILL 装完后的落盘扫描（op:'skill' 回传名单用）；缺省真实 listLarkCliSkills */
+    listSkills(): Promise<string[]>;
     /** 授权/配置态探测：config op 用它拒绝重复向导；install op 用它决定脚本是否插 config init 段 */
     checkAuth(): Promise<LarkCliAuthStatus>;
     launch(task: TerminalTask, opts?: {