taskmeld 0.1.1

package/dist/src/cli/errors.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertBooleanFlag = exports.assertRequiredArg = exports.withHelpHint = exports.toCliError = exports.CliError = void 0;
+class CliError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(message, options) {
+        super(message);
+        this.name = "CliError";
+        this.code = options?.code ?? "CLI_ERROR";
+        this.exitCode = options?.exitCode ?? 1;
+        this.details = options?.details;
+    }
+}
+exports.CliError = CliError;
+// 统一把未知异常规范化，避免 CLI 输出结构漂移。
+const toCliError = (error) => {
+    if (error instanceof CliError)
+        return error;
+    if (error instanceof Error) {
+        return new CliError(error.message, {
+            code: "UNEXPECTED_ERROR",
+            exitCode: 1,
+        });
+    }
+    return new CliError("Unknown CLI error", {
+        code: "UNEXPECTED_ERROR",
+        exitCode: 1,
+        details: error,
+    });
+};
+exports.toCliError = toCliError;
+// 在不改动原错误元信息的前提下，为参数类错误附加帮助提示。
+const withHelpHint = (error, hint) => {
+    if (!hint.trim())
+        return error;
+    if (error.message.includes(hint))
+        return error;
+    return new CliError(`${error.message}. ${hint}`, {
+        code: error.code,
+        exitCode: error.exitCode,
+        details: error.details,
+    });
+};
+exports.withHelpHint = withHelpHint;
+const assertRequiredArg = (value, name) => {
+    if (value && value.trim())
+        return value.trim();
+    throw new CliError(`Missing required argument: ${name}`, {
+        code: "INVALID_ARGUMENT",
+        exitCode: 2,
+    });
+};
+exports.assertRequiredArg = assertRequiredArg;
+const assertBooleanFlag = (value, name) => {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "true")
+            return true;
+        if (normalized === "false")
+            return false;
+    }
+    throw new CliError(`Invalid boolean flag: --${name}`, {
+        code: "INVALID_ARGUMENT",
+        exitCode: 2,
+    });
+};
+exports.assertBooleanFlag = assertBooleanFlag;

