@eddacraft/anvil-adapters 0.1.0

package/src/speckit/import.ts

@@ -0,0 +1,305 @@
+import { createPlan, type APSPlan, type Change, type Provenance } from '@eddacraft/anvil-core';
+import type {
+  AdapterConfig,
+  ConversionError,
+  ConversionResult,
+  ConversionWarning,
+  ExternalSpec,
+  SpecContext,
+} from '../common/types.js';
+import { BaseAdapter } from '../common/types.js';
+import { SpecKitParser } from './parser.js';
+
+interface SpecKitSpec {
+  specContent?: string;
+  planContent?: string;
+  tasksContent?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class SpecKitImportAdapter extends BaseAdapter {
+  readonly name = 'speckit-import';
+  readonly version = '1.0.0';
+  readonly supportedFormats = ['speckit', 'spec.md'] as const;
+
+  private parser: SpecKitParser;
+
+  constructor(config: AdapterConfig = {}) {
+    super(config);
+    this.parser = new SpecKitParser();
+  }
+
+  async generateSpec(intent: string, context: SpecContext): Promise<APSPlan> {
+    const provenance: Provenance = {
+      timestamp: new Date().toISOString(),
+      source: 'cli',
+      version: this.version,
+      author: context.author,
+      repository: context.repositoryPath,
+      branch: context.branch,
+      commit: context.commit,
+    };
+
+    const changes: Change[] = [
+      {
+        type: 'file_create',
+        path: 'spec.md',
+        description: 'Create initial specification file',
+        content: `# Specification\n\n## Intent\n\n${intent}\n\n## Overview\n\n[Describe the overall approach]\n\n## Requirements\n\n- [List prerequisites]\n\n## Changes\n\n- [List proposed changes]\n`,
+      },
+    ];
+
+    const planId = `aps-${Date.now().toString(16).substring(0, 8)}`;
+
+    const plan = {
+      ...createPlan({
+        id: planId,
+        intent,
+        provenance,
+        changes,
+      }),
+      schema_version: '0.1.0' as const,
+      hash: '0'.repeat(64), // Placeholder hash
+    } as APSPlan;
+    return plan;
+  }
+
+  async validateSpec(spec: APSPlan): Promise<import('@eddacraft/anvil-core').ValidationResult> {
+    const errors: Array<{ field: string; message: string }> = [];
+    const warnings: Array<{ field: string; message: string }> = [];
+
+    if (spec.proposed_changes.length === 0) {
+      warnings.push({
+        field: 'proposed_changes',
+        message: 'No changes specified in the plan',
+      });
+    }
+
+    for (let i = 0; i < spec.proposed_changes.length; i++) {
+      const change = spec.proposed_changes[i];
+      if (!change.description || change.description.length < 10) {
+        warnings.push({
+          field: `proposed_changes[${i}].description`,
+          message: 'Change description is too short or missing',
+        });
+      }
+
+      if (!change.path && change.type !== 'script_execute') {
+        errors.push({
+          field: `proposed_changes[${i}].path`,
+          message: `Path is required for change type '${change.type}'`,
+        });
+      }
+    }
+
+    const issues: Array<{
+      path: string;
+      message: string;
+      code: string;
+      severity: 'error' | 'warning';
+    }> = [
+      ...errors.map((e) => ({
+        path: e.field,
+        message: e.message,
+        code: 'VALIDATION_ERROR',
+        severity: 'error' as const,
+      })),
+      ...warnings.map((w) => ({
+        path: w.field,
+        message: w.message,
+        code: 'VALIDATION_WARNING',
+        severity: 'warning' as const,
+      })),
+    ];
+
+    return {
+      valid: errors.length === 0,
+      data: spec,
+      issues: issues.length > 0 ? issues : undefined,
+      summary: errors.length === 0 ? 'Validation passed' : `Found ${errors.length} error(s)`,
+    };
+  }
+
+  async convertToAPS(spec: ExternalSpec): Promise<ConversionResult<APSPlan>> {
+    const errors: ConversionError[] = [];
+    const warnings: ConversionWarning[] = [];
+
+    if (!this.canImport(spec.format)) {
+      return {
+        success: false,
+        errors: [
+          {
+            code: 'UNSUPPORTED_FORMAT',
+            message: `Format '${spec.format}' is not supported by this adapter`,
+          },
+        ],
+      };
+    }
+
+    try {
+      const specKitSpec = spec.content as SpecKitSpec;
+
+      if (!specKitSpec.specContent) {
+        errors.push({
+          code: 'MISSING_SPEC_CONTENT',
+          message: 'spec.md content is required',
+        });
+        return { success: false, errors };
+      }
+
+      const parsed = this.parser.parseSpecMarkdown(specKitSpec.specContent);
+
+      if (!parsed.intent && !parsed.overview) {
+        errors.push({
+          code: 'MISSING_INTENT',
+          message: 'No intent or overview section found in spec.md',
+        });
+      } else if (!parsed.intent) {
+        warnings.push({
+          code: 'MISSING_INTENT',
+          message: 'No intent section found, using overview as fallback',
+        });
+      }
+
+      const changes = this.convertChangesToAPS(parsed.changes || [], errors, warnings);
+
+      if (errors.length > 0) {
+        return { success: false, errors, warnings };
+      }
+
+      const intent = parsed.intent || parsed.overview || 'Specification from SpecKit';
+
+      const provenance: Provenance = {
+        timestamp: (spec.metadata?.['timestamp'] as string) || new Date().toISOString(),
+        source: 'cli',
+        version: this.version,
+        author: spec.metadata?.['author'] as string,
+        repository: spec.metadata?.['repository'] as string,
+        branch: spec.metadata?.['branch'] as string,
+        commit: spec.metadata?.['commit'] as string,
+      };
+
+      const planId = `aps-${Date.now().toString(16).substring(0, 8)}`;
+
+      try {
+        const plan = {
+          ...createPlan({
+            id: planId,
+            intent: intent.substring(0, 500),
+            provenance,
+            changes,
+          }),
+          schema_version: '0.1.0' as const,
+          hash: '0'.repeat(64), // Placeholder hash
+          metadata: {
+            ...parsed.metadata,
+            source_format: 'speckit',
+            goals: parsed.goals,
+            requirements: parsed.requirements,
+            overview: parsed.overview,
+          },
+        } as APSPlan;
+        return {
+          success: true,
+          data: plan,
+          warnings: warnings.length > 0 ? warnings : undefined,
+        };
+      } catch (error) {
+        errors.push({
+          code: 'APS_CREATION_FAILED',
+          message: error instanceof Error ? error.message : 'Failed to create APS plan',
+        });
+        return { success: false, errors };
+      }
+    } catch (error) {
+      errors.push({
+        code: 'CONVERSION_ERROR',
+        message: error instanceof Error ? error.message : 'Unknown conversion error',
+      });
+      return { success: false, errors };
+    }
+  }
+
+  async convertFromAPS(_spec: APSPlan): Promise<ConversionResult<ExternalSpec>> {
+    return {
+      success: false,
+      errors: [
+        {
+          code: 'NOT_IMPLEMENTED',
+          message: 'Export to SpecKit format is handled by speckit-export adapter',
+        },
+      ],
+    };
+  }
+
+  private convertChangesToAPS(
+    changes: Array<{ type: string; description: string; path?: string; content?: string }>,
+    errors: ConversionError[],
+    warnings: ConversionWarning[]
+  ): Change[] {
+    const apsChanges: Change[] = [];
+
+    for (let i = 0; i < changes.length; i++) {
+      const change = changes[i];
+
+      if (!change.description) {
+        warnings.push({
+          code: 'EMPTY_DESCRIPTION',
+          message: `Change ${i + 1} has no description`,
+          path: `changes[${i}]`,
+        });
+        continue;
+      }
+
+      const validTypes = [
+        'file_create',
+        'file_update',
+        'file_delete',
+        'config_update',
+        'dependency_add',
+        'dependency_remove',
+        'dependency_update',
+        'script_execute',
+      ];
+
+      if (!validTypes.includes(change.type)) {
+        warnings.push({
+          code: 'UNKNOWN_CHANGE_TYPE',
+          message: `Unknown change type '${change.type}', defaulting to 'script_execute'`,
+          path: `changes[${i}].type`,
+        });
+        change.type = 'script_execute';
+      }
+
+      const apsChange: Change = {
+        type: change.type as Change['type'],
+        path: change.path || '',
+        description: change.description,
+      };
+
+      if (change.content) {
+        apsChange.content = change.content;
+      }
+
+      if (!apsChange.path && apsChange.type !== 'script_execute') {
+        warnings.push({
+          code: 'MISSING_PATH',
+          message: `Path not specified for ${apsChange.type}, using placeholder`,
+          path: `changes[${i}].path`,
+        });
+        apsChange.path = '<path-to-be-specified>';
+      }
+
+      apsChanges.push(apsChange);
+    }
+
+    if (apsChanges.length === 0) {
+      warnings.push({
+        code: 'NO_CHANGES',
+        message: 'No valid changes found in specification',
+      });
+    }
+
+    return apsChanges;
+  }
+}

package/src/speckit/index.ts

@@ -0,0 +1,4 @@
+export { SpecKitImportAdapter } from './import.js';
+export { SpecKitExportAdapter } from './export.js';
+export { SpecKitParser } from './parser.js';
+export { SpecKitFormatAdapter, createSpecKitAdapter } from './format-adapter.js';

package/src/speckit/parser.ts

@@ -0,0 +1,351 @@
+import { validateRelativePath } from '@eddacraft/anvil-core';
+
+interface MarkdownSection {
+  title: string;
+  level: number;
+  content: string;
+  subsections: MarkdownSection[];
+}
+
+interface ParsedSpecKit {
+  intent?: string;
+  overview?: string;
+  goals?: string[];
+  requirements?: string[];
+  changes?: Array<{
+    type: string;
+    description: string;
+    path?: string;
+    content?: string;
+  }>;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Validate and sanitize a file path to prevent path traversal attacks.
+ * Returns undefined if the path is invalid (absolute, contains null bytes, or escapes parent directory).
+ */
+function safePath(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  try {
+    return validateRelativePath(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+export class SpecKitParser {
+  private static readonly SPEC_SECTIONS = {
+    intent: ['intent', 'purpose', 'objective'],
+    overview: ['overview', 'summary', 'description'],
+    goals: ['goals', 'objectives', 'outcomes'],
+    requirements: ['requirements', 'prerequisites', 'dependencies'],
+    changes: ['changes', 'modifications', 'alterations', 'tasks'],
+  } as const;
+
+  /** Maximum input size for SpecKit parsing (2MB) */
+  private static readonly MAX_INPUT_SIZE = 2 * 1024 * 1024;
+
+  parseSpecMarkdown(content: string): ParsedSpecKit {
+    if (content.length > SpecKitParser.MAX_INPUT_SIZE) {
+      throw new Error(`Input exceeds maximum size of ${SpecKitParser.MAX_INPUT_SIZE} bytes`);
+    }
+    const sections = this.parseMarkdownSections(content);
+    const result: ParsedSpecKit = {
+      metadata: {},
+    };
+
+    for (const section of sections) {
+      this.extractSectionData(section, result);
+    }
+
+    return result;
+  }
+
+  private parseMarkdownSections(content: string): MarkdownSection[] {
+    const lines = content.split('\n');
+    const sections: MarkdownSection[] = [];
+    const stack: MarkdownSection[] = [];
+    let currentContent: string[] = [];
+
+    for (const line of lines) {
+      const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+      if (headerMatch) {
+        if (currentContent.length > 0 && stack.length > 0) {
+          stack[stack.length - 1].content = currentContent.join('\n').trim();
+        }
+
+        const level = headerMatch[1].length;
+        const title = headerMatch[2].trim();
+
+        const newSection: MarkdownSection = {
+          title,
+          level,
+          content: '',
+          subsections: [],
+        };
+
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+          stack.pop();
+        }
+
+        if (stack.length === 0) {
+          sections.push(newSection);
+        } else {
+          stack[stack.length - 1].subsections.push(newSection);
+        }
+
+        stack.push(newSection);
+        currentContent = [];
+      } else {
+        currentContent.push(line);
+      }
+    }
+
+    if (currentContent.length > 0 && stack.length > 0) {
+      stack[stack.length - 1].content = currentContent.join('\n').trim();
+    }
+
+    return sections;
+  }
+
+  private extractSectionData(section: MarkdownSection, result: ParsedSpecKit): void {
+    const sectionTitleLower = section.title.toLowerCase();
+    let sectionWasProcessed = false;
+
+    for (const [key, aliases] of Object.entries(SpecKitParser.SPEC_SECTIONS)) {
+      // Use word boundary matching to avoid partial matches (e.g., "objective" shouldn't match "objectives")
+      if (
+        aliases.some((alias) => {
+          const regex = new RegExp(`\\b${alias}\\b`, 'i');
+          return regex.test(sectionTitleLower);
+        })
+      ) {
+        sectionWasProcessed = true;
+        switch (key) {
+          case 'intent':
+            // For intent, get only the paragraph text, not list items
+            result.intent = this.extractParagraphText(section.content);
+            break;
+          case 'overview':
+            // For overview, get only the paragraph text, not list items
+            result.overview = this.extractParagraphText(section.content);
+            break;
+          case 'goals':
+            result.goals = this.parseListItems(section.content);
+            break;
+          case 'requirements':
+            result.requirements = this.parseListItems(section.content);
+            break;
+          case 'changes':
+            // parseChanges handles all nested subsections, so don't recurse into them
+            result.changes = this.parseChanges(section);
+            return; // Exit early - changes section is fully processed
+        }
+      }
+    }
+
+    // Only recurse into subsections if this section wasn't fully processed by a specialized method
+    // or if the section didn't match any known section types
+    if (!sectionWasProcessed) {
+      for (const subsection of section.subsections) {
+        this.extractSectionData(subsection, result);
+      }
+    }
+  }
+
+  private extractParagraphText(content: string): string {
+    const lines = content.split('\n');
+    const paragraphLines: string[] = [];
+    let hasContent = false;
+
+    for (const line of lines) {
+      const trimmedLine = line.trim();
+
+      // Stop at list items
+      if (trimmedLine.match(/^[-*+]\s+/) || trimmedLine.match(/^\d+\.\s+/)) {
+        break;
+      }
+
+      // Add non-empty lines
+      if (trimmedLine) {
+        paragraphLines.push(trimmedLine);
+        hasContent = true;
+      } else if (hasContent && paragraphLines.length > 0) {
+        // Stop at empty line after we've collected some content
+        break;
+      }
+    }
+
+    return paragraphLines.join(' ').trim();
+  }
+
+  private parseListItems(content: string): string[] {
+    const lines = content.split('\n');
+    const items: string[] = [];
+    let currentItem = '';
+
+    for (const line of lines) {
+      const listMatch = line.match(/^[\s]*[-*+]\s+(.+)$/);
+      const numberedMatch = line.match(/^[\s]*\d+\.\s+(.+)$/);
+
+      if (listMatch || numberedMatch) {
+        if (currentItem) {
+          items.push(currentItem.trim());
+        }
+        currentItem = (listMatch?.[1] || numberedMatch?.[1] || '').trim();
+      } else if (currentItem && line.trim()) {
+        currentItem += ' ' + line.trim();
+      }
+    }
+
+    if (currentItem) {
+      items.push(currentItem.trim());
+    }
+
+    return items;
+  }
+
+  private parseChanges(section: MarkdownSection): Array<{
+    type: string;
+    description: string;
+    path?: string;
+    content?: string;
+  }> {
+    const changes: Array<{
+      type: string;
+      description: string;
+      path?: string;
+      content?: string;
+    }> = [];
+
+    // Process direct subsections
+    for (const subsection of section.subsections) {
+      // Check if this subsection is a grouping section (like "Files to Create")
+      const subsectionTitleLower = subsection.title.toLowerCase();
+      const isGroupingSection =
+        subsectionTitleLower.includes('files to') ||
+        subsectionTitleLower.includes('configuration') ||
+        subsectionTitleLower.includes('dependencies') ||
+        subsectionTitleLower.includes('scripts');
+
+      if (isGroupingSection && subsection.subsections.length > 0) {
+        // Process nested subsections within grouping sections
+        for (const nestedSection of subsection.subsections) {
+          const change = this.parseChangeSection(nestedSection);
+          if (change) {
+            changes.push(change);
+          }
+        }
+      } else {
+        // Process as a direct change section
+        const change = this.parseChangeSection(subsection);
+        if (change) {
+          changes.push(change);
+        }
+      }
+    }
+
+    // Fallback to parsing list items if no subsections found
+    if (changes.length === 0) {
+      const listItems = this.parseListItems(section.content);
+      for (const item of listItems) {
+        const change = this.parseChangeFromListItem(item);
+        if (change) {
+          changes.push(change);
+        }
+      }
+    }
+
+    return changes;
+  }
+
+  private parseChangeSection(section: MarkdownSection): {
+    type: string;
+    description: string;
+    path?: string;
+    content?: string;
+  } | null {
+    const titleLower = section.title.toLowerCase();
+    let type = 'script_execute';
+
+    if (titleLower.includes('create') || titleLower.includes('new')) {
+      type = 'file_create';
+    } else if (titleLower.includes('update') || titleLower.includes('modify')) {
+      type = 'file_update';
+    } else if (titleLower.includes('delete') || titleLower.includes('remove')) {
+      type = 'file_delete';
+    } else if (titleLower.includes('config')) {
+      type = 'config_update';
+    } else if (titleLower.includes('dependency') || titleLower.includes('package')) {
+      if (titleLower.includes('add') || titleLower.includes('install')) {
+        type = 'dependency_add';
+      } else if (titleLower.includes('remove') || titleLower.includes('uninstall')) {
+        type = 'dependency_remove';
+      } else {
+        type = 'dependency_update';
+      }
+    }
+
+    // Look for path in title first, then in content
+    let pathMatch = section.title.match(/`([^`]+)`/);
+    if (!pathMatch && section.content) {
+      // Look for path in the first line of content
+      const firstLine = section.content.split('\n')[0];
+      pathMatch = firstLine.match(/`([^`]+)`/);
+    }
+    const path = safePath(pathMatch?.[1]);
+
+    const codeBlockMatch = section.content.match(/```[\w]*\n([\s\S]*?)```/);
+    const content = codeBlockMatch ? codeBlockMatch[1].trim() : undefined;
+
+    return {
+      type,
+      description: section.title,
+      path,
+      content,
+    };
+  }
+
+  private parseChangeFromListItem(item: string): {
+    type: string;
+    description: string;
+    path?: string;
+  } | null {
+    const itemLower = item.toLowerCase();
+    let type = 'script_execute';
+
+    // Check for script execution patterns first
+    if (
+      itemLower.includes('run') ||
+      itemLower.includes('execute') ||
+      itemLower.includes('script')
+    ) {
+      type = 'script_execute';
+    } else if (itemLower.includes('create') || itemLower.includes('new file')) {
+      type = 'file_create';
+    } else if (itemLower.includes('delete') || itemLower.includes('remove file')) {
+      type = 'file_delete';
+    } else if (itemLower.includes('update dependency')) {
+      type = 'dependency_update';
+    } else if (itemLower.includes('install') || itemLower.includes('add dependency')) {
+      type = 'dependency_add';
+    } else if (itemLower.includes('uninstall') || itemLower.includes('remove dependency')) {
+      type = 'dependency_remove';
+    } else if (itemLower.includes('update') || itemLower.includes('modify')) {
+      type = 'file_update';
+    } else if (itemLower.includes('config')) {
+      type = 'config_update';
+    }
+
+    const pathMatch = item.match(/`([^`]+)`/);
+    const path = safePath(pathMatch?.[1]);
+
+    return {
+      type,
+      description: item,
+      path,
+    };
+  }
+}