geowiki-cli 1.0.1

package/README.md

@@ -0,0 +1,318 @@
+# GEO Wiki CLI
+
+> AI Agent 与开发者的命令行管理工具
+
+[![npm version](https://img.shields.io/npm/v/geowiki-cli)](https://www.npmjs.com/package/geowiki-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+GEO Wiki CLI 是 [GEO Wiki Pro](https://geowiki.pro) 的命令行工具，专为 AI Agent 和开发者设计，可通过命令行管理知识库的所有内容。
+
+---
+
+## 安装
+
+```bash
+npm install -g geowiki-cli
+```
+
+验证安装：
+
+```bash
+geo --version
+```
+
+---
+
+## 快速开始
+
+### 1. 登录
+
+```bash
+geo login --url https://your-site.com --user admin --pass YourPassword
+```
+
+登录后会保存会话，后续命令自动使用。
+
+### 2. 查看状态
+
+```bash
+geo status
+```
+
+### 3. 列出文档
+
+```bash
+geo doc list
+geo doc list --json          # JSON 格式（供 Agent 使用）
+geo doc list --category cli  # 按分类筛选
+```
+
+---
+
+## 命令参考
+
+### 认证
+
+| 命令 | 说明 |
+|------|------|
+| `geo login --url URL --user USER --pass PASS` | 登录并保存会话 |
+| `geo logout` | 清除保存的凭据 |
+| `geo status` | 显示当前连接状态 |
+
+### 文档管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo doc list` | 列出所有文档 |
+| `geo doc list --category SLUG` | 按分类筛选 |
+| `geo doc list --lang en` | 指定语言 |
+| `geo doc get --slug SLUG` | 获取文档内容 |
+| `geo doc create --file FILE --category CAT` | 创建文档 |
+| `geo doc create --file FILE --category CAT --slug SLUG --lang en` | 创建英文文档 |
+| `geo doc update --slug SLUG --file FILE` | 更新文档 |
+| `geo doc update --slug SLUG --content "新内容"` | 直接更新内容 |
+| `geo doc update --slug SLUG --sort 2` | 更新排序 |
+| `geo doc delete --slug SLUG` | 删除文档（移到回收站） |
+| `geo doc delete --slug SLUG --yes` | 跳过确认删除 |
+| `geo doc trash` | 查看回收站 |
+| `geo doc trash --clear` | 清空回收站 |
+| `geo doc recover --file FILE` | 恢复文档 |
+| `geo doc reorder --orders "slug1:0,slug2:1"` | 批量排序 |
+
+**创建文档示例：**
+
+```bash
+# 从文件创建
+geo doc create --file ./product.md --category products --slug product-a
+
+# 指定语言
+geo doc create --file ./product-en.md --category products --slug product-a --lang en
+
+# 带标签
+geo doc create --file ./guide.md --category docs --tags "guide,tutorial"
+```
+
+### 分类管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo category list` | 列出所有分类 |
+| `geo category create --name "名称" --slug SLUG` | 创建分类 |
+| `geo category create --name "名称" --name-en "Name" --slug SLUG` | 创建分类（含英文名） |
+| `geo category update --slug SLUG --name "新名称"` | 更新分类 |
+| `geo category delete --slug SLUG` | 删除分类 |
+
+### 标签管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo tag list` | 列出所有标签 |
+| `geo tag create --name "名称" --slug SLUG` | 创建标签 |
+| `geo tag delete --slug SLUG` | 删除标签 |
+
+### 媒体管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo media list` | 列出根目录文件 |
+| `geo media list --dir DIR` | 列出子目录文件 |
+| `geo media tree` | 显示目录树 |
+| `geo media upload --file FILE` | 上传文件 |
+| `geo media upload --file FILE --directory DIR` | 上传到子目录 |
+| `geo media mkdir --name NAME` | 创建文件夹 |
+| `geo media mkdir --name NAME --parent PARENT` | 在子目录创建文件夹 |
+| `geo media rmdir --path PATH` | 删除空文件夹 |
+| `geo media move --source SRC --target DIR` | 移动文件 |
+| `geo media move --source DIR/FILE` | 移动到根目录 |
+| `geo media delete --file FILE` | 删除文件 |
+
+**媒体操作示例：**
+
+```bash
+# 上传图片到子目录
+geo media upload --file ./photo.jpg --directory products
+
+# 创建嵌套文件夹
+geo media mkdir --name images --parent products
+
+# 移动文件
+geo media move --source temp/photo.jpg --target products/images
+
+# 查看目录结构
+geo media tree
+```
+
+### 用户管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo user list` | 列出所有用户 |
+| `geo user create --user NAME --pass PASS --role admin` | 创建用户 |
+| `geo user update --user NAME --role editor` | 更新用户角色 |
+| `geo user delete --user NAME` | 删除用户 |
+| `geo user reset-password --user NAME --pass NEWPASS` | 重置密码 |
+
+### 站点配置
+
+| 命令 | 说明 |
+|------|------|
+| `geo config get` | 获取配置 |
+| `geo config get --json` | JSON 格式获取 |
+| `geo config update --hero-title "标题"` | 更新首页标题 |
+| `geo config update --logo-url "/media/logo.png"` | 更新 Logo |
+| `geo config update --favicon-url "/media/favicon.ico"` | 更新 Favicon |
+| `geo config update --featured-slugs "slug1,slug2"` | 设置推荐文档 |
+
+### 草稿管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo draft list` | 列出草稿 |
+| `geo draft get --slug SLUG` | 获取草稿 |
+| `geo draft publish --slug SLUG` | 发布草稿 |
+| `geo draft delete --slug SLUG` | 拒绝/删除草稿 |
+
+### 搜索
+
+```bash
+geo search "关键词"
+geo search "CAN bus" --category products
+geo search "protocol" --lang en --json
+```
+
+### 统计
+
+```bash
+geo stats
+geo stats --json
+```
+
+### 反馈管理
+
+| 命令 | 说明 |
+|------|------|
+| `geo feedback list` | 列出反馈 |
+| `geo feedback delete --id ID` | 删除反馈 |
+| `geo feedback promote --id ID` | 提升为评论 |
+
+### 留言板
+
+| 命令 | 说明 |
+|------|------|
+| `geo guestbook list` | 列出留言 |
+| `geo guestbook toggle` | 开关留言板 |
+| `geo guestbook update --id ID --status approved` | 审核留言 |
+| `geo guestbook delete --id ID` | 删除留言 |
+
+### GEO 优化
+
+| 命令 | 说明 |
+|------|------|
+| `geo geo status` | GEO 状态概览 |
+| `geo geo report` | GEO 详细报告 |
+| `geo geo rebuild` | 重建 llms.txt 和 sitemap |
+
+---
+
+## AI Agent 使用指南
+
+GEO Wiki CLI 专为 AI Agent 设计，所有命令都支持 `--json` 输出：
+
+```bash
+# Agent 获取文档列表
+geo doc list --json
+
+# Agent 搜索文档
+geo search "CAN bus protocol" --json
+
+# Agent 创建文档
+geo doc create --file ./content.md --category products --slug new-product --json
+
+# Agent 上传图片
+geo media upload --file ./diagram.png --directory products --json
+```
+
+### Agent 工作流示例
+
+```bash
+# 1. 获取所有分类
+geo category list --json
+
+# 2. 创建文档
+geo doc create --file ./article.md --category tech --slug my-article
+
+# 3. 上传相关图片
+geo media upload --file ./image.png --directory tech
+
+# 4. 验证创建成功
+geo doc get --slug my-article --json
+```
+
+---
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `GEO_URL` | 站点 URL | — |
+| `GEO_TOKEN` | API Token | — |
+
+使用 API Token 登录（适合 CI/CD）：
+
+```bash
+geo login --url https://your-site.com --token geo_xxxxxxxxxxxx
+```
+
+---
+
+## 常见问题
+
+### 登录失败
+
+```bash
+# 检查连接
+geo status
+
+# 重新登录
+geo login --url https://your-site.com --user admin --pass YourPassword
+```
+
+### 权限不足
+
+确保用户有 `admin` 或 `editor` 角色：
+
+```bash
+geo user list --json
+```
+
+### 文件上传失败
+
+检查文件大小（默认最大 50MB）和文件类型：
+
+```bash
+geo media upload --file ./large-file.zip
+# Error: 文件过大，最大支持 50MB
+```
+
+---
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-org/geowiki-pro.git
+cd geowiki-pro
+
+# 安装依赖
+npm install
+
+# 本地测试 CLI
+node bin/geo.js --help
+node bin/geo.js login --url http://localhost:3002 --user admin --pass Admin@123
+```
+
+---
+
+## License
+
+MIT © GEO Wiki Pro

package/bin/geo.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * GEO Wiki CLI - Entry point
+ * Run via: node bin/geo.js <command>
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..');
+
+// Global error handler for unhandled promise rejections
+process.on('unhandledRejection', (reason) => {
+  console.error(`Error: ${reason?.message || reason || 'Unknown error'}`);
+  process.exit(1);
+});
+
+const cliPath = `file://${projectRoot}/cli/index.js`;
+const { default: main } = await import(cliPath);
+main();

package/cli/commands/category.js

@@ -0,0 +1,171 @@
+/**
+ * Category management commands
+ * Usage: geo category [list|create|update|reorder|delete] [options]
+ */
+
+import { extractArg, hasFlag } from '../utils/args.js';
+import { apiGet, apiPost, apiPut, apiDelete } from '../utils/api.js';
+import { outputJson, outputSuccess, confirmDelete } from '../utils/output.js';
+import { dispatch } from '../utils/dispatch.js';
+
+export async function category(args) {
+  const result = dispatch(
+    args,
+    actions,
+    ['list', 'create', 'update', 'reorder', 'delete'],
+    printCategoryHelp
+  );
+  if (result) await actions[result.action](result.subArgs);
+}
+
+const actions = {
+  async list(args) {
+    const json = hasFlag(args, '--json');
+    const lang = extractArg(args, '--lang') || extractArg(args, '-l') || 'zh';
+
+    const data = await apiGet('/api/v1/categories');
+    const cats = data.data || [];
+
+    if (outputJson(cats, json)) return;
+
+    console.log(`\nCategories (${cats.length} found):\n`);
+    cats.forEach(c => {
+      const displayName = lang === 'jp' ? (c.name_jp || c.name_en || c.name) :
+                          lang === 'en' ? (c.name_en || c.name) : c.name;
+      console.log(`  ${c.slug.padEnd(30)} | sort=${String(c.sort ?? '-').padEnd(3)} | ${displayName}`);
+      if (c.description) console.log(`  ${''.padEnd(30)} | ${c.description}`);
+    });
+  },
+
+  async create(args) {
+    const name = extractArg(args, '--name') || extractArg(args, '-n');
+    const slug = extractArg(args, '--slug') || extractArg(args, '-s');
+    const description = extractArg(args, '--description') || extractArg(args, '-d') || '';
+    const nameEn = extractArg(args, '--name-en');
+    const nameJp = extractArg(args, '--name-jp');
+    const descriptionEn = extractArg(args, '--description-en');
+    const descriptionJp = extractArg(args, '--description-jp');
+    const json = hasFlag(args, '--json');
+
+    if (!name || !slug) {
+      console.error('Error: --name and --slug are required');
+      process.exit(1);
+    }
+
+    const payload = { name, slug, description };
+    if (nameEn != null) payload.name_en = nameEn;
+    if (nameJp != null) payload.name_jp = nameJp;
+    if (descriptionEn != null) payload.description_en = descriptionEn;
+    if (descriptionJp != null) payload.description_jp = descriptionJp;
+
+    await apiPost('/api/v1/admin/categories', payload);
+    outputSuccess(`Category created: ${name} (${slug})`, json, { slug, name });
+  },
+
+  async update(args) {
+    const slug = extractArg(args, '--slug') || extractArg(args, '-s');
+    const name = extractArg(args, '--name') || extractArg(args, '-n');
+    const description = extractArg(args, '--description') || extractArg(args, '-d');
+    const nameEn = extractArg(args, '--name-en');
+    const nameJp = extractArg(args, '--name-jp');
+    const descriptionEn = extractArg(args, '--description-en');
+    const descriptionJp = extractArg(args, '--description-jp');
+    const json = hasFlag(args, '--json');
+
+    if (!slug) {
+      console.error('Error: --slug is required');
+      process.exit(1);
+    }
+
+    const payload = {};
+    if (name != null) payload.name = name;
+    if (description != null) payload.description = description;
+    if (nameEn != null) payload.name_en = nameEn;
+    if (nameJp != null) payload.name_jp = nameJp;
+    if (descriptionEn != null) payload.description_en = descriptionEn;
+    if (descriptionJp != null) payload.description_jp = descriptionJp;
+
+    if (Object.keys(payload).length === 0) {
+      console.error('Error: nothing to update (use --name, --description, --name-en, --name-jp, --description-en, or --description-jp)');
+      process.exit(1);
+    }
+
+    await apiPut(`/api/v1/admin/categories/${encodeURIComponent(slug)}`, payload);
+    outputSuccess(`Category updated: ${slug}`, json, { slug, ...payload });
+  },
+
+  async reorder(args) {
+    const ordersFlag = extractArg(args, '--orders') || extractArg(args, '-o');
+    const json = hasFlag(args, '--json');
+
+    if (!ordersFlag) {
+      console.error('Error: --orders is required (e.g. --orders "products:0,technical:1,support:2")');
+      process.exit(1);
+    }
+
+    const orders = ordersFlag.split(',').map(pair => {
+      const [slug, sort] = pair.split(':').map(s => s && s.trim());
+      const sortNum = Number(sort);
+      if (!slug || Number.isNaN(sortNum)) {
+        console.error(`Error: invalid pair "${pair}". Expected slug:sort.`);
+        process.exit(1);
+      }
+      return { slug, sort: sortNum };
+    });
+
+    await apiPut('/api/v1/admin/categories/reorder', { orders });
+    outputSuccess(`Reordered ${orders.length} categories`, json, { orders });
+  },
+
+  async delete(args) {
+    const slug = extractArg(args, '--slug') || extractArg(args, '-s');
+    const json = hasFlag(args, '--json');
+
+    if (!slug) {
+      console.error('Error: --slug is required');
+      process.exit(1);
+    }
+
+    const confirmed = await confirmDelete(`Delete category "${slug}"?`, args);
+    if (!confirmed) {
+      console.log('Cancelled.');
+      return;
+    }
+
+    await apiDelete(`/api/v1/admin/categories/${encodeURIComponent(slug)}`);
+    outputSuccess(`Category deleted: ${slug}`, json, { deleted: slug });
+  }
+};
+
+function printCategoryHelp() {
+  console.log(`
+Usage: geo category <action> [options]
+
+Actions:
+  list       List all categories
+  create     Create a new category
+  update     Update name/description (admin/editor)
+  reorder    Batch update sort order (admin)
+  delete     Delete a category (admin)
+
+Options:
+  --slug,-s            Category slug (kebab-case)
+  --name,-n            Display name (default language)
+  --name-en            English name
+  --name-jp            Japanese name
+  --description,-d     Short description (default language)
+  --description-en     English description
+  --description-jp     Japanese description
+  --lang,-l            Language for display (zh/en/jp) — list only
+  --orders,-o          For reorder: "slug1:0,slug2:1,slug3:2"
+  --json               Machine-readable JSON output
+
+Examples:
+  geo category list --json
+  geo category create --name "CAN 电机" --name-en "CAN MOTION" --slug can-motion \\
+    --description "CAN总线闭环步进电机" --description-en "CAN bus closed-loop stepper motors"
+  geo category update --slug can-motion --name "新名称" --name-en "New Name"
+  geo category reorder --orders "products:0,technical:1,support:2"
+  geo category delete --slug old-category
+`);
+}

package/cli/commands/config.js

@@ -0,0 +1,180 @@
+/**
+ * Site configuration commands
+ * Usage: geo config [get|update] [options]
+ */
+
+import { extractArg, hasFlag } from '../utils/args.js';
+import { apiGet, apiPut } from '../utils/api.js';
+import { outputJson, outputSuccess } from '../utils/output.js';
+import { dispatch } from '../utils/dispatch.js';
+
+/**
+ * Deep merge a partial update into an existing object.
+ * Only overwrites keys present in `patch`; nested objects are merged recursively.
+ */
+function deepMerge(target, patch) {
+  const result = { ...target };
+  for (const key of Object.keys(patch)) {
+    if (
+      patch[key] !== null &&
+      typeof patch[key] === 'object' &&
+      !Array.isArray(patch[key]) &&
+      typeof result[key] === 'object' &&
+      result[key] !== null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(result[key], patch[key]);
+    } else {
+      result[key] = patch[key];
+    }
+  }
+  return result;
+}
+
+export async function config(args) {
+  const result = dispatch(args, actions, ['get', 'update'], printConfigHelp);
+  if (result) await actions[result.action](result.subArgs);
+}
+
+const actions = {
+  async get(args) {
+    const json = hasFlag(args, '--json');
+
+    const data = await apiGet('/api/v1/admin/config');
+    const cfg = data.data || {};
+
+    if (outputJson(cfg, json)) return;
+
+    console.log('\nSite Configuration:\n');
+    if (cfg.siteName) console.log(`  Site Name: ${cfg.siteName}`);
+    if (cfg.siteDescription) console.log(`  Description: ${cfg.siteDescription}`);
+    if (cfg.defaultLang) console.log(`  Default Language: ${cfg.defaultLang}`);
+    if (cfg.homepageLayout) console.log(`  Homepage Layout: ${JSON.stringify(cfg.homepageLayout)}`);
+    console.log('');
+  },
+
+  async update(args) {
+    const siteName = extractArg(args, '--site-name');
+    const siteDesc = extractArg(args, '--site-desc');
+    const defaultLang = extractArg(args, '--default-lang');
+    const heroTitle = extractArg(args, '--hero-title');
+    const heroSubtitle = extractArg(args, '--hero-subtitle');
+    const featuredSlugs = extractArg(args, '--featured-slugs');
+    const logoUrl = extractArg(args, '--logo-url');
+    const faviconUrl = extractArg(args, '--favicon-url');
+    const customHead = extractArg(args, '--custom-head');
+    const json = hasFlag(args, '--json');
+
+    const payload = {};
+    if (siteName != null) payload.siteName = siteName;
+    if (siteDesc != null) payload.siteDescription = siteDesc;
+    if (defaultLang != null) payload.defaultLang = defaultLang;
+    if (logoUrl != null) payload.logoUrl = logoUrl;
+    if (faviconUrl != null) payload.faviconUrl = faviconUrl;
+    if (customHead != null) payload.customHeadHtml = customHead;
+
+    // Hero fields are multilingual objects { zh, en, jp }.
+    // Accept plain string (sets default lang) or --hero-title-zh/--hero-title-en etc.
+    // Always merge with existing values to avoid losing other languages.
+    const hasHeroTitleUpdate = heroTitle != null || ['zh', 'en', 'jp'].some(l => extractArg(args, `--hero-title-${l}`) != null);
+    const hasHeroSubtitleUpdate = heroSubtitle != null || ['zh', 'en', 'jp'].some(l => extractArg(args, `--hero-subtitle-${l}`) != null);
+
+    if (hasHeroTitleUpdate || hasHeroSubtitleUpdate) {
+      // Read current config to preserve other languages
+      const current = await apiGet('/api/v1/admin/config');
+      const currentCfg = current.data || {};
+
+      if (hasHeroTitleUpdate) {
+        const merged = { ...(currentCfg.heroTitle || {}) };
+        if (heroTitle != null) {
+          merged[defaultLang || 'zh'] = heroTitle;
+        }
+        for (const lang of ['zh', 'en', 'jp']) {
+          const val = extractArg(args, `--hero-title-${lang}`);
+          if (val != null && val !== null) merged[lang] = val;
+        }
+        payload.heroTitle = merged;
+      }
+
+      if (hasHeroSubtitleUpdate) {
+        const merged = { ...(currentCfg.heroSubtitle || {}) };
+        if (heroSubtitle != null) {
+          merged[defaultLang || 'zh'] = heroSubtitle;
+        }
+        for (const lang of ['zh', 'en', 'jp']) {
+          const val = extractArg(args, `--hero-subtitle-${lang}`);
+          if (val != null && val !== null) merged[lang] = val;
+        }
+        payload.heroSubtitle = merged;
+      }
+    }
+
+    if (featuredSlugs != null) {
+      payload._homepageLayoutPatch = { blocks: [{ id: 'featured', config: { slugs: featuredSlugs.split(',').map(s => s.trim()).filter(Boolean) } }] };
+    }
+
+    if (Object.keys(payload).length === 0) {
+      console.error('Error: nothing to update (use --site-name, --site-desc, --default-lang, --hero-title, --hero-subtitle, --featured-slugs, --logo-url, --favicon-url, or --custom-head)');
+      process.exit(1);
+    }
+
+    // For nested homepageLayout patches, read current config and merge
+    const homepagePatch = payload._homepageLayoutPatch;
+    delete payload._homepageLayoutPatch;
+
+    if (homepagePatch) {
+      const current = await apiGet('/api/v1/admin/config');
+      const currentLayout = (current.data || {}).homepageLayout || {};
+      const currentBlocks = Array.isArray(currentLayout.blocks) ? currentLayout.blocks : [];
+      const newBlocks = [...currentBlocks];
+      for (const patch of homepagePatch.blocks) {
+        const idx = newBlocks.findIndex(b => b.id === patch.id);
+        if (idx !== -1) {
+          newBlocks[idx] = deepMerge(newBlocks[idx], patch);
+        }
+      }
+      payload.homepageLayout = { ...currentLayout, blocks: newBlocks };
+    }
+
+    await apiPut('/api/v1/admin/config', payload);
+    outputSuccess('Site configuration updated', json, payload);
+  }
+};
+
+function printConfigHelp() {
+  console.log(`
+Usage: geo config <action> [options]
+
+Actions:
+  get        Get current site configuration
+  update     Update site configuration
+
+Options:
+  --site-name              Site name
+  --site-desc              Site description (for SEO)
+  --default-lang           Default language (zh, en, jp, ...)
+  --hero-title TEXT        Hero section title (sets default language)
+  --hero-title-zh TEXT     Hero title (Chinese)
+  --hero-title-en TEXT     Hero title (English)
+  --hero-title-jp TEXT     Hero title (Japanese)
+  --hero-subtitle TEXT     Hero section subtitle (sets default language)
+  --hero-subtitle-zh TEXT  Hero subtitle (Chinese)
+  --hero-subtitle-en TEXT  Hero subtitle (English)
+  --hero-subtitle-jp TEXT  Hero subtitle (Japanese)
+  --featured-slugs SLUGS   Comma-separated featured doc slugs (e.g. "slug1,slug2,slug3")
+  --logo-url URL           Logo image path (e.g. /media/logo.png)
+  --favicon-url URL        Favicon path (e.g. /media/favicon.ico)
+  --custom-head HTML       Custom HTML for <head> (e.g. '<script>...</script>')
+  --json                   Machine-readable JSON output
+
+Examples:
+  geo config get --json
+  geo config update --site-name "My Wiki" --site-desc "Product documentation"
+  geo config update --hero-title "Welcome" --hero-subtitle "Product docs"
+  geo config update --hero-title-en "Welcome" --hero-subtitle-en "Product docs"
+  geo config update --featured-slugs "quick-start,faq,product-overview"
+  geo config update --logo-url "/media/shared/logo.png" --favicon-url "/media/shared/favicon.ico"
+  geo config update --custom-head '<meta name="theme-color" content="#2563EB">'
+  geo config update --default-lang en
+`);
+}