wpops 0.1.0 → 0.2.0

package/lib/widgets.js

@@ -0,0 +1,93 @@
+// 小工具与边栏(/wp-json/wp/v2/widgets、/wp-json/wp/v2/sidebars)。
+import { printJson, dry, listRequest, parseJson, readJsonFile } from './util.js';
+import { UsageError } from './errors.js';
+
+const WIDGETS = '/wp-json/wp/v2/widgets';
+const SIDEBARS = '/wp-json/wp/v2/sidebars';
+
+/** 从 --instance / --from-file 解析小工具实例 JSON。 */
+function instanceBody(flags) {
+  if (flags['from-file'] !== undefined) return readJsonFile(flags['from-file']);
+  if (flags.instance !== undefined) return parseJson(flags.instance);
+  return undefined;
+}
+
+export async function listWidgets(client, flags) {
+  const query = {
+    per_page: flags['per-page'] ?? 100,
+    page: flags.page,
+    sidebar: flags.sidebar,
+  };
+  const { data, total } = await listRequest(client, WIDGETS, query, flags);
+  if (flags.json) return printJson(data);
+  console.log(`小工具 ${total ?? data.length} 个:`);
+  for (const w of data) {
+    console.log(`  ${w.id}  [${w.sidebar}]  ${w.type ?? ''}`);
+  }
+}
+
+export async function getWidget(client, id, flags) {
+  const { data } = await client.request('GET', `${WIDGETS}/${encodeURIComponent(id)}`);
+  if (flags.json) return printJson(data);
+  console.log(`${data.id}  [${data.sidebar}]  ${data.type ?? ''}`);
+  console.log(JSON.stringify(data.instance ?? {}, null, 2));
+}
+
+export async function createWidget(client, flags) {
+  if (flags.id === undefined || flags.sidebar === undefined) {
+    throw new UsageError('创建小工具需要 --id 与 --sidebar');
+  }
+  const body = { id: String(flags.id), sidebar: String(flags.sidebar) };
+  const instance = instanceBody(flags);
+  body.instance = instance === undefined ? {} : instance;
+  if (flags['dry-run']) return dry(`创建小工具 ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', WIDGETS, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已创建小工具 ${data.id} [${data.sidebar}]`);
+}
+
+export async function updateWidget(client, id, flags) {
+  const body = {};
+  if (flags.sidebar !== undefined) body.sidebar = String(flags.sidebar);
+  const instance = instanceBody(flags);
+  if (instance !== undefined) body.instance = instance;
+  if (!Object.keys(body).length) throw new UsageError('更新小工具需要 --sidebar 或 --instance/--from-file');
+  if (flags['dry-run']) return dry(`更新小工具 ${id} ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', `${WIDGETS}/${encodeURIComponent(id)}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已更新小工具 ${data.id} [${data.sidebar}]`);
+}
+
+export async function deleteWidget(client, id, flags) {
+  if (flags['dry-run']) return dry(`删除小工具 ${id}`);
+  if (!flags.force) throw new UsageError('删除小工具需要 --force(不可撤销)');
+  const { data } = await client.request('DELETE', `${WIDGETS}/${encodeURIComponent(id)}`);
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除小工具 ${id}` : `? 小工具 ${id} 未删除`);
+}
+
+export async function listSidebars(client, flags) {
+  const { data } = await client.request('GET', SIDEBARS);
+  if (flags.json) return printJson(data);
+  console.log(`边栏 ${data.length} 个:`);
+  for (const s of data) {
+    console.log(`  ${s.id}  ${s.name}  widgets=[${(s.widgets || []).join(',')}]`);
+  }
+}
+
+export async function getSidebar(client, id, flags) {
+  const { data } = await client.request('GET', `${SIDEBARS}/${encodeURIComponent(id)}`);
+  if (flags.json) return printJson(data);
+  console.log(`${data.id}  ${data.name}`);
+  console.log(`  widgets=[${(data.widgets || []).join(',')}]`);
+}
+
+export async function updateSidebar(client, id, flags) {
+  if (flags.widgets === undefined) throw new UsageError('更新边栏需要 --widgets a,b,c');
+  const widgets = String(flags.widgets).split(',').map((s) => s.trim()).filter(Boolean);
+  const body = { widgets };
+  if (flags['dry-run']) return dry(`更新边栏 ${id} ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', `${SIDEBARS}/${encodeURIComponent(id)}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已更新边栏 ${data.id} widgets=[${(data.widgets || []).join(',')}]`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wpops",
-  "version": "0.1.0",
-  "description": "WordPress REST operations toolkit — manage posts, pages, media, comments, users and plugins from the CLI. Multi-site, safety-first, zero dependencies.",
+  "version": "0.2.0",
+  "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",
   "type": "module",
@@ -24,6 +24,7 @@
     "cli",
     "application-password",
     "content-management",
+    "navigation-menu",
     "multi-site"
   ],
   "repository": {

package/skills/wpops/SKILL.md

@@ -1,54 +1,76 @@
 ---
 name: wpops
-description: Use when managing a WordPress site through wpops, the REST CLI (npm package `wpops`, command `wpops`) — listing/creating/updating/deleting posts, pages, media, categories, tags, comments, or users; installing/activating/deactivating plugins; switching themes; configuring a site; or running operations 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.
+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.
 ---
 
 # wpops —— WordPress REST 操作
 
 ## 何时用
-用户要管理 WordPress 站点的**内容**或**插件/主题**时,优先用 `wpops`,不要手搓 curl/HTTP 请求。
+用户要管理 WordPress 站点的**内容 / 结构 / 配置 / 插件主题**时,优先用 `wpops`,不要手搓 curl。
+本 skill 自洽,不依赖其他 skill;需要精确细节时**现查现用**(见下)。
 
 ## 安装与位置
-- 全局命令 `wpops`(`npm i -g wpops` 安装;其 postinstall 会顺带装好本 skill)。
-- 未安装时也可一次性运行:`npx wpops ...`。
-- 配置目录:默认是包目录下的 `sites/`;若设置了环境变量 `WPOPS_HOME`,则读 `$WPOPS_HOME/sites/`。
+- 全局命令 `wpops`(`npm i -g wpops` 安装;postinstall 会顺带装好本 skill)。
+- 未安装时也可:`npx wpops ...`。
+- 配置目录:默认包目录下的 `sites/`;设了 `WPOPS_HOME` 则读 `$WPOPS_HOME/sites/`。
 - 凭据:`sites/<名字>.env`。**不要读取、不要打印其中的应用密码。**
 - 首次配置:`wpops setup`(交互式写入凭据并自动体检)。
 
 ## 站点与多站
-- `wpops sites` — 列出已配置站点
-- `wpops -s <名字> ...` — 指定站点;只有一个站点时可省略 `-s`
-- `wpops --all ...` — 对所有站点批量执行
+- `wpops sites` — 列出已配置站点;`sites show <名>`(密码打码)、`sites rm`、`sites rename`。
+- `wpops -s <名字> ...` — 指定站点;只有一个站点时可省略;`-s a,b` 可指定多个。
+- `wpops --all ...` — 对所有站点批量执行。
 
 ## 安全流程(必须遵守)
 1. 首次操作某站先跑 `wpops doctor`(检查连接与权限;失败返回非 0)。
-2. 任何写操作先加 `--dry-run` 预览目标与内容。
+2. 任何写操作先加 `--dry-run` 预览(`delete` 的预览不需要 `--force`;真正删除才加 `--force`)。
 3. `--all` 的**写操作必须加 `--yes`**,否则会被拒绝。
-4. 需要程序化解析输出时加 `--json`。
+4. 需要程序化解析输出时加 `--json`;要投影/表格用 `--fields a,b` / `--csv` / `--table`。
 5. 应用密码绝不写进命令、日志或对话。
-6. 破坏性操作(`delete --force`、分类/用户删除)先确认目标存在且正确。
-
-## 常用命令
-```
-wpops doctor
-wpops setup
-wpops posts  list|get|create|update|delete   [--per-page N] [--page N] [--status s] [--search 词] [--orderby date] [--order desc] [--categories 1,2]
-wpops pages  ...                              # 同 posts
-wpops media  list|get|upload|update|delete    [--alt "文本"]
-wpops categories list|create|update|delete ...
-wpops tags   list|create|update|delete ...
-wpops comments list|get|update|delete         [--status hold|approved|spam|trash]
-wpops users  list|get|create|update|delete|me ...
-wpops plugins list|install <别名>|activate <plugin>|deactivate <plugin>
-wpops themes list|activate <stylesheet>
-wpops install-skill                           # 手动补装本 skill
-wpops raw <METHOD> <path> [--data JSON]       # 兜底:任意端点
-```
+6. 破坏性操作(`delete --force`、分类/用户/菜单项/插件删除)先确认目标存在且正确。
+7. 退出码:`0` 成功;`2` 用法/参数错误(stderr 会给用法与 `--help` 提示);`1` 运行期错误(HTTP/网络/配置)。脚本据此判断成败,不要只看有没有输出。
 
-## 能力边界(不要向用户承诺)
-- **REST 做不到**:插件/主题/核心**更新**、备份/还原、安全扫描、性能优化、文件系统操作。
-  → 这些需要 WP-CLI + SSH,或 MainWP。详见 skill `wp-wpcli-and-ops`。
-- **能做的**:文章/页面/媒体/分类/标签/评论/用户的增删改查、插件安装与启停、主题切换、连接与权限体检。
+## 现查现用(不要背细节)
+- `wpops <组> --help`、`wpops help <组> [动作]` — 该组动作与参数(**首选**)。
+- `wpops commands --json` — 机器可读清单:全部组、动作、是否写操作、别名。
+- `wpops raw GET /wp-json/` — 站点真实命名空间与路由。
+- `wpops raw OPTIONS <path>` — 某端点支持的字段、类型、枚举、必填。
+- 字段语义以 WordPress 官方 REST 文档为准。
+
+## 能力索引(组 → 一句话)
+内置:`doctor`(连接体检) · `me`(当前用户) · `setup`(配置站点) · `sites`(站点档案) · `install-skill` · `completion` · `commands`(命令清单)。
+
+内容与结构:
+- `posts` / `pages` — 文章/页面增删改查。
+- `content <rest_base>` / `terms <rest_base>` — 任意 `show_in_rest` 的 CPT / 自定义分类。
+- `media` — 媒体列出/上传/URL 导入(`sideload`)/图像编辑(`edit-image` 裁剪旋转)/更新/删除。
+- `categories` / `tags` — 分类/标签。
+- `comments` — 评论(含创建/回复)。
+- `users` — 用户(含 `me`)。
+- `menus` / `menu-items` — 导航菜单与菜单项(`--locations` 绑定主题位置)。
+- `revisions` — 修订列表/查看/删除/恢复。
+- `search` — 跨内容搜索。
+- `settings` — 站点设置读取/更新。
+- `types` / `taxonomies` / `statuses` — 自省已注册类型/分类/状态。
 
-## 相关 skill
-`wp-rest-api`(REST 端点)、`wp-wpcli-and-ops`(WP-CLI/SSH 运维)、`wp-performance`(性能)、`wordpress-router`(项目分类入口)。
+区块主题与现代内容:
+- `blocks` — 可复用区块。
+- `navigation` — 区块主题 Navigation。
+- `templates` / `template-parts` — 模板与片段。
+- `global-styles` — theme.json 全局样式。
+- `widgets` / `sidebars` — 小工具/边栏。
+- `app-passwords` — 用户应用密码(创建时明文只打印一次)。
+
+运维与插件:
+- `plugins` — 列表/安装/启停/删除。
+- `themes` — 列表/切换。
+- `abilities` — Abilities API 列出/运行(需插件)。
+- `health` — 站点健康测试(需插件)。
+- `batch` — 批量 REST 请求(仅 POST/PUT/PATCH/DELETE)。
+- `raw` — 任意端点兜底。
+
+## 能力边界(不要向用户承诺)
+- **REST 做不到**:插件/主题/核心**代码更新**、备份/还原、安全扫描、性能优化、文件系统操作 → 需 WP-CLI + SSH 或集中管理平台。
+- **能做的**:上面索引里的全部内容,以及连接与权限体检。
+- **需要插件**:导航菜单(`/menus`、`/menu-items`)、`abilities`、`health`;路由不存在时端点会报 404,wpops 会提示"需插件",此时回退到 `wpops raw` 或后台操作。
+- **`batch` 只接受 POST/PUT/PATCH/DELETE**(核心 `/batch/v1` 拒绝 GET)。