niranzwp 0.1.0 → 0.6.1

package/bin/niranzwp.js

@@ -1,12 +1,20 @@
 #!/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 { saveProfile, saveOAuthProfile, getProfile, listProfiles, deleteProfile, storageKind, configDir } from '../lib/store.js';
+import { discover, registerClient, startDeviceFlow, pollForToken } from '../lib/oauth.js';
+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 { readFileSync } from 'node:fs';
 
-const USAGE = `niranzwp -- a CLI for WordPress
+const VERSION = '0.6.0';
 
-  niranzwp auth login <url> [--name <profile>] [--no-open]
+const USAGE = `NiranzWP CLI v${VERSION} -- a CLI for WordPress
+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>
 
@@ -14,11 +22,34 @@ const USAGE = `niranzwp -- a CLI for WordPress
   niranzwp discover [--site <profile>]    list abilities this site exposes
 
   niranzwp post list [--status draft] [--search x] [--limit 10] [--page 1]
+
+  niranzwp seo audit                    site-wide SEO gaps, ranked by severity
+  niranzwp seo missing <field>          list posts missing description|title|focus|thumbnail|alt
+  niranzwp geo check                    AI crawler access, llms.txt, sitemap
+  niranzwp geo llms-txt [--write]       generate llms.txt for AI answer engines
+
   niranzwp run <ability> [--input '<json>' | --file <path>]
 
+  seo and geo commands need the NiranzWP plugin on the site.
+
+  niranzwp describe <ability>           show an ability's schema and annotations
+
+  niranzwp sites                        list connected sites
+  niranzwp doctor [--offline]           check this install and every connection
+  niranzwp cache clear                  drop cached ability metadata
+
+  niranzwp mcp servers                  MCP servers this site exposes
+  niranzwp mcp tools                    tools available over MCP
+  niranzwp mcp call <tool> [--input]    call a tool over MCP
+
 Options
-  --site <profile>   which site to act on (default: the only one, or NIRANZWP_SITE)
-  --json             raw JSON output
+  --all                run across every connected site (seo, geo, discover)
+  --site <profile>     which site to act on (default: the only one, or NIRANZWP_SITE)
+  --json               raw JSON output
+  --yes                approve a write ability (required for anything not read-only)
+  --timeout <ms>       request timeout (default 30000)
+  --max-output <bytes> response budget (default 1048576)
+  --version            print version
 `;
 
 function parseArgs(argv) {
@@ -56,6 +87,21 @@ function resolveProfile(flags) {
 	return p;
 }
 
+// --all turns any site-scoped command into a fleet operation. Nothing else
+// in the WordPress CLI space does this, and it is the whole point of the tool
+// for anyone running more than one site.
+function targets(flags) {
+	if (flags.all !== true) return [resolveProfile(flags)];
+	const all = listProfiles().map((p) => getProfile(p.name)).filter(Boolean);
+	if (!all.length) die('no sites connected. Run: niranzwp auth login <url>');
+	return all;
+}
+
+const reqOpts = (flags) => ({
+	timeout: Number(flags.timeout || DEFAULT_TIMEOUT_MS),
+	maxOutput: Number(flags['max-output'] || DEFAULT_MAX_OUTPUT),
+});
+
 const out = (flags, value, pretty) => {
 	if (flags.json || !pretty) console.log(JSON.stringify(value, null, 2));
 	else pretty(value);
@@ -65,12 +111,45 @@ async function main() {
 	const { _: pos, flags } = parseArgs(process.argv.slice(2));
 	const [cmd, sub, ...rest] = pos;
 
+	if (flags.version || cmd === 'version') {
+		console.log(`NiranzWP CLI v${VERSION}`);
+		console.log('Built by Niranjan -- https://niranz.dev');
+		return;
+	}
+
 	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);
+
+		// Prefer OAuth where the site offers it: nothing is stored that can be
+		// replayed, and access can be revoked server-side. --app-password
+		// forces the older path.
+		const meta = flags['app-password'] === true ? null : await discover(site);
+
+		if (meta?.device_authorization_endpoint) {
+			const name = flags.name || new URL(site).hostname.replace(/^www\./, '');
+			const clientId = await registerClient(meta);
+			const device = await startDeviceFlow(meta, clientId);
+
+			console.error('Open this page and enter the code:');
+			console.error(`  ${device.verificationUri}`);
+			console.error(`  code: ${device.userCode}`);
+			console.error(`\nExpires in ${Math.round(device.expiresIn / 60)} minutes. Waiting...`);
+
+			const tokens = await pollForToken(meta, clientId, device, {
+				timeoutMs: Number(flags.timeout || device.expiresIn * 1000),
+			});
+
+			saveOAuthProfile(name, { siteUrl: site, clientId, tokens });
+			console.log(`Connected "${name}" -> ${site} via OAuth`);
+			console.log(`Tokens stored in ${storageKind()}; they refresh automatically.`);
+			console.log('Try: niranzwp discover');
+			return;
+		}
+
 		const creds = await loginWithAppPassword(site, { open: flags.open !== false });
 		const name = flags.name || new URL(creds.siteUrl).hostname.replace(/^www\./, '');
 		saveProfile(name, creds);
@@ -156,14 +235,266 @@ async function main() {
 		return;
 	}
 
+	if (cmd === 'mcp') {
+		const p = resolveProfile(flags);
+		const servers = await listServers(p.siteUrl);
+		if (!servers.length) die(`${p.siteUrl} exposes no MCP servers.`);
+
+		if (sub === 'servers') {
+			out(flags, servers, (rows) => {
+				for (const s of rows) console.log(`  ${s.name.padEnd(30)}${s.url}`);
+			});
+			return;
+		}
+
+		const endpoint = flags.endpoint || pickEndpoint(servers, { oauth: p.auth === 'oauth' });
+		const client = new McpClient(endpoint, {
+			token: p.auth === 'oauth' ? p.tokens.accessToken : undefined,
+			basic: p.auth !== 'oauth' && p.password
+				? Buffer.from(`${p.user}:${p.password.replace(/\s+/g, '')}`, 'utf8').toString('base64')
+				: undefined,
+			timeout: Number(flags.timeout || DEFAULT_TIMEOUT_MS),
+		});
+		await client.initialize();
+
+		if (sub === 'tools') {
+			const tools = await client.listTools();
+			out(flags, tools, (rows) => {
+				console.log(`${rows.length} tools on ${endpoint}`);
+				for (const t of rows) console.log(`  ${t.name}${t.description ? `  -- ${String(t.description).split('\n')[0].slice(0, 70)}` : ''}`);
+			});
+			return;
+		}
+
+		if (sub === 'call') {
+			const tool = rest[0];
+			if (!tool) die('usage: niranzwp mcp call <tool> [--input <json>|--file <path>]');
+			let args = {};
+			if (flags.file) args = JSON.parse(readFileSync(flags.file, 'utf8'));
+			else if (typeof flags.input === 'string') args = JSON.parse(flags.input);
+			const r = await client.callTool(tool, args);
+			console.log(textOf(r));
+			return;
+		}
+
+		die('usage: niranzwp mcp servers|tools|call <tool>');
+	}
+
+	if (cmd === 'cache' && sub === 'clear') {
+		cache.clear();
+		console.log(`Cleared ${cache.dir()}`);
+		return;
+	}
+
+	if (cmd === 'sites') {
+		const all = listProfiles();
+		if (!all.length) { console.log('No sites connected. Run: niranzwp auth login <url>'); return; }
+		out(flags, all, (rows) => {
+			for (const r of rows) {
+				const has = Boolean(getProfile(r.name));
+				console.log(`  ${has ? ' ' : '!'} ${r.name.padEnd(28)}${r.siteUrl}${has ? '' : '   (credential missing)'}`);
+			}
+			console.log(`\n${rows.length} site${rows.length === 1 ? '' : 's'} -- storage: ${storageKind()}`);
+		});
+		return;
+	}
+
+	if (cmd === 'doctor') {
+		const checks = [];
+		const nodeMajor = Number(process.versions.node.split('.')[0]);
+		checks.push({
+			ok: nodeMajor >= 22,
+			label: 'Node 22+',
+			detail: `running ${process.versions.node}`,
+		});
+		checks.push({
+			ok: storageKind().includes('Keychain'),
+			warn: !storageKind().includes('Keychain'),
+			label: 'Credential storage',
+			detail: storageKind(),
+		});
+
+		const all = listProfiles();
+		checks.push({ ok: all.length > 0, label: 'Sites connected', detail: `${all.length}` });
+
+		if (flags.offline !== true) {
+			for (const prof of all) {
+				const info = await contract(prof.siteUrl);
+				if (!info) continue;
+				const problems = checkCompat(info);
+				checks.push({
+					ok: problems.length === 0,
+					label: `${prof.name} contract`,
+					detail: problems.length
+						? problems.join('; ')
+						: `WordPress ${info.wordpress_version}, REST contract v${info.rest_api_version}`,
+				});
+			}
+		}
+
+		if (flags.offline !== true) {
+			for (const prof of all) {
+				const full = getProfile(prof.name);
+				if (!full) {
+					checks.push({ ok: false, label: prof.name, detail: 'credential missing from keychain' });
+					continue;
+				}
+				try {
+					const me = await whoami(full);
+					let abilities = 0;
+					try {
+						const list = await listAbilities(full);
+						abilities = (Array.isArray(list) ? list : list?.abilities || []).length;
+					} catch { /* tier 1 only */ }
+					checks.push({
+						ok: true,
+						label: prof.name,
+						detail: `${me.name} (id ${me.id}) -- ${abilities} abilities`,
+					});
+				} catch (e) {
+					checks.push({ ok: false, label: prof.name, detail: e.message });
+				}
+			}
+		}
+
+		out(flags, checks, (rows) => {
+			for (const c of rows) {
+				const icon = c.ok ? 'ok  ' : (c.warn ? 'warn' : 'FAIL');
+				console.log(`  [${icon}] ${c.label.padEnd(24)}${c.detail}`);
+			}
+			const bad = rows.filter((c) => !c.ok && !c.warn).length;
+			console.log(`\n${bad === 0 ? 'All checks passed.' : `${bad} check(s) failed.`}`);
+		});
+		if (checks.some((c) => !c.ok && !c.warn)) process.exitCode = 1;
+		return;
+	}
+
+	// --- SEO ---------------------------------------------------------------
+
+	if (cmd === 'seo' && sub === 'audit') {
+		for (const p of targets(flags)) {
+		const r = await runAbility(p, 'niranzwp/seo-audit', {
+			post_type: flags['post-type'] || 'post',
+		}, { ...reqOpts(flags), ability: await describeAbility(p, 'niranzwp/seo-audit', reqOpts(flags)).catch(() => null) })
+			.catch((e) => ({ _error: e.message }));
+		if (r._error) { console.error(`${p.name}: ${r._error}`); continue; }
+		out(flags, r, (a) => {
+			console.log(`${p.siteUrl}  --  ${a.published} published ${a.post_type}`);
+			console.log(`SEO plugin: ${a.seo_plugin || 'none detected'}\n`);
+			if (!a.issues?.length) { console.log('  No issues found.'); return; }
+			const mark = { high: '!!', medium: ' !', warning: ' ?', low: '  ' };
+			for (const i of a.issues) {
+				console.log(`${mark[i.severity] ?? '  '} [${i.severity}] ${i.message}`);
+			}
+			console.log(`\n${a.issue_count} issue${a.issue_count === 1 ? '' : 's'}.\n`);
+		});
+		}
+		return;
+	}
+
+	if (cmd === 'seo' && sub === 'missing') {
+		const p = resolveProfile(flags);
+		const listMeta = await describeAbility(p, 'niranzwp/seo-list-missing', reqOpts(flags)).catch(() => null);
+		const r = await runAbility(p, 'niranzwp/seo-list-missing', {
+			field: rest[0] || flags.field || 'description',
+			post_type: flags['post-type'] || 'post',
+			limit: Number(flags.limit || 20),
+			offset: Number(flags.offset || 0),
+		}, { ...reqOpts(flags), ability: listMeta });
+		out(flags, r, (d) => {
+			console.log(`${d.count} missing "${d.field}" (offset ${d.offset})`);
+			for (const i of d.items) {
+				console.log(`  ${String(i.id).padEnd(8)}${(i.date ?? '').padEnd(12)}${(i.title || '').slice(0, 58)}`);
+			}
+		});
+		return;
+	}
+
+	// --- GEO ---------------------------------------------------------------
+
+	if (cmd === 'geo' && sub === 'check') {
+		for (const p of targets(flags)) {
+		const r = await runAbility(p, 'niranzwp/geo-check', {}, {
+			...reqOpts(flags),
+			ability: await describeAbility(p, 'niranzwp/geo-check', reqOpts(flags)).catch(() => null),
+		}).catch((e) => ({ _error: e.message }));
+		if (r._error) { console.error(`${p.name}: ${r._error}`); continue; }
+		out(flags, r, (g) => {
+			console.log(`${g.site}\n`);
+			console.log(`  robots.txt         ${g.robots_txt ? 'yes' : 'NO'}`);
+			console.log(`  llms.txt           ${g.llms_txt ? 'yes' : 'NO'}`);
+			console.log(`  sitemap in robots  ${g.sitemap_in_robots ? 'yes' : 'NO'}\n`);
+			console.log('  AI crawlers:');
+			for (const [agent, info] of Object.entries(g.ai_crawlers || {})) {
+				console.log(`    ${info.blocked ? 'BLOCKED' : 'allowed'}  ${agent.padEnd(20)} ${info.owner}`);
+			}
+			if (g.issues?.length) {
+				console.log('');
+				for (const i of g.issues) console.log(`  [${i.severity}] ${i.message}`);
+			}
+			console.log('');
+		});
+		}
+		return;
+	}
+
+	if (cmd === 'geo' && sub === 'llms-txt') {
+		const p = resolveProfile(flags);
+		const write = flags.write === true;
+		const llmsMeta = await describeAbility(p, 'niranzwp/geo-llms-txt', reqOpts(flags)).catch(() => null);
+		const r = await runAbility(p, 'niranzwp/geo-llms-txt', {
+			write,
+			limit: Number(flags.limit || 30),
+		}, { ...reqOpts(flags), ability: llmsMeta });
+		if (flags.json) { console.log(JSON.stringify(r, null, 2)); return; }
+		console.log(r.content);
+		console.error(`\n${r.bytes} bytes -- ${r.written ? `written to ${r.url}` : 'not written (pass --write)'}`);
+		return;
+	}
+
+	if (cmd === 'describe') {
+		const p = resolveProfile(flags);
+		if (!sub) die('usage: niranzwp describe <ability>');
+		const a = await describeAbility(p, sub, reqOpts(flags));
+		out(flags, a, (d) => {
+			console.log(`${d.name}\n  ${d.description || ''}`);
+			console.log(`  type: ${isReadOnly(d) ? 'read-only' : 'WRITE -- needs --yes'}`);
+			if (d.input_schema) console.log(`  input: ${JSON.stringify(d.input_schema)}`);
+		});
+		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);
+
+		// One describe serves two purposes: the write gate, and validating the
+		// input locally so a bad argument never reaches the site.
+		let meta = null;
+		try {
+			meta = await describeAbility(p, ability, reqOpts(flags));
+		} catch { /* fall through; run will report the real error */ }
+
+		if (meta && !isReadOnly(meta) && flags.yes !== true) {
+			throw new CliError('approval_required', `"${ability}" is a write ability.`, {
+				hint: 'Re-run with --yes to approve it.',
+			});
+		}
+
+		if (meta?.input_schema) {
+			input = applyDefaults(input, meta.input_schema);
+			const errors = validate(input, meta.input_schema);
+			if (errors.length) {
+				throw new CliError('usage_error', `Invalid input for ${ability}:\n  - ${errors.join('\n  - ')}`);
+			}
+		}
+
+		const result = await runAbility(p, ability, input, { ...reqOpts(flags), ability: meta });
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
@@ -173,6 +504,11 @@ async function main() {
 }
 
 main().catch((e) => {
+	if (e instanceof CliError) {
+		console.error(`error [${e.code}]: ${e.message}`);
+		if (e.hint) console.error(`hint: ${e.hint}`);
+		process.exit(e.exitCode);
+	}
 	if (e instanceof WpError) {
 		die(`${e.message}${e.code ? ` [${e.code}]` : ''}${e.status ? ` (HTTP ${e.status})` : ''}`);
 	}

package/lib/cache.js

@@ -0,0 +1,122 @@
+// Ability metadata cache.
+//
+// Ability schemas change only when a site's plugins change, but the --yes gate
+// needs them on every run. Caching removes that round trip.
+//
+// Records are keyed by a SHA-256 of origin + profile + ability name, so two
+// sites can never read each other's entries, and a key is never a filename
+// derived from untrusted input. Reads fail closed: anything corrupt, expired
+// or oversized is deleted rather than returned.
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DIR = join(homedir(), '.config', 'niranzwp', 'cache', 'abilities', 'v1');
+const TTL_MS = 5 * 60 * 1000;      // metadata is cheap to refetch; keep it fresh
+const MAX_ENTRY = 256 * 1024;      // one oversized record must not fill the disk
+const MAX_TOTAL = 10 * 1024 * 1024;
+
+// Bumping this invalidates every entry, for when our own record shape changes.
+const RECORD_VERSION = 1;
+
+function keyFor(origin, profile, name) {
+	return createHash('sha256').update([origin, profile, name].join('\0')).digest('hex');
+}
+
+function pathFor(origin, profile, name) {
+	return join(DIR, `${keyFor(origin, profile, name)}.json`);
+}
+
+export function get(origin, profile, name) {
+	const file = pathFor(origin, profile, name);
+	if (!existsSync(file)) return null;
+
+	try {
+		const rec = JSON.parse(readFileSync(file, 'utf8'));
+
+		// The record repeats its own identity so a stale or moved file cannot
+		// be served for the wrong site.
+		if (
+			rec.v !== RECORD_VERSION ||
+			rec.origin !== origin ||
+			rec.profile !== profile ||
+			rec.name !== name
+		) {
+			rmSync(file, { force: true });
+			return null;
+		}
+		if (Date.now() - rec.at > TTL_MS) {
+			rmSync(file, { force: true });
+			return null;
+		}
+		return rec.data;
+	} catch {
+		rmSync(file, { force: true });
+		return null;
+	}
+}
+
+export function put(origin, profile, name, data) {
+	const body = JSON.stringify({
+		v: RECORD_VERSION,
+		origin,
+		profile,
+		name,
+		at: Date.now(),
+		data,
+	});
+
+	if (body.length > MAX_ENTRY) return;
+
+	mkdirSync(DIR, { recursive: true, mode: 0o700 });
+	writeFileSync(pathFor(origin, profile, name), body, { mode: 0o600 });
+	sweep();
+}
+
+/** Drop expired entries, then oldest-first until the directory fits. */
+function sweep() {
+	if (!existsSync(DIR)) return;
+
+	let files;
+	try {
+		files = readdirSync(DIR).map((f) => {
+			const full = join(DIR, f);
+			const st = statSync(full);
+			return { full, size: st.size, mtime: st.mtimeMs };
+		});
+	} catch {
+		return;
+	}
+
+	const now = Date.now();
+	let total = 0;
+	const live = [];
+
+	for (const f of files) {
+		if (now - f.mtime > TTL_MS) {
+			rmSync(f.full, { force: true });
+			continue;
+		}
+		total += f.size;
+		live.push(f);
+	}
+
+	if (total <= MAX_TOTAL) return;
+
+	live.sort((a, b) => a.mtime - b.mtime);
+	for (const f of live) {
+		if (total <= MAX_TOTAL) break;
+		rmSync(f.full, { force: true });
+		total -= f.size;
+	}
+}
+
+export function clear() {
+	rmSync(DIR, { recursive: true, force: true });
+}
+
+export function dir() {
+	return DIR;
+}

package/lib/errors.js

@@ -0,0 +1,78 @@
+// Typed errors with stable exit codes, so scripts can branch on failure kind
+// instead of grepping messages.
+//
+//   1  generic / usage
+//   2  the site is not usable (unreachable, not WordPress, unsupported)
+//   3  authorization (missing, expired, denied, insufficient scope)
+//   4  the request was refused (budget, timeout, batch too large)
+
+export const EXIT = {
+	GENERIC: 1,
+	SERVER: 2,
+	AUTH: 3,
+	REFUSED: 4,
+};
+
+export const CODES = {
+	usage_error: EXIT.GENERIC,
+	not_found: EXIT.GENERIC,
+
+	server_unreachable: EXIT.SERVER,
+	not_wordpress: EXIT.SERVER,
+	server_unsupported: EXIT.SERVER,
+	contract_mismatch: EXIT.SERVER,
+
+	auth_required: EXIT.AUTH,
+	auth_expired: EXIT.AUTH,
+	auth_denied: EXIT.AUTH,
+	insufficient_scope: EXIT.AUTH,
+
+	output_budget: EXIT.REFUSED,
+	timeout: EXIT.REFUSED,
+	approval_required: EXIT.REFUSED,
+	batch_too_large: EXIT.REFUSED,
+};
+
+export class CliError extends Error {
+	constructor(code, message, { hint, cause } = {}) {
+		super(message);
+		this.name = 'CliError';
+		this.code = code;
+		this.hint = hint;
+		this.cause = cause;
+		this.exitCode = CODES[code] ?? EXIT.GENERIC;
+	}
+
+	toJSON() {
+		return { error: this.code, message: this.message, hint: this.hint ?? null };
+	}
+}
+
+/** Map a WordPress REST failure onto our taxonomy. */
+export function fromRest(status, body, fallback = 'usage_error') {
+	const wpCode = body && typeof body === 'object' ? body.code : undefined;
+
+	if (401 === status || 'rest_oauth_required' === wpCode) {
+		return new CliError('auth_required', body?.message || 'Authorization required.', {
+			hint: 'Run: niranzwp auth login <url>',
+		});
+	}
+	if (403 === status) {
+		// A token can be valid but scoped to a narrower set of routes than the
+		// one being called -- that reads very differently from a plain
+		// capability failure, so keep the two hints apart.
+		const scoped = /route|scope/i.test(String(body?.message ?? ''));
+		return new CliError('insufficient_scope', body?.message || 'Not permitted.', {
+			hint: scoped
+				? 'This token is scoped to a different endpoint. Novamira OAuth tokens work against its MCP endpoint, not the core abilities run route.'
+				: 'This credential belongs to a user without the required capability.',
+		});
+	}
+	if (404 === status) {
+		return new CliError('not_found', body?.message || 'Not found.');
+	}
+	if (status >= 500) {
+		return new CliError('server_unsupported', body?.message || `Server error (HTTP ${status}).`);
+	}
+	return new CliError(fallback, body?.message || `HTTP ${status}`);
+}