wpops 0.2.0 → 0.3.1

package/README.md

@@ -115,15 +115,19 @@ node bin/wpops.js doctor
 > **退出码**:`0` 成功;`2` 用法/参数错误(stderr 打印错误 + 精简用法 + `--help` 提示);`1` 运行期错误(HTTP/网络/配置)。`--help` 始终走 stdout 且为 `0`。
 
 ```
-# 内容
+# 内容(默认存草稿,发布是独立动作——见下方"发布安全")
 wpops posts  list [--per-page 10] [--page 2] [--status draft] [--search 关键词]
                  [--orderby date] [--order desc] [--categories 1,2] [--tags 3]
                  [--author 1] [--after 2026-01-01] [--before 2026-12-31] [--json]
 wpops posts  get <id>
-wpops posts  create --title "标题" --content "正文" [--status draft] [--categories 1,2] [--tags 3] [--featured-media 44]
+wpops posts  create --title "标题" --content "正文" [--categories 1,2] [--tags 3]   # 未给 --status 即草稿
 wpops posts  create --title "标题" --from-file ./post.md --status draft
-wpops posts  update <id> --title "新标题" [--status publish] [--featured-media 0]
-wpops posts  delete <id> [--force]        # 默认进回收站
+wpops posts  export <id> --file post.html              # 导出正文,本地改排版
+wpops posts  update <id> --from-file post.html --dry-run   # 先预览,再真正应用(下面这行)
+wpops posts  update <id> --from-file post.html
+wpops posts  publish <id>                              # 显式发布
+wpops posts  unpublish <id>                            # 下线为草稿
+wpops posts  delete <id> [--force]                     # 默认进回收站
 wpops pages  ...                          # 同样的子命令
 wpops me
 
@@ -229,11 +233,20 @@ wpops raw POST /wp-json/wp/v2/comments --data '{"post":1,"content":"hi"}'
 
 # 安全开关
 wpops posts delete 12 --dry-run                     # 只预览,不执行(所有写命令都支持)
+wpops posts update 12 --from-file post.html --dry-run
 wpops --all posts delete 12 --dry-run               # 跨站预览
 wpops --all plugins list                            # 读操作无需确认
 wpops --all plugins activate akismet/akismet --yes  # 写操作必须 --yes
 ```
 
+### 发布安全(两步走)
+
+- **创建默认草稿**,不会直接上线;发布是独立动作 `wpops posts publish <id>`(页面/CPT 同理),下线用 `unpublish <id>`。
+- 修改**已发布**内容的正文时,会先在 stderr 提示并给出修订回滚命令(加 `--yes` 可静默);`settings` / 菜单位置等 live 变更同样会提示。
+- 改版式/长文的安全流程:`export` 导出正文 → 本地编辑 → 建**草稿副本**预览(回显后台编辑链接)→ `update --from-file` 应用到原页 → 不满意用 `revisions restore` 回滚。
+- **页面构建器注意**:Elementor / SiteOrigin / Divi 等把布局存在插件 meta 里,直接改 REST 的 `post_content` 会**弄坏页面**;这类页面请在构建器 UI 里改,wpops 只用于体检/备份/回滚。
+- WP 的**前端草稿预览**依赖登录态,应用密码在浏览器里用不了;可靠入口是回显的**后台编辑/预览链接**。
+
 ## 4. 多站点
 
 所有站点都放在 `sites/`,一个站点一个文件:

package/lib/commands.js

