faf-cli 8.1.0 → 8.2.0

package/dist/interop/cards.d.ts

@@ -2,8 +2,7 @@ import type { FafData } from '../core/types.js';
 import { type RenderedResult } from '../core/render-hash.js';
 import { type CatalogHost, type FafaDoc, type ProjectedA2A } from './pack.js';
 import { type ServerCardOptions } from './servercard.js';
-/** A2A extension URI — dereference, not the MCP `_meta` key `one.faf/context`. */
-export declare const A2A_CONTEXT_URI = "https://faf.one/ext/context/v1";
+export { A2A_CONTEXT_URI } from './context-block.js';
 export { A2A_PROTOCOL_BINDING, A2A_PROTOCOL_VERSION, FAF_MEDIA_TYPES, a2aEndpoints, a2aDoors, } from './pack.js';
 export type { FafaAgent, FafaCapability, FafaEndpoint, FafaDoc, ProjectedA2A } from './pack.js';
 export type CardTarget = 'a2a' | 'mcp' | 'registry' | 'catalog' | 'ard';
@@ -32,13 +31,15 @@ export interface AiCatalog {
     [key: string]: unknown;
 }
 export interface ProjectedCards {
-    block: Record<string, unknown>;
+    /** faf's context block — only when a project.faf was given (BEST). */
+    block?: Record<string, unknown>;
     a2a?: ProjectedA2A;
     mcp?: Record<string, unknown>;
     registry?: {
         name: string;
         title?: string;
-        _meta: Record<string, unknown>;
+        /** FAF's context block (BEST); absent from a plain registry identity (BETTER). */
+        _meta?: Record<string, unknown>;
     };
     catalog?: CatalogEntry[];
     /** The same rows, carrying ARD's search hints — the ARD manifest. */
@@ -50,23 +51,27 @@ export interface ProjectedCards {
 export declare function readFafa(path: string): FafaDoc;
 /** Discover agent.fafa / .fafa (cwd, then one parent). */
 export declare function findFafaFile(dir?: string): string | null;
-/** Build the A2A Agent Card (JSON) from a .fafa + .faf: the core card
- *  ({@link projectA2ACard}) carrying FAF's context extension. */
-export declare function buildA2ACard(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): ProjectedA2A;
+/** Build the A2A Agent Card (JSON) from a .fafa: the core card
+ *  ({@link projectA2ACard}). With a project.faf (BEST) it carries FAF's
+ *  context extension; with none (BETTER) it is the plain A2A card — the
+ *  .fafa is its source, and nothing on it points at a project.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;
 /**
- * The catalog rows for this agent, keyed exactly as the pack projector keys
- * them: `urn:air:{publisher}:{namespace}:{name}`, where the publisher is the
- * domain the `.fafa` *declares* (`agent.id`'s urn:air, `metadata.cards.domain`,
- * else the homepage host) and the name is the handle — never the display name,
- * which is free text and may carry spaces a URN may not.
+ * The catalog rows for this agent — the pack projector's own
+ * ({@link catalogRows}), so `faf cards` and the pack list the same rows: the
+ * A2A card (when the `.fafa` names an A2A door), the Server Card (when it names
+ * a remote MCP URL) and the `.fafa` itself, keyed
+ * `urn:air:{publisher}:{namespace}:{name}`, where the publisher is the domain
+ * the `.fafa` *declares* (`agent.id`'s urn:air, `metadata.cards.domain`, else
+ * the homepage host) and the name is the handle.
  *
  * Throws, rather than inventing either half, when the `.fafa` names no domain:
  * an identifier is a catalog's primary key, and `urn:air:local:…` published to
  * the world is worse than a refusal a line of YAML fixes.
  */
-export declare function catalogEntriesFor(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
+export declare function catalogEntriesFor(fafa: FafaDoc, faf?: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
 /** Upsert projector entries into an existing catalog. Leaves every other row
  *  alone: a row is faf's only when its identifier is exactly faf's (never by
  *  type or URL). On match, only url / type / updatedAt move — host copy
@@ -90,8 +95,22 @@ export declare function upsertCatalogText(text: string | null, incoming: Catalog
     text: string;
     changed: boolean;
 };
+/** The cards an agent.fafa gives with no project.faf (BETTER): the A2A card
+ *  (when it names an A2A door), the MCP Server Card (when it names a remote MCP
+ *  URL), the registry server.json (a remote or a package), the AI Catalog, ARD. */
+export declare function betterTargets(fafa: FafaDoc, opts?: ProjectCardsOptions): CardTarget[];
+/**
+ * Project the cards. The ladder — BETTER is the .fafa, BEST is project.faf:
+ * an agent.fafa alone gives the plain cards ({@link betterTargets}); a
+ * project.faf, resident and used, adds FAF's context block to each (the A2A
+ * card's extension, the Server Card's and server.json's `_meta`). A card's
+ * identity comes from the .fafa at both rungs. With a project.faf and no MCP
+ * endpoint in the .fafa (an MCP server's own repo), the Server Card and the
+ * registry identity come from project.faf, as `faf server-card` writes them.
+ */
 export declare function projectCards(input: {
-    faf: FafData;
+    /** project.faf — absent means BETTER. */
+    faf?: FafData;
     fafa?: FafaDoc;
     targets?: CardTarget[];
     opts?: ProjectCardsOptions;

package/dist/interop/context-block.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FAF's context block — what BEST adds to a card. Pure (no Node built-ins), so
+ * `faf cards` and the browser-safe pack projector add the same block.
+ *
+ * The cards ladder: an agent.fafa gives the plain cards (BETTER); a project.faf,
+ * resident and used, adds this block to each of them (BEST) — the A2A card's
+ * context extension, the Server Card's `_meta["one.faf/context"]`, the registry
+ * `server.json`'s publisher-provided `_meta`.
+ */
+import type { FafData } from '../core/types.js';
+/** project.faf's IANA media type. */
+export declare const FAF_MEDIA_TYPE = "application/vnd.faf+yaml";
+/** A2A extension URI — dereference, not the MCP `_meta` key `one.faf/context`. */
+export declare const A2A_CONTEXT_URI = "https://faf.one/ext/context/v1";
+export declare const REGISTRY_PUBLISHER_KEY = "io.modelcontextprotocol.registry/publisher-provided";
+export interface ContextBlockOptions {
+    /** 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 "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?: ContextBlockOptions): Record<string, unknown>;
+/**
+ * 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?: ContextBlockOptions): Record<string, unknown>;

package/dist/interop/pack.d.ts

@@ -1,3 +1,5 @@
+import type { FafData } from '../core/types.js';
+import { type ContextBlockOptions } from './context-block.js';
 export declare const A2A_PROTOCOL_BINDING = "JSONRPC";
 export declare const A2A_PROTOCOL_VERSION = "1.0";
 /** The three FAF-family media types, in family order. */
@@ -108,6 +110,16 @@ export declare function a2aEndpoints(fafa: FafaDoc): FafaEndpoint[];
 export declare function a2aDoors(fafa: FafaDoc, opts?: {
     doorUrl?: string;
 }): FafaEndpoint[];
+/**
+ * FAF's context extension for the A2A card (BEST). Its `params` are a superset
+ * of {@link fafContextBlock}, enriched with `.fafa`-specific identity that only
+ * makes sense for an agent card (agentId, passport, the full FAF media-type
+ * family). Nests the base block's `faf`/`mediaType` under `provenance` rather
+ * than flattening them, per the extension's own shape (`§7` of the field
+ * mapping). The Server Card and registry `_meta` stay on the plain
+ * {@link fafContextBlock} shape.
+ */
+export declare function fafaContextExtension(fafa: FafaDoc, faf: FafData, opts?: ContextBlockOptions): A2AExtension;
 /**
  * The A2A Agent Card from a `.fafa`: every field comes from the document, and
  * `capabilities.extensions` holds exactly the extensions passed (none by default).
@@ -154,10 +166,25 @@ export declare function fafaDomain(fafa: FafaDoc): string;
 export declare function fafaHandle(fafa: FafaDoc): string;
 /** MCP names are reverse-DNS: example.com + weather → com.example/weather. */
 export declare function mcpName(fafa: FafaDoc): string;
-/** The MCP Server Card for a remote MCP server. */
-export declare function projectServerCard(fafa: FafaDoc): Record<string, unknown>;
-/** The MCP Registry `server.json` (publishing it stays the owner's step). */
-export declare function projectServerJson(fafa: FafaDoc): Record<string, unknown>;
+/** The `.fafa`'s MCP endpoints at an http(s) URL — what a Server Card describes. */
+export declare function mcpRemotes(fafa: FafaDoc): Array<{
+    type: string;
+    url: string;
+}>;
+/** True when the `.fafa` gives a registry entry: a package or a remote MCP URL. */
+export declare function hasRegistryEntry(fafa: FafaDoc): boolean;
+/** The registry identity from the `.fafa`: `name`, and `title` when it has one. */
+export declare function registryIdentity(fafa: FafaDoc): {
+    name: string;
+    title?: string;
+};
+/** The MCP Server Card for a remote MCP server. With a project.faf (`faf`,
+ *  BEST) it carries FAF's context block at `_meta["one.faf/context"]`. */
+export declare function projectServerCard(fafa: FafaDoc, faf?: FafData, opts?: ContextBlockOptions): Record<string, unknown>;
+/** The MCP Registry `server.json` (publishing it stays the owner's step). With
+ *  a project.faf (`faf`, BEST) it carries FAF's context block in the registry's
+ *  publisher-provided `_meta`. */
+export declare function projectServerJson(fafa: FafaDoc, faf?: FafData, opts?: ContextBlockOptions): Record<string, unknown>;
 export type PackCard = 'a2a' | 'server_card' | 'server_json' | 'ai_catalog' | 'ard' | 'fafa';
 export interface CatalogRow {
     identifier: string;
@@ -168,11 +195,21 @@ export interface CatalogRow {
     version?: string;
     updatedAt: string;
 }
-/** One row per card the domain serves: the A2A card, the Server Card, and the `.fafa` only when asked. */
-export declare function catalogRows(fafa: FafaDoc, cards: PackCard[], opts?: {
+/** Options for the catalog rows. */
+export interface CatalogRowOptions {
+    /** `updatedAt` for the rows; otherwise now. */
     now?: string;
+    /** List the `.fafa` itself (served at /.well-known/fafa). Default true: it is
+     *  the source of the cards — what makes them BETTER. */
     listFafa?: boolean;
-}): CatalogRow[];
+    /** Public URL of the A2A card; default the domain's /.well-known/agent-card.json. */
+    a2aCardUrl?: string;
+    /** An A2A door when the `.fafa` names none (as `faf cards --door-url`). */
+    doorUrl?: string;
+}
+/** One row per card the domain serves: the A2A card (when the `.fafa` names an
+ *  A2A door), the Server Card (when it names a remote MCP URL), and the `.fafa`. */
+export declare function catalogRows(fafa: FafaDoc, cards: PackCard[], opts?: CatalogRowOptions): CatalogRow[];
 /** Who publishes a catalog: AI Catalog's `host` object. */
 export interface CatalogHost {
     displayName: string;
@@ -189,10 +226,7 @@ export interface CatalogHost {
  */
 export declare function catalogHost(fafa: FafaDoc): CatalogHost | undefined;
 /** The AI Catalog for the domain: every row above, with the host named. */
-export declare function projectAiCatalog(fafa: FafaDoc, cards: PackCard[], opts?: {
-    now?: string;
-    listFafa?: boolean;
-}): Record<string, unknown>;
+export declare function projectAiCatalog(fafa: FafaDoc, cards: PackCard[], opts?: CatalogRowOptions): Record<string, unknown>;
 /**
  * The search hints ARD reads, from the `.fafa`: `metadata.cards.keywords` and
  * `metadata.cards.examples`. An entry with no `representativeQueries` is, in
@@ -206,19 +240,20 @@ export declare function ardHints(fafa: FafaDoc): {
 /** The ARD manifest: the catalog, plus the search hints ARD reads. ARD builds
  *  on ai-catalog (spec §4), so the document is the same shape — the entries
  *  carry more. */
-export declare function projectArd(fafa: FafaDoc, cards: PackCard[], opts?: {
-    now?: string;
-    listFafa?: boolean;
-}): Record<string, unknown>;
-export interface PackOptions {
+export declare function projectArd(fafa: FafaDoc, cards: PackCard[], opts?: CatalogRowOptions): Record<string, unknown>;
+export interface PackOptions extends ContextBlockOptions {
     /** Which cards to build; the `.fafa` is always written. */
     cards: PackCard[];
     /** `updatedAt` for catalog rows (tests); otherwise now. */
     now?: string;
-    /** List the `.fafa` itself in the catalog and ARD manifest (it is then served at /.well-known/fafa). */
+    /** List the `.fafa` itself in the catalog and ARD manifest (it is then served
+     *  at /.well-known/fafa). Default true; `false` leaves it out. */
     listFafa?: boolean;
-    /** Extensions to put on the A2A card; none by default. */
+    /** Extensions to put on the A2A card, besides FAF's own (added with `faf`). */
     a2aExtensions?: A2AExtension[];
+    /** project.faf (BEST): adds FAF's context block to the A2A card, the Server
+     *  Card and server.json. Without it the cards are plain (BETTER). */
+    faf?: FafData;
 }
 export interface Pack {
     fafa: FafaDoc;

package/dist/interop/servercard.d.ts

@@ -1,4 +1,5 @@
 import type { FafData } from '../core/types.js';
+export { REGISTRY_PUBLISHER_KEY, fafContextBlock, registryMeta } from './context-block.js';
 /**
  * Build an MCP Server Card (SEP-2127) from a .faf.
  *
@@ -25,27 +26,8 @@ export interface ServerCardOptions {
     /** 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 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`.
- *
- * 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
@@ -99,8 +81,9 @@ export interface ServerJsonIdentity {
     title?: string;
     /** A version to set (`--set-version`); when undefined the file's own is kept. */
     version?: string;
-    /** The `_meta` faf writes ({@link registryMeta}). */
-    meta: Record<string, unknown>;
+    /** The `_meta` faf writes ({@link registryMeta}); absent for a plain
+     *  registry identity from a .fafa (BETTER), which leaves `_meta` as it is. */
+    meta?: Record<string, unknown>;
 }
 /**
  * Put faf's identity into the text of a registry `server.json`, changing