@jaimevalasek/aioson 1.4.0 → 1.5.1

package/src/cli.js

@@ -32,6 +32,8 @@ const { runQaInit } = require('./commands/qa-init');
 const { runQaRun } = require('./commands/qa-run');
 const { runQaScan } = require('./commands/qa-scan');
 const { runQaReport } = require('./commands/qa-report');
+const { runWebMap } = require('./commands/web-map');
+const { runWebScrape } = require('./commands/web-scrape');
 const { runScanProject } = require('./commands/scan-project');
 const { runConfig } = require('./commands/config');
 const { runGenomeDoctor } = require('./commands/genome-doctor');
@@ -48,6 +50,17 @@ const { runImplementationPlan } = require('./commands/implementation-plan');
 const { runSquadPlan } = require('./commands/squad-plan');
 const { runSquadLearning } = require('./commands/squad-learning');
 const { runLearning } = require('./commands/learning');
+const { runSquadDashboard } = require('./commands/squad-dashboard');
+const { runSquadWorker } = require('./commands/squad-worker');
+const { runSquadDaemon } = require('./commands/squad-daemon');
+const { runSquadMcp } = require('./commands/squad-mcp');
+const { runSquadRoi } = require('./commands/squad-roi');
+const { runSquadScore } = require('./commands/squad-score');
+const { runSquadProcesses } = require('./commands/squad-processes');
+const { runSquadWorktrees, runSquadMerge } = require('./commands/squad-worktrees');
+const { runSquadRecovery } = require('./commands/squad-recovery');
+const { runSquadDeploy } = require('./commands/squad-deploy');
+const { runSquadWebhook } = require('./commands/squad-webhook');
 const {
   runRuntimeInit,
   runRuntimeIngest,
@@ -60,6 +73,8 @@ const {
   runRuntimeFail,
   runRuntimeStatus,
   runRuntimeLog,
+  runAgentDone,
+  runAgentRecover,
   runRuntimeSessionStart,
   runRuntimeSessionLog,
   runRuntimeSessionFinish,
@@ -93,6 +108,7 @@ const {
   runSkillList,
   runSkillRemove
 } = require('./commands/skill');
+const { runBackupLocal } = require('./commands/backup-local-cmd');
 
 const JSON_SUPPORTED_COMMANDS = new Set([
   'init',
@@ -159,6 +175,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'qa-scan',
   'qa:report',
   'qa-report',
+  'web:map',
+  'web-map',
+  'web:scrape',
+  'web-scrape',
   'scan:project',
   'scan-project',
   'config',
@@ -182,6 +202,31 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'squad-agent-create',
   'squad:investigate',
   'squad-investigate',
+  'squad:dashboard',
+  'squad-dashboard',
+  'squad:worker',
+  'squad-worker',
+  'squad:daemon',
+  'squad-daemon',
+  'squad:mcp',
+  'squad-mcp',
+  'squad:mcp:call',
+  'squad:roi',
+  'squad-roi',
+  'squad:score',
+  'squad-score',
+  'squad:processes',
+  'squad-processes',
+  'squad:worktrees',
+  'squad-worktrees',
+  'squad:merge',
+  'squad-merge',
+  'squad:recovery',
+  'squad-recovery',
+  'squad:deploy',
+  'squad-deploy',
+  'squad:webhook',
+  'squad-webhook',
   'plan:show',
   'plan:status',
   'plan:checkpoint',
@@ -218,6 +263,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'runtime-status',
   'runtime:log',
   'runtime-log',
+  'agent:done',
+  'agent-done',
+  'agent:recover',
+  'agent-recover',
   'runtime:session:start',
   'runtime-session-start',
   'runtime:session:log',
@@ -333,6 +382,8 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_qa_run');
   logHelpLine(t, logger, 'cli.help_qa_scan');
   logHelpLine(t, logger, 'cli.help_qa_report');
+  logHelpLine(t, logger, 'cli.help_web_map');
+  logHelpLine(t, logger, 'cli.help_web_scrape');
   logHelpLine(t, logger, 'cli.help_scan_project');
   logHelpLine(t, logger, 'cli.help_config');
   logHelpLine(t, logger, 'cli.help_genome_doctor');
@@ -345,6 +396,12 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_squad_pipeline');
   logHelpLine(t, logger, 'cli.help_squad_agent_create');
   logHelpLine(t, logger, 'cli.help_squad_investigate');
+  logHelpLine(t, logger, 'cli.help_squad_dashboard');
+  logHelpLine(t, logger, 'cli.help_squad_worker');
+  logHelpLine(t, logger, 'cli.help_squad_daemon');
+  logHelpLine(t, logger, 'cli.help_squad_mcp');
+  logHelpLine(t, logger, 'cli.help_squad_roi');
+  logHelpLine(t, logger, 'cli.help_squad_score');
   logHelpLine(t, logger, 'cli.help_squad_learning');
   logHelpLine(t, logger, 'cli.help_learning');
   logHelpLine(t, logger, 'cli.help_runtime_init');
@@ -523,6 +580,10 @@ async function main() {
       result = await runQaScan({ args, options, logger: commandLogger, t });
     } else if (command === 'qa:report' || command === 'qa-report') {
       result = await runQaReport({ args, options, logger: commandLogger, t });
+    } else if (command === 'web:map' || command === 'web-map') {
+      result = await runWebMap({ args, options, logger: commandLogger, t });
+    } else if (command === 'web:scrape' || command === 'web-scrape') {
+      result = await runWebScrape({ args, options, logger: commandLogger, t });
     } else if (command === 'scan:project' || command === 'scan-project') {
       result = await runScanProject({ args, options, logger: commandLogger, t });
     } else if (command === 'config') {
@@ -547,6 +608,37 @@ async function main() {
       result = await runSquadAgentCreate({ args, options, logger: commandLogger, t });
     } else if (command === 'squad:investigate' || command === 'squad-investigate') {
       result = await runSquadInvestigate({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:dashboard' || command === 'squad-dashboard') {
+      result = await runSquadDashboard({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:worker' || command === 'squad-worker') {
+      const sub = options.sub || 'list';
+      result = await runSquadWorker({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command === 'squad:daemon' || command === 'squad-daemon') {
+      const sub = options.sub || 'status';
+      result = await runSquadDaemon({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command === 'squad:mcp:call') {
+      result = await runSquadMcp({ args, options: { ...options, sub: 'call' }, logger: commandLogger, t });
+    } else if (command === 'squad:mcp' || command === 'squad-mcp') {
+      const sub = options.sub || 'status';
+      result = await runSquadMcp({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command === 'squad:roi' || command === 'squad-roi') {
+      const sub = options.sub || 'report';
+      result = await runSquadRoi({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command === 'squad:score' || command === 'squad-score') {
+      result = await runSquadScore({ args, options, logger: commandLogger, translator: t });
+    } else if (command === 'squad:processes' || command === 'squad-processes') {
+      result = await runSquadProcesses({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:worktrees' || command === 'squad-worktrees') {
+      result = await runSquadWorktrees({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:merge' || command === 'squad-merge') {
+      result = await runSquadMerge({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:recovery' || command === 'squad-recovery') {
+      result = await runSquadRecovery({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:deploy' || command === 'squad-deploy') {
+      result = await runSquadDeploy({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:webhook' || command === 'squad-webhook') {
+      const sub = options.sub || 'start';
+      result = await runSquadWebhook({ args, options: { ...options, sub }, logger: commandLogger, t });
     } else if (command === 'squad:plan' || command === 'squad-plan') {
       result = await runSquadPlan({ args, options, logger: commandLogger, t });
     } else if (command === 'squad:learning' || command === 'squad-learning') {
@@ -580,6 +672,10 @@ async function main() {
       result = await runRuntimeStatus({ args, options, logger: commandLogger, t });
     } else if (command === 'runtime:log' || command === 'runtime-log') {
       result = await runRuntimeLog({ args, options, logger: commandLogger, t });
+    } else if (command === 'agent:done' || command === 'agent-done') {
+      result = await runAgentDone({ args, options, logger: commandLogger, t });
+    } else if (command === 'agent:recover' || command === 'agent-recover') {
+      result = await runAgentRecover({ args, options, logger: commandLogger, t });
     } else if (command === 'runtime:session:start' || command === 'runtime-session-start') {
       result = await runRuntimeSessionStart({ args, options, logger: commandLogger, t });
     } else if (command === 'runtime:session:log' || command === 'runtime-session-log') {
@@ -614,6 +710,8 @@ async function main() {
       result = await runRuntimeBackup({ args, options, logger: commandLogger, t });
     } else if (command === 'runtime:restore' || command === 'runtime-restore') {
       result = await runRuntimeRestore({ args, options, logger: commandLogger, t });
+    } else if (command === 'backup:local' || command === 'backup-local') {
+      result = await runBackupLocal({ args, options, logger: commandLogger, t });
     } else if (command === 'skill:install' || command === 'skill-install') {
       result = await runSkillInstall({ args, options, logger: commandLogger, t });
     } else if (command === 'skill:list' || command === 'skill-list') {

package/src/commands/backup-local-cmd.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const path = require('node:path');
+const { backupAiosonDocs } = require('../backup-local');
+
+/**
+ * aioson backup:local [.]
+ *
+ * Manually backs up all .md files from .aioson/context/ and .aioson/plans/
+ * to ~/.aioson/backups/{project}/{timestamp}/
+ */
+async function runBackupLocal({ args, options, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const result = await backupAiosonDocs(targetDir);
+
+  if (result.count === 0) {
+    logger.log('backup:local — nothing to back up (no .md files found in .aioson/context/ or .aioson/plans/)');
+    return { ok: true, count: 0, backupPath: null };
+  }
+
+  logger.log(`backup:local — ${result.count} file(s) backed up → ${result.backupPath}`);
+  return { ok: true, count: result.count, backupPath: result.backupPath };
+}
+
+module.exports = { runBackupLocal };

package/src/commands/runtime.js

@@ -20,6 +20,7 @@ const {
 } = require('../runtime-store');
 const { runAutoDelivery } = require('../delivery-runner');
 const { writeHandoff, buildRuntimeLogHandoff } = require('../session-handoff');
+const { backupAiosonDocs, isDocCreatingAgent } = require('../backup-local');
 
 const ALLOWED_LAYOUTS = new Set(['document', 'tabs', 'accordion', 'stack', 'mixed']);
 const DEFAULT_TEXT_FIELDS = ['content', 'text', 'body', 'lyrics', 'markdown'];
@@ -1159,6 +1160,80 @@ async function runRuntimeLog({ args, options = {}, logger, t }) {
 }
 
 
+/**
+ * aioson agent:done . --agent=<name> --summary="..." [--title="..."] [--status=completed|failed]
+ *
+ * Safe self-registration for official agents invoked directly (not via workflow:next or live:start).
+ * - If an active live session exists for the agent: appends a completion event without closing the session.
+ * - If no session exists: creates a standalone task+run and immediately marks it completed.
+ *
+ * Intended to be called ONCE at the very end of an agent session, after delivering the main artifact.
+ */
+async function runAgentDone({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agentName = String(options.agent || '').trim();
+  if (!agentName) {
+    throw new Error('--agent is required');
+  }
+  const normalizedAgent = agentName.startsWith('@') ? agentName : `@${agentName}`;
+  const summary = String(options.summary || options.message || `${normalizedAgent} session completed`).trim();
+  const title = options.title ? String(options.title).trim() : null;
+  const status = options.status || 'completed';
+
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  try {
+    const session = await readAgentSession(runtimeDir, normalizedAgent);
+    const hasActiveSession = session && !session.finished && session.runKey;
+
+    if (hasActiveSession) {
+      // Live or tracked session is already open — only append a completion note.
+      // Do NOT close the session: live:handoff or live:close owns the lifecycle.
+      appendRunEvent(db, {
+        runKey: session.runKey,
+        eventType: 'agent_done',
+        phase: 'live',
+        status: 'running',
+        message: summary
+      });
+
+      if (!options.json) {
+        logger.log(`agent:done — ${normalizedAgent} | live session active, event logged | run: ${session.runKey} (${dbPath})`);
+      }
+
+      if (isDocCreatingAgent(normalizedAgent)) {
+        backupAiosonDocs(targetDir).catch(() => {});
+      }
+
+      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey };
+    }
+
+    // No active session — create a standalone task+run and immediately complete it.
+    const { runKey, taskKey } = await logAgentEvent(db, runtimeDir, {
+      agentName: normalizedAgent,
+      message: summary,
+      type: 'completed',
+      taskTitle: title || normalizedAgent,
+      finish: true,
+      status,
+      summary
+    });
+
+    if (!options.json) {
+      logger.log(`agent:done — ${normalizedAgent} | task: ${taskKey} | run: ${runKey} (${dbPath})`);
+    }
+
+    if (isDocCreatingAgent(normalizedAgent)) {
+      backupAiosonDocs(targetDir).catch(() => {});
+    }
+
+    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey };
+  } finally {
+    db.close();
+  }
+}
+
+
 async function runRuntimeSessionStart({ args, options = {}, logger, t }) {
   const targetDir = resolveTargetDir(args);
   const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
@@ -1683,6 +1758,171 @@ function parseFrontmatter(content) {
   return result;
 }
 
+/**
+ * Parses a duration string like "24h", "30m", "7d" into milliseconds.
+ * Falls back to treating the raw value as hours.
+ */
+function parseDurationMs(value, defaultHours = 24) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return defaultHours * 60 * 60 * 1000;
+
+  const match = text.match(/^(\d+(?:\.\d+)?)\s*([hmd]?)$/);
+  if (!match) return defaultHours * 60 * 60 * 1000;
+
+  const n = parseFloat(match[1]);
+  const unit = match[2] || 'h';
+  if (unit === 'd') return n * 24 * 60 * 60 * 1000;
+  if (unit === 'm') return n * 60 * 1000;
+  return n * 60 * 60 * 1000; // hours (default)
+}
+
+/**
+ * aioson agent:recover [targetDir] [--older-than=<duration>] [--dry-run]
+ *
+ * Detects and closes agent sessions that were abandoned (Claude Code closed before
+ * agent:done was called, or live:start session was never closed).
+ *
+ * Sources checked:
+ *   1. Session files in .aioson/.sessions/ with finished=false older than threshold.
+ *   2. agent_runs rows with status='running'/'queued' and started_at older than threshold
+ *      that have no corresponding live session file (orphaned DB records).
+ *
+ * --older-than  Duration threshold. Accepts: 24h (default), 8h, 30m, 7d.
+ * --dry-run     Report what would be recovered without making any changes.
+ * --json        Output JSON result.
+ */
+async function runAgentRecover({ args, options = {}, logger }) {
+  const targetDir = resolveTargetDir(args);
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
+  const olderThanMs = parseDurationMs(options['older-than'] || options.olderThan, 24);
+  const cutoffMs = Date.now() - olderThanMs;
+  const cutoffIso = new Date(cutoffMs).toISOString();
+  const now = new Date().toISOString();
+
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  const recovered = [];
+  const skipped = [];
+
+  try {
+    // ── 1. Scan session files ─────────────────────────────────────────────────
+    const sessionsDir = path.join(runtimeDir, '.sessions');
+    let sessionFiles = [];
+    try {
+      const entries = await fs.readdir(sessionsDir);
+      sessionFiles = entries.filter((f) => f.endsWith('.json'));
+    } catch {
+      // .sessions dir may not exist — that's fine
+    }
+
+    for (const file of sessionFiles) {
+      const filePath = path.join(sessionsDir, file);
+      let session;
+      try {
+        session = JSON.parse(await fs.readFile(filePath, 'utf8'));
+      } catch {
+        continue;
+      }
+
+      if (session.finished) continue;
+
+      const startedAt = session.startedAt ? new Date(session.startedAt).getTime() : 0;
+      if (startedAt > cutoffMs) {
+        skipped.push({ source: 'session_file', file, reason: 'within_threshold', startedAt: session.startedAt });
+        continue;
+      }
+
+      const agentName = file.replace(/\.json$/, '');
+      const runKey = session.runKey || null;
+      const taskKey = session.taskKey || null;
+
+      if (!dryRun) {
+        // Mark run as abandoned
+        if (runKey) {
+          const runRow = db.prepare('SELECT run_key, status FROM agent_runs WHERE run_key = ?').get(runKey);
+          if (runRow && (runRow.status === 'running' || runRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE agent_runs
+              SET status = 'abandoned', summary = 'Recovered: session abandoned without close', updated_at = ?, finished_at = ?
+              WHERE run_key = ?
+            `).run(now, now, runKey);
+          }
+        }
+        // Mark task as abandoned
+        if (taskKey) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(taskKey);
+          if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE tasks
+              SET status = 'abandoned', updated_at = ?, finished_at = ?
+              WHERE task_key = ?
+            `).run(now, now, taskKey);
+          }
+        }
+        // Remove session file
+        try { await fs.unlink(filePath); } catch { /* noop */ }
+      }
+
+      recovered.push({ source: 'session_file', agent: agentName, runKey, taskKey, startedAt: session.startedAt });
+    }
+
+    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
+    const orphanedRuns = db.prepare(`
+      SELECT run_key, task_key, agent_name, started_at
+      FROM agent_runs
+      WHERE status IN ('running', 'queued')
+        AND source = 'direct'
+        AND started_at < ?
+    `).all(cutoffIso);
+
+    for (const run of orphanedRuns) {
+      // Skip if already recovered via session file
+      if (recovered.some((r) => r.runKey === run.run_key)) continue;
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE agent_runs
+          SET status = 'abandoned', summary = 'Recovered: orphaned run with no session file', updated_at = ?, finished_at = ?
+          WHERE run_key = ?
+        `).run(now, now, run.run_key);
+
+        if (run.task_key) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
+          if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE tasks
+              SET status = 'abandoned', updated_at = ?, finished_at = ?
+              WHERE task_key = ?
+            `).run(now, now, run.task_key);
+          }
+        }
+      }
+
+      recovered.push({ source: 'orphaned_run', agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
+    }
+
+    // ── Output ────────────────────────────────────────────────────────────────
+    const olderThanLabel = options['older-than'] || options.olderThan || '24h';
+    if (recovered.length === 0) {
+      logger.log(`agent:recover — no abandoned sessions found older than ${olderThanLabel} (${dbPath})`);
+    } else {
+      const verb = dryRun ? '[dry-run] would recover' : 'recovered';
+      logger.log(`agent:recover — ${verb} ${recovered.length} abandoned session(s) older than ${olderThanLabel} (${dbPath})`);
+      for (const r of recovered) {
+        logger.log(`  ${r.agent}  started: ${r.startedAt || '?'}  run: ${r.runKey || '—'}  [${r.source}]`);
+      }
+    }
+    if (skipped.length > 0) {
+      logger.log(`  skipped ${skipped.length} session(s) within threshold.`);
+    }
+
+    return { ok: true, targetDir, dbPath, dryRun, cutoff: cutoffIso, recovered, skipped };
+  } finally {
+    db.close();
+  }
+}
+
+
 /**
  * aioson runtime:prune [targetDir] --older-than=<days>
  *
@@ -1767,6 +2007,8 @@ module.exports = {
   runRuntimeFail,
   runRuntimeStatus,
   runRuntimeLog,
+  runAgentDone,
+  runAgentRecover,
   runRuntimeSessionStart,
   runRuntimeSessionLog,
   runRuntimeSessionFinish,

package/src/commands/setup-context.js

@@ -8,7 +8,8 @@ const {
   calculateClassification,
   normalizeBoolean,
   renderProjectContext,
-  writeProjectContext
+  writeProjectContext,
+  renderSquadApiSection
 } = require('../context-writer');
 const { applyAgentLocale } = require('../locales');
 const { openRuntimeDb, logAgentEvent } = require('../runtime-store');
@@ -208,6 +209,7 @@ function applyExplicitOverrides(data, options, detectedInstalled) {
   const langValue = options.language ?? options.lang;
   if (langValue !== undefined) output.conversationLanguage = String(langValue);
   if (hasOption(options, 'design-skill')) output.designSkill = String(options['design-skill']);
+  if (hasOption(options, 'test-runner')) output.testRunner = String(options['test-runner']);
   if (hasOption(options, 'web3-enabled')) {
     output.web3Enabled = normalizeBoolean(options['web3-enabled'], output.web3Enabled);
   }
@@ -469,6 +471,7 @@ async function runSetupContext({ args, options, logger, t }) {
     frameworkInstalled: detectedInstalled,
     conversationLanguage: 'en',
     designSkill: '',
+    testRunner: '',
     web3Enabled: inferredWeb3Enabled,
     web3Networks: inferredWeb3Enabled ? inferWeb3Network(detectedFramework) : '',
     contractFramework: inferredWeb3Enabled ? detectedFramework : '',
@@ -616,7 +619,9 @@ async function runSetupContext({ args, options, logger, t }) {
   }
 
   const content = renderProjectContext(data);
-  const filePath = await writeProjectContext(targetDir, content);
+  const squadApiSection = await renderSquadApiSection(targetDir);
+  const fullContent = squadApiSection ? content + '\n' + squadApiSection + '\n' : content;
+  const filePath = await writeProjectContext(targetDir, fullContent);
   const localeApplyResult = await applyAgentLocale(targetDir, data.conversationLanguage, {
     dryRun: false
   });