@cloudglab/confluence-cli 0.0.1

package/dist/core/cli-output.d.ts

@@ -0,0 +1,16 @@
+import type { Role } from "../types/common.js";
+import type { InMemoryCliRegistry } from "./cli-registry.js";
+export declare const BUILTIN_COMMAND_NAMES: string[];
+export declare const BUILTIN_COMMAND_ALIASES: string[];
+export declare function printHelp(role: Role, commandNames: string[]): void;
+export declare function printCommandList(role: Role, commandNames: string[], builtinCommandNames?: string[]): void;
+export declare function getBuiltinCommandHelp(commandName: string): string | undefined;
+export declare function printCommandHelp(registry: InMemoryCliRegistry, name: string): void;
+export declare function renderCommandHelp(registry: InMemoryCliRegistry, name: string): string;
+export interface ChangelogOptions {
+    limit: number | "all";
+    version?: string;
+    since?: string;
+    raw: boolean;
+}
+export declare function renderChangelog(options: ChangelogOptions): Promise<string>;

package/dist/core/cli-output.js

@@ -0,0 +1,318 @@
+import { z } from "zod";
+import { VERSION } from "../version.js";
+import { loadChangelogRaw, loadChangelogSections } from "./changelog.js";
+const BUILTIN_DESCRIPTIONS = {
+    help: "查看总帮助或指定命令参数",
+    list: "按场景列出可用命令",
+    version: "查看 CLI 版本",
+    changelog: "查看版本更新记录",
+    install: "安装 CLI 和 Confluence skill",
+    update: "更新 CLI 和 Confluence skill",
+    upgrade: "update 的别名",
+    uninstall: "卸载 CLI / skill / 配置",
+    remove: "uninstall 的别名",
+};
+const COMMAND_DESCRIPTIONS = {
+    initConfluence: "初始化或校验 Confluence 连接配置",
+    install: "安装 CLI 和 Confluence skill",
+    update: "更新 CLI 和 Confluence skill",
+    convertMarkdownToWiki: "将 Markdown 转换为 Confluence Wiki 标记",
+    convertMermaidToDrawio: "将 Mermaid 图转换为 draw.io XML",
+    generateMarkMetadata: "生成 Markdown 页面元数据",
+    request: "发送原始 Confluence REST 请求",
+    searchSpace: "搜索 Confluence 空间",
+    listSpaces: "列出 Confluence 空间",
+    getSpace: "获取空间详情",
+    searchContent: "使用 CQL 搜索内容",
+    getContent: "获取页面或博客内容",
+    createContent: "创建 Confluence 内容",
+    updateContent: "更新 Confluence 内容",
+    deleteContent: "删除 Confluence 内容",
+    addLabels: "添加内容标签",
+    removeLabel: "移除内容标签",
+    listLabels: "列出内容标签",
+    listAttachments: "列出页面附件",
+    uploadAttachment: "上传页面附件",
+    downloadAttachment: "下载页面附件",
+    uploadMarkdown: "上传 Markdown 为 Confluence 页面",
+    downloadPage: "下载页面为本地内容",
+};
+export const BUILTIN_COMMAND_NAMES = ["changelog", "help", "list", "version"];
+export const BUILTIN_COMMAND_ALIASES = ["install", "update", "upgrade", "uninstall", "remove"];
+export function printHelp(role, commandNames) {
+    const recommended = getRecommendedCommands(commandNames);
+    process.stdout.write([
+        `confluence CLI ${VERSION}`,
+        "",
+        `当前 role: ${role}`,
+        "适配版本：Confluence Data Center / Server REST API。",
+        "运行要求：Node.js >= 18",
+        "",
+        "用法：",
+        "  confluence [--role full|reader|writer] <command> [--key value]",
+        "  confluence help <command>",
+        "  confluence <command> --help",
+        "",
+        "快速开始：",
+        "  confluence list                 查看全部可用命令（推荐）",
+        "  confluence help <command>       查看命令参数",
+        "  confluence initConfluence       初始化或校验连接配置",
+        "  confluence version              查看版本",
+        "  confluence changelog            查看最近更新",
+        "",
+        "安装/更新：",
+        "  confluence install              一键安装 CLI + Skill",
+        "  confluence update               更新到最新版本",
+        "  npx -y @cloudglab/confluence-cli@latest install",
+        "",
+        "常用命令：",
+        ...recommended.map((item) => `  - ${item.name.padEnd(28)} ${item.description}`),
+        "",
+        "写操作保护：",
+        "  真实写操作必须显式传 --confirm true",
+        "  CONFLUENCE_DISABLE_WRITE=true 可强制禁用真实写入",
+        "",
+        "查看更多：",
+        "  confluence list                 按场景查看命令说明",
+        "  confluence list --raw           仅输出命令名，适合脚本处理",
+        "  confluence help <command>       查看某个命令的参数",
+        "",
+    ].join("\n"));
+}
+export function printCommandList(role, commandNames, builtinCommandNames = BUILTIN_COMMAND_NAMES) {
+    const allCommandNames = [...new Set([...builtinCommandNames, ...commandNames])]
+        .sort((left, right) => left.localeCompare(right));
+    const groups = buildCommandGroups(allCommandNames);
+    const lines = [
+        "confluence 可用命令",
+        "",
+        `当前 role: ${role}`,
+        `命令数量：${allCommandNames.length}`,
+        "",
+    ];
+    for (const group of groups) {
+        if (group.commands.length === 0)
+            continue;
+        lines.push(`${group.title}：`);
+        for (const commandName of group.commands) {
+            lines.push(`  - ${commandName.padEnd(28)} ${describeCommand(commandName)}`);
+        }
+        lines.push("");
+    }
+    lines.push("下一步：", "  - 查看参数：confluence help <command>，例如 confluence help searchContent", "  - 初始化配置：confluence initConfluence", "  - 查看脚本友好命令名：confluence list --raw", "  - 切换角色命令集：confluence --role reader list 或 confluence --role writer list", "");
+    process.stdout.write(lines.join("\n"));
+}
+export function getBuiltinCommandHelp(commandName) {
+    const normalizedCommand = commandName === "upgrade"
+        ? "update"
+        : commandName === "remove"
+            ? "uninstall"
+            : commandName;
+    const help = {
+        help: [
+            "confluence help [command]",
+            "",
+            "查看总帮助或指定命令参数。",
+        ].join("\n"),
+        list: [
+            "confluence list [--raw]",
+            "",
+            "按场景列出可用命令。",
+            "",
+            "参数：",
+            "  --raw  仅输出命令名，每行一个，适合脚本处理",
+        ].join("\n"),
+        install: [
+            "confluence install",
+            "",
+            "用法：",
+            "  confluence install [--skill-source local|git|npm] [--skill-local-path <path>] [--skip-config-check] [--cli-only] [--skill-only]",
+            "  npx -y @cloudglab/confluence-cli@latest install",
+            "",
+            "说明：",
+            "  安装或更新 CLI，并按来源安装 Confluence skill。",
+            "",
+            "参数：",
+            "  --skill-source <local|git|npm> （可选）：skill 安装来源，默认 local。",
+            "  --skill-local-path <string> （可选）：直接从本地目录安装 skill。",
+            "  --skip-config-check （可选）：安装后跳过 Confluence 配置校验。",
+            "  --cli-only （可选）：只安装 CLI，不安装 skill。",
+            "  --skill-only （可选）：只安装 skill，不安装 CLI。",
+        ].join("\n"),
+        update: [
+            "confluence update",
+            "",
+            "用法：",
+            "  confluence update [--skill-source local|git|npm] [--skill-local-path <path>] [--skip-config-check] [--cli-only] [--skill-only]",
+            "  npx -y @cloudglab/confluence-cli@latest update",
+            "",
+            "说明：",
+            "  更新或重新安装 CLI，并按来源更新 Confluence skill。",
+            "",
+            "参数：",
+            "  --skill-source <local|git|npm> （可选）：skill 更新来源，默认 local。",
+            "  --skill-local-path <string> （可选）：直接从本地目录更新 skill。",
+            "  --skip-config-check （可选）：更新后跳过 Confluence 配置校验。",
+            "  --cli-only （可选）：只更新 CLI，不更新 skill。",
+            "  --skill-only （可选）：只更新 skill，不更新 CLI。",
+        ].join("\n"),
+        uninstall: [
+            "confluence uninstall",
+            "",
+            "用法：",
+            "  confluence uninstall [--confirm true] [--keep-config true] [--cli-only] [--skill-only]",
+            "  npx -y @cloudglab/confluence-cli@latest uninstall --confirm true",
+            "",
+            "说明：",
+            "  卸载 CLI、Confluence skill，以及可选的本地配置文件。",
+            "",
+            "参数：",
+            "  --confirm （可选）：显式确认后才真实执行卸载。",
+            "  --keep-config （可选）：保留 ~/.confluence/config.json。",
+            "  --cli-only （可选）：只卸载 CLI，不卸载 skill。",
+            "  --skill-only （可选）：只卸载 skill，不卸载 CLI。",
+        ].join("\n"),
+        version: [
+            "confluence version",
+            "",
+            "输出当前 CLI 版本。",
+        ].join("\n"),
+        changelog: [
+            "confluence changelog [--limit N|all] [--version VERSION] [--since VERSION] [--raw]",
+            "",
+            "查看 CHANGELOG.md 中的版本更新记录。",
+            "",
+            "参数：",
+            "  --limit N|all       输出最近 N 个版本，默认 5；all 输出全部",
+            "  --version VERSION   只输出指定版本",
+            "  --since VERSION     输出从最新版到指定版本的记录",
+            "  --raw               输出完整 CHANGELOG.md 原文",
+        ].join("\n"),
+    };
+    return help[normalizedCommand];
+}
+export function printCommandHelp(registry, name) {
+    process.stdout.write(`${renderCommandHelp(registry, name)}\n`);
+}
+export function renderCommandHelp(registry, name) {
+    const selected = registry.get(name);
+    if (!selected)
+        throw new Error(`Unknown command: ${name}`);
+    const lines = [`confluence ${name} [--key value]`];
+    if (selected.description)
+        lines.push("", selected.description);
+    const params = describeParams(selected.schema);
+    if (params.length > 0)
+        lines.push("", "Parameters:", ...params.map((param) => `  ${param}`));
+    return lines.join("\n");
+}
+function buildCommandGroups(commandNames) {
+    const groups = [
+        { title: "开始使用", match: (name) => ["changelog", "help", "list", "version", "install", "update", "upgrade", "uninstall", "remove", "initConfluence"].includes(name), commands: [] },
+        { title: "内容检索 / 页面", match: (name) => /Content|Page|searchContent|getContent/.test(name), commands: [] },
+        { title: "上传 / 下载 / 附件", match: (name) => /Upload|Download|Attachment|upload|download/.test(name), commands: [] },
+        { title: "空间 / 标签", match: (name) => /Space|Label/.test(name), commands: [] },
+        { title: "转换 / 元数据", match: (name) => /convert|generate|Metadata|Markdown|Mermaid|Drawio/.test(name), commands: [] },
+        { title: "底层 REST", match: (name) => ["request"].includes(name), commands: [] },
+        { title: "其他", match: () => true, commands: [] },
+    ];
+    for (const commandName of commandNames) {
+        const group = groups.find((item) => item.match(commandName));
+        group?.commands.push(commandName);
+    }
+    return groups;
+}
+function getRecommendedCommands(commandNames) {
+    const candidates = [
+        { name: "initConfluence", description: "初始化或校验连接配置" },
+        { name: "searchContent", description: "使用 CQL 搜索页面/博客" },
+        { name: "getContent", description: "读取 Confluence 内容" },
+        { name: "uploadMarkdown", description: "上传 Markdown 页面（需确认）" },
+        { name: "downloadPage", description: "下载页面到本地" },
+        { name: "convertMarkdownToWiki", description: "本地转换 Markdown" },
+    ];
+    return candidates.filter((item) => commandNames.includes(item.name));
+}
+function describeCommand(commandName) {
+    return BUILTIN_DESCRIPTIONS[commandName]
+        ?? COMMAND_DESCRIPTIONS[commandName]
+        ?? `查看参数：confluence help ${commandName}`;
+}
+export async function renderChangelog(options) {
+    if (options.raw)
+        return loadChangelogRaw();
+    const sections = await loadChangelogSections();
+    if (sections.length === 0)
+        throw new Error("CHANGELOG.md 中没有版本记录");
+    let selected = sections;
+    if (options.version) {
+        selected = sections.filter((section) => section.version === options.version);
+        if (selected.length === 0)
+            throw new Error(`未找到版本 ${options.version} 的更新记录`);
+    }
+    else if (options.since) {
+        const sinceIndex = sections.findIndex((section) => section.version === options.since);
+        if (sinceIndex === -1)
+            throw new Error(`未找到起始版本 ${options.since}`);
+        selected = sections.slice(0, sinceIndex + 1);
+    }
+    else if (options.limit !== "all") {
+        selected = sections.slice(0, options.limit);
+    }
+    const header = options.version
+        ? `confluence CLI ${options.version} 更新内容`
+        : `confluence CLI 最近更新（共 ${sections.length} 个版本）`;
+    return [header, "", ...selected.map((section) => section.content)].join("\n").trimEnd() + "\n";
+}
+function describeParams(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (!(unwrapped instanceof z.ZodObject))
+        return [];
+    return Object.entries(unwrapped.shape).map(([key, field]) => describeParam(key, field));
+}
+function describeParam(name, schema) {
+    const isOptional = schema instanceof z.ZodOptional || schema instanceof z.ZodDefault;
+    const defaultValue = schema instanceof z.ZodDefault ? formatDefaultValue(schema._def.defaultValue()) : undefined;
+    const description = schema.description;
+    const parts = [`--${name} ${describeZodType(schema)}`, isOptional ? "optional" : "required"];
+    if (defaultValue !== undefined)
+        parts.push(`default=${defaultValue}`);
+    if (description)
+        parts.push(description);
+    return parts.join(" | ");
+}
+function unwrapSchema(schema) {
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable)
+        return unwrapSchema(schema.unwrap());
+    if (schema instanceof z.ZodDefault)
+        return unwrapSchema(schema._def.innerType);
+    if (schema instanceof z.ZodEffects)
+        return unwrapSchema(schema.innerType());
+    return schema;
+}
+function describeZodType(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped instanceof z.ZodString)
+        return "string";
+    if (unwrapped instanceof z.ZodNumber)
+        return "number";
+    if (unwrapped instanceof z.ZodBoolean)
+        return "boolean";
+    if (unwrapped instanceof z.ZodArray)
+        return "array";
+    if (unwrapped instanceof z.ZodEnum)
+        return unwrapped.options.join("|");
+    if (unwrapped instanceof z.ZodObject)
+        return "json-object";
+    return "value";
+}
+function formatDefaultValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value) || (typeof value === "object" && value !== null))
+        return JSON.stringify(value);
+    return String(value);
+}
+//# sourceMappingURL=cli-output.js.map

