osuite 2.9.0 → 2.9.1

package/cli.js

@@ -1,129 +1,417 @@
 #!/usr/bin/env node
 
-import pkg from './package.json' with { type: 'json' };
-import { OSuite } from './osuite.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OSuite, buildReviewSurface } from './osuite.js';
 
-function printHelp() {
-  process.stdout.write(`OSuite CLI v${pkg.version}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+const PROTECTED_REFS = new Set(['main', 'master', 'prod', 'production', 'stable']);
+const OBSERVE_OPS = new Set(['get', 'describe', 'logs', 'top', 'version', 'diff']);
+const PLAN_OPS = new Set(['plan', 'show', 'validate', 'output', 'fmt', 'providers', 'graph']);
+const MUTATION_OPS = new Set(['apply', 'destroy', 'delete', 'create', 'replace', 'taint', 'untaint', 'import', 'upgrade', 'rollback', 'install', 'uninstall']);
 
-Usage:
-  osuite help
-  osuite version
-  osuite approvals [--limit 20] [--offset 0]
-  osuite approve <actionId> [--reason "Approved by operator"]
-  osuite deny <actionId> [--reason "Outside change window"]
+function useColor() {
+  return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+
+function c(value, color) {
+  return useColor() ? `${color}${value}${ANSI.reset}` : value;
+}
 
-Environment:
-  OSUITE_BASE_URL     Required, your OSuite base URL
-  OSUITE_URL          Optional fallback for hosted/base URL
-  NEXTAUTH_URL        Optional fallback when reusing app env files
-  OSUITE_API_KEY      Required, admin API key for approval operations
-  OSUITE_AGENT_ID     Optional, defaults to "osuite-cli"
-`);
+function write(value = '') {
+  process.stdout.write(`${value}\n`);
 }
 
 function parseArgs(argv) {
   const [command = 'help', ...rest] = argv;
   const args = { _: [] };
-
-  for (let i = 0; i < rest.length; i += 1) {
-    const token = rest[i];
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
     if (token.startsWith('--')) {
       const key = token.slice(2);
-      const next = rest[i + 1];
-      if (!next || next.startsWith('--')) {
-        args[key] = true;
-      } else {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('--')) args[key] = true;
+      else {
         args[key] = next;
-        i += 1;
+        index += 1;
       }
-      continue;
+    } else {
+      args._.push(token);
     }
-    args._.push(token);
   }
-
   return { command, args };
 }
 
-function getClient() {
-  const baseUrl = process.env.OSUITE_BASE_URL
-    || process.env.DASHCLAW_BASE_URL
-    || process.env.OSUITE_URL
-    || process.env.DASHCLAW_URL
-    || process.env.NEXTAUTH_URL;
-  const apiKey = process.env.OSUITE_API_KEY || process.env.DASHCLAW_API_KEY;
-  const agentId = process.env.OSUITE_AGENT_ID || process.env.DASHCLAW_AGENT_ID || 'osuite-cli';
+function envValue(name, fallback) {
+  return process.env[name] || process.env[fallback] || '';
+}
+
+function readConfig() {
+  return {
+    baseUrl: envValue('OSUITE_BASE_URL', 'DASHCLAW_BASE_URL'),
+    apiKey: envValue('OSUITE_API_KEY', 'DASHCLAW_API_KEY'),
+    agentId: envValue('OSUITE_AGENT_ID', 'DASHCLAW_AGENT_ID') || 'osuite-cli',
+    runtimeAdapterId: process.env.OSUITE_RUNTIME_ADAPTER_ID || '',
+    signatureMode: process.env.OSUITE_SIGNATURE_MODE || '',
+  };
+}
 
-  if (!baseUrl || !apiKey) {
-    process.stderr.write('Missing a base URL env (OSUITE_BASE_URL / OSUITE_URL / NEXTAUTH_URL) or OSUITE_API_KEY.\n');
+function requireClient() {
+  const config = readConfig();
+  if (!config.baseUrl || !config.apiKey) {
+    write(c('OSuite is not connected yet.', ANSI.yellow));
+    write('Set OSUITE_BASE_URL and OSUITE_API_KEY, or run:');
+    write('  osuite init');
     process.exit(1);
   }
+  return new OSuite(config);
+}
 
-  return new OSuite({ baseUrl, apiKey, agentId });
+function banner() {
+  return [
+    c('OSUITE', `${ANSI.bold}${ANSI.cyan}`),
+    c('Governed action layer for AI agents', ANSI.bold),
+    c('PCAA authority  |  CAVA action understanding  |  Decision V2 review', ANSI.dim),
+  ].join('\n');
 }
 
-async function listApprovals(args) {
-  const client = getClient();
-  const limit = Number.parseInt(args.limit || '20', 10);
-  const offset = Number.parseInt(args.offset || '0', 10);
-  const result = await client.getPendingApprovals(limit, offset);
-  const actions = result.actions || [];
+function printHelp() {
+  write(banner());
+  write('');
+  write(c(`OSuite CLI v${pkg.version}`, ANSI.dim));
+  write('');
+  write(c('Useful commands', ANSI.bold));
+  write('  osuite doctor                         Check connection, runtime, signatures, package health');
+  write('  osuite status                         Ping Studio and show current workspace connection');
+  write('  osuite explain "git push origin main" Explain how CAVA/Decision V2 will read a command');
+  write('  osuite approvals --limit 20           Show pending approval inbox');
+  write('  osuite review <actionId>              Render the decision review card');
+  write('  osuite approve <actionId> --reason "Looks safe"');
+  write('  osuite deny <actionId> --reason "Outside change window"');
+  write('  osuite init [codex|claude|mcp]        Print setup steps for a runtime lane');
+  write('');
+  write(c('Environment', ANSI.bold));
+  write('  OSUITE_BASE_URL     Studio URL, for example https://studio.osuite.ai');
+  write('  OSUITE_API_KEY      Workspace or admin API key');
+  write('  OSUITE_AGENT_ID     Optional actor label for CLI actions');
+  write('');
+  write(c('Old DASHCLAW_* environment names are still accepted for compatibility.', ANSI.dim));
+}
 
-  if (actions.length === 0) {
-    process.stdout.write('No pending approvals.\n');
-    return;
+function tokenize(command) {
+  return String(command || '').match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) || [];
+}
+
+function protectedGitTarget(tokens) {
+  if (tokens[0] !== 'git' || tokens[1] !== 'push') return null;
+  const refs = tokens.slice(2).filter((token) => !token.startsWith('-') && token !== 'origin' && !token.includes(':'));
+  const target = refs[0] || 'unknown';
+  const normalized = target.replace(/^refs\/heads\//, '');
+  if (PROTECTED_REFS.has(normalized) || normalized.startsWith('release/') || normalized.includes('prod')) return normalized;
+  return null;
+}
+
+function classifyCommand(command) {
+  const tokens = tokenize(command);
+  const executable = tokens[0] || '';
+  const operation = tokens[1] || '';
+
+  if (!tokens.length) {
+    return { category: 'unknown', operation: 'unknown', risk: 20, reversible: true, summary: 'No command provided.' };
   }
 
-  for (const action of actions) {
-    process.stdout.write(
-      `${action.action_id}\t${action.agent_name || action.agent_id}\t${action.action_type}\t${action.declared_goal || '-'}\n`
-    );
+  if (executable === 'git' && operation === 'push') {
+    const protectedTarget = protectedGitTarget(tokens);
+    const target = protectedTarget || tokens.filter((token) => !token.startsWith('-')).at(-1) || 'remote';
+    return {
+      category: 'deployment',
+      operation: 'push',
+      risk: protectedTarget ? 82 : 58,
+      reversible: false,
+      systems: ['git', 'remote_repository'],
+      summary: protectedTarget
+        ? `Git push to protected target ${protectedTarget}.`
+        : `Git push to ${target}.`,
+      notes: protectedTarget ? ['protected target', 'approval recommended before side effects'] : ['feature branch target'],
+    };
   }
-}
 
-async function decide(actionId, decision, args) {
-  if (!actionId) {
-    process.stderr.write('Missing actionId.\n');
-    process.exit(1);
+  if (executable === 'npm' && operation === 'run' && tokens[2] === 'build') {
+    return {
+      category: 'build',
+      operation: 'build',
+      risk: 30,
+      reversible: true,
+      systems: ['local_workspace'],
+      summary: 'Local build or compilation step.',
+      notes: ['usually does not require approval unless chained with deployment'],
+    };
   }
 
-  const client = getClient();
-  const result = await client.approveAction(actionId, decision, args.reason || args.reasoning);
-  process.stdout.write(`${decision === 'allow' ? 'Approved' : 'Denied'} ${actionId}\n`);
-  if (result?.action?.status) {
-    process.stdout.write(`New status: ${result.action.status}\n`);
+  if (['kubectl', 'helm', 'terraform', 'pulumi', 'ansible'].includes(executable)) {
+    const op = operation || 'unknown';
+    if (OBSERVE_OPS.has(op)) {
+      return {
+        category: 'observation',
+        operation: op,
+        risk: 28,
+        reversible: true,
+        systems: [executable],
+        summary: `${executable} observation command.`,
+        notes: ['read-oriented runtime action'],
+      };
+    }
+    if (PLAN_OPS.has(op)) {
+      return {
+        category: 'infrastructure_plan',
+        operation: op,
+        risk: 38,
+        reversible: true,
+        systems: [executable],
+        summary: `${executable} planning command.`,
+        notes: ['plan evidence can improve approval confidence'],
+      };
+    }
+    if (MUTATION_OPS.has(op)) {
+      return {
+        category: 'infrastructure_change',
+        operation: op,
+        risk: op === 'apply' || op === 'destroy' ? 90 : 78,
+        reversible: false,
+        systems: [executable],
+        summary: `${executable} infrastructure mutation.`,
+        notes: ['approval recommended', 'capture plan/output as evidence'],
+      };
+    }
+  }
+
+  if (executable === 'az' && tokens[1] === 'keyvault' && tokens[2] === 'secret') {
+    return {
+      category: 'secret_access',
+      operation: tokens[3] || 'secret',
+      risk: 74,
+      reversible: true,
+      systems: ['azure_key_vault'],
+      summary: 'Azure Key Vault secret access.',
+      notes: ['sensitive read', 'approval may be required by policy'],
+    };
+  }
+
+  if (['rm', 'drop', 'truncate'].some((prefix) => String(command).toLowerCase().includes(prefix))) {
+    return {
+      category: 'destructive_operation',
+      operation: executable,
+      risk: 92,
+      reversible: false,
+      systems: ['workspace'],
+      summary: 'Potentially destructive operation.',
+      notes: ['approval strongly recommended'],
+    };
   }
+
+  return {
+    category: 'shell_command',
+    operation: executable,
+    risk: 45,
+    reversible: null,
+    systems: ['shell'],
+    summary: 'General shell command. OSuite will use runtime context and policy to decide.',
+    notes: ['provide declared_goal and evidence for better scoring'],
+  };
 }
 
-async function main() {
-  const { command, args } = parseArgs(process.argv.slice(2));
+function riskBand(score) {
+  if (score >= 75) return 'High';
+  if (score >= 45) return 'Moderate';
+  return 'Low';
+}
 
-  if (command === 'help' || command === '--help' || command === '-h') {
-    printHelp();
-    return;
+function printExplanation(command) {
+  const result = classifyCommand(command);
+  const band = riskBand(result.risk);
+  const bandColor = band === 'High' ? ANSI.red : band === 'Moderate' ? ANSI.yellow : ANSI.green;
+
+  write(c('OSuite CAVA explanation', `${ANSI.bold}${ANSI.cyan}`));
+  write(c('Local preview. No server call was made.', ANSI.dim));
+  write('');
+  write(`Command              ${command}`);
+  write(`Category             ${result.category}`);
+  write(`Operation            ${result.operation}`);
+  write(`Risk                 ${c(`${band} (${result.risk}/100)`, bandColor)}`);
+  write(`Reversible           ${result.reversible === null ? 'unknown' : String(result.reversible)}`);
+  write(`Systems touched      ${(result.systems || []).join(', ') || 'unknown'}`);
+  write(`OSuite understood    ${result.summary}`);
+  if (result.notes?.length) {
+    write('');
+    write(c('Decision hints', ANSI.bold));
+    result.notes.forEach((note) => write(`  - ${note}`));
   }
+}
 
-  if (command === 'version' || command === '--version' || command === '-v') {
-    process.stdout.write(`${pkg.version}\n`);
-    return;
+async function doctor() {
+  const config = readConfig();
+  let ok = true;
+
+  write(c('OSuite Doctor', `${ANSI.bold}${ANSI.cyan}`));
+  write(c('Checking the local developer entry point.', ANSI.dim));
+  write('');
+
+  const checks = [
+    ['OSUITE_BASE_URL', Boolean(config.baseUrl), config.baseUrl || 'missing'],
+    ['OSUITE_API_KEY', Boolean(config.apiKey), config.apiKey ? 'present' : 'missing'],
+    ['OSUITE_AGENT_ID', Boolean(config.agentId), config.agentId || 'osuite-cli'],
+    ['Runtime adapter', Boolean(config.runtimeAdapterId), config.runtimeAdapterId || 'not declared'],
+    ['Signature mode', Boolean(config.signatureMode), config.signatureMode || 'not declared'],
+  ];
+
+  checks.forEach(([label, passed, detail]) => {
+    if (!passed && (label === 'OSUITE_BASE_URL' || label === 'OSUITE_API_KEY')) ok = false;
+    write(`${passed ? c('OK ', ANSI.green) : c('MISS', ANSI.yellow)}  ${label.padEnd(18)} ${detail}`);
+  });
+
+  if (config.baseUrl) {
+    try {
+      const response = await fetch(`${config.baseUrl.replace(/\/$/, '')}/api/health`);
+      const body = await response.text();
+      const healthy = response.ok && body.includes('healthy');
+      ok = ok && healthy;
+      write(`${healthy ? c('OK ', ANSI.green) : c('WARN', ANSI.yellow)}  ${'Studio health'.padEnd(18)} HTTP ${response.status}`);
+    } catch (error) {
+      ok = false;
+      write(`${c('FAIL', ANSI.red)}  ${'Studio health'.padEnd(18)} ${error.message}`);
+    }
   }
 
-  if (command === 'approvals') {
-    await listApprovals(args);
-    return;
+  write('');
+  if (!ok) {
+    write(c('Next step', ANSI.bold));
+    write('  osuite init');
+    write('  export OSUITE_BASE_URL=https://studio.osuite.ai');
+    write('  export OSUITE_API_KEY=<workspace-api-key>');
+    process.exit(1);
   }
 
-  if (command === 'approve') {
-    await decide(args._[0], 'allow', args);
+  write(c('Your OSuite CLI is ready.', ANSI.green));
+}
+
+async function status() {
+  const config = readConfig();
+  write(c('OSuite Status', `${ANSI.bold}${ANSI.cyan}`));
+  write(`Base URL             ${config.baseUrl || 'not configured'}`);
+  write(`Agent ID             ${config.agentId}`);
+  write(`Runtime adapter      ${config.runtimeAdapterId || 'not declared'}`);
+  if (!config.baseUrl) return;
+
+  const response = await fetch(`${config.baseUrl.replace(/\/$/, '')}/api/health`);
+  write(`Studio health        HTTP ${response.status}`);
+}
+
+function renderActionRow(action) {
+  const id = action.action_id || action.id || '-';
+  const score = action.risk_score ?? action.agent_risk_score ?? '-';
+  const type = action.action_type || '-';
+  const agent = action.agent_name || action.agent_id || '-';
+  const goal = action.declared_goal || action.input_summary || '-';
+  return `${id.padEnd(18)} ${String(score).padStart(3)}  ${type.padEnd(24)} ${agent.padEnd(18)} ${goal}`;
+}
+
+async function approvals(args) {
+  const client = requireClient();
+  const limit = Number.parseInt(args.limit || '20', 10);
+  const offset = Number.parseInt(args.offset || '0', 10);
+  const payload = await client.getPendingApprovals(limit, offset);
+  const actions = payload.actions || [];
+
+  write(c('OSuite Approval Inbox', `${ANSI.bold}${ANSI.cyan}`));
+  write(c('Actions waiting for human authority.', ANSI.dim));
+  write('');
+
+  if (!actions.length) {
+    write('No pending approvals.');
     return;
   }
 
-  if (command === 'deny') {
-    await decide(args._[0], 'deny', args);
-    return;
+  write(`${'Action ID'.padEnd(18)} ${'Risk'.padStart(3)}  ${'Type'.padEnd(24)} ${'Agent'.padEnd(18)} Goal`);
+  actions.forEach((action) => write(renderActionRow(action)));
+}
+
+async function review(actionId) {
+  if (!actionId) {
+    write('Missing actionId. Usage: osuite review <actionId>');
+    process.exit(1);
+  }
+  const client = requireClient();
+  const payload = await client.getAction(actionId);
+  const action = payload.action || payload;
+  write(buildReviewSurface(action, { baseUrl: client.baseUrl }));
+}
+
+async function decide(actionId, decision, args) {
+  if (!actionId) {
+    write(`Missing actionId. Usage: osuite ${decision === 'allow' ? 'approve' : 'deny'} <actionId>`);
+    process.exit(1);
   }
+  const client = requireClient();
+  const result = await client.approveAction(actionId, decision, args.reason || args.reasoning);
+  const label = decision === 'allow' ? 'Approved' : 'Denied';
+  write(c(`${label} ${actionId}`, decision === 'allow' ? ANSI.green : ANSI.red));
+  if (result?.action?.status) write(`New status           ${result.action.status}`);
+}
+
+function init(target = 'generic') {
+  write(c('OSuite init', `${ANSI.bold}${ANSI.cyan}`));
+  write('Paste these into your shell, then run `osuite doctor`:');
+  write('');
+  write('export OSUITE_BASE_URL=https://studio.osuite.ai');
+  write('export OSUITE_API_KEY=<workspace-api-key>');
+  write('export OSUITE_AGENT_ID=<agent-or-runtime-id>');
+  write('');
+
+  if (target === 'codex') {
+    write(c('Codex runtime lane', ANSI.bold));
+    write('  osuite doctor');
+    write('  npm run runtime:install:codex-plugin');
+  } else if (target === 'claude') {
+    write(c('Claude Code runtime lane', ANSI.bold));
+    write('  export OSUITE_RUNTIME_ADAPTER_ID=claude_code_hooks');
+    write('  export OSUITE_SIGNATURE_MODE=required');
+  } else if (target === 'mcp') {
+    write(c('MCP runtime lane', ANSI.bold));
+    write('  Use OSuite preflight, wait-for-approval, and complete-action tools around consequential actions.');
+  }
+}
+
+async function main() {
+  const { command, args } = parseArgs(process.argv.slice(2));
+
+  if (['help', '--help', '-h'].includes(command)) return printHelp();
+  if (['version', '--version', '-v'].includes(command)) return write(pkg.version);
+  if (command === 'doctor') return doctor();
+  if (command === 'status') return status();
+  if (command === 'explain') return printExplanation(args._.join(' '));
+  if (command === 'approvals') return approvals(args);
+  if (command === 'review') return review(args._[0]);
+  if (command === 'approve') return decide(args._[0], 'allow', args);
+  if (command === 'deny') return decide(args._[0], 'deny', args);
+  if (command === 'init') return init(args._[0] || 'generic');
 
-  process.stderr.write(`Unknown command: ${command}\n\n`);
+  write(`Unknown command: ${command}`);
+  write('');
   printHelp();
   process.exit(1);
 }