niranzwp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niranjan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# NiranzWP CLI
+
+A CLI for WordPress.
+
+Works on **any** WordPress site through core Application Passwords — no plugin
+required. Where a site also exposes the WordPress Abilities API (core, 6.9+),
+`niranzwp` unlocks those abilities too.
+
+```sh
+niranzwp probe example.com          # what does this site support? (no auth)
+niranzwp auth login example.com     # browser consent -> credential in Keychain
+niranzwp post list --status draft
+niranzwp discover                   # abilities, if the site exposes any
+```
+
+## Why
+
+`wp-cli` is the standard WordPress CLI, and it needs **SSH access to the
+server**. On shared hosting, on managed platforms, or across a portfolio of
+client sites, you usually do not have that.
+
+`niranzwp` needs a **URL and one browser click**.
+
+## Two tiers
+
+| | Requires | Gives you |
+|---|---|---|
+| **Tier 1** | nothing — core WordPress 5.6+ | posts, pages, media, users, taxonomies, comments, settings |
+| **Tier 2** | an abilities provider on the site | whatever that site registers — PHP execution, filesystem, WP-CLI, … |
+
+`niranzwp probe` reports which tiers a site offers before you connect.
+
+```
+$ niranzwp probe uaestories.com
+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
+```
+
+Tier 2 is deliberately **not** tied to one plugin. Any provider that registers
+abilities through the core API works — Novamira, your own plugin, anything else.
+
+## Install
+
+```sh
+npm install -g niranzwp
+```
+
+Requires Node 22+. No runtime dependencies.
+
+## Authentication
+
+`niranzwp auth login` opens WordPress's own
+`/wp-admin/authorize-application.php` consent screen. You approve there, and
+WordPress redirects back to a temporary loopback listener with the credential.
+Nothing is typed or pasted, and no password crosses a third party.
+
+Credentials go to the **macOS Keychain** where available, otherwise to a
+`0600` file under `~/.config/niranzwp`. Profile metadata (site URL, username)
+lives in `~/.config/niranzwp/profiles.json`; passwords never do.
+
+`niranzwp auth logout <profile>` removes the local copy. Revoke the password
+itself under **Users → Profile → Application Passwords** in WordPress.
+
+## Status
+
+Early. Tier 1 auth, `probe`, `post list`, `discover`, and `run` work today.
+
+## License
+
+MIT

