niranzwp 0.1.0 → 0.7.2

package/README.md

@@ -31,13 +31,13 @@ client sites, you usually do not have that.
 `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
+$ niranzwp probe example.com
+Example Magazine -- a WordPress site
+  https://example.com
   Tier 1 (app passwords): yes
   Tier 2 (abilities):     yes
-  MCP endpoint:           yes
-  OAuth server:           yes
+  MCP endpoint:           no
+  OAuth server:           no
 ```
 
 Tier 2 is deliberately **not** tied to one plugin. Any provider that registers

package/bin/niranzwp.js

@@ -1,24 +1,63 @@
 #!/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,
+	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 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>
+  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
+  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 +95,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 +119,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);
@@ -103,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;
 	}
 
@@ -138,20 +267,388 @@ 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'})`);
+			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);
+		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) {
-				console.log(`  ${String(r.id).padEnd(8)}${r.date.slice(0, 10)}  ${(r.title?.raw ?? r.title?.rendered ?? '').slice(0, 60)}`);
+				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;
 	}
@@ -160,10 +657,33 @@ async function main() {
 		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 +693,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})` : ''}`);
 	}