auramaxx 0.0.1

package/server/cli/commands/skill.ts

@@ -0,0 +1,216 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import readline from 'readline';
+
+type TargetKey = 'codex' | 'claude' | 'openclaw';
+
+type Target = {
+  key: TargetKey;
+  name: string;
+  dir: string;
+};
+
+type InstallResult = {
+  target: Target;
+  status: 'installed' | 'updated' | 'missing-source' | 'failed';
+  detail?: string;
+};
+
+const root = path.join(__dirname, '..', '..', '..');
+
+function parseArgs(argv: string[]) {
+  const flags = new Set(argv);
+  if (flags.has('--help') || flags.has('-h')) {
+    console.log('Usage: npx auramaxx skill [--all|--claude|--codex|--openclaw] [--doctor] [--yes]');
+    process.exit(0);
+  }
+
+  return {
+    doctor: flags.has('--doctor'),
+    yes: flags.has('--yes') || flags.has('-y'),
+    claude: flags.has('--claude'),
+    codex: flags.has('--codex'),
+    openclaw: flags.has('--openclaw'),
+    all: flags.has('--all'),
+  };
+}
+
+function resolveTargets(): Target[] {
+  const home = os.homedir();
+  return [
+    { key: 'codex', name: 'Codex', dir: path.join(process.env.CODEX_HOME || path.join(home, '.codex'), 'skills', 'auramaxx') },
+    { key: 'claude', name: 'Claude', dir: path.join(process.env.CLAUDE_HOME || path.join(home, '.claude'), 'skills', 'auramaxx') },
+    { key: 'openclaw', name: 'OpenClaw', dir: path.join(process.env.OPENCLAW_HOME || path.join(home, '.openclaw'), 'skills', 'auramaxx') },
+  ];
+}
+
+function sourceDir(): string {
+  return path.join(root, 'skills', 'auramaxx');
+}
+
+function sourceAvailable(): boolean {
+  return fs.existsSync(path.join(sourceDir(), 'SKILL.md'));
+}
+
+function inspectTarget(target: Target) {
+  const skillPath = path.join(target.dir, 'SKILL.md');
+  return fs.existsSync(skillPath) ? 'installed' : 'missing';
+}
+
+const HEARTBEAT_MARKER = '<!-- auramaxx-heartbeat -->';
+
+function getOpenClawWorkspaces(): string[] {
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const configPath = path.join(openclawHome, 'openclaw.json');
+
+  const workspaces = new Set<string>();
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+    // Default workspace
+    if (config?.agents?.defaults?.workspace) {
+      workspaces.add(config.agents.defaults.workspace);
+    }
+
+    // Per-agent workspaces
+    if (Array.isArray(config?.agents?.list)) {
+      for (const agent of config.agents.list) {
+        if (agent.workspace) workspaces.add(agent.workspace);
+      }
+    }
+  } catch { /* no config or unreadable */ }
+
+  // Fallback: ~/.openclaw/workspace (legacy default)
+  if (workspaces.size === 0) {
+    workspaces.add(path.join(openclawHome, 'workspace'));
+  }
+
+  return [...workspaces];
+}
+
+function patchHeartbeatFile(heartbeatPath: string): boolean {
+  let existing = '';
+  try {
+    existing = fs.readFileSync(heartbeatPath, 'utf-8');
+  } catch { /* file doesn't exist yet */ }
+
+  if (existing.includes(HEARTBEAT_MARKER)) return false;
+
+  const section = [
+    '',
+    HEARTBEAT_MARKER,
+    '## AuraMaxx (every heartbeat)',
+    '1. Call `GET /what_is_happening` (add `?since=<last_timestamp_ms>` if you have one)',
+    '2. Review: `highlights` → `humanActions` → `recentEvents` → `syncHealth`',
+    '3. If anything urgent (pending approvals, sync errors, unexpected credential access): report it',
+    '4. Write a diary entry: use MCP `write_diary` or `npx auramaxx diary write --entry "..."`',
+    '5. If diary write fails with auth/approval issues: ask human to open approval link, then retry once',
+    '6. If nothing happened and 12h+ since last human update: send a short all-clear',
+    '7. Reply HEARTBEAT_OK if no follow-up needed',
+    '',
+  ].join('\n');
+
+  fs.mkdirSync(path.dirname(heartbeatPath), { recursive: true });
+  fs.appendFileSync(heartbeatPath, section);
+  return true;
+}
+
+function patchOpenClawHeartbeat(target: Target): void {
+  if (target.key !== 'openclaw') return;
+
+  const workspaces = getOpenClawWorkspaces();
+  for (const ws of workspaces) {
+    const heartbeatPath = path.join(ws, 'HEARTBEAT.md');
+    if (patchHeartbeatFile(heartbeatPath)) {
+      console.log(`  ↳ Patched ${heartbeatPath} with AuraMaxx heartbeat section`);
+    }
+  }
+}
+
+function installTarget(target: Target): InstallResult {
+  if (!sourceAvailable()) {
+    return { target, status: 'missing-source', detail: `Missing source at ${sourceDir()}` };
+  }
+
+  const targetSkill = path.join(target.dir, 'SKILL.md');
+  const alreadyInstalled = fs.existsSync(targetSkill);
+
+  try {
+    fs.mkdirSync(path.dirname(target.dir), { recursive: true });
+    fs.cpSync(sourceDir(), target.dir, { recursive: true, force: true });
+    patchOpenClawHeartbeat(target);
+    return { target, status: alreadyInstalled ? 'updated' : 'installed' };
+  } catch (err: unknown) {
+    return { target, status: 'failed', detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function chooseTargets(allTargets: Target[], args: ReturnType<typeof parseArgs>): Target[] {
+  const explicit: TargetKey[] = [];
+  if (args.codex) explicit.push('codex');
+  if (args.claude) explicit.push('claude');
+  if (args.openclaw) explicit.push('openclaw');
+  if (args.all || explicit.length === 0) return allTargets;
+  return allTargets.filter((t) => explicit.includes(t.key));
+}
+
+function askYesNo(prompt: string): Promise<boolean> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const v = answer.trim().toLowerCase();
+      resolve(v === 'y' || v === 'yes');
+    });
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targets = resolveTargets();
+
+  if (args.doctor) {
+    console.log('Aura skill doctor');
+    for (const target of targets) {
+      const state = inspectTarget(target);
+      console.log(`- ${target.name}: ${state} (${target.dir})`);
+    }
+    return;
+  }
+
+  const selected = chooseTargets(targets, args);
+
+  if (!args.yes && process.stdin.isTTY && !args.all && !args.codex && !args.claude && !args.openclaw) {
+    const doAll = await askYesNo('Install AuraMaxx skill for all compatible agents (Codex, Claude, OpenClaw)? [y/N] ');
+    if (!doAll) {
+      console.log('No changes made. Run one of:');
+      console.log('  npx auramaxx skill --codex');
+      console.log('  npx auramaxx skill --claude');
+      console.log('  npx auramaxx skill --openclaw');
+      console.log('Fallback: cd <your-codebase> && npx -y skills add Aura-Industry/auramaxx');
+      process.exit(0);
+    }
+  }
+
+  const results = selected.map(installTarget);
+
+  for (const result of results) {
+    const suffix = result.detail ? ` — ${result.detail}` : '';
+    console.log(`- ${result.target.name}: ${result.status}${suffix}`);
+  }
+
+  const failed = results.filter((r) => r.status === 'failed' || r.status === 'missing-source');
+  if (failed.length > 0) {
+    console.log('Some targets failed. Fallback: cd <your-codebase> && npx -y skills add Aura-Industry/auramaxx');
+    process.exit(1);
+  }
+
+  console.log('Done. Verify with: npx auramaxx skill --doctor');
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/server/cli/commands/start.ts

@@ -0,0 +1,139 @@
+/**
+ * auramaxx start — Start wallet servers
+ */
+
+import { isServerRunning, waitForServer } from '../lib/http';
+import { startServer, stopServer } from '../lib/process';
+import { getErrorMessage } from '../../lib/error';
+import { printBanner, printStatus, printHelp } from '../lib/theme';
+import { isServiceInstalled, isServiceRunning, loadServiceIfNeeded } from './service';
+
+export interface StartCliArgs {
+  headless: boolean;
+  background: boolean;
+  debug: boolean;
+  help: boolean;
+}
+
+export function parseStartArgs(argv: string[]): StartCliArgs {
+  const args = new Set(argv);
+  return {
+    headless: args.has('--headless'),
+    background: args.has('--background') || args.has('--daemon') || args.has('-d'),
+    debug: args.has('--debug'),
+    help: args.has('--help') || args.has('-h'),
+  };
+}
+
+function showHelp(): void {
+  printHelp('START', 'npx auramaxx start [options]', [], [
+    'Options:',
+    '  --headless               Start server + cron only (no dashboard)',
+    '  --background, --daemon   Start detached in background mode',
+    '  -d                       Short alias for --background',
+    '  --debug                  Stream runtime logs in console (foreground only)',
+  ]);
+}
+
+export async function runStartCli(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const parsed = parseStartArgs(argv);
+  if (parsed.help) {
+    showHelp();
+    return 0;
+  }
+
+  const streamLogs = parsed.debug && !parsed.background;
+
+  // If server is already running (e.g. via launchd), just print status and exit.
+  // If the launchd service was just installed, it may still be bootstrapping —
+  // give it a moment before falling through to manual start.
+  let alreadyRunning = await isServerRunning();
+  if (!alreadyRunning && isServiceInstalled()) {
+    if (!isServiceRunning()) {
+      // Plist exists but service isn't loaded (e.g. after `auramaxx stop`).
+      // Re-load it so it's registered for future reboots, then start manually.
+      loadServiceIfNeeded();
+    } else {
+      // Service is loaded — launchd may be starting the server right now.
+      // Wait briefly rather than spawning a duplicate.
+      try {
+        await waitForServer(30000);
+        alreadyRunning = true;
+      } catch {
+        // Service didn't bring the server up — fall through to manual start
+      }
+    }
+  }
+  if (alreadyRunning) {
+    printBanner('RUNNING');
+    const serviceInstalled = isServiceInstalled();
+    const modeLabel = serviceInstalled ? 'BACKGROUND SERVICE' : 'BACKGROUND PROCESS';
+    printStatus('Mode', modeLabel);
+    printStatus('API (server)', 'http://localhost:4242');
+    printStatus('Dashboard', parsed.headless ? 'disabled' : 'http://localhost:4747');
+    printStatus('Stop', 'auramaxx stop');
+    console.log('');
+    return 0;
+  }
+
+  // Always start in background — launchd/systemd manages the lifecycle.
+  // Use `--debug` for foreground streaming.
+  const background = !streamLogs;
+
+  printBanner(parsed.headless ? 'HEADLESS' : 'STARTING');
+
+  // Clean slate
+  stopServer();
+
+  // Start servers (background by default so CLI returns immediately)
+  startServer({ headless: parsed.headless, debug: streamLogs, background });
+
+  // Wait for Express server
+  try {
+    await waitForServer(15000);
+  } catch {
+    console.error('Server failed to start within 15 seconds.');
+    console.error('Check for port conflicts on :4242');
+    stopServer();
+    return 1;
+  }
+
+  const modeLabel = parsed.headless ? 'HEADLESS (API only)' : 'FULL (API + dashboard)';
+  const dashboardLabel = parsed.headless ? 'disabled (headless mode)' : 'http://localhost:4747';
+  printStatus('Mode', modeLabel);
+  printStatus('API (server)', 'http://localhost:4242');
+  printStatus('Dashboard', dashboardLabel);
+  printStatus('Stop', 'auramaxx stop');
+  console.log('');
+
+  if (background) {
+    return 0;
+  }
+
+  // Debug/foreground mode — keep alive, clean shutdown on Cmd+C.
+  const shutdown = () => {
+    console.log('\nShutting down...');
+    stopServer();
+    console.log('Goodbye.');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep event loop alive so Ctrl+C works
+  setInterval(() => {}, 60_000);
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runStartCli().then((code) => {
+    if (typeof code === 'number' && code !== 0) {
+      process.exit(code);
+    }
+  }).catch((error) => {
+    console.error('Error:', getErrorMessage(error));
+    stopServer();
+    process.exit(1);
+  });
+}

package/server/cli/commands/status.ts

@@ -0,0 +1,59 @@
+/**
+ * auramaxx status — Health check and wallet status
+ */
+
+import { serverUrl, fetchJson, isServerRunning } from '../lib/http';
+import { getErrorMessage } from '../../lib/error';
+import { printBanner, printStatus } from '../lib/theme';
+
+interface SetupStatus {
+  hasWallet: boolean;
+  unlocked: boolean;
+  address: string | null;
+}
+
+async function main() {
+  const url = serverUrl();
+
+  printBanner('STATUS');
+
+  // Check API server
+  const serverUp = await isServerRunning();
+  printStatus('API Server', url, serverUp);
+
+  // Check dashboard
+  let dashboardUp = false;
+  try {
+    const resp = await fetch('http://localhost:4747');
+    dashboardUp = resp.ok || resp.status === 200 || resp.status === 304;
+  } catch {
+    // Not running
+  }
+  printStatus('Dashboard UI', 'http://localhost:4747', dashboardUp);
+
+  if (!serverUp) {
+    console.log('\n  Run `npx auramaxx` to start API + dashboard services.');
+    process.exit(0);
+  }
+
+  // Check wallet status
+  try {
+    const status = await fetchJson<SetupStatus>('/setup');
+    console.log('');
+    printStatus('Vault', status.hasWallet ? 'created' : 'not created', status.hasWallet);
+    printStatus('Unlocked', status.unlocked ? 'yes' : 'no', status.unlocked);
+    if (status.address) {
+      printStatus('Address', status.address);
+    }
+  } catch (error) {
+    const message = getErrorMessage(error);
+    console.log(`\n  Could not fetch wallet status: ${message}`);
+  }
+
+  console.log('');
+}
+
+main().catch((error) => {
+  console.error('Error:', getErrorMessage(error));
+  process.exit(1);
+});

package/server/cli/commands/stop.ts

@@ -0,0 +1,36 @@
+/**
+ * auramaxx stop — Stop running servers
+ *
+ * - `auramaxx stop`         — kills processes, service stays registered (auto-starts on next login)
+ * - `auramaxx stop --force` — kills processes AND uninstalls the service
+ */
+
+import { stopServer, cleanupTempFiles } from '../lib/process';
+import { isServiceInstalled, stopServiceProcesses, uninstallService } from './service';
+
+function main() {
+  const force = process.argv.includes('--force');
+
+  console.log('Stopping AuraMaxx...');
+
+  // If a launchd/systemd service is registered, unload it first so it doesn't
+  // immediately respawn the processes we're about to kill.
+  if (isServiceInstalled()) {
+    stopServiceProcesses();
+  }
+
+  stopServer();
+  cleanupTempFiles();
+
+  if (force && isServiceInstalled()) {
+    uninstallService();
+    console.log('Background service removed. AuraMaxx will not auto-start on login.');
+  } else if (isServiceInstalled()) {
+    console.log('Stopped. Service still registered — will auto-start on next login.');
+    console.log('To fully remove: auramaxx stop --force');
+  }
+
+  console.log('Stopped.');
+}
+
+main();

package/server/cli/commands/token.ts

@@ -0,0 +1,180 @@
+/**
+ * auramaxx token — Profile-first token tooling
+ *
+ * Usage:
+ *   npx auramaxx token preview --profile dev
+ *   npx auramaxx token preview --profile strict --profile-version v1 --json
+ *   npx auramaxx token preview --profile dev --overrides '{"ttlSeconds":900}'
+ *
+ * Auth:
+ *   Requires admin token in AURA_TOKEN (or --token <token>)
+ */
+
+import { fetchJson } from '../lib/http';
+import { getErrorMessage } from '../../lib/error';
+
+type Json = Record<string, unknown>;
+
+interface PolicyPreviewResponse {
+  version: string;
+  profile: { id: string; version: string; displayName?: string; rationale?: string };
+  request: {
+    profile: string;
+    profileVersion?: string;
+    profileOverrides?: Json;
+  };
+  effectivePolicy: {
+    permissions: string[];
+    credentialAccess: { read: string[]; write: string[] };
+    excludeFields: string[];
+    ttlSeconds: number;
+    maxReads: number | null;
+    rateBudget: {
+      state: 'none' | 'inherited' | 'explicit';
+      requests: number | null;
+      windowSeconds: number | null;
+      source: 'none' | 'profile' | 'override';
+    };
+  };
+  effectivePolicyHash: string;
+  warnings: string[];
+  denyExamples: Array<{ code: string; message: string }>;
+}
+
+export interface TokenCliArgs {
+  subcommand?: string;
+  profile?: string;
+  profileVersion?: string;
+  overridesRaw?: string;
+  token?: string;
+  json: boolean;
+}
+
+export function parseTokenArgs(args: string[]): TokenCliArgs {
+  const getValue = (flag: string): string | undefined => {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : undefined;
+  };
+
+  return {
+    subcommand: args[0],
+    profile: getValue('--profile'),
+    profileVersion: getValue('--profile-version'),
+    overridesRaw: getValue('--overrides'),
+    token: getValue('--token'),
+    json: args.includes('--json'),
+  };
+}
+
+function parseOverrides(raw?: string): Json | undefined {
+  if (!raw) return undefined;
+  const parsed = JSON.parse(raw) as unknown;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--overrides must be a JSON object');
+  }
+  return parsed as Json;
+}
+
+export function formatPolicyPreview(preview: PolicyPreviewResponse): string {
+  const lines: string[] = [];
+  lines.push(`Profile: ${preview.profile.id}@${preview.profile.version}`);
+  lines.push(`Hash: ${preview.effectivePolicyHash}`);
+  lines.push(`Permissions: ${preview.effectivePolicy.permissions.join(', ') || '(none)'}`);
+  lines.push(`Credential read scope: ${preview.effectivePolicy.credentialAccess.read.join(', ') || '(none)'}`);
+  lines.push(`Credential write scope: ${preview.effectivePolicy.credentialAccess.write.join(', ') || '(none)'}`);
+  lines.push(`Excluded fields: ${preview.effectivePolicy.excludeFields.join(', ') || '(none)'}`);
+  lines.push(`TTL seconds: ${preview.effectivePolicy.ttlSeconds}`);
+  lines.push(`Max reads: ${preview.effectivePolicy.maxReads ?? 'unlimited'}`);
+
+  const rb = preview.effectivePolicy.rateBudget;
+  lines.push(`Rate budget: ${rb.state} (${rb.requests ?? 'n/a'} / ${rb.windowSeconds ?? 'n/a'}s, source=${rb.source})`);
+
+  if (preview.warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const warning of preview.warnings) lines.push(`  - ${warning}`);
+  }
+
+  if (preview.denyExamples.length > 0) {
+    lines.push('Expected deny examples:');
+    for (const deny of preview.denyExamples) lines.push(`  - ${deny.code}: ${deny.message}`);
+  }
+
+  return lines.join('\n');
+}
+
+function showHelp(): void {
+  console.log(`
+  auramaxx token — Token policy preview
+
+  Usage:
+    npx auramaxx token preview --profile <id> [--profile-version <v>] [--overrides <json>] [--json]
+
+  Options:
+    --profile <id>          Profile id (required)
+    --profile-version <v>   Profile version (default: v1)
+    --overrides <json>      JSON object for profile overrides (tighten-only)
+    --json                  Print raw PolicyPreviewV1 payload
+    --token <token>         Admin token (falls back to AURA_TOKEN env)
+
+  Examples:
+    npx auramaxx token preview --profile dev
+    npx auramaxx token preview --profile strict --profile-version v1 --json
+    npx auramaxx token preview --profile dev --overrides '{"ttlSeconds":900}'
+`);
+}
+
+async function main(): Promise<void> {
+  const parsed = parseTokenArgs(process.argv.slice(2));
+
+  if (!parsed.subcommand || parsed.subcommand === '--help' || parsed.subcommand === '-h') {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (parsed.subcommand !== 'preview') {
+    console.error(`Unknown token subcommand: ${parsed.subcommand}`);
+    showHelp();
+    process.exit(1);
+  }
+
+  if (!parsed.profile) {
+    console.error('--profile is required');
+    process.exit(1);
+  }
+
+  const token = parsed.token || process.env.AURA_TOKEN;
+  if (!token) {
+    console.error('Admin auth required. Provide --token or set AURA_TOKEN.');
+    process.exit(1);
+  }
+
+  try {
+    const profileOverrides = parseOverrides(parsed.overridesRaw);
+    const preview = await fetchJson<PolicyPreviewResponse>('/actions/token/preview', {
+      method: 'POST',
+      token,
+      body: {
+        profile: parsed.profile,
+        profileVersion: parsed.profileVersion,
+        profileOverrides,
+      },
+    });
+
+    if (parsed.json) {
+      console.log(JSON.stringify(preview, null, 2));
+      return;
+    }
+
+    console.log(formatPolicyPreview(preview));
+  } catch (error) {
+    console.error(`Token preview failed: ${getErrorMessage(error)}`);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(`Token preview failed: ${getErrorMessage(error)}`);
+    process.exit(1);
+  });
+}

