@iservu-inc/adf-cli 0.17.1 → 0.18.0

package/lib/harness/feature-manifest.js

@@ -0,0 +1,175 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { FeatureManifest } = require('./protocol');
+
+/**
+ * Feature Manifest Manager
+ *
+ * Generates and manages the feature list from session outputs.
+ * Enforces passes-only mutation pattern (Anthropic feature list pattern).
+ */
+class FeatureManifestManager {
+  constructor(runDir) {
+    this.runDir = runDir;
+    this.filePath = path.join(runDir, 'feature-manifest.json');
+    this.manifest = null;
+  }
+
+  /**
+   * Generate feature manifest from session outputs
+   */
+  async generateFromSession(runId, sessionOutputs = {}) {
+    const features = [];
+
+    // Extract features from PRP output
+    if (sessionOutputs.prp) {
+      const prpFeatures = this.extractFeaturesFromMarkdown(sessionOutputs.prp, 'prp');
+      features.push(...prpFeatures);
+    }
+
+    // Extract features from specification output
+    if (sessionOutputs.specification) {
+      const specFeatures = this.extractFeaturesFromMarkdown(sessionOutputs.specification, 'specification');
+      features.push(...specFeatures);
+    }
+
+    // Extract features from stories output
+    if (sessionOutputs.stories) {
+      const storyFeatures = this.extractFeaturesFromMarkdown(sessionOutputs.stories, 'stories');
+      features.push(...storyFeatures);
+    }
+
+    // Extract features from PRD output
+    if (sessionOutputs.prd) {
+      const prdFeatures = this.extractFeaturesFromMarkdown(sessionOutputs.prd, 'prd');
+      features.push(...prdFeatures);
+    }
+
+    // Extract features from tasks output
+    if (sessionOutputs.tasks) {
+      const taskFeatures = this.extractFeaturesFromMarkdown(sessionOutputs.tasks, 'tasks');
+      features.push(...taskFeatures);
+    }
+
+    this.manifest = new FeatureManifest({ runId, features });
+    await this.save();
+    return this.manifest;
+  }
+
+  /**
+   * Generate feature manifest from explicit feature list
+   */
+  async generateFromList(runId, featureList) {
+    const features = featureList.map(f => ({
+      title: f.title,
+      description: f.description || '',
+      sourceQuestions: f.sourceQuestions || [],
+      acceptanceCriteria: f.acceptanceCriteria || []
+    }));
+
+    this.manifest = new FeatureManifest({ runId, features });
+    await this.save();
+    return this.manifest;
+  }
+
+  /**
+   * Mark a feature as passing (ONLY allowed mutation)
+   */
+  async markPasses(featureId) {
+    if (!this.manifest) {
+      await this.load();
+    }
+    if (!this.manifest) {
+      throw new Error('No feature manifest loaded');
+    }
+
+    const feature = this.manifest.markPasses(featureId);
+    await this.save();
+    return feature;
+  }
+
+  /**
+   * Get progress summary
+   */
+  getProgress() {
+    if (!this.manifest) return { total: 0, passed: 0, remaining: 0, percentage: 0 };
+    return this.manifest.getProgress();
+  }
+
+  /**
+   * Save manifest to disk
+   */
+  async save() {
+    if (!this.manifest) return;
+    await fs.writeJson(this.filePath, this.manifest.toJSON(), { spaces: 2 });
+  }
+
+  /**
+   * Load manifest from disk
+   */
+  async load() {
+    if (!await fs.pathExists(this.filePath)) {
+      return false;
+    }
+
+    const data = await fs.readJson(this.filePath);
+    this.manifest = FeatureManifest.fromJSON(data);
+    return true;
+  }
+
+  /**
+   * Get the manifest
+   */
+  getManifest() {
+    return this.manifest;
+  }
+
+  /**
+   * Extract features from markdown content (simple heuristic)
+   */
+  extractFeaturesFromMarkdown(content, source) {
+    const features = [];
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      // Match h2/h3 headers that look like features
+      const headerMatch = line.match(/^#{2,3}\s+(?:\d+\.\s+)?(.+)/);
+      if (headerMatch) {
+        const title = headerMatch[1].trim();
+
+        // Skip generic headers
+        const skipHeaders = [
+          'overview', 'summary', 'introduction', 'table of contents',
+          'references', 'appendix', 'glossary', 'changelog',
+          'executive summary', 'background', 'scope', 'assumptions'
+        ];
+        if (skipHeaders.some(h => title.toLowerCase().includes(h))) {
+          continue;
+        }
+
+        // Collect description from following lines
+        let description = '';
+        for (let j = i + 1; j < lines.length && j < i + 4; j++) {
+          const nextLine = lines[j].trim();
+          if (nextLine && !nextLine.startsWith('#')) {
+            description += (description ? ' ' : '') + nextLine;
+          } else if (nextLine.startsWith('#')) {
+            break;
+          }
+        }
+
+        features.push({
+          title,
+          description: description.slice(0, 200),
+          sourceQuestions: [source]
+        });
+      }
+    }
+
+    return features;
+  }
+}
+
+module.exports = FeatureManifestManager;

