faf-cli 7.10.1 → 7.12.0

package/dist/interop/agents.d.ts

@@ -0,0 +1,15 @@
+import type { FafData } from '../core/types.js';
+/**
+ * Author a BETTER-shaped AGENTS.md from .faf data (+ repo enrichment at export).
+ *
+ * Deterministic projection from curated TRUTH — facts, not hallucinated prose
+ * (Gloaguen: LLM freewrite hurts). Sections: orientation · setup · verify ·
+ * map · conventions · three-tier guardrails · DoD · when stuck · security ·
+ * commit. Human Context (who/why marketing) is intentionally omitted — that
+ * belongs in README / project.faf, not agent ops.
+ *
+ * Design: BETTER guide + hand exemplar (faf-cli AGENTS.md) + agents-md-facts.
+ */
+export declare function renderAgentsMd(data: FafData): string;
+/** Write AGENTS.md — non-destructive: injects/updates the faf block, preserves the rest. */
+export declare function writeAgentsMd(dir: string, data: FafData): void;

package/dist/interop/cards.d.ts

@@ -106,7 +106,10 @@ export declare function findFafaFile(dir?: string): string | null;
 export declare function a2aEndpoints(fafa: FafaDoc): FafaEndpoint[];
 /** Authored A2A endpoints, else a single `doorUrl`. Never invents a door. */
 export declare function a2aDoors(fafa: FafaDoc, opts?: ProjectCardsOptions): FafaEndpoint[];