package/server/cli/commands/unlock.ts

@@ -0,0 +1,50 @@
+/**
+ * auramaxx unlock — Unlock the vault interactively
+ */
+
+import { fetchPublicKey, fetchJson, isServerRunning } from '../lib/http';
+import { promptPassword } from '../lib/prompt';
+import { encryptPassword, generateAgentKeypair } from '../../cli/transport-client';
+import { getErrorMessage } from '../../lib/error';
+
+async function main() {
+  // Check server is running
+  if (!(await isServerRunning())) {
+    console.error('Wallet server is not running.');
+    console.error('Start it with: npx auramaxx');
+    process.exit(1);
+  }
+
+  // Get public key
+  const publicKey = await fetchPublicKey();
+
+  // Prompt for password
+  const password = await promptPassword('Password');
+
+  // Encrypt and unlock
+  const encrypted = encryptPassword(password, publicKey);
+  const { publicKey: agentPubkey } = generateAgentKeypair();
+
+  try {
+    const result = await fetchJson<{
+      success: boolean;
+      address: string;
+      token: string;
+      error?: string;
+    }>('/unlock', { body: { encrypted, pubkey: agentPubkey } });
+
+    console.log(`\nWallet unlocked.`);
+    console.log(`  Address: ${result.address}`);
+    console.log(`  Token:   ${result.token.substring(0, 20)}...`);
+    process.exit(0);
+  } catch (error) {
+    const msg = getErrorMessage(error);
+    console.error(`\nFailed to unlock: ${msg}`);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Error:', getErrorMessage(error));
+  process.exit(1);
+});