niranzwp 0.8.4 → 0.8.5

package/bin/niranzwp.js

@@ -74,6 +74,13 @@ Built by Niranjan -- https://niranz.dev
   niranzwp media list [--missing-alt]
   niranzwp media set-alt <id> "<text>"
   niranzwp user list
+
+  niranzwp file read <path> [--offset <n>] [--limit <n>]
+  niranzwp file list [<path>] [--recursive] [--pattern '*.php']
+  niranzwp file write <path> <content|-> [--append] [--create-dirs] [--apply]
+  niranzwp file edit <path> --old '<text>' --new '<text>' [--all] [--apply]
+  niranzwp file delete|disable|enable <path> [--recursive] [--apply]
+     writes preview by default -- add --apply to change the file
   niranzwp settings get|set <key> <value>
 
   niranzwp seo audit                    site-wide SEO gaps, ranked by severity
@@ -105,6 +112,25 @@ Options
   --version            print version
 `;
 
+/*
+ * Flags that take a value, listed rather than guessed.
+ *
+ * The parser used to decide by looking ahead: a flag swallowed the next token
+ * unless it began with --. That is right for --site local and wrong for every
+ * boolean, and it broke silently rather than loudly. `--site local --yes run
+ * <ability>` parsed as yes="run", left the ability as the command, and printed
+ * usage -- so putting the global flags first, which works for every other
+ * command, quietly did nothing here.
+ *
+ * Anything not named here is a boolean, so a new switch needs no change and
+ * cannot eat the command after it.
+ */
+const VALUE_FLAGS = new Set([
+	'site', 'name', 'input', 'file', 'timeout', 'max-output', 'endpoint',
+	'title', 'content', 'excerpt', 'status', 'field', 'search',
+	'page', 'limit', 'offset', 'post-type', 'old', 'new', 'pattern',
+]);
+
 function parseArgs(argv) {
 	const args = { _: [], flags: {} };
 	for (let i = 0; i < argv.length; i++) {
@@ -112,9 +138,13 @@ function parseArgs(argv) {
 		if (a.startsWith('--')) {
 			const key = a.slice(2);
 			if (key.startsWith('no-')) { args.flags[key.slice(3)] = false; continue; }
+			if (!VALUE_FLAGS.has(key)) { args.flags[key] = true; continue; }
 			const next = argv[i + 1];
-			if (next === undefined || next.startsWith('--')) { args.flags[key] = true; }
-			else { args.flags[key] = next; i++; }
+			if (next === undefined || next.startsWith('--')) {
+				args.flags[key] = true;
+			} else {
+				args.flags[key] = next; i++;
+			}
 		} else {
 			args._.push(a);
 		}
@@ -152,6 +182,19 @@ function targets(flags) {
 	return all;
 }
 
+/**
+ * Read the whole of stdin.
+ *
+ * `file write <path> -` is how a generated file gets here without going
+ * through the shell's quoting, which mangles anything with a newline or a
+ * quote in it - which is most files worth writing.
+ */
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString('utf8');
+}
+
 const reqOpts = (flags) => ({
 	timeout: Number(flags.timeout || DEFAULT_TIMEOUT_MS),
 	maxOutput: Number(flags['max-output'] || DEFAULT_MAX_OUTPUT),
@@ -425,6 +468,120 @@ async function main() {
 		die(`usage: niranzwp ${cmd} list|get|create|update|delete`);
 	}
 
+	/*
+	 * The filesystem group.
+	 *
+	 * The plugin has eight filesystem abilities and the CLI had shortcuts for
+	 * none of them, so every one of them had to be reached through `run` with a
+	 * hand-written JSON blob. That is fine for a program and miserable for a
+	 * person, and these are the abilities someone reaches for while something
+	 * is broken.
+	 *
+	 * Writes keep the ability's own dry_run default: --yes approves the call,
+	 * --apply is what actually changes the file. Two gestures, because the
+	 * first is "I meant to run this" and the second is "I have read the
+	 * preview".
+	 */
+	if (cmd === 'file') {
+		const p = resolveProfile(flags);
+		/*
+		 * The abilities API routes read-only abilities over GET and refuses
+		 * them over POST. runAbility works that out from ability metadata it
+		 * does not have here, and fetching the metadata first would be a round
+		 * trip to learn something already known - these two are read-only and
+		 * always will be.
+		 */
+		const READS = new Set(['read-file', 'list-directory']);
+		const call = (ability, input) => runAbility(
+			p,
+			`niranzwp/${ability}`,
+			input,
+			{ ...reqOpts(flags), method: READS.has(ability) ? 'GET' : 'POST' }
+		);
+		const apply = flags.apply === true;
+
+		if (sub === 'read') {
+			const path = rest[0];
+			if (!path) die('usage: niranzwp file read <path> [--offset <n>] [--limit <n>]');
+			const input = { path };
+			if (flags.offset !== undefined) input.offset = Number(flags.offset);
+			if (flags.limit !== undefined) input.limit = Number(flags.limit);
+			const r = await call('read-file', input);
+			out(flags, r, (d) => {
+				process.stdout.write(d.content ?? '');
+				if (!d.eof) {
+					console.error(`\n-- ${d.bytes_returned} of ${d.bytes} bytes. Continue with --offset ${d.next_offset}`);
+				}
+			});
+			return;
+		}
+
+		if (sub === 'list') {
+			const input = { path: rest[0] ?? '' };
+			if (flags.recursive === true) input.recursive = true;
+			if (flags.pattern) input.pattern = flags.pattern;
+			if (flags.limit !== undefined) input.limit = Number(flags.limit);
+			if (flags['include-hidden'] === true) input.include_hidden = true;
+			const r = await call('list-directory', input);
+			out(flags, r, (d) => {
+				console.log(`${d.total} entries in ${d.path}${d.truncated ? ' (truncated)' : ''}`);
+				for (const e of d.entries) {
+					console.log(`  ${(e.type === 'directory' ? 'dir ' : '    ')}${String(e.size).padStart(9)}  ${e.name}`);
+				}
+			});
+			return;
+		}
+
+		if (sub === 'write') {
+			const path = rest[0];
+			if (!path) die('usage: niranzwp file write <path> <content|-> [--append] [--apply] --yes');
+			// A dash means stdin, which is how a generated file gets here
+			// without going through the shell's quoting.
+			const rawArg = rest.slice(1).join(' ');
+			const content = rawArg === '-' ? await readStdin() : rawArg;
+			const input = { path, content, dry_run: !apply };
+			if (flags.append === true) input.mode = 'append';
+			if (flags['create-dirs'] === true) input.create_directories = true;
+			out(flags, await call('write-file', input));
+			return;
+		}
+
+		if (sub === 'edit') {
+			const path = rest[0];
+			if (!path || flags.old === undefined || flags.new === undefined) {
+				die('usage: niranzwp file edit <path> --old "<text>" --new "<text>" [--all] [--apply] --yes');
+			}
+			out(flags, await call('edit-file', {
+				path,
+				old_string: String(flags.old),
+				new_string: String(flags.new),
+				replace_all: flags.all === true,
+				dry_run: !apply,
+			}));
+			return;
+		}
+
+		if (sub === 'delete') {
+			const path = rest[0];
+			if (!path) die('usage: niranzwp file delete <path> [--recursive] [--apply] --yes');
+			out(flags, await call('delete-file', {
+				path,
+				recursive: flags.recursive === true,
+				dry_run: !apply,
+			}));
+			return;
+		}
+
+		if (sub === 'disable' || sub === 'enable') {
+			const path = rest[0];
+			if (!path) die(`usage: niranzwp file ${sub} <path> [--apply] --yes`);
+			out(flags, await call(`${sub}-file`, { path, dry_run: !apply }));
+			return;
+		}
+
+		die('usage: niranzwp file read|list|write|edit|delete|disable|enable');
+	}
+
 	if (cmd === 'media') {
 		const p = resolveProfile(flags);
 

package/lib/auth.js

@@ -66,16 +66,35 @@ export async function loginWithAppPassword(siteUrl, { appName = 'NiranzWP CLI',
 			resolve({ siteUrl: site.replace(/\/+$/, ''), user, password, info });
 		});
 
+		/*
+		 * This listener cannot see what the browser saw. If WordPress refused
+		 * the request - it answers "Invalid URL format" when something between
+		 * the browser and PHP rewrites the success_url, which a WAF will do to
+		 * anything carrying http://127.0.0.1 - the person is looking at an
+		 * error page while this sits here saying nothing for five minutes.
+		 *
+		 * So it stops being silent. Nothing is cancelled: an approval arriving
+		 * at minute four still works.
+		 */
+		const nudge = setTimeout(() => {
+			console.error('Still waiting.');
+			console.error('If the browser showed an error instead of an approval screen, or is not on');
+			console.error('this machine, press Ctrl-C and run again with --manual.');
+			console.error('');
+		}, Math.min(45_000, timeoutMs / 2));
+
 		const timer = setTimeout(() => {
 			cleanup();
 			reject(new Error(
-				'Timed out waiting for authorization. If the browser is not on this machine ' +
-				'(SSH, a VPS, a container), it cannot reach this listener -- run again with --manual.'
+				'Timed out waiting for authorization. Either nobody approved it, or the browser ' +
+				'could not reach this listener (SSH, a VPS, a container) or was refused by ' +
+				'WordPress -- run again with --manual, which sends no callback URL at all.'
 			));
 		}, timeoutMs);
 
 		function cleanup() {
 			clearTimeout(timer);
+			clearTimeout(nudge);
 			server.close();
 		}
 

package/lib/oauth.js

@@ -70,8 +70,48 @@ async function postJson(url, body, { timeout = 30_000 } = {}) {
 	}
 }
 
-/** Fetch the authorization server metadata, or null if the site has none. */
+/**
+ * Find the authorization server, preferring the plugin's own.
+ *
+ * /.well-known/oauth-authorization-server is a single path and any plugin can
+ * claim it; whichever hooks parse_request first and exits wins. On a site
+ * running more than one MCP plugin the document there may describe somebody
+ * else's server entirely, and a token minted against it dies the moment that
+ * plugin is removed. So ask the plugin's own namespace first - it can only
+ * ever answer for itself - and fall back to the well-known document for sites
+ * that have an authorization server but not this plugin.
+ */
 export async function discover(siteUrl) {
+	return (await discoverOwn(siteUrl)) || (await discoverWellKnown(siteUrl));
+}
+
+/** The REST namespace index lists the routes actually registered, and nothing else's. */
+async function discoverOwn(siteUrl) {
+	try {
+		const res = await fetchWithTimeout(`${siteUrl}/wp-json/niranzwp/v1`, {
+			headers: { Accept: 'application/json', 'User-Agent': UA },
+		});
+		if (!res.ok) return null;
+		const index = await res.json();
+		const routes = Object.keys(index?.routes || {});
+		const has = (r) => routes.includes(`/niranzwp/v1/oauth/${r}`);
+		if (!has('token') || !has('device') || !has('register')) return null;
+
+		return {
+			issuer: siteUrl,
+			token_endpoint: `${siteUrl}/wp-json/niranzwp/v1/oauth/token`,
+			device_authorization_endpoint: `${siteUrl}/wp-json/niranzwp/v1/oauth/device`,
+			registration_endpoint: `${siteUrl}/wp-json/niranzwp/v1/oauth/register`,
+			grant_types_supported: ['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token'],
+			token_endpoint_auth_methods_supported: ['none'],
+			scopes_supported: ['abilities'],
+		};
+	} catch {
+		return null;
+	}
+}
+
+async function discoverWellKnown(siteUrl) {
 	try {
 		const res = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-authorization-server`, {
 			headers: { Accept: 'application/json', 'User-Agent': UA },

package/lib/store.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, rmSync, existsSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 
@@ -23,9 +23,33 @@ function readProfiles() {
 	}
 }
 
