@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/commands/classify.js

@@ -0,0 +1,256 @@
+'use strict';
+
+/**
+ * aioson classify — deterministic classification scoring (MICRO/SMALL/MEDIUM).
+ *
+ * Reads prd-{slug}.md or requirements-{slug}.md and counts complexity indicators.
+ * Falls back to --interactive mode if insufficient data.
+ *
+ * Usage:
+ *   aioson classify . --feature=checkout
+ *   aioson classify . --feature=checkout --json
+ *   aioson classify . --interactive
+ */
+
+const path = require('node:path');
+const readline = require('node:readline');
+const { readFileSafe, contextDir } = require('../preflight-engine');
+
+const BAR = '━'.repeat(30);
+
+// Scoring thresholds
+// user_types: 1→0, 2→1, 3+→2
+// external_integrations: 0→0, 1-2→1, 3+→2
+// rule_complexity: none→0, some→1, complex→2
+// Score: 0-1=MICRO, 2-3=SMALL, 4-6=MEDIUM
+
+function scoreUserTypes(count) {
+  if (count >= 3) return 2;
+  if (count >= 2) return 1;
+  return 0;
+}
+
+function scoreIntegrations(count) {
+  if (count >= 3) return 2;
+  if (count >= 1) return 1;
+  return 0;
+}
+
+function scoreComplexity(level) {
+  if (level === 'complex') return 2;
+  if (level === 'some') return 1;
+  return 0;
+}
+
+function scoreToClassification(score) {
+  if (score <= 1) return 'MICRO';
+  if (score <= 3) return 'SMALL';
+  return 'MEDIUM';
+}
+
+function classificationToPhaseDepth(classification) {
+  if (classification === 'MICRO') {
+    return {
+      specify: 'brief note or inline',
+      research: 'not needed',
+      requirements: 'optional',
+      design: 'skip',
+      plan: 'optional',
+      execute: 'direct from task description'
+    };
+  }
+  if (classification === 'SMALL') {
+    return {
+      specify: 'full PRD',
+      research: 'recommended (@sheldon)',
+      requirements: 'required (requirements-{slug}.md)',
+      design: 'selective (only if new pattern)',
+      plan: 'recommended',
+      execute: 'from requirements + spec'
+    };
+  }
+  return {
+    specify: 'full PRD + stakeholder review',
+    research: 'required (@sheldon)',
+    requirements: 'required + conformance YAML',
+    design: 'required (@ux-ui + @architect)',
+    plan: 'required + @pm backlog',
+    execute: 'from approved plan, phased delivery'
+  };
+}
+
+// Pattern-based auto-detection from markdown content
+
+const USER_TYPE_PATTERNS = [
+  /\b(admin|administrator)\b/gi,
+  /\b(user|customer|client|buyer|seller|vendor|manager|operator|guest|visitor|member|owner|reviewer|moderator)\b/gi,
+  /\bAs an? ([a-z]+)/gi,
+  /\brole[s]?\b.*?:\s*([^,\n]+)/gi
+];
+
+const INTEGRATION_PATTERNS = [
+  /\b(stripe|paypal|braintree|square)\b/gi,
+  /\b(sendgrid|mailchimp|ses|postmark|smtp)\b/gi,
+  /\b(twilio|vonage|nexmo)\b/gi,
+  /\b(s3|cloudinary|gcs|azure blob)\b/gi,
+  /\b(oauth|jwt|saml|sso|auth0|firebase auth)\b/gi,
+  /\b(redis|memcached|elasticsearch|algolia)\b/gi,
+  /\bAPI\s+(integration|endpoint|call)\b/gi,
+  /\bthird.party\b/gi,
+  /\bwebhook[s]?\b/gi,
+  /\bexternal\s+service\b/gi
+];
+
+const COMPLEXITY_HIGH_PATTERNS = [
+  /\b(multi.step|multi-phase|pipeline|workflow)\b/gi,
+  /\b(state machine|finite state|transition)\b/gi,
+  /\b(calculation|formula|algorithm|score|pricing engine)\b/gi,
+  /\b(complex|intricate|elaborate)\s+(logic|rule|condition)/gi,
+  /\b(concurrent|parallel|async|queue)\b/gi,
+  /\b(if.+then.+else|conditional|depends on)\b/gi
+];
+
+const COMPLEXITY_SOME_PATTERNS = [
+  /\b(validation|constraint|rule)\b/gi,
+  /\b(permission|role.based|access control)\b/gi,
+  /\b(notification|trigger|event)\b/gi
+];
+
+function analyzeContent(content) {
+  // Count unique user types
+  const userTypeSet = new Set();
+  for (const pattern of USER_TYPE_PATTERNS) {
+    let m;
+    while ((m = pattern.exec(content)) !== null) {
+      userTypeSet.add(m[1] ? m[1].toLowerCase() : m[0].toLowerCase());
+    }
+  }
+  const userTypeCount = Math.min(userTypeSet.size, 5);
+
+  // Count integrations
+  const integrationSet = new Set();
+  for (const pattern of INTEGRATION_PATTERNS) {
+    let m;
+    while ((m = pattern.exec(content)) !== null) {
+      integrationSet.add(m[0].toLowerCase());
+    }
+  }
+  const integrationCount = integrationSet.size;
+
+  // Complexity level
+  let complexityLevel = 'none';
+  const highMatches = COMPLEXITY_HIGH_PATTERNS.some((p) => p.test(content));
+  if (highMatches) {
+    complexityLevel = 'complex';
+  } else {
+    const someMatches = COMPLEXITY_SOME_PATTERNS.some((p) => p.test(content));
+    if (someMatches) complexityLevel = 'some';
+  }
+
+  return { userTypeCount, integrationCount, complexityLevel };
+}
+
+async function runInteractive(logger) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    logger.log('');
+    logger.log('Classification — Interactive Mode');
+    logger.log(BAR);
+
+    const utRaw = await ask('User types (1 / 2 / 3+): ');
+    const userTypeCount = parseInt(utRaw) || 1;
+
+    const intRaw = await ask('External integrations (0 / 1-2 / 3+): ');
+    const integrationCount = parseInt(intRaw) || 0;
+
+    const cxRaw = await ask('Business rule complexity (none / some / complex): ');
+    const complexityLevel = ['none', 'some', 'complex'].includes(cxRaw.trim().toLowerCase())
+      ? cxRaw.trim().toLowerCase()
+      : 'none';
+
+    rl.close();
+    return { userTypeCount, integrationCount, complexityLevel };
+  } catch {
+    rl.close();
+    return { userTypeCount: 1, integrationCount: 0, complexityLevel: 'none' };
+  }
+}
+
+async function runClassify({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+  const interactive = Boolean(options.interactive);
+
+  let userTypeCount, integrationCount, complexityLevel;
+  let sourceFile = null;
+
+  if (interactive) {
+    ({ userTypeCount, integrationCount, complexityLevel } = await runInteractive(logger));
+  } else {
+    // Auto-detect from PRD or requirements file
+    const dir = contextDir(targetDir);
+    const candidates = slug
+      ? [
+          path.join(dir, `requirements-${slug}.md`),
+          path.join(dir, `prd-${slug}.md`),
+          path.join(dir, `sheldon-enrichment-${slug}.md`)
+        ]
+      : [path.join(dir, 'requirements.md'), path.join(dir, 'prd.md')];
+
+    let content = null;
+    for (const candidate of candidates) {
+      content = await readFileSafe(candidate);
+      if (content) { sourceFile = path.relative(targetDir, candidate); break; }
+    }
+
+    if (!content) {
+      if (options.json) return { ok: false, reason: 'no_source', message: 'No prd or requirements file found. Use --interactive or --feature=<slug>.' };
+      logger.log('No source file found. Use --interactive or provide --feature=<slug>.');
+      return { ok: false };
+    }
+
+    ({ userTypeCount, integrationCount, complexityLevel } = analyzeContent(content));
+  }
+
+  const utScore = scoreUserTypes(userTypeCount);
+  const intScore = scoreIntegrations(integrationCount);
+  const cxScore = scoreComplexity(complexityLevel);
+  const totalScore = utScore + intScore + cxScore;
+  const classification = scoreToClassification(totalScore);
+  const phaseDepth = classificationToPhaseDepth(classification);
+
+  const result = {
+    ok: true,
+    feature_slug: slug,
+    source_file: sourceFile,
+    inputs: { user_types: userTypeCount, external_integrations: integrationCount, rule_complexity: complexityLevel },
+    scores: { user_types: utScore, integrations: intScore, complexity: cxScore, total: totalScore },
+    classification,
+    phase_depth: phaseDepth
+  };
+
+  if (options.json) return result;
+
+  const header = slug ? `Classification — ${slug}` : 'Classification';
+  logger.log('');
+  logger.log(header);
+  logger.log(BAR);
+  if (sourceFile) logger.log(`Source: ${sourceFile}`);
+  logger.log(`User types:              ${userTypeCount}  → +${utScore}`);
+  logger.log(`External integrations:   ${integrationCount}  → +${intScore}`);
+  logger.log(`Business rule complexity: ${complexityLevel} → +${cxScore}`);
+  logger.log(BAR);
+  logger.log(`Score: ${totalScore} → ${classification}`);
+  logger.log('');
+  logger.log('Phase depth:');
+  for (const [phase, desc] of Object.entries(phaseDepth)) {
+    logger.log(`  ${phase.padEnd(14)}: ${desc}`);
+  }
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runClassify };

package/src/commands/context-compact.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * aioson context:compact — Standalone context compaction
+ *
+ * Usage:
+ *   aioson context:compact . --agent=dev --input=devlog.md
+ *   aioson context:compact . --agent=orache --input=notes.md --session=abc-123
+ *   aioson context:compact . --agent=dev --json
+ */
+
+const path = require('node:path');
+const { compactContext } = require('../squad/context-compactor');
+
+async function runContextCompact({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agent = String(options.agent || options.a || 'dev').trim();
+  const input = options.input ? String(options.input).trim() : undefined;
+  const session = options.session ? String(options.session).trim() : undefined;
+
+  if (!input) {
+    logger.error('Error: --input=<path> is required (path to devlog, notes, or output)');
+    return { ok: false, error: 'missing_input' };
+  }
+
+  const result = await compactContext(targetDir, { agent, input, session });
+
+  if (!result.ok) {
+    logger.error(`Error: ${result.error}`);
+    return result;
+  }
+
+  if (options.json) return result.summary;
+
+  const s = result.summary.summary;
+  logger.log(`Context compacted for @${agent}`);
+  logger.log(`  Session:  ${result.summary.session_id}`);
+  logger.log(`  Tools:    ${s.tools_used.length} detected`);
+  logger.log(`  Requests: ${s.recent_requests.length} extracted`);
+  logger.log(`  Pending:  ${s.pending_work.length} items`);
+  logger.log(`  Files:    ${s.key_files.length} referenced`);
+  logger.log(`  Timeline: ${s.timeline.length} events`);
+  logger.log('');
+  logger.log(`Output: ${path.relative(targetDir, result.path)}`);
+
+  return { ok: true, ...result.summary };
+}
+
+module.exports = { runContextCompact };

package/src/commands/context-health.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+const CHARS_PER_TOKEN = 4;
+const HEAVY_TOKEN_THRESHOLD = 5000;   // ~20KB
+const CRITICAL_TOKEN_THRESHOLD = 12500; // ~50KB
+
+function estimateTokens(content) {
+  return Math.ceil(content.length / CHARS_PER_TOKEN);
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  return `${(bytes / 1024).toFixed(1)}KB`;
+}
+
+function formatTokens(n) {
+  return `~${n.toLocaleString()}`;
+}
+
+async function loadFeatureStatuses(contextDir) {
+  const featuresPath = path.join(contextDir, 'features.md');
+  try {
+    const content = await fs.readFile(featuresPath, 'utf8');
+    const done = new Set();
+    for (const line of content.split(/\r?\n/)) {
+      // Match lines like: - auth: done or | auth | done |
+      const m = line.match(/[-|]\s*([a-z0-9_-]+)\s*[:|]\s*done/i);
+      if (m) done.add(m[1].toLowerCase());
+    }
+    return done;
+  } catch {
+    return new Set();
+  }
+}
+
+async function getCacheHitRate(db) {
+  if (!db) return null;
+  try {
+    const rows = db.prepare(`
+      SELECT COUNT(*) as total,
+             SUM(CASE WHEN event_type = 'cache_hit' THEN 1 ELSE 0 END) as hits
+      FROM execution_events
+      WHERE created_at >= datetime('now', '-7 days')
+    `).get();
+    if (!rows || rows.total === 0) return null;
+    return Math.round((rows.hits / rows.total) * 100);
+  } catch {
+    return null;
+  }
+}
+
+async function runContextHealth({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+
+  let entries;
+  try {
+    entries = await fs.readdir(contextDir);
+  } catch {
+    if (!options.json) logger.log('No .aioson/context/ directory found.');
+    return { ok: false, reason: 'no_context_dir' };
+  }
+
+  const mdFiles = entries.filter((f) => f.endsWith('.md'));
+  const report = [];
+  let totalTokens = 0;
+
+  for (const file of mdFiles) {
+    try {
+      const content = await fs.readFile(path.join(contextDir, file), 'utf8');
+      const tokens = estimateTokens(content);
+      totalTokens += tokens;
+      report.push({
+        file,
+        sizeBytes: content.length,
+        tokens,
+        heavy: tokens > HEAVY_TOKEN_THRESHOLD,
+        critical: tokens > CRITICAL_TOKEN_THRESHOLD
+      });
+    } catch { /* skip unreadable files */ }
+  }
+
+  report.sort((a, b) => b.tokens - a.tokens);
+
+  const doneFeatures = await loadFeatureStatuses(contextDir);
+  const staleSpecs = report.filter((r) => {
+    if (!r.file.startsWith('spec-')) return false;
+    const slug = r.file.replace(/^spec-/, '').replace(/\.md$/, '');
+    return doneFeatures.has(slug);
+  });
+
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true }).catch(() => ({ db: null, dbPath: null }));
+  const cacheHitRate = await getCacheHitRate(db);
+  if (db) db.close();
+
+  const skeletonPresent = entries.includes('skeleton-system.md') || entries.includes('skeleton.md');
+
+  if (options.json) {
+    return {
+      ok: true,
+      totalTokens,
+      files: report,
+      staleSpecs: staleSpecs.map((s) => s.file),
+      cacheHitRate,
+      skeletonPresent,
+      dbPath
+    };
+  }
+
+  const COL_FILE = 28;
+  const COL_SIZE = 10;
+  const COL_TOKENS = 16;
+
+  logger.log(`Context Health Report — ${path.basename(targetDir)}`);
+  logger.log('─'.repeat(56));
+  logger.log('Files'.padEnd(COL_FILE) + 'Size'.padEnd(COL_SIZE) + 'Tokens (est.)');
+  logger.log('─'.repeat(56));
+
+  for (const r of report) {
+    const flag = r.critical ? ' !! CRITICAL' : r.heavy ? ' ⚠ HEAVY' : '';
+    logger.log(
+      r.file.padEnd(COL_FILE) +
+      formatBytes(r.sizeBytes).padEnd(COL_SIZE) +
+      formatTokens(r.tokens) + flag
+    );
+  }
+
+  logger.log('─'.repeat(56));
+  logger.log(`Total context load:`.padEnd(COL_FILE + COL_SIZE) + formatTokens(totalTokens) + ' tokens');
+  logger.log('');
+
+  const heavyFiles = report.filter((r) => r.heavy);
+  if (heavyFiles.length > 0) {
+    for (const r of heavyFiles) {
+      const label = r.critical ? 'CRITICAL' : 'heavy';
+      logger.log(`⚠  ${r.file} is ${label} (${formatBytes(r.sizeBytes)}). Consider:`);
+      logger.log(`   → Run: aioson context:pack . --scope=<feature>`);
+      logger.log(`     Creates a scoped context for a specific feature`);
+    }
+    logger.log('');
+  }
+
+  if (staleSpecs.length > 0) {
+    logger.log(`⚠  ${staleSpecs.length} stale spec file(s) (features: done):`);
+    for (const s of staleSpecs) {
+      const slug = s.file.replace(/^spec-/, '').replace(/\.md$/, '');
+      logger.log(`   → ${s.file} (feature: ${slug} is done)`);
+    }
+    logger.log(`   Run: aioson context:trim . to archive them`);
+    logger.log('');
+  }
+
+  if (cacheHitRate !== null) {
+    logger.log(`✓  Cache hit rate: ${cacheHitRate}% (last 7 days)`);
+  }
+  if (skeletonPresent) {
+    logger.log(`✓  skeleton-system.md present — agents can use as lightweight index`);
+  }
+
+  return {
+    ok: true,
+    totalTokens,
+    files: report,
+    staleSpecs: staleSpecs.map((s) => s.file),
+    cacheHitRate,
+    skeletonPresent,
+    dbPath
+  };
+}
+
+module.exports = { runContextHealth };

package/src/commands/context-monitor.js

@@ -6,6 +6,13 @@ const {
   computeWarningLevel,
   THRESHOLDS
 } = require('../squad-dashboard/context-monitor');
+const { openRuntimeDb, appendRunEvent } = require('../runtime-store');
+
+const PROJECT_BUDGET_ZONES = {
+  safe: 0.60,
+  warning: 0.80,
+  critical: 1.00
+};
 
 const BAR_WIDTH = 20;
 const LEVEL_ICONS = { normal: ' ', warning: '⚠', critical: '!', overflow: 'X', unknown: '?' };
@@ -36,15 +43,79 @@ function renderAgent(slug, agent) {
   return line;
 }
 
+async function emitBudgetEvent(cwd, { tokens, budget, pct, zone, agentName }) {
+  const { db } = await openRuntimeDb(cwd, { mustExist: true }).catch(() => ({ db: null }));
+  if (!db) return;
+  try {
+    const run = db.prepare(
+      "SELECT run_key FROM agent_runs WHERE status = 'running' ORDER BY updated_at DESC LIMIT 1"
+    ).get();
+    if (run) {
+      appendRunEvent(db, {
+        runKey: run.run_key,
+        eventType: zone === 'critical' ? 'context_budget_critical' : 'context_budget_warning',
+        phase: 'live',
+        status: 'running',
+        message: `Context at ${pct}% of budget (${tokens.toLocaleString()} tokens)`,
+        payload: { tokens, budget, pct, zone, agentName: agentName || null },
+        createdAt: new Date().toISOString()
+      });
+    }
+  } finally {
+    db.close();
+  }
+}
+
 async function runContextMonitor({ args, options, logger }) {
   const cwd = path.resolve(process.cwd(), args[0] || '.');
   const squadSlug = options.squad || null;
   const agentSlug = options.agent || null;
+  const budget = options.budget ? Number(options.budget) : null;
+
+  // Project-level budget monitoring (--budget=<tokens>)
+  if (budget && !squadSlug) {
+    const tokens = options.tokens ? Number(options.tokens) : null;
+    if (tokens !== null) {
+      const pct = Math.round((tokens / budget) * 100);
+      const zone = pct >= 100 ? 'overflow'
+        : pct >= PROJECT_BUDGET_ZONES.warning * 100 ? 'critical'
+        : pct >= PROJECT_BUDGET_ZONES.safe * 100 ? 'warning'
+        : 'safe';
+
+      const icon = zone === 'overflow' ? 'X' : zone === 'critical' ? '!' : zone === 'warning' ? '⚠' : '✓';
+
+      if (!options.json) {
+        logger.log(`  ${icon} Context: ${tokens.toLocaleString()} tokens (${pct}%) — ${zone.toUpperCase()}`);
+        if (zone === 'warning') {
+          logger.log(`  Suggestion: /clear before next agent activation`);
+        } else if (zone === 'critical' || zone === 'overflow') {
+          logger.log(`  Run: aioson context:health . for reduction options`);
+        }
+      }
+
+      if (zone === 'warning' || zone === 'critical' || zone === 'overflow') {
+        await emitBudgetEvent(cwd, { tokens, budget, pct, zone, agentName: agentSlug });
+      }
+
+      if (options.json) {
+        return { ok: true, tokens, budget, pct, zone };
+      }
+      return { ok: true, tokens, budget, pct, zone };
+    }
+
+    if (!options.json) {
+      logger.log(`  Budget: ${budget.toLocaleString()} tokens`);
+      logger.log(`  Zones: safe=<${PROJECT_BUDGET_ZONES.safe * 100}%  warning=${PROJECT_BUDGET_ZONES.safe * 100}-${PROJECT_BUDGET_ZONES.warning * 100}%  critical=>=${PROJECT_BUDGET_ZONES.warning * 100}%`);
+      logger.log(`  Use --tokens=<n> to check against budget`);
+    }
+    return { ok: true, budget, zones: PROJECT_BUDGET_ZONES };
+  }
 
   if (!squadSlug) {
     logger.log('\n  Context Monitor\n');
     logger.log('  No squad specified. Use --squad=<slug> to monitor a squad.');
     logger.log('  Example: aioson context:monitor . --squad=my-squad');
+    logger.log('  Or use --budget=<tokens> --tokens=<current> for project-level monitoring.');
     logger.log('');
     return { ok: true, squads: [] };
   }