package/lib/harness/headless-adapter.js

@@ -0,0 +1,184 @@
+const fs = require('fs-extra');
+
+/**
+ * Headless Adapter
+ *
+ * Replaces interactive inquirer prompts with JSON-driven input
+ * for CI/automation pipelines. Provides deterministic answer flow
+ * without user interaction.
+ */
+class HeadlessAdapter {
+  constructor(inputSource) {
+    this.answers = new Map();
+    this.defaultAnswer = null;
+    this.answerIndex = 0;
+    this.orderedAnswers = [];
+    this.log = [];
+
+    if (inputSource) {
+      this.loadSource(inputSource);
+    }
+  }
+
+  /**
+   * Load answers from various source types
+   */
+  loadSource(source) {
+    if (typeof source === 'string') {
+      // File path - will be loaded async
+      this.pendingFile = source;
+    } else if (Array.isArray(source)) {
+      // Ordered array of answers
+      this.orderedAnswers = source;
+    } else if (typeof source === 'object') {
+      // Map of questionId -> answer
+      for (const [key, value] of Object.entries(source)) {
+        this.answers.set(key, value);
+      }
+    }
+  }
+
+  /**
+   * Load answers from a JSON file
+   */
+  async loadFromFile(filePath) {
+    if (!await fs.pathExists(filePath)) {
+      throw new Error(`Headless input file not found: ${filePath}`);
+    }
+
+    const data = await fs.readJson(filePath);
+
+    if (data.answers) {
+      // Structured format: { answers: { questionId: answer }, defaults: {...} }
+      for (const [key, value] of Object.entries(data.answers)) {
+        this.answers.set(key, value);
+      }
+    }
+
+    if (data.orderedAnswers) {
+      this.orderedAnswers = data.orderedAnswers;
+    }
+
+    if (data.defaultAnswer) {
+      this.defaultAnswer = data.defaultAnswer;
+    }
+
+    return this;
+  }
+
+  /**
+   * Initialize (load pending file if any)
+   */
+  async initialize() {
+    if (this.pendingFile) {
+      await this.loadFromFile(this.pendingFile);
+      this.pendingFile = null;
+    }
+  }
+
+  /**
+   * Get an answer for a question (replaces inquirer.prompt)
+   */
+  getAnswer(questionId, questionText) {
+    let answer = null;
+
+    // Try mapped answer first
+    if (this.answers.has(questionId)) {
+      answer = this.answers.get(questionId);
+    }
+    // Try ordered answers
+    else if (this.answerIndex < this.orderedAnswers.length) {
+      answer = this.orderedAnswers[this.answerIndex];
+      this.answerIndex++;
+    }
+    // Use default
+    else if (this.defaultAnswer) {
+      answer = typeof this.defaultAnswer === 'function'
+        ? this.defaultAnswer(questionId, questionText)
+        : this.defaultAnswer;
+    }
+
+    this.log.push({
+      questionId,
+      questionText,
+      answer,
+      timestamp: new Date().toISOString()
+    });
+
+    return answer;
+  }
+
+  /**
+   * Get a choice selection (replaces inquirer list/select)
+   */
+  getChoice(questionId, choices, defaultChoice) {
+    // Try mapped answer
+    if (this.answers.has(questionId)) {
+      const mapped = this.answers.get(questionId);
+      // Find matching choice
+      const match = choices.find(c =>
+        (typeof c === 'string' && c === mapped) ||
+        (typeof c === 'object' && (c.value === mapped || c.name === mapped))
+      );
+      if (match) {
+        return typeof match === 'object' ? match.value : match;
+      }
+    }
+
+    // Return default or first choice
+    if (defaultChoice !== undefined) return defaultChoice;
+    const first = choices[0];
+    return typeof first === 'object' ? first.value : first;
+  }
+
+  /**
+   * Get confirmation (replaces inquirer confirm)
+   */
+  getConfirmation(questionId, defaultValue = true) {
+    if (this.answers.has(questionId)) {
+      const val = this.answers.get(questionId);
+      return typeof val === 'boolean' ? val : val === 'yes' || val === 'true';
+    }
+    return defaultValue;
+  }
+
+  /**
+   * Check if there are more answers available
+   */
+  hasMoreAnswers() {
+    return this.answerIndex < this.orderedAnswers.length ||
+           this.defaultAnswer !== null;
+  }
+
+  /**
+   * Get the interaction log
+   */
+  getLog() {
+    return this.log;
+  }
+
+  /**
+   * Get stats
+   */
+  getStats() {
+    return {
+      totalQuestions: this.log.length,
+      answered: this.log.filter(l => l.answer !== null).length,
+      unanswered: this.log.filter(l => l.answer === null).length,
+      mappedAnswers: this.answers.size,
+      orderedAnswersRemaining: Math.max(0, this.orderedAnswers.length - this.answerIndex)
+    };
+  }
+
+  /**
+   * Export log to JSON for debugging
+   */
+  async exportLog(filePath) {
+    await fs.writeJson(filePath, {
+      stats: this.getStats(),
+      log: this.log
+    }, { spaces: 2 });
+  }
+}
+
+module.exports = HeadlessAdapter;

