@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/agent-loader.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const path = require('node:path');
+const { AgentLoader } = require('../agent-loader');
+
+async function runAgentLoad({ args, options, logger }) {
+  const agentId = args[0] || options.agent || '';
+  const goal = options.goal || '';
+  const cwd = path.resolve(process.cwd(), options.cwd || '.');
+  const agentsDir = path.join(cwd, options['agents-dir'] || '.aioson/agents');
+  const maxShards = Number(options['max-shards']) || 3;
+  const maxTokens = Number(options['max-tokens']) || 2000;
+
+  if (!agentId) {
+    logger.error('Usage: aioson agent:load <agent-id> --goal="..." [--cwd=.]');
+    return { ok: false, error: 'missing_agent' };
+  }
+
+  const loader = new AgentLoader();
+  await loader.open();
+
+  try {
+    // Index agents dir if needed
+    await loader.indexAgentsDir(agentsDir, { force: Boolean(options.force) });
+
+    // Load relevant shards
+    const result = await loader.loadRelevantShards(agentId, goal, { maxShards, maxTokens });
+
+    if (result.shards.length === 0) {
+      logger.log(`No shards found for agent: ${agentId}`);
+      logger.log(`Make sure the agents directory exists: ${agentsDir}`);
+      return { ok: true, agentId, shards: [], tokens: 0 };
+    }
+
+    if (options.json) {
+      return { ok: true, ...result };
+    }
+
+    logger.log(`\n  Agent: ${agentId}  (${result.shards.length}/${result.totalShards} shards, ${result.tokens} tokens)\n`);
+    for (const shard of result.shards) {
+      logger.log(`  ## ${shard.heading}  (${shard.tokens} tokens)`);
+    }
+    logger.log('');
+
+    if (options.print) {
+      logger.log('\n---\n');
+      logger.log(AgentLoader.buildContext(result.shards));
+    }
+
+    return { ok: true, ...result };
+  } finally {
+    loader.close();
+  }
+}
+
+async function runAgentShardIndex({ args, options, logger }) {
+  const cwd = path.resolve(process.cwd(), args[0] || '.');
+  const agentsDir = path.join(cwd, options['agents-dir'] || '.aioson/agents');
+  const force = Boolean(options.force);
+
+  logger.log(`Indexing agent shards from: ${agentsDir}`);
+
+  const loader = new AgentLoader();
+  await loader.open();
+
+  try {
+    const result = await loader.indexAgentsDir(agentsDir, { force });
+    const stats = loader.stats();
+
+    if (options.json) {
+      return { ok: true, ...result, stats };
+    }
+
+    logger.log(`  Agents indexed: ${result.agents}`);
+    logger.log(`  Total shards: ${result.totalShards}`);
+    logger.log(`  Index total docs: ${stats.totalDocs}`);
+    logger.log('');
+
+    return { ok: true, ...result, stats };
+  } finally {
+    loader.close();
+  }
+}
+
+module.exports = { runAgentLoad, runAgentShardIndex };