package/dist/core/cli-registry.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolHandler } from "../types/common.js";
+export interface RegisteredTool<TInput = unknown> {
+    name: string;
+    description?: string;
+    schema: z.ZodType<TInput>;
+    handler: ToolHandler<TInput>;
+}
+export interface CliRegistry {
+    tool<TInput>(name: string, schema: z.ZodType<TInput>, handler: ToolHandler<TInput>, description?: string): void;
+    get(name: string): RegisteredTool | undefined;
+    list(): RegisteredTool[];
+}
+export declare class InMemoryCliRegistry implements CliRegistry {
+    private readonly tools;
+    tool<TInput>(name: string, schema: z.ZodType<TInput>, handler: ToolHandler<TInput>, description?: string): void;
+    get(name: string): RegisteredTool | undefined;
+    list(): RegisteredTool[];
+}
+export declare function parseCommandInput(schema: z.ZodType, args: string[]): unknown;

package/dist/core/cli-registry.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+export class InMemoryCliRegistry {
+    tools = new Map();
+    tool(name, schema, handler, description) {
+        this.tools.set(name, { name, schema, handler: handler, description });
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return [...this.tools.values()].sort((left, right) => left.name.localeCompare(right.name));
+    }
+}
+export function parseCommandInput(schema, args) {
+    const raw = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith("--")) {
+            throw new Error(`无法识别的位置参数: ${token}`);
+        }
+        const equalsIndex = token.indexOf("=");
+        const key = equalsIndex >= 0 ? token.slice(2, equalsIndex) : token.slice(2);
+        if (!key)
+            throw new Error("检测到空参数名。");
+        const next = args[index + 1];
+        const hasInlineValue = equalsIndex >= 0;
+        const hasExplicitValue = !hasInlineValue && typeof next === "string" && !next.startsWith("--");
+        const value = hasInlineValue ? token.slice(equalsIndex + 1) : hasExplicitValue ? next : true;
+        if (hasExplicitValue)
+            index += 1;
+        appendArg(raw, key, value);
+    }
+    const objectSchema = unwrapObjectSchema(schema);
+    if (!objectSchema)
+        return schema.parse(raw);
+    const shape = objectSchema.shape;
+    const unknownKeys = Object.keys(raw).filter((key) => !(key in shape));
+    if (unknownKeys.length > 0) {
+        throw new Error(`未知参数: ${unknownKeys.map((key) => `--${key}`).join(", ")}`);
+    }
+    const converted = {};
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (!(key in raw))
+            continue;
+        converted[key] = coerceValue(selectValueForSchema(raw[key], fieldSchema), fieldSchema);
+    }
+    return schema.parse(converted);
+}
+function appendArg(target, key, value) {
+    const current = target[key];
+    if (current === undefined) {
+        target[key] = value;
+        return;
+    }
+    if (Array.isArray(current)) {
+        current.push(value);
+        return;
+    }
+    target[key] = [current, value];
+}
+function selectValueForSchema(value, schema) {
+    if (!Array.isArray(value))
+        return value;
+    const unwrapped = unwrapSchema(schema);
+    return unwrapped instanceof z.ZodArray ? value : value[value.length - 1];
+}
+function coerceValue(value, schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped instanceof z.ZodBoolean)
+        return toBoolean(value);
+    if (unwrapped instanceof z.ZodNumber)
+        return toNumber(value);
+    if (unwrapped instanceof z.ZodString)
+        return typeof value === "string" ? value : String(value);
+    if (unwrapped instanceof z.ZodArray) {
+        const items = Array.isArray(value)
+            ? value
+            : typeof value === "string" && value.trim().startsWith("[")
+                ? parseJsonValue(value, "数组参数")
+                : typeof value === "string"
+                    ? value.split(",").map((item) => item.trim()).filter(Boolean)
+                    : [value];
+        return items.map((item) => coerceValue(item, unwrapped.element));
+    }
+    if (unwrapped instanceof z.ZodObject) {
+        if (typeof value !== "string")
+            return value;
+        return parseJsonValue(value, "对象参数");
+    }
+    if (unwrapped instanceof z.ZodUnion) {
+        for (const option of unwrapped._def.options) {
+            try {
+                return coerceValue(value, option);
+            }
+            catch {
+                // try next option
+            }
+        }
+    }
+    return value;
+}
+function parseJsonValue(value, label) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`无法解析${label}: ${value}（${message}）`);
+    }
+}
+function unwrapObjectSchema(schema) {
+    const unwrapped = unwrapSchema(schema);
+    return unwrapped instanceof z.ZodObject ? unwrapped : undefined;
+}
+function unwrapSchema(schema) {
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable)
+        return unwrapSchema(schema.unwrap());
+    if (schema instanceof z.ZodDefault)
+        return unwrapSchema(schema._def.innerType);
+    if (schema instanceof z.ZodEffects)
+        return unwrapSchema(schema.innerType());
+    if (schema instanceof z.ZodPipeline)
+        return unwrapSchema(schema._def.out);
+    return schema;
+}
+function toBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["true", "1", "yes", "y", "on"].includes(normalized))
+            return true;
+        if (["false", "0", "no", "n", "off"].includes(normalized))
+            return false;
+    }
+    throw new Error(`无法解析布尔值: ${String(value)}`);
+}
+function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    throw new Error(`无法解析数字: ${String(value)}`);
+}
+//# sourceMappingURL=cli-registry.js.map

