wpops 0.1.1 → 0.2.0

package/lib/global-styles.js

@@ -0,0 +1,25 @@
+// 全局样式(/wp-json/wp/v2/global-styles):区块主题的 theme.json 样式配置。
+import { stripTags, printJson, dry, parseJson, readJsonFile } from './util.js';
+import { UsageError } from './errors.js';
+
+const GLOBAL_STYLES = '/wp-json/wp/v2/global-styles';
+
+export async function getGlobalStyles(client, id, flags) {
+  const { data } = await client.request('GET', `${GLOBAL_STYLES}/${id}`);
+  if (flags.json) return printJson(data);
+  const title = stripTags(data.title?.rendered || data.title || '');
+  console.log(`${data.id}  ${title}`.trimEnd());
+  console.log(JSON.stringify(data.styles ?? {}, null, 2));
+}
+
+export async function updateGlobalStyles(client, id, flags) {
+  let styles;
+  if (flags['from-file'] !== undefined) styles = readJsonFile(flags['from-file']);
+  else if (flags.styles !== undefined) styles = parseJson(flags.styles);
+  if (styles === undefined) throw new UsageError('更新全局样式需要 --styles JSON 或 --from-file');
+  const body = { styles };
+  if (flags['dry-run']) return dry(`更新全局样式 ${id} ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', `${GLOBAL_STYLES}/${id}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已更新全局样式 ${data.id}`);
+}

package/lib/health.js

@@ -0,0 +1,41 @@
+// 站点健康命令(/wp-json/wp-site-health/v1)。
+// 多数测试端点是只读的;directory-sizes 走单独路径。
+import { printJson } from './util.js';
+import { UsageError } from './errors.js';
+
+const BASE = '/wp-json/wp-site-health/v1';
+
+/** 已知的站点健康测试名。 */
+export const KNOWN_TESTS = [
+  'authorization-header',
+  'background-updates',
+  'dotorg-communication',
+  'https-status',
+  'loopback-requests',
+  'page-cache',
+  'directory-sizes',
+];
+
+/** 列出已知测试名与用法,不发任何请求。 */
+export async function listHealth(client, flags) {
+  if (flags.json) return printJson(KNOWN_TESTS);
+  console.log('已知站点健康测试:');
+  for (const test of KNOWN_TESTS) console.log(`  ${test}`);
+  console.log('用法:wpops health <test> [--json]');
+}
+
+/** 运行一个健康测试:directory-sizes 走专用路径,其余走 tests/{test}。 */
+export async function runHealth(client, test, flags) {
+  if (!test) {
+    throw new UsageError(`health 需要一个测试名:wpops health <test>;可用:${KNOWN_TESTS.join(', ')}`);
+  }
+  const path = test === 'directory-sizes'
+    ? `${BASE}/directory-sizes`
+    : `${BASE}/tests/${encodeURIComponent(test)}`;
+  const { data } = await client.request('GET', path);
+  if (flags.json) return printJson(data);
+  const status = data?.status;
+  const label = data?.label ?? data?.name ?? test;
+  const description = data?.description ?? data?.message ?? '';
+  console.log(`[${status === undefined || status === null ? '?' : status}] ${label} — ${description}`);
+}

package/lib/help.js

@@ -0,0 +1,117 @@
+// 由 lib/spec.js 生成所有帮助文本与机器清单,保证与实现同源。
+import { GROUPS, GLOBAL_FLAGS, groupByName, manifest } from './spec.js';
+
+function groupLine(g, width) {
+  const alias = g.aliases?.length ? `  (别名:${g.aliases.join(',')})` : '';
+  return `  ${g.name.padEnd(width)} ${g.summary}${alias}`;
+}
+
+/** 总帮助。 */
+export function generalHelp(version = 'unknown') {
+  const width = Math.max(...GROUPS.map((g) => g.name.length)) + 1;
+  const local = GROUPS.filter((g) => g.local);
+  const remote = GROUPS.filter((g) => !g.local);
+
+  const lines = [];
+  lines.push(`wpops ${version} —— WordPress REST 操作工具`);
+  lines.push('');
+  lines.push('用法: wpops [--site 名字 | --all] <组> <动作> [参数] [--flags]');
+  lines.push('');
+  lines.push('先看这个(现查现用,不要背细节):');
+  lines.push('  wpops <组> --help · wpops help <组> [动作]   某组的动作与参数');
+  lines.push('  wpops commands --json                        机器可读命令清单(组/动作/写操作)');
+  lines.push('  wpops raw GET /wp-json/                      站点真实路由与命名空间');
+  lines.push('  wpops raw OPTIONS <path>                     端点支持的字段与枚举');
+  lines.push('  wpops doctor                                 连接与权限体检(先跑这个)');
+  lines.push('');
+  lines.push('内置命令:');
+  for (const g of local) lines.push(groupLine(g, width));
+  lines.push('');
+  lines.push('站点命令:');
+  for (const g of remote) lines.push(groupLine(g, width));
+  lines.push('');
+  lines.push('多站点:');
+  lines.push('  --site <名字> / -s <名字>        对 sites/<名字>.env 执行,可逗号分隔多个');
+  lines.push('  --all / -a                       对所有已配置站点批量执行(写操作需 --yes)');
+  lines.push('');
+  lines.push('安全:');
+  lines.push('  --dry-run                       只预览不执行(--force 仅用于真正执行)');
+  lines.push('  --yes / -y                      批量写操作确认');
+  lines.push('');
+  lines.push('全局开关:');
+  for (const [flag, desc] of GLOBAL_FLAGS) lines.push(`  ${flag.padEnd(28)} ${desc}`);
+  lines.push('');
+  lines.push('示例:');
+  lines.push('  wpops doctor');
+  lines.push('  wpops -s blog-a posts list --per-page 5 --orderby date --order desc');
+  lines.push('  wpops posts update 12 --from-file ./post.md --status draft');
+  lines.push('  wpops menus list --help');
+  lines.push('  wpops menu-items list --menus 190');
+  lines.push('  wpops --all plugins list');
+  lines.push('  wpops posts list --all-pages --fields id,title --csv');
+  return lines.join('\n');
+}
+
+/**
+ * 某组(可带动作)的帮助。未知组返回 null。
+ * 动作级只补充该动作说明;细节参数统一用 `wpops raw OPTIONS <path>` 或上方用法。
+ */
+export function groupHelp(name, action) {
+  const g = groupByName(name);
+  if (!g) return null;
+
+  const lines = [];
+  lines.push(`${g.name} —— ${g.summary}`);
+  if (g.aliases?.length) lines.push(`别名:${g.aliases.join(', ')}`);
+  lines.push('');
+
+  const actions = Object.entries(g.actions || {});
+  if (actions.length) {
+    lines.push('动作:');
+    for (const [a, desc] of actions) lines.push(`  ${a.padEnd(10)} ${desc}`);
+    lines.push('');
+  } else {
+    lines.push('(无子动作,直接运行)');
+    lines.push('');
+  }
+
+  if (action) {
+    const desc = (g.actions || {})[action];
+    if (desc) lines.push(`动作 ${action}:${desc}`);
+    else if (actions.length) lines.push(`未知动作 "${action}";可用:${actions.map(([a]) => a).join(', ')}`);
+    lines.push('');
+  }
+
+  if (g.usage?.length) {
+    lines.push('用法:');
+    for (const u of g.usage) lines.push(`  ${u}`);
+    lines.push('');
+  }
+
+  if (g.flags?.length) {
+    lines.push('参数:');
+    for (const f of g.flags) lines.push(`  ${f}`);
+    lines.push('');
+  }
+
+  lines.push('提示:wpops commands --json 可列出全部组与动作;端点字段用 wpops raw OPTIONS <path>。');
+  return lines.join('\n');
+}
+
+/** 用法错误时用的精简用法(优先与该动作相关的行,最多几行)。 */
+export function usageHint(name, action) {
+  const g = groupByName(name);
+  if (!g || !g.usage?.length) return [];
+  if (action) {
+    const escaped = String(action).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(^|\\s)${escaped}(\\s|$)`);
+    const matches = g.usage.filter((u) => re.test(u));
+    if (matches.length) return matches.slice(0, 3);
+  }
+  return g.usage.slice(0, 4);
+}
+
+/** 机器可读清单。 */
+export function commandsJson(version = 'unknown') {
+  return JSON.stringify(manifest(version), null, 2);
+}

