@cloudglab/confluence-cli 0.0.1

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@cloudglab/confluence-cli",
+  "version": "0.0.1",
+  "description": "Confluence REST CLI for agents and local automation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudglab/confluence-cli.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "confluence": "dist/bin/confluence.js",
+    "confluence-cli": "dist/bin/confluence.js",
+    "confluence-reader": "dist/bin/confluence-reader.js",
+    "confluence-writer": "dist/bin/confluence-writer.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "skills",
+    "docs",
+    "assets"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsx scripts/generate-manifest.ts && tsc -p tsconfig.json && node scripts/fix-bin-mode.mjs",
+    "dev": "tsx src/bin/confluence.ts",
+    "dev:reader": "tsx src/bin/confluence.ts --role reader",
+    "dev:writer": "tsx src/bin/confluence.ts --role writer",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "oxlint src",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build",
+    "release:smoke-query": "node scripts/release-query-smoke.mjs",
+    "prepare": "node scripts/prepare.mjs"
+  },
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.15.0",
+    "@whitebite/diagram-converter": "^0.2.0",
+    "axios": "^1.7.9",
+    "marked": "^18.0.5",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.8",
+    "@types/node": "^22.10.2",
+    "lefthook": "^2.1.9",
+    "oxlint": "^0.15.15",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@9.15.0"
+}

