@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/agent-audit.js

@@ -0,0 +1,397 @@
+'use strict';
+
+/**
+ * aioson agent:audit — Token and size audit for AIOSON agent files
+ *
+ * Scans .aioson/agents/*.md (and optionally locale variants) and reports:
+ *   - Size in chars and estimated tokens per file
+ *   - Size per section (## headings)
+ *   - Files and sections over budget thresholds
+ *   - Sections that are candidates to move to .aioson/docs/ (on-demand loading)
+ *   - Estimated token savings per session if candidates are moved
+ *
+ * Budget thresholds (from config.md guidelines):
+ *   Auto-loaded files (CLAUDE.md, AGENTS.md): 3,500 chars recommended / 4,000 hard
+ *   Agent files (read manually):
+ *     focused agents  (analyst, qa, tester):   8,000 chars
+ *     generalist agents (dev, architect):      15,000 chars
+ *     orchestrator agents (orchestrator, squad): 12,000 chars
+ *
+ * Usage:
+ *   aioson agent:audit .
+ *   aioson agent:audit . --verbose          Show per-section breakdown
+ *   aioson agent:audit . --locales          Include locale variant files
+ *   aioson agent:audit . --fix              Write savings report to .aioson/docs/agent-audit.md
+ *   aioson agent:audit . --json
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+// ─── Thresholds ───────────────────────────────────────────────────────────────
+
+const CHARS_PER_TOKEN = 4;
+
+// Agent type classification by slug keywords
+const AGENT_TYPES = [
+  { type: 'auto-loaded',   slugs: ['CLAUDE', 'AGENTS'],                    target: 3500, hard: 4000 },
+  { type: 'orchestrator',  slugs: ['orchestrator', 'squad'],                target: 12000, hard: 20000 },
+  { type: 'generalist',    slugs: ['dev', 'architect', 'deyvin', 'sheldon', 'setup', 'product', 'ux-ui', 'site-forge'], target: 15000, hard: 40000 },
+  { type: 'focused',       slugs: [],                                       target: 8000,  hard: 16000 } // default
+];
+
+// Sections considered "on-demand candidates" — rarely needed at session start
+const ON_DEMAND_KEYWORDS = [
+  'conventions', 'folder structure', 'stack', 'laravel', 'next.js', 'node',
+  'web3', 'dapp', 'brownfield', 'debugging', 'git worktree', 'worktree',
+  'motion', 'animation', 'output contract', 'output targets', 'format',
+  'devlog', 'observabilidade', 'observability', 'exemplos', 'examples',
+  'reference', 'template', 'esquema'
+];
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function estimateTokens(chars) {
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+function formatKb(chars) {
+  return `${(chars / 1024).toFixed(1)}KB`;
+}
+
+function formatTokens(chars) {
+  return `~${estimateTokens(chars).toLocaleString()} tok`;
+}
+
+function classifyAgent(slug) {
+  for (const def of AGENT_TYPES) {
+    if (def.slugs.some((s) => slug.toLowerCase().includes(s.toLowerCase()))) {
+      return def;
+    }
+  }
+  return AGENT_TYPES[AGENT_TYPES.length - 1]; // focused (default)
+}
+
+function isOnDemandCandidate(sectionTitle) {
+  const lower = sectionTitle.toLowerCase();
+  return ON_DEMAND_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+// ─── Section parser ───────────────────────────────────────────────────────────
+
+function parseSections(content) {
+  const sections = [];
+  const lines = content.split(/\r?\n/);
+  const headingRe = /^(#{1,4})\s+(.+)/;
+
+  let currentSection = null;
+  let currentLines = [];
+
+  function flush() {
+    if (currentSection !== null) {
+      const body = currentLines.join('\n');
+      sections.push({
+        title: currentSection.title,
+        level: currentSection.level,
+        chars: body.length,
+        tokens: estimateTokens(body.length),
+        onDemandCandidate: isOnDemandCandidate(currentSection.title)
+      });
+    }
+  }
+
+  for (const line of lines) {
+    const match = line.match(headingRe);
+    if (match) {
+      flush();
+      currentSection = { level: match[1].length, title: match[2].trim() };
+      currentLines = [line];
+    } else {
+      currentLines.push(line);
+    }
+  }
+  flush();
+
+  return sections;
+}
+
+// ─── File scanner ─────────────────────────────────────────────────────────────
+
+async function scanAgentFile(filePath, relativePath) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const slug = path.basename(filePath, '.md');
+  const typeDef = classifyAgent(slug);
+  const chars = content.length;
+  const sections = parseSections(content);
+
+  const onDemandSections = sections.filter((s) => s.onDemandCandidate);
+  const onDemandChars = onDemandSections.reduce((sum, s) => sum + s.chars, 0);
+
+  const status =
+    chars > typeDef.hard
+      ? 'over_hard'
+      : chars > typeDef.target
+        ? 'over_target'
+        : 'ok';
+
+  return {
+    file: relativePath,
+    slug,
+    agent_type: typeDef.type,
+    chars,
+    tokens: estimateTokens(chars),
+    target_chars: typeDef.target,
+    hard_chars: typeDef.hard,
+    status,
+    sections,
+    on_demand_candidates: onDemandSections,
+    savings_if_moved: onDemandChars,
+    savings_tokens: estimateTokens(onDemandChars)
+  };
+}
+
+async function scanDir(dirPath, projectDir, results) {
+  let entries;
+  try {
+    entries = await fs.readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const filePath = path.join(dirPath, entry.name);
+    const rel = path.relative(projectDir, filePath).split(path.sep).join('/');
+    const result = await scanAgentFile(filePath, rel);
+    if (result) results.push(result);
+  }
+}
+
+// ─── Report writer ────────────────────────────────────────────────────────────
+
+function buildMarkdownReport(files, projectDir) {
+  const overHard = files.filter((f) => f.status === 'over_hard');
+  const overTarget = files.filter((f) => f.status === 'over_target');
+  const totalTokens = files.reduce((s, f) => s + f.tokens, 0);
+  const totalSavings = files.reduce((s, f) => s + f.savings_tokens, 0);
+
+  const lines = [
+    '# Agent Audit Report',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    '## Summary',
+    `Total agent files scanned : ${files.length}`,
+    `Total estimated tokens    : ~${totalTokens.toLocaleString()}`,
+    `Over hard limit           : ${overHard.length}`,
+    `Over target               : ${overTarget.length}`,
+    `Potential savings (on-demand split): ~${totalSavings.toLocaleString()} tokens/session`,
+    ''
+  ];
+
+  if (overHard.length > 0) {
+    lines.push('## Over hard limit (split recommended)');
+    for (const f of overHard) {
+      lines.push(`- **${f.file}** — ${formatKb(f.chars)} (${formatTokens(f.chars)}) — type: ${f.agent_type}, hard: ${formatKb(f.hard_chars)}`);
+    }
+    lines.push('');
+  }
+
+  if (overTarget.length > 0) {
+    lines.push('## Over target (consider splitting)');
+    for (const f of overTarget) {
+      lines.push(`- ${f.file} — ${formatKb(f.chars)} (${formatTokens(f.chars)}) — target: ${formatKb(f.target_chars)}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## On-demand candidates (sections to move to .aioson/docs/)');
+  lines.push('These sections are loaded every session but are rarely needed at start.');
+  lines.push('Moving them to `.aioson/docs/` files saves tokens without losing capability.');
+  lines.push('');
+
+  for (const f of files) {
+    if (f.on_demand_candidates.length === 0) continue;
+    lines.push(`### ${f.file}`);
+    lines.push(`Current size: ${formatKb(f.chars)} — savings if moved: ~${f.savings_tokens.toLocaleString()} tokens`);
+    for (const s of f.on_demand_candidates) {
+      lines.push(`- \`## ${s.title}\` (${formatKb(s.chars)})`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## All files');
+  lines.push('| File | Type | Size | Tokens | Target | Status |');
+  lines.push('|------|------|------|--------|--------|--------|');
+  for (const f of [...files].sort((a, b) => b.chars - a.chars)) {
+    const statusLabel = { ok: '✓', over_target: '⚠', over_hard: '✗' }[f.status];
+    lines.push(`| ${f.file} | ${f.agent_type} | ${formatKb(f.chars)} | ${formatTokens(f.chars)} | ${formatKb(f.target_chars)} | ${statusLabel} |`);
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Main command ─────────────────────────────────────────────────────────────
+
+async function runAgentAudit({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const verbose = Boolean(options.verbose || options.v);
+  const includeLocales = Boolean(options.locales);
+  const writeFix = Boolean(options.fix);
+
+  const agentsDir = path.join(targetDir, 'template', '.aioson', 'agents');
+  const rootAgentsDir = path.join(targetDir, '.aioson', 'agents');
+
+  const files = [];
+
+  // Scan template agents (this project)
+  if (await dirExists(agentsDir)) {
+    await scanDir(agentsDir, targetDir, files);
+  }
+  // Scan project agents (when used inside a project)
+  if (await dirExists(rootAgentsDir)) {
+    await scanDir(rootAgentsDir, targetDir, files);
+  }
+  // Scan auto-loaded files
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    for (const base of [path.join(targetDir, 'template'), targetDir]) {
+      const fp = path.join(base, name);
+      const rel = path.relative(targetDir, fp).split(path.sep).join('/');
+      const r = await scanAgentFile(fp, rel);
+      if (r) files.push(r);
+    }
+  }
+
+  // Optionally include locales
+  if (includeLocales) {
+    const localesBase = path.join(targetDir, 'template', '.aioson', 'locales');
+    try {
+      const langs = await fs.readdir(localesBase, { withFileTypes: true });
+      for (const lang of langs) {
+        if (!lang.isDirectory()) continue;
+        await scanDir(
+          path.join(localesBase, lang.name, 'agents'),
+          targetDir,
+          files
+        );
+      }
+    } catch { /* locales dir optional */ }
+  }
+
+  if (files.length === 0) {
+    if (!options.json) logger.log('No agent files found. Run from the aioson project root or a project with .aioson/agents/.');
+    return { ok: false, reason: 'no_files' };
+  }
+
+  // Sort by size descending
+  files.sort((a, b) => b.chars - a.chars);
+
+  if (options.json) return { ok: true, files };
+
+  // ── Console report ─────────────────────────────────────────────────────────
+  const overHard = files.filter((f) => f.status === 'over_hard');
+  const overTarget = files.filter((f) => f.status === 'over_target');
+  const totalTokens = files.reduce((s, f) => s + f.tokens, 0);
+  const totalSavings = files.reduce((s, f) => s + f.savings_tokens, 0);
+
+  logger.log('Agent Audit');
+  logger.log('─'.repeat(70));
+  logger.log(`Files scanned  : ${files.length}`);
+  logger.log(`Total tokens   : ~${totalTokens.toLocaleString()} per session`);
+  logger.log(`Over hard limit: ${overHard.length}   Over target: ${overTarget.length}`);
+  logger.log(`Potential save : ~${totalSavings.toLocaleString()} tokens/session (on-demand split)`);
+  logger.log('');
+
+  // File table
+  const COL = { file: 45, type: 14, size: 9, tokens: 12, status: 8 };
+  logger.log(
+    'File'.padEnd(COL.file) +
+    'Type'.padEnd(COL.type) +
+    'Size'.padEnd(COL.size) +
+    'Tokens'.padEnd(COL.tokens) +
+    'Status'
+  );
+  logger.log('─'.repeat(70));
+
+  for (const f of files) {
+    const statusLabel = { ok: '✓ ok', over_target: '⚠ target', over_hard: '✗ hard' }[f.status];
+    logger.log(
+      f.file.slice(0, COL.file - 1).padEnd(COL.file) +
+      f.agent_type.padEnd(COL.type) +
+      formatKb(f.chars).padEnd(COL.size) +
+      formatTokens(f.chars).padEnd(COL.tokens) +
+      statusLabel
+    );
+
+    if (verbose && f.sections.length > 0) {
+      const topSections = [...f.sections].sort((a, b) => b.chars - a.chars).slice(0, 5);
+      for (const s of topSections) {
+        const flag = s.onDemandCandidate ? ' [on-demand candidate]' : '';
+        logger.log(`  ${'§ ' + s.title.slice(0, 40)}  ${formatKb(s.chars)}${flag}`);
+      }
+    }
+  }
+
+  logger.log('');
+
+  // On-demand candidates summary
+  const withCandidates = files.filter((f) => f.on_demand_candidates.length > 0);
+  if (withCandidates.length > 0) {
+    logger.log('On-demand candidates (move to .aioson/docs/ to save tokens):');
+    for (const f of withCandidates) {
+      logger.log(`  ${f.file.slice(0, 42)}  save ~${f.savings_tokens.toLocaleString()} tok  (${f.on_demand_candidates.length} section${f.on_demand_candidates.length > 1 ? 's' : ''})`);
+      if (verbose) {
+        for (const s of f.on_demand_candidates) {
+          logger.log(`    § ${s.title.slice(0, 50)}  ${formatKb(s.chars)}`);
+        }
+      }
+    }
+    logger.log('');
+  }
+
+  if (overHard.length > 0) {
+    logger.log('✗ Files over hard limit (will be truncated in auto-loaded contexts):');
+    for (const f of overHard) {
+      logger.log(`  ${f.file} — ${formatKb(f.chars)} (target: ${formatKb(f.target_chars)}, hard: ${formatKb(f.hard_chars)})`);
+    }
+    logger.log('');
+  }
+
+  // Write fix report
+  if (writeFix) {
+    const reportPath = path.join(targetDir, '.aioson', 'docs', 'agent-audit.md');
+    const reportDir = path.dirname(reportPath);
+    await fs.mkdir(reportDir, { recursive: true });
+    await fs.writeFile(reportPath, buildMarkdownReport(files, targetDir), 'utf8');
+    logger.log(`✓ Full report saved: .aioson/docs/agent-audit.md`);
+    logger.log('  Review the "On-demand candidates" section to decide which sections to move.');
+  } else {
+    logger.log('Tip: Run with --fix to save a full markdown report with split recommendations.');
+    logger.log('     Run with --verbose to see per-section breakdown.');
+  }
+
+  return {
+    ok: true,
+    files: files.length,
+    over_hard: overHard.length,
+    over_target: overTarget.length,
+    total_tokens: totalTokens,
+    potential_savings_tokens: totalSavings
+  };
+}
+
+async function dirExists(dirPath) {
+  try {
+    const s = await fs.stat(dirPath);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { runAgentAudit };

package/src/commands/agent-export-skill.js

@@ -0,0 +1,229 @@
+'use strict';
+
+/**
+ * aioson agent:export-skill — Export AIOSON agent as portable Agent Skills Standard
+ *
+ * Converts an AIOSON agent (.aioson/agents/<name>.md) into the Agent Skills Standard
+ * format (SKILL.md + resources), making it usable in Cursor, Copilot, Gemini CLI,
+ * Codex, JetBrains, and 32+ other tools.
+ *
+ * Usage:
+ *   aioson agent:export-skill . --agent=dev
+ *   aioson agent:export-skill . --agent=dev --output=.claude/skills/aioson-dev/
+ *   aioson agent:export-skill . --agent=qa --json
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const AGENTS_DIR = path.join('.aioson', 'agents');
+
+// ─── Frontmatter extraction ─────────────────────────────────────────────────
+
+/**
+ * Extract YAML-like frontmatter from a markdown file.
+ */
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w[\w_-]*):\s*(.+)$/);
+    if (kv) meta[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+
+  return { meta, body: match[2] };
+}
+
+/**
+ * Extract template sections from agent body (```template blocks or ## Template sections).
+ */
+function extractTemplates(body) {
+  const templates = [];
+  const templatePattern = /```template(?:\s+(\S+))?\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = templatePattern.exec(body)) !== null) {
+    templates.push({
+      name: match[1] || `template-${templates.length + 1}`,
+      content: match[2].trim()
+    });
+  }
+
+  return templates;
+}
+
+/**
+ * Extract tool references from agent body.
+ */
+function extractTools(body) {
+  const tools = new Set();
+  const toolPattern = /\b(Read|Write|Edit|Bash|Glob|Grep|Agent|WebFetch|WebSearch|NotebookEdit)\b/g;
+  let match;
+
+  while ((match = toolPattern.exec(body)) !== null) {
+    tools.add(match[1]);
+  }
+
+  return [...tools];
+}
+
+/**
+ * Infer activation patterns from agent content.
+ */
+function inferActivation(agentName, body) {
+  const activation = [];
+
+  // Always activate for .aioson files
+  activation.push({ path: '.aioson/**' });
+
+  // Keyword-based activation from agent name/role
+  const keywords = {
+    dev: ['implement', 'code', 'build', 'feature'],
+    qa: ['test', 'quality', 'verify', 'bug'],
+    architect: ['architecture', 'structure', 'design'],
+    analyst: ['analyze', 'discover', 'map'],
+    'ux-ui': ['design', 'interface', 'component'],
+    product: ['product', 'prd', 'requirement'],
+    pm: ['sprint', 'backlog', 'story']
+  };
+
+  const agentKeywords = keywords[agentName] || [agentName];
+  for (const kw of agentKeywords) {
+    activation.push({ keyword: kw });
+  }
+
+  return activation;
+}
+
+// ─── SKILL.md generator ──────────────────────────────────────────────────────
+
+/**
+ * Generate Agent Skills Standard SKILL.md from AIOSON agent.
+ */
+function generateSkillMd(agentName, agentContent, options = {}) {
+  const { meta, body } = extractFrontmatter(agentContent);
+  const tools = extractTools(body);
+  const activation = inferActivation(agentName, body);
+
+  // Build skills-standard frontmatter
+  const frontmatter = {
+    name: meta.name || `AIOSON ${capitalize(agentName)} Agent`,
+    description: meta.description || `${capitalize(agentName)} agent from AIOSON framework`,
+    version: options.version || '1.0.0',
+    tools: tools.length > 0 ? tools : ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
+    context: 'fork',
+    activation
+  };
+
+  const fmLines = [
+    '---',
+    `name: ${frontmatter.name}`,
+    `description: ${frontmatter.description}`,
+    `version: ${frontmatter.version}`,
+    `tools: [${frontmatter.tools.join(', ')}]`,
+    `context: ${frontmatter.context}`,
+    'activation:',
+    ...frontmatter.activation.map((a) => {
+      if (a.path) return `  - path: "${a.path}"`;
+      if (a.keyword) return `  - keyword: "${a.keyword}"`;
+      return '';
+    }).filter(Boolean),
+    '---',
+    ''
+  ];
+
+  // Clean body: remove AIOSON-specific sections that don't apply portably
+  let cleanBody = body;
+  // Remove runtime boundary sections
+  cleanBody = cleanBody.replace(/## AIOSON Runtime boundary[\s\S]*?(?=\n## |$)/g, '');
+  // Remove observability sections
+  cleanBody = cleanBody.replace(/## Observability[\s\S]*?(?=\n## |$)/g, '');
+
+  return fmLines.join('\n') + cleanBody.trim() + '\n';
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Export an AIOSON agent as an Agent Skills Standard skill.
+ *
+ * @param {object} params  — { args, options, logger }
+ */
+async function runAgentExportSkill({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agentName = String(options.agent || options.a || '').trim();
+  const outputDir = options.output
+    ? path.resolve(targetDir, options.output)
+    : path.join(targetDir, '.claude', 'skills', `aioson-${agentName}`);
+
+  if (!agentName) {
+    logger.error('Error: --agent is required');
+    return { ok: false, error: 'missing_agent' };
+  }
+
+  // Read agent file
+  const agentPath = path.join(targetDir, AGENTS_DIR, `${agentName}.md`);
+  let agentContent;
+  try {
+    agentContent = await fs.readFile(agentPath, 'utf8');
+  } catch {
+    logger.error(`Agent not found: ${agentPath}`);
+    return { ok: false, error: 'agent_not_found' };
+  }
+
+  // Generate SKILL.md
+  const skillContent = generateSkillMd(agentName, agentContent, {
+    version: options.version || '1.0.0'
+  });
+
+  // Extract templates
+  const templates = extractTemplates(agentContent);
+
+  // Write output
+  await fs.mkdir(outputDir, { recursive: true });
+  await fs.writeFile(path.join(outputDir, 'SKILL.md'), skillContent, 'utf8');
+
+  const written = ['SKILL.md'];
+
+  // Write templates
+  if (templates.length > 0) {
+    const templatesDir = path.join(outputDir, 'templates');
+    await fs.mkdir(templatesDir, { recursive: true });
+    for (const t of templates) {
+      const ext = t.content.includes('{') ? '.json' : '.md';
+      await fs.writeFile(path.join(templatesDir, `${t.name}${ext}`), t.content, 'utf8');
+      written.push(`templates/${t.name}${ext}`);
+    }
+  }
+
+  // Write scripts directory (empty, for custom scripts)
+  const scriptsDir = path.join(outputDir, 'scripts');
+  await fs.mkdir(scriptsDir, { recursive: true });
+
+  if (options.json) {
+    return {
+      ok: true,
+      agent: agentName,
+      outputDir: path.relative(targetDir, outputDir),
+      files: written
+    };
+  }
+
+  logger.log(`Exported @${agentName} as Agent Skills Standard:`);
+  logger.log(`  Output: ${path.relative(targetDir, outputDir)}/`);
+  for (const f of written) {
+    logger.log(`  ✓ ${f}`);
+  }
+  logger.log('');
+  logger.log('This skill is now portable to Cursor, Copilot, Gemini CLI, and 32+ tools.');
+
+  return { ok: true, agent: agentName, outputDir: path.relative(targetDir, outputDir), files: written };
+}
+
+module.exports = { runAgentExportSkill, generateSkillMd };