onepage-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,112 +1,102 @@
-# OnePage CLI（onepage-cli）
+# onepage-cli
 
-在终端用 git 风格指令生成、部署、管理你的 OnePage 静态网页。零依赖，Node 18+ 即可运行。
+OnePage 平台命令行工具（`op` 命令）。在终端部署静态网页、管理博客文章/配置/主题。零依赖，Node 18+。
 
-## 安装
+- 服务端默认：`https://app.collegehub.cn`（可用环境变量 `OP_SERVER` 覆盖）
+- 认证：Bearer Token，`op login` 获取，本地存于 `~/.onepage-cli.json`
+- 响应格式：JSON `{ok, ...}`，401 表示登录失效需重新 `op login`
 
-```bash
-npm install -g onepage-cli
-```
-
-安装后即可使用 `op` 命令（注意：若你同时安装了 1Password CLI，其命令也是 `op`，可通过 `npm exec -p onepage-cli -- op ...` 或全局别名区分）。
-
-## 快速开始
-
-```bash
-op login    # 登录（输入邮箱 + 密码）
-op init     # 在项目目录创建暂存区
-op add .    # 把代码加入暂存区
-op push     # 部署上线（交互式输入短链名、预览图、公开、SEO）
-```
-
-## 全部命令
+## 命令
 
 ### 账号
 
 | 命令 | 说明 |
 |---|---|
-| `op login` | 登录。新邮箱**自动注册**，用户名默认为邮箱 `@` 前面的字符（重名自动加随机后缀） |
+| `op login` | 登录（输入邮箱+密码）。新邮箱自动注册，用户名默认邮箱 @ 前缀 |
 | `op whoami` | 查看当前登录账号 |
-| `op logout` | 退出登录（清除本地凭证） |
+| `op logout` | 退出登录，清除本地凭证 |
 
-### 部署流程
+### 静态站点
 
 | 命令 | 说明 |
 |---|---|
-| `op init` | 在当前目录创建代码暂存区 `.onepage/`，并生成**站点配置模板 `.onepage/preview.yml`** |
-| `op add [路径]` | 把文件/目录加入暂存区，默认当前目录 `.`（自动过滤不支持的类型与 node_modules 等） |
-| `op status` | 查看暂存区文件清单与大小 |
-| `op push` | 部署暂存区代码上线。**存在 `.onepage/preview.yml` 时直接按其配置部署（免交互）**；不存在时回退为交互式输入：短链名 → 预览图路径或 no → 是否公开 → 是否 SEO。短链名已存在且属于自己时为**覆盖更新** |
+| `op init` | 当前目录创建暂存区 `.onepage/`（stage/ + preview.yml） |
+| `op add [路径]` | 把文件/目录加入暂存区（默认当前目录） |
+| `op status` | 查看暂存区文件 |
+| `op push` | 部署上线。无 `.onepage/preview.yml` 时交互式输入短链名/预览图/公开/SEO；有则按配置免交互部署 |
+| `op list` | 列出本账号所有站点 |
+| `op clone <url>` | 拉取站点代码到本地（支持完整 URL 或短链名） |
+| `op delete <name>` | 删除站点（需确认） |
+| `op open <name>` | 浏览器打开站点 |
 
-### preview.yml 站点配置（op init 自动生成）
+`preview.yml` 字段：`path_name`（短链名）、`title`、`description`、`preview`（预览图路径，no 跳过）、`is_public`、`seo`。
 
-```yaml
-# OnePage 站点配置 —— 填好后直接执行 op push，无需交互输入
-title: ''            # 站点名称（留空则使用短链名）
-description: ''      # 站点介绍
-path_name: ''        # 短链名：字母/数字/连字符/下划线，<=64 字符（留空则使用目录名）
-preview: no          # 预览图路径（本地图片文件，无则填 no）
-is_public: yes       # 是否公开（yes/no）
-seo: yes             # 是否 SEO 优化（yes/no）
-```
-
-### 站点管理
+### 博客（`op blog <子命令>`）
 
-| 命令 | 说明 |
+| 子命令 | 说明 |
 |---|---|
