faf-taf-git 2.0.4

package/project.faf

@@ -0,0 +1,259 @@
+faf_version: 2.5.0
+ai_scoring_system: 2025-09-20
+ai_score: 65%
+ai_confidence: MODERATE
+ai_value: 30_seconds_replaces_20_minutes_of_questions
+ai_tldr:
+  project: faf-taf-git v2.0.4 - Git-tracked testing timelines for ANY CI/CD
+  stack: TypeScript CLI + GitHub Action (pre-capture architecture)
+  quality_bar: ZERO_ERRORS_F1_STANDARDS
+  status: PRODUCTION_READY (working in faf-cli repo)
+  breakthrough: v2.0.0 pre-capture pattern (tested 19 methods before this)
+  current_focus: Ecosystem adoption and user onboarding
+  your_role: Support users, fix bugs, add test framework support
+instant_context:
+  what_building: Platform-agnostic CLI + GitHub Action for TAF updates
+  tech_stack: TypeScript
+  main_language: TypeScript
+  deployment: npm + GitHub Actions Marketplace
+  architecture: v2.0.0 pre-capture pattern (separate test execution from receipt generation)
+  use_cases: Standalone CLI, GitHub Action, GitLab CI, Jenkins, CircleCI, Local
+    development
+  test_support: Jest (fully supported) with plans for Mocha, Vitest, Pytest, Go
+    test, Rust cargo
+  golden_triangle: .faf (project DNA) + repo (code) + .taf (test proof)
+  key_files:
+    - src/index.ts (v2.0.0 rewrite - reads test output file)
+    - src/parsers/jest.ts (v2.0.4 fix - correct pattern matching)
+    - src/taf-core.ts (MCP-portable core)
+    - action.yml (v2.0.2 fix - correct bundle path)
+    - README.md (6Ws format)
+    - CHANGELOG.md (22 versions documented)
+  documentation:
+    - README: 6Ws format (What/Who/Why/Where/When/How)
+    - CHANGELOG: Complete debugging journey (v1.0.4 → v2.0.4)
+    - Migration guide: v1.x → v2.x breaking changes
+context_quality:
+  slots_filled: 11/21 (52%)
+  ai_confidence: MODERATE
+  handoff_ready: true
+  missing_context: []
+project:
+  name: faf-taf-git
+  goal: Platform-agnostic TAF (Testing Activity Feed) updater - works in ANY CI/CD
+  innovation: On-the-fly Testing Audit Files - Unheard of in CI/CD
+  taf_meaning:
+    file: Testing Audit File (.taf)
+    feed: Testing Activity Feed (live updates)
+  main_language: TypeScript
+  type: typescript
+  generated: 2025-10-28T01:26:05.656Z
+  repository: https://github.com/Wolfe-Jam/faf-taf-git
+  license: MIT
+  author: wolfejam
+  keywords: testing, taf, ci-cd, github-actions, gitlab-ci, platform-agnostic,
+    jest, faf, git
+  mission: 🚀 Make Your AI Happy! 🧡 Trust-Driven 🤖
+  revolution: 30 seconds replaces 20 minutes of questions
+  brand: F1-Inspired Software Engineering - Championship AI Context
+ai_instructions:
+  priority_order:
+    - 1. Read THIS .faf file first
+    - 2. Check CLAUDE.md for session context
+    - 3. Review package.json for dependencies
+  working_style:
+    code_first: true
+    explanations: minimal
+    quality_bar: zero_errors
+    testing: required
+  warnings:
+    - Never modify dial components without approval
+    - All TypeScript must pass strict mode
+    - Test coverage required for new features
+stack:
+  frontend: None
+  css_framework: None
+  ui_library: None
+  state_management: None
+  backend: None
+  runtime: Node.js
+  database: None
+  build: TypeScript Compiler
+  package_manager: npm
+  api_type: REST
+  hosting: npm Registry
+  cicd: GitHub Actions
+  targetUser: developers
+  coreProblem: understanding project
+  missionPurpose: project documentation
+  packageManager: npm/yarn/pnpm
+  mainLanguage: JavaScript/TypeScript
+cli_features:
+  commands:
+    - npx faf-taf-git
+    - --file (test output file - v2.0.0+)
+    - --command (custom test command - legacy v1.x)
+    - --commit (auto-commit .taf changes)
+    - --verbose (detailed output)
+    - --message (custom commit message)
+    - --cwd (working directory)
+  github_action_inputs:
+    test-output-file: required (v2.0.0+)
+    auto-commit: true (default)
+    commit-message: "chore(taf): update .taf receipt [skip ci] (default)"
+  architecture:
+    version: v2.0.0
+    pattern: pre-capture
+    breakthrough: Separate test execution from receipt generation
+    why: Avoids GitHub Actions execution context corruption
+    reliability: Tested 19 methods before this solution
+    benefits:
+      - More reliable (no execution context issues)
+      - Platform-agnostic (works everywhere)
+      - Simpler (400+ lines removed, 11KB smaller)
+  test_frameworks:
+    - Jest (fully supported)
+  supported_platforms:
+    - GitHub Actions
+    - GitLab CI
+    - Bitbucket Pipelines
+    - Jenkins
+    - CircleCI
+    - Travis CI
+    - Azure Pipelines
+    - Local development
+taf_format:
+  format: YAML
+  file_location: .taf (hidden dotfile)
+  purpose: Git-tracked testing timeline - permanent proof your code works
+  links_to_faf: true
+  snapshots_faf_score: true
+  closed_loop_system: .faf (DNA) + repo (code) + .taf (proof) = Golden Triangle
+deployment:
+  npm_package: faf-taf-git@2.0.4
+  github_action: Wolfe-Jam/faf-taf-git@v2.0.4
+  marketplaces:
+    - npm Registry
+    - GitHub Actions Marketplace
+  install: npx faf-taf-git
+  production_users:
+    - faf-cli (working in CI)
+testing:
+  framework: Jest
+  coverage: Core functionality
+  ci_integration: GitHub Actions
+  test_files:
+    - tests/ (unit tests)
+  quality_gates:
+    - All tests must pass
+    - TypeScript strict mode
+    - Zero build errors
+examples:
+  github_actions: README.md Quick Start section
+  standalone_cli: README.md Standalone CLI section
+  gitlab_ci: README.md GitLab CI section
+  jenkins: README.md Jenkins section
+  migration: README.md Migration from v1.x section
+performance:
+  bundle_size: 1.2MB (v2.0.0 - reduced 11KB from v1.x)
+  startup_time: <100ms
+  parse_time: <10ms for typical Jest output
+  reliability: 100% success rate in faf-cli CI (after v2.0.4)
+preferences:
+  quality_bar: zero_errors
+  commit_style: conventional_emoji
+  response_style: concise_code_first
+  explanation_level: minimal
+  communication: direct
+  testing: required
+  documentation: as_needed
+contributing:
+  guidelines: CONTRIBUTING.md
+  code_style: TypeScript strict mode
+  pr_process: Fork, branch, PR with tests
+  commit_format: Conventional commits with Co-Authored-By
+  testing_required: true
+  documentation_required: For new features
+resources:
+  readme: README.md (6Ws format)
+  changelog: CHANGELOG.md (22 versions documented)
+  license: MIT
+  repository: https://github.com/Wolfe-Jam/faf-taf-git
+  npm: https://npmjs.com/package/faf-taf-git
+  issues: https://github.com/Wolfe-Jam/faf-taf-git/issues
+  discussions: https://github.com/Wolfe-Jam/faf/discussions
+state:
+  phase: production
+  version: 2.0.4
+  focus: ecosystem_adoption
+  status: production_ready
+  achievements:
+    - v2.0.0 architectural redesign (pre-capture pattern)
+    - v2.0.4 parser fix (working in CI)
+    - Updated README (6Ws format)
+    - Updated CHANGELOG (22 versions documented)
+    - TAF Receipt generating successfully in faf-cli repo
+  next_milestone: user_adoption
+  blockers: null
+tags:
+  auto_generated:
+    - faf-taf-action
+    - none
+    - typescript
+  smart_defaults:
+    - .faf
+    - ai-ready
+    - "2025"
+    - software
+    - open-source
+  user_defined: null
+human_context:
+  who: Development teams
+  what: TAF file updates in CI/CD pipelines
+  why: Improve development efficiency
+  where: Any CI/CD platform (GitHub, GitLab, Bitbucket)
+  when: During CI/CD test runs
+  how: Test-driven development
+  additional_context: Part of Golden Triangle (.faf + repo + .taf). Tracks test
+    runs permanently in git. Supports Jest, works as CLI or GitHub Action.
+    Platform-agnostic core - runs on ANY CI/CD with Node.js.
+  context_score: 0
+  total_prd_score: 65
+  success_rate: 50%
+scores:
+  faf_score: 50
+  slot_based_percentage: 52
+  ai_score: 65
+  total_slots: 21
+  filled_slots: 11
+  scoring_method: Honest percentage - no fake minimums
+  trust_embedded: COUNT ONCE architecture - trust MY embedded scores
+ai_scoring_details:
+  system_date: 2025-09-20
+  slot_based_percentage: 52
+  ai_score: 65
+  total_slots: 21
+  filled_slots: 11
+  scoring_method: Honest percentage - no fake minimums
+  trust_embedded: COUNT ONCE architecture - trust MY embedded scores
+faf_dna:
+  birth_dna: 22
+  birth_certificate: FAF-2025-FAFTAFAC-TMZU
+  birth_date: 2025-10-28T01:26:05.692Z
+  current_score: 50
+projectName: faf-taf-git
+projectGoal: Platform-agnostic TAF (Testing Activity Feed) updater - works in ANY CI/CD
+generated: 2026-02-17T20:14:09.215Z
+last_major_update: v2.0.4 (2026-02-17)
+production_status: Working in faf-cli repository
+stack_signature: typescript-nodejs-javascript
+detected_frameworks:
+  - Claude Code
+  - Jest
+  - Node.js
+  - JavaScript
+  - TypeScript
+turbo_cat_intelligence: 260
+stats:
+  last_auto_time: 0.6
+  times_run: 1

