@actiondock/cli 2.0.12 → 2.2.1

package/dist/prompt.d.ts

@@ -0,0 +1,53 @@
+import type { CliContext } from "./types.js";
+/**
+ * 密码输入提示配置选项。
+ */
+export interface PromptPasswordOptions {
+    /** 掩码字符，默认为 '*'；若传入空字符串则为完全无回显静默模式 */
+    mask?: string;
+    /** 自定义输入流，默认为 process.stdin */
+    inputStream?: NodeJS.ReadableStream;
+    /** 自定义输出流，默认为 process.stdout */
+    outputStream?: NodeJS.WritableStream;
+}
+/**
+ * 在终端中安全交互式读取用户输入的密码或敏感信息。
+ * 处于 TTY 交互终端时，自动进入原始模式并打印掩码字符；退出时确保恢复终端回显。
+ *
+ * @param promptText 提示文案，例如 "Enter value: "
+ * @param options 配置选项
+ */
+export declare function promptPassword(promptText: string, options?: PromptPasswordOptions): Promise<string>;
+/**
+ * 在终端中常规交互式读取一行文本输入。
+ *
+ * @param promptText 提示文案
+ * @param options 配置选项
+ */
+export declare function promptText(promptText: string, options?: {
+    inputStream?: NodeJS.ReadableStream;
+    outputStream?: NodeJS.WritableStream;
+}): Promise<string>;
+/**
+ * 从可读流中读取单行内容。
+ */
+export declare function readStreamLine(stream: NodeJS.ReadableStream): Promise<string>;
+/**
+ * 从流中完整读取所有数据，并移除末尾的换行符。
+ */
+export declare function readEntireStdin(stream?: NodeJS.ReadableStream): Promise<string>;
+/**
+ * 解析并获取配置项的具体输入值。
+ * 优先顺序：
+ * - context.promptInput（测试或宿主环境注入）
+ * - --stdin / context.stdin（标准输入流读取）
+ * - 终端交互式输入（区分 secret 掩码模式与普通文本模式）
+ * - 管道非 TTY 降级读取
+ */
+export declare function resolveConfigValueInput(options: {
+    promptText: string;
+    secret?: boolean;
+    mask?: string;
+    context?: CliContext;
+    useStdin?: boolean;
+}): Promise<string>;

package/dist/prompt.js

