@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/brief-validate.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * aioson brief:validate — Validate brief completeness before spawning
+ *
+ * Usage:
+ *   aioson brief:validate . --brief=briefs/phase-1.md
+ *   aioson brief:validate . --brief=briefs/phase-1.md --auto-fix
+ *   aioson brief:validate . --brief=briefs/phase-1.md --json
+ */
+
+const path = require('node:path');
+const { validateBrief, autoFixBrief } = require('../squad/brief-validator');
+
+async function runBriefValidate({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const briefPath = String(options.brief || options.b || '').trim();
+
+  if (!briefPath) {
+    logger.error('Error: --brief=<path> is required');
+    return { ok: false, error: 'missing_brief' };
+  }
+
+  const result = await validateBrief(briefPath, targetDir);
+
+  // Auto-fix if requested and possible
+  if (!result.ready && options['auto-fix'] && result.autoFixable) {
+    const fixResult = await autoFixBrief(briefPath, targetDir);
+    if (fixResult.fixed) {
+      logger.log(`Auto-fixed: ${fixResult.fieldsFixed.join(', ')}`);
+      // Re-validate after fix
+      const recheck = await validateBrief(briefPath, targetDir);
+      if (options.json) {
+        return { ...recheck, autoFixed: fixResult.fieldsFixed };
+      }
+      printResult(recheck, logger, fixResult.fieldsFixed);
+      return { ok: recheck.ready, ...recheck, autoFixed: fixResult.fieldsFixed };
+    }
+  }
+
+  if (options.json) return result;
+
+  printResult(result, logger);
+  return { ok: result.ready, ...result };
+}
+
+function printResult(result, logger, autoFixed) {
+  const status = result.ready ? 'READY' : `NOT READY (${result.issues.length} blocking issue${result.issues.length > 1 ? 's' : ''})`;
+  logger.log(`Score: ${result.score}/${result.total} — ${status}`);
+
+  if (result.issues.length > 0) {
+    logger.log('');
+    for (const issue of result.issues) {
+      const fix = issue.autoFixable ? ' [auto-fixable]' : '';
+      logger.log(`  ✗ ${issue.field}: ${issue.message}${fix}`);
+    }
+  }
+
+  if (autoFixed && autoFixed.length > 0) {
+    logger.log('');
+    logger.log(`Auto-fixed fields: ${autoFixed.join(', ')}`);
+  }
+}
+
+module.exports = { runBriefValidate };

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-cache.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const path = require('node:path');
+const { saveContextShadow, listSessions, restoreContext, cleanup } = require('../context-cache');
+
+async function runContextCacheList({ args, options, logger }) {
+  const cacheDir = options.cacheDir || undefined;
+  const sessions = await listSessions({ cacheDir });
+
+  if (options.json) {
+    return { ok: true, sessions };
+  }
+
+  if (sessions.length === 0) {
+    logger.log('No cached sessions found.');
+    return { ok: true, sessions: [] };
+  }
+
+  logger.log('\n  Cached Context Sessions\n');
+  for (const s of sessions) {
+    const kb = Math.round(s.size / 1024);
+    const goal = s.metadata.goal ? ` — ${s.metadata.goal.slice(0, 50)}` : '';
+    logger.log(`  ${s.sessionId}  ${s.createdAt.slice(0, 16)}  ${kb}KB${goal}`);
+  }
+  logger.log('');
+
+  return { ok: true, sessions };
+}
+
+async function runContextCacheSave({ args, options, logger }) {
+  const cwd = path.resolve(process.cwd(), args[0] || '.');
+  const content = options.content || '';
+
+  if (!content) {
+    logger.error('--content is required. Example: aioson context:cache:save . --content="..." --goal="..."');
+    return { ok: false, error: 'missing_content' };
+  }
+
+  const result = await saveContextShadow(content, {
+    goal: options.goal || '',
+    agent: options.agent || '',
+    projectDir: cwd
+  });
+
+  if (options.json) return result;
+
+  logger.log(`Context saved. Session ID: ${result.sessionId}`);
+  logger.log(`Path: ${result.path}`);
+  return result;
+}
+
+async function runContextCacheRestore({ args, options, logger }) {
+  const sessionId = options.session || args[0] || '';
+  const cacheDir = options.cacheDir || undefined;
+
+  if (!sessionId) {
+    logger.error('--session=<id> is required.');
+    return { ok: false, error: 'missing_session' };
+  }
+
+  const result = await restoreContext(sessionId, {
+    cacheDir,
+    query: options.query || undefined
+  });
+
+  if (!result.ok) {
+    logger.error(`Restore failed: ${result.error}`);
+    return result;
+  }
+
+  if (options.json) return result;
+
+  logger.log(result.content);
+  return result;
+}
+
+async function runContextCacheCleanup({ args, options, logger }) {
+  const cacheDir = options.cacheDir || undefined;
+  const maxAgeHours = Number(options['max-age']) || 24;
+  const maxAge = maxAgeHours * 60 * 60 * 1000;
+
+  const result = await cleanup({ cacheDir, maxAge });
+
+  if (options.json) return { ok: true, ...result };
+
+  logger.log(`Removed ${result.removed} expired session(s).`);
+  return { ok: true, ...result };
+}
+
+module.exports = { runContextCacheList, runContextCacheSave, runContextCacheRestore, runContextCacheCleanup };

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 };