niranzwp 0.1.0 → 0.6.1

package/lib/wp.js

@@ -1,3 +1,7 @@
+import { CliError, fromRest } from './errors.js';
+import { discover, refresh as refreshTokens, isExpired } from './oauth.js';
+import { updateTokens } from './store.js';
+import * as cache from './cache.js';
 // Thin WordPress REST client. No dependencies -- Node's fetch is enough.
 
 export class WpError extends Error {
@@ -17,14 +21,39 @@ export function normalizeSite(url) {
 }
 
 function authHeader(profile) {
+	if ('oauth' === profile.auth) {
+		return `Bearer ${profile.tokens.accessToken}`;
+	}
 	// Application Passwords are sent as HTTP Basic. WordPress strips the
 	// spaces WordPress itself put in the generated password.
 	const raw = `${profile.user}:${profile.password.replace(/\s+/g, '')}`;
 	return `Basic ${Buffer.from(raw, 'utf8').toString('base64')}`;
 }
 
-async function parse(res) {
+/**
+ * Refresh an OAuth profile in place when its access token is about to expire.
+ * The rotated pair is persisted before it is used, because the old refresh
+ * token is consumed by the exchange.
+ */
+export async function ensureFresh(profile) {
+	if ('oauth' !== profile.auth || !profile.tokens?.refreshToken) return profile;
+	if (!isExpired(profile.tokens)) return profile;
+
+	const meta = await discover(profile.siteUrl);
+	if (!meta) throw new CliError('server_unsupported', 'This site no longer advertises an OAuth server.');
+
+	const tokens = await refreshTokens(meta, profile.clientId, profile.tokens.refreshToken);
+	updateTokens(profile.name, tokens);
+	return { ...profile, tokens };
+}
+
+async function parse(res, maxOutput = DEFAULT_MAX_OUTPUT) {
 	const text = await res.text();
+	if (text.length > maxOutput) {
+		throw new CliError('output_budget', `Response body is ${text.length} bytes, over the ${maxOutput} byte budget.`, {
+			hint: 'Narrow the request or raise --max-output.',
+		});
+	}
 	if (!text) return null;
 	try {
 		return JSON.parse(text);
@@ -33,28 +62,62 @@ async function parse(res) {
 	}
 }
 
-export async function request(profile, path, { method = 'GET', body, query, raw = false } = {}) {
+// Guardrails, matching what a careful CLI should do rather than trusting the
+// server to be well behaved: every request is bounded in time and in size.
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_OUTPUT = 1_048_576; // 1 MiB
+
+export async function request(profile, path, {
+	method = 'GET',
+	body,
+	query,
+	raw = false,
+	timeout = DEFAULT_TIMEOUT_MS,
+	maxOutput = DEFAULT_MAX_OUTPUT,
+} = {}) {
 	const url = new URL(path.startsWith('http') ? path : `${profile.siteUrl}/wp-json${path}`);
 	for (const [k, v] of Object.entries(query || {})) {
 		if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
 	}
 
 	const headers = { Accept: 'application/json', 'User-Agent': 'niranzwp' };
-	if (profile.password) headers.Authorization = authHeader(profile);
+	if (profile.password || profile.tokens) headers.Authorization = authHeader(profile);
 	if (body !== undefined) headers['Content-Type'] = 'application/json';
 
-	const res = await fetch(url, {
-		method,
-		headers,
-		body: body === undefined ? undefined : JSON.stringify(body),
-	});
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeout);
 
-	const data = await parse(res);
+	let res;
+	try {
+		res = await fetch(url, {
+			method,
+			headers,
+			body: body === undefined ? undefined : JSON.stringify(body),
+			signal: controller.signal,
+		});
+	} catch (e) {
+		clearTimeout(timer);
+		if (e.name === 'AbortError') {
+			throw new CliError('timeout', `Request timed out after ${timeout}ms.`, { hint: 'Raise it with --timeout <ms>.' });
+		}
+		throw reachError(profile.siteUrl, e);
+	} finally {
+		clearTimeout(timer);
+	}
+
+	// A site can return an unbounded response. Refuse to buffer it rather than
+	// letting one call exhaust memory or flood the caller.
+	const declared = Number(res.headers.get('content-length') || 0);
+	if (declared > maxOutput) {
+		throw new CliError('output_budget', `Response is ${declared} bytes, over the ${maxOutput} byte budget.`, {
+			hint: 'Narrow the request or raise --max-output.',
+		});
+	}
+
+	const data = await parse(res, maxOutput);
 
 	if (!res.ok) {
-		const code = data && typeof data === 'object' ? data.code : undefined;
-		const msg = (data && typeof data === 'object' && data.message) || `HTTP ${res.status}`;
-		throw new WpError(msg, { status: res.status, code, body: data });
+		throw fromRest(res.status, data);
 	}
 
 	return raw ? { data, headers: res.headers } : data;
@@ -68,7 +131,7 @@ export async function probe(siteUrl) {
 			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
 		});
 	} catch (e) {
-		throw new WpError(`cannot reach ${siteUrl}: ${e.message}`);
+		throw reachError(siteUrl, e);
 	}
 
 	const text = await res.text();
@@ -141,9 +204,143 @@ export async function listAbilities(profile) {
 	return request(profile, '/wp-abilities/v1/abilities');
 }
 
-export async function runAbility(profile, name, input) {
-	return request(profile, `/wp-abilities/v1/abilities/${name}/run`, {
-		method: 'POST',
-		body: input ?? {},
-	});
+/**
+ * Core dictates the HTTP method from the ability's own annotations, and always
+ * carries the payload under an "input" key -- as a query parameter for the
+ * methods that have no body, and in the JSON body otherwise.
+ */
+export function methodFor(ability) {
+	const ann = ability?.meta?.annotations ?? ability?.annotations ?? {};
+	if (ann.readonly) return 'GET';
+	if (ann.destructive && ann.idempotent) return 'DELETE';
+	return 'POST';
+}
+
+/**
+ * Flatten a value into PHP-style bracketed query keys:
+ *   { a: 1, b: { c: 2 }, d: [3] } -> input[a]=1, input[b][c]=2, input[d][0]=3
+ */
+function bracketed(prefix, value, out = {}) {
+	if (value === null || value === undefined) return out;
+
+	if (Array.isArray(value)) {
+		value.forEach((v, i) => bracketed(`${prefix}[${i}]`, v, out));
+		return out;
+	}
+	if ('object' === typeof value) {
+		const entries = Object.entries(value);
+		// An empty object must still be sent, or core sees no input at all.
+		if (!entries.length) { out[`${prefix}`] = ''; return out; }
+		for (const [k, v] of entries) bracketed(`${prefix}[${k}]`, v, out);
+		return out;
+	}
+
+	out[prefix] = 'boolean' === typeof value ? (value ? '1' : '0') : String(value);
+	return out;
+}
+
+export async function runAbility(profile, name, input, opts = {}) {
+	const { ability, ...rest } = opts;
+	const method = opts.method ?? methodFor(ability);
+	const path = `/wp-abilities/v1/abilities/${name}/run`;
+	const payload = input ?? {};
+
+	if ('GET' === method || 'DELETE' === method) {
+		// Core reads $request->get_query_params()['input'] and expects a real
+		// array, so the payload has to be bracket-encoded rather than sent as
+		// a JSON string.
+		return request(profile, path, { ...rest, method, query: bracketed('input', payload) });
+	}
+
+	return request(profile, path, { ...rest, method, body: { input: payload } });
+}
+
+export async function describeAbility(profile, name, opts = {}) {
+	const hit = cache.get(profile.siteUrl, profile.name, name);
+	if (hit) return hit;
+
+	const data = await request(profile, `/wp-abilities/v1/abilities/${name}`, opts);
+	cache.put(profile.siteUrl, profile.name, name, data);
+	return data;
+}
+
+// Is this ability declared read-only by the site? Used to decide whether a
+// run needs explicit approval.
+export function isReadOnly(ability) {
+	const ann = ability?.meta?.annotations ?? ability?.annotations ?? {};
+	return ann.readonly === true;
+}
+
+
+/**
+ * Read the site's Novamira/abilities compatibility metadata, if it publishes
+ * any. Used to fail early with a clear message rather than midway through a
+ * command, when a site is too old to serve what we are about to ask for.
+ */
+export async function contract(siteUrl, endpoint = '/wp-json/mcp/novamira-oauth') {
+	try {
+		const res = await fetch(`${siteUrl}/.well-known/oauth-protected-resource${endpoint}`, {
+			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+		});
+		if (!res.ok) return null;
+		const body = await res.json();
+		return body?.novamira ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export const MIN_WORDPRESS = '6.9';
+
+export function checkCompat(info) {
+	const problems = [];
+	if (!info) return problems;
+	if (info.wordpress_version && compareVersions(info.wordpress_version, MIN_WORDPRESS) < 0) {
+		problems.push(`site runs WordPress ${info.wordpress_version}; the Abilities API needs ${MIN_WORDPRESS}`);
+	}
+	if (info.rest_api_version && Number(info.rest_api_version) > 1) {
+		problems.push(`site advertises REST contract v${info.rest_api_version}; this CLI speaks v1`);
+	}
+	return problems;
+}
+
+function compareVersions(a, b) {
+	const pa = String(a).split('.').map(Number);
+	const pb = String(b).split('.').map(Number);
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+		const d = (pa[i] || 0) - (pb[i] || 0);
+		if (d) return d < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
+
+/**
+ * Turn a fetch failure into something actionable. Node ships its own CA list,
+ * so a certificate the OS trusts -- a LocalWP or mkcert development cert, or a
+ * corporate proxy's -- is still rejected here, and the bare "fetch failed"
+ * gives no clue why.
+ */
+function reachError(siteUrl, e) {
+	const chain = [];
+	for (let c = e; c; c = c.cause) chain.push(c.code || c.message || '');
+	const codes = chain.join(' ');
+
+	const tls = /SELF_SIGNED|UNABLE_TO_VERIFY|DEPTH_ZERO|CERT_|ERR_TLS/i.test(codes);
+	if (tls) {
+		return new CliError('server_unreachable', `TLS certificate for ${siteUrl} is not trusted by Node.`, {
+			hint: 'Node uses its own CA list. For a development certificate run: NODE_OPTIONS=--use-system-ca niranzwp ... (after trusting it in the OS), or use the http:// URL for a local site.',
+		});
+	}
+	if (/ENOTFOUND|EAI_AGAIN/i.test(codes)) {
+		return new CliError('server_unreachable', `Cannot resolve ${siteUrl}.`, {
+			hint: 'Check the hostname, and that the site is running.',
+		});
+	}
+	if (/ECONNREFUSED/i.test(codes)) {
+		return new CliError('server_unreachable', `Connection refused by ${siteUrl}.`, {
+			hint: 'The host resolved but nothing is listening. Is the site started?',
+		});
+	}
+	return new CliError('server_unreachable', `Cannot reach ${siteUrl}: ${e.message}`);
 }

package/package.json

@@ -1,11 +1,33 @@
 {
   "name": "niranzwp",
-  "version": "0.1.0",
+  "version": "0.6.1",
   "description": "A CLI for WordPress. Works on any site via Application Passwords, and unlocks Abilities where a site provides them.",
   "type": "module",
   "bin": {
     "niranzwp": "bin/niranzwp.js"
   },
+  "author": {
+    "name": "Niranjan",
+    "url": "https://niranz.dev"
+  },
+  "homepage": "https://niranz.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niranz-dev/niranzwp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/niranz-dev/niranzwp/issues"
+  },
+  "keywords": [
+    "wordpress",
+    "cli",
+    "wp-cli",
+    "rest-api",
+    "application-passwords",
+    "abilities-api",
+    "seo",
+    "site-management"
+  ],
   "engines": {
     "node": ">=22"
   },