package/lib/introspect.js

@@ -0,0 +1,59 @@
+// 站点自省:列出 / 查看已注册的文章类型、分类法与文章状态。
+// 这些端点返回以 slug 为键的对象,而非数组。
+
+import { printJson } from './util.js';
+
+const TYPES = '/wp-json/wp/v2/types';
+const TAXONOMIES = '/wp-json/wp/v2/taxonomies';
+const STATUSES = '/wp-json/wp/v2/statuses';
+
+export async function listTypes(client, flags) {
+  const { data } = await client.request('GET', TYPES);
+  if (flags.json) return printJson(data);
+
+  const entries = Object.entries(data || {});
+  console.log(`文章类型 ${entries.length} 个:`);
+  for (const [name, type] of entries) {
+    console.log(`  ${name}  rest_base=${type.rest_base}`);
+  }
+}
+
+export async function getType(client, type, flags) {
+  const { data } = await client.request('GET', `${TYPES}/${type}`);
+  if (flags.json) return printJson(data);
+
+  console.log(`name:${data.name}`);
+  console.log(`slug:${data.slug}`);
+  console.log(`rest_base:${data.rest_base}`);
+}
+
+export async function listTaxonomies(client, flags) {
+  const { data } = await client.request('GET', TAXONOMIES);
+  if (flags.json) return printJson(data);
+
+  const entries = Object.entries(data || {});
+  console.log(`分类法 ${entries.length} 个:`);
+  for (const [name, tax] of entries) {
+    console.log(`  ${name}  rest_base=${tax.rest_base}`);
+  }
+}
+
+export async function getTaxonomy(client, tax, flags) {
+  const { data } = await client.request('GET', `${TAXONOMIES}/${tax}`);
+  if (flags.json) return printJson(data);
+
+  console.log(`name:${data.name}`);
+  console.log(`slug:${data.slug}`);
+  console.log(`rest_base:${data.rest_base}`);
+}
+
+export async function listStatuses(client, flags) {
+  const { data } = await client.request('GET', STATUSES);
+  if (flags.json) return printJson(data);
+
+  const entries = Object.entries(data || {});
+  console.log(`状态 ${entries.length} 个:`);
+  for (const [slug, status] of entries) {
+    console.log(`  ${slug}  ${status.name}`);
+  }
+}