package/dist/core/command-groups.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const commandToGroup: Record<string, string>;
+export declare const groupCommands: Record<string, string[]>;

package/dist/core/command-groups.generated.js

@@ -0,0 +1,88 @@
+// 由 scripts/generate-manifest.ts 在 build 时自动生成，请勿手动编辑。
+export const commandToGroup = {
+    "initConfluence": "init",
+    "install": "install",
+    "remove": "install",
+    "uninstall": "install",
+    "update": "install",
+    "convertMarkdownToWiki": "convert",
+    "convertMermaidToDrawio": "convert",
+    "generateMarkMetadata": "metadata",
+    "callRestApi": "rest",
+    "listRestApis": "rest",
+    "convertContentBody": "space",
+    "getCurrentUser": "space",
+    "getSpace": "space",
+    "listSpaces": "space",
+    "addComment": "content",
+    "deleteContent": "content",
+    "findContent": "content",
+    "getComments": "content",
+    "getContent": "content",
+    "getPageChildren": "content",
+    "searchContent": "content",
+    "addLabels": "labels",
+    "deleteLabel": "labels",
+    "getLabels": "labels",
+    "downloadAttachment": "attachments",
+    "listAttachments": "attachments",
+    "updateAttachment": "attachments",
+    "uploadAttachment": "attachments",
+    "downloadPage": "transfer",
+    "uploadHtml": "transfer",
+    "uploadMarkdown": "transfer"
+};
+export const groupCommands = {
+    "init": [
+        "initConfluence"
+    ],
+    "install": [
+        "install",
+        "remove",
+        "uninstall",
+        "update"
+    ],
+    "convert": [
+        "convertMarkdownToWiki",
+        "convertMermaidToDrawio"
+    ],
+    "metadata": [
+        "generateMarkMetadata"
+    ],
+    "rest": [
+        "callRestApi",
+        "listRestApis"
+    ],
+    "space": [
+        "convertContentBody",
+        "getCurrentUser",
+        "getSpace",
+        "listSpaces"
+    ],
+    "content": [
+        "addComment",
+        "deleteContent",
+        "findContent",
+        "getComments",
+        "getContent",
+        "getPageChildren",
+        "searchContent"
+    ],
+    "labels": [
+        "addLabels",
+        "deleteLabel",
+        "getLabels"
+    ],
+    "attachments": [
+        "downloadAttachment",
+        "listAttachments",
+        "updateAttachment",
+        "uploadAttachment"
+    ],
+    "transfer": [
+        "downloadPage",
+        "uploadHtml",
+        "uploadMarkdown"
+    ]
+};
+//# sourceMappingURL=command-groups.generated.js.map

package/dist/core/config.d.ts

@@ -0,0 +1,5 @@
+import type { ConfluenceConfig } from "../types/common.js";
+export declare function normalizeConfig(raw: Partial<ConfluenceConfig>): ConfluenceConfig;
+export declare function loadConfluenceConfig(): ConfluenceConfig;
+export declare function saveConfig(config: Partial<ConfluenceConfig>): void;
+export declare function maskConfig(config: ConfluenceConfig): ConfluenceConfig;