@eddacraft/anvil-adapters 0.1.0

package/src/bmad/parser.ts

@@ -0,0 +1,224 @@
+/**
+ * BMAD Parser
+ *
+ * Parses BMAD format documents (PRD, Architecture, Epics, Stories) into APS plans.
+ */
+
+import { type APSPlan, type Change, validateRelativePath } from '@eddacraft/anvil-core';
+import type { ParseContext, AdapterError, AdapterWarning } from '../base/types.js';
+import { BMADDocument, BMADRequirement, BMADUserStory, RequirementType } from './types.js';
+import {
+  extractFrontMatter,
+  extractRequirements,
+  extractUserStories,
+  extractChangeLog,
+  identifyDocumentType,
+  extractTitle,
+  extractIntent,
+} from './utils.js';
+import { createError, createWarning, generateDeterministicPlanId } from '../base/utils.js';
+
+/**
+ * Parse BMAD document into internal structure
+ *
+ * @param content - BMAD markdown content
+ * @returns Parsed document
+ */
+/**
+ * Validate and sanitize a file path to prevent path traversal attacks.
+ * Falls back to stripping special characters if validation fails.
+ */
+function safePath(raw: string): string {
+  try {
+    return validateRelativePath(raw);
+  } catch {
+    return raw.replace(/[^a-z0-9/._-]/gi, '').replace(/\.{2,}/g, '');
+  }
+}
+
+/** Maximum input size for BMAD parsing (2MB) */
+const MAX_INPUT_SIZE = 2 * 1024 * 1024;
+
+export function parseBMADDocument(content: string): BMADDocument {
+  if (content.length > MAX_INPUT_SIZE) {
+    throw new Error(`Input exceeds maximum size of ${MAX_INPUT_SIZE} bytes`);
+  }
+  const frontMatter = extractFrontMatter(content);
+  const docType = identifyDocumentType(content, frontMatter);
+  const requirements = extractRequirements(content);
+  const userStories = extractUserStories(content);
+  const changeLog = extractChangeLog(content);
+  const title = extractTitle(content);
+  const intent = extractIntent(content, docType);
+
+  return {
+    type: docType,
+    frontMatter: frontMatter || undefined,
+    title: title || undefined,
+    intent,
+    requirements,
+    userStories,
+    changeLog,
+    sections: new Map(),
+    raw: content,
+  };
+}
+
+/**
+ * Convert BMAD requirement to APS change
+ *
+ * @param requirement - BMAD requirement
+ * @returns APS change
+ */
+function requirementToChange(requirement: BMADRequirement): Change {
+  // Map requirement type to change type
+  switch (requirement.type) {
+    case RequirementType.FUNCTIONAL:
+      // FR typically means creating or updating files
+      return {
+        type: 'file_create',
+        path: safePath(`features/${requirement.id.toLowerCase()}.ts`),
+        description: `${requirement.id}: ${requirement.description}`,
+      };
+
+    case RequirementType.NON_FUNCTIONAL:
+      // NFR typically means configuration or validation
+      return {
+        type: 'config_update',
+        path: 'config/requirements.json',
+        description: `${requirement.id}: ${requirement.description}`,
+      };
+
+    case RequirementType.USER_STORY:
+      // US typically means creating feature files
+      return {
+        type: 'file_create',
+        path: safePath(`features/stories/${requirement.id.toLowerCase()}.ts`),
+        description: `${requirement.id}: ${requirement.description}`,
+      };
+
+    default:
+      return {
+        type: 'file_create',
+        path: safePath(`requirements/${requirement.id.toLowerCase()}.md`),
+        description: requirement.description,
+      };
+  }
+}
+
+/**
+ * Convert BMAD user story to APS change
+ *
+ * @param story - BMAD user story
+ * @returns APS change
+ */
+function userStoryToChange(story: BMADUserStory): Change {
+  let description = `${story.id}: ${story.title}`;
+
+  if (story.userType && story.action && story.benefit) {
+    description += ` (As a ${story.userType}, I want ${story.action}, so that ${story.benefit})`;
+  }
+
+  if (story.acceptanceCriteria && story.acceptanceCriteria.length > 0) {
+    description += ` - Acceptance criteria: ${story.acceptanceCriteria.join('; ')}`;
+  }
+
+  return {
+    type: 'file_create',
+    path: safePath(`features/stories/${story.id.toLowerCase()}.ts`),
+    description,
+  };
+}
+
+export function bmadToAPS(
+  document: BMADDocument,
+  context?: ParseContext,
+  originalContent?: string
+): APSPlan {
+  const planId =
+    context?.planId ??
+    (originalContent
+      ? generateDeterministicPlanId(originalContent)
+      : `aps-${Date.now().toString(16).substring(0, 8)}`);
+
+  // Convert requirements and stories to changes
+  const changes: Change[] = [];
+  const errors: AdapterError[] = [];
+  const warnings: AdapterWarning[] = [];
+
+  // Add requirements as changes
+  for (const requirement of document.requirements) {
+    try {
+      const change = requirementToChange(requirement);
+      changes.push(change);
+    } catch (error) {
+      errors.push(
+        createError(
+          'REQUIREMENT_CONVERSION_ERROR',
+          `Failed to convert requirement ${requirement.id}`,
+          {
+            details: error,
+          }
+        )
+      );
+    }
+  }
+
+  // Add user stories as changes
+  for (const story of document.userStories) {
+    try {
+      const change = userStoryToChange(story);
+      changes.push(change);
+    } catch (error) {
+      errors.push(
+        createError('STORY_CONVERSION_ERROR', `Failed to convert story ${story.id}`, {
+          details: error,
+        })
+      );
+    }
+  }
+
+  // If no changes found, add warning
+  if (changes.length === 0) {
+    warnings.push(
+      createWarning('NO_CHANGES', 'No requirements or user stories found in document', {
+        details: { type: document.type },
+      })
+    );
+  }
+
+  // Extract provenance from front-matter or context
+  const timestamp = document.frontMatter?.date || context?.timestamp || new Date().toISOString();
+  const author = document.frontMatter?.author || context?.author || 'unknown';
+  const version = document.frontMatter?.version || '1.0.0';
+
+  // Build APS plan
+  const plan: APSPlan = {
+    id: planId,
+    schema_version: '0.1.0',
+    intent: document.intent || 'BMAD document conversion',
+    proposed_changes: changes,
+    provenance: {
+      timestamp,
+      author,
+      source: 'cli',
+      version,
+      repository: context?.repositoryPath,
+      branch: context?.branch,
+      commit: context?.commit,
+    },
+    validations: {
+      required_checks: ['lint', 'test', 'coverage'],
+      skip_checks: [],
+    },
+    // Note: hash will be generated by the adapter after plan creation
+    hash: '0000000000000000000000000000000000000000000000000000000000000000',
+  };
+
+  return plan;
+}
+
+export function parseBMAD(content: string, context?: ParseContext): APSPlan {
+  const document = parseBMADDocument(content);
+  return bmadToAPS(document, context, content);
+}

