🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

faf-cli

Package Overview
Dependencies
Maintainers
1
Versions
158
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

faf-cli - npm Package Compare versions

Comparing version
7.1.3
 to
7.1.4
+3
-2
package.json
{
"name": "faf-cli",
"version": "7.1.3",
"version": "7.1.4",
"description": "Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.",

@@ -79,6 +79,7 @@ "type": "module",

"@faf/specification": "github:Wolfe-Jam/faf",
"ajv": "^8.17.1",
"@types/bun": "^1.3.14",
"@types/node": "^22.15.0",
"@typescript-eslint/eslint-plugin": "^8.41.0",
"@typescript-eslint/parser": "^8.41.0",
"ajv": "^8.17.1",
"eslint": "^9.39.2",

@@ -85,0 +86,0 @@ "prettier": "^3.2.5",

+76
-265
README.md

@@ -6,8 +6,8 @@ <!-- faf: faf-cli | TypeScript | cli | CLI for the .faf and .fafm IANA-registered formats — AI context + memory that versions with your code -->

**CONTEXT, versioned.**
<h1>
<img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="72" /><br>
faf-cli<br>
<sub><sub>CONTEXT, versioned.</sub></sub>
</h1>
<img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="72" />
# faf-cli
### The context every AI coding agent reads — authored from your repo, never guessed.

@@ -25,6 +25,7 @@

<br>
**115,000+ downloads across the FAF ecosystem · IANA-registered · Anthropic-merged (#2759)**
⭐ **If faf-cli saves you setup time, a star helps other devs find it** —<br>
despite all our downloads, ~3 of 4 developers check stars before adopting.
⭐ **A star helps other devs find faf-cli** — despite the downloads, ~3 of 4 devs check stars.

@@ -38,3 +39,3 @@ <!-- ② papers · funnel · testing — one line -->

**[faf.one/cli](https://faf.one/cli)** · FAF defines. MD instructs. AI codes.
FAF defines. MD instructs. AI codes.

@@ -75,267 +76,54 @@ <!-- trophy — bottom of hero -->

## Nelly Never Forgets
## Quick Start
Run `faf` with no arguments:
![faf](./nelly.png)
---
## v7.1 — The AGENTS.md Edition
**`faf export --agents` now authors a complete, best-in-class AGENTS.md for any repo — detected from your code, non-destructive, never stale.**
Point it at any repo and it detects your build/test commands, key files, conventions (ESLint/Prettier/strict/ruff/mypy…), and guardrails — then writes the definitive AGENTS.md: orientation, setup, tests, where-things-live, conventions, three-tier guardrails, a Definition of Done composed from your real commands, and secrets handling. Facts, not bloat. Your hand-written content is preserved.
```bash
npx faf-cli export --agents
```
# ANY GitHub repo — no clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react
---
## Context for AI agents
FAF-CLI authors the files agents read (AGENTS.md, CLAUDE.md, .cursorrules) from real project detection — zero-install via `bunx faf`.
- [→ FAF-CLI for Grok, xAI & Cursor 👀](docs/faf-cli-for-agents.md)
- [→ FAF-CLI for Claude Code 👀](docs/faf-cli-for-claude.md)
- [→ FAF-CLI for Bun 👀](docs/faf-cli-for-bun.md)
## v7.0 — The GIT Version
**FAF is to Context what Git is to Versions.**
Git gave your *code* diff, log, blame, hooks, CI. v7.0 gives your *context* the same — `project.faf` is now a git-native artifact:
- **`faf diff`** — semantic context diff + score delta between any two refs (`85% ● → 100% 🏆`)
- **`git diff` speaks .faf** — `faf diff --install-driver` makes native `git diff` / `log -p` / `show` render the delta
- **`faf log`** — the score timeline across history (Proof-Over-Time)
- **`faf hooks --install`** — pre-commit guard: warn, or `--strict` block, on a context regression
- **`faf git owner/repo --ref <tag>`** — instant, *versioned*, scored context from any repo
Purely additive — a safe upgrade. (One change: `faf git` now refuses to overwrite an existing `project.faf` — pass `--force`.)
## v6.16 — Know Your Stack
**FAF knows your stack — and now labels it identically in every file it writes: CLAUDE.md, AGENTS.md, copilot-instructions.md, GEMINI.md, .cursorrules.**
```bash
faf export --all # CLAUDE.md · AGENTS.md · copilot-instructions.md · GEMINI.md · .cursorrules
# Your own project
bunx faf-cli init # Create .faf
bunx faf-cli auto # Zero to 100% in one command
bunx faf-cli go # Interactive interview to gold code
```
FAF *knows your stack* — all 33 canonical slots now carry their display label in the registry, so `api_type` → **API**, `cicd` → **CI/CD**, `frontend` → **Framework**, the same way in **every** emitted file. GEMINI.md and `.cursorrules` were raw-key dumps; now they read like the rest. And `.github/copilot-instructions.md` gets a ground-up **Copilot-grade** rewrite — a prose overview, a `## Build & run` command section, GitHub-spec framing. Copilot enhancements, and more.
---
## v6.15 — The Copilot Edition
## Nelly Never Forgets
**FAF now writes the file GitHub Copilot reads.**
Run `faf` with no arguments:
```bash
faf export --copilot # → .github/copilot-instructions.md (every Copilot surface reads it)
faf git owner/repo # instant scored .faf from any GitHub repo (now injection-hardened)
```
![faf](./nelly.png)
`faf export --copilot` emits GitHub Copilot's repository-wide instruction file — the **widest-surface** one, read by default across web chat, code review, VS Code, JetBrains, the CLI, and the coding agent. `faf git` is now hardened against URL command injection (no-shell `execFileSync` + a strict allowlist). Shipped with an exemplary WJTTC Git suite that adopts the full five tiers — **BRAKE · ENGINE · AERO · TYRE · PIT**.
> **faf-cli dogfoods itself** — [project.faf](./project.faf) is source DNA; [CLAUDE.md](./CLAUDE.md) and [GEMINI.md](./GEMINI.md) are authored from it via `faf`. [AGENTS.md](./AGENTS.md) is the **BETTER** ops briefing (hand-kept for agents; `faf export --agents` still authors AGENTS.md for other repos).
---
## v6.14 — The Loop Edition
**`faf loop` drives any repo to 🏆 100% or the honest human wall** — sourcing every slot it can with provenance, asking only what only you know, never inventing.
```bash
faf loop # init → auto → score, then ask only the human-only gaps
```
The loop sources what detection can, then stops at one of three honest terminals: `done` (🏆 100%), `needs-human` (it asks only the slots only you can answer), or `stuck` (it sourced everything sourceable and nothing's left for a human to add). It never fabricates a slot to reach 100% — sourced 6Ws now carry provenance (`{value, source, confidence}`), so every seeded value is a confirm-or-edit suggestion, never an auto-confirmed guess.
---
## v6.13 — The Dart Edition
**faf now understands Dart and Flutter projects.** Content-aware `pubspec.yaml` classification — Flutter app vs reusable package · Dart server (Serverpod / Dart Frog / Shelf) / CLI / MCP — pure Dart stays Dart. The single-source engine faf-python-sdk and the MCPs compose, parity-tested across languages.
```bash
faf auto # reads pubspec.yaml → Dart/Flutter into project.faf
```
A pubspec alone no longer means "Flutter": `faf` reads the dependencies and classifies — a Flutter app, a reusable package, a Dart server, a CLI, or a Dart MCP server. The detection knowledge lives in one spec (`dart-detection.json`) that faf-cli, faf-python-sdk, and the MCPs all share.
---
## v6.12 — The Single-Source Edition
**faf-cli is now the single source for the registry `_meta`** — it emits the `one.faf/context` block every FAF MCP server composes: `registryMeta`/`registryName`/`fafContextBlock`, one deterministic projection, byte-identical, end-to-end across every surface, verifiable by sha, re-derivable instantly on-demand.
```ts
import { registryMeta, registryName } from 'faf-cli';
serverJson.name = registryName(faf); // → one.faf/<name>, derived from project.homepage
serverJson._meta = registryMeta(faf); // nests one.faf/context under publisher-provided (4 KB cap)
```
Honest-first: the block carries `{ faf, mediaType, iana, deterministic, generated }` — **no baked score**. One emitter, every door, byte-identical.
---
## v6.11 — The Ledger Edition
**`faf bench --submit` posts your cold-vs-grounded receipt to the public ledger — the context bench goes public, one command.** Run the grounding benchmark, then submit the full pair receipt:
```bash
faf bench --submit
```
The benchmark stops being a private number and becomes a shared, verifiable receipt on the public ledger. Also new: `relentlessContext` / `assembleFreshFaf` and the `buildTableOf8` interview keystone join the public API.
## v6.10 — The Composed Edition
**Every FAF MCP composes single-source engines, never reimplements them.** Turbo-Cat (the ~200-format knowledge base) and the bench engine join the public API, alongside scoring and the 6Ws Interview:
```ts
import { turboCatScan, deriveQuestionSet, publicQuestions, gradeAnswers, buildReceipt } from 'faf-cli';
```
- **Turbo-Cat composed** — `turboCatScan` / `turboCatSlots`: per-format breakdown + stack signature, sourced-only, deterministic, pure read. The MCPs retire their hardcoded format maps.
- **Bench composed** — derive questions from any `.faf` (the answer key stays server-side via `publicQuestions`), grade mechanically, emit the `✪` receipt. One grading engine, byte-identical everywhere.
- **`✪` = one convention** — parity · trust · bench all emit sha256-over-canonical-projection receipts any third party can re-derive.
---
## v6.9 — The Grounded Edition
**Grounding becomes a first-class primitive: `faf bench` proves it, the 6Ws Interview single-sources it, `faf refresh` keeps it.**
- **`faf bench`** — the AI-grounding benchmark. Cold vs with-faf, two numbers (answers right, tokens burned), and **the `.faf` is the answer key** — grading is mechanical, the receipt is a verifiable `✪` sha256. A low cold score is an alarm bell: you are hemorrhaging tokens and the AI is guessing at what you're building. `faf bench` → protocol, `faf bench questions` → hand them to any AI, `faf bench grade answers.json --cold|--faf` → the pair.
- **The 6Ws Interview, exported** — the 8-question core (name + goal + the six Ws) plus the stack interview now ship as the public API (`SIX_WS_INTERVIEW`, `questionForSlot`, `interviewForMissing`). One registry; every consumer (CLI, MCPs, UIs) asks the same questions. Question drift is dead.
- **`faf refresh`** — the re-ground: re-score the live `.faf`, measure drift vs the DNA baseline (`drift: 43% ↑ 55% (+12)`), keep an existing `.fafb` fast tier compiled current, record the journey. `drift → refresh → re-grounded`.
---
## v6.7 — The HTML Edition
**We rendered a `.faf`. 🔥 The day we *saw* FAF.**
A major development — not a new flag, a new way to *see* what your AI
works from. A `.faf` was always machine-readable. Now it is
human-visible.
```
faf show
```
**What:** one verb renders your *current* `project.faf` to a
self-contained `project.html` and opens it — score, tier, the 6 W's,
the stack, in any browser.
**Why it matters:** HTML shows **on-demand** — current truth, never a
stale snapshot — **visuals for human *and team* review.** The same
context your AI reads, now reviewable by people. Trophy renders the
earned award; sub-Trophy renders the honest gaps — a map, not a
verdict. Humans like visuals. We gave them one.
It is a **cross-check**: see what your AI sees, then improve what it is
working with **at the root** — the `project.faf` itself, not the
symptoms.
This is the **4th pillar**:
> **FAF defines. MD instructs. AI codes. HTML shows.**
`faf show` · `faf export --html` · a public render API
(`generateProjectHtml`) — one single-sourced renderer, no reinvention.
Receipts → [CHANGELOG](./CHANGELOG.md)
---
## v6.6 — The Trophy Edition
Until now we have had 85% as a recommended minimum. **It's now 100%! 🏆 All or nothing.**
AI gets its best shot at assisting you. **Period.**
We are able to do this because we can now get you to 100% on virtually any app-type.
**FAF Init > Auto > Go = 100%.**
`faf sync` locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.
(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.)
Receipts → [CHANGELOG](./CHANGELOG.md)
---
## v6.0 — Built with Bun
v6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.
| | Claude Code | faf-cli v6 |
|-|-------------|------------|
| **Runtime** | Bun | Bun (`bunx`) |
| **Test** | Bun | `bun test` |
| **Build** | Bun | `bun build` |
| **Language** | TypeScript | TypeScript |
| **Compile** | Bun bytecode | `bun build --compile` |
880 tests in ~18s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.
32 commands. 880 tests. WJTTC-tested. 93% smaller than v5.
```
commands → interop → core → wasm
```
The WASM scoring kernel (`faf-scoring-kernel` 2.0.0) does the math. Bun does the delivery.
---
## Commands
| # | Command | One-liner |
|---|---------|-----------|
| 1 | `faf init` | Create `.faf` from your local project |
| 2 | `faf git <url>` | Instant `.faf` from any GitHub repo — no clone |
| 3 | `faf auto` | Zero to 100% in one command |
| 4 | `faf go` | Guided interview to gold code |
| 5 | `faf score` | Check AI-readiness (0-100%) |
| 6 | `faf sync` | `.faf` ↔ CLAUDE.md (bi-sync, mtime auto-direction) |
| 7 | `faf compile` | `.faf` → `.fafb` binary — sealed, portable, deterministic |
| 8 | `faf decompile` | `.fafb` → JSON |
| 9 | `faf export` | Author AGENTS.md, .cursorrules, GEMINI.md |
| 10 | `faf check` | Validate `.faf` file |
| 11 | `faf edit` | Edit `.faf` fields inline |
| 12 | `faf convert` | Convert `.faf` to JSON |
| 13 | `faf drift` | Check context drift |
| 14 | `faf context` | Author context output |
| 15 | `faf recover` | Recover `.faf` from CLAUDE.md / AGENTS.md |
| 16 | `faf migrate` | Migrate `.faf` to latest version |
| 17 | `faf search` | Search slots and formats |
| 18 | `faf share` | Share `.faf` via URL |
| 19 | `faf taf` | Generate TAF test receipt |
| 20 | `faf demo` | Demo walkthrough |
| 21 | `faf ai` | AI-powered enhance & analyze |
| 22 | `faf pro` | Pro features & licensing |
| 23 | `faf conductor` | Conductor integration |
| 24 | `faf formats` | Show supported formats |
| 25 | `faf info` | Version and system info |
| 26 | `faf clear` | Clear cached data |
| Command | What it does |
|---------|--------------|
| `faf init` | Create `project.faf` from your local project |
| `faf git <url>` | Instant `.faf` from any GitHub repo — no clone |
| `faf auto` | Detect stack, fill every slot it can, score |
| `faf go` | Guided interview to fill the human-only slots |
| `faf score` | Check AI-readiness (0–100%) |
| `faf export` | Author `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules` |
| `faf sync` | Bi-directional `.faf` ↔ `CLAUDE.md` |
| `faf diff` / `log` | Semantic context diff + score timeline across git history |
| `faf hooks --install` | Pre-commit guard against context regression |
| `faf compile` / `decompile` | `.faf` ↔ `.fafb` sealed binary |
| `faf check` | Validate a `.faf` file |
| `faf recover` | Rebuild `.faf` from an existing `CLAUDE.md` / `AGENTS.md` |
| `faf show` | Render `project.faf` to a browsable HTML page |
| `faf formats` | List supported stacks and formats |
Run `faf --help` for full options.
Run `faf --help` for the full command set and options.
---
## Quick Start
## Custom instructions
```bash
# ANY GitHub repo — no clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react
Your own rules for the AI — *"use full words in identifiers," "use bun, not npm"* — go in `project.faf` under `ai_instructions.warnings`. They land at the top of every `AGENTS.md` faf writes, verbatim and non-destructive.
# Your own project
bunx faf-cli init # Create .faf
bunx faf-cli auto # Zero to 100% in one command
bunx faf-cli go # Interactive interview to gold code
```
**→ [How to add custom rules](https://docs.faf.one/custom-rules)** · [docs.faf.one](https://docs.faf.one)

@@ -366,4 +154,4 @@ ---

```
bi-sync: .faf ←── 8ms ──→ CLAUDE.md (free forever)
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md (Pro)
bi-sync: .faf ←── 8ms ──→ CLAUDE.md
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md
```

@@ -373,2 +161,28 @@

## Docs
The full manual lives at **[docs.faf.one](https://docs.faf.one)** — facts for devs, faf-cli first.
- [Getting started](https://docs.faf.one/getting-started) — install · run · use
- [Custom rules](https://docs.faf.one/custom-rules) — pin instructions your AI must follow
For a specific agent: [Grok, xAI & Cursor 👀](docs/faf-cli-for-agents.md) · [Claude Code 👀](docs/faf-cli-for-claude.md) · [Bun 👀](docs/faf-cli-for-bun.md)
---
## Recent editions
Pivotal releases — full history in [CHANGELOG.md](./CHANGELOG.md):
- **v7.1 — AGENTS.md** — `faf export --agents` authors a complete, non-destructive `AGENTS.md`.
- **v7.0 — GIT** — context goes git-native: `faf diff` / `log` / `hooks`.
- **v6.16 — Know Your Stack** — every emitted file labels your stack identically.
- **v6.15 — Copilot** — `faf export --copilot` writes the file GitHub Copilot reads.
- **v6.14 — Loop** — `faf loop` drives any repo to 🏆 100% or the honest human wall.
- **v6.7 — HTML** — `faf show` renders a `.faf` to a browsable page. *(FAF defines. MD instructs. AI codes. HTML shows.)*
- **v6.6 — Trophy** — 100% or nothing.
- **v6.0 — Bun** — ground-up rewrite; single portable binary, four platforms.
---
## Compiled Binaries

@@ -391,5 +205,5 @@

src/
├── cli.ts ← Entry point, 26 command registrations
├── commands/ ← 26 command files (1 per command)
├── core/ ← Types, slots (33 Mk4), tiers, scorer, schema
├── cli.ts ← Entry point (Commander registrations)
├── commands/ ← one file per faf subcommand
├── core/ ← Types, slots (Mk4), tiers, scorer, schema
├── detect/ ← Framework detection, stack scanner

@@ -410,8 +224,8 @@ ├── interop/ ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md

```bash
bun test # 880 tests, 75 files, ~18s
bun test # extensive WJTTC + e2e suite
```
- **WJTTC Build Resilience** (13) — every regression class locked.
- **WJTTC Kernel Stress** (19) — WASM kernel boundary tests.
- **e2e lifecycle** — every command in sequence.
- **WJTTC Build Resilience** — regression classes locked.
- **WJTTC Kernel Stress** — WASM kernel boundary tests.
- **e2e lifecycle** — commands in sequence.

@@ -427,4 +241,2 @@ Test reports in `reports/`.

---
If `faf-cli` has been useful, consider starring the repo — it helps others find it.

@@ -434,3 +246,2 @@

## Citation

@@ -474,3 +285,3 @@

*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)*
*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev) · [faf.one/cli](https://faf.one/cli)*

@@ -477,0 +288,0 @@ <div align="center">

dist/cli.js

Sorry, the diff of this file is too big to display

dist/cli.js.map

Sorry, the diff of this file is too big to display

dist/index.js

Sorry, the diff of this file is too big to display

dist/index.js.map

Sorry, the diff of this file is too big to display

project.faf

Sorry, the diff of this file is not supported yet