faf-cli 2.4.21 → 2.5.1

package/README.md

@@ -1,156 +1,174 @@
-# 🩵⚡️ faf-cli | .faf - Project DNA for ANY AI✨
+# faf-cli v2.5.0
 
-## Sonnet 4.5 hits 100% 🧡 New ASCII Art too⚡️🏁
-
-![FAF Championship Banner](https://raw.githubusercontent.com/Wolfe-Jam/faf/main/cli/faf-banner.png)
-
-> **💎 See it live in your terminal:** `faf version`
+<div align="center">
 
-## AI|HUMAN Balance is here 🧡⚡️🩵 50|50
+<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/icons/orange-smiley.svg" alt="Orange Smiley" width="48" />
 
-See the balance between AI-detected tech and your human context:
+**Project DNA ✨ for ANY AI** • **Context-Mirroring** • **Sub-20ms Sync**
 
-```bash
-⚖️ Balance: AI:75% | HUMAN:25%
-```
+[![NPM Version](https://img.shields.io/npm/v/faf-cli)](https://www.npmjs.com/package/faf-cli)
+[![Downloads](https://img.shields.io/npm/dt/faf-cli)](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%20Strict-3178C6?logo=typescript)](https://www.typescriptlang.org/)
 
-Add Project Details for AI to reach championship 50|50 balance! 🏆
+**[Website](https://faf.one)** • **[Community](https://github.com/Wolfe-Jam/faf/discussions)** • **[Issues](https://github.com/Wolfe-Jam/faf/issues)**
 
-### 💥 Also New:
-  **⚡ 60% FASTER** - Lightning-quick operations
-  **🏎️ NATIVE PERFORMANCE** - Built/Installed New engine, championship grade
-  **🎨 ZERO DISPLAY BUGS** - Perfect terminal rendering
-  **💾 LEAN & FAST** - Optimized for speed
-  **✨ 100% BACKWARDS COMPATIBLE** - Same commands, MORE SPEED!
-
-  FAST, LEAN, CHAMPIONSHIP GRADE! 🏆
-
-NEW for AI assistants (Codex, Cursor, Copilot, etc.): install locally with `npm install -g faf-cli`, confirm with `faf --version`, and default to quiet mode (`-q` / `--quiet`) for every command.
+</div>
 
-<div align="center">
+---
 
-## Transform Any Project into Perfect AI Context in 30 Seconds
+![FAF Championship Banner](https://cdn.jsdelivr.net/npm/faf-cli@latest/faf-banner.png)
 
-**3000+ Downloads** • **100% FREE Forever** • **Works with ALL AI Tools**
+---
 
-**[💬 Join Our Community](https://github.com/Wolfe-Jam/faf/discussions)** • **[⭐ Star on GitHub](https://github.com/Wolfe-Jam/faf)** • **[🐛 Report Issues](https://github.com/Wolfe-Jam/faf/issues)**
+## 🚀 What's New in v2.5.0
 
-</div>
+### Context-Mirroring: Bidirectional Sync in Sub-20ms
 
-## 🚀 What is .faf?
+**The Breakthrough:** Keep `.faf` (structured data) and `CLAUDE.md` (human-readable) in perfect sync automatically.
 
-**.faf = Project DNA for ANY AI✨ [Foundational AI-context Format]**
+```bash
+# Edit either file, both stay synchronized
+faf bi-sync
+
+# Result: 15ms average sync, zero data loss
+🔗 C-MIRROR LIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+└─ 🎉 Synchronized in ~17ms 🏎️
+✅ Integrity: PERFECT
+```
 
-Universal, shareable AI-Context for any AI, human or team, regardless of size, location, languages, stack, setup or documentation.
+**Key Features:**
+- **15ms average** sync (95% under 50ms)
+- **Bidirectional**: `.faf` → `CLAUDE.md` → `.faf`
+- **Zero-slippage**: Atomic file operations guarantee
+- **Cross-platform**: Mac + Windows tested (20/20 tests)
+- **Universal**: Works with Claude, Gemini, Cursor, all AI tools
 
-Add a .faf file to your repo and watch Claude, Codex, Gemini, or any AI tool understand your entire codebase with speed and precision.
+**C-Mirror Stack:**
+1. **Context-Mirroring** - The standard (industry-level concept)
+2. **C-Mirror** - The engine (FAF's implementation)
+3. **`faf bi-sync`** - The command (what you type)
 
-**Join our growing community of 3000+ developers who save hours daily by using .faf files!**
+---
 
-<div align="center">
-<img src="https://faf.one/orange-smiley.svg" alt="Orange Smiley Logo" width="150" />
+## 🏆 Championship Scoring System
 
-### 💬 Community-Driven • Open Source • Built by Developers, for Developers
+Track your project's AI-readiness with F1-inspired tiers:
 
-[![NPM Downloads](https://img.shields.io/npm/dw/faf-cli)](https://www.npmjs.com/package/faf-cli)
-[![GitHub Stars](https://img.shields.io/github/stars/Wolfe-Jam/faf)](https://github.com/Wolfe-Jam/faf)
-[![Discussions](https://img.shields.io/badge/Discussions-Join%20Community-7289DA)](https://github.com/Wolfe-Jam/faf/discussions)
+```
+🏆 Trophy (100%)    - Championship - Perfect 50|50 AI|HUMAN balance
+🥇 Gold (99%)       - Gold standard
+🥈 Silver (95-98%)  - Excellence
+🥉 Bronze (85-94%)  - Production ready
+🟢 Green (70-84%)   - Good foundation
+🟡 Yellow (55-69%)  - Getting there
+🔴 Red (0-54%)      - Needs attention
+```
 
-</div>
+**Live output in your terminal:**
 
-## 🎯 Why Developers Love .faf
+```
+🏎️ FAF Status
+━━━━━━━━━━━━
+Score: 85% 🥉 Bronze
+⚖️  Balance: AI:75% | HUMAN:25%
 
-### The Problem:
-- ❌ Spending 20+ minutes explaining your project to AI
-- ❌ AI gives wrong answers because it doesn't understand your codebase
-- ❌ Copying and pasting files manually into ChatGPT/AI assistants
-- ❌ AI forgets context between sessions/doesn't know your setup properly
+Next: 95% 🥈 Silver (10% to go!)
+Add Project Details to reach 50|50 balance! 🏆
+```
 
-### The Solution:
-- ✅ **One command** creates perfect AI context
-- ✅ **30 seconds** to complete AI understanding
-- ✅ **Works everywhere** - Claude, ChatGPT, Gemini, Cursor, any AI
-- ✅ **Share context** with your team instantly
+---
 
-## 🚀 Getting Started (30 Seconds!)
+## 🚀 Quick Start
 
-### ⚡️💥 GET BOTH! Double Down! (100% FREE)
 ```bash
-# Install BOTH for maximum power - completely FREE!
-npm install -g faf-cli           # 🩵 Cyan CLI - Command Line Tool
-npm install -g claude-faf-mcp    # 🧡 Orange Smiley MCP - Claude Desktop integration
+# Install globally
+npm install -g faf-cli
 
-# Try it now!
+# Initialize in any project
 cd your-project
 faf init
+
+# Auto-detect and score
+faf auto
+faf score
+
+# Sync with CLAUDE.md (NEW in v2.5.0!)
+faf bi-sync
 ```
 
-Done! Your AI now understands your project 99% better! 🏁
+Your AI now understands your project! 🏁
 
-### 🤖 Codex CLI Quickstart (AI Assistants)
-1. Install with user approval when required: `npm install -g faf-cli`
-2. Verify availability right away: `faf --version`
-3. Run every command in quiet mode to suppress banners: `faf init -q`, `faf auto -q`, `faf score -q`
-4. Pause for approval before any network or write action in sandboxed sessions
-5. Summarize the key results instead of dumping raw output for the user
+---
 
-## 🌟 Join Our Growing Community!
+## 🎯 What is faf-cli?
 
-### 💬 New Community Hub at [github.com/Wolfe-Jam/faf/discussions](https://github.com/Wolfe-Jam/faf/discussions)
+Command-line tool that creates `.faf` files for instant AI project understanding.
 
-Connect with 2000+ developers using .faf to accelerate their AI workflows:
-- **Share your projects** - Show what you're building with .faf
-- **Get help** - Community support for any questions
-- **Request features** - Help shape the future of .faf
-- **Learn best practices** - Tips from experienced users
+**.faf = Project DNA ✨ for ANY AI**
+Universal, shareable context for Claude, ChatGPT, Gemini, Cursor - regardless of stack, size, or setup.
 
-## ⚡ Key Features
+### Why Developers Love It
 
-### For Developers
-- **Universal Compatibility** - Works with Claude, ChatGPT, Gemini, Cursor, and more
-- **30-Second Setup** - Run `faf init` in your project directory and you're done
-- **Smart Auto-Detection** - Automatically identifies your tech stack
-- **Real-Time Scoring** - Instantly see your AI-readiness score
-- **100% Free & Open Source** - No hidden costs, ever
+**The Problem:**
+- ❌ 20+ minutes explaining projects to AI
+- ❌ AI gives wrong answers without context
+- ❌ Manual copy/paste into chat interfaces
+- ❌ Context lost between sessions
 
-### Technical Excellence
-- **Performance** - <50ms operations, rigorously benchmarked
-- **Reliability** - Extensively tested including edge cases and stress scenarios
-- **Type Safety** - 100% TypeScript with strict mode enforcement
-- **Security** - Minimal dependencies, fully audited codebase
-- **Production Ready** - Zero-error tolerance with comprehensive error handling
+**The Solution:**
+- ✅ One command creates perfect context
+- ✅ 30 seconds to complete understanding
+- ✅ Works with every AI tool
+- ✅ Share context with your team instantly
+- ✅ **NEW:** Bidirectional sync keeps everything in harmony
 
-## 💬 Join Our Community
+### Key Features
 
-**We're building .faf together with our community!**
+- ✅ **Universal** - Works with all AI tools
+- ✅ **Fast** - <50ms operations, sub-20ms sync
+- ✅ **Smart** - Auto-detects your tech stack
+- ✅ **Simple** - One command setup
+- ✅ **Bidirectional** - Edit .faf or CLAUDE.md, both update
+- ✅ **Free** - 100% open source, forever
 
-- 🌟 **[Star us on GitHub](https://github.com/Wolfe-Jam/faf)** - If you find it helpful!
-- 💬 **[Join Discussions](https://github.com/Wolfe-Jam/faf/discussions)** - Share ideas, get help, show your projects
-- 🐛 **[Report Issues](https://github.com/Wolfe-Jam/faf/issues)** - Help us improve
-- 📖 **[Read the Docs](https://faf.one/docs)** - Complete guides and tutorials
-- 🤝 **[Contribute](https://github.com/Wolfe-Jam/faf/blob/main/CONTRIBUTING.md)** - PRs welcome!
+---
 
 ## 🛠️ Available Commands
 
 ### Core Commands
-- `faf init` - Initialize .faf context
-- `faf auto` - Auto-detect and generate
-- `faf score` - Calculate AI readiness score
-- `faf quick` - Quick mode with comma-separated values
-- `faf index` - Universal A-Z reference of all commands and concepts
+- `faf init` - Initialize project context
+- `faf auto` - Auto-detect and populate
+- `faf score` - Calculate AI readiness
+- `faf status` - Project health check
+- `faf quick "app, react, vercel"` - Quick setup
+
+### Context-Mirroring (NEW in v2.5.0)
+- `faf bi-sync` - **Bidirectional sync** (.faf ↔ CLAUDE.md)
+  - 15ms average performance
+  - Zero data loss guarantee
+  - Edit either file, both update
+  - Cross-platform verified
 
 ### Enhancement Commands
-- `faf enhance` - Optimized scoring system
-- `faf sync` - Sync .faf with CLAUDE.md
-- `faf bi-sync` - Bidirectional sync
+- `faf enhance` - Optimize scoring
+- `faf sync` - Sync with CLAUDE.md (one-way)
 
 ### Management Commands
-- `faf trust` - Validate context integrity
-- `faf doctor` - Diagnose and fix issues
-- `faf welcome` - First-time user guide
+- `faf trust` - Validate integrity
+- `faf doctor` - Diagnose issues
 - `faf clear` - Clear caches
+- `faf index` - A-Z command reference
+
+### Utility Commands
+- `faf version` - Show version (with ASCII art!)
+- `faf welcome` - First-time guide
+- `faf help` - Command help
+
+---
 
-## 📖 Usage Examples
+## 💡 Usage Examples
 
 ```bash
 # Quick setup for new project
@@ -159,72 +177,169 @@ faf quick "my-app, react, typescript, vercel"
 # Auto-detect existing project
 faf auto
 
-# Check your score
+# Check your score with details
 faf score --details
 
+# See current status
+faf status
+
+# NEW: Bidirectional sync with CLAUDE.md
+faf bi-sync
+
 # Fix any issues
 faf doctor
 
 # Optimize scoring
 faf enhance
+
+# Quiet mode (for AI assistants)
+faf init -q
+faf auto -q
 ```
 
-## 📊 Real Metrics
+---
+
+## 🎉 Version History
+
+### v2.5.0 (October 3rd, 2025) - Context-Mirroring Release
+- **Context-Mirroring engine** - Bidirectional .faf ↔ CLAUDE.md sync
+- **C-Mirror** - Championship-grade sync in 15ms average
+- **Zero-slippage guarantee** - Atomic file operations
+- **Cross-platform verified** - Mac + Windows tested
+- **20/20 test suite** - All edge cases conquered
+- **Event-driven architecture** - Power Chords system
+- **TypeScript strict mode** - 100% type safety
+
+### v2.4.6 - Performance Championship
+- **60% faster** operations across all commands
+- **Native engine** - Championship-grade performance
+- **Zero display bugs** - Perfect terminal rendering
+- **100% backwards compatible** - Same commands, more speed
+
+### v2.4 Highlights
+- **AI|HUMAN Balance** - Track 50|50 balance for championship
+- **Enhanced auto-detection** - Smarter tech stack recognition
+- **Improved scoring** - More accurate AI-readiness metrics
+
+---
+
+## 📊 Technical Specs
 
 ```
-📈 Status: PRODUCTION
-├─ 💎 Production Ready
-├─ 🚀 Performance: <50ms
-├─ 📦 Dependencies: 2 (MINIMAL!)
-├─ 🧪 Tests Passed: 100%
-└─ 🏆 AI Readiness: 100% target
+Version:       2.5.0
+Performance:   Sub-20ms sync (15ms average)
+C-Mirror:      95% of operations under 50ms
+TypeScript:    100% strict mode
+Dependencies:  2 (inquirer, yaml)
+Tests:         100% passing (20/20 C-Mirror suite)
+Build:         Zero errors
+Platform:      Mac, Linux, Windows
 ```
 
-## 🏁 Development
+---
+
+## 🔬 Context-Mirroring Technical Details
+
+### Architecture
+- **Event-driven**: Power Chords broadcast at lowest level
+- **Atomic operations**: Write → Validate → Commit pattern
+- **Bidirectional intelligence**: Preserves technical fields during sync
+- **Format-agnostic**: Works with any Tool.md format
+- **Self-healing**: Automatic backup and recovery
+
+### Performance
+- **Average**: 15ms per sync operation
+- **95th percentile**: Under 50ms
+- **Worst case**: <110ms (complex validation)
+- **Target achieved**: Context-On-Demand (<20ms)
+
+### Testing
+- **20/20 test suite** passed (WJTC certified)
+- **Edge cases conquered**: Emoji, Unicode, nested quotes, Windows paths
+- **Round-trip verified**: Perfect data preservation
+- **Cross-platform**: Mac + PC tested
+
+---
+
+## 🤖 For AI Assistants (Codex, Cursor, Copilot)
+
+When using faf-cli programmatically:
+
+1. Install with user approval: `npm install -g faf-cli`
+2. Verify: `faf --version`
+3. Use quiet mode: `faf init -q`, `faf auto -q`, `faf score -q`
+4. Use `faf bi-sync` for CLAUDE.md synchronization
+5. Request approval before network/write operations
+6. Summarize results instead of raw output
+
+---
+
+## 🏗️ Development
 
 ```bash
-# Clone repo
+# Clone
 git clone https://github.com/Wolfe-Jam/faf.git
 cd faf/cli
 
-# Install & build
+# Install & Build
 npm install
 npm run build
 
 # Test
 npm test
+
+# Test C-Mirror specifically
+npm run test -- tests/c-mirror/
+
+# Link locally
+npm link
 ```
 
+---
+
 ## 📋 Requirements
 
-- Node.js 18+
-- macOS, Linux, or Windows
-- Any AI tool (Claude, ChatGPT, Gemini, etc.)
+- **Node.js** 18+
+- **OS**: macOS, Linux, or Windows
+- **AI Tools**: Works with Claude, ChatGPT, Gemini, Cursor, etc.
+
+---
+
+## 🔗 The FAF Ecosystem
 
-## 🔗 Links
+- [🩵 **faf-cli**](https://npmjs.com/package/faf-cli) - This command-line tool
+- [🧡 **claude-faf-mcp**](https://npmjs.com/package/claude-faf-mcp) - MCP server for Claude Desktop
+- [💚 **faf.one**](https://faf.one) - Documentation & guides
+- [🖥️ **Chrome Extension**](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm) - Browser integration
 
-- **NPM**: [faf-cli](https://www.npmjs.com/package/faf-cli)
-- **Website**: [faf.one](https://faf.one)
-- **GitHub**: [Wolfe-Jam/faf](https://github.com/Wolfe-Jam/faf)
-- **Community**: [Join Discussions](https://github.com/Wolfe-Jam/faf/discussions)
-- **Support**: support@faf.one
+---
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - See [LICENSE](./LICENSE) file
 
-**Note**: The .faf-Engine(s) are proprietary and available under license.
+**Note**: C-Mirror core is open source. FAF-specific extensions available under separate license.
 
 ---
 
-## ⚡️💥 The Complete FAF Ecosystem
+## 🤝 Contributing
 
-[🩵 Cyan CLI](https://npmjs.com/package/faf-cli) • [🧡 Orange Smiley MCP](https://npmjs.com/package/claude-faf-mcp) • [💚 WEB](https://faf.one) • [🧰 DevOps](https://fafdev.tools) • [🖥️ Chrome](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm)
+We welcome contributions! Join our [community discussions](https://github.com/Wolfe-Jam/faf/discussions) or submit issues/PRs.
 
-**🏎️⚡️ FAST AF - Project DNA for ANY AI ✨**
+**Connect with 3000+ developers** using .faf to accelerate their AI workflows:
+- Share your projects
+- Get help from the community
+- Request features
+- Learn best practices
 
 ---
 
-**Made with 🧡 by wolfejam** | **3000+ Weekly Downloads** | **Growing Community** 🎉
+<div align="center">
+
+**Made with 🧡 by wolfejam**
+
+**100% FREE Forever** • **3000+ Weekly Downloads** • **Zero Faff™**
 
-**100% FREE Forever** • **No Strings Attached** • **Just Build Faster with AI**
+[⭐ Star on GitHub](https://github.com/Wolfe-Jam/faf) • [📦 View on NPM](https://www.npmjs.com/package/faf-cli)
+
+</div>

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AA8zC/C,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAg0C/C,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -140,8 +140,8 @@ function withAnalyticsTracking(commandName, fn) {
             const result = await fn(...args);
             const duration = Date.now() - start;
             await (0, analytics_1.trackCommand)(commandName, commandArgs, duration, true);
-            // Show score footer after every command
-            await showScoreFooter('device');
+            // DEPRECATED: Old score footer removed - conflicts with new compiler scores
+            // await showScoreFooter('device');
             return result;
         }
         catch (error) {
@@ -158,14 +158,14 @@ function showHeaderIfAppropriate(commandName) {
     if (opts.quiet) {
         return; // Skip header in quiet mode
     }
-    const showHeaderCommands = ['help', 'init', 'clear', 'enhance', 'analyze', 'chat', 'formats', 'score', 'version'];
+    const showHeaderCommands = ['help', 'clear', 'enhance', 'analyze', 'chat', 'formats', 'version'];
     if (!commandName || showHeaderCommands.includes(commandName)) {
         console.log((0, championship_style_1.generateFAFHeader)());
     }
 }
 commander_1.program
     .name('faf')
-    .description('.faf = Project DNA for ANY AI✨ | Foundational AI-context Format | SPEEDY AI you can TRUST! 🧡⚡️')
+    .description('.faf = Project DNA ✨ for ANY AI | Foundational AI-context Format | SPEEDY AI you can TRUST! 🧡⚡️')
     .version(version)
     .option('--no-color', 'Disable colored output for accessibility')
     .option('--color-scheme <scheme>', 'Color scheme for colorblind accessibility: normal|deuteranopia|protanopia|tritanopia', 'normal')
@@ -1073,7 +1073,8 @@ async function showInteractiveWelcome() {
     console.log(colors_1.chalk.white('  Ready to make your AI happy again?'));
     console.log('');
     // Footer - show BEFORE menu
-    await showScoreFooter();
+    // DEPRECATED: Old score footer removed
+    // await showScoreFooter();
     console.log('');
     try {
         const answer = await inquirer_1.default.prompt([
@@ -1217,7 +1218,8 @@ async function showInteractiveWelcome() {
                 }
                 // Show footer after each command (unless it was help which shows its own footer)
                 if (command !== 'help' && command !== '') {
-                    await showScoreFooter('faf');
+                    // DEPRECATED: Old score footer removed
+                    // await showScoreFooter('faf');
                 }
                 console.log('');
             }