package/src/commands/artifact-validate.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * aioson artifact:validate — validate the complete artifact chain for a feature.
+ *
+ * Checks all expected artifacts (prd → sheldon → requirements → spec →
+ * architecture → implementation-plan → conformance) and reports chain integrity.
+ *
+ * Usage:
+ *   aioson artifact:validate . --feature=checkout
+ *   aioson artifact:validate . --feature=checkout --json
+ */
+
+const path = require('node:path');
+const {
+  scanArtifacts,
+  detectClassification,
+  parseGatesFromSpec,
+  parseFrontmatter,
+  contextDir
+} = require('../preflight-engine');
+
+const BAR = '━'.repeat(45);
+
+function gateDisplay(gates) {
+  const letters = { requirements: 'A', design: 'B', plan: 'C', execution: 'D' };
+  return Object.entries(letters).map(([name, letter]) => {
+    const status = gates[name];
+    return status === 'approved' ? `${letter}✓` : `${letter}○`;
+  }).join(' ');
+}
+
+async function runArtifactValidate({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+
+  if (!slug) {
+    if (options.json) return { ok: false, reason: 'missing_feature' };
+    logger.log('--feature=<slug> is required.');
+    return { ok: false };
+  }
+
+  const artifacts = await scanArtifacts(targetDir, slug);
+  const classification = await detectClassification(targetDir, slug);
+
+  // Gates from spec
+  const specGates = artifacts.spec.exists ? parseGatesFromSpec(artifacts.spec.content) : {};
+
+  // Spec details
+  const specFm = artifacts.spec.exists ? parseFrontmatter(artifacts.spec.content) : {};
+  const specVersion = specFm.version || null;
+  const specGateDisplay = artifacts.spec.exists ? gateDisplay(specGates) : null;
+
+  // Sheldon readiness
+  const sheldonReady = artifacts.sheldon_enrichment.exists
+    ? (artifacts.sheldon_enrichment.frontmatter.readiness === 'ready_for_downstream' ? 'ready_for_downstream' : 'present')
+    : null;
+
+  // Implementation plan status
+  const planStatus = artifacts.implementation_plan.exists
+    ? (artifacts.implementation_plan.frontmatter.status || 'present')
+    : null;
+
+  // Requirement count
+  let reqCount = null;
+  if (artifacts.requirements.exists && artifacts.requirements.content) {
+    const reqs = artifacts.requirements.content.match(/\bREQ[-\s]?\d+\b/g) || [];
+    const acs = artifacts.requirements.content.match(/\bAC[-\s]?\d+\b/g) || [];
+    reqCount = `${reqs.length} REQs, ${acs.length} ACs`;
+  }
+
+  // Conformance required?
+  const conformanceRequired = classification === 'MEDIUM';
+
+  // Build chain items
+  const chain = [
+    {
+      name: 'project.context.md',
+      exists: artifacts.project_context.exists,
+      detail: artifacts.project_context.exists ? `${artifacts.project_context.size}B` : null,
+      required: true,
+      indent: 0
+    },
+    {
+      name: `prd-${slug}.md`,
+      exists: artifacts.prd.exists,
+      detail: artifacts.prd.exists ? `${artifacts.prd.size}B` : null,
+      required: true,
+      indent: 0
+    },
+    {
+      name: `sheldon-enrichment-${slug}.md`,
+      exists: artifacts.sheldon_enrichment.exists,
+      detail: sheldonReady ? `readiness: ${sheldonReady}` : null,
+      required: false,
+      indent: 1
+    },
+    {
+      name: `requirements-${slug}.md`,
+      exists: artifacts.requirements.exists,
+      detail: reqCount,
+      required: true,
+      indent: 1
+    },
+    {
+      name: `spec-${slug}.md`,
+      exists: artifacts.spec.exists,
+      detail: artifacts.spec.exists ? `version: ${specVersion || '?'}, gates: ${specGateDisplay || '?'}` : null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: 'architecture.md',
+      exists: artifacts.architecture.exists,
+      detail: null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: `implementation-plan-${slug}.md`,
+      exists: artifacts.implementation_plan.exists,
+      detail: planStatus ? `status: ${planStatus}` : null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: `conformance-${slug}.yaml`,
+      exists: artifacts.conformance.exists,
+      detail: !conformanceRequired ? `required for MEDIUM — NOT required for ${classification || 'SMALL'}` : null,
+      required: conformanceRequired,
+      indent: 1
+    }
+  ];
+
+  // Validate chain integrity
+  const missing = chain.filter((c) => c.required && !c.exists);
+  const missingOptional = chain.filter((c) => !c.required && !c.exists);
+
+  const valid = missing.length === 0;
+
+  const result = {
+    ok: valid,
+    feature: slug,
+    classification: classification || 'unknown',
+    chain: chain.map((c) => ({
+      name: c.name,
+      exists: c.exists,
+      required: c.required,
+      detail: c.detail
+    })),
+    missing_required: missing.map((c) => c.name),
+    missing_optional: missingOptional.map((c) => c.name),
+    integrity: valid ? 'VALID' : 'INVALID'
+  };
+
+  if (options.json) return result;
+
+  logger.log('');
+  logger.log(`Artifact Chain — ${slug}`);
+  logger.log(BAR);
+
+  for (const item of chain) {
+    const icon = item.exists ? '✓' : '✗';
+    const indent = '  '.repeat(item.indent) + (item.indent > 0 ? '→ ' : '');
+    const detail = item.detail ? ` (${item.detail})` : '';
+    logger.log(`${indent}${icon} ${item.name}${detail}`);
+  }
+
+  logger.log('');
+  logger.log(`Chain integrity: ${valid ? 'VALID' : 'INVALID'}`);
+
+  if (missing.length > 0) {
+    logger.log(`Missing required: ${missing.map((c) => c.name).join(', ')}`);
+  }
+
+  if (missingOptional.length > 0 && !valid) {
+    logger.log(`Missing optional: ${missingOptional.map((c) => c.name).join(', ')}`);
+  }
+
+  if (valid && missingOptional.length > 0) {
+    logger.log(`Missing optional: ${missingOptional.map((c) => c.name).join(', ')} (${classification || 'SMALL'} — acceptable)`);
+  }
+
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runArtifactValidate };

package/src/commands/brief-gen.js

@@ -0,0 +1,405 @@
+'use strict';
+
+/**
+ * aioson brief:gen — Generate a 100% self-contained worker brief
+ *
+ * Reads the current implementation plan phase (or a named phase), combines
+ * it with the project architecture, spec, and any existing context files,
+ * and writes a fully self-contained brief that a worker can execute with
+ * zero additional lookups.
+ *
+ * Brief completeness checklist (from orchestrator.md):
+ *   ✓ Phase name and goal
+ *   ✓ Files to read before starting
+ *   ✓ Files to create or modify
+ *   ✓ Hard constraints (must not touch)
+ *   ✓ Out-of-scope (what NOT to do)
+ *   ✓ Done criteria (verifiable)
+ *   ✓ Relevant excerpts from architecture / spec
+ *
+ * Usage:
+ *   aioson brief:gen .
+ *   aioson brief:gen . --phase=2               Target a specific plan phase
+ *   aioson brief:gen . --plan=my-plan.md       Use a specific plan file
+ *   aioson brief:gen . --out=briefs/phase-2.md Override output path
+ *   aioson brief:gen . --squad=content-team    Target squad directory instead of .aioson/context
+ *   aioson brief:gen . --executor=writer       Target executor inside squad
+ *   aioson brief:gen . --json                  JSON output
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+// ─── File discovery helpers ───────────────────────────────────────────────────
+
+async function tryRead(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function findFile(candidates) {
+  for (const p of candidates) {
+    const content = await tryRead(p);
+    if (content !== null) return { path: p, content };
+  }
+  return null;
+}
+
+// ─── Plan parser ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse phases from an implementation plan markdown.
+ * Phases are identified by ## or ### headings containing "Phase" or "Sprint" or
+ * "Step" followed by a number.
+ */
+function parsePlanPhases(content) {
+  const lines = content.split(/\r?\n/);
+  const phases = [];
+  const phaseHeadingRe = /^#{1,4}\s+(?:Phase|Sprint|Step|Fase|Etapa)\s*(\d+)\b(.*)$/i;
+
+  let current = null;
+  let currentLines = [];
+
+  function flush() {
+    if (current !== null) {
+      phases.push({
+        number: current.number,
+        title: current.title,
+        content: currentLines.join('\n').trim()
+      });
+    }
+  }
+
+  for (const line of lines) {
+    const match = line.match(phaseHeadingRe);
+    if (match) {
+      flush();
+      current = {
+        number: parseInt(match[1], 10),
+        title: line.trim()
+      };
+      currentLines = [line];
+    } else if (current !== null) {
+      currentLines.push(line);
+    }
+  }
+  flush();
+
+  return phases;
+}
+
+/**
+ * Extract a named section (## heading) from markdown content.
+ * Returns the section body (without the heading line).
+ */
+function extractSection(content, sectionPattern) {
+  const lines = content.split(/\r?\n/);
+  const re = new RegExp(`^#{1,4}\\s+.*${sectionPattern}.*$`, 'i');
+  let inSection = false;
+  let sectionLevel = 0;
+  const result = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,4})\s+/);
+
+    if (!inSection) {
+      if (re.test(line)) {
+        inSection = true;
+        sectionLevel = headingMatch ? headingMatch[1].length : 2;
+      }
+      continue;
+    }
+
+    // Stop if we hit a heading of equal or higher level
+    if (headingMatch && headingMatch[1].length <= sectionLevel) {
+      break;
+    }
+    result.push(line);
+  }
+
+  return result.join('\n').trim();
+}
+
+// ─── Architecture excerpt extractor ──────────────────────────────────────────
+
+const ARCH_SECTIONS = [
+  'tech stack', 'stack', 'architecture', 'folder structure', 'directory',
+  'conventions', 'database', 'api', 'services', 'modules', 'layers'
+];
+
+function extractArchitectureExcerpts(archContent, maxChars = 3000) {
+  if (!archContent) return null;
+
+  // Try to pull relevant sections
+  const excerpts = [];
+  for (const keyword of ARCH_SECTIONS) {
+    const section = extractSection(archContent, keyword);
+    if (section.length > 50) {
+      excerpts.push(section);
+    }
+    if (excerpts.reduce((s, e) => s + e.length, 0) >= maxChars) break;
+  }
+
+  if (excerpts.length === 0) {
+    // Fall back to the first maxChars characters
+    return archContent.slice(0, maxChars) + (archContent.length > maxChars ? '\n\n[...truncated — read full file for details]' : '');
+  }
+
+  return excerpts.join('\n\n---\n\n');
+}
+
+// ─── Brief builder ────────────────────────────────────────────────────────────
+
+function buildBrief({
+  phase,
+  planPath,
+  architectureExcerpt,
+  specExcerpt,
+  contextNote,
+  squadSlug,
+  executorSlug,
+  projectDir
+}) {
+  const now = new Date().toISOString();
+  const relPlan = path.relative(projectDir, planPath);
+  const squadLine = squadSlug ? `Squad        : ${squadSlug}` : null;
+  const executorLine = executorSlug ? `Executor     : ${executorSlug}` : null;
+
+  const lines = [
+    '---',
+    `generated_at : ${now}`,
+    `plan_file    : ${relPlan}`,
+    `phase        : ${phase.number}`,
+    ...(squadLine ? [squadLine] : []),
+    ...(executorLine ? [executorLine] : []),
+    '---',
+    '',
+    `# Worker Brief — ${phase.title}`,
+    '',
+    '> This brief is 100% self-contained. Do not look up additional context.',
+    '> Read only the files listed in "Files to read". Write only the files listed in "Files to write".',
+    ''
+  ];
+
+  // Phase task block
+  lines.push('## Phase goal and tasks');
+  lines.push('');
+  lines.push(phase.content);
+  lines.push('');
+
+  // Architecture
+  if (architectureExcerpt) {
+    lines.push('## Architecture reference (excerpts)');
+    lines.push('');
+    lines.push(architectureExcerpt);
+    lines.push('');
+  }
+
+  // Spec
+  if (specExcerpt) {
+    lines.push('## Spec reference (excerpts)');
+    lines.push('');
+    lines.push(specExcerpt);
+    lines.push('');
+  }
+
+  // Context note
+  if (contextNote) {
+    lines.push('## Project context');
+    lines.push('');
+    lines.push(contextNote);
+    lines.push('');
+  }
+
+  // Done criteria placeholder (agent should fill in based on phase content)
+  lines.push('## Done criteria');
+  lines.push('');
+  lines.push('> Fill in the specific, verifiable done criteria for this phase before handing off.');
+  lines.push('> Example format:');
+  lines.push('> - [ ] `path/to/file.ts` exists and exports `FunctionName`');
+  lines.push('> - [ ] All existing tests pass (`npm test`)');
+  lines.push('> - [ ] No TypeScript errors (`tsc --noEmit`)');
+  lines.push('');
+
+  // Hard constraints placeholder
+  lines.push('## Hard constraints');
+  lines.push('');
+  lines.push('> Fill in what the worker MUST NOT touch or change.');
+  lines.push('> Example:');
+  lines.push('> - Do NOT modify `src/db/schema.ts` (owned by another phase)');
+  lines.push('> - Do NOT add new npm dependencies without coordinator approval');
+  lines.push('');
+
+  // Out of scope
+  lines.push('## Out of scope');
+  lines.push('');
+  lines.push('> Fill in what explicitly falls outside this phase.');
+  lines.push('> Example:');
+  lines.push('> - UI styling (handled in Phase 3)');
+  lines.push('> - Authentication (handled in Phase 4)');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Main command ─────────────────────────────────────────────────────────────
+
+async function runBriefGen({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const phaseNumber = options.phase != null ? Number(options.phase) : null;
+  const squadSlug = String(options.squad || '').trim() || null;
+  const executorSlug = String(options.executor || '').trim() || null;
+
+  const contextDir = squadSlug
+    ? path.join(targetDir, '.aioson', 'squads', squadSlug)
+    : path.join(targetDir, '.aioson', 'context');
+
+  // ── Locate plan file ─────────────────────────────────────────────────────
+  let planFile;
+  if (options.plan) {
+    const explicit = path.resolve(targetDir, options.plan);
+    const content = await tryRead(explicit);
+    if (!content) {
+      logger.error(`Plan file not found: ${options.plan}`);
+      return { ok: false, error: 'plan_not_found' };
+    }
+    planFile = { path: explicit, content };
+  } else {
+    planFile = await findFile([
+      path.join(contextDir, 'implementation-plan.md'),
+      path.join(targetDir, '.aioson', 'context', 'implementation-plan.md'),
+      path.join(targetDir, 'plans', 'implementation-plan.md'),
+      path.join(targetDir, 'implementation-plan.md')
+    ]);
+  }
+
+  if (!planFile) {
+    logger.error('No implementation plan found. Run `aioson plan:show` or provide --plan=<path>.');
+    return { ok: false, error: 'no_plan' };
+  }
+
+  // ── Parse phases ─────────────────────────────────────────────────────────
+  const phases = parsePlanPhases(planFile.content);
+
+  if (phases.length === 0) {
+    logger.error(`No phases found in plan: ${path.relative(targetDir, planFile.path)}`);
+    logger.error('Phases must use headings like "## Phase 1 — description" or "## Sprint 2".');
+    return { ok: false, error: 'no_phases' };
+  }
+
+  // Pick target phase
+  let phase;
+  if (phaseNumber != null) {
+    phase = phases.find((p) => p.number === phaseNumber);
+    if (!phase) {
+      logger.error(`Phase ${phaseNumber} not found. Available: ${phases.map((p) => p.number).join(', ')}`);
+      return { ok: false, error: 'phase_not_found' };
+    }
+  } else {
+    // Default: first incomplete phase (or first phase)
+    phase = phases[0];
+  }
+
+  // ── Locate supporting files ───────────────────────────────────────────────
+  const [archFile, specFile, ctxFile] = await Promise.all([
+    findFile([
+      path.join(contextDir, 'architecture.md'),
+      path.join(targetDir, '.aioson', 'context', 'architecture.md'),
+      path.join(targetDir, 'docs', 'architecture.md'),
+      path.join(targetDir, 'ARCHITECTURE.md')
+    ]),
+    findFile([
+      path.join(contextDir, 'spec.md'),
+      path.join(targetDir, '.aioson', 'context', 'spec.md'),
+      path.join(targetDir, 'docs', 'spec.md'),
+      path.join(targetDir, 'SPEC.md')
+    ]),
+    findFile([
+      path.join(contextDir, 'project.context.md'),
+      path.join(targetDir, '.aioson', 'context', 'project.context.md')
+    ])
+  ]);
+
+  const architectureExcerpt = archFile
+    ? extractArchitectureExcerpts(archFile.content)
+    : null;
+
+  const specExcerpt = specFile
+    ? (specFile.content.length > 4000
+        ? specFile.content.slice(0, 4000) + '\n\n[...truncated — read full file for details]'
+        : specFile.content)
+    : null;
+
+  // Context: pull a short summary from project.context.md
+  const contextNote = ctxFile
+    ? extractSection(ctxFile.content, 'summary|overview|objetivo|goal') ||
+      ctxFile.content.slice(0, 800)
+    : null;
+
+  // ── Build brief ───────────────────────────────────────────────────────────
+  const briefContent = buildBrief({
+    phase,
+    planPath: planFile.path,
+    architectureExcerpt,
+    specExcerpt,
+    contextNote,
+    squadSlug,
+    executorSlug,
+    projectDir: targetDir
+  });
+
+  // ── Determine output path ─────────────────────────────────────────────────
+  let outPath;
+  if (options.out) {
+    outPath = path.resolve(targetDir, options.out);
+  } else {
+    const outDir = squadSlug
+      ? path.join(targetDir, '.aioson', 'squads', squadSlug, 'briefs')
+      : path.join(targetDir, '.aioson', 'context', 'briefs');
+    const executorSuffix = executorSlug ? `-${executorSlug}` : '';
+    outPath = path.join(outDir, `phase-${phase.number}${executorSuffix}.md`);
+  }
+
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  await fs.writeFile(outPath, briefContent, 'utf8');
+
+  const relOut = path.relative(targetDir, outPath);
+
+  if (options.json) {
+    return {
+      ok: true,
+      brief_path: relOut,
+      phase: phase.number,
+      phase_title: phase.title,
+      plan_file: path.relative(targetDir, planFile.path),
+      has_architecture: Boolean(architectureExcerpt),
+      has_spec: Boolean(specExcerpt),
+      has_context: Boolean(contextNote),
+      chars: briefContent.length,
+      tokens: Math.ceil(briefContent.length / 4)
+    };
+  }
+
+  logger.log('Brief generated');
+  logger.log('─'.repeat(60));
+  logger.log(`Phase        : ${phase.number} — ${phase.title}`);
+  logger.log(`Plan         : ${path.relative(targetDir, planFile.path)}`);
+  logger.log(`Architecture : ${archFile ? path.relative(targetDir, archFile.path) : '(not found)'}`);
+  logger.log(`Spec         : ${specFile ? path.relative(targetDir, specFile.path) : '(not found)'}`);
+  logger.log(`Output       : ${relOut}`);
+  logger.log(`Size         : ${briefContent.length} chars (~${Math.ceil(briefContent.length / 4)} tokens)`);
+  logger.log('');
+  logger.log('Review the "Done criteria", "Hard constraints", and "Out of scope" sections');
+  logger.log('before handing the brief to a worker. These are left as placeholders intentionally.');
+
+  return {
+    ok: true,
+    brief_path: relOut,
+    phase: phase.number
+  };
+}
+
+module.exports = { runBriefGen };