ccli-core

cli-core 是工具链基础库，提供命令上下文、日志系统、Shell 工具函数，以及 adc / ccli 工具链命令。

接入方式

在命令文件中按需导入：

import {
  getJsMeta,       // 获取当前命令的上下文路径（projectRoot / cmdName / assetsDir 等）
  initCmdLogger,   // 接入日志系统
  exec,            // 执行 shell 命令（async，失败自动写 error log）
  execDetailed,    // 同 exec 但返回 { stdout, stderr, exitCode }，不抛异常
  sleep,           // sleep(ms: number): Promise<void>
  escapeChars,     // shell 特殊字符转义
  promiseForEach,  // 串行异步遍历
} from "ccli-core";

日志系统

所有通过 adc 创建的命令模板已自动包含日志接入。手动为已有命令接入，在文件顶部加一行：

import { initCmdLogger } from "ccli-core";
initCmdLogger(import.meta);

每次运行时会自动：

• 将 stdout/stderr 完整保存到 ~/ccli/logs/YYYYMMDD/HHmmss-cmdname.log
• 在 ~/ccli/logs/index.jsonl 中追加一条元数据记录（命令名、参数、结果、耗时、日志路径）

查看运行记录：

ccli log              # 展示最近 30 条运行记录（表格）
ccli log -n 50        # 最近 50 条
ccli log -c yt-srt    # 只看 yt-srt 命令的记录
ccli log --failed     # 只看失败记录

API 说明

getJsMeta(importMeta)

获取当前命令的运行时上下文：

const { projectRoot, cmdName, assetsDir, jsDir, srcDir, cwd } = getJsMeta(import.meta);
// projectRoot  工作区根目录（含 package.json）
// cmdName      当前命令名（取自 @cmdName 注解）
// assetsDir    <projectRoot>/assets
// jsDir        当前 JS 文件所在目录（dist/commands/...）
// srcDir       对应的 TS 源文件目录（src/commands/...）
// cwd          process.cwd()

exec(cmd, options?)

异步执行 shell 命令，失败时自动写入 error log 并抛出异常：

await exec("git pull");

execDetailed(cmd, options?)

同 exec，但不抛异常，返回结构化结果：

const { stdout, stderr, exitCode } = await execDetailed("git status");

sleep(ms)

await sleep(2000); // 等待 2 秒

escapeChars(str)

转义 shell 特殊字符，用于拼接命令字符串。

promiseForEach(arr, asyncFn)

串行异步遍历，依次等待每个 item 处理完成。

工具链命令

cli-core 全局注册以下命令：

| 命令 | 作用 | |------|------| | adc <name> [desc] | 在 src/commands/<name>/ 创建命令模板，自动编译注册并用 VSCode 打开 | | ccli update | 编译 workspace（tsc），扫描 TS 源文件中的 @cmdName 注解同步 package.json bin，执行 npm link | | ccli list | 列出当前已注册的所有命令（表格） | | ccli log [options] | 查看历史运行记录（表格） |

命令注册机制

cli-core 通过扫描 src/commands/ 下所有 .ts 文件中的 @cmdName 注解来确定需要注册的命令：

#!/usr/bin/env node
/**
 * @cmdName my-tool   ← 只有声明了此注解的文件才会被注册为独立命令
 */

注解所在文件对应的编译产物路径会写入 package.json 的 bin 字段。