@lark-apaas/miaoda-cli 0.1.0-alpha.08508f4

package/dist/main.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const index_1 = require("./cli/commands/index");
+const config_1 = require("./utils/config");
+const log_id_1 = require("./utils/log_id");
+const output_1 = require("./utils/output");
+const package_json_1 = __importDefault(require("../package.json"));
+const program = new commander_1.Command();
+const { version } = package_json_1.default;
+program
+    .name("miaoda")
+    .description("妙搭平台命令行工具")
+    .version(version, "-v, --version", "显示版本号")
+    .option("--json [fields]", "JSON 输出，可选字段级选择")
+    .option("--output <format>", "输出格式（pretty|json）", "pretty")
+    .option("--verbose", "debug 日志到 stderr")
+    .helpOption("-h, --help", "显示帮助信息")
+    .hook("preAction", (_thisCmd, actionCmd) => {
+    (0, log_id_1.generateLogId)();
+    const opts = actionCmd.optsWithGlobals();
+    (0, config_1.initConfigFromOpts)(opts);
+});
+(0, index_1.registerCommands)(program);
+program.parseAsync(process.argv).catch((err) => {
+    (0, output_1.emitError)(err);
+    process.exitCode = 1;
+});

package/dist/utils/config.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+exports.setConfig = setConfig;
+exports.resetConfig = resetConfig;
+exports.initConfigFromOpts = initConfigFromOpts;
+const defaults = {
+    json: false,
+    output: "pretty",
+    verbose: false,
+};
+let config = { ...defaults };
+function getConfig() {
+    return config;
+}
+function setConfig(partial) {
+    config = { ...config, ...partial };
+}
+function resetConfig() {
+    config = { ...defaults };
+}
+/** 从 CLI 全局 option 初始化 config */
+function initConfigFromOpts(opts) {
+    const json = opts.json;
+    const output = opts.output;
+    setConfig({
+        json: json ?? defaults.json,
+        output: output === "json" || json ? "json" : defaults.output,
+        verbose: opts.verbose ?? defaults.verbose,
+    });
+}

package/dist/utils/error.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = exports.AppError = void 0;
+class AppError extends Error {
+    code;
+    retryable;
+    next_actions;
+    statement_index;
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "AppError";
+        this.code = code;
+        this.retryable = opts?.retryable ?? false;
+        this.next_actions = opts?.next_actions ?? [];
+        this.statement_index = opts?.statement_index;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            next_actions: this.next_actions,
+            statement_index: this.statement_index,
+        };
+    }
+}
+exports.AppError = AppError;
+class HttpError extends AppError {
+    status;
+    url;
+    constructor(status, url, message, opts) {
+        super(`HTTP_${String(status)}`, message, opts ?? { retryable: status >= 500 || status === 429 });
+        this.name = "HttpError";
+        this.status = status;
+        this.url = url;
+    }
+}
+exports.HttpError = HttpError;

