faf-cli 3.0.5 → 3.1.0

package/README.md

@@ -1,22 +1,68 @@
-# 🩵⚡️faf-cli v3.0.5 - 🏆 1st Persistent Project AI Context CLI
-Powered by Anthropic-Approved code
-and featuring New Skills.md 🎸 integration 
+# faf-cli
+
+## TL;DR
+
+**Problem:** AI needs persistent project context to work at its best.
+
+**Solution:** The .faf format provides that context. This CLI creates, scores, and improves .faf files from your codebase.
+
+**How it works:** Run `faf init` to create your .faf file. Get a score (0-100%) showing context quality. Higher scores = AI more in-tune with your project. Use `faf auto` and other commands to improve your score quickly. Align your .faf file with CLAUDE.md to maintain context persistently with bi-sync.
+
+**Install:**
+```bash
+# npm (works everywhere)
+npm install -g faf-cli
+
+# Homebrew (macOS/Linux)
+brew install faf-cli
+```
+
+**Quick start:**
+```bash
+cd your-project
+faf init        # Creates .faf file
+faf score       # Check AI-readiness (0-100%)
+```
+
+**CLI vs MCP clarity**
+- **faf-cli** (this): Runs on your machine locally in a terminal
+- **claude-faf-mcp** ([npm](https://www.npmjs.com/package/claude-faf-mcp)): Runs through Claude Desktop as a tool
+
+Same .faf, different way to use. Same Project DNA and scoring. Same capabilities (create, score, improve). Different execution layer.
+
+Use CLI for raw speed and local development; use MCP for AI-integrated workflows. No feature gaps between them - pick based on your flow.
+
+[Website](https://faf.one) | [GitHub](https://github.com/Wolfe-Jam/faf-cli) | [Discussions](https://github.com/Wolfe-Jam/faf-cli/discussions)
+
+---
+
+### 📸 See It In Action
 
 <div align="center">
+<img src="./assets/screenshots/package-json+project-faf.png" alt="project.faf sits between package.json and README.md" width="500" />
 
-<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/icons/orange-smiley.svg" alt="FAF Logo" width="64" />
+**`project.faf` sits right between `package.json` and `README.md`** - exactly where it belongs.
+
+Visible. Discoverable. Universal.
+</div>
+
+---
+
+## 📚 Complete Documentation
 
-## **FREE FOR ALL DEVS** 🆓 • **Growing Fast** 📈 • **AI-Context, On-Demand.**
+**For developers who want the full story**, here's everything about FAF's architecture, testing, and championship engineering standards.
 
-**Project DNA ✨ for Claude Code/ any AI CLI** • 
-**Zero Faff Innit™🇬🇧**
+<div align="center">
+
+<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/icons/orange-smiley.svg" alt="FAF Logo" width="64" />
+
+**Free for all devs** 🆓 • **Project DNA ✨ for any AI** • **Zero Faff™🇬🇧**
 
 [![NPM Version](https://img.shields.io/npm/v/faf-cli?color=FF4500)](https://www.npmjs.com/package/faf-cli)
 [![Downloads](https://img.shields.io/npm/dt/faf-cli?color=00CCFF)](https://www.npmjs.com/package/faf-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178C6?logo=typescript)](https://www.typescriptlang.org/)
 
-**[Website](https://faf.one)** • **[GitHub](https://github.com/Wolfe-Jam/faf-cli)** • **[Community](https://github.com/Wolfe-Jam/faf-cli/discussions)** • **[npm](https://www.npmjs.com/package/faf-cli)**
+**[Website](https://faf.one)** • **[GitHub](https://github.com/Wolfe-Jam/faf-cli)** • **[Community](https://github.com/Wolfe-Jam/faf-cli/discussions)**
 
 </div>
 
@@ -36,13 +82,181 @@ npm install -g faf-cli
 brew install faf-cli
 ```
 
-**One line. Zero config. Championship context.** 🏁
+**One line. Zero config. Podium context.** 🏁
+
+---
+
+## 🎉 What's New in v3.1.0
+
+### 🔥 THE VISIBILITY REVOLUTION 🔥
+
+**AI context just became UNIVERSAL. project.faf is here.**
+
+For too long, `.faf` lived in the shadows - hidden, invisible, forgotten. **NOT ANYMORE.**
+
+### 📂 Introducing: `project.faf`
+
+## **`package.json` for AI**
+
+**Just like `package.json` tells npm what your project needs...**
+**`project.faf` tells AI what your project IS.**
+
+| File | Purpose | Who Reads It |
+|------|---------|--------------|
+| `package.json` | Dependencies, scripts, metadata | npm, Node.js, developers |
+| `project.faf` | **Context, architecture, purpose** | **AI, Claude, Cursor, any AI tool** |
+
+**Same pattern. Same universality. Same necessity.**
+
+**VISIBLE. DISCOVERABLE. UNIVERSAL.**
+
+```bash
+# The old way (hidden like .env)
+ls -la
+.env          # 🔒 Hidden (secrets - SHOULD be hidden)
+.faf          # 👻 Hidden (AI context - SHOULD be visible!)
+
+# The NEW WAY (visible like package.json)
+ls
+package.json  # ✅ Visible (dependencies - everyone needs to see)
+project.faf   # ✅ Visible (AI context - AI needs to find this!)
+.env          # 🔒 Still hidden (secrets stay secret)
+```
+
+**`.env` hides secrets. `project.faf` shares context.**
+
+**`.faf` was hiding in the wrong category. `project.faf` fixes that.**
+
+### 🚀 Why This Changes Everything
+
+**Before:**
+- Hidden `.faf` files easily forgotten
+- Hard to discover in new projects
+- "Wait, does this project have AI context?"
+- Invisible to Git UIs, IDEs, file managers
+
+**After:**
+- `project.faf` sits next to `package.json`
+- **IMPOSSIBLE TO MISS**
+- Universal pattern developers already know
+- Every project SHOWS its AI-readiness
+
+### 🔺 The Golden Triangle
+
+**Three sides. Closed loop. Complete accountability.**
+
+```
+         project.faf
+          (WHAT IT IS)
+              /    \
+             /      \
+            /        \
+         repo    ←→   .taf
+        (CODE)    (PROOF IT WORKS)
+```
+
+Every project needs three things:
+- **Code that works** (repo)
+- **Context for AI** (project.faf)
+- **Proof it works** (.taf - git-tracked testing timeline)
+
+**TAF** (Testing Audit File) format tracks every test run in git. On-the-fly CI/CD updates. Permanent audit trail. Unheard of in CI/CD.
+
+**Traditional CI/CD:** Tests run → Results disappear → No permanent record
+**TAF:** Tests run → .taf updates → Git commits → Permanent timeline
+
+Format defined in **faf-taf-git** (GitHub Actions native support).
+
+### ✨ The Essential Trio
+
+```bash
+your-project/
+├── package.json    # What your project NEEDS (dependencies)
+├── project.faf     # What your project IS (context for AI)
+└── tsconfig.json   # How your project BUILDS (TypeScript config)
+```
+
+**`package.json`** → Tells npm: "Install these dependencies"
+**`project.faf`** → Tells AI: "This is what I am, this is my purpose"
+**`tsconfig.json`** → Tells TypeScript: "Compile with these settings"
+
+**All visible. All universal. All essential.**
+
+**You wouldn't skip `package.json`. Don't skip `project.faf`.**
+
+### 🔥 New Commands
+
+**1. `faf migrate` - Instant Upgrade**
+```bash
+faf migrate
+# .faf → project.faf (27ms)
+```
+
+**2. `faf rename` - Bulk Power**
+```bash
+faf rename
+# Recursively migrates ENTIRE monorepo tree
+# Found 147 .faf files? ✅ Migrated in 420ms
+```
+
+**3. Auto-Magic for New Projects**
+```bash
+faf init    # Creates project.faf (not .faf)
+faf auto    # Creates project.faf
+```
+
+### 🎯 Championship Detection Upgrade
+
+**TSA Engine Integration** - "We're INSPECTORS, not trash collectors"
+
+**Before (naive):**
+```
+Has 'commander' in package.json? → Maybe CLI
+```
+
+**After (championship):**
+```
+'commander' imported 10+ times? → DEFINITELY CLI
+Analyzes CORE dependencies (actual usage)
+95% accuracy vs 70% accuracy
+```
+
+### ⚡ Performance
+
+- **migrate:** 27ms (54% faster than 50ms target)
+- **rename:** 27ms for 3 files (73% faster than target)
+- **championship grade** across all operations
+
+### 🏆 WJTTC GOLD Certification
+
+**97/100 Championship Score**
+- Project Understanding: 20/20
+- TURBO-CAT Knowledge: 20/20
+- Architecture Understanding: 20/20
+
+Full report: 194KB comprehensive test suite
+
+### 🔙 100% Backward Compatible
+
+**Still works with `.faf` files** - graceful transition, no breaking changes.
+
+Your old `.faf` files keep working. Migrate when ready.
+
+### 🌍 The Vision
+
+**Every project with a `package.json` should have a `project.faf`**
+
+Just like every TypeScript project has `tsconfig.json`, every Rust project has `Cargo.toml`, every Python project has `requirements.txt`...
+
+**Every AI-augmented project has `project.faf`**
+
+**This is the new universal standard for AI context.**
 
 ---
 
 ## 🎉 What's New in v3.0.0
 
-### The Championship Release
+### The Podium Release
 
 **The biggest release yet:**
 
@@ -50,10 +264,10 @@ brew install faf-cli
 - 💨 **TURBO Model Introduced** - Like VS Code + Copilot, Spotify Free + Premium, Zoom Basic + Pro
 - 😽 **TURBO-CAT™ Format Discovery** - Introduced in v2.0.0, now purring at full power in v3.0.0 - 153 validated formats organized in a perfect pyramid
 - 🧬 **Birth DNA Lifecycle** - Track your project's evolution from birth to championship
-- 🏆 **7-Tier Championship Scoring** - 🏆 🥇 🥈 🥉 🟢 🟡 🔴 🤍 - From Lonely Heart to Podium Champion
+- 🏆 **7-Tier Podium Scoring** - 🏆 🥇 🥈 🥉 🟢 🟡 🔴 🤍 - From Lonely Heart to Podium Champion
 - ⚖️ **AI | HUMAN Balance** - 50|50 system = Optimal Context for championship performance
 - 🔗 **Context-Mirroring w/Bi-Sync** - Bidirectional .faf ↔ CLAUDE.md synchronization
-- ⚡ **Championship Speed** - 8ms bi-sync, <50ms all commands, 18ms avg, 0ms operations achieved
+- ⚡ **Podium Speed** - 8ms bi-sync, <50ms all commands, 18ms avg, 0ms operations achieved
 - 🏁 **WJTTC GOLD Certified** - 1,000+ comprehensive tests, unique test suite
 - 🤖 **BIG-3 AI Validation** - Verified by Google Gemini, Anthropic Claude, OpenAI Codex
 - 🌐 **Universal AI Support** - Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, Warp, Copilot, Windsurf, ALL AI coding assistants
@@ -155,7 +369,7 @@ faf formats
 
 ### **FAF v3.0.3 (FREE FOR ALL DEVS)** 🆓
 
-✅ **41 Championship Commands**
+✅ **41 Podium Commands**
 - Project initialization & auto-detection
 - TURBO-CAT format discovery (153 formats)
 - Birth DNA lifecycle tracking
@@ -324,7 +538,7 @@ You're gonna end up with a **CAVITY**.
 
 ### The Solution: Project DNA
 
-- ✅ **Championship context** (85-99% quality scores)
+- ✅ **Podium context** (85-99% quality scores)
 - ✅ **Persistent intelligence** - AI remembers your project perfectly
 - ✅ **Seamless collaboration** - Human + AI working together optimally
 - ✅ **Project health monitoring** - Track context quality over time
@@ -337,7 +551,7 @@ You're gonna end up with a **CAVITY**.
 
 ### 🏎️ Power Commands
 ```bash
-faf auto        # ONE COMMAND TO RULE THEM ALL - Zero to Championship
+faf auto        # ONE COMMAND TO RULE THEM ALL - Zero to Podium
 faf init        # Create .faf from your project
 faf enhance     # Real AI analysis & improvements
 faf analyze     # Claude-first intelligence
@@ -453,12 +667,12 @@ faf             # Interactive menu (use faf auto instead)
 
 ---
 
-## 🏆 Championship Scoring
+## 🏆 Podium Scoring
 
 Track your project's AI-readiness with F1-inspired tiers:
 
 ```
-🏆 Trophy (100%)    - Championship - Perfect 50|50 AI|HUMAN balance
+🏆 Trophy (100%)    - Podium - Perfect 50|50 AI|HUMAN balance
 🥇 Gold (99%)       - Gold standard
 🥈 Silver (95-98%)  - Excellence
 🥉 Bronze (85-94%)  - Production ready
@@ -481,7 +695,7 @@ Status: Bronze - Production Ready
 
 Next milestone: 95% 🥈 Silver (6 points to go!)
 
-🏎️  FAF Championship Status
+🏎️  FAF Podium Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Initial DNA: 12% (born 2025-10-03)
 Growth: +77% over 4 days
@@ -490,7 +704,7 @@ Next Milestone: 95% 🥈 Silver (6% to go!)
 
 ---
 
-## ⚖️ AI | HUMAN Balance - The 50|50 Championship System
+## ⚖️ AI | HUMAN Balance - The 50|50 Podium System
 
 **NEW in v3.0.0:** Track the perfect balance between AI-readable and human-readable content.
 
@@ -581,7 +795,7 @@ Automation:    n8n workflows, OpenAI Builder, Google Opal, Make.com - AI-Automat
 | **Cost** | Per-query fees | Zero runtime cost |
 | **Versioning** | Difficult | Git-friendly YAML |
 
-**.faf is RAG's output—captured once, reused infinitely.** Championship efficiency.
+**.faf is RAG's output—captured once, reused infinitely.** Podium efficiency.
 
 ### Universal Pattern
 
@@ -599,7 +813,7 @@ Same pattern. Same output. Universal by design.
 
 ---
 
-## 🏆 WJTTC Championship Testing
+## 🏆 WJTTC Podium Testing
 
 **FAF CLI v3.0.3 is WJTTC GOLD Certified** - tested to F1-grade standards.
 
@@ -610,7 +824,7 @@ Same pattern. Same output. Universal by design.
 
 **Battle-tested with 12,500+ test iterations across 5 testing tiers:**
 - ✅ **BIG-3 AI Validation** (11,200 iterations - Claude, ChatGPT/Codex, Gemini)
-- ✅ **287 Automated Tests** (191 Jest unit + 66 Championship Safety + 30 YOLO torture)
+- ✅ **287 Automated Tests** (191 Jest unit + 66 Podium Safety + 30 YOLO torture)
 - ✅ **730 Empirical C.O.R.E Tests** (100% MCP protocol compliance)
 - ✅ **301 Context-On-Demand Tests** (Torture testing, edge cases, stress scenarios)
 - ✅ **35+ Test Documents** (Comprehensive validation reports)
@@ -778,7 +992,7 @@ Copy cats? Why bother.
 
 <div align="center">
 
-## 🏁 v3.0.3 - Championship Edition
+## 🏁 v3.0.3 - Podium Edition
 
 **FREE FOR ALL DEVS** 🆓 • **Growing Fast** 📈 • **AI-Context, On-Demand.**
 

package/dist/big-orange/bigo-push.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BIG ORANGE 🍊 - Output Handler
+ * Pushes comparison results to Big🍊 web visualization
+ */
+import type { ComparisonResults } from './types';
+/**
+ * Push comparison results to Big🍊
+ * @param results - Comparison results to store
+ * @returns URL to view results
+ */
+export declare function pushToBigO(results: ComparisonResults): Promise<string>;
+/**
+ * Fetch session results (for Big🍊 web app)
+ * @param sessionId - Session ID to fetch
+ * @returns Comparison results
+ */
+export declare function fetchSession(sessionId: string): Promise<ComparisonResults | null>;
+//# sourceMappingURL=bigo-push.d.ts.map

package/dist/big-orange/bigo-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigo-push.d.ts","sourceRoot":"","sources":["../../src/big-orange/bigo-push.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B5E;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAYvF"}

package/dist/big-orange/bigo-push.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * BIG ORANGE 🍊 - Output Handler
+ * Pushes comparison results to Big🍊 web visualization
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushToBigO = pushToBigO;
+exports.fetchSession = fetchSession;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+/**
+ * Push comparison results to Big🍊
+ * @param results - Comparison results to store
+ * @returns URL to view results
+ */
+async function pushToBigO(results) {
+    const sessionId = results.sessionId;
+    // For now: Write to file system
+    // Later: POST to API endpoint
+    const dataDir = process.env.BIGO_DATA_DIR || '/tmp/big-orange-sessions';
+    const sessionFile = (0, path_1.join)(dataDir, `${sessionId}.json`);
+    try {
+        // Ensure directory exists
+        await (0, promises_1.mkdir)(dataDir, { recursive: true });
+        // Write session data
+        await (0, promises_1.writeFile)(sessionFile, JSON.stringify(results, null, 2), 'utf-8');
+        console.log(`✓ Session saved: ${sessionFile}`);
+    }
+    catch (error) {
+        console.error('Failed to save session:', error);
+        throw error;
+    }
+    // Return URL to Big🍊
+    const baseUrl = process.env.BIGO_URL || 'https://fafdev.tools';
+    return `${baseUrl}/BigO?session=${sessionId}`;
+}
+/**
+ * Fetch session results (for Big🍊 web app)
+ * @param sessionId - Session ID to fetch
+ * @returns Comparison results
+ */
+async function fetchSession(sessionId) {
+    const dataDir = process.env.BIGO_DATA_DIR || '/tmp/big-orange-sessions';
+    const sessionFile = (0, path_1.join)(dataDir, `${sessionId}.json`);
+    try {
+        const { readFile } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+        const data = await readFile(sessionFile, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch (error) {
+        console.error(`Session not found: ${sessionId}`);
+        return null;
+    }
+}
+//# sourceMappingURL=bigo-push.js.map

package/dist/big-orange/bigo-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigo-push.js","sourceRoot":"","sources":["../../src/big-orange/bigo-push.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWH,gCA8BC;AAOD,oCAYC;AA1DD,0CAA+C;AAC/C,+BAA4B;AAG5B;;;;GAIG;AACI,KAAK,UAAU,UAAU,CAAC,OAA0B;IACzD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAEpC,gCAAgC;IAChC,8BAA8B;IAE9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,0BAA0B,CAAC;IACxE,MAAM,WAAW,GAAG,IAAA,WAAI,EAAC,OAAO,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;IAEvD,IAAI,CAAC;QACH,0BAA0B;QAC1B,MAAM,IAAA,gBAAK,EAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1C,qBAAqB;QACrB,MAAM,IAAA,oBAAS,EACb,WAAW,EACX,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAChC,OAAO,CACR,CAAC;QAEF,OAAO,CAAC,GAAG,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAC;IAEjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QAChD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,sBAAsB;IACtB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,sBAAsB,CAAC;IAC/D,OAAO,GAAG,OAAO,iBAAiB,SAAS,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,YAAY,CAAC,SAAiB;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,0BAA0B,CAAC;IACxE,MAAM,WAAW,GAAG,IAAA,WAAI,EAAC,OAAO,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;IAEvD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,wDAAa,aAAa,GAAC,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/big-orange/compare.d.ts

@@ -0,0 +1,11 @@
+/**
+ * BIG ORANGE 🍊 - Core Comparison Logic
+ * Compares AI responses with different .faf context levels
+ */
+import type { ComparisonRequest, ComparisonResults } from './types';
+/**
+ * Compare AI responses at two different .faf scores
+ * Calls Claude API twice in parallel with different context levels
+ */
+export declare function compareContexts(request: ComparisonRequest): Promise<ComparisonResults>;
+//# sourceMappingURL=compare.d.ts.map

package/dist/big-orange/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/big-orange/compare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAiB,MAAM,SAAS,CAAC;AAOnF;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAuC5B"}

package/dist/big-orange/compare.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * BIG ORANGE 🍊 - Core Comparison Logic
+ * Compares AI responses with different .faf context levels
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareContexts = compareContexts;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const crypto_1 = require("crypto");
+const faf_generator_1 = require("./faf-generator");
+const faf_compiler_1 = require("../compiler/faf-compiler");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * Compare AI responses at two different .faf scores
+ * Calls Claude API twice in parallel with different context levels
+ */
+async function compareContexts(request) {
+    console.log(`\n🍊 Comparing ${request.leftScore}% vs ${request.rightScore}%`);
+    console.log(`Prompt: "${request.prompt}"\n`);
+    // 1. Generate .faf instances at specified scores
+    const [leftFaf, rightFaf] = await Promise.all([
+        (0, faf_generator_1.generateFafInstance)(request.leftScore, request.projectPath),
+        (0, faf_generator_1.generateFafInstance)(request.rightScore, request.projectPath)
+    ]);
+    console.log(`Generated .faf instances:`);
+    console.log(`  Left: ${request.leftScore}% (${leftFaf.content.length} chars)`);
+    console.log(`  Right: ${request.rightScore}% (${rightFaf.content.length} chars)\n`);
+    // 2. Call Claude API with both contexts
+    console.log('Calling Claude API...');
+    const client = new sdk_1.default({ apiKey: process.env.ANTHROPIC_API_KEY });
+    const [leftResponse, rightResponse] = await Promise.all([
+        callClaudeWithContext(client, request.prompt, leftFaf.content, request.leftScore),
+        callClaudeWithContext(client, request.prompt, rightFaf.content, request.rightScore)
+    ]);
+    console.log('✓ Both responses received\n');
+    // 3. Calculate delta metrics
+    const delta = calculateDelta(leftResponse, rightResponse);
+    const results = {
+        sessionId: (0, crypto_1.randomUUID)(),
+        timestamp: new Date(),
+        leftWindow: leftResponse,
+        rightWindow: rightResponse,
+        delta
+    };
+    return results;
+}
+/**
+ * Call Claude API with specific .faf context
+ * Uses FafCompiler for real scoring, no fake metrics
+ */
+async function callClaudeWithContext(client, prompt, fafContent, score) {
+    const startTime = Date.now();
+    // Build system prompt based on .faf score
+    const systemPrompt = score > 0
+        ? `You are a developer with this project context:\n\n${fafContent}\n\nUse this context to inform your response.`
+        : 'You are a developer with no project context. Ask clarifying questions as needed.';
+    try {
+        // Call Claude API
+        const response = await client.messages.create({
+            model: 'claude-sonnet-4-20250514',
+            max_tokens: 4000,
+            system: systemPrompt,
+            messages: [{
+                    role: 'user',
+                    content: prompt
+                }]
+        });
+        const timeToComplete = (Date.now() - startTime) / 1000;
+        const aiResponse = response.content[0].type === 'text'
+            ? response.content[0].text
+            : '';
+        // Get real FAF score using FafCompiler
+        const { emoji, metadata } = await scoreFafContent(fafContent, score);
+        return {
+            fafScore: score,
+            aiResponse,
+            timeToComplete,
+            emoji,
+            fafMetadata: metadata
+        };
+    }
+    catch (error) {
+        console.error(`Error calling Claude (score ${score}%):`, error);
+        throw error;
+    }
+}
+/**
+ * Score .faf content using FafCompiler
+ * Returns championship emoji and metadata
+ */
+async function scoreFafContent(fafContent, expectedScore) {
+    // Write .faf to temp file
+    const tempDir = (0, path_1.join)((0, os_1.tmpdir)(), 'big-orange-scoring');
+    (0, fs_1.mkdirSync)(tempDir, { recursive: true });
+    const tempFafPath = (0, path_1.join)(tempDir, `temp-${Date.now()}.faf`);
+    try {
+        (0, fs_1.writeFileSync)(tempFafPath, fafContent);
+        // Use FafCompiler to score
+        const compiler = new faf_compiler_1.FafCompiler();
+        const result = await compiler.compile(tempFafPath);
+        // Get championship emoji based on score
+        const emoji = getChampionshipEmoji(result.score);
+        return {
+            emoji,
+            metadata: {
+                filled: result.filled,
+                total: result.total,
+                checksum: result.checksum
+            }
+        };
+    }
+    catch (error) {
+        console.error('Error scoring .faf:', error);
+        // Fallback to expected score
+        return {
+            emoji: getChampionshipEmoji(expectedScore)
+        };
+    }
+}
+/**
+ * Get championship emoji based on score
+ * Uses FAF CLI's standard scoring tiers
+ */
+function getChampionshipEmoji(score) {
+    if (score >= 100)
+        return '🏆'; // Trophy (championship)
+    if (score >= 99)
+        return '🥇'; // Gold
+    if (score >= 95)
+        return '🥈'; // Silver (Target 2)
+    if (score >= 85)
+        return '🥉'; // Bronze (Target 1)
+    if (score >= 70)
+        return '🟢'; // Green (GO!)
+    if (score >= 55)
+        return '🟡'; // Yellow (Caution)
+    if (score >= 10)
+        return '🔴'; // Red (Pit Stop)
+    return '🤍'; // White (empty)
+}
+/**
+ * Calculate delta metrics between two responses
+ * Simple comparison: time saved and score improvement
+ */
+function calculateDelta(left, right) {
+    const timeSaved = left.timeToComplete - right.timeToComplete;
+    const scoreImprovement = right.fafScore - left.fafScore;
+    // Generate verdict
+    let verdict = '';
+    if (scoreImprovement > 0) {
+        if (timeSaved > 0) {
+            verdict = `.faf-${right.fafScore}% completed ${timeSaved.toFixed(1)}s faster with ${scoreImprovement}% better context`;
+        }
+        else {
+            verdict = `.faf-${right.fafScore}% had ${scoreImprovement}% better context`;
+        }
+    }
+    else {
+        verdict = 'Context levels comparison complete';
+    }
+    return {
+        timeSaved,
+        scoreImprovement,
+        verdict
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/big-orange/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/big-orange/compare.ts"],"names":[],"mappings":"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"}