@actiondock/cli 2.10.0 → 2.12.0

package/dist/renderer.js

@@ -1,5 +1,10 @@
-import { formatActionDetail, } from "@actiondock/core/project";
 import { formatError } from "./errors.js";
+export * from "./renderers/project.js";
+export * from "./renderers/action.js";
+export * from "./renderers/playbook.js";
+export * from "./renderers/config.js";
+export * from "./renderers/state.js";
+export * from "./renderers/runs.js";
 /**
  * 构造标准成功结果信封。
  *
@@ -110,440 +115,3 @@ export function renderError(err, options) {
         }
     }
 }
-/**
- * 将工程详情信息转换为机器输出视图（结构化配置契约、规程与动作索引）。
- */
-export function projectDetailToJson(info) {
-    const config = {};
-    if (info.configDeclared && info.configDeclared.length > 0) {
-        for (const key of info.configDeclared) {
-            const item = info.configDef?.[key];
-            config[key] = {
-                ...(item?.description !== undefined ? { description: item.description } : {}),
-                ...(item?.default !== undefined ? { default: item.default } : {}),
-                secret: Boolean(item?.secret),
-            };
-        }
-    }
-    const playbooks = [];
-    if (info.playbooksMap && info.playbooksMap.size > 0) {
-        for (const [id, pb] of info.playbooksMap.entries()) {
-            playbooks.push({
-                id,
-                ...(pb?.description ? { description: pb.description } : {}),
-            });
-        }
-    }
-    else if (info.playbooks && info.playbooks.length > 0) {
-        for (const pbId of info.playbooks) {
-            playbooks.push({ id: pbId });
-        }
-    }
-    const actions = [];
-    if (info.actionsMap && info.actionsMap.size > 0) {
-        for (const [id, act] of info.actionsMap.entries()) {
-            actions.push({
-                id,
-                ...(act?.description ? { description: act.description } : {}),
-            });
-        }
-    }
-    else if (info.actions && info.actions.length > 0) {
-        for (const actId of info.actions) {
-            actions.push({ id: actId });
-        }
-    }
-    const hints = [
-        "Tip: Run 'ad playbook show <id>' to inspect procedure steps before execution.",
-    ];
-    if (info.configDeclared && info.configDeclared.length > 0) {
-        hints.push("Tip: Run 'ad config set <KEY> <val>' to configure required settings.");
-    }
-    const result = {
-        id: info.id,
-        name: info.name || info.id,
-        version: info.version || "0.0.0",
-        root: info.projectRoot,
-        config,
-        playbooks,
-        actions,
-        hints,
-    };
-    if (info.description) {
-        result.description = info.description;
-    }
-    return result;
-}
-/**
- * 格式化渲染单个项目的元数据与详情信息。
- */
-export function renderProjectDetail(info) {
-    const lines = [];
-    lines.push(`ActionDock Project: ${info.name} (${info.id})`);
-    lines.push(`Version:     ${info.version}`);
-    if (info.description) {
-        lines.push(`Description: ${info.description}`);
-    }
-    lines.push(`Root:        ${info.projectRoot}`);
-    if (info.configDeclared.length > 0) {
-        lines.push(`\nDeclared Config Keys (${info.configDeclared.length}):`);
-        for (const k of info.configDeclared) {
-            const item = info.configDef?.[k];
-            const isSec = item?.secret ? " [secret]" : "";
-            const def = item?.default !== undefined ? ` (default: ${JSON.stringify(item.default)})` : "";
-            lines.push(`  - ${k.padEnd(24)} ${item?.description || ""}${def}${isSec}`);
-        }
-    }
-    lines.push(`\nPlaybooks (${info.playbooksCount}):`);
-    if (info.playbooksMap && info.playbooksMap.size > 0) {
-        for (const [id, pb] of info.playbooksMap.entries()) {
-            lines.push(`  - ${id.padEnd(28)} ${pb.description || ""}`);
-        }
-    }
-    else if (info.playbooks && info.playbooks.length > 0) {
-        for (const pbId of info.playbooks) {
-            lines.push(`  - ${pbId}`);
-        }
-    }
-    else {
-        lines.push("  (no playbooks declared)");
-    }
-    lines.push(`\nActions (${info.actionsCount}):`);
-    const actionList = [];
-    if (info.actionsMap) {
-        for (const [id, act] of info.actionsMap.entries()) {
-            actionList.push({ id, description: act.description || "" });
-        }
-    }
-    else if (info.actions) {
-        for (const actId of info.actions) {
-            actionList.push({ id: actId, description: "" });
-        }
-    }
-    if (actionList.length === 0) {
-        lines.push("  (no actions declared)");
-    }
-    else {
-        for (const a of actionList) {
-            lines.push(`  - ${a.id.padEnd(28)} ${a.description}`);
-        }
-    }
-    lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
-    if (info.configDeclared.length > 0) {
-        lines.push("Tip: Run 'ad config set <KEY> <val>' to configure required settings.");
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染已链接的多个 Package 摘要信息。
- */
-export function renderAggregatedPackages(packages, options) {
-    const lines = [];
-    if (options?.header) {
-        lines.push(options.header);
-    }
-    else {
-        lines.push(`ActionDock Linked Packages (${packages.length}):\n`);
-    }
-    for (const p of packages) {
-        lines.push(`- ${p.name} (${p.id}) v${p.version}`);
-        lines.push(`  Path:      ${p.path}`);
-        if (p.description) {
-            lines.push(`  Desc:      ${p.description}`);
-        }
-        lines.push(`  Actions (${p.actionsCount}):   ${p.actions.join(", ") || "(none)"}`);
-        lines.push(`  Playbooks (${p.playbooksCount}): ${p.playbooks.join(", ") || "(none)"}`);
-        lines.push("");
-    }
-    if (options?.showTip !== false) {
-        lines.push("Tip: Run 'ad info <package-id>' to view detailed package configuration and schema.");
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染注册表层级树结构。
- */
-export function renderRegistryTree(status) {
-    const lines = [];
-    const workspaces = status.workspaces || [];
-    const packages = status.packages || [];
-    const hasWorkspaces = workspaces.length > 0;
-    const hasPackages = packages.length > 0;
-    if (!hasWorkspaces && !hasPackages) {
-        lines.push("[INFO] No ActionDock packages or workspaces currently linked.");
-        lines.push("       Run 'ad link' inside an Action package or workspace to register it.");
-        return lines.join("\n");
-    }
-    lines.push("[ActionDock Workspace & Package Tree]\n");
-    if (hasWorkspaces) {
-        lines.push("Workspaces:");
-        for (const ws of workspaces) {
-            const tag = ws.status === "active" ? "[OK]" : "[STALE]";
-            lines.push(`  ${tag} ${ws.path} (${ws.packagesCount} package${ws.packagesCount === 1 ? "" : "s"})`);
-            if (ws.children && ws.children.length > 0) {
-                const children = ws.children;
-                children.forEach((child, idx) => {
-                    const isLast = idx === children.length - 1;
-                    const prefix = isLast ? "    +-- " : "    |-- ";
-                    lines.push(`${prefix}${child.id} (v${child.version}) -> ${child.path}`);
-                });
-            }
-        }
-    }
-    if (hasPackages) {
-        if (hasWorkspaces)
-            lines.push("");
-        lines.push("Standalone Packages:");
-        for (const pkg of packages) {
-            const tag = pkg.status === "active" ? "[OK]" : "[STALE]";
-            lines.push(`  ${tag} ${pkg.id} (v${pkg.version || "unknown"}) -> ${pkg.path}`);
-        }
-    }
-    const totalActive = status.totalPackagesCount ?? packages.length;
-    lines.push(`\n[Summary] Total: ${totalActive} active package(s), ${workspaces.length} workspace(s)`);
-    if (status.staleCount && status.staleCount > 0) {
-        lines.push(`[WARN] ${status.staleCount} stale entry/entries detected. Run 'ad unlink --prune' to clean up.`);
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染 Action 列表。
- */
-export function renderActionList(items, title = "Actions", isFallback = false, intent) {
-    const lines = [];
-    lines.push(`${title}:\n`);
-    if (isFallback && intent) {
-        lines.push(`(No actions matched intent '${intent}', showing all actions)\n`);
-    }
-    if (items.length === 0) {
-        lines.push("  (no actions found)");
-    }
-    else {
-        for (const a of items) {
-            lines.push(`  - ${a.id.padEnd(28)} ${a.description}`);
-        }
-    }
-    lines.push("\nTip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.");
-    return lines.join("\n");
-}
-/**
- * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
- * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
- */
-export function renderActionDetail(action) {
-    return formatActionDetail(action);
-}
-/**
- * 格式化渲染 Action 校验结果。
- */
-export function renderActionValidation(results) {
-    const lines = [];
-    for (const r of results) {
-        if (r.valid) {
-            lines.push(`[OK] ${r.id}: Valid`);
-        }
-        else {
-            lines.push(`[FAIL] ${r.id}: ${r.errors.join(", ")}`);
-        }
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染 Playbook 列表。
- */
-export function renderPlaybookList(items, title = "Playbooks", isFallback = false, intent) {
-    const lines = [];
-    lines.push(`${title}:\n`);
-    if (isFallback && intent) {
-        lines.push(`(No playbooks matched intent '${intent}', showing all playbooks)\n`);
-    }
-    if (items.length === 0) {
-        lines.push("  (no playbooks found)");
-    }
-    else {
-        for (const p of items) {
-            const pkgDesc = p.packageId ? ` (Package: ${p.packageId})` : "";
-            lines.push(`  - ${p.id.padEnd(26)} ${p.description}${pkgDesc}`);
-        }
-    }
-    lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
-    return lines.join("\n");
-}
-/**
- * 格式化渲染 Playbook 详情。
- */
-export function renderPlaybookDetail(pb) {
-    const lines = [];
-    const pkgDesc = pb.packageId ? ` (Package: ${pb.packageId})` : "";
-    lines.push(`Playbook:    ${pb.id}${pkgDesc}`);
-    if (pb.description)
-        lines.push(`Description: ${pb.description}`);
-    if (pb.actions && pb.actions.length > 0) {
-        lines.push(`Actions:     ${pb.actions.join(", ")}`);
-    }
-    if (pb.filePath)
-        lines.push(`File:        ${pb.filePath}\n`);
-    if (pb.content) {
-        lines.push("--- Content ---");
-        lines.push(pb.content);
-    }
-    lines.push("\nTip: Follow steps sequentially. Invoke constituent actions using 'ad run <action> [options] -- <assignments...>'.");
-    return lines.join("\n");
-}
-/**
- * 格式化渲染配置项列表。
- * 掩码决策收敛在命令层（传入的 value 已完成是否打码处理），
- * 此处仅负责值的字符串格式化：字符串原样输出，其余类型 JSON 序列化。
- */
-export function renderConfigList(items, scopeLabel = "Global Scope", isFallback = false, intent) {
-    const lines = [];
-    lines.push(`Configurations [${scopeLabel}]:\n`);
-    if (isFallback && intent) {
-        lines.push(`(No config entries matched intent '${intent}', showing all entries)\n`);
-    }
-    if (items.length === 0) {
-        lines.push("  (No configuration entries found)");
-    }
-    else {
-        for (const item of items) {
-            const valStr = formatConfigValue(item.value);
-            const secretBadge = item.secret ? ", secret" : "";
-            lines.push(`  - ${item.key.padEnd(24)} = ${valStr} (${item.source}${secretBadge})`);
-        }
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化配置值：字符串原样输出，其余类型 JSON 序列化。
- */
-function formatConfigValue(value) {
-    return typeof value === "string" ? value : JSON.stringify(value);
-}
-/**
- * 格式化渲染配置依赖规范检查。
- */
-export function renderConfigSchema(items, packageId, root) {
-    const lines = [];
-    lines.push(`Configuration Requirements for ${packageId} (${root}):\n`);
-    if (items.length === 0) {
-        lines.push("  (No configuration dependencies declared for this package)");
-        return lines.join("\n");
-    }
-    lines.push(`  ${"KEY".padEnd(24)} ${"STATUS".padEnd(12)} ${"SOURCE".padEnd(10)} ${"SECRET".padEnd(8)} DESCRIPTION`);
-    lines.push("  " + "-".repeat(85));
-    const missing = [];
-    for (const item of items) {
-        const statusLabel = item.status === "SET" ? "[SET]" : item.status === "DEFAULT" ? "[DEFAULT]" : "[MISSING]";
-        const secretLabel = item.secret ? "yes" : "no";
-        lines.push(`  ${item.key.padEnd(24)} ${statusLabel.padEnd(12)} ${item.source.padEnd(10)} ${secretLabel.padEnd(8)} ${item.description}`);
-        if (item.status === "MISSING") {
-            missing.push(item.key);
-        }
-    }
-    if (missing.length > 0) {
-        lines.push(`\n[WARNING] ${missing.length} required config(s) not set:`);
-        for (const m of missing) {
-            lines.push(`  - ${m}: Run 'ad config set ${m} <value>' to configure.`);
-        }
-    }
-    else {
-        lines.push("\n[OK] All configuration dependencies are satisfied.");
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染环境变量满足率诊断。
- */
-export function renderConfigEnv(checks, packageId) {
-    const lines = [];
-    const targetDesc = packageId ? `for Package '${packageId}'` : "Global";
-    lines.push(`Environment Variable Satisfaction Diagnostics ${targetDesc}:\n`);
-    if (checks.length === 0) {
-        lines.push("  (No configuration dependencies declared)");
-        return lines.join("\n");
-    }
-    lines.push(`  ${"KEY".padEnd(24)} ${"SATISFIED".padEnd(12)} ${"REQUIRED".padEnd(10)} ${"MATCHED ENV".padEnd(28)} SECRET`);
-    lines.push("  " + "-".repeat(85));
-    for (const c of checks) {
-        const satLabel = c.satisfied ? "[OK]" : "[MISSING]";
-        const reqLabel = c.required ? "yes" : "no";
-        const matched = c.matchedEnv || (c.hasDefault ? "(using default)" : "-");
-        const secLabel = c.secret ? "yes" : "no";
-        lines.push(`  ${c.key.padEnd(24)} ${satLabel.padEnd(12)} ${reqLabel.padEnd(10)} ${matched.padEnd(28)} ${secLabel}`);
-    }
-    const missingRequired = checks.filter((c) => c.required && !c.satisfied);
-    if (missingRequired.length > 0) {
-        lines.push(`\n[WARNING] ${missingRequired.length} required environment variable(s) not satisfied:`);
-        for (const m of missingRequired) {
-            lines.push(`  - ${m.key}: Please export ${m.key}=... in your environment.`);
-        }
-    }
-    else {
-        lines.push("\n[OK] All declared configuration dependencies are satisfied by environment or defaults.");
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染状态键列表。
- */
-export function renderStateList(keys, scopeLabel = "Current State", isFallback = false, intent) {
-    const lines = [];
-    lines.push(`State keys for ${scopeLabel} (${keys.length}):\n`);
-    if (isFallback && intent) {
-        lines.push(`(No state keys matched intent '${intent}', showing all keys)\n`);
-    }
-    if (keys.length === 0) {
-        lines.push("  (no state keys found)");
-    }
-    else {
-        for (const k of keys) {
-            lines.push(`  - ${k}`);
-        }
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染执行记录列表。
- */
-export function renderRunsList(items, scopeLabel = "Execution Runs", isFallback = false, intent) {
-    const lines = [];
-    lines.push(`${scopeLabel} (${items.length}):\n`);
-    if (isFallback && intent) {
-        lines.push(`(No runs matched intent '${intent}', showing all runs)\n`);
-    }
-    lines.push(`  ${"RUN ID".padEnd(38)} ${"PACKAGE".padEnd(18)} ${"ACTION".padEnd(22)} ${"STATUS".padEnd(10)} STARTED`);
-    lines.push("  " + "-".repeat(105));
-    for (const r of items) {
-        const time = (r.startedAt || "").replace("T", " ").slice(0, 19);
-        const pkg = (r.packageId || "").padEnd(18);
-        lines.push(`  ${r.id.padEnd(38)} ${pkg} ${r.actionId.padEnd(22)} ${r.status.padEnd(10)} ${time}`);
-    }
-    return lines.join("\n");
-}
-/**
- * 格式化渲染单次执行记录详情。
- */
-export function renderRunDetail(run) {
-    const lines = [];
-    lines.push(`Run:          ${run.id}`);
-    lines.push(`Action:       ${run.actionId}`);
-    if (run.packageId)
-        lines.push(`Package:      ${run.packageId}`);
-    lines.push(`Status:       ${run.status}`);
-    if (run.parentRunId)
-        lines.push(`Parent Run:   ${run.parentRunId}`);
-    lines.push(`Started:      ${run.startedAt}`);
-    if (run.finishedAt)
-        lines.push(`Finished:     ${run.finishedAt}`);
-    lines.push("\nInput:");
-    lines.push(JSON.stringify(run.input, null, 2));
-    if (run.output !== undefined) {
-        lines.push("\nOutput:");
-        lines.push(JSON.stringify(run.output, null, 2));
-    }
-    if (run.error) {
-        lines.push("\nError:");
-        lines.push(JSON.stringify(run.error, null, 2));
-    }
-    return lines.join("\n");
-}

package/dist/renderers/action.d.ts

@@ -0,0 +1,78 @@
+import type { ActionSpec } from "@actiondock/core";
+import { buildActionDescribePayload } from "@actiondock/core/project";
+/**
+ * 解析 Action 注解中的默认正文输出字段声明。
+ *
+ * 契约规范：
+ * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
+ * - 正文字段键名为 textField，值必须为非空字符串。
+ * - 无相关注解或未声明 textField 时返回 undefined。
+ * - 注解存在但类型非法时抛出 ExecutionError。
+ */
+export declare function resolveActionDefaultTextField(annotations?: Record<string, unknown>): string | undefined;
+/**
+ * 结构化正文与元数据抽取结果。
+ */
+export interface TextFieldExtractionResult {
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 从 Action 执行数据中抽取指定自有顶层正文字段及剩余元数据。
+ *
+ * 契约规范：
+ * - 仅支持结果数据的顶层自有字符串字段，拒绝通过原型链提取。
+ * - 结果数据本身必须为对象且不能为数组。
+ * - 目标字段必须存在且值为字符串（空字符串为合法有效正文）。
+ * - 剩余元数据安全构造，杜绝原型污染；元数据为空时返回 undefined。
+ */
+export declare function extractTextFieldPayload(data: unknown, textField: string): TextFieldExtractionResult;
+/**
+ * 格式化渲染 Action 列表。
+ */
+export declare function renderActionList(items: Array<{
+    id: string;
+    description: string;
+    packageId?: string;
+}>, title?: string, isFallback?: boolean, intent?: string): string;
+/**
+ * 格式化渲染 Action 详情人类可读文本。
+ *
+ * @param input Action 描述载荷或 Action 规范
+ * @returns 格式化后的说明文本
+ */
+export declare function formatActionDetail(input: ReturnType<typeof buildActionDescribePayload> | (Partial<ActionSpec> & {
+    id: string;
+}) | {
+    id: string;
+    packageId?: string;
+    projectRoot?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    tags?: string[];
+    annotations?: Record<string, unknown>;
+    uses?: string[];
+    entry?: string;
+    [key: string]: any;
+}): string;
+/**
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 formatActionDetail 实现。
+ */
+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;