package/bin/niranzwp.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { loginWithAppPassword } from '../lib/auth.js';
+import { saveProfile, getProfile, listProfiles, deleteProfile, storageKind, configDir } from '../lib/store.js';
+import { normalizeSite, probe, whoami, listPosts, listAbilities, runAbility, WpError } from '../lib/wp.js';
+import { readFileSync } from 'node:fs';
+
+const USAGE = `niranzwp -- a CLI for WordPress
+
+  niranzwp auth login <url> [--name <profile>] [--no-open]
+  niranzwp auth status [--site <profile>]
+  niranzwp auth logout <profile>
+
+  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]
+  niranzwp run <ability> [--input '<json>' | --file <path>]
+
+Options
+  --site <profile>   which site to act on (default: the only one, or NIRANZWP_SITE)
+  --json             raw JSON output
+`;
+
+function parseArgs(argv) {
+	const args = { _: [], flags: {} };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a.startsWith('--')) {
+			const key = a.slice(2);
+			if (key.startsWith('no-')) { args.flags[key.slice(3)] = false; continue; }
+			const next = argv[i + 1];
+			if (next === undefined || next.startsWith('--')) { args.flags[key] = true; }
+			else { args.flags[key] = next; i++; }
+		} else {
+			args._.push(a);
+		}
+	}
+	return args;
+}
+
+function die(msg, code = 1) {
+	console.error(`error: ${msg}`);
+	process.exit(code);
+}
+
+function resolveProfile(flags) {
+	const wanted = flags.site || process.env.NIRANZWP_SITE;
+	const all = listProfiles();
+	if (!all.length) die('no sites connected yet. Run: niranzwp auth login <url>');
+
+	const name = wanted || (all.length === 1 ? all[0].name : null);
+	if (!name) die(`multiple sites connected (${all.map((p) => p.name).join(', ')}). Pass --site <profile>.`);
+
+	const p = getProfile(name);
+	if (!p) die(`profile "${name}" has no stored credential. Run: niranzwp auth login <url> --name ${name}`);
+	return p;
+}
+
+const out = (flags, value, pretty) => {
+	if (flags.json || !pretty) console.log(JSON.stringify(value, null, 2));
+	else pretty(value);
+};
+
+async function main() {
+	const { _: pos, flags } = parseArgs(process.argv.slice(2));
+	const [cmd, sub, ...rest] = pos;
+
+	if (!cmd || flags.help || cmd === 'help') { console.log(USAGE); return; }
+
+	if (cmd === 'auth' && sub === 'login') {
+		const url = rest[0];
+		if (!url) die('usage: niranzwp auth login <url>');
+		const site = normalizeSite(url);
+		const creds = await loginWithAppPassword(site, { open: flags.open !== false });
+		const name = flags.name || new URL(creds.siteUrl).hostname.replace(/^www\./, '');
+		saveProfile(name, creds);
+		console.log(`Connected "${name}" -> ${creds.siteUrl} as ${creds.user}`);
+		console.log(`Credential stored in ${storageKind()}.`);
+		console.log(creds.info.tier2
+			? 'This site exposes the Abilities API. Try: niranzwp discover'
+			: 'Tier 1 only (core REST). No abilities provider detected on this site.');
+		return;
+	}
+
+	if (cmd === 'auth' && sub === 'status') {
+		const all = listProfiles();
+		if (!all.length) { console.log('No sites connected.'); return; }
+		for (const p of all) {
+			const full = getProfile(p.name);
+			let who = 'credential missing';
+			if (full) {
+				try {
+					const me = await whoami(full);
+					who = `${me.name} (id ${me.id}, ${(me.roles || []).join(',') || 'no role'})`;
+				} catch (e) {
+					who = `unreachable: ${e.message}`;
+				}
+			}
+			console.log(`${p.name}\n  ${p.siteUrl}\n  ${who}`);
+		}
+		console.log(`\nStorage: ${storageKind()}\nConfig:  ${configDir()}`);
+		return;
+	}
+
+	if (cmd === 'auth' && sub === 'logout') {
+		const name = rest[0];
+		if (!name) die('usage: niranzwp auth logout <profile>');
+		deleteProfile(name);
+		console.log(`Removed "${name}" locally.`);
+		console.log('Revoke the password itself under Users -> Profile -> Application Passwords in WordPress.');
+		return;
+	}
+
+	if (cmd === 'probe') {
+		const url = sub;
+		if (!url) die('usage: niranzwp probe <url>');
+		const info = await probe(normalizeSite(url));
+		out(flags, info, (i) => {
+			console.log(`${i.name} -- ${i.description || ''}`);
+			console.log(`  ${i.home}`);
+			console.log(`  Tier 1 (app passwords): ${i.tier1 ? 'yes' : 'no'}`);
+			console.log(`  Tier 2 (abilities):     ${i.tier2 ? 'yes' : 'no'}`);
+			console.log(`  MCP endpoint:           ${i.mcp ? 'yes' : 'no'}`);
+			console.log(`  OAuth server:           ${i.oauth ? 'yes' : 'no'}`);
+			console.log(`  namespaces: ${i.namespaces.length}`);
+		});
+		return;
+	}
+
+	if (cmd === 'discover') {
+		const p = resolveProfile(flags);
+		const list = await listAbilities(p);
+		const items = Array.isArray(list) ? list : list?.abilities || [];
+		out(flags, items, (rows) => {
+			console.log(`${rows.length} abilities on ${p.siteUrl}`);
+			for (const a of rows) console.log(`  ${a.name}${a.label ? `  -- ${a.label}` : ''}`);
+		});
+		return;
+	}
+
+	if (cmd === 'post' && sub === 'list') {
+		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,
+		});
+		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)}`);
+			}
+		});
+		return;
+	}
+
+	if (cmd === 'run') {
+		const p = resolveProfile(flags);
+		const ability = sub;
+		if (!ability) die('usage: niranzwp run <ability> [--input <json>|--file <path>]');
+		let input = {};
+		if (flags.file) input = JSON.parse(readFileSync(flags.file, 'utf8'));
+		else if (typeof flags.input === 'string') input = JSON.parse(flags.input);
+		const result = await runAbility(p, ability, input);
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	console.log(USAGE);
+	process.exit(1);
+}
+
+main().catch((e) => {
+	if (e instanceof WpError) {
+		die(`${e.message}${e.code ? ` [${e.code}]` : ''}${e.status ? ` (HTTP ${e.status})` : ''}`);
+	}
+	die(e.message);
+});

package/lib/auth.js

@@ -0,0 +1,94 @@
+import { createServer } from 'node:http';
+import { execFile } from 'node:child_process';
+import { platform } from 'node:os';
+import { probe } from './wp.js';
+
+// WordPress core ships an Application Password authorization screen at
+// /wp-admin/authorize-application.php. Given a success_url it redirects back
+// with site_url, user_login and password in the query string. That gives us a
+// browser consent flow on ANY WordPress since 5.6 -- no plugin required.
+
+function openBrowser(url) {
+	const cmd = platform() === 'darwin' ? 'open'
+		: platform() === 'win32' ? 'cmd'
+		: 'xdg-open';
+	const args = platform() === 'win32' ? ['/c', 'start', '', url] : [url];
+	execFile(cmd, args, () => { /* a failure just means the user opens it themselves */ });
+}
+
+function page(title, body) {
+	return `<!doctype html><meta charset="utf-8">
+<title>${title}</title>
+<style>
+  body{font:16px/1.6 -apple-system,system-ui,sans-serif;max-width:34rem;margin:12vh auto;padding:0 1.5rem;color:#111}
+  h1{font-size:1.3rem;margin:0 0 .5rem}
+  p{color:#555;margin:0}
+  code{background:#f4f4f5;padding:.15em .4em;border-radius:4px}
+</style>
+<h1>${title}</h1><p>${body}</p>`;
+}
+
+export async function loginWithAppPassword(siteUrl, { appName = 'NiranzWP CLI', open = true, timeoutMs = 300000 } = {}) {
+	const info = await probe(siteUrl);
+
+	if (!info.tier1 || !info.authorizeUrl) {
+		throw new Error(
+			'This site does not advertise Application Passwords. It needs WordPress 5.6+ over HTTPS, ' +
+			'or WP_ENVIRONMENT_TYPE set to "local". A security plugin may also be disabling them.'
+		);
+	}
+
+	return new Promise((resolve, reject) => {
+		const server = createServer((req, res) => {
+			const url = new URL(req.url, 'http://127.0.0.1');
+			if (!url.pathname.startsWith('/callback')) {
+				res.writeHead(404).end();
+				return;
+			}
+
+			const user = url.searchParams.get('user_login');
+			const password = url.searchParams.get('password');
+			const site = url.searchParams.get('site_url') || siteUrl;
+
+			if (!user || !password) {
+				res.writeHead(400, { 'Content-Type': 'text/html' })
+					.end(page('Authorization failed', 'WordPress did not return a credential. You can close this tab and try again.'));
+				cleanup();
+				reject(new Error('Authorization was rejected or returned no credential.'));
+				return;
+			}
+
+			res.writeHead(200, { 'Content-Type': 'text/html' })
+				.end(page('Connected', `<code>niranzwp</code> is now authorized for <code>${site}</code>. You can close this tab.`));
+
+			cleanup();
+			resolve({ siteUrl: site.replace(/\/+$/, ''), user, password, info });
+		});
+
+		const timer = setTimeout(() => {
+			cleanup();
+			reject(new Error('Timed out waiting for authorization.'));
+		}, timeoutMs);
+
+		function cleanup() {
+			clearTimeout(timer);
+			server.close();
+		}
+
+		server.on('error', (e) => { cleanup(); reject(e); });
+
+		// Port 0 lets the OS pick a free port.
+		server.listen(0, '127.0.0.1', () => {
+			const port = server.address().port;
+			const successUrl = `http://127.0.0.1:${port}/callback`;
+			const authorize = new URL(info.authorizeUrl);
+			authorize.searchParams.set('app_name', appName);
+			authorize.searchParams.set('success_url', successUrl);
+
+			console.error('Approve this connection in your browser:');
+			console.error(`  ${authorize}`);
+			console.error('');
+			if (open) openBrowser(authorize.toString());
+		});
+	});
+}