package/dist/utils/http.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHttpClient = getHttpClient;
+exports.getRuntimeHttpClient = getRuntimeHttpClient;
+exports.resetHttpClient = resetHttpClient;
+exports.setHttpClient = setHttpClient;
+exports.setRuntimeHttpClient = setRuntimeHttpClient;
+exports.applyCanaryHeader = applyCanaryHeader;
+const http_client_1 = require("@lark-apaas/http-client");
+let adminClient;
+let runtimeClient;
+/**
+ * 获取单例 HttpClient（默认：管理端 innerapi）。
+ *
+ * 管理端链路仅适用于妙搭开发态——baseURL 从 `MIAODA_DEV_INNER_DOMAIN` 读取，
+ * 每次请求自动从 `MIAODA_AUTHN_CODE` 读取用户凭证并注入 `X-Miaoda-Client-Token`。
+ * AK/SK 的 `Authorization` / `x-api-key` 照旧叠加。
+ *
+ * 访问运行端 innerapi（`/api/v1/studio/innerapi/...`）请使用 {@link getRuntimeHttpClient}。
+ */
+function getHttpClient() {
+    adminClient ??= createClient({ adminInnerApi: true });
+    return adminClient;
+}
+/** 运行端 innerapi 单例。baseURL 来自 `FORCE_AUTHN_INNERAPI_DOMAIN`。 */
+function getRuntimeHttpClient() {
+    runtimeClient ??= createClient({ adminInnerApi: false });
+    return runtimeClient;
+}
+/** 重建管理端与运行端客户端（测试/配置变更后调用）。 */
+function resetHttpClient() {
+    adminClient = undefined;
+    runtimeClient = undefined;
+}
+/** 替换管理端 HttpClient 实例（用于测试 mock）。 */
+function setHttpClient(custom) {
+    adminClient = custom;
+}
+/** 替换运行端 HttpClient 实例（用于测试 mock）。 */
+function setRuntimeHttpClient(custom) {
+    runtimeClient = custom;
+}
+function createClient(opts) {
+    const config = {
+        timeout: 30_000,
+        platform: {
+            enabled: true,
+            adminInnerApi: opts.adminInnerApi,
+        },
+        security: {
+            strictMode: true,
+        },
+    };
+    const instance = new http_client_1.HttpClient(config);
+    instance.interceptors.request.use(applyCanaryHeader);
+    return instance;
+}
+/** 若 MIAODA_CANARY_HEADER 已设置，注入 x-tt-env 小流量头 */
+function applyCanaryHeader(reqConfig) {
+    const canary = process.env.MIAODA_CANARY_HEADER;
+    if (!canary)
+        return reqConfig;
+    const headers = new Headers(reqConfig.headers);
+    headers.set("x-tt-env", canary);
+    reqConfig.headers = headers;
+    return reqConfig;
+}