@@ -0,0 +1,192 @@
+import { createInterface } from "node:readline";
+import { ArgumentError, SigintError } from "./errors.js";
+/**
+ * 在终端中安全交互式读取用户输入的密码或敏感信息。
+ * 处于 TTY 交互终端时，自动进入原始模式并打印掩码字符；退出时确保恢复终端回显。
+ *
+ * @param promptText 提示文案，例如 "Enter value: "
+ * @param options 配置选项
+ */
+export async function promptPassword(promptText, options = {}) {
+    const mask = options.mask ?? "*";
+    const stdin = (options.inputStream || process.stdin);
+    const stdout = (options.outputStream || process.stdout);
+    // 如果并非处于交互式终端或不支持原始模式，降级为普通流式单行读取
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+        return readStreamLine(stdin);
+    }
+    return new Promise((resolve, reject) => {
+        stdout.write(promptText);
+        let password = "";
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf-8");
+        let isCleanedUp = false;
+        const cleanup = () => {
+            if (isCleanedUp)
+                return;
+            isCleanedUp = true;
+            try {
+                stdin.setRawMode(false);
+            }
+            catch {
+                // 忽略可能存在的终端模式恢复异常
+            }
+            stdin.pause();
+            stdin.removeListener("data", onData);
+        };
+        const onData = (chunk) => {
+            const str = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+            for (const char of str) {
+                switch (char) {
+                    case "\n":
+                    case "\r":
+                    case "\u0004": // Ctrl+D
+                        cleanup();
+                        stdout.write("\n");
+                        resolve(password);
+                        return;
+                    case "\u0003": // Ctrl+C
+                        cleanup();
+                        stdout.write("\n");
+                        reject(new SigintError("User cancelled input"));
+                        return;
+                    case "\u0008": // Backspace
+                    case "\x7f": // Delete
+                        if (password.length > 0) {
+                            password = password.slice(0, -1);
+                            if (mask) {
+                                stdout.write("\b \b");
+                            }
+                        }
+                        break;
+                    case "\u001b": // Escape sequence
+                        break;
+                    default:
+                        // 过滤不可见控制字符，只追加可打印字符
+                        if (char.charCodeAt(0) >= 32) {
+                            password += char;
+                            if (mask) {
+                                stdout.write(mask);
+                            }
+                        }
+                        break;
+                }
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/**
+ * 在终端中常规交互式读取一行文本输入。
+ *
+ * @param promptText 提示文案
+ * @param options 配置选项
+ */
+export async function promptText(promptText, options) {
+    const input = options?.inputStream || process.stdin;
+    const output = options?.outputStream || process.stdout;
+    const rl = createInterface({ input, output });
+    return new Promise((resolve, reject) => {
+        rl.question(promptText, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+        rl.on("SIGINT", () => {
+            rl.close();
+            reject(new SigintError("User cancelled input"));
+        });
+    });
+}
+/**
+ * 从可读流中读取单行内容。
+ */
+export async function readStreamLine(stream) {
+    return new Promise((resolve, reject) => {
+        const rl = createInterface({
+            input: stream,
+            crlfDelay: Infinity,
+        });
+        let resolved = false;
+        rl.once("line", (line) => {
+            resolved = true;
+            rl.close();
+            resolve(line);
+        });
+        rl.once("close", () => {
+            if (!resolved) {
+                resolve("");
+            }
+        });
+        rl.once("error", (err) => {
+            rl.close();
+            reject(err);
+        });
+    });
+}
+/**
+ * 从流中完整读取所有数据，并移除末尾的换行符。
+ */
+export async function readEntireStdin(stream = process.stdin) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on("data", (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        stream.once("end", () => {
+            const content = Buffer.concat(chunks).toString("utf-8");
+            resolve(content.replace(/[\r\n]+$/, ""));
+        });
+        stream.once("error", reject);
+        if ("resume" in stream && typeof stream.resume === "function") {
+            stream.resume();
+        }
+    });
+}
+/**
+ * 解析并获取配置项的具体输入值。
+ * 优先顺序：
+ * - context.promptInput（测试或宿主环境注入）
+ * - --stdin / context.stdin（标准输入流读取）
+ * - 终端交互式输入（区分 secret 掩码模式与普通文本模式）
+ * - 管道非 TTY 降级读取
+ */
+export async function resolveConfigValueInput(options) {
+    const { promptText: queryText, secret, mask, context, useStdin } = options;
+    const effectiveMask = mask ?? (secret ? "*" : undefined);
+    // 1. 如果上下文注入了自定义输入函数（如测试隔离环境），优先调用
+    if (context?.promptInput) {
+        return await context.promptInput(queryText, { secret, mask: effectiveMask });
+    }
+    // 2. 如果显式指定了 --stdin 选项
+    if (useStdin) {
+        const stream = context?.stdin || process.stdin;
+        const val = await readEntireStdin(stream);
+        if (!val) {
+            throw new ArgumentError("No data received from standard input");
+        }
+        return val;
+    }
+    // 3. 如果上下文提供了自定义 stdin 流
+    if (context?.stdin) {
+        const val = await readEntireStdin(context.stdin);
+        if (!val) {
+            throw new ArgumentError("Value is required for config set. Omit value in an interactive terminal to enter securely, or pass via stdin.");
+        }
+        return val;
+    }
+    // 4. 判断是否处于交互式终端设备
+    const isTty = Boolean(process.stdin.isTTY && typeof process.stdin.setRawMode === "function");
+    if (isTty) {
+        if (secret) {
+            return await promptPassword(queryText, { mask: effectiveMask });
+        }
+        return await promptText(queryText);
+    }
+    // 5. 非交互式终端环境（例如管道输入 echo "val" | ad config set key）
+    const val = await readEntireStdin(process.stdin);
+    if (!val) {
+        throw new ArgumentError("Value is required for config set. Omit value in an interactive terminal to enter securely, or pass via stdin.");
+    }
+    return val;
+}

package/dist/renderer.d.ts

@@ -0,0 +1,197 @@
+import type { RunRecord } from "@actiondock/sdk";
+import type { RegistryStatusReport } from "@actiondock/core";
+import type { Envelope, ProjectDetailInfo, AggregatedPackage, EnvCheckItem, CliContext } from "./types.js";
+/**
+ * 构造标准成功结果信封。
+ *
+ * @param data 业务数据载荷
+ * @param meta 附加元数据
+ */
+export declare function createSuccessEnvelope<T>(data: T, meta?: Record<string, unknown>): Envelope<T>;
+/**
+ * 构造标准失败结果信封。
+ *
+ * @param code 错误码
+ * @param message 错误描述信息
+ * @param details 附加错误细节
+ * @param meta 附加元数据
+ */
+export declare function createErrorEnvelope(code: string, message: string, details?: unknown, meta?: Record<string, unknown>): Envelope<never>;
+/**
+ * 序列化数据为格式化 JSON 字符串。
+ *
+ * @param data 待序列化数据
+ * @param pretty 是否美化格式
+ */
+export declare function formatJson(data: unknown, pretty?: boolean): string;
+/**
+ * 标准输出写入辅助方法。
+ */
+export declare function writeStdout(message: string, context?: CliContext): void;
+/**
+ * 标准错误写入辅助方法。
+ */
+export declare function writeStderr(message: string, context?: CliContext): void;
+/**
+ * 统一根据输出模式进行渲染输出。
+ */
+export declare function renderResult<T>(data: T, options: {
+    json?: boolean;
+    envelope?: boolean;
+    humanFormatter?: () => string;
+    context?: CliContext;
+}): void;
+/**
+ * 统一渲染异常输出。
+ */
+export declare function renderError(err: unknown, options: {
+    json?: boolean;
+    envelope?: boolean;
+    context?: CliContext;
+}): void;
+/**
+ * 将工程详情信息转换为机器输出视图（剔除 Map 明细与定义字典）。
+ */
+export declare function projectDetailToJson(info: ProjectDetailInfo): {
+    id: string;
+    name: string;
+    version: string;
+    description: string | undefined;
+    projectRoot: string;
+    actionsDir: string;
+    playbooksDir: string;
+    actionsCount: number;
+    playbooksCount: number;
+    actions: string[];
+    playbooks: string[];
+    configDeclared: string[];
+};
+/**
+ * 格式化渲染单个项目的元数据与详情信息。
+ */
+export declare function renderProjectDetail(info: ProjectDetailInfo): string;
+/**
+ * 格式化渲染已链接的多个 Package 摘要信息。
+ */
+export declare function renderAggregatedPackages(packages: AggregatedPackage[], options?: {
+    header?: string;
+    showTip?: boolean;
+}): string;
+/**
+ * 远端 info 接口返回的注册表树视图（与 RegistryStatusReport 字段兼容的宽松结构）。
+ */
+export type RegistryTreeView = RegistryStatusReport | (Record<string, unknown> & {
+    workspaces?: Array<{
+        id?: string;
+        path: string;
+        status: string;
+        packagesCount?: number;
+        children?: Array<{
+            id: string;
+            version?: string;
+            path: string;
+        }>;
+    }>;
+    packages?: Array<{
+        id: string;
+        version?: string;
+        path: string;
+        status: string;
+    }>;
+    totalPackagesCount?: number;
+    staleCount?: number;
+});
+/**
+ * 格式化渲染注册表层级树结构。
+ */
+export declare function renderRegistryTree(status: RegistryTreeView): string;
+/**
+ * 格式化渲染 Action 列表。
+ */
+export declare function renderActionList(items: Array<{
+    id: string;
+    description: string;
+    packageId?: string;
+}>, title?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染 Action 详情。
+ */
+export declare function renderActionDetail(action: {
+    id: string;
+    packageId?: string;
+    projectRoot?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}): string;
+/**
+ * 格式化渲染 Action 校验结果。
+ */
+export declare function renderActionValidation(results: Array<{
+    id: string;
+    valid: boolean;
+    errors: string[];
+}>): string;
+/**
+ * 格式化渲染 Playbook 列表。
+ */
+export declare function renderPlaybookList(items: Array<{
+    id: string;
+    description?: string;
+    packageId?: string;
+}>, title?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染 Playbook 详情。
+ */
+export declare function renderPlaybookDetail(pb: {
+    id: string;
+    packageId?: string;
+    description?: string;
+    actions?: string[];
+    filePath?: string;
+    content?: string;
+}): string;
+/**
+ * 格式化渲染配置项列表。
+ * 掩码决策收敛在命令层（传入的 value 已完成是否打码处理），
+ * 此处仅负责值的字符串格式化：字符串原样输出，其余类型 JSON 序列化。
+ */
+export declare function renderConfigList(items: Array<{
+    key: string;
+    value: unknown;
+    source: string;
+    secret: boolean;
+    description?: string;
+}>, scopeLabel?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染配置依赖规范检查。
+ */
+export declare function renderConfigSchema(items: Array<{
+    key: string;
+    status: string;
+    source: string;
+    secret: boolean;
+    description: string;
+}>, packageId: string, root: string): string;
+/**
+ * 格式化渲染环境变量满足率诊断。
+ */
+export declare function renderConfigEnv(checks: EnvCheckItem[], packageId?: string): string;
+/**
+ * 格式化渲染状态键列表。
+ */
+export declare function renderStateList(keys: string[], scopeLabel?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染执行记录列表。
+ */
+export declare function renderRunsList(items: Array<{
+    id: string;
+    actionId: string;
+    packageId?: string;
+    status: string;
+    startedAt: string;
+}>, scopeLabel?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染单次执行记录详情。
+ */
+export declare function renderRunDetail(run: RunRecord): string;