package/lib/navigation.js

@@ -0,0 +1,71 @@
+// 区块主题导航(wp_navigation):/wp-json/wp/v2/navigation。
+// 结构与 blocks.js 一致。
+
+import { readFileSync } from 'node:fs';
+import { stripTags, printJson, dry, listRequest } from './util.js';
+import { UsageError } from './errors.js';
+
+const NAVIGATION = '/wp-json/wp/v2/navigation';
+
+export async function listNavigation(client, flags) {
+  const query = {
+    per_page: flags['per-page'] ?? 20,
+    page: flags.page,
+    search: flags.search,
+    status: flags.status,
+    context: 'edit',
+  };
+  const { data, total } = await listRequest(client, NAVIGATION, query, flags);
+  if (flags.json) return printJson(data);
+  console.log(`导航 ${total ?? data.length} 个:`);
+  for (const n of data) {
+    console.log(`  #${n.id}  [${n.status}]  ${stripTags(n.title?.raw ?? n.title?.rendered ?? '(无标题)')}`);
+  }
+}
+
+export async function getNavigation(client, id, flags) {
+  const { data } = await client.request('GET', `${NAVIGATION}/${Number(id)}`, {
+    query: { context: flags.context || 'edit' },
+  });
+  if (flags.json) return printJson(data);
+  console.log(`#${data.id}  [${data.status}]  ${stripTags(data.title?.raw ?? data.title?.rendered ?? '')}`);
+  console.log('─'.repeat(44));
+  console.log(data.content?.raw ?? stripTags(data.content?.rendered || ''));
+}
+
+function navigationBody(flags) {
+  const body = {};
+  if (flags.title !== undefined) body.title = String(flags.title);
+  if (flags['from-file'] !== undefined) body.content = readFileSync(String(flags['from-file']), 'utf8');
+  else if (flags.content !== undefined) body.content = String(flags.content);
+  if (flags.status !== undefined) body.status = String(flags.status);
+  return body;
+}
+
+export async function createNavigation(client, flags) {
+  const body = navigationBody(flags);
+  if (body.title === undefined) throw new UsageError('创建导航需要 --title');
+  if (flags['dry-run']) return dry(`创建导航 ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', NAVIGATION, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已创建导航 #${data.id} [${data.status}]`);
+}
+
+export async function updateNavigation(client, id, flags) {
+  const body = navigationBody(flags);
+  if (!Object.keys(body).length) {
+    throw new UsageError('没有可更新的字段(--title/--content/--from-file/--status)');
+  }
+  if (flags['dry-run']) return dry(`更新导航 #${id} ${JSON.stringify(body)}`);
+  const { data } = await client.request('POST', `${NAVIGATION}/${Number(id)}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已更新导航 #${data.id}`);
+}
+
+export async function deleteNavigation(client, id, flags) {
+  if (flags['dry-run']) return dry(`删除导航 #${id}`);
+  if (!flags.force) throw new UsageError('删除导航需要 --force(不可撤销)');
+  const { data } = await client.request('DELETE', `${NAVIGATION}/${Number(id)}`, { query: { force: 'true' } });
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除导航 #${id}` : `? 导航 #${id} 未删除`);
+}