package/src/bmad/serializer.ts

@@ -0,0 +1,206 @@
+/**
+ * BMAD Serializer
+ *
+ * Serializes APS plans to BMAD format documents.
+ */
+
+import type { APSPlan, Change } from '@eddacraft/anvil-core';
+
+/**
+ * Serialize APS plan to BMAD format
+ *
+ * Generates a BMAD PRD document from an APS plan.
+ *
+ * @param plan - APS plan to serialize
+ * @returns BMAD markdown content
+ */
+export function serializeToBMAD(plan: APSPlan): string {
+  const lines: string[] = [];
+
+  // Generate YAML front-matter
+  lines.push('---');
+  lines.push('name: "Product Requirements Document"');
+  lines.push(`version: "${plan.provenance.version || '1.0.0'}"`);
+  lines.push(`date: "${plan.provenance.timestamp}"`);
+  lines.push(`author: "${plan.provenance.author || 'unknown'}"`);
+  lines.push('description: "Generated from Anvil Plan Specification"');
+  lines.push('---');
+  lines.push('');
+
+  // Generate document header
+  const projectName = plan.metadata?.['projectName'] || 'Project';
+  lines.push(`# ${projectName} - Product Requirements Document`);
+  lines.push('');
+  lines.push(`**Author:** ${plan.provenance.author || 'unknown'}`);
+  lines.push(`**Date:** ${plan.provenance.timestamp}`);
+  lines.push(`**Version:** ${plan.provenance.version || '1.0.0'}`);
+  lines.push('');
+
+  // Generate change log
+  lines.push('## Change Log');
+  lines.push('');
+  lines.push('| Date | Version | Description | Author |');
+  lines.push('| :--- | :------ | :---------- | :----- |');
+
+  const date = new Date(plan.provenance.timestamp).toISOString().split('T')[0];
+  const version = plan.provenance.version || '1.0.0';
+  const author = plan.provenance.author || 'unknown';
+
+  lines.push(`| ${date} | ${version} | Initial version | ${author} |`);
+  lines.push('');
+
+  // Generate overview/intent section
+  lines.push('## Overview');
+  lines.push('');
+  lines.push(plan.intent);
+  lines.push('');
+
+  // Categorize changes
+  const functionalRequirements: Change[] = [];
+  const nonFunctionalRequirements: Change[] = [];
+  const userStories: Change[] = [];
+
+  for (const change of plan.proposed_changes) {
+    // Categorize based on change type and path
+    if (change.path.includes('stories/') || change.description.match(/^US-\d{2}/)) {
+      userStories.push(change);
+    } else if (
+      change.type === 'config_update' ||
+      change.type === 'dependency_add' ||
+      change.type === 'dependency_update' ||
+      change.description.match(/^NFR-\d{2}/)
+    ) {
+      nonFunctionalRequirements.push(change);
+    } else {
+      functionalRequirements.push(change);
+    }
+  }
+
+  // Generate Functional Requirements section
+  if (functionalRequirements.length > 0) {
+    lines.push('## Functional Requirements');
+    lines.push('');
+
+    functionalRequirements.forEach((change, index) => {
+      const reqNum = String(index + 1).padStart(2, '0');
+      const reqId = `FR-${reqNum}`;
+
+      // Extract description (remove existing FR-XX if present)
+      let description = change.description.replace(/^FR-\d{2}:\s*/, '');
+
+      // Add path context if not already in description
+      if (!description.includes(change.path)) {
+        description += ` (${change.path})`;
+      }
+
+      lines.push(`${reqId}: ${description}`);
+    });
+
+    lines.push('');
+  }
+
+  // Generate Non-Functional Requirements section
+  if (nonFunctionalRequirements.length > 0) {
+    lines.push('## Non-Functional Requirements');
+    lines.push('');
+
+    nonFunctionalRequirements.forEach((change, index) => {
+      const reqNum = String(index + 1).padStart(2, '0');
+      const reqId = `NFR-${reqNum}`;
+
+      // Extract description
+      const description = change.description.replace(/^NFR-\d{2}:\s*/, '');
+
+      lines.push(`${reqId}: ${description}`);
+    });
+
+    lines.push('');
+  }
+
+  // Add validation requirements as NFRs
+  if (plan.validations.required_checks.length > 0) {
+    if (nonFunctionalRequirements.length === 0) {
+      lines.push('## Non-Functional Requirements');
+      lines.push('');
+    }
+
+    const startIndex = nonFunctionalRequirements.length + 1;
+    plan.validations.required_checks.forEach((check, index) => {
+      const reqNum = String(startIndex + index).padStart(2, '0');
+      const reqId = `NFR-${reqNum}`;
+      lines.push(`${reqId}: Must pass ${check} validation`);
+    });
+
+    lines.push('');
+  }
+
+  // Generate User Stories section
+  if (userStories.length > 0) {
+    lines.push('## User Stories');
+    lines.push('');
+
+    userStories.forEach((story, index) => {
+      const storyNum = String(index + 1).padStart(2, '0');
+      const storyId = `US-${storyNum}`;
+
+      // Extract story title
+      let title = story.description.replace(/^US-\d{2}:\s*/, '');
+
+      // Check if description contains "As a... I want... so that..." pattern
+      const storyMatch = title.match(/\(As a (.+?), I want (.+?), so that (.+?)\)/);
+
+      if (storyMatch) {
+        const [, userType, action, benefit] = storyMatch;
+        title = title.replace(/\(As a .+?\)/, '').trim();
+
+        lines.push(`### ${storyId}: ${title}`);
+        lines.push('');
+        lines.push(`As a ${userType},`);
+        lines.push(`I want ${action},`);
+        lines.push(`so that ${benefit}.`);
+        lines.push('');
+
+        // Extract acceptance criteria if present
+        const criteriaMatch = title.match(/- Acceptance criteria: (.+)$/);
+        if (criteriaMatch) {
+          const criteria = criteriaMatch[1].split(';').map((c) => c.trim());
+          lines.push('**Acceptance Criteria:**');
+          lines.push('');
+          criteria.forEach((criterion, i) => {
+            lines.push(`${i + 1}. ${criterion}`);
+          });
+          lines.push('');
+        }
+      } else {
+        lines.push(`### ${storyId}: ${title}`);
+        lines.push('');
+      }
+    });
+  }
+
+  // Add repository information if available
+  if (plan.provenance.repository || plan.provenance.branch) {
+    lines.push('## Repository Information');
+    lines.push('');
+
+    if (plan.provenance.repository) {
+      lines.push(`**Repository:** ${plan.provenance.repository}`);
+    }
+    if (plan.provenance.branch) {
+      lines.push(`**Branch:** ${plan.provenance.branch}`);
+    }
+    if (plan.provenance.commit) {
+      lines.push(`**Commit:** ${plan.provenance.commit}`);
+    }
+
+    lines.push('');
+  }
+
+  // Add footer
+  lines.push('---');
+  lines.push('');
+  lines.push('*Generated by Anvil - https://github.com/EddaCraft/anvil-001*');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/bmad/types.ts

@@ -0,0 +1,135 @@
+/**
+ * BMAD Format Types
+ *
+ * Type definitions for BMAD (Breakthrough Method for Agile AI-Driven Development) format.
+ */
+
+/**
+ * BMAD v6 folder structure constants
+ *
+ * v6 changed `.bmad` → `_bmad` and `_cfg` → `_config`.
+ * We support both legacy and new paths for backward compatibility.
+ */
+export const BMAD_FOLDERS = {
+  /** New v6 project folder */
+  PROJECT: '_bmad',
+  /** Legacy project folder */
+  PROJECT_LEGACY: '.bmad',
+  /** New v6 config folder */
+  CONFIG: '_config',
+  /** Legacy config folder */
+  CONFIG_LEGACY: '_cfg',
+  /** Agent memory folder (v6) */
+  MEMORY: '_memory',
+  /** Module config file (v6) */
+  MODULE_CONFIG: 'module.yaml',
+} as const;
+
+/**
+ * YAML front-matter metadata
+ */
+export interface BMADFrontMatter {
+  name?: string;
+  version?: string;
+  description?: string;
+  output_file?: string;
+  variables?: Record<string, string>;
+  template?: string;
+  date?: string;
+  author?: string;
+  /** v6: Whether the agent document has a sidecar config */
+  hasSidecar?: boolean;
+}
+
+/**
+ * BMAD document types
+ */
+export enum BMADDocumentType {
+  PRD = 'prd',
+  ARCHITECTURE = 'architecture',
+  EPIC = 'epic',
+  STORY = 'story',
+  /** v6: Agent persona/configuration document */
+  AGENT = 'agent',
+  UNKNOWN = 'unknown',
+}
+
+/**
+ * Requirement types
+ */
+export enum RequirementType {
+  FUNCTIONAL = 'FR',
+  NON_FUNCTIONAL = 'NFR',
+  USER_STORY = 'US',
+}
+
+/**
+ * Parsed requirement
+ */
+export interface BMADRequirement {
+  type: RequirementType;
+  id: string;
+  number: number;
+  description: string;
+  line?: number;
+}
+
+/**
+ * User story structure
+ */
+export interface BMADUserStory {
+  id: string;
+  title: string;
+  userType?: string;
+  action?: string;
+  benefit?: string;
+  acceptanceCriteria?: string[];
+  line?: number;
+}
+
+/**
+ * Change log entry
+ */
+export interface BMADChangeLogEntry {
+  date: string;
+  version: string;
+  description: string;
+  author: string;
+}
+
+/**
+ * Parsed BMAD document
+ */
+export interface BMADDocument {
+  type: BMADDocumentType;
+  frontMatter?: BMADFrontMatter;
+  title?: string;
+  intent?: string;
+  requirements: BMADRequirement[];
+  userStories: BMADUserStory[];
+  changeLog: BMADChangeLogEntry[];
+  sections: Map<string, string>;
+  raw: string;
+}
+
+/**
+ * Detection indicators for confidence scoring
+ */
+export interface DetectionIndicators {
+  hasYamlFrontMatter: boolean;
+  hasFunctionalRequirements: boolean;
+  hasNonFunctionalRequirements: boolean;
+  hasUserStories: boolean;
+  hasUserStoryFormat: boolean;
+  hasChangeLogTable: boolean;
+  hasDocumentTitle: boolean;
+  requirementCount: number;
+  /** v6: Path is inside a BMAD project folder */
+  hasBmadFolderPath: boolean;
+  /** v6: Path is inside a BMAD config folder */
+  hasBmadConfigPath: boolean;
+  /** v6: Document has hasSidecar field */
+  hasHasSidecar: boolean;
+  /** v6: Document uses hyphenated variable syntax */
+  hasHyphenatedVariables: boolean;
+}