@jaimevalasek/aioson 1.4.0 → 1.6.0

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/sandbox.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const path = require('node:path');
+const { executeInSandbox } = require('../sandbox');
+
+async function runSandboxExec({ args, options, logger }) {
+  const command = args[0] || options.command || '';
+  const cwd = path.resolve(process.cwd(), options.cwd || '.');
+  const timeout = Number(options.timeout) || 30_000;
+  const intent = options.intent || undefined;
+
+  if (!command) {
+    logger.error('Usage: aioson sandbox:exec "<command>" [--timeout=30000] [--cwd=.]');
+    return { ok: false, error: 'missing_command' };
+  }
+
+  const result = await executeInSandbox(command, { cwd, timeout, intent });
+
+  if (options.json) {
+    return { ok: result.ok, ...result };
+  }
+
+  if (result.stdout) {
+    logger.log(result.stdout);
+  }
+  if (result.stderr) {
+    logger.error(result.stderr);
+  }
+
+  if (result.timedOut) {
+    logger.error(`Command timed out after ${timeout}ms`);
+  }
+
+  return { ok: result.ok, ...result };
+}
+
+module.exports = { runSandboxExec };

package/src/commands/setup-context.js

@@ -3,12 +3,32 @@
 const path = require('node:path');
 const readline = require('node:readline/promises');
 const { detectFramework, isMonorepoDetection } = require('../detector');
+
+/**
+ * Infer conversation language from the OS locale environment variables.
+ * Supports LANGUAGE, LANG, and LC_ALL in priority order.
+ * Maps POSIX locale codes (e.g. pt_BR.UTF-8) to AIOSON locale codes (e.g. pt-BR).
+ */
+function detectSystemLanguage() {
+  const raw = process.env.LANGUAGE || process.env.LANG || process.env.LC_ALL || '';
+  const base = raw.split(':')[0].split('.')[0].trim();
+  if (!base || base === 'C' || base === 'POSIX') return 'en';
+  const normalized = base.replace('_', '-');
+  const supported = ['en', 'pt-BR', 'es', 'fr'];
+  if (supported.includes(normalized)) return normalized;
+  const lang = normalized.split('-')[0].toLowerCase();
+  if (lang === 'pt') return 'pt-BR';
+  if (lang === 'es') return 'es';
+  if (lang === 'fr') return 'fr';
+  return 'en';
+}
 const { getCliVersionSync } = require('../version');
 const {
   calculateClassification,
   normalizeBoolean,
   renderProjectContext,
-  writeProjectContext
+  writeProjectContext,
+  renderSquadApiSection
 } = require('../context-writer');
 const { applyAgentLocale } = require('../locales');
 const { openRuntimeDb, logAgentEvent } = require('../runtime-store');
@@ -208,6 +228,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);
   }
@@ -467,8 +488,9 @@ async function runSetupContext({ args, options, logger, t }) {
     profile: 'developer',
     framework: detectedFramework,
     frameworkInstalled: detectedInstalled,
-    conversationLanguage: 'en',
+    conversationLanguage: detectSystemLanguage(),
     designSkill: '',
+    testRunner: '',
     web3Enabled: inferredWeb3Enabled,
     web3Networks: inferredWeb3Enabled ? inferWeb3Network(detectedFramework) : '',
     contractFramework: inferredWeb3Enabled ? detectedFramework : '',
@@ -616,7 +638,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
   });
@@ -669,5 +693,6 @@ module.exports = {
   runSetupContext,
   servicesToContextFields,
   mergeProfileData,
-  applyExplicitOverrides
+  applyExplicitOverrides,
+  detectSystemLanguage
 };

