faf-cli 6.10.1 → 6.12.0

package/dist/interop/servercard.d.ts

@@ -0,0 +1,61 @@
+import type { FafData } from '../core/types.js';
+/**
+ * Generate 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
+ * through FAF ships FAF context by default. This emitter is the SINGLE SOURCE of
+ * the block — faf-server-card-ref and `.fafa` provenance compose it (never
+ * hand-roll), so every surface is byte-identical by construction: one context,
+ * one source, every door.
+ *
+ * Honest-first: no score is baked (it would go stale on disk); the block points
+ * to the .faf and asserts the score is deterministic. The card omits `remotes`
+ * unless a deployment URL is supplied — it must not claim an endpoint it lacks.
+ */
+export interface ServerCardOptions {
+    /** Pointer to the .faf context (default: ./project.faf). Pass an absolute URL
+     *  for a remote/served card (e.g. faf-server-card-ref at context.faf.one). */
+    fafPointer?: string;
+    /** Optional live endpoint; adds a streamable-http remote when set. */
+    remoteUrl?: string;
+    /** Optional "verify the score here" URL — makes verify-don't-trust actionable
+     *  (faf-server-card-ref uses https://faf.one). Omitted from the block if unset. */
+    scoreEndpoint?: string;
+    /** Override timestamp (tests); otherwise .faf `generated`, else now. */
+    now?: string;
+}
+/**
+ * The canonical FAF context-block — the value of `_meta["one.faf/context"]`,
+ * identical across every surface (Server Card, registry `server.json`, `.fafa`):
+ * one context, every door. Honest-first: no score baked (it would go stale on
+ * disk); it points to the .faf and asserts the score is deterministic.
+ */
+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 const REGISTRY_PUBLISHER_KEY = "io.modelcontextprotocol.registry/publisher-provided";
+/**
+ * Build the `_meta` for an MCP Registry `server.json`.
+ *
+ * The SAME canonical context-block as the Server Card, but nested under
+ * `io.modelcontextprotocol.registry/publisher-provided` — the ONLY `_meta` key
+ * the official registry preserves on publish. Top-level keys (the way the card
+ * carries `one.faf/context`) are silently dropped by the registry. Throws if the
+ * block exceeds the registry's 4KB cap. Merge the result into an existing
+ * `server.json` `_meta`; don't regenerate the manifest (packages/mcpb are tuned).
+ */
+export declare function registryMeta(data: FafData, opts?: ServerCardOptions): Record<string, unknown>;
+/** The canonical reverse-DNS registry name, e.g. `one.faf/claude-faf-mcp`.
+ *
+ *  HOMEPAGE REQUIRED: the namespace is derived from `project.homepage`'s host
+ *  (faf.one -> one.faf). With no homepage/website/url the namespace falls back
+ *  to `local/<name>`. This can't silently ship — the migration is guarded
+ *  (`rewrite-server-json.ts` refuses any name that isn't `one.faf/*`) — but set
+ *  `homepage: https://faf.one` in the .faf to get the correct `one.faf/<name>`. */
+export declare function registryName(data: FafData): string;
+/** Write the Server Card to a `server-card` file. Returns the path.
+ *  Per experimental-ext-server-card#22 the reserved location is
+ *  `<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;

package/dist/interrogate/cargo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cargo.toml interrogation — extract Rust project metadata.
+ *
+ * The [package].description field is the Rust ecosystem's equivalent of
+ * package.json's `description` — a one-line elevator pitch. It maps to
+ * `project.goal` (overarching/use-case framing).
+ */
+import { type ExtractedContext } from './types.js';
+/** Read Cargo.toml and extract per-slot content. Returns {} if no Cargo.toml. */
+export declare function interrogateCargo(dir: string): ExtractedContext;

package/dist/interrogate/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Repo interrogation orchestrator — runs all extractors and merges results.
+ *
+ * Order of precedence: extractors that run first WIN (their non-empty values
+ * are kept; later extractors fill only empties). README is highest-precedence
+ * because its prose is most likely to be hand-curated; manifest fields
+ * (Cargo.toml description, package.json description) are fallbacks.
+ *
+ * The orchestrator never overwrites with empty — only fills empties.
+ */
+import type { ExtractedContext } from './types.js';
+export type { ExtractedContext } from './types.js';
+export { interrogateReadme } from './readme.js';
+export { interrogateCargo } from './cargo.js';
+/** Run all repo interrogators and return merged context. */
+export declare function interrogateRepo(dir: string): ExtractedContext;

package/dist/interrogate/readme.d.ts