-| `op list` | 表格列出本账号所有站点（短链名/标题/公开/浏览/点赞/更新时间/URL） |
-| `op clone <url>` | 拉取站点代码到 `./<短链名>/`（支持完整 URL 或短链名；公开站点可拉，私有站点仅所有者） |
-| `op delete <短链名>` | 删除指定站点（需二次确认 yes/no） |
-| `op open <短链名>` | 在浏览器打开站点 |
-
-## 支持的文件类型
-
-`html` `css` `js` `mjs` `jpg` `jpeg` `png` `gif` `svg` `webp` `ico` `json` `txt` `md` `woff` `woff2` `ttf` `eot` `otf` `mp3` `mp4` `webm` `ogg` `wav` `map`
-
-暂存区自动跳过：`.onepage`、`node_modules`、`.git` 及隐藏文件。
+| `init` | 创建博客工作区 `.onepage/blog/`（config.yml + posts/ + themes/） |
+| `write <标题>` | 新建带 front-matter 的 Markdown 文章模板 |
+| `push [文件] [--publish]` | 推送文章。`--publish` 直接发布（自动过 AI 审核），否则存草稿 |
+| `pull [slug\|all] [-f]` | 拉取远端文章为 Markdown，`-f` 覆盖本地改动 |
+| `list` | 远端文章列表 |
+| `status` | 本地文章与远端对比 |
+| `delete <slug> [-y]` | 删除文章 |
+| `config [pull\|push]` | 拉取/推送博客配置（标题、介绍、主题及选项） |
+| `categories add\|rename\|delete` | 分类管理 |
+| `themes` | 主题列表 |
+| `theme apply <key> [--opt k=v]` | 应用主题及选项（静态页重建） |
+| `theme push <zip> [--overwrite]` | 上传主题包 |
+
+## 博客文章 front-matter 字段
 
-## 配置
-
-登录凭证保存在 `~/.onepage-cli.json`（权限 600）：
-
-```json
-{
-  "server": "https://app.collegehub.cn",
-  "token": "...",
-  "username": "...",
-  "email": "..."
-}
-```
-
-默认服务器为 `https://app.collegehub.cn`；如需指向其他地址，设置环境变量 `OP_SERVER=https://xxx` 后重新 `op login`。
-
-## 典型工作流
-
-```bash
-# 首次
-op login
-mkdir my-site && cd my-site
-# ... 编写 index.html 等文件 ...
-op init && op add . && op push
-# → 短链名 [my-site]:
-# → 预览图路径（no 跳过）: no
-# → 是否公开（yes/no）: yes
-# → 是否 SEO 优化（yes/no）: yes
-# ✓ 部署完成：https://app.collegehub.cn/my-site/
-
-# 更新：改完代码再 add + push（短链名不变即覆盖更新）
-op add . && op push
-
-# 备份/迁移
-op clone https://app.collegehub.cn/my-site/
+```yaml
+---
+title: 标题
+slug: url-slug          # 留空由服务端按标题生成并保证唯一
+status: draft           # draft=草稿 / published=发布
+category: 分类名
+description: 摘要
+cover:                  # 封面图（1.2.0+）
+                        #   本地路径（相对 md 文件）→ push 时自动上传
+                        #   http(s) URL → 自动下载转存
+                        #   留空 → 清除封面
+---
+正文支持 Markdown。
 ```
 
-## 安全说明
-
-- 密码仅在登录/注册时通过 HTTPS 提交一次，本地只保存服务端签发的 token
-- token 与账号绑定，`op logout` 即可作废本地凭证
-- 站点文件由服务端校验扩展名与相对路径（禁止 `..` 越权）
-
-## License
-
-MIT
+- `cover` 仅支持 jpg/jpeg/png/gif/webp，服务端自动压缩为 WebP 存入资源库
+- 本地封面成功上传后，CLI 自动把该字段改写为线上 URL，避免重复上传
+- 封面同时用作文章分享卡片图（og:image）
+
+## 服务端 API（本工具调用）
+
+认证方式：请求头 `Authorization: Bearer <token>`。token 通过 `POST /api/cli/login`（body: `{email, password}`）获取，返回 `{token, username, email}`。
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/cli/deploy` | 部署站点（multipart：文件 + path_name/title/description/preview/is_public/seo） |
+| GET | `/api/cli/sites` | 站点列表 |
+| DELETE | `/api/cli/site/<name>` | 删除站点 |
+| GET | `/api/cli/download/<name>` | 打包下载站点代码 |
+| GET/POST | `/api/cli/blog/config` | 博客配置读取/保存（site_title/description/theme/options） |
+| GET | `/api/cli/blog/posts` | 文章列表（含 cover 字段） |
+| POST | `/api/cli/blog/posts` | 创建/更新文章。body: `{slug?, title?, markdown, description?, category?, status?, publish?, cover_asset_id?, cover_remove?}` |
+| GET | `/api/cli/blog/post/<slug>` | 文章详情（含 markdown 与 cover） |
+| DELETE | `/api/cli/blog/post/<slug>` | 删除文章 |
+| POST | `/api/cli/blog/post/<slug>/publish` | 发布文章 |
+| POST | `/api/cli/blog/assets` | 上传图片资源（multipart `file`），返回 `{asset_id, url}`，自动压缩 WebP |
+| GET/POST | `/api/cli/blog/categories` | 分类查询/管理（action: add/rename/delete） |
+| GET | `/api/cli/blog/themes` | 主题列表 |
+| POST | `/api/cli/blog/theme/apply` | 应用主题（body: `{theme, options}`） |
+| POST | `/api/cli/blog/theme/import` | 导入主题包（multipart zip） |
+
+## 注意事项
+
+1. 需要 Node 18+（使用原生 fetch / FormData / Blob，无第三方依赖）。
+2. 命令名 `op` 与 1Password CLI 重名，冲突时用 `npm exec -p onepage-cli -- op ...` 或设置别名。
+3. 暂存区/博客工作区均在项目目录的 `.onepage/` 下，可加入 .gitignore。
+4. `--publish` 发布会触发 AI 内容审核与静态页重建，属异步操作。
+5. 文章 slug 服务端保证唯一；重复 push 同一 slug 为更新。
+6. 本地凭证文件 `~/.onepage-cli.json` 权限 600，含 Bearer token，勿泄露。
+7. 所有写操作（发布/删除/配置/主题）都会即时同步线上并对已发布页面生效。