-export declare function generateA2ACard(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): ProjectedA2A;
+/** Build the A2A Agent Card (JSON) from a .fafa + .faf. */
+export declare function buildA2ACard(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): ProjectedA2A;
+/** @deprecated Use {@link buildA2ACard}. Removed in the next major. */
+export declare const generateA2ACard: typeof buildA2ACard;
 export declare function catalogEntriesFor(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
 /** Upsert projector entries into an existing catalog. Leaves unknown rows alone.
  *  On match, only url / type / updatedAt move — host copy (title, tags) stays. */

package/dist/interop/claude.d.ts

@@ -0,0 +1,35 @@
+import type { FafData } from '../core/types.js';
+/** Read CLAUDE.md from a directory */
+export declare function readClaudeMd(dir: string): string | null;
+/** Write CLAUDE.md — non-destructive: injects/updates the faf block, preserves the rest. */
+export declare function writeClaudeMd(dir: string, content: string): void;
+/** Get mtime of CLAUDE.md */
+export declare function claudeMdMtime(dir: string): number | null;
+/** Optional knobs for the 2-line FAF stamp. */
+export interface FafMetaOpts {
+    /** Canonical structured-truth file the md claims (default `project.faf`).
+     *  Use for AI-context md (CLAUDE/GEMINI/AGENTS/.cursorrules). */
+    claim?: string;
+    /** Role identifier (`readme`, `changelog`, `skill`, …).
+     *  Use for repo-meta md whose primary reader is human. Mutually exclusive with `claim`. */
+    doc?: string;
+    /** Current AI-readiness score (0–100). */
+    score?: number;
+    /** Sister-product family — `FAF` (default), `TAF`, `WJTTC`, … */
+    family?: string;
+    /** Other docs in the repo the reader should know about. */
+    siblings?: string[];
+}
+/**
+ * Build the canonical 2-line FAF stamp.
+ *
+ * Line 1 — positional identity: `name | lang | type | description`
+ * Line 2 — key=value navigation/state: `claim=… | score=… | family=… | siblings=…`
+ *
+ * Spec: `memory/cross-ai-2-line-meta-stamp.md`. Issue #64.
+ */
+export declare function fafMetaTag(data: FafData, opts?: FafMetaOpts): string;
+/** Render CLAUDE.md content from .faf data */
+export declare function renderClaudeMd(data: FafData): string;
+/** Extract project data from CLAUDE.md content (pull direction) */
+export declare function parseClaudeMd(content: string): Partial<FafData>;

package/dist/interop/copilot-instructions.d.ts

@@ -0,0 +1,26 @@
+import type { FafData } from '../core/types.js';
+/**
+ * Render `.github/copilot-instructions.md` content from .faf data.
+ *
+ * GitHub Copilot's repository-wide custom-instructions file — the WIDEST-supported
+ * instruction surface (web chat, code review, VS Code, JetBrains, Visual Studio,
+ * Eclipse, Xcode, Copilot CLI, coding agent), injected into EVERY request.
+ *
+ * Built to GitHub's published custom-instructions guidance:
+ * short, self-contained, imperative INSTRUCTIONS — not a metadata dump. So we lead
+ * with the goal as a prose overview, Title-Case labels (acronym-aware), surface the
+ * build/run steps as copy-pasteable commands, keep it compact, and avoid every named
+ * anti-pattern (no tone/length rules, no external references). Deliberately NOT a
+ * clone of AGENTS.md (which it outranks in-repo) — they are complementary.
+ *
+ * Strictly faithful to the .faf — nothing invented (GitHub bans speculative,
+ * task-specific instructions). Future-proof: the command section + Title-Caser
+ * already consume the richer slots Option B will add (test/lint/run, …), so this
+ * emitter is built once and grows with the data.
+ */
+export declare function renderCopilotInstructions(data: FafData): string;
+/**
+ * Write `.github/copilot-instructions.md` — non-destructive (injects/updates the
+ * faf block, preserves the rest). Creates the `.github/` directory if absent.
+ */
+export declare function writeCopilotInstructions(dir: string, data: FafData): void;

package/dist/interop/cursorrules.d.ts

@@ -0,0 +1,5 @@
+import type { FafData } from '../core/types.js';
+/** Render .cursorrules content from .faf data */
+export declare function renderCursorrules(data: FafData): string;
+/** Write .cursorrules — non-destructive: injects/updates the faf block (hash-comment markers), preserves the rest. */
+export declare function writeCursorrules(dir: string, data: FafData): void;

package/dist/interop/gemini.d.ts

@@ -0,0 +1,12 @@
+import type { FafData } from '../core/types.js';
+/**
+ * Render GEMINI.md content from .faf data (+ repo enrichment at export).
+ *
+ * Matches Gemini CLI's own GEMINI.md convention (hierarchical, concatenation-
+ * friendly, `@file.md`-importable): commands, key files, and confirmation-
+ * required actions — not the AGENTS.md BETTER ladder, which is a different
+ * spec for a different reader.
+ */
+export declare function renderGeminiMd(data: FafData): string;
+/** Write GEMINI.md — non-destructive: injects/updates the faf block, preserves the rest. */
+export declare function writeGeminiMd(dir: string, data: FafData): void;

package/dist/interop/inject.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Block markers for the faf-managed front section.
+ *
+ * Markdown files (AGENTS.md, CLAUDE.md, GEMINI.md) use HTML comments; non-markdown
+ * files (.cursorrules) pass hash-comment markers via the `start`/`end` args.
+ */
+export declare const FAF_START = "<!-- faf:start -->";
+export declare const FAF_END = "<!-- faf:end -->";
+/**
+ * Locate the faf-managed block in `text`: the first START marker line and the
+ * first END marker line after it. Returns the char range covering both marker
+ * lines (terminator of the END line excluded), or null when there is no
+ * complete block.
+ *
+ * Markers are matched as WHOLE LINES at column 0, never as substrings. Substring
+ * search was a real bug (7.1.4–7.11.0): renderAgentsMd quoted the marker tokens
+ * in its own blockquote, so on every re-run `indexOf(end)` hit the quote, cut
+ * the old block in half and appended its stale tail below the new block —
+ * `faf export --agents` grew AGENTS.md by ~49 lines per run. The same happened
+ * to users who documented the markers in a code fence above the block.
+ *
+ * Two passes. The first skips START candidates inside fenced code, so a fenced
+ * example is not mistaken for the block. Fence detection is a plain toggle and
+ * Markdown has shapes it misreads (list-item fences, ```` around ```, a stray
+ * unclosed fence), so if the first pass finds nothing the second ignores fences
+ * entirely. A miss must never be silent: the caller treats "no block" as a
+ * user file and prefixes — it does not overwrite.
+ */
+export declare function findFafBlock(text: string, start?: string, end?: string): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Non-destructively write a faf-managed block into a file.
+ *
+ *   - file does not exist     → create it containing just the block
+ *   - file has the markers    → replace ONLY the content between them (update in place)
+ *   - legacy faf file         → metastamp-led, no marker lines: reclaim in place
+ *   - file exists, no block   → PREFIX the block; everything the user wrote is preserved
+ *
+ * Idempotent: re-running updates the managed block in place and never duplicates
+ * it or touches a byte the user owns. faf owns what's between the markers; the
+ * user owns everything else. Enhance, never replace.
+ */
+export declare function injectFafBlock(path: string, block: string, start?: string, end?: string): void;

package/dist/interop/labels.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared label formatting for the AI-context emitters (CLAUDE.md, AGENTS.md,
+ * .github/copilot-instructions.md). ONE acronym-aware Title-Caser so `api_type`
+ * renders "API Type" everywhere — not "Api Type" in one file and a raw
+ * `api_type` key in another. Unified 2026-06-25 (faf-cli 6.15.1).
+ *
+ * Labels are registry-first: `slotLabel()` reads the canonical label from the
+ * slot registry ("know your stack"); the acronym-aware `titleLabel()` is only a
+ * fallback for off-registry freeform keys.
+ */
+/** All-caps acronym tokens that stay upper-cased inside a Title-Cased label. */
+export declare const ACRONYMS: Set<string>;
+/**
+ * snake_case → Title Case, acronym-aware.
+ * `api_type` → "API Type", `mcp_sdk` → "MCP SDK", `runtime` → "Runtime".
+ */
+export declare function titleLabel(key: string): string;
+/** A slot value that carries real content (not empty, not slotignored). */
+export declare function filled(v: unknown): v is string;
+/**
+ * The canonical display label for a .faf slot path, sourced from the slot
+ * registry ("know your stack") — `stack.cicd` → "CI/CD", `stack.api_type` → "API".
+ * Resolves legacy OR canonical paths (SLOT_BY_PATH is dual-keyed). Falls back to
+ * the acronym-aware Title-Caser for off-registry freeform keys.
+ */
+export declare function slotLabel(path: string): string;

package/dist/interop/projecthtml.d.ts

@@ -1,5 +1,7 @@
 import type { FafData, ScoreResult } from '../core/types.js';
 /** Render project.faf data + its score into a self-contained HTML string. */
-export declare function generateProjectHtml(data: FafData, result: ScoreResult, fafPath?: string): string;
+export declare function renderProjectHtml(data: FafData, result: ScoreResult, fafPath?: string): string;
 /** Write project.html beside project.faf (repo root). */
 export declare function writeProjectHtml(dir: string, data: FafData, result: ScoreResult, fafPath?: string): void;
+/** @deprecated Use {@link renderProjectHtml}. Removed in the next major. */
+export declare const generateProjectHtml: typeof renderProjectHtml;

package/dist/interop/servercard.d.ts

@@ -1,6 +1,6 @@
 import type { FafData } from '../core/types.js';
 /**
- * Generate an MCP Server Card (SEP-2127) from a .faf.
+ * Build an MCP Server Card (SEP-2127) from a .faf.
  *
  * The card is a published discovery manifest. By design it carries the FAF
  * context-block in `_meta["one.faf/context"]` — so every Server Card produced
@@ -33,7 +33,7 @@ export interface ServerCardOptions {
  */
 export declare function fafContextBlock(data: FafData, opts?: ServerCardOptions): Record<string, unknown>;
 /** Build the Server Card object from .faf data. */
-export declare function generateServerCard(data: FafData, opts?: ServerCardOptions): Record<string, unknown>;
+export declare function buildServerCard(data: FafData, opts?: ServerCardOptions): Record<string, unknown>;
 export declare const REGISTRY_PUBLISHER_KEY = "io.modelcontextprotocol.registry/publisher-provided";
 /**
  * Build the `_meta` for an MCP Registry `server.json`.
@@ -68,3 +68,5 @@ export declare function registryTitle(data: FafData): string | undefined;
  *  `<streamable-http-url>/server-card` (no longer `.well-known`); serve the
  *  emitted file there as `application/mcp-server-card+json`. */
 export declare function writeServerCard(dir: string, data: FafData, opts?: ServerCardOptions): string;
+/** @deprecated Use {@link buildServerCard}. Removed in the next major. */
+export declare const generateServerCard: typeof buildServerCard;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faf-cli",
-  "version": "7.10.1",
+  "version": "7.12.0",
   "description": "Persistent AI context + memory — .faf and .fafm, IANA-registered. Anthropic-merged.",
   "type": "module",
   "icon": "https://faf.one/orange-smiley.svg",

package/project.faf

@@ -1,8 +1,8 @@
 faf_version: "3.0"
 project:
   name: faf-cli
-  version: "7.10.1"
-  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v7.10.1 The Full-Facts Edition."
+  version: "7.12.0"
+  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v7.12.0 The Open Renderers Edition."
   main_language: TypeScript
   type: cli  # found: package.json bin
 # Commands + key_files feed `faf export --agents` (hand values win over detection).
@@ -58,7 +58,7 @@ human_context:
   what: Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.
   why: Eliminates 91% context re-discovery tax — define once, AI remembers forever
   where: npm registry, Homebrew, GitHub
-  when: Production since September 2025; Bun-native since v6; current package 7.10.1
+  when: Production since September 2025; Bun-native since v6; current package 7.12.0
   how: bunx faf-cli auto, then project.faf versions with your code — faf show renders it human-visible
 monorepo:
   packages_count: slotignored