package/src/commands/setup.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const { installTemplate, readInstallProfile } = require('../installer');
+const { detectFramework } = require('../detector');
+const { detectSystemLanguage } = require('./setup-context');
+const { runSetupContext } = require('./setup-context');
+const { resolvePromptTool } = require('../prompt-tool');
+const { normalizeBoolean } = require('../context-writer');
+const { runInstallWizard } = require('../install-wizard');
+
+async function ask(rl, question, fallback = '') {
+  const suffix = fallback ? ` (${fallback})` : '';
+  const value = await rl.question(`${question}${suffix}: `);
+  const cleaned = String(value || '').trim();
+  if (!cleaned) return fallback;
+  return cleaned;
+}
+
+async function runSetup({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run']);
+  const force = Boolean(options.force);
+  const defaultsMode = Boolean(options.defaults);
+  const promptTool = resolvePromptTool(options.tool);
+
+  // Step 1 — detect install profile (wizard if first time in TTY)
+  const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+  let installProfile = null;
+
+  if (!dryRun && isTTY) {
+    const existingProfile = await readInstallProfile(targetDir);
+    if (!existingProfile) {
+      installProfile = await runInstallWizard({});
+    } else {
+      installProfile = existingProfile;
+    }
+  }
+
+  // Step 2 — install template
+  logger.log(t('setup.installing'));
+  const installResult = await installTemplate(targetDir, {
+    overwrite: force,
+    dryRun,
+    mode: 'install',
+    installProfile
+  });
+  logger.log(t('setup.installed', { count: installResult.copied.length }));
+
+  // Step 3 — detect framework and system language
+  const detection = await detectFramework(targetDir);
+  const detectedFramework = detection.framework;
+  const detectedInstalled = detection.installed;
+  const systemLang = detectSystemLanguage();
+
+  // Build setup:context options by merging detected state with explicit flags
+  const contextOptions = { defaults: true };
+
+  // Propagate any explicit overrides the user passed to `setup`
+  const passthroughFlags = [
+    'project-name', 'project-type', 'framework', 'framework-installed',
+    'classification', 'lang', 'language', 'profile', 'backend', 'frontend',
+    'database', 'auth', 'uiux', 'design-skill', 'test-runner',
+    'web3-enabled', 'web3-networks', 'contract-framework',
+    'wallet-provider', 'indexer', 'rpc-provider',
+    'queues', 'storage', 'websockets', 'payments', 'email', 'cache', 'search'
+  ];
+  for (const flag of passthroughFlags) {
+    if (Object.prototype.hasOwnProperty.call(options, flag)) {
+      contextOptions[flag] = options[flag];
+    }
+  }
+
+  // Apply language: explicit flag > system detection
+  if (!contextOptions.lang && !contextOptions.language) {
+    contextOptions.lang = systemLang;
+  }
+
+  // For greenfield projects (nothing detected), ask minimal interactive questions
+  // unless --defaults is set or the user already passed --framework
+  const isGreenfield = !detectedFramework;
+  const frameworkProvided = Object.prototype.hasOwnProperty.call(options, 'framework');
+
+  if (!defaultsMode && isGreenfield && !frameworkProvided) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    try {
+      logger.log(t('setup.no_framework_detected'));
+
+      const projectName = await ask(
+        rl,
+        t('setup.q_project_name'),
+        path.basename(targetDir) || 'my-project'
+      );
+      if (projectName !== path.basename(targetDir)) {
+        contextOptions['project-name'] = projectName;
+      }
+
+      const framework = await ask(rl, t('setup.q_framework'), '');
+      if (framework) {
+        contextOptions.framework = framework;
+        contextOptions['framework-installed'] = 'false';
+      }
+
+      const detectedLang = contextOptions.lang || systemLang;
+      const lang = await ask(rl, t('setup.q_lang'), detectedLang);
+      contextOptions.lang = lang;
+    } finally {
+      rl.close();
+    }
+  } else if (!defaultsMode && detectedFramework) {
+    // Existing project with detected framework — confirm before proceeding
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    try {
+      logger.log(
+        t('setup.framework_detected', {
+          framework: detectedFramework,
+          installed: String(detectedInstalled)
+        })
+      );
+
+      const confirmed = normalizeBoolean(
+        await ask(rl, t('setup.q_confirm_framework'), 'true'),
+        true
+      );
+
+      if (!confirmed) {
+        const override = await ask(rl, t('setup.q_override_framework'), detectedFramework);
+        contextOptions.framework = override;
+        contextOptions['framework-installed'] = await ask(
+          rl,
+          t('setup.q_framework_installed'),
+          'false'
+        );
+      }
+
+      const detectedLang = contextOptions.lang || systemLang;
+      const lang = await ask(rl, t('setup.q_lang'), detectedLang);
+      contextOptions.lang = lang;
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Step 4 — run setup:context with fully resolved options
+  logger.log(t('setup.writing_context'));
+  const contextResult = await runSetupContext({
+    args: [targetDir],
+    options: contextOptions,
+    logger,
+    t
+  });
+
+  if (!dryRun) {
+    logger.log('');
+    logger.log(t('setup.done'));
+    logger.log(t('setup.step_agents'));
+    logger.log(t('setup.step_agent_prompt', { tool: promptTool }));
+  }
+
+  return {
+    ok: true,
+    targetDir,
+    installResult,
+    contextResult,
+    detection
+  };
+}
+
+module.exports = { runSetup };