package/lib/harness/milestone-tracker.js

@@ -0,0 +1,183 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { Milestone } = require('./protocol');
+
+/**
+ * Milestone Tracker
+ *
+ * Maps ADF question blocks to milestones, tracks progression,
+ * and provides checkpoint-based progress reporting.
+ */
+class MilestoneTracker {
+  constructor(runDir) {
+    this.runDir = runDir;
+    this.milestonesDir = path.join(runDir, 'milestones');
+    this.milestones = [];
+  }
+
+  /**
+   * Generate milestones from question blocks
+   */
+  async generateFromBlocks(blocks) {
+    this.milestones = blocks.map((block, index) => {
+      return new Milestone({
+        index,
+        title: block.title || `Block ${index + 1}`,
+        description: block.description || '',
+        blockNumber: block.number != null ? block.number : index + 1,
+        questionsInScope: (block.questions || []).map(q => q.id || q),
+        acceptanceCriteria: block.acceptanceCriteria || [
+          `All questions in "${block.title || `Block ${index + 1}`}" answered or explicitly skipped`
+        ]
+      });
+    });
+
+    await this.saveAll();
+    return this.milestones;
+  }
+
+  /**
+   * Mark a question as completed within its milestone
+   */
+  async completeQuestion(questionId) {
+    for (const milestone of this.milestones) {
+      if (milestone.questionsInScope.includes(questionId)) {
+        if (!milestone.questionsCompleted.includes(questionId)) {
+          milestone.questionsCompleted.push(questionId);
+        }
+
+        // Update percentage
+        const total = milestone.questionsInScope.length;
+        const done = milestone.questionsCompleted.length;
+        milestone.percentage = total > 0 ? Math.round((done / total) * 100) : 0;
+
+        // Auto-transition status
+        if (milestone.status === 'pending') {
+          milestone.status = 'in_progress';
+        }
+        if (done >= total) {
+          milestone.status = 'completed';
+          milestone.completedAt = new Date().toISOString();
+        }
+
+        await this.saveMilestone(milestone);
+        return milestone;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Skip a milestone entirely
+   */
+  async skipMilestone(index) {
+    if (index < 0 || index >= this.milestones.length) {
+      throw new Error(`Invalid milestone index: ${index}`);
+    }
+
+    const milestone = this.milestones[index];
+    milestone.status = 'skipped';
+    await this.saveMilestone(milestone);
+    return milestone;
+  }
+
+  /**
+   * Get current milestone (first non-completed, non-skipped)
+   */
+  getCurrentMilestone() {
+    return this.milestones.find(m =>
+      m.status === 'pending' || m.status === 'in_progress'
+    ) || null;
+  }
+
+  /**
+   * Get current milestone index
+   */
+  getCurrentIndex() {
+    const current = this.getCurrentMilestone();
+    return current ? current.index : this.milestones.length;
+  }
+
+  /**
+   * Get overall progress
+   */
+  getProgress() {
+    const total = this.milestones.length;
+    const completed = this.milestones.filter(m => m.status === 'completed').length;
+    const skipped = this.milestones.filter(m => m.status === 'skipped').length;
+    const inProgress = this.milestones.filter(m => m.status === 'in_progress').length;
+    const pending = this.milestones.filter(m => m.status === 'pending').length;
+
+    return {
+      total,
+      completed,
+      skipped,
+      inProgress,
+      pending,
+      percentage: total > 0 ? Math.round(((completed + skipped) / total) * 100) : 0
+    };
+  }
+
+  /**
+   * Get milestone for handoff package
+   */
+  getHandoffInfo() {
+    const current = this.getCurrentMilestone();
+    if (!current) {
+      return { index: this.milestones.length, title: 'All complete', percentage: 100 };
+    }
+    return {
+      index: current.index,
+      title: current.title,
+      percentage: current.percentage
+    };
+  }
+
+  /**
+   * Save a single milestone
+   */
+  async saveMilestone(milestone) {
+    await fs.ensureDir(this.milestonesDir);
+    const filePath = path.join(this.milestonesDir, `ms_${milestone.index + 1}.json`);
+    await fs.writeJson(filePath, milestone.toJSON(), { spaces: 2 });
+  }
+
+  /**
+   * Save all milestones
+   */
+  async saveAll() {
+    await fs.ensureDir(this.milestonesDir);
+    for (const milestone of this.milestones) {
+      await this.saveMilestone(milestone);
+    }
+  }
+
+  /**
+   * Load milestones from disk
+   */
+  async load() {
+    if (!await fs.pathExists(this.milestonesDir)) {
+      return false;
+    }
+
+    const files = await fs.readdir(this.milestonesDir);
+    const milestoneFiles = files.filter(f => f.startsWith('ms_') && f.endsWith('.json'));
+
+    this.milestones = [];
+    for (const file of milestoneFiles.sort()) {
+      const data = await fs.readJson(path.join(this.milestonesDir, file));
+      this.milestones.push(Milestone.fromJSON(data));
+    }
+
+    return this.milestones.length > 0;
+  }
+
+  /**
+   * Get all milestones
+   */
+  getAll() {
+    return this.milestones;
+  }
+}
+
+module.exports = MilestoneTracker;