@@ -0,0 +1,25 @@
+/**
+ * README.md interrogation — extract slot content from semantic markdown anchors.
+ *
+ * Per faf-auto-no-guess-no-slop:
+ *   Each extractor looks for a specific anchor (heading, structural pattern).
+ *   If the anchor is missing or the content fails validation → return undefined.
+ *   No slot is synthesized from another slot's content.
+ */
+import { type ExtractedContext } from './types.js';
+/** Extract `project.goal` — first prose paragraph or ## Use Case / ## Goal */
+export declare function extractGoal(content: string): string | undefined;
+/** Extract `human_context.what` — ## About / ## Description / ## Overview */
+export declare function extractWhat(content: string): string | undefined;
+/** Extract `human_context.who` — ## Audience / ## For Whom / ## Users */
+export declare function extractWho(content: string): string | undefined;
+/** Extract `human_context.why` — ## Why / ## Motivation / ## Problem */
+export declare function extractWhy(content: string): string | undefined;
+/** Extract `human_context.where` — ## Deployment / ## Where it runs / ## Install */
+export declare function extractWhere(content: string): string | undefined;
+/** Extract `human_context.when` — ## Status / ## History / "Production since" */
+export declare function extractWhen(content: string): string | undefined;
+/** Extract `human_context.how` — ## Architecture / ## How it works / ## Approach */
+export declare function extractHow(content: string): string | undefined;
+/** Read README.md and extract per-slot content. Returns {} if no README. */
+export declare function interrogateReadme(dir: string): ExtractedContext;

package/dist/interrogate/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Repo interrogation — extract slot content from README, Cargo.toml,
+ * package.json, etc., without guessing or substituting generic slop.
+ *
+ * Contract (per faf-auto-no-guess-no-slop doctrine):
+ *   - Each slot has a per-slot evidence anchor
+ *   - If the anchor is missing → leave empty (do NOT synthesize from other slots)
+ *   - If the anchor is present but content is generic / too long / structural →
+ *     leave empty (do NOT settle for slop)
+ *   - Empty is honest; wrong is a lie
+ *
+ * Per goal-is-not-a-6w doctrine:
+ *   - `project.goal` is the elevator pitch / use case — its own anchor
+ *   - Each `human_context.*` 6W has its own anchor
+ *   - No slot inherits from / is split-extracted from another
+ */
+/** Content extracted from a single source file (README, Cargo.toml, etc.) */
+export interface ExtractedContext {
+    project?: {
+        /** One-line elevator pitch / use case. README first prose paragraph,
+         *  ## Use Case section, or Cargo.toml description. */
+        goal?: string;
+    };
+    human_context?: {
+        /** Audience — "## Audience" / "for {audience}" patterns */
+        who?: string;
+        /** What's being built — "## About" / "## Description" / "X is..." */
+        what?: string;
+        /** Motivation — "## Why" / "## Motivation" / "Problem:" */
+        why?: string;
+        /** Where it runs — "## Deployment" / "## Where" / install-target */
+        where?: string;
+        /** Status / timeline — "## Status" / "Production since" / version line */
+        when?: string;
+        /** Approach — "## Architecture" / "## How it works" */
+        how?: string;
+    };
+}
+/** Confidence threshold rules for extracted text — empty if violated */
+export declare const EXTRACTION_LIMITS: {
+    /** Minimum length for a slot to be considered worth filling (in chars) */
+    readonly MIN_LENGTH: 8;
+    /** Maximum length — anything longer is documentation, not a slot fill */
+    readonly MAX_LENGTH: 280;
+};
+/** Generic slop patterns — extracted text matching these is rejected */
+export declare const SLOP_PATTERNS: readonly RegExp[];
+/** Validate extracted text against the no-guess/no-slop doctrine */
+export declare function isValidExtraction(text: string): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "faf-cli",
-  "version": "6.10.1",
-  "description": "Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-approved.",
+  "version": "6.12.0",
+  "description": "Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.",
   "type": "module",
   "icon": "https://faf.one/orange-smiley.svg",
   "logo": "https://faf.one/orange-smiley.svg",
@@ -25,7 +25,8 @@
   ],
   "scripts": {
     "dev": "bun src/cli.ts",
-    "build": "bun build src/cli.ts --outdir dist --target=node --minify --sourcemap=linked --external faf-scoring-kernel --external open && bun build src/index.ts --outdir dist --target=node --minify --sourcemap=linked --external faf-scoring-kernel --external open && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun build src/cli.ts --outdir dist --target=node --minify --sourcemap=linked --external faf-scoring-kernel --external open && bun build src/index.ts --outdir dist --target=node --minify --sourcemap=linked --external faf-scoring-kernel --external open && tsc -p tsconfig.build.json",
     "compile": "bun build src/cli.ts --compile --bytecode --minify --outfile faf",
     "compile:all": "bun build src/cli.ts --compile --bytecode --minify --target=bun-darwin-arm64 --outfile faf-darwin-arm64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-darwin-x64 --outfile faf-darwin-x64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-linux-x64 --outfile faf-linux-x64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-windows-x64 --outfile faf-windows-x64.exe",
     "test": "bun test --timeout=120000",

package/project.faf

@@ -26,7 +26,7 @@ stack:
   storage: slotignored
 human_context:
   who: Developers and teams using AI coding assistants
-  what: Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-approved.
+  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, v6.0 March 2026