package/skills/confluence-cli/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: confluence-cli
+description: Use this CLI for Confluence REST operations from a terminal or agent workflow. Triggers on Confluence page search, read, upload (Markdown/HTML with Mermaid + TOC), download, labels, attachments, comments, and Confluence 7.13.7 REST pass-through.
+---
+
+# Confluence CLI Skill
+
+Use this CLI when a task needs Confluence REST operations from a terminal or agent workflow.
+
+Start with these references when you need details:
+
+- `reference/overview.md`：整体工作流与安全原则
+- `reference/commands.md`：命令速查
+- `reference/cli.md`：安装、更新、角色入口和环境变量
+- `reference/content.md`：页面查询、读取、子页、评论、标签
+- `reference/transfer.md`：Markdown/HTML 发布、下载、附件、Mermaid/TOC
+- `reference/rest.md`：Confluence 7.13.7 REST 端点透传
+- `../../docs/release.md`：发布前检查与 npm 发布流程
+
+## Decision Matrix
+
+- Read/search small content: `confluence searchContent` or `confluence getContent`.
+- Convert Markdown locally: `confluence convertMarkdownToWiki`.
+- Generate mark metadata: `confluence generateMarkMetadata`.
+- Upload large Markdown through REST: `confluence uploadMarkdown --toc --confirm true`.
+- Upload raw HTML through REST: `confluence uploadHtml --toc --confirm true`.
+- For full page publishes or republish flows, include `--toc` by default; only omit it when the user explicitly says no TOC.
+- Upload Markdown with attachments: `confluence uploadMarkdown --attachments '["a.png"]' --toc --confirm true`.
+- Dry-run uploads first: omit `--confirm true`.
+- Render Mermaid on the fly: any ```mermaid fence in Markdown/HTML auto-generates PNG attachments by default.
+- Download editable backup: `confluence downloadPage`.
+- Download page with attachments/children: `confluence downloadPage --downloadAttachments true --downloadChildren true`.
+- Use MCP-style page tools: `getPageChildren`, `getComments`, `addComment`, `getLabels`, `addLabels`.
+- Use attachment tools: `listAttachments`, `uploadAttachment`, `updateAttachment`, `downloadAttachment`.
+- Check PAT identity: `confluence getCurrentUser`.
+
+## Safety
+
+All writes must pass `--confirm true`. Without confirmation, upload, delete, label, comment and attachment write commands return a dry-run preview.
+
+## CQL Examples
+
+```bash
+confluence searchContent --cql 'space = "DEV" AND text ~ "API"'
+confluence searchContent --cql 'type = page AND title ~ "Runbook"'
+```
+
+## Upload Patterns
+
+```bash
+# Markdown → Confluence，自动 Mermaid → PNG 附件图片，默认注入双 TOC 宏
+confluence uploadMarkdown --file doc.md --id 142552620 --toc --tocMaxLevel 3 --confirm true
+
+# 保持原代码块不渲染
+confluence uploadMarkdown --file doc.md --id 142552620 --mermaid none --toc --confirm true
+
+# HTML → Confluence，同样支持Mermaid和TOC
+confluence uploadHtml --file page.html --space DEV --toc --confirm true
+
+# 只预览（dry-run）
+confluence uploadMarkdown --file doc.md --id 142552620 --toc
+confluence uploadHtml --file page.html --space DEV --toc
+```

package/skills/confluence-cli/reference/cli.md

@@ -0,0 +1,36 @@
+# CLI
+
+## 安装与更新
+
+```bash
+confluence install --skip-config-check true
+confluence update --skip-config-check true
+```
+
+可选参数：
+
+- `--skill-source local|git|npm`
+- `--skill-local-path <dir>`
+- `--cli-only true|false`
+- `--skill-only true|false`
+- `--skip-config-check true|false`
+
+## 角色入口
+
+```bash
+confluence list
+confluence-reader list
+confluence-writer list
+```
+
+- `confluence`：完整入口。
+- `confluence-reader`：不注册发布上传类 transfer 命令。
+- `confluence-writer`：注册写入和发布命令，但仍需要 `--confirm true`。
+
+## 环境变量
+
+- `CONFLUENCE_URL`
+- `CONFLUENCE_PAT` 或 `CONFLUENCE_PERSONAL_TOKEN`
+- `CONFLUENCE_USERNAME` + `CONFLUENCE_PASSWORD`
+- `CONFLUENCE_DISABLE_WRITE=true`
+- `CONFLUENCE_SKIP_UPDATE_CHECK=true`

package/skills/confluence-cli/reference/commands.md

@@ -0,0 +1,41 @@
+# 命令速查
+
+## 基础
+
+```bash
+confluence help
+confluence list
+confluence version
+confluence help searchContent
+```
+
+## 配置
+
+```bash
+confluence initConfluence --url https://confluence.example.com --pat TOKEN --save true
+```
+
+## 查询
+
+```bash
+confluence searchContent --cql 'space = "DEV" AND text ~ "API"'
+confluence getContent --id 123456
+confluence findContent --space DEV --title "API Guide"
+confluence getPageChildren --id 123456 --type page
+```
+
+## 发布与下载
+
+```bash
+confluence uploadMarkdown --file docs/page.md --space DEV --toc --confirm false
+confluence uploadMarkdown --file docs/page.md --id 123456 --attachments '["docs/a.png"]' --toc --confirm true
+confluence uploadHtml --file docs/page.html --space DEV --toc --confirm true
+confluence downloadPage --id 123456 --outputDir exports --downloadAttachments true --downloadChildren true
+```
+
+## REST 透传
+
+```bash
+confluence listRestApis --group content --limit 20
+confluence callRestApi --method GET --path '/content/{id}' --pathParams '{"id":"123456"}' --query '{"expand":"body.storage,version"}'
+```

package/skills/confluence-cli/reference/content.md

@@ -0,0 +1,23 @@
+# 内容操作
+
+## 查询页面
+
+```bash
+confluence searchContent --cql 'type = page AND title ~ "Runbook"'
+confluence findContent --space DEV --title "Runbook"
+confluence getContent --id 123456
+```
+
+## 子页、评论、标签
+
+```bash
+confluence getPageChildren --id 123456 --type page
+confluence getComments --id 123456
+confluence addComment --id 123456 --text "LGTM" --confirm true
+confluence getLabels --id 123456
+confluence addLabels --id 123456 --labels '["api","docs"]' --confirm true
+```
+
+## 安全原则
+
+所有删除、评论、标签等写命令都必须显式 `--confirm true`；不传确认时只返回 preview。

package/skills/confluence-cli/reference/overview.md

@@ -0,0 +1,23 @@
+# 总览
+
+## 这个 skill 做什么
+
+- 用命令行方式操作 Confluence Server/Data Center REST API。
+- 默认写操作只 preview，真实写入必须显式 `--confirm true`。
+- 支持页面搜索、读取、评论、标签、附件、Markdown/HTML 发布、页面下载和 REST 端点透传。
+
+## 推荐工作流
+
+1. 先确认本机是否安装 `confluence`。
+2. 如果没有，优先运行 `confluence install --skip-config-check true`。
+3. 对命令参数不确定时，先运行 `confluence help <command>` 校对。
+4. 查询类任务优先用 `searchContent`、`getContent`、`findContent`。
+5. 发布类任务优先 dry-run，再加 `--confirm true`。
+6. Markdown/HTML 全量发布默认加 `--toc`，除非用户明确不要目录。
+7. 自动化环境可设置 `CONFLUENCE_DISABLE_WRITE=true` 彻底禁用真实写入。
+
+## 适合谁
+
+- 需要命令行操作 Confluence 的人。
+- 需要把 Confluence 接入智能体的人。
+- 需要在 Confluence 7.13.7 环境下稳定自动化的人。

package/skills/confluence-cli/reference/rest.md

@@ -0,0 +1,19 @@
+# REST 透传
+
+`listRestApis` 和 `callRestApi` 用于覆盖 Confluence 7.13.7 官方 REST 端点。
+
+## 查看端点
+
+```bash
+confluence listRestApis --limit 20
+confluence listRestApis --group content --limit 20
+confluence listRestApis --method GET --write false --limit 20
+```
+
+## 调用端点
+
+```bash
+confluence callRestApi --method GET --path '/content/{id}' --pathParams '{"id":"123456"}' --query '{"expand":"body.storage,version"}'
+```
+
+写 REST 端点仍受 `--confirm true` 和 `CONFLUENCE_DISABLE_WRITE=true` 保护。

package/skills/confluence-cli/reference/transfer.md

@@ -0,0 +1,27 @@
+# 发布与下载
+
+## Markdown 发布
+
+```bash
+confluence uploadMarkdown --file docs/page.md --space DEV --toc --confirm false
+confluence uploadMarkdown --file docs/page.md --id 123456 --toc --confirm true
+```
+
+## HTML 发布
+
+```bash
+confluence uploadHtml --file docs/page.html --space DEV --toc --confirm false
+confluence uploadHtml --file docs/page.html --id 123456 --toc --confirm true
+```
+
+## Mermaid 与附件
+
+- 默认将 Markdown/HTML 中的 Mermaid 渲染为 PNG 附件并插入图片宏。
+- 如需保留原代码块，使用 `--mermaid none`。
+- 附件用 JSON 数组传入：`--attachments '["docs/a.png"]'`。
+
+## 下载
+
+```bash
+confluence downloadPage --id 123456 --outputDir exports --downloadAttachments true --downloadChildren true
+```