package/lib/store.js

@@ -0,0 +1,122 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+// Profiles (which sites exist, who we are on each) live in a plain JSON file.
+// Passwords never do -- they go to the OS keychain where available.
+
+const DIR = join(homedir(), '.config', 'niranzwp');
+const PROFILES = join(DIR, 'profiles.json');
+const SERVICE = 'niranzwp';
+
+function readProfiles() {
+	if (!existsSync(PROFILES)) return {};
+	try {
+		return JSON.parse(readFileSync(PROFILES, 'utf8'));
+	} catch {
+		return {};
+	}
+}
+
+function writeProfiles(all) {
+	mkdirSync(DIR, { recursive: true, mode: 0o700 });
+	writeFileSync(PROFILES, JSON.stringify(all, null, 2), { mode: 0o600 });
+}
+
+const useKeychain = () => platform() === 'darwin';
+
+function keychainSet(account, secret) {
+	execFileSync('security', [
+		'add-generic-password',
+		'-a', account,
+		'-s', SERVICE,
+		'-w', secret,
+		'-U', // update if it already exists
+	]);
+}
+
+function keychainGet(account) {
+	try {
+		return execFileSync('security', [
+			'find-generic-password', '-a', account, '-s', SERVICE, '-w',
+		], { encoding: 'utf8' }).trim();
+	} catch {
+		return null;
+	}
+}
+
+function keychainDelete(account) {
+	try {
+		execFileSync('security', [
+			'delete-generic-password', '-a', account, '-s', SERVICE,
+		], { stdio: 'ignore' });
+	} catch { /* nothing stored */ }
+}
+
+// Fallback for non-macOS: a 0600 file. Less safe than a keychain, so we say so.
+const secretsPath = () => join(DIR, 'secrets.json');
+
+function fileSecrets() {
+	if (!existsSync(secretsPath())) return {};
+	try {
+		return JSON.parse(readFileSync(secretsPath(), 'utf8'));
+	} catch {
+		return {};
+	}
+}
+
+function account(name) {
+	return `${SERVICE}:${name}`;
+}
+
+export function saveProfile(name, { siteUrl, user, password }) {
+	const all = readProfiles();
+	all[name] = { siteUrl, user, createdAt: new Date().toISOString() };
+	writeProfiles(all);
+
+	if (useKeychain()) {
+		keychainSet(account(name), password);
+	} else {
+		const s = fileSecrets();
+		s[name] = password;
+		mkdirSync(DIR, { recursive: true, mode: 0o700 });
+		writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+	}
+}
+
+export function getProfile(name) {
+	const p = readProfiles()[name];
+	if (!p) return null;
+	const password = useKeychain() ? keychainGet(account(name)) : fileSecrets()[name];
+	if (!password) return null;
+	return { name, ...p, password };
+}
+
+export function listProfiles() {
+	return Object.entries(readProfiles()).map(([name, p]) => ({ name, ...p }));
+}
+
+export function deleteProfile(name) {
+	const all = readProfiles();
+	delete all[name];
+	writeProfiles(all);
+
+	if (useKeychain()) {
+		keychainDelete(account(name));
+	} else {
+		const s = fileSecrets();
+		delete s[name];
+		if (existsSync(secretsPath())) writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+	}
+}
+
+export function storageKind() {
+	return useKeychain() ? 'macOS Keychain' : `file (${secretsPath()}, mode 0600)`;
+}
+
+export function configDir() {
+	return DIR;
+}
+
+export { rmSync };

