faf-cli 6.8.0 → 6.10.0

package/dist/commands/bench.d.ts

@@ -0,0 +1,104 @@
+/**
+ * faf bench — the AI-grounding benchmark (P1, agent-native).
+ *
+ * Measures the thing FAF sells, falsifiably: AI works better and faster WITH
+ * structured context. Two numbers, one harness — grounding ACCURACY (N
+ * project questions, cold vs with-faf) and grounding COST (tokens to get
+ * grounded, as reported by the runner).
+ *
+ * The unfair advantage: the .faf IS the answer key. Questions derive from the
+ * populated active slots; grading is mechanical (normalize + versioned alias
+ * map + significant-token containment — no judge, no rubric drift). The
+ * question-set hash rides a ✪ receipt, parity-hash discipline.
+ *
+ * DOCTRINE (wolfejam 2026-06-11):
+ *  - "A low score is an ALARM BELL — you are hemorrhaging tokens and the AI
+ *    is pretty much clueless about what you are doing, even trying to do."
+ *    Headline: "Trouble ahead, expensive trouble."
+ *  - NEVER render a low score alone — always the pair (cold → with-faf), or
+ *    the alarm framing with headroom. The delta is the product; the cold
+ *    number belongs to the ABSENCE of context ("without context"), never to
+ *    FAF. Output always ends in a prescription, never a verdict.
+ *  - The 6Ws are UNDERIVABLE from code: cold exploration can dig out a stack
+ *    (you pay for the dig); it can never find intent.
+ */
+/** Bump when phrasing, aliases, or grading rules change — part of the qset hash. */
+export declare const BENCH_VERSION = "faf-bench/1";
+export interface BenchQuestion {
+    n: number;
+    path: string;
+    question: string;
+}
+/**
+ * Versioned alias groups — mechanical equivalences, no fuzzy scoring.
+ * Members are compared post-normalization. Extend deliberately; every change
+ * bumps the qset hash via BENCH_VERSION.
+ */
+export declare const ALIAS_GROUPS: string[][];
+export declare function normalizeAnswer(s: string): string;
+/**
+ * Mechanical match: exact normalized equality, alias-group equality, or
+ * every significant token of the EXPECTED value present in the answer
+ * (deterministic set containment — handles sentence-shaped 6W answers
+ * without a judge). A miss is a miss.
+ */
+export declare function answersMatch(expected: string, given: string): boolean;
+export interface QuestionSet {
+    version: string;
+    qsetHash: string;
+    questions: BenchQuestion[];
+    /** Internal answer key — NEVER printed by `questions`; used by `grade`. */
+    answers: Record<number, string>;
+}
+/** Derive the question set + answer key from a project.faf (active populated slots only). */
+export declare function deriveQuestionSet(yaml: string): QuestionSet;
+/**
+ * The answer-key-safe projection of a QuestionSet — version + qsetHash +
+ * questions, NEVER `answers`. Any "give me the questions" surface (MCP tools,
+ * UIs) MUST hand out THIS, not the raw QuestionSet: a tool that prints the
+ * answer key makes the benchmark a lie. The CLI's `bench questions` follows
+ * the same rule.
+ */
+export declare function publicQuestions(qset: QuestionSet): {
+    version: string;
+    qsetHash: string;
+    questions: BenchQuestion[];
+};
+export interface GradeResult {
+    correct: number;
+    total: number;
+    misses: BenchQuestion[];
+    perQuestion: {
+        n: number;
+        path: string;
+        ok: boolean;
+    }[];
+}
+export declare function gradeAnswers(qset: QuestionSet, given: Record<string, string>): GradeResult;
+export interface RunRecord {
+    score: number;
+    total: number;
+    tokens?: number;
+    model?: string;
+}
+export interface BenchState {
+    version: string;
+    qsetHash: string;
+    protocol: 'in-session';
+    cold?: RunRecord;
+    faf?: RunRecord;
+}
+/** ✪ receipt — sha256 over the canonical projection; third-party verifiable. */
+export declare function buildReceipt(state: BenchState): {
+    projection: string;
+    hash: string;
+};
+export interface BenchOptions {
+    json?: boolean;
+    cold?: boolean;
+    faf?: boolean;
+    tokens?: string;
+    model?: string;
+    file?: string;
+}
+export declare function benchCommand(action?: string, answersFile?: string, options?: BenchOptions): void;

