niranzwp 0.6.1 → 0.7.3

package/README.md

@@ -36,8 +36,12 @@ UAE Stories -- UAE's first people centric magazine
   https://uaestories.com
   Tier 1 (app passwords): yes
   Tier 2 (abilities):     yes
-  MCP endpoint:           yes
-  OAuth server:           yes
+  namespaces: 38
+
+$ niranzwp probe niranz.dev
+error [server_unreachable]: https://niranz.dev did not return a WordPress
+REST API (HTTP 200, got HTML). Either it is not WordPress, or /wp-json/
+is disabled or blocked.
 ```
 
 Tier 2 is deliberately **not** tied to one plugin. Any provider that registers

package/bin/niranzwp.js

@@ -6,7 +6,9 @@ import { CliError } from '../lib/errors.js';
 import * as cache from '../lib/cache.js';
 import { listServers, pickEndpoint, McpClient, textOf } from '../lib/mcp.js';
 import { validate, applyDefaults } from '../lib/schema.js';
-import { normalizeSite, probe, whoami, listPosts, listAbilities, runAbility, describeAbility, isReadOnly, methodFor, contract, checkCompat, WpError, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_OUTPUT } from '../lib/wp.js';
+import { normalizeSite, probe, whoami, listPosts, listAbilities, runAbility, describeAbility, isReadOnly, methodFor, contract, checkCompat,
+	listItems, getItem, createItem, updateItem, deleteItem, getSettings, updateSettings, totalOf,
+	introspectAppPassword, revokeAppPassword, WpError, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_OUTPUT } from '../lib/wp.js';
 import { readFileSync } from 'node:fs';
 
 const VERSION = '0.6.0';
@@ -16,12 +18,18 @@ Built by Niranjan -- https://niranz.dev
 
   niranzwp auth login <url> [--name <profile>] [--no-open] [--app-password]
   niranzwp auth status [--site <profile>]
-  niranzwp auth logout <profile>
+  niranzwp auth logout <profile> [--local]   revoke on the site too, unless --local
 
   niranzwp probe <url>                    what does this site support? (no auth)
   niranzwp discover [--site <profile>]    list abilities this site exposes
 
-  niranzwp post list [--status draft] [--search x] [--limit 10] [--page 1]
+  --- no plugin needed, works on any WordPress 5.6+ ---
+  niranzwp post list|get|create|update|delete
+  niranzwp page list|get|create|update|delete
+  niranzwp media list [--missing-alt]
+  niranzwp media set-alt <id> "<text>"
+  niranzwp user list
+  niranzwp settings get|set <key> <value>
 
   niranzwp seo audit                    site-wide SEO gaps, ranked by severity
   niranzwp seo missing <field>          list posts missing description|title|focus|thumbnail|alt
@@ -182,11 +190,53 @@ async function main() {
 	}
 
 	if (cmd === 'auth' && sub === 'logout') {
-		const name = rest[0];
-		if (!name) die('usage: niranzwp auth logout <profile>');
+		const name = rest[0] || flags.site;
+		if (!name) die('usage: niranzwp auth logout <profile> [--local]');
+
+		const prof = getProfile(name);
+		if (!prof) {
+			deleteProfile(name);
+			console.log(`Removed "${name}" locally (no stored credential to revoke).`);
+			return;
+		}
+
+		// Removing the local copy is not disconnecting: the credential stays
+		// valid on the site until it is revoked there. Do both by default.
+		let revoked = null;
+		if (flags.local !== true) {
+			try {
+				if ('oauth' === prof.auth) {
+					const meta = await discover(prof.siteUrl);
+					if (meta?.revocation_endpoint) {
+						await fetch(meta.revocation_endpoint, {
+							method: 'POST',
+							headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+							body: new URLSearchParams({
+								token: prof.tokens.refreshToken || prof.tokens.accessToken,
+								client_id: prof.clientId,
+							}).toString(),
+						});
+						revoked = 'oauth grant';
+					}
+				} else {
+					const me = await introspectAppPassword(prof, reqOpts(flags));
+					if (me?.uuid) {
+						await revokeAppPassword(prof, me.uuid, reqOpts(flags));
+						revoked = `application password "${me.name || name}"`;
+					}
+				}
+			} catch (e) {
+				console.error(`warning: could not revoke on the site (${e.message})`);
+				console.error('The local credential is still being removed. Revoke it under Users -> Profile -> Application Passwords.');
+			}
+		}
+
 		deleteProfile(name);
-		console.log(`Removed "${name}" locally.`);
-		console.log('Revoke the password itself under Users -> Profile -> Application Passwords in WordPress.');
+		console.log(`Disconnected "${name}" from ${prof.siteUrl}.`);
+		console.log(revoked ? `Revoked ${revoked} on the site.` : 'Local credential removed.');
+		if (flags.local === true) {
+			console.log('--local was passed, so nothing was revoked on the site.');
+		}
 		return;
 	}
 
@@ -217,24 +267,163 @@ async function main() {
 		return;
 	}
 
-	if (cmd === 'post' && sub === 'list') {
+	// --- Tier 1: core REST, no plugin -------------------------------------
+
+	if (['post', 'page'].includes(cmd)) {
 		const p = resolveProfile(flags);
-		const { data, headers } = await listPosts(p, {
-			status: flags.status || 'publish',
-			perPage: Number(flags.limit || 10),
-			page: Number(flags.page || 1),
-			search: flags.search === true ? undefined : flags.search,
-		});
+		const title = (r) => r.title?.raw ?? r.title?.rendered ?? '';
+
+		if (sub === 'list' || sub === undefined) {
+			const { data, headers } = await listItems(p, cmd, {
+				status: flags.status || 'publish',
+				perPage: Number(flags.limit || 20),
+				page: Number(flags.page || 1),
+				search: flags.search === true ? undefined : flags.search,
+				fields: 'id,date,status,link,title',
+			}, reqOpts(flags));
+			out(flags, data, (rows) => {
+				console.log(`${rows.length} of ${totalOf(headers) ?? '?'} ${cmd}s (${flags.status || 'publish'})`);
+				for (const r of rows) {
+					console.log(`  ${String(r.id).padEnd(8)}${r.date.slice(0, 10)}  ${title(r).slice(0, 58)}`);
+				}
+			});
+			return;
+		}
+
+		if (sub === 'get') {
+			if (!rest[0]) die(`usage: niranzwp ${cmd} get <id>`);
+			out(flags, await getItem(p, cmd, rest[0], reqOpts(flags)), null);
+			return;
+		}
+
+		if (sub === 'create') {
+			const body = {
+				title: flags.title === true ? undefined : flags.title,
+				content: flags.content === true ? undefined : flags.content,
+				excerpt: flags.excerpt === true ? undefined : flags.excerpt,
+				// Draft unless publishing is asked for explicitly.
+				status: flags.status || 'draft',
+			};
+			if (!body.title) die('--title is required');
+			const r = await createItem(p, cmd, body, reqOpts(flags));
+			console.log(`created ${cmd} ${r.id} (${r.status}) -- ${r.link}`);
+			return;
+		}
+
+		if (sub === 'update') {
+			const id = rest[0];
+			if (!id) die(`usage: niranzwp ${cmd} update <id> [--title x] [--content y] [--status z]`);
+			const body = {};
+			for (const k of ['title', 'content', 'excerpt', 'status', 'slug']) {
+				if (typeof flags[k] === 'string') body[k] = flags[k];
+			}
+			if (!Object.keys(body).length) die('nothing to update -- pass --title, --content, --excerpt, --status or --slug');
+			if (flags.yes !== true) {
+				throw new CliError('approval_required', `This edits ${cmd} ${id} on ${p.siteUrl}.`, { hint: 'Re-run with --yes.' });
+			}
+			const r = await updateItem(p, cmd, id, body, reqOpts(flags));
+			console.log(`updated ${cmd} ${r.id} (${r.status})`);
+			return;
+		}
+
+		if (sub === 'delete') {
+			const id = rest[0];
+			if (!id) die(`usage: niranzwp ${cmd} delete <id> [--force]`);
+			if (flags.yes !== true) {
+				throw new CliError('approval_required',
+					flags.force === true
+						? `This PERMANENTLY deletes ${cmd} ${id} on ${p.siteUrl}.`
+						: `This moves ${cmd} ${id} to trash on ${p.siteUrl}.`,
+					{ hint: 'Re-run with --yes.' });
+			}
+			const r = await deleteItem(p, cmd, id, { force: flags.force === true }, reqOpts(flags));
+			console.log(flags.force === true ? `deleted ${cmd} ${id}` : `trashed ${cmd} ${id} (restorable)`);
+			return;
+		}
+
+		die(`usage: niranzwp ${cmd} list|get|create|update|delete`);
+	}
+
+	if (cmd === 'media') {
+		const p = resolveProfile(flags);
+
+		if (sub === 'list' || sub === undefined) {
+			const { data, headers } = await listItems(p, 'media', {
+				perPage: Number(flags.limit || 20),
+				page: Number(flags.page || 1),
+				search: flags.search === true ? undefined : flags.search,
+				fields: 'id,date,alt_text,mime_type,source_url,title',
+				extra: { media_type: 'image' },
+			}, reqOpts(flags));
+			const rows = flags['missing-alt'] === true ? data.filter((m) => !m.alt_text) : data;
+			out(flags, rows, (list) => {
+				console.log(`${list.length} of ${totalOf(headers) ?? '?'} images${flags['missing-alt'] === true ? ' (missing alt on this page)' : ''}`);
+				for (const m of list) {
+					console.log(`  ${String(m.id).padEnd(8)}${(m.alt_text ? 'alt' : '---').padEnd(5)}${(m.source_url || '').split('/').pop().slice(0, 52)}`);
+				}
+			});
+			return;
+		}
+
+		if (sub === 'set-alt') {
+			const [id, ...words] = rest;
+			const alt = words.join(' ');
+			if (!id || !alt) die('usage: niranzwp media set-alt <id> "<alt text>"');
+			if (flags.yes !== true) {
+				throw new CliError('approval_required', `This sets alt text on media ${id} at ${p.siteUrl}.`, { hint: 'Re-run with --yes.' });
+			}
+			const r = await updateItem(p, 'media', id, { alt_text: alt }, reqOpts(flags));
+			console.log(`media ${r.id} alt set to: ${r.alt_text}`);
+			return;
+		}
+
+		die('usage: niranzwp media list|set-alt');
+	}
+
+	if (cmd === 'user' && (sub === 'list' || sub === undefined)) {
+		const p = resolveProfile(flags);
+		const { data, headers } = await listItems(p, 'user', {
+			perPage: Number(flags.limit || 20),
+			fields: 'id,name,slug,roles,email',
+		}, reqOpts(flags));
 		out(flags, data, (rows) => {
-			const total = headers.get('x-wp-total');
-			console.log(`${rows.length} shown of ${total ?? '?'} (${flags.status || 'publish'})`);
-			for (const r of rows) {
-				console.log(`  ${String(r.id).padEnd(8)}${r.date.slice(0, 10)}  ${(r.title?.raw ?? r.title?.rendered ?? '').slice(0, 60)}`);
+			console.log(`${rows.length} of ${totalOf(headers) ?? '?'} users`);
+			for (const u of rows) {
+				console.log(`  ${String(u.id).padEnd(6)}${(u.name || '').padEnd(26)}${(u.roles || []).join(',')}`);
 			}
 		});
 		return;
 	}
 
+	if (cmd === 'settings') {
+		const p = resolveProfile(flags);
+
+		if (sub === 'get' || sub === undefined) {
+			const s = await getSettings(p, reqOpts(flags));
+			out(flags, s, (o) => {
+				for (const [k, v] of Object.entries(o)) {
+					console.log(`  ${k.padEnd(28)}${typeof v === 'object' ? JSON.stringify(v) : String(v)}`);
+				}
+			});
+			return;
+		}
+
+		if (sub === 'set') {
+			const [key, ...words] = rest;
+			const value = words.join(' ');
+			if (!key || !value) die('usage: niranzwp settings set <key> <value>');
+			if (flags.yes !== true) {
+				throw new CliError('approval_required', `This changes "${key}" on ${p.siteUrl}.`, { hint: 'Re-run with --yes.' });
+			}
+			const before = (await getSettings(p, reqOpts(flags)))[key];
+			const after = await updateSettings(p, { [key]: value }, reqOpts(flags));
+			console.log(`${key}\n  before: ${JSON.stringify(before)}\n  after:  ${JSON.stringify(after[key])}`);
+			return;
+		}
+
+		die('usage: niranzwp settings get|set <key> <value>');
+	}
+
 	if (cmd === 'mcp') {
 		const p = resolveProfile(flags);
 		const servers = await listServers(p.siteUrl);

package/lib/wp.js

@@ -344,3 +344,87 @@ function reachError(siteUrl, e) {
 	}
 	return new CliError('server_unreachable', `Cannot reach ${siteUrl}: ${e.message}`);
 }
+
+
+// ---------------------------------------------------------------------------
+// Tier 1: core REST only. Everything below works on any WordPress 5.6+ site
+// with no plugin installed, because wp/v2 and Application Passwords ship with
+// WordPress itself.
+// ---------------------------------------------------------------------------
+
+const TYPE_ROUTE = { post: 'posts', page: 'pages', media: 'media', user: 'users', comment: 'comments' };
+
+export function routeFor(type) {
+	return TYPE_ROUTE[type] ?? `${type}s`;
+}
+
+export async function listItems(profile, type, { perPage = 20, page = 1, status, search, fields, extra = {} } = {}, opts = {}) {
+	return request(profile, `/wp/v2/${routeFor(type)}`, {
+		...opts,
+		raw: true,
+		query: {
+			per_page: perPage,
+			page,
+			status,
+			search,
+			context: 'edit',
+			_fields: fields,
+			...extra,
+		},
+	});
+}
+
+export async function getItem(profile, type, id, opts = {}) {
+	return request(profile, `/wp/v2/${routeFor(type)}/${id}`, { ...opts, query: { context: 'edit' } });
+}
+
+export async function createItem(profile, type, body, opts = {}) {
+	return request(profile, `/wp/v2/${routeFor(type)}`, { ...opts, method: 'POST', body });
+}
+
+export async function updateItem(profile, type, id, body, opts = {}) {
+	return request(profile, `/wp/v2/${routeFor(type)}/${id}`, { ...opts, method: 'POST', body });
+}
+
+/**
+ * WordPress trashes rather than deletes unless force is set, which is the
+ * safer default -- a trashed post can be restored, a deleted one cannot.
+ */
+export async function deleteItem(profile, type, id, { force = false } = {}, opts = {}) {
+	return request(profile, `/wp/v2/${routeFor(type)}/${id}`, {
+		...opts,
+		method: 'DELETE',
+		query: force ? { force: 'true' } : undefined,
+	});
+}
+
+export async function getSettings(profile, opts = {}) {
+	return request(profile, '/wp/v2/settings', opts);
+}
+
+export async function updateSettings(profile, body, opts = {}) {
+	return request(profile, '/wp/v2/settings', { ...opts, method: 'POST', body });
+}
+
+/** Total count from the X-WP-Total header, which every list route sets. */
+export function totalOf(headers) {
+	const n = Number(headers?.get?.('x-wp-total'));
+	return Number.isFinite(n) ? n : null;
+}
+
+
+/**
+ * The application password actually being used for this request. WordPress
+ * exposes it so a client can identify -- and revoke -- its own credential
+ * without the user hunting for it in wp-admin.
+ */
+export async function introspectAppPassword(profile, opts = {}) {
+	return request(profile, '/wp/v2/users/me/application-passwords/introspect', opts);
+}
+
+export async function revokeAppPassword(profile, uuid, opts = {}) {
+	return request(profile, `/wp/v2/users/me/application-passwords/${uuid}`, {
+		...opts,
+		method: 'DELETE',
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niranzwp",
-  "version": "0.6.1",
+  "version": "0.7.3",
   "description": "A CLI for WordPress. Works on any site via Application Passwords, and unlocks Abilities where a site provides them.",
   "type": "module",
   "bin": {