package/lib/wp.js

@@ -0,0 +1,149 @@
+// Thin WordPress REST client. No dependencies -- Node's fetch is enough.
+
+export class WpError extends Error {
+	constructor(message, { status, code, body } = {}) {
+		super(message);
+		this.name = 'WpError';
+		this.status = status;
+		this.code = code;
+		this.body = body;
+	}
+}
+
+export function normalizeSite(url) {
+	let u = url.trim();
+	if (!/^https?:\/\//i.test(u)) u = `https://${u}`;
+	return u.replace(/\/+$/, '');
+}
+
+function authHeader(profile) {
+	// 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) {
+	const text = await res.text();
+	if (!text) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
+export async function request(profile, path, { method = 'GET', body, query, raw = false } = {}) {
+	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 (body !== undefined) headers['Content-Type'] = 'application/json';
+
+	const res = await fetch(url, {
+		method,
+		headers,
+		body: body === undefined ? undefined : JSON.stringify(body),
+	});
+
+	const data = await parse(res);
+
+	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 });
+	}
+
+	return raw ? { data, headers: res.headers } : data;
+}
+
+// Unauthenticated probe: what does this site actually support?
+export async function probe(siteUrl) {
+	let res;
+	try {
+		res = await fetch(`${siteUrl}/wp-json/`, {
+			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+		});
+	} catch (e) {
+		throw new WpError(`cannot reach ${siteUrl}: ${e.message}`);
+	}
+
+	const text = await res.text();
+	let root;
+	try {
+		root = JSON.parse(text);
+	} catch {
+		// A WordPress REST root always returns JSON. HTML means this is either
+		// not WordPress, or the REST API is disabled or behind a firewall.
+		throw new WpError(
+			`${siteUrl} did not return a WordPress REST API (HTTP ${res.status}, got ${
+				text.trimStart().startsWith('<') ? 'HTML' : 'non-JSON'
+			}). Either it is not WordPress, or /wp-json/ is disabled or blocked.`,
+			{ status: res.status }
+		);
+	}
+
+	if (!root || typeof root !== 'object' || !Array.isArray(root.namespaces)) {
+		throw new WpError(`${siteUrl} returned JSON, but not a WordPress REST root.`, { status: res.status });
+	}
+
+	const namespaces = root.namespaces || [];
+	const appPasswords = Boolean(root.authentication?.['application-passwords']);
+
+	// Abilities API is WordPress core from 6.9. Its presence is the Tier 2 signal.
+	const abilities = namespaces.includes('wp-abilities/v1');
+	const mcp = namespaces.includes('mcp');
+
+	let oauth = null;
+	try {
+		const r = await fetch(`${siteUrl}/.well-known/oauth-authorization-server`, {
+			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
+		});
+		if (r.ok) oauth = await r.json();
+	} catch { /* not every site has one */ }
+
+	return {
+		name: root.name,
+		description: root.description,
+		home: root.home,
+		namespaces,
+		tier1: appPasswords,
+		tier2: abilities,
+		mcp,
+		oauth: Boolean(oauth),
+		oauthMeta: oauth,
+		authorizeUrl: root.authentication?.['application-passwords']?.endpoints?.authorization || null,
+	};
+}
+
+export async function whoami(profile) {
+	return request(profile, '/wp/v2/users/me', { query: { context: 'edit' } });
+}
+
+export async function listPosts(profile, { status = 'publish', perPage = 10, page = 1, search } = {}) {
+	return request(profile, '/wp/v2/posts', {
+		raw: true,
+		query: {
+			status,
+			per_page: perPage,
+			page,
+			search,
+			context: 'edit',
+			_fields: 'id,date,status,link,title',
+		},
+	});
+}
+
+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 ?? {},
+	});
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "niranzwp",
+  "version": "0.1.0",
+  "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"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT"
+}