wpops 0.1.0 → 0.2.0

package/lib/commands.js

@@ -2,7 +2,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { loadEnv, configHome } from './env.js';
-import { buildConfig, createClient } from './client.js';
+import { buildConfig, createClient, WpError } from './client.js';
+import { stripTags, printJson, dry, pick, listRequest, parseJson, readJsonFile } from './util.js';
+import { UsageError } from './errors.js';
 
 const CONTENT = {
   posts: '/wp-json/wp/v2/posts',
@@ -14,21 +16,20 @@ const TAX = {
   tags: '/wp-json/wp/v2/tags',
 };
 
-const MEDIA = '/wp-json/wp/v2/media';
-const COMMENTS = '/wp-json/wp/v2/comments';
-const USERS = '/wp-json/wp/v2/users';
-
-function stripTags(html = '') {
-  return String(html).replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+/** 内置类型走映射;其余按 rest_base 直接拼,支持任意 show_in_rest 的 CPT。 */
+function contentPath(type) {
+  return CONTENT[type] || `/wp-json/wp/v2/${String(type).replace(/^\/+/, '')}`;
 }
 
-function printJson(value) {
-  console.log(JSON.stringify(value, null, 2));
+function taxPath(tax) {
+  return TAX[tax] || `/wp-json/wp/v2/${String(tax).replace(/^\/+/, '')}`;
 }
 
-function dry(message) {
-  console.log(`[dry-run] ${message}`);
-}
+const MEDIA = '/wp-json/wp/v2/media';
+const COMMENTS = '/wp-json/wp/v2/comments';
+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) {
   if (flags.json) return printJson(data);
@@ -36,17 +37,6 @@ function printItem(data, flags) {
   if (data.link) console.log(`  ${data.link}`);
 }
 
-/** 把 flags 中的指定键转成 REST 查询参数(- 转 _)。 */
-function pick(flags, keys) {
-  const query = {};
-  for (const key of keys) {
-    const value = flags[key];
-    if (value === undefined || value === null || value === false) continue;
-    query[key.replace(/-/g, '_')] = String(value);
-  }
-  return query;
-}
-
 // ------------------------------------------------------------------ doctor
 
 export async function doctor(client, cfg, flags) {
@@ -216,10 +206,8 @@ export async function listContent(client, type, flags) {
     context: flags.context,
     ...pick(flags, CONTENT_FILTERS[type] || []),
   };
-  const { data, headers } = await client.request('GET', CONTENT[type], { query });
+  const { data, total, totalPages } = await listRequest(client, contentPath(type), query, flags);
   if (flags.json) return printJson(data);
-  const total = headers.get('x-wp-total');
-  const totalPages = headers.get('x-wp-totalpages');
   console.log(
     `${type} 共 ${total ?? '?'} 条 / ${totalPages ?? '?'} 页;第 ${page} 页${totalPages ? `/${totalPages}` : ''},本页 ${data.length} 条:`,
   );
@@ -232,7 +220,7 @@ export async function listContent(client, type, flags) {
 }
 
 export async function getContent(client, type, id, flags) {
-  const { data } = await client.request('GET', `${CONTENT[type]}/${Number(id)}`, {
+  const { data } = await client.request('GET', `${contentPath(type)}/${Number(id)}`, {
     query: { context: flags.context || 'edit' },
   });
   if (flags.json) return printJson(data);
@@ -265,24 +253,24 @@ function contentBody(flags) {
 export async function createContent(client, type, flags) {
   const body = contentBody(flags);
   if (body.title === undefined && body.content === undefined) {
-    throw new Error('至少需要 --title 或 --content/--from-file');
+    throw new UsageError('至少需要 --title 或 --content/--from-file');
   }
   if (flags['dry-run']) return dry(`创建 ${type} ${JSON.stringify(body)}`);
-  const { data } = await client.request('POST', CONTENT[type], { body });
+  const { data } = await client.request('POST', contentPath(type), { body });
   printItem(data, flags);
 }
 
 export async function updateContent(client, type, id, flags) {
   const body = contentBody(flags);
-  if (!Object.keys(body).length) throw new Error('没有可更新的字段');
+  if (!Object.keys(body).length) throw new UsageError('没有可更新的字段');
   if (flags['dry-run']) return dry(`更新 ${type} #${id} ${JSON.stringify(body)}`);
-  const { data } = await client.request('POST', `${CONTENT[type]}/${Number(id)}`, { body });
+  const { data } = await client.request('POST', `${contentPath(type)}/${Number(id)}`, { body });
   printItem(data, flags);
 }
 
 export async function deleteContent(client, type, id, flags) {
   if (flags['dry-run']) return dry(`删除 ${type} #${id}${flags.force ? '(彻底)' : '(回收站)'}`);
-  const { data } = await client.request('DELETE', `${CONTENT[type]}/${Number(id)}`, {
+  const { data } = await client.request('DELETE', `${contentPath(type)}/${Number(id)}`, {
     query: { force: flags.force ? 'true' : undefined },
   });
   if (flags.json) return printJson(data);
@@ -299,10 +287,8 @@ export async function listMedia(client, flags) {
     page,
     ...pick(flags, ['media_type', 'mime_type', 'parent', 'author', 'after', 'before', 'orderby', 'order', 'offset', 'include', 'exclude']),
   };
-  const { data, headers } = await client.request('GET', MEDIA, { query });
+  const { data, total, totalPages } = await listRequest(client, MEDIA, query, flags);
   if (flags.json) return printJson(data);
-  const total = headers.get('x-wp-total');
-  const totalPages = headers.get('x-wp-totalpages');
   console.log(
     `媒体共 ${total ?? '?'} 项 / ${totalPages ?? '?'} 页;第 ${page} 页${totalPages ? `/${totalPages}` : ''},本页 ${data.length} 项:`,
   );
@@ -344,7 +330,7 @@ export async function updateMedia(client, id, flags) {
   if (flags.description !== undefined) body.description = String(flags.description);
   if (flags.post !== undefined) body.post = Number(flags.post);
   if (!Object.keys(body).length) {
-    throw new Error('没有可更新的字段(--title/--alt/--caption/--description/--post)');
+    throw new UsageError('没有可更新的字段(--title/--alt/--caption/--description/--post)');
   }
   if (flags['dry-run']) return dry(`更新媒体 #${id} ${JSON.stringify(body)}`);
   const { data } = await client.request('POST', `${MEDIA}/${Number(id)}`, { body });
@@ -352,6 +338,56 @@ export async function updateMedia(client, id, flags) {
   console.log(`✓ 已更新媒体 #${data.id}`);
 }
 
+/** 图像编辑(裁剪/旋转),POST /media/<id>/edit。缺 --src 时自动取当前 source_url。 */
+export async function editMediaImage(client, id, flags) {
+  const body = {};
+  if (flags.src !== undefined) body.src = String(flags.src);
+  if (flags.rotation !== undefined) body.rotation = Number(flags.rotation);
+  if (flags['dest-width'] !== undefined) body.width = Number(flags['dest-width']);
+  if (flags['dest-height'] !== undefined) body.height = Number(flags['dest-height']);
+  if (flags.x !== undefined) body.x = Number(flags.x);
+  if (flags.y !== undefined) body.y = Number(flags.y);
+  const modifiers = [];
+  if (flags.crop) modifiers.push('crop');
+  if (flags.modifiers !== undefined) {
+    modifiers.push(...String(flags.modifiers).split(',').map((s) => s.trim()).filter(Boolean));
+  }
+  if (modifiers.length) body.modifiers = modifiers;
+  if (flags.title !== undefined) body.title = String(flags.title);
+  if (flags.alt !== undefined) body.alt_text = String(flags.alt);
+  if (flags.caption !== undefined) body.caption = String(flags.caption);
+  if (flags.description !== undefined) body.description = String(flags.description);
+  if (flags.post !== undefined) body.post = Number(flags.post);
+  if (!Object.keys(body).length) {
+    throw new UsageError('图像编辑需要至少一个参数(--rotation/--crop/--x/--y/--dest-width/--dest-height/--modifiers/--src/...)');
+  }
+  if (flags['dry-run']) return dry(`编辑媒体 #${id} ${JSON.stringify(body)}`);
+  if (body.src === undefined) {
+    const { data } = await client.request('GET', `${MEDIA}/${Number(id)}`, { query: { context: 'edit' } });
+    body.src = data.source_url;
+  }
+  if (!body.src) throw new UsageError('无法确定图片来源,请显式传 --src <url>');
+  const { data } = await client.request('POST', `${MEDIA}/${Number(id)}/edit`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已编辑媒体 #${data.id}  ${data.source_url || ''}`);
+}
+
+/** 从 URL 导入媒体:sideload,POST /media(带 url)。 */
+export async function sideloadMedia(client, flags) {
+  if (flags.url === undefined) throw new UsageError('media sideload 需要 --url <图片地址>');
+  const body = { url: String(flags.url) };
+  if (flags.title !== undefined) body.title = String(flags.title);
+  if (flags.alt !== undefined) body.alt_text = String(flags.alt);
+  if (flags.caption !== undefined) body.caption = String(flags.caption);
+  if (flags.description !== undefined) body.description = String(flags.description);
+  if (flags.slug !== undefined) body.slug = String(flags.slug);
+  if (flags.post !== undefined) body.post = Number(flags.post);
+  if (flags['dry-run']) return dry(`从 URL 导入媒体 ${body.url}`);
+  const { data } = await client.request('POST', MEDIA, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已导入媒体 #${data.id}  ${data.source_url || ''}`);
+}
+
 export async function deleteMedia(client, id, flags) {
   if (flags['dry-run']) return dry(`删除媒体 #${id}${flags.force ? '(彻底)' : '(回收站)'}`);
   const { data } = await client.request('DELETE', `${MEDIA}/${Number(id)}`, {
@@ -392,6 +428,14 @@ export async function setPluginStatus(client, plugin, activate, flags) {
   console.log(`✓ ${data.name} → ${data.status === 'active' ? '已启用' : '已停用'}`);
 }
 
+export async function deletePlugin(client, plugin, flags) {
+  if (flags['dry-run']) return dry(`删除插件 ${plugin}`);
+  if (!flags.force) throw new UsageError('删除插件需要 --force(不可撤销)');
+  const { data } = await client.request('DELETE', `/wp-json/wp/v2/plugins/${encodeURIComponent(plugin)}`);
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除插件 ${plugin}` : `? 插件 ${plugin} 未删除`);
+}
+
 // ------------------------------------------------------------------ themes
 
 export async function listThemes(client, flags) {
@@ -415,26 +459,25 @@ export async function activateTheme(client, stylesheet, flags) {
 // ------------------------------------------------------------------ taxonomy
 
 export async function listTaxonomy(client, tax, flags) {
-  const { data, headers } = await client.request('GET', TAX[tax], {
-    query: {
-      per_page: flags['per-page'] ?? 100,
-      page: flags.page,
-      search: flags.search,
-      orderby: flags.orderby,
-      order: flags.order,
-      parent: flags.parent,
-      hide_empty: flags['hide-empty'] ? 'true' : 'false',
-    },
-  });
+  const query = {
+    per_page: flags['per-page'] ?? 100,
+    page: flags.page,
+    search: flags.search,
+    orderby: flags.orderby,
+    order: flags.order,
+    parent: flags.parent,
+    hide_empty: flags['hide-empty'] ? 'true' : 'false',
+  };
+  const { data, total } = await listRequest(client, taxPath(tax), query, flags);
   if (flags.json) return printJson(data);
-  console.log(`${tax} 共 ${headers.get('x-wp-total') ?? '?'} 个:`);
+  console.log(`${tax} 共 ${total ?? '?'} 个:`);
   for (const t of data) {
     console.log(`  #${t.id}  ${t.name}  (${t.count})  slug=${t.slug}${t.parent ? `  parent=#${t.parent}` : ''}`);
   }
 }
 
 export async function getTaxonomy(client, tax, id) {
-  const { data } = await client.request('GET', `${TAX[tax]}/${Number(id)}`);
+  const { data } = await client.request('GET', `${taxPath(tax)}/${Number(id)}`);
   printJson(data);
 }
 
@@ -449,42 +492,220 @@ function taxonomyBody(flags) {
 
 export async function createTaxonomy(client, tax, flags) {
   const body = taxonomyBody(flags);
-  if (body.name === undefined) throw new Error(`创建 ${tax} 需要 --name`);
+  if (body.name === undefined) throw new UsageError(`创建 ${tax} 需要 --name`);
   if (flags['dry-run']) return dry(`创建 ${tax} ${JSON.stringify(body)}`);
-  const { data } = await client.request('POST', TAX[tax], { body });
+  const { data } = await client.request('POST', taxPath(tax), { body });
   if (flags.json) return printJson(data);
   console.log(`✓ 已创建 ${tax} #${data.id} ${data.name}`);
 }
 
 export async function updateTaxonomy(client, tax, id, flags) {
   const body = taxonomyBody(flags);
-  if (!Object.keys(body).length) throw new Error('没有可更新的字段(--name/--slug/--parent/--description)');
+  if (!Object.keys(body).length) throw new UsageError('没有可更新的字段(--name/--slug/--parent/--description)');
   if (flags['dry-run']) return dry(`更新 ${tax} #${id} ${JSON.stringify(body)}`);
-  const { data } = await client.request('POST', `${TAX[tax]}/${Number(id)}`, { body });
+  const { data } = await client.request('POST', `${taxPath(tax)}/${Number(id)}`, { body });
   if (flags.json) return printJson(data);
   console.log(`✓ 已更新 ${tax} #${data.id} ${data.name}`);
 }
 
 export async function deleteTaxonomy(client, tax, id, flags) {
-  if (!flags.force) throw new Error(`删除 ${tax} 需要 --force(不可撤销)`);
   if (flags['dry-run']) return dry(`删除 ${tax} #${id}`);
-  const { data } = await client.request('DELETE', `${TAX[tax]}/${Number(id)}`, { query: { force: 'true' } });
+  if (!flags.force) throw new UsageError(`删除 ${tax} 需要 --force(不可撤销)`);
+  const { data } = await client.request('DELETE', `${taxPath(tax)}/${Number(id)}`, { query: { force: 'true' } });
   if (flags.json) return printJson(data);
   console.log(data.deleted ? `✓ 已删除 ${tax} #${id}` : `? ${tax} #${id} 未删除`);
 }
 
+// ------------------------------------------------------------------ menus
+
+const MENU_PLUGIN_HINT =
+  '菜单接口由插件提供(WordPress 核心 REST 没有 /menus、/menu-items);请确认站点已装并启用对应插件。';
+
+/** 菜单端点请求:路由不存在时补充"需插件"的提示,便于排障。 */
+async function menuRequest(client, method, path, opts) {
+  try {
+    return await client.request(method, path, opts);
+  } catch (err) {
+    if (err?.code === 'rest_no_route') {
+      throw new WpError(`${err.message} —— ${MENU_PLUGIN_HINT}`, {
+        status: err.status,
+        code: err.code,
+        data: err.data,
+        method: err.method,
+        path: err.path,
+      });
+    }
+    throw err;
+  }
+}
+
+export async function listMenus(client, flags) {
+  const { data, headers } = await menuRequest(client, 'GET', MENUS, {
+    query: { per_page: flags['per-page'] ?? 100, page: flags.page },
+  });
+  if (flags.json) return printJson(data);
+  console.log(`菜单共 ${headers.get('x-wp-total') ?? data.length} 个:`);
+  for (const m of data) {
+    console.log(`  #${m.id}  ${m.name}  slug=${m.slug}  locations=${(m.locations || []).join(',') || '—'}`);
+  }
+}
+
+export async function getMenu(client, id, flags) {
+  const { data } = await menuRequest(client, 'GET', `${MENUS}/${Number(id)}`);
+  if (flags.json) return printJson(data);
+  console.log(`#${data.id}  ${data.name}  slug=${data.slug}`);
+  console.log(`  位置:${(data.locations || []).join(', ') || '—'}`);
+  console.log(`  自动添加:${data.auto_add ? '是' : '否'}`);
+  if (data.description) console.log(`  描述:${data.description}`);
+}
+
+/** 菜单字段转请求体(locations/auto_add 用于给菜单绑定主题位置)。 */
+function menuBody(flags) {
+  const body = {};
+  if (flags.name !== undefined) body.name = String(flags.name);
+  if (flags.slug !== undefined) body.slug = String(flags.slug);
+  if (flags.description !== undefined) body.description = String(flags.description);
+  if (flags.locations !== undefined) {
+    body.locations = String(flags.locations).split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  if (flags['auto-add'] !== undefined) body.auto_add = Boolean(flags['auto-add']);
+  return body;
+}
+
+export async function createMenu(client, flags) {
+  const body = menuBody(flags);
+  if (body.name === undefined) throw new UsageError('创建菜单需要 --name');
+  if (flags['dry-run']) return dry(`创建菜单 ${JSON.stringify(body)}`);
+  const { data } = await menuRequest(client, 'POST', MENUS, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已创建菜单 #${data.id} ${data.name}`);
+}
+
+export async function updateMenu(client, id, flags) {
+  const body = menuBody(flags);
+  if (!Object.keys(body).length) {
+    throw new UsageError('没有可更新的字段(--name/--slug/--description/--locations/--auto-add)');
+  }
+  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);
+  console.log(`✓ 已更新菜单 #${data.id} ${data.name}  位置:${(data.locations || []).join(',') || '—'}`);
+}
+
+export async function deleteMenu(client, id, 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' } });
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除菜单 #${id}` : `? 菜单 #${id} 未删除`);
+}
+
+/** 把 flags 中的菜单项字段转成 REST 请求体(注意数值/数组类型)。 */
+function menuItemBody(flags) {
+  const body = {};
+  if (flags.title !== undefined) body.title = String(flags.title);
+  if (flags.url !== undefined) body.url = String(flags.url);
+  if (flags.menus !== undefined) body.menus = Number(flags.menus);
+  if (flags['menu-order'] !== undefined) body.menu_order = Number(flags['menu-order']);
+  if (flags.parent !== undefined) body.parent = Number(flags.parent);
+  if (flags.status !== undefined) body.status = String(flags.status);
+  if (flags.type !== undefined) body.type = String(flags.type);
+  if (flags.object !== undefined) body.object = String(flags.object);
+  if (flags['object-id'] !== undefined) body.object_id = Number(flags['object-id']);
+  if (flags.target !== undefined) body.target = String(flags.target);
+  if (flags.classes !== undefined) {
+    body.classes = String(flags.classes).split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  if (flags.description !== undefined) body.description = String(flags.description);
+  if (flags['attr-title'] !== undefined) body.attr_title = String(flags['attr-title']);
+  if (flags.xfn !== undefined) body.xfn = String(flags.xfn).split(',').map((s) => s.trim()).filter(Boolean);
+  return body;
+}
+
+export async function listMenuItems(client, flags) {
+  const perPage = Number(flags['per-page'] ?? 100) || 100;
+  const page = Number(flags.page ?? 1) || 1;
+  const query = {
+    per_page: perPage,
+    page,
+    ...pick(flags, ['menus', 'search', 'status', 'orderby', 'order', 'menu-order']),
+  };
+  const { data, total, totalPages } = await listRequest(
+    client,
+    MENU_ITEMS,
+    query,
+    flags,
+    (method, path, opts) => menuRequest(client, method, path, opts),
+  );
+  if (flags.json) return printJson(data);
+  console.log(
+    `菜单项共 ${total ?? '?'} 项 / ${totalPages ?? '?'} 页;第 ${page} 页${totalPages ? `/${totalPages}` : ''},本页 ${data.length} 项:`,
+  );
+  for (const item of data) {
+    const title = stripTags(item.title?.rendered || '(无标题)');
+    console.log(
+      `  #${item.id}  [${item.status}]  order=${item.menu_order}  parent=${item.parent}  ${item.type}/${item.object}  ${title}  ${item.url}`,
+    );
+  }
+  if (totalPages && page < Number(totalPages)) {
+    console.log(`  …下一页:wpops menu-items list --page ${page + 1} --per-page ${perPage}`);
+  }
+}
+
+export async function getMenuItem(client, id, flags) {
+  const { data } = await menuRequest(client, 'GET', `${MENU_ITEMS}/${Number(id)}`);
+  if (flags.json) return printJson(data);
+  console.log(`#${data.id}  [${data.status}]  ${stripTags(data.title?.rendered || '')}`);
+  console.log(`  顺序:${data.menu_order}  父级:#${data.parent}  类型:${data.type}/${data.object}  object_id=${data.object_id}`);
+  console.log(`  链接:${data.url}`);
+  if (data.attr_title) console.log(`  attr_title:${data.attr_title}`);
+  if (data.target) console.log(`  target:${data.target}`);
+  if (data.classes?.filter(Boolean).length) console.log(`  classes:${data.classes.filter(Boolean).join(',')}`);
+  if (data.description) console.log(`  描述:${data.description}`);
+}
+
+export async function createMenuItem(client, flags) {
+  const body = menuItemBody(flags);
+  if (body.title === undefined) throw new UsageError('创建菜单项需要 --title');
+  if (body.url === undefined && body.object === undefined) {
+    throw new UsageError('创建菜单项需要 --url(自定义链接)或 --object/--object-id(指向现有内容)');
+  }
+  if (flags['dry-run']) return dry(`创建菜单项 ${JSON.stringify(body)}`);
+  const { data } = await menuRequest(client, 'POST', MENU_ITEMS, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已创建菜单项 #${data.id} [${data.status}] ${stripTags(data.title?.rendered || '')}`);
+}
+
+export async function updateMenuItem(client, id, flags) {
+  const body = menuItemBody(flags);
+  if (!Object.keys(body).length) {
+    throw new UsageError('没有可更新的字段(--title/--url/--menus/--menu-order/--parent/--status/--type/--object/--object-id/--target/--classes/--description/--attr-title)');
+  }
+  if (flags['dry-run']) return dry(`更新菜单项 #${id} ${JSON.stringify(body)}`);
+  const { data } = await menuRequest(client, 'POST', `${MENU_ITEMS}/${Number(id)}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已更新菜单项 #${data.id} ${stripTags(data.title?.rendered || '')}`);
+}
+
+export async function deleteMenuItem(client, id, flags) {
+  if (flags['dry-run']) return dry(`删除菜单项 #${id}`);
+  if (!flags.force) throw new UsageError('删除菜单项需要 --force(不可撤销)');
+  const { data } = await menuRequest(client, 'DELETE', `${MENU_ITEMS}/${Number(id)}`, { query: { force: 'true' } });
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除菜单项 #${id}` : `? 菜单项 #${id} 未删除`);
+}
+
 // ------------------------------------------------------------------ comments
 
 export async function listComments(client, flags) {
-  const { data, headers } = await client.request('GET', COMMENTS, {
-    query: {
-      per_page: flags['per-page'] ?? 10,
-      page: flags.page,
-      ...pick(flags, ['post', 'status', 'search', 'author', 'orderby', 'order', 'type']),
-    },
-  });
+  const query = {
+    per_page: flags['per-page'] ?? 10,
+    page: flags.page,
+    ...pick(flags, ['post', 'status', 'search', 'author', 'orderby', 'order', 'type']),
+  };
+  const { data, total } = await listRequest(client, COMMENTS, query, flags);
   if (flags.json) return printJson(data);
-  console.log(`评论共 ${headers.get('x-wp-total') ?? '?'} 条,本页 ${data.length}:`);
+  console.log(`评论共 ${total ?? '?'} 条,本页 ${data.length}:`);
   for (const c of data) {
     console.log(`  #${c.id}  [${c.status}]  post#${c.post}  ${stripTags(c.author_name || '')}: ${stripTags(c.content?.rendered || '')}`);
   }
@@ -495,12 +716,29 @@ export async function getComment(client, id) {
   printJson(data);
 }
 
+export async function createComment(client, flags) {
+  const post = flags.post ?? flags['post-id'];
+  if (post === undefined) throw new UsageError('创建评论需要 --post <id>');
+  const body = { post: Number(post) };
+  if (flags['from-file'] !== undefined) body.content = readFileSync(String(flags['from-file']), 'utf8');
+  else if (flags.content !== undefined) body.content = String(flags.content);
+  if (body.content === undefined) throw new UsageError('创建评论需要 --content 或 --from-file');
+  if (flags['author-name'] !== undefined) body.author_name = String(flags['author-name']);
+  if (flags['author-email'] !== undefined) body.author_email = String(flags['author-email']);
+  if (flags.parent !== undefined) body.parent = Number(flags.parent);
+  if (flags.status !== undefined) body.status = String(flags.status);
+  if (flags['dry-run']) return dry(`创建评论 ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', COMMENTS, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已创建评论 #${data.id} post#${data.post} [${data.status}]`);
+}
+
 export async function updateComment(client, id, flags) {
   const body = {};
   if (flags.status !== undefined) body.status = String(flags.status);
   if (flags.content !== undefined) body.content = String(flags.content);
   if (!Object.keys(body).length) {
-    throw new Error('没有可更新的字段(--status approve|hold|spam|trash / --content)');
+    throw new UsageError('没有可更新的字段(--status approve|hold|spam|trash / --content)');
   }
   if (flags['dry-run']) return dry(`更新评论 #${id} ${JSON.stringify(body)}`);
   const { data } = await client.request('POST', `${COMMENTS}/${Number(id)}`, { body });
@@ -520,16 +758,15 @@ export async function deleteComment(client, id, flags) {
 // ------------------------------------------------------------------ users
 
 export async function listUsers(client, flags) {
-  const { data, headers } = await client.request('GET', USERS, {
-    query: {
-      per_page: flags['per-page'] ?? 10,
-      page: flags.page,
-      context: 'edit',
-      ...pick(flags, ['search', 'roles', 'orderby', 'order', 'who']),
-    },
-  });
+  const query = {
+    per_page: flags['per-page'] ?? 10,
+    page: flags.page,
+    context: 'edit',
+    ...pick(flags, ['search', 'roles', 'orderby', 'order', 'who']),
+  };
+  const { data, total } = await listRequest(client, USERS, query, flags);
   if (flags.json) return printJson(data);
-  console.log(`用户共 ${headers.get('x-wp-total') ?? '?'} 个,本页 ${data.length}:`);
+  console.log(`用户共 ${total ?? '?'} 个,本页 ${data.length}:`);
   for (const u of data) {
     console.log(`  #${u.id}  ${u.name} (@${u.slug})  ${(u.roles || []).join(',')}  ${u.email || ''}`);
   }
@@ -541,8 +778,8 @@ export async function getUser(client, id) {
 }
 
 export async function createUser(client, flags) {
-  if (flags.username === undefined) throw new Error('创建用户需要 --username');
-  if (flags.email === undefined) throw new Error('创建用户需要 --email');
+  if (flags.username === undefined) throw new UsageError('创建用户需要 --username');
+  if (flags.email === undefined) throw new UsageError('创建用户需要 --email');
   const body = { username: String(flags.username), email: String(flags.email) };
   if (flags.password !== undefined) body.password = String(flags.password);
   if (flags.name !== undefined) body.name = String(flags.name);
@@ -559,7 +796,7 @@ export async function updateUser(client, id, flags) {
     if (flags[key] !== undefined) body[key] = String(flags[key]);
   }
   if (flags.role !== undefined) body.roles = String(flags.role).split(',').map((s) => s.trim()).filter(Boolean);
-  if (!Object.keys(body).length) throw new Error('没有可更新的字段(--name/--email/--password/--role/...)');
+  if (!Object.keys(body).length) throw new UsageError('没有可更新的字段(--name/--email/--password/--role/...)');
   if (flags['dry-run']) return dry(`更新用户 #${id} ${JSON.stringify({ ...body, password: body.password ? '***' : undefined })}`);
   const { data } = await client.request('POST', `${USERS}/${Number(id)}`, { body });
   if (flags.json) return printJson(data);
@@ -567,8 +804,8 @@ export async function updateUser(client, id, flags) {
 }
 
 export async function deleteUser(client, id, flags) {
-  if (!flags.force) throw new Error('删除用户需要 --force(不可撤销)');
   if (flags['dry-run']) return dry(`删除用户 #${id}${flags.reassign ? `(内容转交 #${flags.reassign})` : ''}`);
+  if (!flags.force) throw new UsageError('删除用户需要 --force(不可撤销)');
   const { data } = await client.request('DELETE', `${USERS}/${Number(id)}`, {
     query: { force: 'true', reassign: flags.reassign },
   });
@@ -581,8 +818,11 @@ export async function deleteUser(client, id, flags) {
 export async function raw(client, method, path, flags) {
   const upper = String(method).toUpperCase();
   let body;
-  if (flags.data !== undefined) body = JSON.parse(String(flags.data));
-  else if (flags['data-file'] !== undefined) body = JSON.parse(readFileSync(String(flags['data-file']), 'utf8'));
+  if (flags.data !== undefined) body = parseJson(flags.data);
+  else if (flags['data-file'] !== undefined) body = readJsonFile(flags['data-file']);
+  if (body !== undefined && ['GET', 'HEAD'].includes(upper)) {
+    throw new UsageError(`${upper} 请求不能带 --data(--data 仅用于写操作)`, { group: 'raw', action: upper });
+  }
 
   if (flags['dry-run'] && !['GET', 'HEAD', 'OPTIONS'].includes(upper)) {
     return dry(`${upper} ${path}${body !== undefined ? ` ${JSON.stringify(body)}` : ''}`);
@@ -643,7 +883,7 @@ function promptHidden(query) {
 export async function setup(flags) {
   const tty = Boolean(process.stdin.isTTY);
   const need = (what) => {
-    if (!tty) throw new Error(`非交互模式请提供 ${what}`);
+    if (!tty) throw new UsageError(`非交互模式请提供 ${what}`);
   };
 
   let url = flags.url;
@@ -652,7 +892,7 @@ export async function setup(flags) {
     url = await promptLine('站点 URL(https://...):');
   }
   url = String(url).replace(/\/+$/, '');
-  if (!/^https:\/\//i.test(url)) throw new Error('URL 必须以 https:// 开头');
+  if (!/^https:\/\//i.test(url)) throw new UsageError('URL 必须以 https:// 开头');
 
   let user = flags.user;
   if (!user) {
@@ -665,7 +905,7 @@ export async function setup(flags) {
     need('--password');
     password = await promptHidden('应用密码(输入不回显):');
   }
-  if (!password) throw new Error('应用密码为空');
+  if (!password) throw new UsageError('应用密码为空');
 
   const defaultName = (() => {
     try {
@@ -685,7 +925,7 @@ export async function setup(flags) {
   mkdirSync(dir, { recursive: true });
   const file = join(dir, `${name}.env`);
   if (existsSync(file) && !flags.force) {
-    throw new Error(`已存在 ${file};要覆盖请加 --force`);
+    throw new UsageError(`已存在 ${file};要覆盖请加 --force`);
   }
 
   const content = [

package/lib/env.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { UsageError } from './errors.js';
 
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -44,7 +45,7 @@ export function parseDotenv(text) {
 
 function assertSiteName(site) {
   if (site && !/^[A-Za-z0-9._-]+$/.test(site)) {
-    throw new Error(`非法站点名 "${site}":只允许字母、数字、点、下划线、连字符`);
+    throw new UsageError(`非法站点名 "${site}":只允许字母、数字、点、下划线、连字符`);
   }
 }
 

package/lib/errors.js

@@ -0,0 +1,10 @@
+// 用法/参数错误:表示“命令调用方式不对”(缺参数、未知动作、缺少必填开关等),
+// 与运行期错误(HTTP/网络/配置)区分开,由 CLI 以退出码 2 处理并附带用法提示。
+export class UsageError extends Error {
+  constructor(message, meta = {}) {
+    super(message);
+    this.name = 'UsageError';
+    this.group = meta.group;
+    this.action = meta.action;
+  }
+}