cipher-security 2.0.0

package/lib/gateway/commands.js

@@ -0,0 +1,991 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * commands.js — Node.js handler functions for all 22 bridge-mode commands.
+ *
+ * Each handler accepts a plain args object and returns a plain JS object.
+ * No Rich formatting, no Typer framework — just data. The rendering
+ * layer stays in cipher.js's formatBridgeResult().
+ *
+ * All module imports are lazy (dynamic import()) to preserve cold start.
+ *
+ * @module gateway/commands
+ */
+
+import { readFileSync, existsSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const debug = process.env.CIPHER_DEBUG === '1'
+  ? (/** @type {string} */ msg) => process.stderr.write(`[bridge:node] commands: ${msg}\n`)
+  : () => {};
+
+/**
+ * Default memory directory — mirrors Python's ~/.cipher/memory/default.
+ * @returns {string}
+ */
+function defaultMemoryDir() {
+  return join(homedir(), '.cipher', 'memory', 'default');
+}
+
+/**
+ * Resolve the repository root by walking up from this file.
+ * @returns {string}
+ */
+function findRepoRoot() {
+  let dir = resolve(__dirname, '..', '..');
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, 'skills')) && (existsSync(join(dir, 'cli')) || existsSync(join(dir, 'package.json')))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(__dirname, '..', '..');
+}
+
+/**
+ * Read package.json version from the CLI package.
+ * @returns {string}
+ */
+function readVersion() {
+  try {
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Resolve the skills directory path.
+ * @returns {string}
+ */
+function skillsDir() {
+  const root = findRepoRoot();
+  return join(root, 'skills');
+}
+
+// ---------------------------------------------------------------------------
+// Memory-backed handlers (8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Search cross-session memory.
+ * @param {object} args
+ * @param {string} args.query
+ * @param {string} [args.engagement]
+ * @param {number} [args.limit]
+ * @returns {Promise<object>}
+ */
+export async function handleSearch(args = {}) {
+  const { AdaptiveRetriever, CipherMemory } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const retriever = new AdaptiveRetriever(memory);
+    const results = retriever.retrieve(
+      args.query || '',
+      args.engagement || '',
+      args.limit || 10,
+    );
+    debug(`search: ${results.length} results for "${args.query}"`);
+    return {
+      query: args.query || '',
+      count: results.length,
+      results: results.map(r => ({
+        content: r.content,
+        type: r.memoryType || '',
+        severity: r.severity || '',
+        targets: r.targets || [],
+        mitre: r.mitreAttack || [],
+        created: r.createdAt || '',
+      })),
+    };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Store finding/IOC/TTP in memory.
+ * @param {object} args
+ * @param {string} args.content
+ * @param {string} [args.type]
+ * @param {string} [args.severity]
+ * @param {string} [args.engagement]
+ * @param {string[]} [args.tags]
+ * @returns {Promise<object>}
+ */
+export async function handleStore(args = {}) {
+  const { CipherMemory, MemoryEntry, MemoryType } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const typeStr = args.type || 'note';
+    const entry = new MemoryEntry({
+      content: args.content || '',
+      memoryType: Object.values(MemoryType).includes(typeStr) ? typeStr : MemoryType.NOTE,
+      severity: args.severity || '',
+      engagementId: args.engagement || '',
+      tags: Array.isArray(args.tags)
+        ? args.tags
+        : (typeof args.tags === 'string' && args.tags ? args.tags.split(',') : []),
+    });
+    const entryId = memory.store(entry);
+    debug(`store: id=${entryId} type=${typeStr}`);
+    return { id: entryId, type: typeStr, stored: true };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Show memory and platform statistics.
+ * @returns {Promise<object>}
+ */
+export async function handleStats(args = {}) {
+  const { CipherMemory } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const memStats = memory.stats();
+    const version = readVersion();
+    const sDir = skillsDir();
+    let skillCount = 0;
+    let domainCount = 0;
+    let scriptCount = 0;
+
+    if (existsSync(sDir)) {
+      try {
+        // Count SKILL.md files recursively
+        skillCount = countFiles(sDir, 'SKILL.md');
+        // Count top-level domain directories
+        domainCount = readdirSync(sDir).filter(d => {
+          try {
+            return !d.startsWith('.') && statSync(join(sDir, d)).isDirectory();
+          } catch { return false; }
+        }).length;
+        // Count script files recursively
+        scriptCount = countFiles(sDir, '*.py', 'scripts');
+      } catch {
+        // Skills dir unreadable
+      }
+    }
+
+    debug(`stats: version=${version} memory=${JSON.stringify(memStats)}`);
+    return {
+      version,
+      memory: memStats,
+      skills: { total: skillCount, domains: domainCount, scripts: scriptCount },
+    };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Score response quality (PRM evaluation).
+ * @param {object} args
+ * @param {string} args.query
+ * @param {string} args.response
+ * @param {string} [args.mode]
+ * @returns {Promise<object>}
+ */
+export async function handleScore(args = {}) {
+  const { ResponseScorer } = await import('../memory/index.js');
+  const scorer = new ResponseScorer();
+  const scored = scorer.score(
+    args.query || '',
+    args.response || '',
+    args.mode || '',
+  );
+  debug(`score: ${scored.score}`);
+  return {
+    score: scored.score,
+    votes: scored.votes,
+    feedback: scored.feedback,
+  };
+}
+
+/**
+ * Export memory database to JSON.
+ * @param {object} args
+ * @param {string} [args.output]
+ * @param {string} [args.engagement]
+ * @returns {Promise<object>}
+ */
+export async function handleMemoryExport(args = {}) {
+  const { CipherMemory } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const results = memory.search('', {}, 10000);
+    let entries = results.map(r => (typeof r.toDict === 'function' ? r.toDict() : r));
+    if (args.engagement) {
+      entries = entries.filter(e =>
+        (e.engagement_id || e.engagementId) === args.engagement
+      );
+    }
+    const output = args.output || 'cipher-memory-export.json';
+    const data = { entries, count: entries.length };
+    writeFileSync(output, JSON.stringify(data, null, 2), 'utf-8');
+    debug(`memory-export: ${entries.length} entries → ${output}`);
+    return { exported: entries.length, file: output };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Import memory from JSON backup.
+ * @param {object} args
+ * @param {string} args.file
+ * @returns {Promise<object>}
+ */
+export async function handleMemoryImport(args = {}) {
+  const file = args.file;
+  if (!file || !existsSync(file)) {
+    return { error: true, message: `File not found: ${file || '(none)'}` };
+  }
+  const { CipherMemory, MemoryEntry } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf-8'));
+    const entries = raw.entries || (Array.isArray(raw) ? raw : []);
+    let imported = 0;
+    for (const entryData of entries) {
+      try {
+        const entry = MemoryEntry.fromDict(entryData);
+        memory.store(entry);
+        imported++;
+      } catch {
+        // Skip invalid entries
+      }
+    }
+    debug(`memory-import: ${imported}/${entries.length} from ${file}`);
+    return { imported, total: entries.length, file };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Trigger memory ingestion pipeline.
+ * @returns {Promise<object>}
+ */
+export async function handleIngest(args = {}) {
+  const { CipherMemory } = await import('../memory/index.js');
+  const memory = new CipherMemory(defaultMemoryDir());
+  try {
+    const stats = memory.consolidate();
+    debug('ingest: consolidation complete');
+    return { ingested: true, ...stats };
+  } finally {
+    memory.close();
+  }
+}
+
+/**
+ * Config check + memory stats + backend reachability.
+ * @returns {Promise<object>}
+ */
+export async function handleStatus(args = {}) {
+  const { loadConfig, configExists } = await import('../config.js');
+  const { validateConfig } = await import('./config-validate.js');
+
+  const hasConfig = configExists();
+  let configValid = false;
+  let backend = 'unknown';
+
+  if (hasConfig) {
+    try {
+      const raw = loadConfig();
+      const config = validateConfig(raw);
+      configValid = true;
+      backend = config.backend;
+    } catch {
+      // Config present but invalid
+    }
+  }
+
+  // Memory stats
+  let memStats = null;
+  try {
+    const { CipherMemory } = await import('../memory/index.js');
+    const memory = new CipherMemory(defaultMemoryDir());
+    memStats = memory.stats();
+    memory.close();
+  } catch {
+    // Memory unavailable
+  }
+
+  const status = configValid ? 'ready' : (hasConfig ? 'misconfigured' : 'unconfigured');
+  debug(`status: ${status} backend=${backend}`);
+  return {
+    status,
+    backend,
+    config: { exists: hasConfig, valid: configValid },
+    memory: memStats,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline-backed handlers (6)
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze git diff for security issues.
+ * @param {object} args
+ * @param {string} args.file - Diff file path or diff text content
+ * @returns {Promise<object>}
+ */
+export async function handleDiff(args = {}) {
+  const { SecurityDiffAnalyzer } = await import('../pipeline/index.js');
+  const analyzer = new SecurityDiffAnalyzer();
+
+  let diffText = args.file || '';
+  // If it looks like a file path (no newlines, exists on disk), read it
+  if (diffText && !diffText.includes('\n') && existsSync(diffText)) {
+    diffText = readFileSync(diffText, 'utf-8');
+  }
+
+  const analysis = analyzer.analyzeDiff(diffText);
+  const riskVal = analysis.riskLevel?.value ?? analysis.riskLevel ?? 'info';
+
+  debug(`diff: risk=${riskVal} files=${analysis.filesChanged?.length}`);
+  return {
+    risk_level: riskVal,
+    files_changed: analysis.filesChanged?.length ?? 0,
+    auth_changes: analysis.authChanges?.length ?? 0,
+    sql_changes: analysis.sqlChanges?.length ?? 0,
+    crypto_changes: analysis.cryptoChanges?.length ?? 0,
+    secrets_found: analysis.secrets?.length ?? 0,
+    has_security_findings: analysis.hasSecurityFindings ?? false,
+    summary: analysis.summary || '',
+  };
+}
+
+/**
+ * Generate GitHub Actions security workflow.
+ * @param {object} args
+ * @param {string} [args.profile]
+ * @returns {Promise<object>}
+ */
+export async function handleWorkflow(args = {}) {
+  const { WorkflowGenerator } = await import('../pipeline/index.js');
+  const gen = new WorkflowGenerator();
+  const workflow = gen.generateWorkflow(args.profile || 'pentest');
+  debug('workflow: generated');
+  return { workflow };
+}
+
+/**
+ * Convert scan results to SARIF v2.1.0.
+ * @param {object} args
+ * @param {string} args.input - Scan results JSON file path
+ * @param {string} [args.output]
+ * @returns {Promise<object>}
+ */
+export async function handleSarif(args = {}) {
+  const { SarifReport } = await import('../pipeline/index.js');
+  const input = args.input;
+  if (!input || !existsSync(input)) {
+    return { error: true, message: `Input file not found: ${input || '(none)'}` };
+  }
+
+  const data = JSON.parse(readFileSync(input, 'utf-8'));
+  const report = new SarifReport();
+  const findings = data.findings || (Array.isArray(data) ? data : []);
+
+  for (const finding of findings) {
+    report.addFinding(finding);
+  }
+
+  const output = args.output || 'cipher-results.sarif';
+  report.write(output);
+  const summary = report.summary();
+
+  debug(`sarif: ${findings.length} findings → ${output}`);
+  return { file: output, findings: findings.length, summary };
+}
+
+/**
+ * Run OSINT investigation (domain/IP).
+ * @param {object} args
+ * @param {string} args.target
+ * @param {string} [args.type]
+ * @returns {Promise<object>}
+ */
+export async function handleOsint(args = {}) {
+  const { OSINTPipeline } = await import('../pipeline/index.js');
+  const pipeline = new OSINTPipeline();
+  const target = args.target || '';
+  const type = args.type || 'domain';
+
+  const results = type === 'ip'
+    ? pipeline.investigateIp(target)
+    : pipeline.investigateDomain(target);
+
+  const data = {
+    target,
+    type,
+    results: results.map(r => (typeof r.toDict === 'function' ? r.toDict() : r)),
+    summary: pipeline.summary(),
+  };
+  debug(`osint: ${target} (${type}) → ${results.length} results`);
+  return data;
+}
+
+/**
+ * List all skill domains.
+ * @returns {Promise<object>}
+ */
+export async function handleDomains(args = {}) {
+  const sDir = skillsDir();
+  if (!existsSync(sDir)) {
+    return { domains: {}, total_domains: 0, total_techniques: 0 };
+  }
+
+  const domainMap = {};
+  const entries = readdirSync(sDir).sort();
+  for (const d of entries) {
+    const dirPath = join(sDir, d);
+    try {
+      if (d.startsWith('.') || !statSync(dirPath).isDirectory()) continue;
+    } catch { continue; }
+
+    const techniquesDir = join(dirPath, 'techniques');
+    if (existsSync(techniquesDir)) {
+      try {
+        const techniques = readdirSync(techniquesDir).filter(t => {
+          try {
+            return statSync(join(techniquesDir, t)).isDirectory();
+          } catch { return false; }
+        });
+        domainMap[d] = techniques.length;
+      } catch {
+        domainMap[d] = 0;
+      }
+    }
+  }
+
+  const totalTechniques = Object.values(domainMap).reduce((a, b) => a + b, 0);
+  debug(`domains: ${Object.keys(domainMap).length} domains, ${totalTechniques} techniques`);
+  return {
+    domains: domainMap,
+    total_domains: Object.keys(domainMap).length,
+    total_techniques: totalTechniques,
+  };
+}
+
+/**
+ * Search skills by keyword.
+ * @param {object} args
+ * @param {string} args.query
+ * @param {number} [args.limit]
+ * @returns {Promise<object>}
+ */
+export async function handleSkills(args = {}) {
+  const sDir = skillsDir();
+  const query = (args.query || '').toLowerCase();
+  const limit = args.limit || 10;
+  const results = [];
+
+  if (!existsSync(sDir)) {
+    return { query: args.query || '', count: 0, results: [] };
+  }
+
+  // Walk skills dir looking for SKILL.md files
+  const walk = (dir, relBase) => {
+    if (results.length >= limit) return;
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        if (results.length >= limit) return;
+        const fullPath = join(dir, entry);
+        try {
+          if (statSync(fullPath).isDirectory()) {
+            walk(fullPath, join(relBase, entry));
+          } else if (entry === 'SKILL.md') {
+            const name = dirname(join(relBase, entry)).split('/').pop() || '';
+            const rel = dirname(join(relBase, entry));
+            if (query === '' || name.toLowerCase().includes(query) || rel.toLowerCase().includes(query)) {
+              results.push({ name, path: rel });
+            }
+          }
+        } catch { /* skip unreadable entries */ }
+      }
+    } catch { /* skip unreadable dirs */ }
+  };
+
+  walk(sDir, '');
+  debug(`skills: "${query}" → ${results.length} results`);
+  return { query: args.query || '', count: results.length, results };
+}
+
+// ---------------------------------------------------------------------------
+// Self-contained handlers (4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read version from package.json.
+ * @returns {Promise<object>}
+ */
+export async function handleVersion(args = {}) {
+  return { version: readVersion() };
+}
+
+/**
+ * Comprehensive health check.
+ * @returns {Promise<object>}
+ */
+export async function handleDoctor(args = {}) {
+  const checks = [];
+
+  // Node.js version
+  checks.push({
+    name: 'Node.js',
+    status: 'ok',
+    detail: process.version,
+  });
+
+  // npm version
+  try {
+    const npmVer = execSync('npm --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    checks.push({ name: 'npm', status: 'ok', detail: `v${npmVer}` });
+  } catch {
+    checks.push({ name: 'npm', status: 'missing', detail: 'npm not found' });
+  }
+
+  // External tools (optional)
+  for (const tool of ['nuclei', 'katana', 'ollama']) {
+    try {
+      execSync(`which ${tool}`, { encoding: 'utf-8', timeout: 3000 });
+      checks.push({ name: tool, status: 'ok', detail: 'installed' });
+    } catch {
+      checks.push({ name: tool, status: 'optional', detail: `${tool} not found — optional` });
+    }
+  }
+
+  // Config validity
+  try {
+    const { loadConfig, configExists } = await import('../config.js');
+    const { validateConfig } = await import('./config-validate.js');
+
+    if (configExists()) {
+      const raw = loadConfig();
+      const config = validateConfig(raw);
+      checks.push({
+        name: 'Config',
+        status: 'ok',
+        detail: `backend=${config.backend} model=${config[`${config.backend}_model`] || 'default'}`,
+      });
+    } else {
+      checks.push({
+        name: 'Config',
+        status: 'missing',
+        detail: 'No config found — run: cipher setup',
+      });
+    }
+  } catch (err) {
+    checks.push({
+      name: 'Config',
+      status: 'error',
+      detail: err.message?.split('\n')[0] || 'Config validation failed',
+    });
+  }
+
+  // Memory database health
+  try {
+    const { CipherMemory } = await import('../memory/index.js');
+    const memory = new CipherMemory(defaultMemoryDir());
+    const stats = memory.stats();
+    memory.close();
+    checks.push({
+      name: 'Memory',
+      status: 'ok',
+      detail: `total=${stats.total ?? 0} active=${stats.active ?? 0} archived=${stats.archived ?? 0}`,
+    });
+  } catch (err) {
+    checks.push({
+      name: 'Memory',
+      status: 'error',
+      detail: err.message || 'Memory database unavailable',
+    });
+  }
+
+  const healthy = checks.every(c => c.status === 'ok' || c.status === 'optional');
+  const summary = `${checks.filter(c => c.status === 'ok').length}/${checks.length} checks passed`;
+
+  debug(`doctor: ${summary}`);
+  return { checks, healthy, summary };
+}
+
+/**
+ * Plugin management.
+ * @param {object} args
+ * @param {string} [args.action] - 'list', 'install', 'remove'
+ * @returns {Promise<object>}
+ */
+export async function handlePlugin(args = {}) {
+  const { PluginManager } = await import('./plugins.js');
+  const pm = new PluginManager();
+  const action = args.action || 'list';
+
+  if (action === 'list') {
+    const plugins = pm.plugins;
+    return {
+      count: plugins.length,
+      plugins: plugins.map(p => ({
+        name: p.name,
+        version: p.version,
+        description: p.description,
+        author: p.author,
+        modes: p.modes,
+        priority: p.priority,
+        source: p.source,
+      })),
+    };
+  }
+
+  // install/remove are placeholder — real implementation depends on registry
+  return {
+    error: true,
+    message: `Plugin action '${action}' not yet implemented. Only 'list' is available.`,
+  };
+}
+
+/**
+ * Non-streaming query path — delegates to Gateway.send().
+ * @param {object} args
+ * @param {string} args.message
+ * @param {Array<{role: string, content: string}>} [args.history]
+ * @returns {Promise<object>}
+ */
+export async function handleQuery(args = {}) {
+  const { Gateway } = await import('./gateway.js');
+  const gateway = new Gateway();
+  const response = await gateway.send(args.message || '', args.history);
+  debug('query: response received');
+  return { response, mode: 'auto' };
+}
+
+// ---------------------------------------------------------------------------
+// Stub handlers (4)
+// ---------------------------------------------------------------------------
+
+/**
+ * @returns {Promise<object>}
+ */
+export async function handleLeaderboard(args = {}) {
+  return {
+    error: true,
+    message: 'Leaderboard requires autonomous framework (available after S04). Use Python bridge: cipher leaderboard --bridge',
+  };
+}
+
+/**
+ * @returns {Promise<object>}
+ */
+export async function handleFeedback(args = {}) {
+  return {
+    error: true,
+    message: 'Feedback loop requires autonomous framework (available after S04). Use Python bridge: cipher feedback --bridge',
+  };
+}
+
+/**
+ * @returns {Promise<object>}
+ */
+export async function handleMarketplace(args = {}) {
+  return {
+    error: true,
+    message: 'Marketplace requires api/marketplace module (available after S05). Use Python bridge: cipher marketplace --bridge',
+  };
+}
+
+/**
+ * @returns {Promise<object>}
+ */
+export async function handleCompliance(args = {}) {
+  return {
+    error: true,
+    message: 'Compliance requires api/compliance module (available after S05). Use Python bridge: cipher compliance --bridge',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively count files matching a filename pattern.
+ * @param {string} dir
+ * @param {string} filename - exact filename (e.g. 'SKILL.md') or glob-like '*.py'
+ * @param {string} [subdir] - optional subdirectory filter (only count in dirs named this)
+ * @returns {number}
+ */
+function countFiles(dir, filename, subdir) {
+  let count = 0;
+  const isGlob = filename.startsWith('*.');
+  const ext = isGlob ? filename.slice(1) : null;
+
+  const walk = (d) => {
+    try {
+      const entries = readdirSync(d);
+      for (const entry of entries) {
+        const fullPath = join(d, entry);
+        try {
+          const st = statSync(fullPath);
+          if (st.isDirectory()) {
+            if (!subdir || entry === subdir || d !== dir) {
+              walk(fullPath);
+            }
+          } else if (st.isFile()) {
+            if (isGlob ? entry.endsWith(ext) : entry === filename) {
+              if (!subdir || dirname(fullPath).split('/').includes(subdir)) {
+                count++;
+              }
+            }
+          }
+        } catch { /* skip unreadable entries */ }
+      }
+    } catch { /* skip unreadable dirs */ }
+  };
+
+  walk(dir);
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Scan command — delegates to Node.js NucleiRunner
+// ---------------------------------------------------------------------------
+
+export async function handleScan(args = {}) {
+  const target = Array.isArray(args) ? args.find(a => !a.startsWith('-')) : args.target;
+  if (!target) {
+    return { error: true, message: 'Usage: cipher scan <target> [--profile <profile>]' };
+  }
+  try {
+    const { NucleiRunner, ScanProfile } = await import('../pipeline/scanner.js');
+    const runner = new NucleiRunner();
+    const profileArg = Array.isArray(args) ? (args.find((a, i) => args[i - 1] === '--profile') || 'standard') : (args.profile || 'standard');
+    const result = await runner.scan(target, { profile: ScanProfile.fromDomain(profileArg) });
+    return {
+      output: JSON.stringify({
+        target,
+        profile: profileArg,
+        findings: (result.findings || []).length,
+        status: 'completed',
+      }, null, 2),
+    };
+  } catch (err) {
+    return { error: true, message: `Scan failed: ${err.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard command — stub for Node.js TUI (Textual TUI not ported)
+// ---------------------------------------------------------------------------
+
+export async function handleDashboard() {
+  return {
+    output: JSON.stringify({
+      status: 'info',
+      message: 'Dashboard TUI is not yet available in Node.js mode. Use `cipher status` for system status or `cipher api` for the REST API.',
+    }, null, 2),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Web command — delegates to API server
+// ---------------------------------------------------------------------------
+
+export async function handleWeb(args = {}) {
+  return {
+    output: JSON.stringify({
+      status: 'info',
+      message: 'The web interface has been consolidated into `cipher api`. Use `cipher api --no-auth --port 8443` to start the REST API server.',
+    }, null, 2),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Setup Signal command — Signal bot configuration
+// ---------------------------------------------------------------------------
+
+export async function handleSetupSignal() {
+  const clack = await import('@clack/prompts');
+  const { execSync } = await import('node:child_process');
+  const { writeConfig, loadConfig, configExists } = await import('../config.js');
+  const brand = await import('../brand.js');
+
+  brand.banner();
+  clack.intro('Signal Bot Setup');
+
+  // Step 1: Check if signal-cli-rest-api is running
+  let signalService = 'http://localhost:8080';
+  let apiHealthy = false;
+
+  clack.log.step('Checking for signal-cli-rest-api...');
+
+  try {
+    const resp = execSync(`curl -sf ${signalService}/v1/about`, { encoding: 'utf-8', timeout: 5000 });
+    const info = JSON.parse(resp);
+    clack.log.success(`Signal API running (v${info.version}, mode: ${info.mode})`);
+    apiHealthy = true;
+  } catch {
+    clack.log.warn('Signal API not detected at localhost:8080');
+    clack.log.info(
+      'Start it with Docker:\n\n' +
+      '  docker compose --profile signal up -d signal-api\n\n' +
+      'Or manually:\n\n' +
+      '  docker run -d --name signal-api \\\n' +
+      '    -p 8080:8080 -e MODE=json-rpc \\\n' +
+      '    -v signal-data:/home/.local/share/signal-cli \\\n' +
+      '    bbernhard/signal-cli-rest-api:0.98'
+    );
+
+    const customUrl = await clack.text({
+      message: 'Signal API URL (or press Enter to skip)',
+      placeholder: 'http://localhost:8080',
+      defaultValue: '',
+    });
+    if (clack.isCancel(customUrl)) { clack.outro('Cancelled.'); process.exit(0); }
+
+    if (customUrl) {
+      signalService = customUrl;
+      try {
+        const resp = execSync(`curl -sf ${signalService}/v1/about`, { encoding: 'utf-8', timeout: 5000 });
+        clack.log.success('Signal API reachable.');
+        apiHealthy = true;
+      } catch {
+        clack.log.error('Cannot reach Signal API at that URL.');
+        clack.outro('Fix the Signal API first, then run cipher setup-signal again.');
+        process.exit(1);
+      }
+    } else {
+      clack.outro('Start the Signal API first, then run cipher setup-signal again.');
+      process.exit(1);
+    }
+  }
+
+  // Step 2: Check registered phone numbers
+  let phoneNumber = '';
+  try {
+    const accounts = JSON.parse(execSync(`curl -sf ${signalService}/v1/accounts`, { encoding: 'utf-8', timeout: 5000 }));
+    if (accounts.length > 0) {
+      if (accounts.length === 1) {
+        phoneNumber = accounts[0];
+        clack.log.success(`Registered number: ${phoneNumber}`);
+      } else {
+        const selected = await clack.select({
+          message: 'Select the phone number for the bot',
+          options: accounts.map(a => ({ value: a, label: a })),
+        });
+        if (clack.isCancel(selected)) { clack.outro('Cancelled.'); process.exit(0); }
+        phoneNumber = selected;
+      }
+    } else {
+      clack.log.warn('No phone numbers registered with signal-cli.');
+      clack.log.info(
+        'Register a number:\n\n' +
+        `  curl -X POST ${signalService}/v1/register/<YOUR_NUMBER>\n` +
+        `  curl -X POST ${signalService}/v1/verify/<YOUR_NUMBER> -d '{"token":"<CODE>"}'`
+      );
+      clack.outro('Register a number first, then run cipher setup-signal again.');
+      process.exit(1);
+    }
+  } catch (err) {
+    clack.log.error('Failed to query accounts: ' + err.message);
+    process.exit(1);
+  }
+
+  // Step 3: Whitelist
+  const whitelistInput = await clack.text({
+    message: 'Allowed phone numbers (comma-separated, E.164 format)',
+    placeholder: '+15551234567,+15559876543',
+    defaultValue: '',
+  });
+  if (clack.isCancel(whitelistInput)) { clack.outro('Cancelled.'); process.exit(0); }
+
+  const whitelist = whitelistInput
+    ? whitelistInput.split(',').map(n => n.trim()).filter(Boolean)
+    : [];
+
+  // Step 4: Save config
+  let existingConfig = {};
+  try {
+    if (configExists()) existingConfig = loadConfig();
+  } catch { /* ignore */ }
+
+  const config = {
+    ...existingConfig,
+    signal: {
+      signal_service: signalService,
+      phone_number: phoneNumber,
+      whitelist,
+      session_timeout: 3600,
+    },
+  };
+
+  const configPath = writeConfig(config);
+
+  clack.log.success('Signal configuration saved.');
+  clack.outro(`Run cipher bot to start. Config: ${configPath}`);
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Update command — self-update from npm
+// ---------------------------------------------------------------------------
+
+export async function handleUpdate(args = {}) {
+  const { execSync } = await import('node:child_process');
+  const { readFileSync } = await import('node:fs');
+  const { join, dirname } = await import('node:path');
+  const brand = await import('../brand.js');
+
+  const pkgPath = join(dirname(new URL(import.meta.url).pathname), '..', '..', 'package.json');
+  let currentVersion = 'unknown';
+  try {
+    currentVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  } catch { /* ignore */ }
+
+  brand.header('Update', currentVersion);
+  brand.info(`Current version: ${currentVersion}`);
+  brand.info('Checking npm for updates...');
+
+  try {
+    const latest = execSync('npm view cipher-security version', {
+      encoding: 'utf-8',
+      timeout: 10000,
+    }).trim();
+
+    if (latest === currentVersion) {
+      brand.success(`Already up to date (${currentVersion})`);
+      return {};
+    }
+
+    brand.warn(`New version available: ${latest}`);
+    brand.info('Installing update...');
+
+    execSync('npm install -g cipher-security@latest', {
+      encoding: 'utf-8',
+      timeout: 60000,
+      stdio: 'inherit',
+    });
+
+    brand.success(`Updated ${currentVersion} → ${latest}`);
+    return {};
+  } catch (err) {
+    brand.error(`Update failed: ${err.message}`);
+    return { error: true, message: `Update failed: ${err.message}` };
+  }
+}