@@ -3,7 +3,7 @@ import { basename, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { loadEnv, configHome } from './env.js';
 import { buildConfig, createClient, WpError } from './client.js';
-import { stripTags, printJson, dry, pick, listRequest, parseJson, readJsonFile } from './util.js';
+import { stripTags, printJson, dry, warn, pick, listRequest, parseJson, readJsonFile } from './util.js';
 import { UsageError } from './errors.js';
 
 const CONTENT = {
@@ -31,10 +31,14 @@ const USERS = '/wp-json/wp/v2/users';
 const MENUS = '/wp-json/wp/v2/menus';
 const MENU_ITEMS = '/wp-json/wp/v2/menu-items';
 
-function printItem(data, flags) {
+/** 内容写操作的结果输出:草稿/待审等非公开状态额外回显后台编辑(预览)链接。 */
+function printItem(data, flags, client) {
   if (flags.json) return printJson(data);
   console.log(`✓ #${data.id} [${data.status}] ${stripTags(data.title?.rendered || '')}`);
-  if (data.link) console.log(`  ${data.link}`);
+  if (data.link) console.log(`  链接:${data.link}`);
+  if (data.status && data.status !== 'publish' && client?.root) {
+    console.log(`  编辑/预览:${client.root}/wp-admin/post.php?post=${Number(data.id)}&action=edit`);
+  }
 }
 
 // ------------------------------------------------------------------ doctor
@@ -255,17 +259,61 @@ export async function createContent(client, type, flags) {
   if (body.title === undefined && body.content === undefined) {
     throw new UsageError('至少需要 --title 或 --content/--from-file');
   }
-  if (flags['dry-run']) return dry(`创建 ${type} ${JSON.stringify(body)}`);
+  // 未显式指定状态时按草稿创建,不依赖服务端默认(避免"直接发布")。
+  if (body.status === undefined) body.status = 'draft';
+  if (flags['dry-run']) return dry(`将创建 ${type}(status=${body.status}) ${JSON.stringify(body)}`);
   const { data } = await client.request('POST', contentPath(type), { body });
-  printItem(data, flags);
+  printItem(data, flags, client);
 }
 
 export async function updateContent(client, type, id, flags) {
   const body = contentBody(flags);
   if (!Object.keys(body).length) throw new UsageError('没有可更新的字段');
-  if (flags['dry-run']) return dry(`更新 ${type} #${id} ${JSON.stringify(body)}`);
+  // 修改已发布内容的正文(未显式改状态)会立即影响线上:先提示可回滚(--yes 跳过预检与提示)。
+  if (body.status === undefined && !flags.yes) {
+    try {
+      const { data: current } = await client.request('GET', `${contentPath(type)}/${Number(id)}`, {
+        query: { context: 'edit' },
+      });
+      if (current.status === 'publish') {
+        warn(
+          `正在修改已发布内容 ${type} #${id};已生成修订,回滚:wpops revisions restore ${id} <rev> --type ${type}`,
+          flags,
+        );
+      }
+    } catch {
+      // 预检失败(权限/网络)不阻断写入,也不提示。
+    }
+  }
+  if (flags['dry-run']) return dry(`将更新 ${type} #${id} ${JSON.stringify(body)}`);
   const { data } = await client.request('POST', `${contentPath(type)}/${Number(id)}`, { body });
-  printItem(data, flags);
+  printItem(data, flags, client);
+}
+
+/** 显式发布 / 下线为草稿。 */
+export async function setContentStatus(client, type, id, status, flags) {
+  const label = status === 'publish' ? '发布' : '下线为草稿';
+  if (flags['dry-run']) return dry(`将${label} ${type} #${id}`);
+  const { data } = await client.request('POST', `${contentPath(type)}/${Number(id)}`, { body: { status } });
+  if (flags.json) return printJson(data);
+  console.log(`✓ #${data.id} → ${data.status}  ${data.link || ''}`);
+  if (data.status !== 'publish' && client.root) {
+    console.log(`  编辑/预览:${client.root}/wp-admin/post.php?post=${Number(data.id)}&action=edit`);
+  }
+}
+
+/** 导出原始正文 content.raw 到文件(或 stdout),便于本地改排版后再 `update --from-file`。 */
+export async function exportContent(client, type, id, flags) {
+  const { data } = await client.request('GET', `${contentPath(type)}/${Number(id)}`, {
+    query: { context: 'edit' },
+  });
+  const raw = data.content?.raw ?? stripTags(data.content?.rendered || '');
+  if (flags.file !== undefined) {
+    writeFileSync(String(flags.file), raw, 'utf8');
+    console.log(`✓ 已导出 ${type} #${id} → ${flags.file}`);
+    return;
+  }
+  process.stdout.write(raw.endsWith('\n') ? raw : `${raw}\n`);
 }
 
 export async function deleteContent(client, type, id, flags) {
@@ -586,6 +634,9 @@ export async function updateMenu(client, id, flags) {
   if (!Object.keys(body).length) {
     throw new UsageError('没有可更新的字段(--name/--slug/--description/--locations/--auto-add)');
   }
+  if (body.locations !== undefined) {
+    warn('正在修改菜单位置绑定,会立即影响站点导航', flags);
+  }
   if (flags['dry-run']) return dry(`更新菜单 #${id} ${JSON.stringify(body)}`);
   const { data } = await menuRequest(client, 'POST', `${MENUS}/${Number(id)}`, { body });
   if (flags.json) return printJson(data);
@@ -593,6 +644,7 @@ export async function updateMenu(client, id, flags) {
 }
 
 export async function deleteMenu(client, id, flags) {
+  warn('删除菜单会影响站点导航', flags);
   if (flags['dry-run']) return dry(`删除菜单 #${id}`);
   if (!flags.force) throw new UsageError('删除菜单需要 --force(不可撤销)');
   const { data } = await menuRequest(client, 'DELETE', `${MENUS}/${Number(id)}`, { query: { force: 'true' } });

package/lib/run.js

@@ -43,6 +43,14 @@ export async function dispatch(client, cfg, group, action, rest, flags) {
       case 'update':
       case 'edit':
         return cmd.updateContent(client, type, needFirst('update'), flags);
+      case 'import':
+        return cmd.updateContent(client, type, needFirst('import'), flags);
+      case 'export':
+        return cmd.exportContent(client, type, needFirst('export'), flags);
+      case 'publish':
+        return cmd.setContentStatus(client, type, needFirst('publish'), 'publish', flags);
+      case 'unpublish':
+        return cmd.setContentStatus(client, type, needFirst('unpublish'), 'draft', flags);
       case 'delete':
       case 'rm':
         return cmd.deleteContent(client, type, needFirst('delete'), flags);

package/lib/settings.js

@@ -1,7 +1,7 @@
 // 站点设置:读取 / 更新核心 /wp/v2/settings 端点。
 // flag 名(- 分隔)映射到 REST 字段(_ 分隔),数值字段自动转 Number。
 
-import { printJson, dry, parseJson, readJsonFile } from './util.js';
+import { printJson, dry, warn, parseJson, readJsonFile } from './util.js';
 import { UsageError } from './errors.js';
 
 const SETTINGS = '/wp-json/wp/v2/settings';
@@ -66,6 +66,7 @@ export async function updateSettings(client, flags) {
     throw new UsageError('没有可更新的字段(--title/--description/--timezone/--posts-per-page/... 或 --data JSON)');
   }
 
+  warn('正在修改站点设置,会立即对全站生效', flags);
   if (flags['dry-run']) return dry(`更新站点设置 ${JSON.stringify(body)}`);
 
   const { data } = await client.request('POST', SETTINGS, { body });

package/lib/spec.js

@@ -2,7 +2,8 @@
 // help / `wpops commands --json` / --all 写操作护栏(isMutation)/ shell 补全 全部由这里派生,
 // 避免文档与代码各写一份、越走越偏。
 
-const CONTENT_MUT = ['create', 'new', 'update', 'edit', 'delete', 'rm'];
+const CONTENT_MUT = ['create', 'new', 'update', 'edit', 'import', 'publish', 'unpublish', 'delete', 'rm'];
+const TERM_MUT = ['create', 'new', 'update', 'edit', 'delete', 'rm'];
 const ITEM_MUT = ['create', 'new', 'update', 'edit', 'delete', 'rm'];
 
 /** 全局开关(所有组通用)。 */
@@ -71,33 +72,46 @@ export const GROUPS = [
   },
 
   {
-    name: 'posts', summary: '文章:增删改查', aliases: ['post'],
-    actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
+    name: 'posts', summary: '文章:增删改查/发布/导出', aliases: ['post'],
+    actions: {
+      list: '列出', get: '查看', create: '新建(默认草稿)', update: '更新',
+      import: '从文件导入正文', export: '导出正文到文件',
+      publish: '发布', unpublish: '下线为草稿', delete: '删除',
+    },
     mutation: CONTENT_MUT,
     usage: [
       'wpops posts list [--per-page 10] [--page 2] [--status draft] [--search 词] [--categories 1,2]',
       'wpops posts get <id>',
-      'wpops posts create --title "标题" --content "正文" [--status draft] [--categories 1,2] [--tags 3]',
-      'wpops posts create --title "标题" --from-file ./post.md',
-      'wpops posts update <id> --title "新标题" [--status publish] [--featured-media 44]',
-      'wpops posts delete <id> [--force]        # 默认进回收站',
+      'wpops posts create --title "标题" --content "正文"        # 默认草稿,不会直接上线',
+      'wpops posts export <id> --file post.html                 # 导出后本地改排版',
+      'wpops posts update <id> --from-file post.html --dry-run  # 先预览,再真正应用',
+      'wpops posts publish <id> · wpops posts unpublish <id>',
+      'wpops posts delete <id> [--force]                        # 默认进回收站',
     ],
-    flags: ['--title', '--content', '--from-file', '--status', '--slug', '--excerpt',
+    flags: ['--title', '--content', '--from-file', '--file', '--status', '--slug', '--excerpt',
       '--featured-media', '--author', '--date', '--categories', '--tags',
       '--per-page', '--page', '--search', '--orderby', '--order'],
   },
   {
-    name: 'pages', summary: '页面:增删改查', aliases: ['page'],
-    actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
+    name: 'pages', summary: '页面:增删改查/发布/导出', aliases: ['page'],
+    actions: {
+      list: '列出', get: '查看', create: '新建(默认草稿)', update: '更新',
+      import: '从文件导入正文', export: '导出正文到文件',
+      publish: '发布', unpublish: '下线为草稿', delete: '删除',
+    },
     mutation: CONTENT_MUT,
-    usage: ['wpops pages ...                            # 与 posts 同'],
+    usage: ['wpops pages ...                             # 与 posts 同'],
     flags: ['同 posts'],
   },
   {
     name: 'content', summary: '任意 show_in_rest 的 CPT(按 rest_base)', local: false,
-    actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
+    actions: {
+      list: '列出', get: '查看', create: '新建(默认草稿)', update: '更新',
+      import: '从文件导入正文', export: '导出正文到文件',
+      publish: '发布', unpublish: '下线为草稿', delete: '删除',
+    },
     mutation: CONTENT_MUT,
-    usage: ['wpops content list books', 'wpops content get books 12', 'wpops content create books --title "..."'],
+    usage: ['wpops content list books', 'wpops content export books 12 --file book.html', 'wpops content publish books 12'],
     flags: ['同 posts;第一个位置参数是 rest_base'],
   },
   {
@@ -121,21 +135,21 @@ export const GROUPS = [
   {
     name: 'categories', summary: '分类:增删改查', aliases: ['category'],
     actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
-    mutation: CONTENT_MUT,
+    mutation: TERM_MUT,
     usage: ['wpops categories create --name "新分类" [--slug x] [--parent 3]', 'wpops categories delete <id> --force'],
     flags: ['--name', '--slug', '--parent', '--description'],
   },
   {
     name: 'tags', summary: '标签:增删改查', aliases: ['tag'],
     actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
-    mutation: CONTENT_MUT,
+    mutation: TERM_MUT,
     usage: ['wpops tags ...                               # 与 categories 同'],
     flags: ['--name', '--slug', '--parent', '--description'],
   },
   {
     name: 'terms', summary: '任意 show_in_rest 的自定义分类法(按 rest_base)', local: false,
     actions: { list: '列出', get: '查看', create: '新建', update: '更新', delete: '删除' },
-    mutation: CONTENT_MUT,
+    mutation: TERM_MUT,
     usage: ['wpops terms list genres', 'wpops terms create genres --name 科幻'],
     flags: ['同 categories;第一个位置参数是 rest_base'],
   },

package/lib/util.js

@@ -21,6 +21,12 @@ function dry(message) {
   console.log(`[dry-run] ${message}`);
 }
 
+/** 非阻断风险提示(stderr);--yes 或 --quiet 时静默。 */
+function warn(message, flags = {}) {
+  if (flags.quiet || flags.yes) return;
+  console.error(`⚠ ${message}`);
+}
+
 /** 把 flags 中的指定键转成 REST 查询参数(- 转 _)。 */
 function pick(flags, keys) {
   const query = {};
@@ -139,5 +145,5 @@ export async function listRequest(client, path, query, flags = {}, request) {
   return { data, total: headers.get('x-wp-total'), totalPages: headers.get('x-wp-totalpages') };
 }
 
-export { stripTags, dry, pick, printJson, project, toCsv, toTable };
+export { stripTags, dry, warn, pick, printJson, project, toCsv, toTable };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wpops",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "WordPress REST operations toolkit — manage posts, pages, media, menus, comments, users, custom types, revisions, blocks, templates, widgets, settings and plugins from the CLI. Multi-site, safety-first, zero dependencies.",
   "license": "MIT",
   "author": "qnnp",

package/skills/wpops/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wpops
 description: Use when managing a WordPress site through wpops, the zero-dependency REST CLI (npm package `wpops`, command `wpops`) — posts, pages, media, menus, comments, users, custom post types, search, settings, revisions, blocks, block-theme navigation/templates/global styles, widgets, application passwords, plugins, themes, Abilities, site health, or batch requests; configuring a site; or operating across multiple configured sites. Covers the required safe workflow (doctor first, --dry-run before writes, --all needs --yes) and the REST capability boundary. Prefer wpops over hand-written curl or raw HTTP for any WordPress task.
+license: MIT
 ---
 
 # wpops —— WordPress REST 操作
@@ -24,11 +25,12 @@ description: Use when managing a WordPress site through wpops, the zero-dependen
 ## 安全流程(必须遵守)
 1. 首次操作某站先跑 `wpops doctor`(检查连接与权限;失败返回非 0)。
 2. 任何写操作先加 `--dry-run` 预览(`delete` 的预览不需要 `--force`;真正删除才加 `--force`)。
-3. `--all` 的**写操作必须加 `--yes`**,否则会被拒绝。
-4. 需要程序化解析输出时加 `--json`;要投影/表格用 `--fields a,b` / `--csv` / `--table`。
-5. 应用密码绝不写进命令、日志或对话。
-6. 破坏性操作(`delete --force`、分类/用户/菜单项/插件删除)先确认目标存在且正确。
-7. 退出码:`0` 成功;`2` 用法/参数错误(stderr 会给用法与 `--help` 提示);`1` 运行期错误(HTTP/网络/配置)。脚本据此判断成败,不要只看有没有输出。
+3. **内容默认草稿**:创建不带 `--status` 即草稿,不会直接上线;发布用显式 `publish`(`unpublish` 下线)。修改已发布内容会先提示并给出 `wpops revisions restore` 回滚;`--yes` 可静默。改版式的安全流程:先建**草稿副本**预览(命令回显后台编辑链接),满意后再 `update` 原页。
+4. `--all` 的**写操作必须加 `--yes`**,否则会被拒绝。
+5. 需要程序化解析输出时加 `--json`;要投影/表格用 `--fields a,b` / `--csv` / `--table`。
+6. 应用密码绝不写进命令、日志或对话。
+7. 破坏性操作(`delete --force`、分类/用户/菜单项/插件删除)先确认目标存在且正确。页面构建器(Elementor 等)布局存在插件 meta,不要用 REST 改其 `post_content`。
+8. 退出码:`0` 成功;`2` 用法/参数错误(stderr 会给用法与 `--help` 提示);`1` 运行期错误(HTTP/网络/配置)。脚本据此判断成败,不要只看有没有输出。
 
 ## 现查现用(不要背细节)
 - `wpops <组> --help`、`wpops help <组> [动作]` — 该组动作与参数(**首选**)。
@@ -41,7 +43,7 @@ description: Use when managing a WordPress site through wpops, the zero-dependen
 内置:`doctor`(连接体检) · `me`(当前用户) · `setup`(配置站点) · `sites`(站点档案) · `install-skill` · `completion` · `commands`(命令清单)。
 
 内容与结构:
-- `posts` / `pages` — 文章/页面增删改查。
+- `posts` / `pages` — 文章/页面增删改查;**默认草稿**、`publish`/`unpublish`、`export`/`import`(改版式)、`--dry-run` 预览。
 - `content <rest_base>` / `terms <rest_base>` — 任意 `show_in_rest` 的 CPT / 自定义分类。
 - `media` — 媒体列出/上传/URL 导入(`sideload`)/图像编辑(`edit-image` 裁剪旋转)/更新/删除。
 - `categories` / `tags` — 分类/标签。