package/dist/core/interview.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The 6Ws Interview — SINGLE SOURCE.
+ *
+ * The canonical question registry for filling a .faf by asking a human (or an
+ * agent asking a human). faf-cli OWNS it; consumers (claude-faf-mcp's faf_go,
+ * siblings, UIs) IMPORT it — never reimplement, never copy. Decided
+ * 2026-06-10: the CLI exports, CFM consumes, zero drift. (CFM's previous
+ * hand-maintained registry had already drifted — e.g. its `how` asked "How
+ * should AI assist?" while the canonical slot semantic is "How is it built /
+ * used?". This file is the arbiter; slots.ts is its spine.)
+ *
+ * Shape carries what interactive consumers need: question text, a short
+ * header chip, input type, required flag, select options where a closed-ish
+ * vocabulary exists. Question SEMANTICS align to core/slots.ts descriptions —
+ * the slot is the meaning, the question is just its interview voice.
+ *
+ * Authoring doctrine baked into the prompts: 6Ws answers are terse LABELS
+ * (3-4 words, hard cap <6) — a scannable spec card, not prose.
+ */
+/** Bump when questions/options change — consumers can pin or report it. */
+export declare const INTERVIEW_VERSION = "faf-interview/1";
+export interface InterviewOption {
+    label: string;
+    value: string;
+    description: string;
+}
+export interface InterviewQuestion {
+    /** Canonical slot path (core/slots.ts is the spine). */
+    path: string;
+    question: string;
+    /** Short chip/header label (max ~12 chars) for option-UI consumers. */
+    header: string;
+    type: 'text' | 'select';
+    required: boolean;
+    options?: InterviewOption[];
+}
+/**
+ * THE 8-Q 6Ws INTERVIEW — the core. Project identity (name + goal) plus the
+ * six Ws. Language is deliberately NOT here: detection finds it; humans are
+ * only asked what machines cannot derive. The 6Ws are the underivable half.
+ */
+export declare const SIX_WS_INTERVIEW: InterviewQuestion[];
+/**
+ * Stack interview — asked only for slots ACTIVE for the app_type and still
+ * empty. Selects where a common vocabulary exists; every select includes
+ * Other (specify) and None where absence is legitimate.
+ */
+export declare const STACK_INTERVIEW: InterviewQuestion[];
+/** The full ordered registry: the 8-Q core first, then stack. */
+export declare const INTERVIEW: InterviewQuestion[];
+/** Lookup by slot path. */
+export declare const INTERVIEW_BY_PATH: Map<string, InterviewQuestion>;
+/**
+ * Plain-object companion to INTERVIEW_BY_PATH. A Map JSON-serializes to `{}`,
+ * which reads as "the export shipped empty" to any consumer that crosses a
+ * serialization boundary (caught by the CFM compose handoff, 2026-06-12).
+ * Bridge consumers that serialize should use THIS; in-process consumers can
+ * use either.
+ */
+export declare const INTERVIEW_PATHS: Record<string, InterviewQuestion>;
+/**
+ * Interview voice for ANY slot: the registry question when one exists,
+ * otherwise derived from the slot's canonical description — so slot-driven
+ * flows (faf go) and registry-driven flows (faf_go) speak the same language.
+ */
+export declare function questionForSlot(path: string): string;
+/**
+ * The questions still worth asking for a given .faf: registry order, empty
+ * (or placeholder) slots only, slotignored skipped — the What-Not is never
+ * interviewed. `data` is the parsed .faf object.
+ */
+export declare function interviewForMissing(data: Record<string, unknown>, isEmpty: (value: unknown) => boolean): InterviewQuestion[];

package/dist/core/slots.d.ts

@@ -28,9 +28,10 @@ export declare const ENTERPRISE_SLOTS: SlotDef[];
 export declare const PLACEHOLDERS: Set<string>;
 /** Check if a value is a placeholder (empty) */
 export declare function isPlaceholder(value: unknown): boolean;
-/** App-type to active category mapping. The canonical 22-type ladder —
- *  20 detectable apps + `about` (non-app, 0 slots, owner-attested)
- *  + `encyclopedia` (curated knowledge surface, FAFipedia and similar).
+/** App-type to active category mapping. The canonical 24-type ladder —
+ *  21 detectable apps + `about` (non-app, 0 slots, owner-attested)
+ *  + `encyclopedia` (curated knowledge surface, FAFipedia and similar)
+ *  + `intent` (human-intent seed from builder.faf.one, not auto-detected).
  *  (See v6.6.md doctrine memory + fafipedia-vs-grokipedia-architecture.)
  *  Sorted ascending by active slot count for readability.
  *

package/dist/detect/turbo-cat-knowledge.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 🔺 TURBO-CAT™ FORMAT PYRAMID v3.1.1
+ *
+ * ROW 20 IN PROGRESS - 199 FORMATS CATALOGUED!
+ *
+ * Like precious metals in a catalytic converter - each format triggers
+ * a specific intelligence reaction. We CAN catalyze ANY format, but only
+ * the WORTHY earn a pyramid stone!
+ *
+ * Pyramid Evolution:
+ * ├── Row 17: Sum(1..17) + 1 = 154 (THE SACRED - ACHIEVED 2024)
+ * ├── Row 18: Sum(1..18) + 1 = 172 (BEYOND SACRED - ACHIEVED)
+ * ├── Row 19: Sum(1..19) + 1 = 190 (ACHIEVED 2025-12-17)
+ * └── Row 20: Sum(1..20) + 1 = 211 (IN PROGRESS - 9/21 added)
+ *
+ * Row 20 Tier 1 Added (2025-12-17):
+ * - build.zig.zon (Zig packages)
+ * - gleam.toml (Gleam - 2nd most admired 2025)
+ * - bunfig.toml (Bun config)
+ * - mise.toml / .mise.toml (mise version manager)
+ * - manifest.toml (Flox/Nix environments)
+ * - justfile (Just command runner - 10k+ stars)
+ * - .pre-commit-config.yaml (Git hooks framework)
+ * - CLAUDE.md (Claude Code AI context)
+ *
+ * THE DOCTRINE: To add a new format, PROVE it's better than existing ones!
+ *
+ * 😽 We are the FORMAT FREAKS - Quality over Quantity!
+ * 🏆 199 formats - CHAMPIONSHIP GRADE FORMAT DETECTION
+ */
+export interface FormatKnowledge {
+    frameworks: string[];
+    slots: Partial<ContextSlots>;
+    priority: number;
+    intelligence: 'ultra-high' | 'high' | 'medium' | 'low';
+    confirmWith?: string[];
+}
+export interface ContextSlots {
+    framework: string;
+    mainLanguage: string;
+    buildTool: string;
+    packageManager: string;
+    hosting: string;
+    backend: string;
+    apiType: string;
+    cicd: string;
+    database: string;
+    cssFramework: string;
+    uiLibrary: string;
+    stateManagement: string;
+    server: string;
+    connection: string;
+    runtime: string;
+    build: string;
+    main_language: string;
+    build_tool: string;
+    pkg_manager: string;
+    api: string;
+    css: string;
+    ui_library: string;
+    state: string;
+    db: string;
+    targetUser: string;
+    coreProblem: string;
+    missionPurpose: string;
+    deploymentMarket: string;
+    timeline: string;
+    approach: string;
+}
+/**
+ * THE KNOWLEDGE BASE
+ *
+ * Add any file format here and map it to:
+ * 1. Frameworks it indicates
+ * 2. Context slots it can fill
+ * 3. Priority/intelligence score
+ *
+ * The fab-formats engine will automatically use this knowledge!
+ */
+export declare const KNOWLEDGE_BASE: Record<string, FormatKnowledge>;
+/**
+ * Get knowledge for a specific format
+ */
+export declare function getFormatKnowledge(format: string): FormatKnowledge | undefined;
+/**
+ * Get all format keys
+ */
+export declare function getAllFormats(): string[];
+/**
+ * Get high-value formats (priority >= 30)
+ */
+export declare function getHighValueFormats(): string[];
+/**
+ * Get formats by intelligence level
+ */
+export declare function getFormatsByIntelligence(level: FormatKnowledge['intelligence']): string[];
+/**
+ * Get formats that can fill a specific slot
+ */
+export declare function getFormatsForSlot(slotName: keyof ContextSlots): string[];
+/**
+ * Calculate total possible intelligence score
+ */
+export declare function getMaxIntelligenceScore(): number;

package/dist/detect/turbo-cat.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turbo-Cat™ (= Format-finder) — fills .faf slots from file-format evidence
+ * across ~200 formats (the KNOWLEDGE_BASE). Restores the multi-ecosystem
+ * manifest interrogation the v6.0 rewrite narrowed to README+Cargo+package.json.
+ *
+ * v6-native sync port (the v5 engine was async; sync integrates cleanly with
+ * `auto`). Two-layer: (1A) config files walking up to the monorepo .git
+ * boundary, (1B) source extensions; priority-wins slot recommendations.
+ *
+ * Used as the LOWEST-precedence filler in `auto`: v6's specific detection wins;
+ * Turbo-Cat fills only the slots still empty (esp. non-npm stacks).
+ */
+/** A format actually discovered on disk (config-file layer; real files only). */
+export interface DiscoveredFormat {
+    fileName: string;
+    /** Derived from the entry's primary slot family (deterministic — real
+     *  knowledge surfaced, not invented): package-manager, language, framework,
+     *  backend, database, ci-cd, hosting, build, … */
+    category: string;
+    priority: number;
+}
+export interface TurboCatResult {
+    slotFills: Record<string, string>;
+    frameworks: string[];
+    confirmedCount: number;
+    /** Option B (compose spec 2026-06-12): the per-format breakdown consumers
+     *  display — surfaced so MCPs can DELETE their local format maps entirely. */
+    discoveredFormats: DiscoveredFormat[];
+    /** Deterministic lowercase signature, e.g. "typescript-react" ('unknown-stack' when bare). */
+    stackSignature: string;
+}
+/** Scan formats → priority-wins slot recommendations. */
+export declare function turboCatScan(projectDir: string): TurboCatResult;
+/** Turbo-Cat slot fills shaped as a v6 .faf partial ({ project, stack }) for fillEmpties. */
+export declare function turboCatSlots(projectDir: string): {
+    project?: Record<string, string>;
+    stack?: Record<string, string>;
+};

package/dist/index.d.ts

@@ -6,4 +6,10 @@ export { enrichScore, scoreFafYaml } from './core/scorer.js';
 export { validateFaf } from './core/schema.js';
 export { findFafFile, readFaf, readFafRaw } from './interop/faf.js';
 export { generateProjectHtml, writeProjectHtml } from './interop/projecthtml.js';
+export type { InterviewQuestion, InterviewOption } from './core/interview.js';
+export { INTERVIEW, SIX_WS_INTERVIEW, STACK_INTERVIEW, INTERVIEW_BY_PATH, INTERVIEW_PATHS, INTERVIEW_VERSION, questionForSlot, interviewForMissing, } from './core/interview.js';
+export { BENCH_VERSION, deriveQuestionSet, publicQuestions, gradeAnswers, buildReceipt, normalizeAnswer, answersMatch, ALIAS_GROUPS, } from './commands/bench.js';
+export type { BenchQuestion, QuestionSet, GradeResult, BenchState, RunRecord } from './commands/bench.js';
+export { turboCatScan, turboCatSlots } from './detect/turbo-cat.js';
+export type { TurboCatResult, DiscoveredFormat } from './detect/turbo-cat.js';
 export * as kernel from './wasm/kernel.js';