quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/plugin.js

@@ -0,0 +1,539 @@
+/**
+ * Plugin commands: org-scoped plugin install registry (PD-1..PD-8)
+ *
+ * quox plugin list|get|install|update|uninstall|mine
+ * quox plugin data list|get|set|delete
+ * quox plugin secrets list|set|reveal|delete
+ * quox plugin assign list|add|remove
+ * quox plugin trusted-keys list|add|remove
+ *
+ * Backend: services/auth/routes/plugins.js, mounted org-scoped at
+ * `/api/orgs/:orgId/...` (server.js). Install/update/uninstall and all
+ * secrets writes are admin-only per the PD stream's locked "admin-only
+ * install model" decision; read endpoints require org membership only.
+ */
+
+import { registerPluginDoctor } from './plugin-doctor.js';
+import { readFileSync } from 'node:fs';
+import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
+import { resolveOrgId, parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/** Read + JSON.parse a file, wrapping errors with the file path for context. */
+function readJsonFile(filePath, label) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    throw new Error(`Could not read ${label} file "${filePath}": ${err.message}`);
+  }
+  return parseJSON(raw, label);
+}
+
+/** Read a file and base64-encode its bytes (bundle_b64 / css_b64 shape). */
+function readBase64File(filePath, label) {
+  try {
+    return readFileSync(filePath).toString('base64');
+  } catch (err) {
+    throw new Error(`Could not read ${label} file "${filePath}": ${err.message}`);
+  }
+}
+
+/** Best-effort JSON parse for a data value; falls back to the raw string. */
+function coerceDataValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+async function confirmOrSkip(program, message) {
+  const { default: inquirer } = await import('inquirer');
+  const ans = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message, default: false }]);
+  return ans.confirm;
+}
+
+export function registerPluginCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const plugin = program
+    .command('plugin')
+    .description('Manage org-installed plugins');
+
+  registerPluginDoctor(plugin);
+
+  // ── plugin licence ──────────────────────────────────────────────────────────
+
+  plugin
+    .command('licence')
+    .alias('license')
+    .description('Show whether a plugin is licence governed and entitled for this org (band, org id, entitlement errors)')
+    .argument('<pluginId>', 'plugin id, e.g. notesq')
+    .action(async (pluginId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('setup.licensing.entitlements.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const entitlements = Array.isArray(data.entitlements) ? data.entitlements : [];
+      const governed = (Array.isArray(data.governed) ? data.governed : []).includes(pluginId);
+      const match = entitlements.find((e) => e === pluginId || String(e).startsWith(`${pluginId}@`)) || null;
+      // `entitlements` is the resolved (band-stripped) list; the band string lives on the licence itself.
+      const licenceEnts = (Array.isArray(data.licenses) ? data.licenses : []).flatMap((l) => (Array.isArray(l.entitlements) ? l.entitlements : []));
+      const banded = licenceEnts.find((e) => String(e).startsWith(`${pluginId}@`)) || null;
+      const bandInfo = (data.org_bands && data.org_bands[pluginId]) || null;
+      // A plugin outside the governed set is never licence gated (same rule as the server).
+      const entitled = governed ? match !== null : true;
+      const summary = {
+        plugin: pluginId,
+        governed,
+        entitled,
+        band: banded || (match && match.includes('@') ? match : null),
+        seats_used: bandInfo && typeof bandInfo.assigned_count === 'number' ? bandInfo.assigned_count : null,
+        seats_allowed: bandInfo && typeof bandInfo.allowance === 'number' ? bandInfo.allowance : null,
+        seat_holders: bandInfo && Array.isArray(bandInfo.assigned_orgs) ? bandInfo.assigned_orgs : [],
+        org_id: data.org_id || null,
+        org_licensed: bandInfo ? bandInfo.org_licensed ?? null : null,
+        entitlement_errors: Array.isArray(data.entitlement_errors) ? data.entitlement_errors : [],
+      };
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+      }
+      formatDetail({
+        plugin: summary.plugin,
+        governed: summary.governed ? 'yes' : 'no',
+        entitled: summary.entitled ? 'yes' : 'no',
+        band: summary.band || '(none)',
+        org_seats: summary.seats_allowed === null ? '(no band)' : `${summary.seats_used} of ${summary.seats_allowed} used`,
+        org_id: summary.org_id || '(instance scoped)',
+        org_licensed: summary.org_licensed === null ? '(unknown)' : summary.org_licensed ? 'yes' : 'no',
+        entitlement_errors: summary.entitlement_errors.length
+          ? summary.entitlement_errors.map((e) => (typeof e === 'string' ? e : JSON.stringify(e))).join('; ')
+          : '(none)',
+      }, { title: `Licence: ${pluginId}` });
+    });
+
+  // ── plugin list ─────────────────────────────────────────────────────────────
+
+  plugin
+    .command('list')
+    .description('List installed plugins for the active org')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.list', { orgId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const plugins = data.plugins || data || [];
+      formatOutput({
+        columns: ['plugin_id', 'version', 'is_enabled', 'installed_by', 'installed_at', 'upgraded_at'],
+        headers: ['Plugin ID', 'Version', 'Enabled', 'Installed By', 'Installed', 'Upgraded'],
+        rows: plugins,
+      }, { format: program.opts().output, emptyMessage: 'No plugins installed.' });
+    });
+
+  // ── plugin get ──────────────────────────────────────────────────────────────
+
+  plugin
+    .command('get')
+    .description('Show plugin install details')
+    .argument('<pluginId>', 'plugin ID (slug) or install-record id')
+    .action(async (pluginId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const getFor = (id) => {
+        const ep = resolveEndpoint('plugins.get', { orgId, pluginId: id });
+        return client.get(ep.path, { service: ep.service });
+      };
+      let resolvedId = pluginId;
+      let data;
+      try {
+        data = await getFor(resolvedId);
+      } catch (err) {
+        // quox-plugin-sdk#2(B): `plugin list --json` emits the install-record
+        // ULID as `id`, but get resolves by plugin_id (slug) and 404s on the
+        // ULID — so `plugin list --json | jq .id | xargs quox plugin get` broke.
+        // On a 404, treat the arg as an install id and map it to its plugin_id
+        // via the list, so BOTH identifiers round-trip. Slugs stay the fast path.
+        if (err && err.status === 404) {
+          const listEp = resolveEndpoint('plugins.list', { orgId });
+          const listData = await client.get(listEp.path, { service: listEp.service });
+          const rows = listData.plugins || listData || [];
+          const match = rows.find(p => p.id === pluginId || p.install_id === pluginId);
+          if (match && match.plugin_id && match.plugin_id !== pluginId) {
+            resolvedId = match.plugin_id;
+            data = await getFor(resolvedId);
+          } else {
+            throw err;
+          }
+        } else {
+          throw err;
+        }
+      }
+      formatDetail(data.plugin || data, {
+        format: program.opts().output,
+        title: `Plugin: ${resolvedId}`,
+        fields: ['id', 'plugin_id', 'version', 'is_enabled', 'bundle_sha256', 'installed_by', 'installed_at', 'upgraded_at', 'manifest', 'signature'],
+        labels: {
+          id: 'Install ID', plugin_id: 'Plugin ID', version: 'Version', is_enabled: 'Enabled',
+          bundle_sha256: 'Bundle SHA256', installed_by: 'Installed By', installed_at: 'Installed',
+          upgraded_at: 'Upgraded', manifest: 'Manifest', signature: 'Signature',
+        },
+      });
+    });
+
+  // ── plugin install ──────────────────────────────────────────────────────────
+
+  plugin
+    .command('install')
+    .description('Install a plugin (admin only)')
+    .requiredOption('--manifest <file>', 'path to a manifest JSON file (must include id, name, version)')
+    .requiredOption('--bundle <file>', 'path to the plugin bundle JS file')
+    .option('--css <file>', 'path to a CSS file for the plugin')
+    .option('--signature <file>', 'path to a signature JSON file (required if the org has trusted keys)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      const manifest = readJsonFile(options.manifest, '--manifest');
+      const body = { manifest, bundle_b64: readBase64File(options.bundle, '--bundle') };
+      if (options.css) body.css_b64 = readBase64File(options.css, '--css');
+      if (options.signature) body.signature = readJsonFile(options.signature, '--signature');
+
+      const ep = resolveEndpoint('plugins.install', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Plugin "${manifest.id}" installed.`);
+      formatDetail(data.plugin || data, { format: program.opts().output });
+    });
+
+  // ── plugin update ───────────────────────────────────────────────────────────
+
+  plugin
+    .command('update')
+    .description('Upgrade a plugin bundle and/or toggle its enabled state (admin only)')
+    .argument('<pluginId>', 'plugin ID')
+    .option('--enable', 'enable the plugin')
+    .option('--disable', 'disable the plugin')
+    .option('--manifest <file>', 'path to a new manifest JSON file (required together with --bundle)')
+    .option('--bundle <file>', 'path to a new bundle JS file (required together with --manifest)')
+    .option('--css <file>', 'path to a new CSS file')
+    .option('--signature <file>', 'path to a new signature JSON file')
+    .action(async (pluginId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (options.enable && options.disable) {
+        throw new Error('Specify only one of --enable or --disable.');
+      }
+
+      const body = {};
+      if (options.enable) body.is_enabled = true;
+      if (options.disable) body.is_enabled = false;
+
+      if (options.manifest || options.bundle) {
+        if (!options.manifest || !options.bundle) {
+          throw new Error('--manifest and --bundle must be provided together for an upgrade.');
+        }
+        body.manifest = readJsonFile(options.manifest, '--manifest');
+        body.bundle_b64 = readBase64File(options.bundle, '--bundle');
+        if (options.css) body.css_b64 = readBase64File(options.css, '--css');
+        if (options.signature) body.signature = readJsonFile(options.signature, '--signature');
+      }
+
+      if (Object.keys(body).length === 0) {
+        throw new Error('Specify --enable, --disable, or --manifest/--bundle to upgrade.');
+      }
+
+      const ep = resolveEndpoint('plugins.update', { orgId, pluginId });
+      const data = await client.patch(ep.path, { service: ep.service, body });
+      printSuccess('Plugin updated.');
+      formatDetail(data.plugin || data, { format: program.opts().output });
+    });
+
+  // ── plugin uninstall ────────────────────────────────────────────────────────
+
+  plugin
+    .command('uninstall')
+    .description('Uninstall a plugin (admin only)')
+    .argument('<pluginId>', 'plugin ID')
+    .option('--force', 'skip confirmation')
+    .action(async (pluginId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!options.force && !program.opts().yes) {
+        const ok = await confirmOrSkip(program, `Uninstall plugin ${pluginId}? This cannot be undone.`);
+        if (!ok) { printInfo('Cancelled.'); return; }
+      }
+
+      const ep = resolveEndpoint('plugins.uninstall', { orgId, pluginId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Plugin uninstalled.');
+    });
+
+  // ── plugin mine ─────────────────────────────────────────────────────────────
+
+  plugin
+    .command('mine')
+    .description('List plugins visible to the current user (respects assignments)')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.mine.list', { orgId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const plugins = data.plugins || data || [];
+      formatOutput({
+        columns: ['plugin_id', 'version', 'is_enabled', 'installed_at'],
+        headers: ['Plugin ID', 'Version', 'Enabled', 'Installed'],
+        rows: plugins,
+      }, { format: program.opts().output, emptyMessage: 'No plugins visible to you in this org.' });
+    });
+
+  // ── plugin data ─────────────────────────────────────────────────────────────
+
+  const data = plugin
+    .command('data')
+    .description('Manage plugin-scoped durable data (KV)');
+
+  data
+    .command('list')
+    .description('List data keys for a plugin')
+    .argument('<pluginId>', 'plugin ID')
+    .option('--scope <scope>', 'org|user', 'org')
+    .action(async (pluginId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.data.list', { orgId, pluginId });
+      const result = await client.get(ep.path, { service: ep.service, query: { scope: options.scope } });
+      const keys = result.keys || [];
+      if (keys.length === 0) {
+        printInfo('No data keys found.');
+        return;
+      }
+      formatOutput({ columns: ['key'], headers: ['Key'], rows: keys.map(key => ({ key })) }, { format: program.opts().output });
+    });
+
+  data
+    .command('get')
+    .description('Get a plugin data value')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<key>', 'data key')
+    .option('--scope <scope>', 'org|user', 'org')
+    .action(async (pluginId, key, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.data.get', { orgId, pluginId, key });
+      const row = await client.get(ep.path, { service: ep.service, query: { scope: options.scope } });
+      formatDetail(row, { format: program.opts().output });
+    });
+
+  data
+    .command('set')
+    .description('Set a plugin data value')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<key>', 'data key')
+    .requiredOption('--value <value>', 'value to store (JSON is parsed automatically; otherwise stored as a string)')
+    .option('--scope <scope>', 'org|user', 'org')
+    .action(async (pluginId, key, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.data.set', { orgId, pluginId, key });
+      const row = await client.put(ep.path, {
+        service: ep.service,
+        query: { scope: options.scope },
+        body: { value: coerceDataValue(options.value) },
+      });
+      printSuccess(`Data key "${key}" set.`);
+      formatDetail(row, { format: program.opts().output });
+    });
+
+  data
+    .command('delete')
+    .description('Delete a plugin data value')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<key>', 'data key')
+    .option('--scope <scope>', 'org|user', 'org')
+    .action(async (pluginId, key, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.data.delete', { orgId, pluginId, key });
+      await client.delete(ep.path, { service: ep.service, query: { scope: options.scope } });
+      printSuccess('Data key deleted.');
+    });
+
+  // ── plugin secrets ──────────────────────────────────────────────────────────
+
+  const secrets = plugin
+    .command('secrets')
+    .description('Manage plugin-scoped encrypted secrets');
+
+  secrets
+    .command('list')
+    .description('List secret metadata for a plugin (no plaintext)')
+    .argument('<pluginId>', 'plugin ID')
+    .action(async (pluginId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.secrets.list', { orgId, pluginId });
+      const result = await client.get(ep.path, { service: ep.service });
+      const rows = result.secrets || result || [];
+      formatOutput({
+        columns: ['name', 'description', 'created_by', 'created_at', 'rotated_at'],
+        headers: ['Name', 'Description', 'Created By', 'Created', 'Rotated'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No secrets set for this plugin.' });
+    });
+
+  secrets
+    .command('set')
+    .description('Set (or rotate) a plugin secret (admin only)')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<name>', 'secret name')
+    .requiredOption('--value <text>', 'secret value')
+    .option('--description <text>', 'secret description')
+    .action(async (pluginId, name, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { value: options.value };
+      if (options.description) body.description = options.description;
+      const ep = resolveEndpoint('plugins.secrets.set', { orgId, pluginId, name });
+      const result = await client.put(ep.path, { service: ep.service, body });
+      printSuccess(`Secret "${name}" set.`);
+      formatDetail(result.secret || result, { format: program.opts().output });
+    });
+
+  secrets
+    .command('reveal')
+    .description('Reveal a plugin secret\'s plaintext value (audited)')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<name>', 'secret name')
+    .action(async (pluginId, name) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      printWarning('This reveals a plaintext secret and is recorded in the audit log.');
+      const ep = resolveEndpoint('plugins.secrets.reveal', { orgId, pluginId, name });
+      const result = await client.post(ep.path, { service: ep.service });
+      formatDetail(result, { format: program.opts().output });
+    });
+
+  secrets
+    .command('delete')
+    .description('Delete a plugin secret (admin only)')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<name>', 'secret name')
+    .action(async (pluginId, name) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.secrets.delete', { orgId, pluginId, name });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Secret deleted.');
+    });
+
+  // ── plugin assign ───────────────────────────────────────────────────────────
+
+  const assign = plugin
+    .command('assign')
+    .description('Manage plugin visibility assignments (admin only)');
+
+  assign
+    .command('list')
+    .description('List assignments for a plugin')
+    .argument('<pluginId>', 'plugin ID')
+    .action(async (pluginId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.assignments.list', { orgId, pluginId });
+      const result = await client.get(ep.path, { service: ep.service });
+      const rows = result.assignments || result || [];
+      formatOutput({
+        columns: ['assignee_type', 'assignee_id', 'assigned_by', 'assigned_at'],
+        headers: ['Type', 'Assignee', 'Assigned By', 'Assigned'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No assignments set (plugin uses default visibility).' });
+    });
+
+  assign
+    .command('add')
+    .description('Assign a plugin to all org members, a user, or a team')
+    .argument('<pluginId>', 'plugin ID')
+    .requiredOption('--type <assigneeType>', 'all_org_members|user|team')
+    .option('--id <assigneeId>', 'assignee ID (user or team ID; omit for all_org_members)')
+    .action(async (pluginId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { assignee_type: options.type };
+      if (options.id) body.assignee_id = options.id;
+      const ep = resolveEndpoint('plugins.assignments.create', { orgId, pluginId });
+      const result = await client.post(ep.path, { service: ep.service, body });
+      printSuccess('Assignment added.');
+      formatDetail(result.assignment || result, { format: program.opts().output });
+    });
+
+  assign
+    .command('remove')
+    .description('Remove a plugin assignment')
+    .argument('<pluginId>', 'plugin ID')
+    .argument('<assigneeType>', 'all_org_members|user|team')
+    .argument('[assigneeId]', 'assignee ID (omit for all_org_members)')
+    .action(async (pluginId, assigneeType, assigneeId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.assignments.delete', { orgId, pluginId, assigneeType, assigneeId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Assignment removed.');
+    });
+
+  // ── plugin trusted-keys ─────────────────────────────────────────────────────
+
+  const trustedKeys = plugin
+    .command('trusted-keys')
+    .description('Manage per-org trusted Ed25519 signing keys (admin only)');
+
+  trustedKeys
+    .command('list')
+    .description('List trusted keys')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.trusted-keys.list', { orgId });
+      const result = await client.get(ep.path, { service: ep.service });
+      const rows = result.trusted_keys || result || [];
+      formatOutput({
+        columns: ['id', 'label', 'public_key_hex', 'added_by', 'added_at'],
+        headers: ['ID', 'Label', 'Public Key', 'Added By', 'Added'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No trusted keys configured (unsigned installs are accepted).' });
+    });
+
+  trustedKeys
+    .command('add')
+    .description('Add a trusted signing key')
+    .requiredOption('--label <label>', 'key label')
+    .requiredOption('--public-key <hex>', 'Ed25519 public key, hex-encoded')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { label: options.label, public_key_hex: options.publicKey };
+      const ep = resolveEndpoint('plugins.trusted-keys.create', { orgId });
+      const result = await client.post(ep.path, { service: ep.service, body });
+      printSuccess('Trusted key added.');
+      formatDetail(result.trusted_key || result, { format: program.opts().output });
+    });
+
+  trustedKeys
+    .command('remove')
+    .description('Remove a trusted signing key')
+    .argument('<keyId>', 'trusted key ID')
+    .option('--confirm-unsigned', 'WARNING: required to remove the LAST trusted key; the org will then accept UNSIGNED plugin bundles')
+    .action(async (keyId, opts) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.trusted-keys.delete', { orgId, keyId });
+      const reqOpts = { service: ep.service };
+      if (opts && opts.confirmUnsigned) {
+        console.error('WARNING: confirming downgrade. This org will accept UNSIGNED plugin bundles after this key is removed.');
+        reqOpts.query = { confirm_unsigned: '1' };
+      }
+      await client.delete(ep.path, reqOpts);
+      printSuccess('Trusted key removed.');
+    });
+}

package/lib/commands/policy.js

@@ -0,0 +1,78 @@
+/**
+ * `quox policy` — the governance compiler from the terminal (OPGOV quox#582).
+ *
+ * compile: plain-language rule -> deterministic quox-policy.v1 DRAFT, with
+ * the compiled policy printed in full for review (a policy nobody read is
+ * not governance). arm: moves a reviewed draft to armed; the collector
+ * refuses arming without a logged-in human. Honesty: enforcement is phase 3
+ * (IMPACT #491) and is NOT wired; an armed policy is a reviewed intent, not
+ * yet a running gate, and this command says so.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+function isJsonOutput(program) {
+  const o = program.opts();
+  return o.json === true || o.output === 'json';
+}
+
+const NOT_ENFORCED_NOTE = 'note: enforcement is phase 3 (IMPACT #491) and is not wired yet; armed = reviewed intent, not a running gate.';
+
+export function registerPolicyCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const p = program
+    .command('policy')
+    .description('Governance compiler: plain-language rule -> reviewed, armable policy (OPGOV)');
+
+  p.command('compile <rule>')
+    .description('Compile a plain-language rule to a quox-policy.v1 draft (deterministic grammar; out-of-grammar rules are refused, never approximated)')
+    .action(async (rule) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.compile', { orgId });
+      try {
+        const data = await client.post(ep.path, { service: ep.service, body: { rule } });
+        if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+        const rec = data.record;
+        console.log(`compiled DRAFT ${rec.id} (${rec.policy.effect})`);
+        console.log(JSON.stringify(rec.policy, null, 2));
+        console.log(`review it, then: quox policy arm ${rec.id}`);
+        console.log(NOT_ENFORCED_NOTE);
+      } catch (err) {
+        const msg = err?.message || String(err);
+        if (/422|unknown/i.test(msg)) {
+          console.log('NOT COMPILED: the rule is outside the deterministic grammar and was refused rather than approximated.');
+        }
+        throw err;
+      }
+    });
+
+  p.command('list')
+    .description('List compiled policies for this org')
+    .option('--state <s>', 'draft | armed | retired')
+    .action(async (opts) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.list', { orgId, state: opts.state });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const items = data.policies || [];
+      if (!items.length) { console.log('No policies. Compile one: quox policy compile "<rule>"'); return; }
+      for (const r of items) {
+        console.log(`${r.id}  [${r.state}]  ${r.policy?.effect ?? '?'}  ${r.rule_text}${r.approved_by ? `  (armed by ${r.approved_by})` : ''}`);
+      }
+      console.log(NOT_ENFORCED_NOTE);
+    });
+
+  p.command('arm <id>')
+    .description('Arm a reviewed draft (requires a logged-in human; service keys are refused by design)')
+    .action(async (id) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.arm', { orgId, id });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const rec = data.record;
+      console.log(`ARMED ${rec.id} (${rec.policy.effect}) approved by ${rec.approved_by}`);
+      console.log(NOT_ENFORCED_NOTE);
+    });
+}