package/dist/src/cli/help.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHelpHintByRouteKey = exports.resolveHelpHint = exports.resolveHelp = void 0;
+const ROOT_USAGE = "taskmeld <resource> <action> [args] [--flags]";
+const GROUP_DESCRIPTIONS = {
+    agent: "智能体管理",
+    artifact: "产物管理",
+    init: "First-time setup",
+    pipeline: "流水线管理",
+    scheduler: "调度控制",
+    server: "后端服务管理",
+    system: "系统信息",
+};
+const COMMON_OPTIONS_LINES = [
+    "Common Options:",
+    "  -f, --format <json|md>  输出格式（默认: md）",
+    "  --envelope              仅与 --format json 搭配可用，输出完整包装层",
+    "  -h, --help      显示当前命令帮助",
+];
+const listPublicRoutes = (routes) => {
+    return routes.filter((route) => route.hidden !== true);
+};
+const uniqueGroups = (routes) => {
+    return [...new Set(listPublicRoutes(routes).map((route) => route.path[0]))].sort();
+};
+const listGroupActions = (routes, group) => {
+    return listPublicRoutes(routes)
+        .filter((route) => route.path[0] === group)
+        .sort((a, b) => a.path[1].localeCompare(b.path[1]));
+};
+const findCommandRoute = (routes, group, action) => {
+    return routes.find((route) => route.path[0] === group && route.path[1] === action);
+};
+const formatArgsBlock = (args) => {
+    if (!args || args.length === 0)
+        return [];
+    return [
+        "Arguments:",
+        ...args.map((item) => {
+            const printableName = item.name.startsWith("<") ? item.name : `<${item.name}>`;
+            const requiredLabel = item.required ? "必填" : "可选";
+            const detail = item.description ? `，${item.description}` : "";
+            return `  ${printableName}  ${requiredLabel}${detail}`;
+        }),
+    ];
+};
+const formatOptionsBlock = (options) => {
+    if (!options || options.length === 0)
+        return [];
+    return [
+        "Options:",
+        ...options.map((item) => {
+            const flagName = item.flags.join(", ");
+            const valueHint = item.valueName ? ` <${item.valueName}>` : "";
+            const requiredLabel = item.required ? "必填" : "可选";
+            const detail = item.description ? `，${item.description}` : "";
+            return `  ${flagName}${valueHint}  ${requiredLabel}${detail}`;
+        }),
+    ];
+};
+const formatExamplesBlock = (examples) => {
+    if (!examples || examples.length === 0)
+        return [];
+    return ["Examples:", ...examples.map((example) => `  ${example}`)];
+};
+const formatNotesBlock = (notes) => {
+    if (!notes || notes.length === 0)
+        return [];
+    return ["Notes:", ...notes.map((note) => `  ${note}`)];
+};
+const appendCommonOptions = (lines) => {
+    lines.push("", ...COMMON_OPTIONS_LINES);
+};
+const renderRoot = (routes) => {
+    const groups = uniqueGroups(routes);
+    const lines = [
+        "Usage:",
+        `  ${ROOT_USAGE}`,
+        "",
+        "Resources:",
+        ...groups.map((group) => {
+            const desc = GROUP_DESCRIPTIONS[group];
+            return desc ? `  ${group.padEnd(12)}${desc}` : `  ${group}`;
+        }),
+        "",
+        "Tips:",
+        "  taskmeld <resource> -h         查看一级命令帮助",
+        "  taskmeld <resource> <action> -h  查看二级命令帮助",
+    ];
+    return lines.join("\n");
+};
+const renderGroup = (routes, group) => {
+    const commands = listGroupActions(routes, group);
+    const lines = [
+        "Usage:",
+        `  taskmeld ${group} <action> [args] [--flags]`,
+        "",
+        "Actions:",
+        ...commands.map((route) => `  ${route.path[1]}  ${route.description}`),
+        "",
+        "Tips:",
+        `  taskmeld ${group} <action> -h`,
+    ];
+    return lines.join("\n");
+};
+const renderAutoCommandHelp = (route) => {
+    const help = route.help;
+    const lines = ["Usage:", `  ${help.usage}`];
+    const summary = help.summary ?? route.description;
+    lines.push("", "Description:", `  ${summary}`);
+    const argsBlock = formatArgsBlock(help.args);
+    if (argsBlock.length > 0) {
+        lines.push("", ...argsBlock);
+    }
+    const optionsBlock = formatOptionsBlock(help.options);
+    if (optionsBlock.length > 0) {
+        lines.push("", ...optionsBlock);
+    }
+    const examplesBlock = formatExamplesBlock(help.examples);
+    if (examplesBlock.length > 0) {
+        lines.push("", ...examplesBlock);
+    }
+    const notesBlock = formatNotesBlock(help.notes);
+    if (notesBlock.length > 0) {
+        lines.push("", ...notesBlock);
+    }
+    return lines.join("\n");
+};
+const renderCommand = (route) => {
+    // 保留特例出口是为了兼容未来极少数需要完全自定义排版的命令；默认路径必须使用路由元数据生成。
+    const text = route.renderHelp ? route.renderHelp(route) : renderAutoCommandHelp(route);
+    const lines = text.split("\n");
+    appendCommonOptions(lines);
+    return lines.join("\n");
+};
+const resolveHelp = (routes, args) => {
+    if (args.length === 0) {
+        return { scope: "root", text: renderRoot(routes) };
+    }
+    const group = args[0];
+    if (!group) {
+        return { scope: "root", text: renderRoot(routes) };
+    }
+    if (args.length === 1) {
+        const standaloneRoute = routes.find((r) => r.path.length === 1 && r.path[0] === group);
+        if (standaloneRoute) {
+            return { scope: "command", text: renderCommand(standaloneRoute) };
+        }
+        const commands = listGroupActions(routes, group);
+        if (commands.length === 0)
+            return null;
+        return { scope: "group", text: renderGroup(routes, group) };
+    }
+    const action = args[1];
+    const route = findCommandRoute(routes, group, action);
+    if (!route)
+        return null;
+    return { scope: "command", text: renderCommand(route) };
+};
+exports.resolveHelp = resolveHelp;
+const resolveHelpHint = (routes, args) => {
+    if (args.length >= 2) {
+        const group = args[0];
+        const hasGroup = listGroupActions(routes, group).length > 0;
+        if (hasGroup) {
+            return `Use: taskmeld ${group} -h`;
+        }
+    }
+    if (args.length >= 2) {
+        return `Use: taskmeld ${args[0]} ${args[1]} -h`;
+    }
+    if (args.length === 1) {
+        return `Use: taskmeld ${args[0]} -h`;
+    }
+    return "Use: taskmeld -h";
+};
+exports.resolveHelpHint = resolveHelpHint;
+const resolveHelpHintByRouteKey = (routes, routeKey) => {
+    const route = routes.find((item) => item.key === routeKey);
+    if (!route)
+        return "Use: taskmeld -h";
+    return `Use: taskmeld ${route.path[0]} ${route.path[1]} -h`;
+};
+exports.resolveHelpHintByRouteKey = resolveHelpHintByRouteKey;

