@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/session-guard.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * aioson session:guard [projectDir] --agent=<name> --tool=<tool>
+ *
+ * Background supervisor that keeps a live session alive.
+ * - If no live session exists: auto-starts one (no-launch mode)
+ * - Polls every 30s to verify the session is still open
+ * - Detects inactivity (no events for --idle-minutes, default: 60) and closes gracefully
+ * - Works alongside hooks:emit — guard handles session lifecycle, hooks handle events
+ *
+ * Run in background:
+ *   aioson session:guard . --agent=dev --tool=claude &
+ *
+ * Or as a foreground check (--once):
+ *   aioson session:guard . --agent=dev --tool=claude --once
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const {
+  openRuntimeDb,
+  resolveRuntimePaths,
+  readAgentSession,
+  writeAgentSession,
+  startTask,
+  startRun,
+  updateRun,
+  updateTask,
+  appendRunEvent
+} = require('../runtime-store');
+
+const POLL_INTERVAL_MS = 30_000;
+const DEFAULT_IDLE_MINUTES = 60;
+
+function nowIso() { return new Date().toISOString(); }
+function log(msg) { process.stderr.write(`[session:guard] ${msg}\n`); }
+
+async function getLastEventTime(runtimeDir, sessionKey) {
+  const eventsPath = path.join(runtimeDir, 'live', sessionKey, 'events.ndjson');
+  try {
+    const content = await fs.readFile(eventsPath, 'utf8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    const last = JSON.parse(lines[lines.length - 1]);
+    return last.ts ? new Date(last.ts) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function startLiveSession(targetDir, runtimeDir, agentName, tool) {
+  const now = nowIso();
+  const sessionKey = `guard-${agentName}-${Date.now()}`;
+  const title = `[guard] ${agentName} via ${tool}`;
+
+  const { db } = await openRuntimeDb(targetDir);
+  try {
+    const taskKey = startTask(db, {
+      sessionKey,
+      title,
+      status: 'running',
+      createdBy: agentName,
+      taskKind: 'live_session',
+      metaJson: { tool_session: tool, path: targetDir, guarded: true }
+    });
+
+    const runKey = startRun(db, {
+      taskKey,
+      agentName,
+      agentKind: 'official',
+      sessionKey,
+      source: 'live',
+      title,
+      eventType: 'session_started',
+      phase: 'live',
+      message: `Session auto-started by session:guard (${tool})`,
+      payload: { tool_session: tool, path: targetDir, guarded: true }
+    });
+
+    await writeAgentSession(runtimeDir, agentName, {
+      runKey, taskKey, sessionKey,
+      startedAt: now, finished: false, source: 'live'
+    });
+
+    // Create state.json for dashboard
+    const stateDir = path.join(runtimeDir, 'live', sessionKey);
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, 'state.json'), JSON.stringify({
+      session_key: sessionKey, run_key: runKey, task_key: taskKey,
+      agent_name: agentName, tool_session: tool,
+      status: 'running', started_at: now, updated_at: now, guarded: true,
+      last_events: [{ ts: now, type: 'session_started', summary: `Auto-started by session:guard (${tool})` }]
+    }, null, 2), 'utf8');
+
+    log(`Session started: ${sessionKey} (run: ${runKey})`);
+    return { runKey, taskKey, sessionKey };
+  } finally {
+    db.close();
+  }
+}
+
+async function closeSession(targetDir, runtimeDir, agentName, runKey, taskKey, reason) {
+  const now = nowIso();
+  const { db } = await openRuntimeDb(targetDir, { mustExist: true });
+  try {
+    appendRunEvent(db, {
+      runKey, eventType: 'session_ended', phase: 'live',
+      status: 'completed', message: `Session closed by session:guard: ${reason}`,
+      createdAt: now
+    });
+    updateRun(db, runKey, { status: 'completed', summary: reason, finishedAt: now });
+    if (taskKey) updateTask(db, taskKey, { status: 'completed', finishedAt: now });
+
+    // Update state.json
+    const { db: _, ...rest } = await readAgentSession(runtimeDir, agentName).catch(() => ({}));
+    const sessionKey = rest?.sessionKey;
+    if (sessionKey) {
+      const statePath = path.join(runtimeDir, 'live', sessionKey, 'state.json');
+      try {
+        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        state.status = 'closed';
+        state.updated_at = now;
+        await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8');
+      } catch { /* non-fatal */ }
+    }
+
+    // Clear session file
+    const sessionFile = path.join(runtimeDir, '.sessions', `${agentName}.json`);
+    try { await fs.unlink(sessionFile); } catch { /* already gone */ }
+
+    log(`Session closed: ${runKey} (${reason})`);
+  } finally {
+    db.close();
+  }
+}
+
+async function tick(targetDir, runtimeDir, agentName, tool, idleMs, state) {
+  const session = await readAgentSession(runtimeDir, agentName);
+
+  if (!session || session.finished) {
+    // No session — start one
+    const created = await startLiveSession(targetDir, runtimeDir, agentName, tool);
+    state.runKey = created.runKey;
+    state.taskKey = created.taskKey;
+    state.sessionKey = created.sessionKey;
+    state.startedAt = Date.now();
+    return;
+  }
+
+  // Session exists — check for idle timeout
+  const sessionKey = session.sessionKey;
+  const lastEvent = await getLastEventTime(runtimeDir, sessionKey);
+  const now = Date.now();
+  const lastActivity = lastEvent ? lastEvent.getTime() : state.startedAt;
+  const idleFor = now - lastActivity;
+
+  if (idleFor > idleMs) {
+    const idleMin = Math.round(idleFor / 60000);
+    log(`Idle for ${idleMin}m — closing session`);
+    await closeSession(targetDir, runtimeDir, agentName, session.runKey, session.taskKey,
+      `Idle for ${idleMin} minutes`);
+    state.runKey = null;
+    state.taskKey = null;
+    state.sessionKey = null;
+  }
+}
+
+async function runSessionGuard({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  const tool = options.tool ? String(options.tool).trim() : 'claude';
+  const once = options.once || options['once'] || false;
+  const idleMinutes = Number(options['idle-minutes'] || options.idleMinutes || DEFAULT_IDLE_MINUTES);
+  const idleMs = idleMinutes * 60 * 1000;
+  const intervalMs = Number(options.interval || POLL_INTERVAL_MS);
+
+  const { runtimeDir } = resolveRuntimePaths(targetDir);
+  const state = { runKey: null, taskKey: null, sessionKey: null, startedAt: Date.now() };
+
+  if (!options.json) {
+    logger.log(`[session:guard] Watching: ${targetDir}`);
+    logger.log(`[session:guard] Agent: @${agentName} | Tool: ${tool} | Idle timeout: ${idleMinutes}m`);
+    logger.log(`[session:guard] Press Ctrl+C to stop.`);
+  }
+
+  await tick(targetDir, runtimeDir, agentName, tool, idleMs, state);
+
+  if (once) {
+    return { ok: true, runKey: state.runKey, sessionKey: state.sessionKey };
+  }
+
+  return new Promise((resolve) => {
+    const timer = setInterval(async () => {
+      try {
+        await tick(targetDir, runtimeDir, agentName, tool, idleMs, state);
+      } catch (err) {
+        log(`Error: ${err.message}`);
+      }
+    }, intervalMs);
+
+    const shutdown = async () => {
+      clearInterval(timer);
+      if (state.runKey) {
+        try {
+          await closeSession(targetDir, runtimeDir, agentName, state.runKey, state.taskKey, 'session:guard stopped');
+        } catch { /* best-effort */ }
+      }
+      if (!options.json) logger.log('[session:guard] Stopped.');
+      resolve({ ok: true });
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+}
+
+module.exports = { runSessionGuard };

package/src/commands/setup-context.js

@@ -3,6 +3,25 @@
 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,
@@ -469,7 +488,7 @@ async function runSetupContext({ args, options, logger, t }) {
     profile: 'developer',
     framework: detectedFramework,
     frameworkInstalled: detectedInstalled,
-    conversationLanguage: 'en',
+    conversationLanguage: detectSystemLanguage(),
     designSkill: '',
     testRunner: '',
     web3Enabled: inferredWeb3Enabled,
@@ -674,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 };

package/src/commands/sizing.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * aioson sizing — Sheldon's sizing decision (inplace / phased_inplace / phased_external).
+ *
+ * Reads a PRD file and counts entities, phases, integrations, user flows, and ACs.
+ * Returns a sizing score and delivery recommendation.
+ *
+ * Usage:
+ *   aioson sizing . --prd=.aioson/context/prd-checkout.md
+ *   aioson sizing . --feature=checkout
+ *   aioson sizing . --feature=checkout --json
+ */
+
+const path = require('node:path');
+const { readFileSafe, contextDir } = require('../preflight-engine');
+
+const BAR = '━'.repeat(30);
+
+// Scoring:
+//   main entities > 3    → +1
+//   delivery phases > 1  → +2
+//   external integrations → +1
+//   user flows > 3       → +0 (no penalty)
+//   AC count > 10        → +1
+//   Score 0-2 → inplace
+//   Score 3   → phased_inplace
+//   Score 4+  → phased_external
+
+function countEntities(content) {
+  // Look for entity mentions: model/entity/table patterns
+  const patterns = [
+    /\b(model|entity|table|resource|object)\s+["`']?([A-Z][a-zA-Z]+)["`']?/g,
+    /## [A-Z][a-zA-Z]+ (Model|Entity|Table)/g,
+    /\b([A-Z][a-zA-Z]+Model)\b/g
+  ];
+  const entities = new Set();
+  for (const pattern of patterns) {
+    let m;
+    while ((m = pattern.exec(content)) !== null) {
+      entities.add((m[2] || m[1]).toLowerCase());
+    }
+  }
+  // Also count H3 headings as potential entities
+  const h3 = content.match(/^### [A-Z][a-zA-Z ]+$/gm) || [];
+  return Math.max(entities.size, Math.floor(h3.length / 2));
+}
+
+function countPhases(content) {
+  // Look for delivery phase / phase N patterns
+  const phaseRe = /\b(phase|stage|sprint|iteration)\s+\d+/gi;
+  const deliveryRe = /##\s+(phase|stage|delivery|sprint)\s+\d+/gi;
+  const phases = new Set();
+  let m;
+  while ((m = phaseRe.exec(content)) !== null) phases.add(m[0].toLowerCase());
+  while ((m = deliveryRe.exec(content)) !== null) phases.add(m[0].toLowerCase());
+  return phases.size;
+}
+
+function countIntegrations(content) {
+  const integrations = [
+    /\b(stripe|paypal|braintree|square|mercadopago)\b/gi,
+    /\b(sendgrid|mailchimp|ses|postmark|smtp)\b/gi,
+    /\b(twilio|vonage|nexmo|sms)\b/gi,
+    /\b(s3|cloudinary|gcs|azure)\b/gi,
+    /\b(oauth|auth0|firebase|cognito)\b/gi,
+    /\b(redis|elasticsearch|algolia)\b/gi,
+    /\bAPI\s+(call|integration)\b/gi,
+    /\bwebhook[s]?\b/gi,
+    /\bexternal\s+service[s]?\b/gi
+  ];
+  const found = new Set();
+  for (const pattern of integrations) {
+    let m;
+    while ((m = pattern.exec(content)) !== null) found.add(m[0].toLowerCase());
+  }
+  return found.size;
+}
+
+function countUserFlows(content) {
+  // User flow = "as a X, I want to Y" or numbered flow steps
+  const asAre = content.match(/As an? [a-z]+, I want/gi) || [];
+  const flowRe = content.match(/\bflow\s+\d+\b/gi) || [];
+  return asAre.length + flowRe.length;
+}
+
+function countACs(content) {
+  // Acceptance criteria: checkboxes or "AC-N" patterns
+  const checkboxes = content.match(/^[-*]\s+\[[ x]\]/gmi) || [];
+  const acRe = content.match(/\bAC[-\s]?\d+\b/g) || [];
+  return Math.max(checkboxes.length, acRe.length);
+}
+
+function sizingDecision(score) {
+  if (score <= 2) return { decision: 'inplace', instruction: 'Implement directly in PRD' };
+  if (score === 3) return { decision: 'phased_inplace', instruction: 'Add ## Delivery plan section to PRD' };
+  return { decision: 'phased_external', instruction: 'Create separate delivery plan document' };
+}
+
+async function runSizing({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+
+  let prdPath = options.prd ? path.resolve(targetDir, options.prd) : null;
+
+  if (!prdPath && slug) {
+    prdPath = path.join(contextDir(targetDir), `prd-${slug}.md`);
+  }
+
+  if (!prdPath) {
+    if (options.json) return { ok: false, reason: 'no_prd', message: 'Provide --prd=<path> or --feature=<slug>' };
+    logger.log('Provide --prd=<path> or --feature=<slug>');
+    return { ok: false };
+  }
+
+  const content = await readFileSafe(prdPath);
+  if (!content) {
+    if (options.json) return { ok: false, reason: 'file_not_found', path: prdPath };
+    logger.log(`File not found: ${path.relative(targetDir, prdPath)}`);
+    return { ok: false };
+  }
+
+  const entities = countEntities(content);
+  const phases = countPhases(content);
+  const integrations = countIntegrations(content);
+  const flows = countUserFlows(content);
+  const acs = countACs(content);
+
+  const entityScore = entities > 3 ? 1 : 0;
+  const phaseScore = phases > 1 ? 2 : 0;
+  const intScore = integrations >= 1 ? 1 : 0;
+  const flowScore = 0; // flows ≤ 3 → +0; only informational
+  const acScore = acs > 10 ? 1 : 0;
+
+  const totalScore = entityScore + phaseScore + intScore + flowScore + acScore;
+  const { decision, instruction } = sizingDecision(totalScore);
+
+  const result = {
+    ok: true,
+    prd_path: path.relative(targetDir, prdPath),
+    metrics: { entities, phases, integrations, user_flows: flows, ac_count: acs },
+    scores: { entities: entityScore, phases: phaseScore, integrations: intScore, acs: acScore, total: totalScore },
+    decision,
+    instruction
+  };
+
+  if (options.json) return result;
+
+  const header = slug ? `Sizing — ${slug}` : `Sizing — ${path.relative(targetDir, prdPath)}`;
+  logger.log('');
+  logger.log(header);
+  logger.log(BAR);
+  logger.log(`Main entities:           ${entities}  → +${entityScore}${entities > 3 ? ' (above 3)' : ''}`);
+  logger.log(`Delivery phases:         ${phases}  → +${phaseScore}${phases > 1 ? ' (above 1)' : ''}`);
+  logger.log(`External integrations:   ${integrations}  → +${intScore}`);
+  logger.log(`User flows:              ${flows}  → +0${flows > 3 ? ' (above 3 — informational)' : ''}`);
+  logger.log(`AC count:                ${acs}  → +${acScore}${acs > 10 ? ' (above 10)' : ''}`);
+  logger.log(BAR);
+  logger.log(`Score: ${totalScore} → ${decision} (${instruction})`);
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runSizing };