faf 6.5.1 → 6.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +236 -12
  3. package/dist/cli.js +337 -0
  4. package/dist/cli.js.map +203 -0
  5. package/dist/index.js +7 -0
  6. package/dist/index.js.map +15 -0
  7. package/package.json +68 -8
  8. package/project.faf +39 -0
  9. package/bin/faf.js +0 -29
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 wolfejam.dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,19 +1,243 @@
1
- # faf
1
+ <!-- faf: faf-cli | TypeScript | cli | CLI for the .faf format — IANA-registered AI context that versions with your code -->
2
+ <!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->
2
3
 
3
- **Thin alias for `faf-cli`.** Same CLI, shorter name.
4
+ <div style="display: flex; align-items: center; gap: 12px;">
5
+ <img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="40" />
6
+ <div>
7
+ <h1 style="margin: 0; color: #000000;">faf-cli v6.6</h1>
8
+ <p style="margin: 2px 0 0 0; font-size: 0.85em; letter-spacing: 0.12em; opacity: 0.7; text-transform: uppercase;"><strong>The Trophy Edition</strong></p>
9
+ <p style="margin: 6px 0 0 0;"><strong>Persistent Project Context for AI.</strong></p>
10
+ <p style="margin: 0;"><strong>Define once. Run anywhere.</strong></p>
11
+ </div>
12
+ </div>
13
+
14
+ **FAF defines. MD instructs. AI codes.**
15
+
16
+ [![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-cli.svg)](https://builder.faf.one)
17
+ [![TAF](./badge.svg)](https://github.com/Wolfe-Jam/faf-taf-git)
18
+ [![CI](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml)
19
+ [![NPM Downloads](https://img.shields.io/npm/dt/faf-cli?label=total%20downloads&color=00CCFF)](https://www.npmjs.com/package/faf-cli)
20
+ [![npm version](https://img.shields.io/npm/v/faf-cli?color=00CCFF)](https://www.npmjs.com/package/faf-cli)
21
+ [![Homebrew](https://img.shields.io/badge/Homebrew-faf--cli-orange)](https://github.com/Wolfe-Jam/homebrew-faf)
22
+ [![Website](https://img.shields.io/badge/Website-faf.one-orange)](https://faf.one)
23
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
24
+ [![Built with Bun](https://img.shields.io/badge/Built_with-Bun-f9f1e1?logo=bun)](https://bun.sh)
25
+ [![project.faf](https://img.shields.io/badge/project.faf-inside-00D4D4)](https://github.com/Wolfe-Jam/faf)
26
+
27
+ ```
28
+ project/
29
+ ├── package.json ← npm reads this
30
+ ├── project.faf ← AI reads this
31
+ ├── README.md ← humans read this
32
+ └── src/
33
+ ```
34
+
35
+ > **Every building requires a foundation. FAF is AI's foundational layer.**
36
+ >
37
+ > You have a `package.json`. AI needs you to add a `project.faf`. Done.
38
+
39
+ **Git-Native.** `project.faf` versions with your code — every clone, every fork, every checkout gets full AI context. No setup, no drift, no re-explaining.
40
+
41
+ ---
42
+
43
+ ## Install
44
+
45
+ ```bash
46
+ bunx faf # Bun — zero install, fastest path
47
+ npx faf # npm — works everywhere
48
+ brew install faf-cli && faf # Homebrew
49
+ ```
50
+
51
+ > `faf` is shorthand for `faf-cli auto` — same behavior, fewer keystrokes.
52
+
53
+ ---
54
+
55
+ ## Nelly Never Forgets
56
+
57
+ Run `faf` with no arguments:
58
+
59
+ ![faf](./nelly.png)
60
+
61
+ ---
62
+
63
+ ## v6.6 — The Trophy Edition
64
+
65
+ Until now we have had 85% as a recommended minimum. **It's now 100%! 🏆 All or nothing.**
66
+
67
+ AI gets its best shot at assisting you. **Period.**
68
+
69
+ We are able to do this because we can now get you to 100% on virtually any app-type.
70
+
71
+ **FAF Init > Auto > Go = 100%.**
72
+
73
+ `faf sync` locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.
74
+
75
+ (Adding `about` — the 20th app-type — made the ladder hit a score. *How no-score became a score.* Fitting, because v6.6 is when that score became the only one we recommend.)
76
+
77
+ Receipts → [CHANGELOG](./CHANGELOG.md)
78
+
79
+ ---
80
+
81
+ ## v6.0 — Built with Bun
82
+
83
+ v6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.
84
+
85
+ | | Claude Code | faf-cli v6 |
86
+ |-|-------------|------------|
87
+ | **Runtime** | Bun | Bun (`bunx`) |
88
+ | **Test** | Bun | `bun test` |
89
+ | **Build** | Bun | `bun build` |
90
+ | **Language** | TypeScript | TypeScript |
91
+ | **Compile** | Bun bytecode | `bun build --compile` |
92
+
93
+ 408 tests in ~13s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.
94
+
95
+ 26 commands. 408 tests. WJTTC-tested. 93% smaller than v5.
96
+
97
+ ```
98
+ commands → interop → core → wasm
99
+ ```
100
+
101
+ The WASM scoring kernel (`faf-scoring-kernel` 2.0.0) does the math. Bun does the delivery.
102
+
103
+ ---
104
+
105
+ ## Commands
106
+
107
+ | # | Command | One-liner |
108
+ |---|---------|-----------|
109
+ | 1 | `faf init` | Create `.faf` from your local project |
110
+ | 2 | `faf git <url>` | Instant `.faf` from any GitHub repo — no clone |
111
+ | 3 | `faf auto` | Zero to 100% in one command |
112
+ | 4 | `faf go` | Guided interview to gold code |
113
+ | 5 | `faf score` | Check AI-readiness (0-100%) |
114
+ | 6 | `faf sync` | `.faf` ↔ CLAUDE.md (bi-sync, mtime auto-direction) |
115
+ | 7 | `faf compile` | `.faf` → `.fafb` binary — sealed, portable, deterministic |
116
+ | 8 | `faf decompile` | `.fafb` → JSON |
117
+ | 9 | `faf export` | Generate AGENTS.md, .cursorrules, GEMINI.md |
118
+ | 10 | `faf check` | Validate `.faf` file |
119
+ | 11 | `faf edit` | Edit `.faf` fields inline |
120
+ | 12 | `faf convert` | Convert `.faf` to JSON |
121
+ | 13 | `faf drift` | Check context drift |
122
+ | 14 | `faf context` | Generate context output |
123
+ | 15 | `faf recover` | Recover `.faf` from CLAUDE.md / AGENTS.md |
124
+ | 16 | `faf migrate` | Migrate `.faf` to latest version |
125
+ | 17 | `faf search` | Search slots and formats |
126
+ | 18 | `faf share` | Share `.faf` via URL |
127
+ | 19 | `faf taf` | Generate TAF test receipt |
128
+ | 20 | `faf demo` | Demo walkthrough |
129
+ | 21 | `faf ai` | AI-powered enhance & analyze |
130
+ | 22 | `faf pro` | Pro features & licensing |
131
+ | 23 | `faf conductor` | Conductor integration |
132
+ | 24 | `faf formats` | Show supported formats |
133
+ | 25 | `faf info` | Version and system info |
134
+ | 26 | `faf clear` | Clear cached data |
135
+
136
+ Run `faf --help` for full options.
137
+
138
+ ---
139
+
140
+ ## Quick Start
141
+
142
+ ```bash
143
+ # ANY GitHub repo — no clone, no install, 2 seconds
144
+ bunx faf-cli git https://github.com/facebook/react
145
+
146
+ # Your own project
147
+ bunx faf-cli init # Create .faf
148
+ bunx faf-cli auto # Zero to 100% in one command
149
+ bunx faf-cli go # Interactive interview to gold code
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Scoring
155
+
156
+ **🏆 Trophy 100% — all or nothing.** From v6.6.0 onward, faf-cli recommends only Trophy. 100% on the FCL is what makes the layers above (MD instructions, Agents, AI tooling) work — sub-Trophy leaves gaps that AI guesses on. Sub-Trophy tiers are honest interim states on the way to Trophy, not endpoints.
157
+
158
+ | Tier | Score | Status |
159
+ |------|-------|--------|
160
+ | 🏆 **Trophy** | 100% | AI never has to guess |
161
+ | ★ **Gold** | 99%+ | 1 slot from Trophy |
162
+ | ◆ **Silver** | 95%+ | Close — keep going |
163
+ | ◇ **Bronze** | 85%+ | Interim — keep going |
164
+ | ● **Green** | 70%+ | Interim — keep going |
165
+ | ● **Yellow** | 55%+ | AI flipping coins |
166
+ | ○ **Red** | <55% | AI working blind |
167
+ | ♡ **White** | 0% | No context at all |
168
+
169
+ ---
170
+
171
+ ## Sync
172
+
173
+ ```
174
+ bi-sync: .faf ←── 8ms ──→ CLAUDE.md (free forever)
175
+ tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md (Pro)
176
+ ```
177
+
178
+ ---
179
+
180
+ ## Compiled Binaries
181
+
182
+ Bun's single-file compiler produces standalone binaries — no runtime needed.
183
+
184
+ ```bash
185
+ bun run compile # Current platform
186
+ bun run compile:all # darwin-arm64, darwin-x64, linux-x64, windows-x64
187
+ ```
188
+
189
+ Ship `faf` as a single binary for CI/CD, Docker, or air-gapped environments.
190
+
191
+ ---
192
+
193
+ ## Architecture
194
+
195
+ ```
196
+ src/
197
+ ├── cli.ts ← Entry point, 26 command registrations
198
+ ├── commands/ ← 26 command files (1 per command)
199
+ ├── core/ ← Types, slots (33 Mk4), tiers, scorer, schema
200
+ ├── detect/ ← Framework detection, stack scanner
201
+ ├── interop/ ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
202
+ ├── ui/ ← Colors (#00D4D4), display
203
+ └── wasm/ ← faf-scoring-kernel wrapper (Rust → WASM)
204
+ ```
205
+
206
+ **Toolchain:** Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)
207
+
208
+ ---
209
+
210
+ ## Testing
211
+
212
+ > **Robust. Reliable. Next-level WJTTC tested.** — The Foundation Edition.
4
213
 
5
214
  ```bash
6
- bunx faf init
7
- bunx faf auto
8
- bunx faf go
9
- bunx faf wjttc
215
+ bun test # 408 tests, 42 files, ~13s
10
216
  ```
11
217
 
12
- This package resolves [`faf-cli`](https://npmjs.com/package/faf-cli) at install time and forwards args through. All docs, all commands, all features live in the canonical CLI.
218
+ - **WJTTC Build Resilience** (13) — every regression class locked.
219
+ - **WJTTC Kernel Stress** (19) — WASM kernel boundary tests.
220
+ - **e2e lifecycle** — every command in sequence.
221
+
222
+ Test reports in `reports/`.
223
+
224
+ ---
225
+
226
+ ## Support
227
+
228
+ - **[GitHub Discussions](https://github.com/Wolfe-Jam/faf-cli/discussions)** — Questions, ideas, community
229
+ - **Email:** team@faf.one
230
+
231
+ ---
232
+
233
+ If `faf-cli` has been useful, consider starring the repo — it helps others find it.
234
+
235
+ ---
236
+
237
+ ## License
238
+
239
+ MIT — Free and open source
13
240
 
14
- - **Canonical CLI:** https://npmjs.com/package/faf-cli
15
- - **Spec:** https://faf.one
16
- - **Issues:** https://github.com/Wolfe-Jam/faf-cli/issues
17
- - **Format:** IANA-registered `application/vnd.faf+yaml`
241
+ **IANA-registered:** [`application/vnd.faf+yaml`](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
18
242
 
19
- > FAF defines. MD instructs. AI codes.
243
+ *format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)*