package/dist/utils/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.isJsonMode = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+var error_1 = require("./error");
+Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
+Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
+Object.defineProperty(exports, "setConfig", { enumerable: true, get: function () { return config_1.setConfig; } });
+Object.defineProperty(exports, "resetConfig", { enumerable: true, get: function () { return config_1.resetConfig; } });
+Object.defineProperty(exports, "initConfigFromOpts", { enumerable: true, get: function () { return config_1.initConfigFromOpts; } });
+var log_id_1 = require("./log_id");
+Object.defineProperty(exports, "generateLogId", { enumerable: true, get: function () { return log_id_1.generateLogId; } });
+Object.defineProperty(exports, "getLogId", { enumerable: true, get: function () { return log_id_1.getLogId; } });
+var output_1 = require("./output");
+Object.defineProperty(exports, "emit", { enumerable: true, get: function () { return output_1.emit; } });
+Object.defineProperty(exports, "emitError", { enumerable: true, get: function () { return output_1.emitError; } });
+Object.defineProperty(exports, "isJsonMode", { enumerable: true, get: function () { return output_1.isJsonMode; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "debug", { enumerable: true, get: function () { return logger_1.debug; } });
+Object.defineProperty(exports, "log", { enumerable: true, get: function () { return logger_1.log; } });
+var http_1 = require("./http");
+Object.defineProperty(exports, "getHttpClient", { enumerable: true, get: function () { return http_1.getHttpClient; } });
+Object.defineProperty(exports, "getRuntimeHttpClient", { enumerable: true, get: function () { return http_1.getRuntimeHttpClient; } });
+Object.defineProperty(exports, "resetHttpClient", { enumerable: true, get: function () { return http_1.resetHttpClient; } });
+Object.defineProperty(exports, "setHttpClient", { enumerable: true, get: function () { return http_1.setHttpClient; } });
+Object.defineProperty(exports, "setRuntimeHttpClient", { enumerable: true, get: function () { return http_1.setRuntimeHttpClient; } });

package/dist/utils/log_id.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogId = generateLogId;
+exports.getLogId = getLogId;
+const node_crypto_1 = require("node:crypto");
+let current;
+function generateLogId() {
+    current = (0, node_crypto_1.randomUUID)();
+    return current;
+}
+function getLogId() {
+    return current ?? generateLogId();
+}

package/dist/utils/logger.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debug = debug;
+exports.log = log;
+const config_1 = require("./config");
+/** verbose 模式下输出 debug 日志到 stderr */
+function debug(msg) {
+    if ((0, config_1.getConfig)().verbose) {
+        process.stderr.write(`[debug] ${msg}\n`);
+    }
+}
+/** 始终输出到 stderr 的进度日志 */
+function log(prefix, msg) {
+    process.stderr.write(`[${prefix}] ${msg}\n`);
+}

package/dist/utils/output.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJsonMode = isJsonMode;
+exports.emit = emit;
+exports.emitError = emitError;
+exports.emitOk = emitOk;
+exports.emitPaged = emitPaged;
+const config_1 = require("./config");
+const error_1 = require("./error");
+function isJsonMode() {
+    const cfg = (0, config_1.getConfig)();
+    return cfg.output === "json" || Boolean(cfg.json);
+}
+/**
+ * 输出数据
+ * - pretty 模式：格式化文本到 stdout
+ * - json 模式：裸 JSON 到 stdout
+ */
+function emit(data) {
+    if (isJsonMode()) {
+        process.stdout.write(JSON.stringify(data) + "\n");
+    }
+    else {
+        if (typeof data === "string") {
+            process.stdout.write(data + "\n");
+        }
+        else {
+            process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+        }
+    }
+}
+/**
+ * 输出错误（写入 stderr）
+ * - pretty 模式：Error: message\n  hint: ...
+ * - json 模式：PRD 约定 envelope 为 `{error: {code, message, hint?}}`
+ */
+function emitError(err) {
+    const info = toErrorInfo(err);
+    if (isJsonMode()) {
+        const errObj = {
+            code: info.code,
+            message: info.message,
+        };
+        if (info.next_actions && info.next_actions.length > 0) {
+            errObj.hint = info.next_actions.join(" ");
+        }
+        if (typeof info.statement_index === "number") {
+            errObj.statement_index = info.statement_index;
+        }
+        process.stderr.write(JSON.stringify({ error: errObj }) + "\n");
+    }
+    else {
+        process.stderr.write(`Error: ${info.message}\n`);
+        if (info.next_actions && info.next_actions.length > 0) {
+            process.stderr.write(`  hint: ${info.next_actions.join(" ")}\n`);
+        }
+    }
+}
+/** 发送成功 JSON envelope（非分页）：`{ data }`。 */
+function emitOk(data) {
+    emit({ data });
+}
+/** 发送成功 JSON envelope（分页信封：`{ data, next_cursor, has_more }`）。 */
+function emitPaged(items, nextCursor, hasMore) {
+    emit({ data: items, next_cursor: nextCursor, has_more: hasMore });
+}
+function toErrorInfo(err) {
+    if (err instanceof error_1.AppError)
+        return err.toJSON();
+    const message = err instanceof Error ? err.message : String(err);
+    return { code: "UNKNOWN", message, retryable: false, next_actions: [] };
+}

package/dist/utils/render.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * CLI 渲染 / 解析工具：跨域共用的格式化、表格渲染、字符串解析。
+ *
+ * 按 AGENTS.md §2.2，跨域共享逻辑统一下沉到 `src/utils/*`。
+ * 这里聚合 db / file 域 handler 共用的纯函数：
+ *   - 格式化：formatSize / formatTime
+ *   - 表格渲染：renderAlignedTable / renderTsv / renderKeyValue
+ *   - 终端探测：isStdoutTty
+ *   - 字符串解析：parseDuration / parseSize
+ *
+ * JSON envelope 输出（emit / emitOk / emitPaged / emitError）见 ./output.ts。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSize = formatSize;
+exports.formatTime = formatTime;
+exports.visibleWidth = visibleWidth;
+exports.renderAlignedTable = renderAlignedTable;
+exports.renderTsv = renderTsv;
+exports.renderKeyValue = renderKeyValue;
+exports.isStdoutTty = isStdoutTty;
+exports.parseDuration = parseDuration;
+exports.parseSize = parseSize;
+/** 将字节数格式化为人类可读（`24 KB` / `2.1 MB` / `1.5 GB`）。 */
+function formatSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "—";
+    if (bytes >= 1 << 30)
+        return `${(bytes / (1 << 30)).toFixed(1)} GB`;
+    if (bytes >= 1 << 20)
+        return `${(bytes / (1 << 20)).toFixed(1)} MB`;
+    if (bytes >= 1 << 10)
+        return `${(bytes / (1 << 10)).toFixed(0)} KB`;
+    return `${String(bytes)} bytes`;
+}
+/** 将 ISO 时间转为 TTY 下更友好的相对时间；non-TTY 保持 ISO 原值。 */
+function formatTime(iso, isTty) {
+    if (!iso)
+        return "—";
+    if (!isTty)
+        return iso;
+    const ts = Date.parse(iso);
+    if (Number.isNaN(ts))
+        return iso;
+    const diff = Date.now() - ts;
+    const minute = 60_000;
+    const hour = 60 * minute;
+    const day = 24 * hour;
+    if (diff < hour) {
+        const m = Math.max(1, Math.round(diff / minute));
+        return `${String(m)}m ago`;
+    }
+    if (diff < day) {
+        const h = Math.round(diff / hour);
+        return `${String(h)}h ago`;
+    }
+    if (diff < 7 * day) {
+        const d = Math.round(diff / day);
+        return `${String(d)}d ago`;
+    }
+    // 超过 7 天，用 YYYY-MM-DD
+    const date = new Date(ts);
+    const y = String(date.getFullYear());
+    const mo = String(date.getMonth() + 1).padStart(2, "0");
+    const da = String(date.getDate()).padStart(2, "0");
+    return `${y}-${mo}-${da}`;
+}
+/**
+ * SGR (Select Graphic Rendition) ANSI 转义匹配：`ESC[<digits;...>m`。
+ * 用于在列宽计算时剥离不显示的控制字符——否则带 ANSI 颜色的 cell 会按 .length
+ * 算进列宽（比如 dim "NULL" 实际占 4 字符但 .length=11），导致表格对齐错位。
+ */
+const ANSI_SGR_RE = /\[[0-9;]*m/g;
+/**
+ * 单字符的终端列宽：CJK 全角字符（汉字/假名/全角符号等）占 2 列，其它占 1 列。
+ * 对齐 Unicode East Asian Width 的 W/F 类，等价于 wcwidth 简化版。
+ * 不实现合字 / 零宽字符（ZWJ / 变体选择符）等极端情况，CLI 表格场景够用。
+ */
+function charWidth(cp) {
+    if ((cp >= 0x1100 && cp <= 0x115F) || // Hangul Jamo
+        cp === 0x2329 || cp === 0x232A ||
+        (cp >= 0x2E80 && cp <= 0x303E) || // CJK Radicals / Punctuation
+        (cp >= 0x3041 && cp <= 0x33FF) || // Hiragana / Katakana / CJK Symbols
+        (cp >= 0x3400 && cp <= 0x4DBF) || // CJK Ext A
+        (cp >= 0x4E00 && cp <= 0x9FFF) || // CJK Unified
+        (cp >= 0xA000 && cp <= 0xA4CF) || // Yi
+        (cp >= 0xAC00 && cp <= 0xD7A3) || // Hangul Syllables
+        (cp >= 0xF900 && cp <= 0xFAFF) || // CJK Compat Ideographs
+        (cp >= 0xFE30 && cp <= 0xFE4F) || // CJK Compat Forms
+        (cp >= 0xFF00 && cp <= 0xFF60) || // Fullwidth Forms
+        (cp >= 0xFFE0 && cp <= 0xFFE6) ||
+        (cp >= 0x20000 && cp <= 0x2FFFD) || // CJK Ext B-F
+        (cp >= 0x30000 && cp <= 0x3FFFD) // CJK Ext G-H
+    ) {
+        return 2;
+    }
+    return 1;
+}
+/** cell 可见字符宽度：剥离 ANSI 转义后按终端列宽逐字符累加（CJK 算 2 列）。 */
+function visibleWidth(s) {
+    const stripped = s.replace(ANSI_SGR_RE, "");
+    let w = 0;
+    for (const c of stripped) {
+        w += charWidth(c.codePointAt(0) ?? 0);
+    }
+    return w;
+}
+function padVisibleEnd(s, targetWidth) {
+    const w = visibleWidth(s);
+    return w >= targetWidth ? s : s + " ".repeat(targetWidth - w);
+}
+/** 渲染 TTY 对齐表格（多行，列宽按最长内容；ANSI 转义不计入列宽）。 */
+function renderAlignedTable(headers, rows) {
+    const colWidths = headers.map((h, i) => {
+        let w = visibleWidth(h);
+        for (const row of rows) {
+            const cw = visibleWidth(row[i] || "");
+            if (cw > w)
+                w = cw;
+        }
+        return w;
+    });
+    const lines = [];
+    lines.push(headers.map((h, i) => padVisibleEnd(h, colWidths[i])).join("  ").trimEnd());
+    for (const row of rows) {
+        lines.push(row.map((cell, i) => padVisibleEnd(cell || "", colWidths[i])).join("  ").trimEnd());
+    }
+    return lines.join("\n");
+}
+/** 渲染 non-TTY tab 分隔（字段原值，ISO 时间）。 */
+function renderTsv(headers, rows) {
+    const lines = [];
+    lines.push(headers.join("\t"));
+    for (const row of rows) {
+        lines.push(row.join("\t"));
+    }
+    return lines.join("\n");
+}
+/** 渲染 key-value 多行（用于 stat 等单条详情）。key 右对齐。 */
+function renderKeyValue(pairs, isTty) {
+    if (pairs.length === 0)
+        return "";
+    if (!isTty) {
+        return pairs.map(([k, v]) => `${k}\t${v}`).join("\n");
+    }
+    const keyWidth = Math.max(...pairs.map(([k]) => k.length));
+    return pairs
+        .map(([k, v]) => `${k.padStart(keyWidth)}:  ${v}`)
+        .join("\n");
+}
+/** 通用 isTTY 判定（stdout 是否交互终端）。Node 运行时 isTTY 为 true 或 undefined；TS 类型上 tty.WriteStream 定义为固定 true，绕开做运行时判断。 */
+function isStdoutTty() {
+    const isTTY = process.stdout.isTTY;
+    return isTTY === true;
+}
+/** 解析时长字符串 `7d` / `24h` / `30m` → 秒。无后缀按秒。 */
+function parseDuration(input) {
+    const m = /^(\d+)([smhd]?)$/.exec(input.trim());
+    if (!m) {
+        throw new Error(`Invalid duration: ${input}`);
+    }
+    const n = Number(m[1]);
+    const unit = m[2] || "s";
+    switch (unit) {
+        case "s": return n;
+        case "m": return n * 60;
+        case "h": return n * 3600;
+        case "d": return n * 86400;
+        default: return n;
+    }
+}
+/** 解析 size 字符串 `1MB` / `500KB` / `1GB` → 字节。 */
+function parseSize(input) {
+    const m = /^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i.exec(input.trim());
+    if (!m) {
+        throw new Error(`Invalid size: ${input}`);
+    }
+    const n = Number(m[1]);
+    const unit = (m[2] || "B").toUpperCase();
+    switch (unit) {
+        case "B": return Math.round(n);
+        case "KB": return Math.round(n * 1024);
+        case "MB": return Math.round(n * 1024 * 1024);
+        case "GB": return Math.round(n * 1024 * 1024 * 1024);
+        default: return Math.round(n);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lark-apaas/miaoda-cli",
+  "version": "0.1.0-alpha.08508f4",
+  "description": "Miaoda 平台命令行工具，面向 Agent 调用",
+  "type": "commonjs",
+  "bin": {
+    "miaoda": "bin/miaoda.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "miaoda",
+    "cli",
+    "agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@lark-apaas/http-client": "^0.1.4",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^9.25.1",
+    "husky": "^9.1.7",
+    "tsc-alias": "^1.8.11",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.4",
+    "xml2js": "^0.6.2"
+  },
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src/ --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "dev": "node --import tsx src/main.ts"
+  }
+}