+/**
+ * Write a file so a concurrent reader never sees half of it.
+ *
+ * writeFileSync truncates and then fills, so anything reading in that window
+ * gets a partial file - and both of these hold JSON, where partial means
+ * unparseable. Two CLI processes at once is ordinary: a script running
+ * commands in parallel, or a save landing while another call is resolving its
+ * profile. rename() is atomic on POSIX, so a reader sees either the old file
+ * or the new one.
+ *
+ * The temp file carries the same 0600 mode, because for a moment it holds the
+ * same secrets.
+ */
+function writeAtomic(path, contents) {
+	const tmp = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmp, contents, { mode: 0o600 });
+		renameSync(tmp, path);
+	} catch (e) {
+		try { unlinkSync(tmp); } catch { /* nothing to clean up */ }
+		throw e;
+	}
+}
+
 function writeProfiles(all) {
 	mkdirSync(DIR, { recursive: true, mode: 0o700 });
-	writeFileSync(PROFILES, JSON.stringify(all, null, 2), { mode: 0o600 });
+	writeAtomic(PROFILES, JSON.stringify(all, null, 2));
 }
 
 const account = (name) => `${SERVICE}:${name}`;
@@ -200,7 +224,7 @@ function fileBlobs() {
 
 function writeBlobs(all) {
 	mkdirSync(DIR, { recursive: true, mode: 0o700 });
-	writeFileSync(secretsPath(), JSON.stringify(all), { mode: 0o600 });
+	writeAtomic(secretsPath(), JSON.stringify(all));
 }
 
 /** Last resort: a 0600 file. Weaker than any keychain, and `storageKind` says so. */

package/lib/wp.js

@@ -40,12 +40,23 @@ 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.');
+	// Discovery can fail for reasons that have nothing to do with the token --
+	// a WAF that started blocking /.well-known/ is the one that actually
+	// happened. The token may still be perfectly good, so fall through and
+	// let the request try it; a real 401 is handled below with one retry.
+	let meta = null;
+	try {
+		meta = await discover(profile.siteUrl);
+	} catch { /* treated the same as no metadata */ }
+	if (!meta) return profile;
 
-	const tokens = await refreshTokens(meta, profile.clientId, profile.tokens.refreshToken);
-	updateTokens(profile.name, tokens);
-	return { ...profile, tokens };
+	try {
+		const tokens = await refreshTokens(meta, profile.clientId, profile.tokens.refreshToken);
+		updateTokens(profile.name, tokens);
+		return { ...profile, tokens };
+	} catch {
+		return profile;
+	}
 }
 
 async function parse(res, maxOutput = DEFAULT_MAX_OUTPUT) {
@@ -65,6 +76,7 @@ async function parse(res, maxOutput = DEFAULT_MAX_OUTPUT) {
 
 // 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 USER_AGENT = 'Mozilla/5.0 (compatible; niranzwp/1.0; +https://niranz.dev)';
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_MAX_OUTPUT = 1_048_576; // 1 MiB
 
@@ -87,7 +99,11 @@ export async function request(profile, path, {
 		if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
 	}
 
-	const headers = { Accept: 'application/json', 'User-Agent': 'niranzwp' };
+	// A bare tool-name UA gets classified as a bot by some hosts' WAF rules
+	// (Hostinger's ModSecurity started 403-ing "niranzwp" + Accept:json on
+	// 15 Aug). Identify honestly, but in the shape browsers use, which is what
+	// those rules are written to allow.
+	const headers = { Accept: 'application/json', 'User-Agent': USER_AGENT };
 	if (profile.password || profile.tokens) headers.Authorization = authHeader(profile);
 	if (body !== undefined) headers['Content-Type'] = 'application/json';
 
@@ -124,6 +140,15 @@ export async function request(profile, path, {
 	const data = await parse(res, maxOutput);
 
 	if (!res.ok) {
+		// A 403 whose body is an HTML page did not come from WordPress -- WP
+		// answers REST with JSON. It is a WAF or the host in front. Say so,
+		// rather than reporting a capability problem the user cannot fix.
+		if (403 === res.status && typeof data === 'string' && /<html/i.test(data)) {
+			throw new CliError('server_unsupported',
+				`${profile.siteUrl} refused this request at the web server, before WordPress saw it (HTTP 403, HTML body).`, {
+				hint: 'A firewall (ModSecurity, Cloudflare, host security) is blocking REST calls. Check the host\'s security or WAF settings; nothing in WordPress will change this.',
+			});
+		}
 		// A token can be revoked server-side before it expires on the clock, so
 		// isExpired() will not have caught it. Refresh once and retry.
 		if (401 === res.status && 'oauth' === profile.auth && profile.tokens?.refreshToken && !_retried) {
@@ -145,7 +170,7 @@ export async function probe(siteUrl, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
 	let res;
 	try {
 		res = await fetchWithTimeout(`${siteUrl}/wp-json/`, {
-			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+			headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
 		}, timeout);
 	} catch (e) {
 		throw reachError(siteUrl, e);
@@ -180,7 +205,7 @@ export async function probe(siteUrl, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
 	let oauth = null;
 	try {
 		const r = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-authorization-server`, {
-			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+			headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
 		}, timeout);
 		if (r.ok) oauth = await r.json();
 	} catch { /* not every site has one */ }
@@ -217,8 +242,32 @@ export async function listPosts(profile, { status = 'publish', perPage = 10, pag
 	});
 }
 
+/**
+ * Every ability the site exposes, across every page.
+ *
+ * The endpoint paginates and defaults to fifty per page. Asking without a page
+ * size therefore returned a silently truncated list: on a site with two MCP
+ * plugins installed, ninety-six abilities came back as fifty, and the ones that
+ * fell off simply looked as though they did not exist. Follow the page count
+ * the response reports rather than trusting one request to be the whole answer.
+ */
 export async function listAbilities(profile) {
-	return request(profile, '/wp-abilities/v1/abilities');
+	const first = await request(profile, '/wp-abilities/v1/abilities', {
+		raw: true,
+		query: { per_page: 100, page: 1 },
+	});
+
+	const all = Array.isArray(first.data) ? [...first.data] : first.data;
+	const pages = Number(first.headers?.get?.('x-wp-totalpages') || 1);
+	if (!Array.isArray(all) || pages <= 1) return all;
+
+	for (let page = 2; page <= pages; page++) {
+		const next = await request(profile, '/wp-abilities/v1/abilities', {
+			query: { per_page: 100, page },
+		});
+		if (Array.isArray(next)) all.push(...next);
+	}
+	return all;
 }
 
 /**
@@ -297,7 +346,7 @@ export function isReadOnly(ability) {
 export async function contract(siteUrl, endpoint = '/wp-json/mcp/novamira-oauth') {
 	try {
 		const res = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-protected-resource${endpoint}`, {
-			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+			headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
 		});
 		if (!res.ok) return null;
 		const body = await res.json();

package/package.json

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