package/lib/blog.js

@@ -2,6 +2,7 @@
 // op blog —— 博客模块命令组（文章 Markdown 双向同步 / 配置 / 分类 / 主题）
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { api } = require('./api');
 const { ok, err, info, warn, table } = require('./util');
 
@@ -158,7 +159,7 @@ function cmdWrite(args) {
   while (fs.existsSync(file)) file = path.join(POSTS_DIR, slug + '-' + n++ + '.md');
   fs.writeFileSync(file, buildFrontMatter({
     title, slug: path.basename(file, '.md'),
-    status: 'draft', category: '', description: '',
+    status: 'draft', category: '', description: '', cover: '',
   }, '正文从这里开始…\n'));
   ok('已创建 ' + file);
   console.log('  写完后执行 op blog push ' + path.basename(file) + ' --publish 发布');
@@ -188,6 +189,50 @@ async function cmdStatus(cfg) {
   info('执行 op blog push 上传变更；--publish 同时发布');
 }
 
+
+/* ---------- 封面（cover）---------- */
+function mimeFromName(name) {
+  const e = path.extname(name).toLowerCase();
+  return { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+           '.gif': 'image/gif', '.webp': 'image/webp' }[e] || '';
+}
+
+async function uploadCoverFile(cfg, filePath) {
+  const mime = mimeFromName(filePath);
+  if (!mime) throw new Error('封面仅支持 jpg/jpeg/png/gif/webp：' + filePath);
+  const form = new FormData();
+  form.append('file', new Blob([fs.readFileSync(filePath)], { type: mime }), path.basename(filePath));
+  const res = await fetch(cfg.server + '/api/cli/blog/assets', {
+    method: 'POST', headers: { Authorization: 'Bearer ' + cfg.token }, body: form,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 401) die('登录已失效，请重新执行 op login');
+  if (!data.ok) throw new Error(data.error || '封面上传失败');
+  return data;
+}
+
+// 解析 front-matter 的 cover：空→清除；http(s) URL→下载后上传；否则视为本地路径
+async function resolveCover(cfg, coverVal, mdFile) {
+  const cv = String(coverVal || '').trim();
+  if (!cv) return { cover_remove: true };
+  if (/^https?:\/\//i.test(cv)) {
+    const res = await fetch(cv);
+    if (!res.ok) throw new Error('封面 URL 无法下载：' + cv);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const name = path.basename(new URL(cv).pathname) || 'cover.jpg';
+    const tmp = path.join(os.tmpdir(), 'op-cover-' + Date.now() + '-' + name.replace(/[^\w.-]/g, '_'));
+    fs.writeFileSync(tmp, buf);
+    try {
+      const up = await uploadCoverFile(cfg, tmp);
+      return { cover_asset_id: up.asset_id, cover_url_final: up.url };
+    } finally { try { fs.unlinkSync(tmp); } catch (e) {} }
+  }
+  const local = path.isAbsolute(cv) ? cv : path.join(path.dirname(path.resolve(mdFile)), cv);
+  if (!fs.existsSync(local)) throw new Error('封面文件不存在：' + cv);
+  const up = await uploadCoverFile(cfg, local);
+  return { cover_asset_id: up.asset_id, cover_url_final: up.url };
+}
+
 /* ---------- push ---------- */
 async function cmdPush(args, cfg) {
   const publishFlag = args.includes('--publish');
@@ -206,6 +251,12 @@ async function cmdPush(args, cfg) {
     const { meta, body } = parseFrontMatter(fs.readFileSync(f, 'utf8'));
     if (!body.trim()) { warn('跳过空文件：' + f); continue; }
     const publish = publishFlag || meta.status === 'published';
+    // 封面：front-matter 的 cover 字段（留空=清除封面；本地路径或 http URL）
+    let coverInfo = null;
+    if (meta.cover !== undefined) {
+      try { coverInfo = await resolveCover(cfg, meta.cover, f); }
+      catch (e) { warn('封面处理失败：' + e.message + ' ← ' + f); }
+    }
     const r = await authed(cfg, 'POST', '/api/cli/blog/posts', {
       slug: meta.slug || path.basename(f, '.md'),
       title: meta.title || '',
@@ -213,11 +264,19 @@ async function cmdPush(args, cfg) {
       description: meta.description || '',
       category: meta.category || '',
       publish,
+      ...(coverInfo || {}),
     });
     if (!r.data.ok) { warn((r.data.error || '推送失败') + ' ← ' + f); continue; }
     if (publish) published++; else saved++;
     console.log((publish ? '  ✓ 已发布' : '  ✓ 已保存草稿') + '  ' + r.data.slug +
-      (r.data.created ? '（新建）' : '（更新）'));
+      (r.data.created ? '（新建）' : '（更新）') +
+      (r.data.cover ? '（封面已设置）' : (coverInfo && coverInfo.cover_remove ? '（封面已清除）' : '')));
+    // 本地文件路径上传成功后，把 cover 改写为线上 URL，避免下次 push 重复上传
+    if (r.data.ok && coverInfo && coverInfo.cover_url_final && !/^https?:/i.test(String(meta.cover || ''))) {
+      const abs = new URL(coverInfo.cover_url_final, cfg.server + '/').href;
+      const updated = fs.readFileSync(f, 'utf8').replace(/^(cover:\s*).*$/m, (m0, p1) => p1 + abs);
+      fs.writeFileSync(f, updated);
+    }
   }
   if (published) info(published + ' 篇已发布，将自动进行 AI 内容审核');
   if (saved) info(saved + ' 篇存为草稿，发布执行 op blog push <文件> --publish 或到网页后台');
@@ -249,6 +308,7 @@ async function cmdPull(args, cfg) {
     const content = buildFrontMatter({
       title: p.title, slug: p.slug, status: p.status,
       category: p.category || '', description: p.description || '',
+      cover: p.cover ? new URL(p.cover, cfg.server + '/').href : '',
     }, md);
     if (fs.existsSync(file) && !force && fs.readFileSync(file, 'utf8') !== content) {
       warn('本地有改动，跳过（用 -f 覆盖）：' + p.slug + '.md');
@@ -345,7 +405,7 @@ function cmdHelp() {
     '  init                     创建博客工作区 .onepage/blog/（config.yml + posts/ + themes/）',
     '  write <标题>             新建带 front-matter 的 Markdown 文章模板',
     '  status                   本地文章与远端对比',
-    '  push [文件] [--publish]  推送文章（--publish 直接发布，自动过 AI 审核）',
+    '  push [文件] [--publish]  推送文章（--publish 直接发布，自动过 AI 审核；front-matter 支持 cover 封面）',
     '  pull [slug|all] [-f]     拉取远端文章为 Markdown（-f 覆盖本地改动）',
     '  list                     远端文章列表',
     '  delete <slug> [-y]       删除文章',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onepage-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OnePage 命令行工具：在终端部署管理静态网页与博客（op 静态站指令 + op blog 文章/配置/主题指令）",
   "bin": {
     "op": "bin/op.js"