package/lib/revisions.js

@@ -0,0 +1,56 @@
+// 内容修订(revisions):列出 / 查看 / 删除 / 恢复到某个修订。
+// type 取 posts 或 pages,默认 posts;端点挂在具体内容下。
+
+import { stripTags, printJson, dry, listRequest } from './util.js';
+import { UsageError } from './errors.js';
+
+function revisionsPath(type, id) {
+  return `/wp-json/wp/v2/${type}/${Number(id)}/revisions`;
+}
+
+export async function listRevisions(client, type, id, flags) {
+  const query = {
+    per_page: flags['per-page'] ?? 10,
+    page: flags.page,
+  };
+  const { data, total } = await listRequest(client, revisionsPath(type, id), query, flags);
+  if (flags.json) return printJson(data);
+  console.log(`${type} #${id} 修订 ${total ?? data.length} 条:`);
+  for (const rev of data) {
+    console.log(`  #${rev.id}  ${rev.date}  ${rev.author}  ${stripTags(rev.title?.rendered || '')}`);
+  }
+}
+
+export async function getRevision(client, type, id, rev, flags) {
+  const { data } = await client.request('GET', `${revisionsPath(type, id)}/${Number(rev)}`);
+  if (flags.json) return printJson(data);
+  console.log(`#${data.id}  ${data.date}  ${data.author}  ${stripTags(data.title?.rendered || '')}`);
+}
+
+export async function deleteRevision(client, type, id, rev, flags) {
+  if (flags['dry-run']) return dry(`删除 ${type} #${id} 修订 #${rev}`);
+  if (!flags.force) throw new UsageError('删除修订需要 --force(不可撤销)');
+  const { data } = await client.request('DELETE', `${revisionsPath(type, id)}/${Number(rev)}`, {
+    query: { force: 'true' },
+  });
+  if (flags.json) return printJson(data);
+  console.log(data.deleted ? `✓ 已删除 ${type} #${id} 修订 #${rev}` : `? 修订 #${rev} 未删除`);
+}
+
+/** 取修订字段:优先 .raw,退回 .rendered。 */
+function revisionValue(field) {
+  return field?.raw ?? field?.rendered;
+}
+
+export async function restoreRevision(client, type, id, rev, flags) {
+  const { data: revision } = await client.request('GET', `${revisionsPath(type, id)}/${Number(rev)}`);
+  const body = {
+    title: revisionValue(revision.title),
+    content: revisionValue(revision.content),
+    excerpt: revisionValue(revision.excerpt),
+  };
+  if (flags['dry-run']) return dry(`恢复 ${type} #${id} 到修订 #${rev}`);
+  const { data } = await client.request('POST', `/wp-json/wp/v2/${type}/${Number(id)}`, { body });
+  if (flags.json) return printJson(data);
+  console.log(`✓ 已恢复 ${type} #${id} 到修订 #${rev}`);
+}