package/dist/src/cli/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.runCli = void 0;
+require("dotenv/config");
+const version_1 = require("../version");
+const errors_1 = require("./errors");
+const bootstrap_1 = require("./bootstrap");
+const output_1 = require("./output");
+const help_1 = require("./help");
+const router_1 = require("./router");
+const runCli = async (options, runOptions) => {
+    const stdout = runOptions.stdout ?? process.stdout;
+    const stderr = runOptions.stderr ?? process.stderr;
+    let routeKey;
+    let routeGlobal = { format: "json", envelope: false };
+    let bootstrapped = null;
+    try {
+        const routeMatch = (0, router_1.resolveRoute)(runOptions);
+        routeKey = routeMatch.key;
+        routeGlobal = routeMatch.global;
+        const route = (0, router_1.getRouteDefinition)(routeMatch.key);
+        bootstrapped = await options.bootstrap({ routeKey: routeMatch.key, route });
+        const result = await route.handler(routeMatch.input, {
+            app: bootstrapped.app,
+            global: routeMatch.global,
+        });
+        (0, output_1.writeResult)(stdout, route.key, result, routeMatch.global);
+        return 0;
+    }
+    catch (error) {
+        let cliError = (0, errors_1.toCliError)(error);
+        if (cliError.code === "HELP_REQUESTED") {
+            (0, output_1.writeHelp)(stdout, cliError.message);
+            return 0;
+        }
+        if (cliError.code === "VERSION_REQUESTED") {
+            stdout.write(`${version_1.APP_VERSION}\n`);
+            return 0;
+        }
+        if (cliError.code === "INVALID_ARGUMENT" || cliError.code === "UNKNOWN_COMMAND") {
+            const hint = routeKey
+                ? (0, help_1.resolveHelpHintByRouteKey)(router_1.CLI_ROUTES, routeKey)
+                : (0, help_1.resolveHelpHint)(router_1.CLI_ROUTES, runOptions.argv);
+            cliError = (0, errors_1.withHelpHint)(cliError, hint);
+        }
+        (0, output_1.writeError)(stderr, cliError, routeKey, routeGlobal);
+        return cliError.exitCode;
+    }
+    finally {
+        await bootstrapped?.dispose?.();
+    }
+};
+exports.runCli = runCli;
+const main = async (argv) => {
+    return (0, exports.runCli)({
+        bootstrap: (0, bootstrap_1.createMainCliBootstrap)(),
+    }, { argv, stdin: process.stdin });
+};
+exports.main = main;
+if (require.main === module) {
+    void (0, exports.main)(process.argv.slice(2)).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/src/cli/output.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeHelp = exports.writeError = exports.writeResult = void 0;
+const renderers_1 = require("./renderers");
+// 成功输出由 renderer 统一分发，命令层不直接拼接文本。
+const writeResult = (stream, command, data, global) => {
+    stream.write(`${(0, renderers_1.renderSuccessByMode)(command, data, global)}\n`);
+};
+exports.writeResult = writeResult;
+// 错误统一写 stderr，避免污染 stdout 结果流。
+const writeError = (stream, error, command, global) => {
+    stream.write(`${(0, renderers_1.renderErrorByMode)(command, error, global)}\n`);
+};
+exports.writeError = writeError;
+// 帮助信息输出纯文本到 stdout，便于人类直接阅读。
+const writeHelp = (stream, helpText) => {
+    stream.write(`${helpText}\n`);
+};
+exports.writeHelp = writeHelp;

package/dist/src/cli/renderers/engine/json.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderJsonError = exports.formatJson = exports.irToData = void 0;
+const utils_1 = require("./utils");
+const camelKey = (title) => {
+    const cleaned = title.replace(/[^a-zA-Z0-9\s]/g, "");
+    const words = cleaned.split(/\s+/);
+    const first = (words[0] ?? "").toLowerCase();
+    const rest = words.slice(1).map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+    return [first, ...rest].join("");
+};
+const irToData = (ir) => {
+    if (ir.kind === "text")
+        return ir.content;
+    if (ir.kind === "list") {
+        return (0, utils_1.extractListRows)(ir);
+    }
+    // kind: "detail"
+    const result = {};
+    for (const section of ir.sections) {
+        const key = camelKey(section.title);
+        if (section.kind === "key-value") {
+            const obj = {};
+            for (const row of section.rows) {
+                obj[row.field] = row.value;
+            }
+            result[key] = obj;
+        }
+        else if (section.kind === "table") {
+            result[key] = (0, utils_1.extractListRows)(section);
+        }
+        // custom sections are markdown-only, skip in JSON
+    }
+    return result;
+};
+exports.irToData = irToData;
+const formatJson = (ir, envelope, command) => {
+    const data = (0, exports.irToData)(ir);
+    if (!envelope)
+        return JSON.stringify(data);
+    const output = {
+        ok: true,
+        ...(command ? { command } : {}),
+        data,
+        meta: {
+            ts: new Date().toISOString(),
+        },
+    };
+    return JSON.stringify(output);
+};
+exports.formatJson = formatJson;
+const renderJsonError = (command, error) => {
+    const payload = {
+        ok: false,
+        ...(command ? { command } : {}),
+        error: {
+            code: error.code,
+            message: error.message,
+            details: error.details ?? null,
+        },
+        meta: {
+            ts: new Date().toISOString(),
+        },
+    };
+    return JSON.stringify(payload);
+};
+exports.renderJsonError = renderJsonError;

package/dist/src/cli/renderers/engine/markdown.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatMarkdown = exports.extractIr = exports.escapeCell = void 0;
+const utils_1 = require("./utils");
+const escapeCell = (value) => {
+    return (0, utils_1.pickText)(value).replace(/\|/g, "\\|");
+};
+exports.escapeCell = escapeCell;
+const renderTable = (headers, rows) => {
+    const lines = [
+        `| ${headers.join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+    ];
+    for (const row of rows) {
+        lines.push(`| ${row.join(" | ")} |`);
+    }
+    return lines;
+};
+const renderListIr = (ir) => {
+    const lines = [`# ${ir.title}`, ""];
+    if (ir.rows.length === 0) {
+        lines.push(ir.emptyText ?? "(none)");
+        return lines.join("\n");
+    }
+    const headers = ir.columns.map((c) => c.title);
+    const stringRows = ir.rows.map((row) => ir.columns.map((c) => (0, exports.escapeCell)(c.render(row))));
+    return [...lines, ...renderTable(headers, stringRows)].join("\n");
+};
+const extractIr = (spec, data) => {
+    if (spec.kind === "text") {
+        return { kind: "text", title: spec.title, content: spec.render(data) };
+    }
+    if (spec.kind === "list") {
+        const rows = (0, utils_1.asArray)(data).map((row) => (0, utils_1.readRecord)(row));
+        return { kind: "list", title: spec.title, columns: spec.columns, rows, emptyText: spec.emptyText };
+    }
+    // kind: "detail"
+    const sections = [];
+    for (const section of spec.sections) {
+        if (section.visible && !section.visible(data))
+            continue;
+        if (section.kind === "key-value") {
+            const rows = section.rows(data);
+            if (!rows || rows.length === 0)
+                continue;
+            sections.push({ kind: "key-value", title: section.title, rows });
+        }
+        else if (section.kind === "table") {
+            const rows = section.rows(data);
+            if (!rows || rows.length === 0)
+                continue;
+            const recordRows = rows.map((r) => (0, utils_1.readRecord)(r));
+            sections.push({ kind: "table", title: section.title, columns: section.columns, rows: recordRows });
+        }
+        else {
+            // kind: "custom"
+            const lines = section.render(data);
+            if (!lines || lines.length === 0)
+                continue;
+            sections.push({ kind: "custom", title: section.title, lines });
+        }
+    }
+    return { kind: "detail", title: spec.title, sections };
+};
+exports.extractIr = extractIr;
+const formatMarkdown = (ir) => {
+    if (ir.kind === "text") {
+        return ir.content;
+    }
+    if (ir.kind === "list") {
+        return renderListIr(ir);
+    }
+    // kind: "detail"
+    const lines = [`# ${ir.title}`];
+    for (const section of ir.sections) {
+        lines.push("", `## ${section.title}`, "");
+        if (section.kind === "key-value") {
+            lines.push("| Field | Value |", "| --- | --- |");
+            for (const row of section.rows) {
+                lines.push(`| ${(0, exports.escapeCell)(row.field)} | ${(0, exports.escapeCell)(row.value)} |`);
+            }
+        }
+        else if (section.kind === "table") {
+            const headers = section.columns.map((c) => c.title);
+            const stringRows = section.rows.map((row) => section.columns.map((c) => (0, exports.escapeCell)(c.render(row))));
+            lines.push(...renderTable(headers, stringRows));
+        }
+        else {
+            // custom: 直接拼入
+            lines.push(...section.lines);
+        }
+    }
+    return lines.join("\n");
+};
+exports.formatMarkdown = formatMarkdown;

package/dist/src/cli/renderers/engine/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/cli/renderers/engine/utils.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractListRows = exports.readRecord = exports.asArray = exports.pickText = void 0;
+const guards_1 = require("../../../utils/guards");
+const pickText = (value) => {
+    if (value === null || value === undefined)
+        return "-";
+    if (typeof value === "string")
+        return value || "-";
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+};
+exports.pickText = pickText;
+const asArray = (value) => {
+    return Array.isArray(value) ? value : [];
+};
+exports.asArray = asArray;
+const readRecord = (value) => {
+    return (0, guards_1.isRecord)(value) ? value : {};
+};
+exports.readRecord = readRecord;
+const extractListRows = (ir) => {
+    return ir.rows.map((row) => {
+        const entry = {};
+        for (const col of ir.columns) {
+            entry[col.title] = col.render(row);
+        }
+        return entry;
+    });
+};
+exports.extractListRows = extractListRows;

package/dist/src/cli/renderers/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderErrorByMode = exports.renderSuccessByMode = void 0;
+const errors_1 = require("../errors");
+const specs_1 = require("./specs");
+const markdown_1 = require("./engine/markdown");
+const json_1 = require("./engine/json");
+const renderSuccessByMode = (command, data, global) => {
+    const spec = specs_1.commandRenderSpecs[command];
+    if (!spec) {
+        throw new errors_1.CliError(`No render spec registered for command: ${command}`, {
+            code: "MISSING_RENDER_SPEC",
+            exitCode: 1,
+            details: { command },
+        });
+    }
+    const ir = (0, markdown_1.extractIr)(spec, data);
+    return global.format === "md" ? (0, markdown_1.formatMarkdown)(ir) : (0, json_1.formatJson)(ir, global.envelope, command);
+};
+exports.renderSuccessByMode = renderSuccessByMode;
+const renderErrorByMode = (command, error, global) => {
+    if (global.format === "md") {
+        return `# Error\n\n**${error.code}** — ${error.message}`;
+    }
+    return (0, json_1.renderJsonError)(command, error);
+};
+exports.renderErrorByMode = renderErrorByMode;

package/dist/src/cli/renderers/specs/agent.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentRenderSpecs = void 0;
+const utils_1 = require("../engine/utils");
+exports.agentRenderSpecs = {
+    "agent.list": {
+        kind: "list",
+        title: "Agent List",
+        columns: [
+            {
+                title: "Agent ID",
+                render: (row) => row.id ?? "-",
+            },
+            {
+                title: "Name",
+                render: (row) => {
+                    const raw = (0, utils_1.readRecord)(row.raw);
+                    return raw.name ?? row.name ?? "-";
+                },
+            },
+            {
+                title: "Workspace",
+                render: (row) => {
+                    const raw = (0, utils_1.readRecord)(row.raw);
+                    return raw.workspace ?? "-";
+                },
+            },
+            {
+                title: "Runtime",
+                render: (row) => {
+                    const raw = (0, utils_1.readRecord)(row.raw);
+                    const runtime = (0, utils_1.readRecord)(raw.agentRuntime);
+                    return runtime.id ?? "-";
+                },
+            },
+            {
+                title: "Model Primary",
+                render: (row) => {
+                    const raw = (0, utils_1.readRecord)(row.raw);
+                    const model = (0, utils_1.readRecord)(raw.model);
+                    return model.primary ?? "-";
+                },
+            },
+            {
+                title: "Last Active At",
+                render: (row) => row.lastActiveAt ?? row.lastActiveAtMs ?? "-",
+            },
+        ],
+    },
+    "agent.session": {
+        kind: "list",
+        title: "Session List",
+        columns: [
+            {
+                title: "Agent ID",
+                render: (row) => row.agentId ?? "-",
+            },
+            {
+                title: "Session ID",
+                render: (row) => row.sessionId ?? "-",
+            },
+        ],
+    },
+    "agent.send": {
+        kind: "text",
+        render: (data) => {
+            const d = data;
+            if (d.streamed === true)
+                return "";
+            if (!d.reply) {
+                const timedOut = d.timedOut === true;
+                return timedOut ? "(timed out, no reply)" : "(no reply)";
+            }
+            const reply = d.reply;
+            return String(reply.content ?? "-");
+        },
+    },
+};

package/dist/src/cli/renderers/specs/artifact.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.artifactRenderSpecs = void 0;
+exports.artifactRenderSpecs = {
+    "artifact.list": {
+        kind: "list",
+        title: "Artifact List",
+        emptyText: "(none)",
+        columns: [
+            {
+                title: "Artifact ID",
+                render: (row) => row.id ?? row.artifactId ?? "-",
+            },
+            {
+                title: "Pipeline ID",
+                render: (row) => row.pipelineId ?? "-",
+            },
+            {
+                title: "Node ID",
+                render: (row) => row.nodeId ?? "-",
+            },
+            {
+                title: "Type",
+                render: (row) => row.type ?? "-",
+            },
+            {
+                title: "Created At",
+                render: (row) => row.createdAt ?? "-",
+            },
+        ],
+    },
+};