@jaimevalasek/aioson 1.6.0 → 1.7.0

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

package/src/commands/skill.js

@@ -397,6 +397,58 @@ async function runSkillInstall({ args, options = {}, logger, t }) {
   };
 }
 
+/**
+ * Parse a minimal extension.yml manifest if present in a skill directory.
+ * Reads only top-level scalar fields and one level of nesting.
+ * Returns null if the file is absent or unreadable.
+ */
+async function parseExtensionManifest(skillDir) {
+  const manifestPath = path.join(skillDir, 'extension.yml');
+  let raw;
+  try {
+    raw = await fs.readFile(manifestPath, 'utf8');
+  } catch {
+    return null; // file not present — this is the normal case for old skills
+  }
+
+  const manifest = {};
+  let currentSection = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Detect top-level section (no leading spaces, ends with colon, no value)
+    if (/^\w[\w-]*:$/.test(trimmed)) {
+      currentSection = trimmed.slice(0, -1);
+      manifest[currentSection] = {};
+      continue;
+    }
+
+    // Nested key: value (indented with spaces or tab)
+    if (currentSection && /^\s+/.test(line)) {
+      const idx = trimmed.indexOf(':');
+      if (idx === -1) continue;
+      const key = trimmed.slice(0, idx).trim();
+      const val = trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) manifest[currentSection][key] = val;
+      continue;
+    }
+
+    // Top-level scalar key: value
+    const idx = trimmed.indexOf(':');
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    const val = trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) {
+      currentSection = null;
+      manifest[key] = val;
+    }
+  }
+
+  return manifest;
+}
+
 /**
  * Scan a directory for .md files with SKILL.md or frontmatter descriptions.
  * Returns array of { slug, name, description, type, path }.
@@ -478,6 +530,9 @@ async function runSkillList({ args, options = {}, logger, t }) {
         meta?.generated_by_model ||
         null;
 
+      // Read optional extension.yml manifest — additive, does not affect existing behavior
+      const extManifest = showAll ? await parseExtensionManifest(path.join(skillsDir, slug)) : null;
+
       installed.push({
         slug,
         name: fm.name || slug,
@@ -485,6 +540,7 @@ async function runSkillList({ args, options = {}, logger, t }) {
         source,
         author,
         model,
+        manifest: extManifest,
         path: path.relative(targetDir, path.join(skillsDir, slug))
       });
     }
@@ -519,6 +575,15 @@ async function runSkillList({ args, options = {}, logger, t }) {
       }
       if (s.author) logger.log(`    author: ${s.author}`);
       if (s.model) logger.log(`    model: ${s.model}`);
+      if (showAll && s.manifest) {
+        const ext = s.manifest.extension || {};
+        if (ext.version) logger.log(`    version: ${ext.version}`);
+        const hooks = s.manifest.hooks;
+        if (hooks && typeof hooks === 'object') {
+          const hookNames = Object.keys(hooks).filter(h => hooks[h]?.enabled !== 'false' && hooks[h]?.enabled !== false);
+          if (hookNames.length > 0) logger.log(`    hooks declared: ${hookNames.join(', ')}`);
+        }
+      }
       logger.log(`    ${s.path}/SKILL.md`);
       logger.log('');
     }

package/src/commands/spec-checkpoint.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb, appendRunEvent } = require('../runtime-store');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function extractLastCheckpoint(content) {
+  // Try frontmatter first
+  const fmMatch = content.match(/^---[\s\S]*?last_checkpoint:\s*(.+)/m);
+  if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, '');
+  // Try section header
+  const sectionMatch = content.match(/##\s+last_checkpoint[^\n]*\n([\s\S]*?)(?=\n##|\s*$)/i);
+  if (sectionMatch) return sectionMatch[1].replace(/^[-*]\s*/, '').trim();
+  return null;
+}
+
+function extractPhaseGates(content) {
+  const fm = parseFrontmatter(content);
+  if (!fm.phase_gates) return null;
+  try {
+    return JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+  } catch {
+    return null;
+  }
+}
+
+async function runSpecCheckpoint({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const featureSlug = options.feature ? String(options.feature).trim() : null;
+  const agentName = options.agent ? String(options.agent).trim() : 'dev';
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+
+  if (!featureSlug) {
+    if (!options.json) logger.log('Error: --feature=<slug> is required.');
+    return { ok: false, reason: 'missing_feature' };
+  }
+
+  // Find spec file
+  const candidates = [
+    path.join(contextDir, `spec-${featureSlug}.md`),
+    path.join(contextDir, 'spec.md')
+  ];
+
+  let specPath = null;
+  let specContent = null;
+  for (const candidate of candidates) {
+    try {
+      specContent = await fs.readFile(candidate, 'utf8');
+      specPath = candidate;
+      break;
+    } catch { /* try next */ }
+  }
+
+  if (!specContent) {
+    if (!options.json) logger.log(`No spec file found for feature: ${featureSlug}`);
+    return { ok: false, reason: 'no_spec_file', featureSlug };
+  }
+
+  const lastCheckpoint = extractLastCheckpoint(specContent);
+  const phaseGates = extractPhaseGates(specContent);
+
+  if (!lastCheckpoint) {
+    if (!options.json) logger.log(`No last_checkpoint found in ${path.basename(specPath)}.`);
+    return { ok: false, reason: 'no_checkpoint', specPath };
+  }
+
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true });
+
+  if (!db) {
+    if (!options.json) logger.log('No runtime database found. Run aioson agent:done first.');
+    return { ok: false, reason: 'no_db' };
+  }
+
+  try {
+    // Find latest agent run for this feature
+    const run = db.prepare(`
+      SELECT r.run_key, r.status, r.summary, r.updated_at
+      FROM agent_runs r
+      WHERE r.agent_name = ?
+        AND (r.run_key LIKE ? OR r.task_key LIKE ?)
+      ORDER BY r.updated_at DESC
+      LIMIT 1
+    `).get(agentName, `%${featureSlug}%`, `%${featureSlug}%`);
+
+    // If no run with feature slug, try latest run by agent name
+    const activeRun = run || db.prepare(`
+      SELECT run_key, status, summary, updated_at
+      FROM agent_runs
+      WHERE agent_name = ? AND status IN ('running', 'completed')
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `).get(agentName);
+
+    if (!activeRun) {
+      if (!options.json) {
+        logger.log(`No active run found for agent @${agentName}.`);
+        logger.log('Tip: run aioson runtime:start first, or specify --agent=<name>.');
+      }
+      return { ok: false, reason: 'no_run', featureSlug, agentName };
+    }
+
+    // Append checkpoint event
+    appendRunEvent(db, {
+      runKey: activeRun.run_key,
+      eventType: 'plan_checkpoint',
+      phase: 'spec',
+      status: 'in_progress',
+      message: lastCheckpoint,
+      payload: phaseGates ? { phase_gates: phaseGates } : null,
+      createdAt: nowIso()
+    });
+
+    // Update run summary to last_checkpoint if run is still in_progress
+    if (activeRun.status !== 'completed') {
+      db.prepare(
+        'UPDATE agent_runs SET summary = ?, updated_at = ? WHERE run_key = ?'
+      ).run(lastCheckpoint, nowIso(), activeRun.run_key);
+    }
+
+    if (options.json) {
+      return {
+        ok: true,
+        featureSlug,
+        specPath,
+        lastCheckpoint,
+        phaseGates,
+        runKey: activeRun.run_key,
+        dbPath
+      };
+    }
+
+    logger.log(`Reading ${path.basename(specPath)}...`);
+    logger.log(`last_checkpoint: "${lastCheckpoint}"`);
+    if (phaseGates) {
+      logger.log(`phase_gates: ${JSON.stringify(phaseGates)}`);
+    }
+    logger.log('');
+    logger.log('Checkpoint registered:');
+    logger.log(`  run_key: ${activeRun.run_key}`);
+    logger.log(`  summary: "${lastCheckpoint}"`);
+    logger.log(`  status: in_progress (checkpoint only — use agent:done to close)`);
+    logger.log('');
+    logger.log(`Next: continue with /${agentName} — start from last_checkpoint`);
+
+    return {
+      ok: true,
+      featureSlug,
+      specPath,
+      lastCheckpoint,
+      phaseGates,
+      runKey: activeRun.run_key,
+      dbPath
+    };
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { runSpecCheckpoint };

package/src/commands/spec-status.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+async function runSpecStatus({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true });
+
+  if (!db) {
+    if (!options.json) logger.log('No runtime database found. Run aioson agent:done first.');
+    return { ok: false, reason: 'no_db' };
+  }
+
+  try {
+    const plans = db.prepare(`
+      SELECT plan_id, feature_slug, status, phases_total, phases_completed, created_at, updated_at
+      FROM implementation_plans
+      WHERE status != 'archived'
+      ORDER BY updated_at DESC
+    `).all();
+
+    const rows = [];
+    for (const plan of plans) {
+      const lastRun = db.prepare(`
+        SELECT r.agent_name, r.summary, r.updated_at
+        FROM agent_runs r
+        JOIN tasks t ON r.task_key = t.task_key
+        WHERE r.status IN ('running', 'completed')
+          AND (t.session_key LIKE ? OR r.agent_name IS NOT NULL)
+        ORDER BY r.updated_at DESC
+        LIMIT 1
+      `).get(`%${plan.feature_slug || ''}%`);
+
+      rows.push({
+        feature: plan.feature_slug || '(project)',
+        phase: `${plan.phases_completed}/${plan.phases_total}`,
+        status: plan.status,
+        lastAgent: lastRun?.agent_name || '—',
+        checkpoint: lastRun?.summary ? lastRun.summary.slice(0, 60) : '—'
+      });
+    }
+
+    const totalLearnings = db.prepare(
+      "SELECT COUNT(*) as cnt FROM project_learnings WHERE status = 'active'"
+    ).get()?.cnt || 0;
+
+    const promotable = db.prepare(
+      "SELECT COUNT(*) as cnt FROM project_learnings WHERE status = 'active' AND frequency >= 3"
+    ).get()?.cnt || 0;
+
+    if (options.json) {
+      return { ok: true, features: rows, totalLearnings, promotable, dbPath };
+    }
+
+    logger.log(`Project Status — ${targetDir}`);
+    logger.log('─'.repeat(80));
+    logger.log('Feature'.padEnd(20) + 'Phase'.padEnd(10) + 'Status'.padEnd(16) + 'Last Agent'.padEnd(16) + 'Checkpoint');
+    logger.log('─'.repeat(80));
+    for (const r of rows) {
+      logger.log(
+        r.feature.padEnd(20) +
+        r.phase.padEnd(10) +
+        r.status.padEnd(16) +
+        r.lastAgent.padEnd(16) +
+        r.checkpoint
+      );
+    }
+    logger.log('─'.repeat(80));
+    logger.log(`Active learnings: ${totalLearnings}  |  Promotable (freq≥3): ${promotable}`);
+
+    return { ok: true, features: rows, totalLearnings, promotable, dbPath };
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { runSpecStatus };