@inkobytes/nexus 1.0.0

package/src/commands/dashboard.js

@@ -0,0 +1,387 @@
+/**
+ * nexus dashboard --serve
+ * Read-only local dashboard for human Nexus status checks.
+ */
+
+import { createServer } from 'http';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { networkInterfaces } from 'os';
+import { join } from 'path';
+import { getConfig } from '../lib/config.js';
+import { listLocks } from '../lib/lockManager.js';
+import { readLedgerEntries } from './ledger.js';
+
+const DEFAULT_PORT = 13787;
+const MAX_PORT_SEARCH = 30;
+const DASHBOARD_HTML_URL = new URL('../../nexus-dashboard/index.html', import.meta.url);
+const DASHBOARD_DOCS_URL = new URL('../../nexus-dashboard/docs/index.html', import.meta.url);
+const DASHBOARD_LOGO_URL = new URL('../../nexus-dashboard/logo-nexus.svg', import.meta.url);
+
+export default function dashboard(args) {
+  if (args.includes('--snapshot')) {
+    console.log(JSON.stringify(buildSnapshot(), null, 2));
+    return;
+  }
+
+  serveDashboard(resolveDashboardPort(args));
+}
+
+export function buildSnapshot() {
+  const config = getConfig();
+  const locks = listLocks().map(lock => ({
+    target: lock.target,
+    age: lock.age,
+    stale: lock.age !== null && lock.age >= config.staleThreshold,
+    agent: lock.agent || '',
+    intent: lock.intent || '',
+    subagents: lock.subagents || 0,
+    model: lock.model || '',
+    thinking: lock.thinking || '',
+    verified: lock.verified ?? true,
+    trustSource: lock.trustSource || 'unverified',
+  }));
+
+  const presence = {};
+  if (existsSync(join(config.root, '.nexus', 'presence'))) {
+    for (const file of readdirSync(join(config.root, '.nexus', 'presence'))) {
+      try {
+        presence[file] = parseInt(readFileSync(join(config.root, '.nexus', 'presence', file), 'utf-8').trim(), 10);
+      } catch { /* ignore */ }
+    }
+  }
+
+  const queueText = readText(config.queue);
+  const standupText = readText(config.standup);
+  const reportText = readText(config.report);
+  const git = getGitStatus(config.root);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    repo: config.root,
+    branch: git.branch,
+    dirtyFiles: git.files,
+    health: getHealth(config),
+    locks,
+    presence,
+    queue: parseQueue(queueText),
+    proposed: parseProposed(queueText),
+    ledger: readLedgerEntries().reverse(),
+    standup: parseStandupEntries(standupText).filter(entry => entry.type.startsWith('@')).slice(-8).reverse(),
+    releases: parseReleaseEntries(reportText).slice(-16).reverse(),
+    report: sortReportBlocksLatestFirst(reportText),
+  };
+}
+
+function serveDashboard(port) {
+  const clients = new Set();
+  const server = createServer((req, res) => {
+    const url = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+
+    if (url.pathname === '/api/snapshot') {
+      sendJson(res, buildSnapshot());
+      return;
+    }
+
+    if (url.pathname === '/style.css') {
+      res.writeHead(200, { 'Content-Type': 'text/css' });
+      res.end(readFileSync(new URL('../../nexus-dashboard/style.css', import.meta.url)));
+      return;
+    }
+
+    if (url.pathname === '/logo-nexus.svg') {
+      res.writeHead(200, { 'Content-Type': 'image/svg+xml' });
+      res.end(readFileSync(DASHBOARD_LOGO_URL));
+      return;
+    }
+
+    if (url.pathname === '/docs' || url.pathname === '/docs/') {
+      res.writeHead(302, { Location: '/docs/index.html' });
+      res.end();
+      return;
+    }
+
+    if (url.pathname === '/docs/index.html') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(readFileSync(DASHBOARD_DOCS_URL, 'utf-8'));
+      return;
+    }
+
+    if (url.pathname === '/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write('event: update\ndata: ready\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(readDashboardHtml());
+  });
+
+  const interval = setInterval(() => {
+    for (const client of clients) {
+      client.write(`event: update\ndata: ${Date.now()}\n\n`);
+    }
+  }, 2000);
+
+  server.on('close', () => clearInterval(interval));
+  listenOnAvailablePort(server, port, port === DEFAULT_PORT);
+}
+
+export function resolveDashboardPort(args) {
+  const index = args.indexOf('--port');
+  if (index === -1) return DEFAULT_PORT;
+  const value = Number.parseInt(args[index + 1], 10);
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new Error('Invalid --port value.');
+  }
+  return value;
+}
+
+function listenOnAvailablePort(server, port, canSearch) {
+  let attempts = 0;
+
+  const tryListen = (candidate) => {
+    server.once('error', (err) => {
+      if (canSearch && err.code === 'EADDRINUSE' && attempts < MAX_PORT_SEARCH) {
+        attempts++;
+        tryListen(candidate + 1);
+        return;
+      }
+      throw err;
+    });
+
+    server.listen(candidate, '0.0.0.0', () => {
+      const moved = candidate !== port ? ` (default ${port} was busy)` : '';
+      console.log(`Nexus dashboard listening at http://127.0.0.1:${candidate}${moved}`);
+      for (const url of getLanUrls(candidate)) {
+        console.log(`Local network: ${url}`);
+      }
+      console.log('Press Ctrl+C to stop.');
+    });
+  };
+
+  tryListen(port);
+}
+
+function getLanUrls(port) {
+  const urls = [];
+  for (const entries of Object.values(networkInterfaces())) {
+    for (const entry of entries || []) {
+      if (entry.family !== 'IPv4' || entry.internal) continue;
+      urls.push(`http://${entry.address}:${port}`);
+    }
+  }
+  return urls;
+}
+
+function sendJson(res, body) {
+  res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+}
+
+function readText(path) {
+  if (!existsSync(path)) return '';
+  return readFileSync(path, 'utf-8');
+}
+
+function getGitStatus(root) {
+  const result = spawnSync('git', ['status', '--short', '--branch'], {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  });
+  if (result.status !== 0) return { branch: 'unknown', files: [] };
+
+  const lines = result.stdout.trim().split('\n').filter(Boolean);
+  const branch = lines[0]?.replace(/^##\s*/, '') || 'unknown';
+  return { branch, files: lines.slice(1) };
+}
+
+function getHealth(config) {
+  const issues = [];
+  for (const file of ['_NEXUS_CONSTITUTION.md', '_NEXUS_QUEUE.md', '_NEXUS_STANDUP.md']) {
+    if (!existsSync(`${config.root}/${file}`)) issues.push(`Missing ${file}`);
+  }
+
+  const trackedPrivate = spawnSync('git', ['ls-files', 'DECISIONS.md', 'docs-priv'], {
+    cwd: config.root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  }).stdout.trim().split('\n').filter(Boolean);
+  for (const file of trackedPrivate) issues.push(`Tracked private path: ${file}`);
+
+  return { ok: issues.length === 0, issues };
+}
+
+function extractSection(content, heading) {
+  const lines = content.split('\n');
+  let inSection = false;
+  const result = [];
+  for (const line of lines) {
+    if (line.startsWith('## ')) { inSection = line.trim() === heading; continue; }
+    if (inSection) result.push(line);
+  }
+  return result.join('\n');
+}
+
+function parseTasks(content) {
+  const tasks = [];
+  const lines = content.split('\n');
+  let current = null;
+
+  for (const line of lines) {
+    const task = line.match(/^- \[([ x])\] TASK\/([^:]+):\s*(.+)$/);
+    if (task) {
+      if (current) tasks.push(current);
+      current = {
+        checked: task[1] === 'x',
+        agent: task[2].trim(),
+        title: task[3].trim(),
+        id: '', epic: '', status: '', depends: '',
+        files: '', drills: '', cost: '', autoFlow: '', notes: '',
+        review: '', approvedBy: '',
+      };
+      continue;
+    }
+    if (!current) continue;
+    const field = line.trim().match(/^- ([^:]+):\s*(.+)$/);
+    if (!field) continue;
+    const key = field[1].toLowerCase();
+    if (key === 'id') current.id = field[2];
+    if (key === 'epic') current.epic = field[2];
+    if (key === 'status') current.status = field[2];
+    if (key === 'depends on') current.depends = field[2];
+    if (key === 'files') current.files = field[2];
+    if (key === 'drills') current.drills = field[2];
+    if (key === 'cost') current.cost = field[2];
+    if (key === 'auto-flow') current.autoFlow = field[2];
+    if (key === 'notes') current.notes = field[2];
+    if (key === 'review') current.review = field[2];
+    if (key === 'approved by') current.approvedBy = field[2];
+  }
+  if (current) tasks.push(current);
+  return tasks;
+}
+
+function parseQueue(content) {
+  return parseTasks(extractSection(content, '## Ready Queue'));
+}
+
+function parseProposed(content) {
+  return parseTasks(extractSection(content, '## Proposed Queue'));
+}
+
+function parseStandupEntries(content) {
+  const entries = [];
+  const lines = content.split('\n');
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith('#') || line.startsWith('---')) continue;
+
+    const task = line.match(/^- \[([ x])\] TASK\/([^:]+):\s*(.+)$/);
+    if (task) {
+      const details = {};
+      while (index + 1 < lines.length && lines[index + 1].trim().startsWith('- ')) {
+        const field = lines[index + 1].trim().match(/^- ([^:]+):\s*(.+)$/);
+        if (!field) break;
+        details[field[1].toLowerCase()] = field[2];
+        index++;
+      }
+      entries.push({
+        type: 'Task',
+        title: task[3].trim(),
+        meta: [task[2].trim(), details.status, details.files].filter(Boolean).join(' · '),
+      });
+      continue;
+    }
+
+    const datedAgent = line.match(/^(\d{4}-\d{2}-\d{2}(?:[ T]\d{1,2}:\d{2}(?:\s?(?:AM|PM|am|pm))?)?)\s+(@\S+)(?:\s+\[([A-Z][A-Z0-9_-]*)\])?:\s*(.+)$/);
+    if (datedAgent) {
+      entries.push({
+        type: datedAgent[2],
+        title: datedAgent[4],
+        meta: [datedAgent[1], datedAgent[3]].filter(Boolean).join(' · '),
+      });
+      continue;
+    }
+
+    const agent = line.match(/^(@[^:]+):\s*(.+)$/);
+    if (agent) {
+      entries.push({
+        type: agent[1],
+        title: agent[2],
+        meta: '',
+        warning: 'Missing date/time. Use YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message',
+      });
+      continue;
+    }
+
+    entries.push({ type: 'Note', title: line.replace(/^- /, ''), meta: '' });
+  }
+
+  return entries;
+}
+
+function parseReleaseEntries(content) {
+  const entries = [];
+  const lines = content.split('\n');
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith('#') || line.startsWith('---')) continue;
+
+    if (line.startsWith('Commit:') || line.startsWith('- Commit:')) {
+      entries.push({ type: 'Commit', title: line.replace(/^-?\s*Commit:\s*/, ''), meta: '' });
+      continue;
+    }
+
+    if (line === 'Done claim:') {
+      const details = [];
+      while (index + 1 < lines.length && lines[index + 1].trim().startsWith('- ')) {
+        const detail = lines[index + 1].trim().replace(/^- /, '');
+        if (hasReleaseDetailValue(detail)) details.push(detail);
+        index++;
+      }
+      if (details.length > 0) {
+        entries.push({ type: 'Done Claim', title: details.join(' · '), meta: '' });
+      }
+    }
+  }
+
+  return entries;
+}
+
+function hasReleaseDetailValue(detail) {
+  const colon = detail.indexOf(':');
+  if (colon === -1) return detail.trim().length > 0;
+  return detail.slice(colon + 1).trim().length > 0;
+}
+
+function sortReportBlocksLatestFirst(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return content;
+
+  const firstBlock = trimmed.search(/^## \[/m);
+  if (firstBlock === -1) return content;
+
+  const intro = trimmed.slice(0, firstBlock).trimEnd();
+  const blockText = trimmed.slice(firstBlock);
+  const blocks = blockText
+    .split(/\n(?=## \[)/)
+    .map((block) => block.trimEnd())
+    .filter(Boolean)
+    .reverse();
+
+  return `${intro ? `${intro}\n\n` : ''}${blocks.join('\n\n')}\n`;
+}
+
+function readDashboardHtml() {
+  return readFileSync(DASHBOARD_HTML_URL, 'utf-8');
+}

package/src/commands/db.js

@@ -0,0 +1,256 @@
+/**
+ * nexus db — database backup, restore, and schedule.
+ * Philosophy: total recoverability over prevention.
+ *
+ * nexus db backup [--auto]      Snapshot all detected DBs
+ * nexus db list                 List available backups
+ * nexus db restore <stamp>      Restore from a backup
+ * nexus db schedule             Show cron setup instructions
+ */
+
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync, writeFileSync } from 'fs';
+import { join, basename } from 'path';
+import { cwd, env } from 'process';
+import { spawnSync } from 'child_process';
+
+const BACKUP_DIR = '.nexus/db-backups';
+const MIGRATION_PATTERNS = /\b(migrate|db:migrate|alembic\s+upgrade|flyway|sequelize.*migrate|knex.*migrate|prisma\s+migrate)\b/i;
+
+export { MIGRATION_PATTERNS };
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+function detectDatabases(root) {
+  const dbs = [];
+
+  // SQLite: scan for .sqlite and .db files, skip node_modules/.git/.nexus
+  const SKIP = new Set(['node_modules', '.git', '.nexus', 'dist', 'build']);
+  function scanDir(dir, depth = 0) {
+    if (depth > 4) return;
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const entry of entries) {
+      if (SKIP.has(entry)) continue;
+      const full = join(dir, entry);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) { scanDir(full, depth + 1); continue; }
+        if (/\.(sqlite|sqlite3|db)$/.test(entry)) {
+          dbs.push({ type: 'sqlite', path: full, name: entry });
+        }
+      } catch { /* skip unreadable */ }
+    }
+  }
+  scanDir(root);
+
+  // Postgres / MySQL via DATABASE_URL
+  const dbUrl = env.DATABASE_URL || env.POSTGRES_URL || env.MYSQL_URL;
+  if (dbUrl) {
+    const isPostgres = /^postgres(ql)?:\/\//i.test(dbUrl);
+    const isMysql = /^mysql:\/\//i.test(dbUrl);
+    if (isPostgres) dbs.push({ type: 'postgres', url: dbUrl, name: 'postgres' });
+    if (isMysql) dbs.push({ type: 'mysql', url: dbUrl, name: 'mysql' });
+  }
+
+  return dbs;
+}
+
+function backupSqlite(db, backupPath) {
+  copyFileSync(db.path, join(backupPath, db.name));
+  return db.name;
+}
+
+function backupPostgres(db, backupPath) {
+  const outFile = join(backupPath, 'dump.sql');
+  const result = spawnSync('pg_dump', [db.url, '--file', outFile], {
+    encoding: 'utf-8', stdio: 'pipe',
+  });
+  if (result.status !== 0) throw new Error(`pg_dump failed: ${result.stderr}`);
+  return 'dump.sql';
+}
+
+function backupMysql(db, backupPath) {
+  const outFile = join(backupPath, 'dump.sql');
+  const result = spawnSync('sh', ['-c', `mysqldump "${db.url}" > "${outFile}"`], {
+    encoding: 'utf-8', stdio: 'pipe',
+  });
+  if (result.status !== 0) throw new Error(`mysqldump failed: ${result.stderr}`);
+  return 'dump.sql';
+}
+
+export default function db(args) {
+  const root = cwd();
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === '--help') {
+    console.log('Usage: nexus db <backup|list|restore|schedule> [options]');
+    console.log('  backup [--auto]    Snapshot all detected databases');
+    console.log('  list               Show available backups');
+    console.log('  restore <stamp>    Restore from a backup stamp');
+    console.log('  schedule           Show cron setup for daily backups');
+    return;
+  }
+
+  if (subcommand === 'backup') return runBackup(root, args.includes('--auto'));
+  if (subcommand === 'list')   return runList(root);
+  if (subcommand === 'restore') return runRestore(root, args[1]);
+  if (subcommand === 'schedule') return runSchedule(root);
+
+  console.error(`Unknown db subcommand: ${subcommand}`);
+  process.exit(1);
+}
+
+function runBackup(root, auto = false) {
+  const dbs = detectDatabases(root);
+
+  if (!dbs.length) {
+    console.log('[nexus db] No databases detected. Checked: *.sqlite, *.db, DATABASE_URL.');
+    return;
+  }
+
+  const stamp = timestamp();
+  const backupPath = join(root, BACKUP_DIR, stamp);
+  mkdirSync(backupPath, { recursive: true });
+
+  const results = [];
+  for (const db of dbs) {
+    try {
+      let file;
+      if (db.type === 'sqlite')   file = backupSqlite(db, backupPath);
+      if (db.type === 'postgres') file = backupPostgres(db, backupPath);
+      if (db.type === 'mysql')    file = backupMysql(db, backupPath);
+      results.push({ db: db.name, type: db.type, file, ok: true });
+      console.log(`[nexus db] ✓ ${db.type} ${db.name} → ${BACKUP_DIR}/${stamp}/${file}`);
+    } catch (err) {
+      results.push({ db: db.name, type: db.type, ok: false, error: err.message });
+      console.error(`[nexus db] ✗ ${db.type} ${db.name}: ${err.message}`);
+    }
+  }
+
+  // Write manifest
+  writeFileSync(
+    join(backupPath, 'manifest.json'),
+    JSON.stringify({ stamp, auto, root, dbs: results }, null, 2),
+    'utf-8'
+  );
+
+  const ok = results.every(r => r.ok);
+  if (auto) {
+    console.log(`[nexus db] Backup complete (${stamp}). Proceeding with migration.`);
+  } else {
+    console.log(`\nStamp: ${stamp}`);
+    console.log(`Restore with: nexus db restore ${stamp}`);
+  }
+
+  return ok;
+}
+
+function runList(root) {
+  const backupRoot = join(root, BACKUP_DIR);
+  if (!existsSync(backupRoot)) {
+    console.log('[nexus db] No backups found. Run `nexus db backup` first.');
+    return;
+  }
+
+  const entries = readdirSync(backupRoot)
+    .filter(e => statSync(join(backupRoot, e)).isDirectory())
+    .sort()
+    .reverse();
+
+  if (!entries.length) {
+    console.log('[nexus db] No backups found.');
+    return;
+  }
+
+  console.log('\nNexus DB Backups\n');
+  console.log('  ' + 'STAMP'.padEnd(22) + 'DATABASES');
+  console.log('  ' + '─'.repeat(50));
+
+  for (const stamp of entries) {
+    const manifestPath = join(backupRoot, stamp, 'manifest.json');
+    let dbs = '(no manifest)';
+    if (existsSync(manifestPath)) {
+      try {
+        const m = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        dbs = m.dbs.map(d => `${d.type}:${d.db}`).join(', ');
+        if (m.auto) dbs += ' [auto]';
+      } catch { /* ignore */ }
+    }
+    console.log('  ' + stamp.padEnd(22) + dbs);
+  }
+  console.log('');
+}
+
+function runRestore(root, stamp) {
+  if (!stamp) {
+    console.error('Usage: nexus db restore <stamp>');
+    console.error('Run `nexus db list` to see available stamps.');
+    process.exit(1);
+  }
+
+  const backupPath = join(root, BACKUP_DIR, stamp);
+  if (!existsSync(backupPath)) {
+    console.error(`[nexus db] Backup not found: ${stamp}`);
+    console.error('Run `nexus db list` to see available stamps.');
+    process.exit(1);
+  }
+
+  const manifestPath = join(backupPath, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    console.error(`[nexus db] No manifest in backup ${stamp}. Cannot restore safely.`);
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  console.log(`\n[nexus db] Restoring from ${stamp}...\n`);
+
+  for (const entry of manifest.dbs) {
+    if (!entry.ok) {
+      console.log(`  skip ${entry.db} — backup was incomplete`);
+      continue;
+    }
+    const backupFile = join(backupPath, entry.file);
+
+    if (entry.type === 'sqlite') {
+      // Find original path from manifest root
+      const originalPath = manifest.dbs.find(d => d.db === entry.db)
+        ? join(manifest.root, entry.db) : null;
+      if (originalPath && existsSync(backupFile)) {
+        copyFileSync(backupFile, originalPath);
+        console.log(`  ✓ sqlite ${entry.db} restored`);
+      } else {
+        console.log(`  ✗ sqlite ${entry.db}: original path not found — copy manually from ${backupFile}`);
+      }
+    }
+
+    if (entry.type === 'postgres') {
+      const url = env.DATABASE_URL || env.POSTGRES_URL;
+      if (!url) { console.log(`  ✗ postgres: DATABASE_URL not set`); continue; }
+      const result = spawnSync('psql', [url, '--file', backupFile], { stdio: 'inherit' });
+      console.log(result.status === 0 ? `  ✓ postgres restored` : `  ✗ postgres restore failed`);
+    }
+
+    if (entry.type === 'mysql') {
+      const url = env.DATABASE_URL || env.MYSQL_URL;
+      if (!url) { console.log(`  ✗ mysql: DATABASE_URL not set`); continue; }
+      const result = spawnSync('sh', ['-c', `mysql "${url}" < "${backupFile}"`], { stdio: 'inherit' });
+      console.log(result.status === 0 ? `  ✓ mysql restored` : `  ✗ mysql restore failed`);
+    }
+  }
+  console.log('');
+}
+
+function runSchedule(root) {
+  const nexusBin = 'nexus db backup';
+  console.log('\nnexus db schedule — daily backup setup\n');
+  console.log('Add one of these to your crontab (`crontab -e`):\n');
+  console.log(`  # Daily at 2am`);
+  console.log(`  0 2 * * * cd ${root} && ${nexusBin} >> .nexus/db-backups/cron.log 2>&1\n`);
+  console.log('Or for a project-specific .env-aware setup:');
+  console.log(`  0 2 * * * cd ${root} && source .env && ${nexusBin} >> .nexus/db-backups/cron.log 2>&1\n`);
+  console.log('Backups are stored in: .nexus/db-backups/');
+  console.log('Restore with: nexus db restore <stamp>');
+  console.log('');
+}