package/src/cli.ts

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+/**
+ * faf-taf-git - Standalone CLI for TAF operations
+ *
+ * Platform-agnostic core that works in ANY CI/CD environment
+ * Can be used standalone or as a library by wrappers
+ */
+
+import * as exec from '@actions/exec';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { parseJestOutput } from './parsers/jest';
+import { updateTafFile } from './taf-core';
+
+export interface CLIOptions {
+  command?: string;
+  autoCommit?: boolean;
+  commitMessage?: string;
+  cwd?: string;
+  verbose?: boolean;
+  logger?: (message: string) => void;
+}
+
+export interface CLIResult {
+  success: boolean;
+  testResults?: {
+    total: number;
+    passed: number;
+    failed: number;
+    result: string;
+  };
+  tafUpdated: boolean;
+  error?: string;
+}
+
+/**
+ * Main CLI function - platform-agnostic
+ * Can be called from GitHub Actions, GitLab CI, or standalone
+ */
+export async function runTafGit(options: CLIOptions = {}): Promise<CLIResult> {
+  const {
+    command = 'npm test',
+    autoCommit = false,
+    commitMessage = 'chore: update .taf with test results',
+    cwd = process.cwd(),
+    verbose = false,
+    logger = console.log,
+  } = options;
+
+  try {
+    if (verbose) console.log(`Running test command: ${command}`);
+
+    // Run tests and capture output using @actions/exec
+    let output = '';
+    let exitCode = 0;
+
+    try {
+      // Parse command into executable and args
+      // For "npm test" -> ["npm", "test"]
+      const commandParts = command.split(' ');
+      const executable = commandParts[0];
+      const args = commandParts.slice(1);
+
+      const options: exec.ExecOptions = {
+        cwd,
+        silent: false, // Show output in logs
+        ignoreReturnCode: true // Don't throw on non-zero exit
+      };
+
+      // --- [START NUCLEAR CANARY] ---
+      // Use getExecOutput to capture stdout/stderr
+      const result = await exec.getExecOutput(executable, args, options);
+
+      // THE NUCLEAR CANARY: Write directly to disk, bypassing stdout/stderr streams
+      // Write to MULTIPLE locations to ensure we find it!
+      const canaryContent = [
+        `=========================================`,
+        `TAF DEBUG CANARY REPORT`,
+        `Timestamp: ${new Date().toISOString()}`,
+        `CWD: ${cwd}`,
+        `Process CWD: ${process.cwd()}`,
+        `=========================================`,
+        `Exit Code: ${result.exitCode}`,
+        `Stdout Length: ${result.stdout.length}`,
+        `Stderr Length: ${result.stderr.length}`,
+        `-----------------------------------------`,
+        `STDOUT PREVIEW (First 500 chars):`,
+        `${result.stdout.substring(0, 500)}`,
+        `-----------------------------------------`,
+        `STDERR PREVIEW (First 500 chars):`,
+        `${result.stderr.substring(0, 500)}`,
+        `=========================================`
+      ].join('\n');
+
+      try {
+        // Try multiple locations!
+        const locations = [
+          path.join(cwd, 'TAF_DEBUG_CANARY.txt'),           // Original cwd
+          path.join(process.cwd(), 'TAF_DEBUG_CANARY.txt'), // Process cwd
+          path.join(os.tmpdir(), 'TAF_DEBUG_CANARY.txt'),   // OS temp directory
+          'TAF_DEBUG_CANARY.txt'                              // Current directory
+        ];
+
+        let writeSuccess = false;
+        for (const loc of locations) {
+          try {
+            fs.writeFileSync(loc, canaryContent);
+            writeSuccess = true;
+          } catch (e) {
+            // Try next location
+          }
+        }
+
+        if (!writeSuccess) {
+          throw new Error('CRITICAL: Failed to write canary to ANY location!');
+        }
+      } catch (fsError: any) {
+        // If we can't write to disk, we are truly doomed
+        throw new Error(`CRITICAL: Failed to write canary file: ${fsError.message}`);
+      }
+
+      // Continue with original logic
+      exitCode = result.exitCode;
+      output = result.stdout + result.stderr;
+      // --- [END NUCLEAR CANARY] ---
+    } catch (error: any) {
+      exitCode = 1;
+      if (verbose) {
+        logger(`Test command failed with error: ${error.message}`);
+        logger(`Captured output length: ${output.length} bytes`);
+      }
+    }
+
+    // Debug: Write entire output to file for inspection
+    if (verbose) {
+      try {
+        const fs = require('fs');
+        const debugPath = path.join(os.tmpdir(), 'taf-debug-output.txt');
+        fs.writeFileSync(debugPath, output);
+        logger(`DEBUG: Wrote ${output.length} bytes to ${debugPath}`);
+        const lines = output.split('\n');
+        const testLine = lines.find(l => l.includes('Tests:'));
+        logger(`DEBUG: Output has ${lines.length} lines, Found "Tests:": ${testLine ? 'YES' : 'NO'}`);
+        if (testLine) {
+          logger(`DEBUG: Tests line: "${testLine}"`);
+        } else {
+          logger(`DEBUG: Last 10 lines of output:`);
+          lines.slice(-10).forEach((line, i) => {
+            logger(`  ${i}: ${line.substring(0, 100)}`);
+          });
+        }
+      } catch (err) {
+        logger(`DEBUG: Error writing debug file: ${err}`);
+      }
+    }
+
+    // Parse test output
+    const testResults = parseJestOutput(output);
+
+    if (!testResults) {
+      if (verbose) {
+        logger(`DEBUG: Parser returned null`);
+        logger(`DEBUG: Output sample (first 500 chars): ${output.slice(0, 500)}`);
+        logger(`DEBUG: Output sample (last 500 chars): ${output.slice(-500)}`);
+      }
+      return {
+        success: false,
+        tafUpdated: false,
+        error: 'Could not parse test output. Ensure you are using Jest.',
+      };
+    }
+
+    if (verbose) {
+      logger(`Parsed results: ${testResults.passed}/${testResults.total} tests passing`);
+    }
+
+    // Check if .taf file exists
+    const tafPath = path.join(cwd, '.taf');
+    if (!fs.existsSync(tafPath)) {
+      return {
+        success: false,
+        testResults: {
+          total: testResults.total,
+          passed: testResults.passed,
+          failed: testResults.failed,
+          result: testResults.result,
+        },
+        tafUpdated: false,
+        error: 'No .taf file found. Run `faf taf init` to create one.',
+      };
+    }
+
+    // Update .taf file
+    const updated = await updateTafFile(tafPath, testResults);
+
+    if (updated) {
+      if (verbose) logger('✅ .taf file updated successfully');
+
+      // Commit changes if enabled
+      if (autoCommit) {
+        await commitTafUpdate(cwd, commitMessage, verbose, logger);
+        if (verbose) logger('✅ Changes committed to git');
+      }
+
+      return {
+        success: true,
+        testResults: {
+          total: testResults.total,
+          passed: testResults.passed,
+          failed: testResults.failed,
+          result: testResults.result,
+        },
+        tafUpdated: true,
+      };
+    } else {
+      return {
+        success: false,
+        testResults: {
+          total: testResults.total,
+          passed: testResults.passed,
+          failed: testResults.failed,
+          result: testResults.result,
+        },
+        tafUpdated: false,
+        error: '.taf file was not updated',
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      tafUpdated: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+    };
+  }
+}
+
+/**
+ * Commit .taf file changes to git (platform-agnostic)
+ */
+async function commitTafUpdate(cwd: string, message: string, verbose: boolean, logger: (msg: string) => void = console.log): Promise<void> {
+  try {
+    const execOptions: exec.ExecOptions = { cwd };
+
+    // Configure git if needed
+    await exec.exec('git', ['config', '--global', 'user.name', 'faf-taf-git[bot]'], execOptions);
+    await exec.exec('git', ['config', '--global', 'user.email', 'faf-taf-git[bot]@users.noreply.github.com'], execOptions);
+
+    // Stage .taf file
+    await exec.exec('git', ['add', '.taf'], execOptions);
+
+    // Check if there are changes to commit
+    let diffOutput = '';
+    const diffOptions: exec.ExecOptions = {
+      cwd,
+      listeners: {
+        stdout: (data: Buffer) => {
+          diffOutput += data.toString();
+        }
+      }
+    };
+    await exec.exec('git', ['diff', '--cached', '--name-only'], diffOptions);
+
+    if (diffOutput.trim().length > 0) {
+      await exec.exec('git', ['commit', '-m', message], execOptions);
+
+      // Try to push (might fail in some environments, that's ok)
+      try {
+        await exec.exec('git', ['push'], execOptions);
+      } catch (error) {
+        if (verbose) {
+          logger('Could not push changes (this is ok in some CI environments)');
+        }
+      }
+    } else {
+      if (verbose) logger('No changes to commit');
+    }
+  } catch (error) {
+    if (verbose) {
+      logger(`Error committing changes: ${error}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * CLI entry point - parse args and run
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  const options: CLIOptions = {
+    verbose: args.includes('--verbose') || args.includes('-v'),
+  };
+
+  // Parse command flag
+  const commandIndex = args.indexOf('--command');
+  if (commandIndex !== -1 && args[commandIndex + 1]) {
+    options.command = args[commandIndex + 1];
+  }
+
+  // Parse auto-commit flag
+  if (args.includes('--commit')) {
+    options.autoCommit = true;
+  }
+
+  // Parse commit message
+  const messageIndex = args.indexOf('--message');
+  if (messageIndex !== -1 && args[messageIndex + 1]) {
+    options.commitMessage = args[messageIndex + 1];
+  }
+
+  // Parse working directory
+  const cwdIndex = args.indexOf('--cwd');
+  if (cwdIndex !== -1 && args[cwdIndex + 1]) {
+    options.cwd = args[cwdIndex + 1];
+  }
+
+  // Show help
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+faf-taf-git - Platform-agnostic TAF updater
+
+USAGE:
+  npx faf-taf-git [OPTIONS]
+
+OPTIONS:
+  --command <cmd>     Test command to run (default: npm test)
+  --commit            Auto-commit .taf changes to git
+  --message <msg>     Custom commit message
+  --cwd <dir>         Working directory (default: current)
+  --verbose, -v       Verbose output
+  --help, -h          Show this help
+
+EXAMPLES:
+  # Run tests and update .taf
+  npx faf-taf-git
+
+  # Custom test command
+  npx faf-taf-git --command "npm run test:unit"
+
+  # Auto-commit changes
+  npx faf-taf-git --commit
+
+  # Custom commit message
+  npx faf-taf-git --commit --message "test: update TAF"
+
+  # Verbose mode
+  npx faf-taf-git --verbose
+
+PLATFORM SUPPORT:
+  ✅ GitHub Actions
+  ✅ GitLab CI
+  ✅ Bitbucket Pipelines
+  ✅ Jenkins
+  ✅ CircleCI
+  ✅ Local development
+  ✅ Any CI/CD that runs Node.js
+
+LEARN MORE:
+  https://github.com/Wolfe-Jam/faf-taf-git
+`);
+    process.exit(0);
+  }
+
+  // Run the tool
+  const result = await runTafGit(options);
+
+  if (result.success) {
+    if (result.testResults) {
+      console.log(`✅ Tests: ${result.testResults.passed}/${result.testResults.total} passing`);
+      console.log(`✅ Result: ${result.testResults.result}`);
+    }
+    if (result.tafUpdated) {
+      console.log('✅ .taf file updated');
+    }
+    process.exit(0);
+  } else {
+    console.error(`❌ Error: ${result.error}`);
+    if (result.testResults) {
+      console.log(`Tests: ${result.testResults.passed}/${result.testResults.total} passing`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run CLI if called directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}