wpops 0.1.0

package/lib/env.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * 配置根目录。
+ * - 默认:包目录(git clone / 本地开发,配置文件就在仓库里)
+ * - 可用 WPOPS_HOME 覆盖(推荐给 npm 全局安装的用户,例如 ~/.config/wpops)
+ */
+export function configHome() {
+  return process.env.WPOPS_HOME ? resolve(process.env.WPOPS_HOME) : pkgRoot;
+}
+
+function sitesDir() {
+  return resolve(configHome(), 'sites');
+}
+
+function rootEnvFile() {
+  return resolve(configHome(), '.env');
+}
+
+/** 解析 .env 文本为对象(导出以便测试)。 */
+export function parseDotenv(text) {
+  const vars = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}
+
+function assertSiteName(site) {
+  if (site && !/^[A-Za-z0-9._-]+$/.test(site)) {
+    throw new Error(`非法站点名 "${site}":只允许字母、数字、点、下划线、连字符`);
+  }
+}
+
+/** 某站点对应哪个配置文件。site 为空→根 .env;有值→sites/<site>.env。 */
+export function envFileFor(site) {
+  if (process.env.WPOPS_ENV) return process.env.WPOPS_ENV;
+  if (site) return resolve(sitesDir(), `${site}.env`);
+  return rootEnvFile();
+}
+
+/** 列出所有已配置站点(默认站 + sites/ 下的名字)。 */
+export function listSites() {
+  const sites = [];
+  if (existsSync(rootEnvFile())) {
+    sites.push({ name: null, label: '(default)', file: rootEnvFile() });
+  }
+  const dir = sitesDir();
+  if (existsSync(dir)) {
+    for (const file of readdirSync(dir).sort()) {
+      if (file.endsWith('.env')) {
+        const name = file.slice(0, -4);
+        sites.push({ name, label: name, file: resolve(dir, file) });
+      }
+    }
+  }
+  return sites;
+}
+
+/**
+ * 读取配置。
+ * - 指定 site                → 只读 sites/<site>.env(不叠加环境变量,避免多站串味)
+ * - 未指定,但有根 .env       → 读根 .env,允许真实环境变量覆盖
+ * - 未指定,且根 .env 不存在  → 若 sites/ 下只有一个站点,就当作默认站
+ */
+export function loadEnv(site) {
+  assertSiteName(site);
+  let effective = site || null;
+
+  if (!effective && !process.env.WPOPS_ENV && !existsSync(rootEnvFile())) {
+    const named = listSites();
+    if (named.length === 1) effective = named[0].name;
+  }
+
+  const file = envFileFor(effective);
+  if (!existsSync(file)) {
+    if (effective) throw new Error(`找不到站点配置 "${effective}":${file}`);
+    return { ...process.env };
+  }
+
+  const fromFile = parseDotenv(readFileSync(file, 'utf8'));
+  return effective ? fromFile : { ...fromFile, ...process.env };
+}

package/lib/skill.js

@@ -0,0 +1,37 @@
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 内置 skill 的源文件路径。 */
+export function skillSource() {
+  return join(pkgRoot, 'skills', 'wpops', 'SKILL.md');
+}
+
+/** skill 要安装到的目录(可通过 WPOPS_SKILL_DIR 覆盖)。 */
+export function skillTargets() {
+  const targets = [];
+  if (process.env.WPOPS_SKILL_DIR) targets.push(resolve(process.env.WPOPS_SKILL_DIR));
+  targets.push(join(homedir(), '.agents', 'skills', 'wpops'));
+  return targets;
+}
+
+/** 把内置 skill 复制到发现目录,返回成功写入的目录列表。best-effort。 */
+export function installSkill() {
+  if (process.env.WPOPS_SKIP_SKILL) return [];
+  const src = skillSource();
+  const installed = [];
+  if (!existsSync(src)) return installed;
+  for (const dir of skillTargets()) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      copyFileSync(src, join(dir, 'SKILL.md'));
+      installed.push(dir);
+    } catch {
+      // 忽略:安装脚本不应因写 skill 失败而中断
+    }
+  }
+  return installed;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "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.",
+  "license": "MIT",
+  "author": "qnnp",
+  "type": "module",
+  "bin": {
+    "wpops": "bin/wpops.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "skills",
+    ".env.example",
+    "README.md"
+  ],
+  "keywords": [
+    "wordpress",
+    "wp",
+    "rest-api",
+    "wp-json",
+    "cli",
+    "application-password",
+    "content-management",
+    "multi-site"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qnnp-me/wpops.git"
+  },
+  "homepage": "https://github.com/qnnp-me/wpops#readme",
+  "bugs": {
+    "url": "https://github.com/qnnp-me/wpops/issues"
+  },
+  "scripts": {
+    "setup": "node bin/wpops.js setup",
+    "doctor": "node bin/wpops.js doctor",
+    "help": "node bin/wpops.js help",
+    "postinstall": "node scripts/postinstall.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,15 @@
+// npm postinstall:把内置 skill 安装到 agent 的发现目录。
+// 任何失败都不应中断 npm 安装本身。
+import { installSkill } from '../lib/skill.js';
+
+try {
+  const installed = installSkill();
+  for (const dir of installed) {
+    console.log(`wpops: skill 已安装到 ${dir}`);
+  }
+  if (!installed.length) {
+    console.log('wpops: 未自动安装 skill(可用 `wpops install-skill` 手动安装)');
+  }
+} catch {
+  // 静默:postinstall 出错不影响安装
+}

package/skills/wpops/SKILL.md

@@ -0,0 +1,54 @@
+---
+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.
+---
+
+# wpops —— WordPress REST 操作
+
+## 何时用
+用户要管理 WordPress 站点的**内容**或**插件/主题**时,优先用 `wpops`,不要手搓 curl/HTTP 请求。
+
+## 安装与位置
+- 全局命令 `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 ...` — 对所有站点批量执行
+
+## 安全流程(必须遵守)
+1. 首次操作某站先跑 `wpops doctor`(检查连接与权限;失败返回非 0)。
+2. 任何写操作先加 `--dry-run` 预览目标与内容。
+3. `--all` 的**写操作必须加 `--yes`**,否则会被拒绝。
+4. 需要程序化解析输出时加 `--json`。
+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]       # 兜底:任意端点
+```
+
+## 能力边界(不要向用户承诺)
+- **REST 做不到**:插件/主题/核心**更新**、备份/还原、安全扫描、性能优化、文件系统操作。
+  → 这些需要 WP-CLI + SSH,或 MainWP。详见 skill `wp-wpcli-and-ops`。
+- **能做的**:文章/页面/媒体/分类/标签/评论/用户的增删改查、插件安装与启停、主题切换、连接与权限体检。
+
+## 相关 skill
+`wp-rest-api`(REST 端点)、`wp-wpcli-and-ops`(WP-CLI/SSH 运维)、`wp-performance`(性能)、`wordpress-router`(项目分类入口)。