@intentius/chant 0.83.0 → 0.85.0

package/src/cli/main.test.ts

@@ -688,6 +688,26 @@ describe("workspace records (#2546)", () => {
   });
 });
 
+describe("workspace graph --composites (#2662)", () => {
+  test("parses as a boolean on workspace graph", () => {
+    const args = parseArgs(["workspace", "graph", "--composites", "--at", "HEAD", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "graph", composites: true, at: "HEAD", json: true });
+    expect(() => parseArgs(["workspace", "graph", "--composites=yes"])).toThrow();
+    expect(resolveCommand(args, commandRegistry)?.def.name).toBe("workspace graph");
+  });
+});
+
+describe("workspace graph --intent (#2651)", () => {
+  test("parses the region and every --kind, in order", () => {
+    const args = parseArgs(["workspace", "graph", "--intent", "app/server.mjs:3-7", "--kind", "a.kind.mjs", "--kind", "b.kind.mjs", "--at", "HEAD", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "graph", intent: "app/server.mjs:3-7", kinds: ["a.kind.mjs", "b.kind.mjs"], kind: "b.kind.mjs", at: "HEAD", json: true });
+    expect(parseArgs(["workspace", "graph", "--intent=app"]).intent).toBe("app");
+    expect(() => parseArgs(["workspace", "graph", "--intent"])).toThrow(/--intent needs a region/);
+    expect(() => parseArgs(["workspace", "graph", "--intent", "--json"])).toThrow(/--intent needs a region/);
+    expect(resolveCommand(args, commandRegistry)?.def.name).toBe("workspace graph");
+  });
+});
+
 describe("workspace init and ls (#2534)", () => {
   test("resolve to their commands in the one workspace group, with the directory as extra positional", () => {
     const ls = parseArgs(["workspace", "ls", "examples", "--at", "HEAD", "--json"]);

package/src/cli/main.ts

@@ -69,6 +69,7 @@ const BOOLEAN_FLAGS = new Set([
   "--strict",
   "--validate",
   "--use-composites",
+  "--composites",
   "--stacks",
   "--components",
   "--up",
@@ -363,6 +364,15 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records|graph|check --kind <kind file>` (#2546, #2549)
       result.kind = args[++i];
       if (!result.kind || result.kind.startsWith("-")) throw new Error("--kind needs a kind file: --kind <path>");
+      // Repeatable for `workspace graph --intent` (#2651); the others read the last one.
+      (result.kinds ??= []).push(result.kind);
+    } else if (arg === "--composites") {
+      // `chant workspace graph --composites` (#2662)
+      result.composites = true;
+    } else if (arg === "--intent") {
+      // `chant workspace graph --intent <path[:start-end]>` (#2651)
+      result.intent = args[++i];
+      if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
     } else if (arg === "--current") {
       result.current = true;
     } else if (arg === "--require") {
@@ -767,6 +777,14 @@ Workspace (level 1, #2524):
                         read-contract document. --at <rev> runs each member's
                         source as it was at that commit; --kind adds the
                         records' asset and constrains links
+  workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
+                        Each composite instance the members declare, with the
+                        components whose contract can deploy it; an instance
+                        with none lists an empty set
+  workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
+                        The intent graph over one region: the commits that
+                        touched it, the decisions whose constrains cover it,
+                        the artifacts they pin, and findings with closed codes
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/mcp/resource-handlers.ts

@@ -1,6 +1,8 @@
 import { resolve, join, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
 import type { ResourceDefinition } from "./types";
+import type { LexiconPlugin } from "../../lexicon";
+import { collectComposites } from "./tools/composites";
 import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
@@ -44,6 +46,12 @@ export const coreResourceDefinitions: ResourceDefinition[] = [
     description: "Latest run state for a named Op",
     mimeType: "application/json",
   },
+  {
+    uri: "chant://composites",
+    name: "Composite catalog",
+    description: "Every composite the loaded lexicons export, with what each bundles and its parameters (#2662)",
+    mimeType: "application/json",
+  },
   {
     uri: "chant://knowledge",
     name: "Knowledge bundle",
@@ -99,9 +107,18 @@ export function collectExamples(
 export async function handleResourcesRead(
   params: Record<string, unknown>,
   pluginResources: Map<string, PluginResourceEntry>,
+  plugins: LexiconPlugin[] = [],
 ): Promise<unknown> {
   const uri = params.uri as string;
 
+  // The whole composite catalog (#2662), static data from each lexicon's
+  // `composites()`; the `composites` tool filters the same list.
+  if (uri === "chant://composites") {
+    return {
+      contents: [{ uri, mimeType: "application/json", text: JSON.stringify(collectComposites(plugins), null, 2) }],
+    };
+  }
+
   if (uri === "chant://context") {
     return {
       contents: [

package/src/cli/mcp/server.test.ts

@@ -778,6 +778,142 @@ describe("McpServer", () => {
     });
   });
 
+  // -----------------------------------------------------------------------
+  // Composite catalog (#2662)
+  // -----------------------------------------------------------------------
+
+  describe("composite catalog", () => {
+    const awsLike = createMockPlugin({
+      name: "aws",
+      composites: () => [
+        {
+          name: "LambdaSqs",
+          lexicon: "aws",
+          description: "A Lambda function fed by an SQS queue through an event source mapping.",
+          bundles: ["EventSourceMapping", "Function", "Queue", "Role"],
+          params: [{ name: "queueName", type: "Value<string>", required: false }],
+        },
+        {
+          name: "VpcDefault",
+          lexicon: "aws",
+          description: "A VPC with public and private subnets.",
+          bundles: ["Subnet", "Vpc"],
+          params: [{ name: "cidr", type: "string", required: false }],
+        },
+      ],
+      mcpResources: () => [
+        {
+          uri: "resource-catalog",
+          name: "Catalog",
+          description: "Resource catalog",
+          mimeType: "application/json",
+          handler: async () => JSON.stringify([
+            { className: "Queue", resourceType: "AWS::SQS::Queue", kind: "resource" },
+          ]),
+        },
+      ],
+    });
+    const k8sLike = createMockPlugin({
+      name: "k8s",
+      composites: () => [
+        {
+          name: "WebApp",
+          lexicon: "k8s",
+          description: "A Deployment and Service.",
+          bundles: ["Deployment", "Service"],
+          params: [{ name: "image", type: "string", required: true }],
+        },
+      ],
+    });
+    const noComposites = createMockPlugin({ name: "cedar" });
+
+    async function call(s: McpServer, name: string, args: Record<string, unknown>) {
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name, arguments: args },
+      });
+      return JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+    }
+
+    test("the composites tool answers what a lexicon has, with bundles and params", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const parsed = await call(s, "composites", { lexicon: "aws" });
+      expect(parsed.total).toBe(2);
+      expect(parsed.composites.map((c: { name: string }) => c.name)).toEqual(["LambdaSqs", "VpcDefault"]);
+      expect(parsed.composites[0].bundles).toContain("Queue");
+      expect(parsed.composites[0].params[0].name).toBe("queueName");
+      expect(parsed.lexicons).toEqual(["aws", "k8s", "cedar"]);
+    });
+
+    test("with no filter it lists every lexicon's composites; a lexicon with none adds nothing", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const parsed = await call(s, "composites", {});
+      expect(parsed.total).toBe(3);
+      expect((await call(s, "composites", { lexicon: "cedar" })).total).toBe(0);
+    });
+
+    test("query matches a bundled kind, and a name match ranks first", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const byKind = await call(s, "composites", { query: "queue" });
+      expect(byKind.composites.map((c: { name: string }) => c.name)).toEqual(["LambdaSqs"]);
+      const byName = await call(s, "composites", { query: "vpc" });
+      expect(byName.composites[0].name).toBe("VpcDefault");
+      expect((await call(s, "composites", { limit: 1 })).composites).toHaveLength(1);
+    });
+
+    test("chant://composites lists the whole catalog", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const list = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "resources/list" });
+      const uris = (list.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri);
+      expect(uris).toContain("chant://composites");
+
+      const read = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "resources/read",
+        params: { uri: "chant://composites" },
+      });
+      const contents = (read.result as { contents: Array<{ mimeType: string; text: string }> }).contents;
+      expect(contents[0].mimeType).toBe("application/json");
+      const catalog = JSON.parse(contents[0].text);
+      expect(catalog.map((c: { lexicon: string; name: string }) => `${c.lexicon}:${c.name}`)).toEqual([
+        "aws:LambdaSqs", "aws:VpcDefault", "k8s:WebApp",
+      ]);
+    });
+
+    test("chant://composites is an empty list with no plugins", async () => {
+      const read = await new McpServer().handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "resources/read",
+        params: { uri: "chant://composites" },
+      });
+      const contents = (read.result as { contents: Array<{ text: string }> }).contents;
+      expect(JSON.parse(contents[0].text)).toEqual([]);
+    });
+
+    test("search finds a resource type and the composite that bundles it", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const parsed = await call(s, "search", { query: "queue" });
+      expect(parsed.total).toBe(2);
+      const kinds = parsed.results.map((r: { kind: string }) => r.kind).sort();
+      expect(kinds).toEqual(["composite", "resource"]);
+      const composite = parsed.results.find((r: { kind: string }) => r.kind === "composite");
+      expect(composite).toMatchObject({ name: "LambdaSqs", lexicon: "aws", bundles: expect.arrayContaining(["Queue"]) });
+      expect(composite.params).toBeUndefined();
+    });
+
+    test("search's lexicon filter applies to composites too", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const parsed = await call(s, "search", { query: "deployment", lexicon: "aws" });
+      expect(parsed.total).toBe(0);
+      const k8s = await call(s, "search", { query: "deployment", lexicon: "k8s" });
+      expect(k8s.results.map((r: { name: string }) => r.name)).toEqual(["WebApp"]);
+    });
+  });
+
   // -----------------------------------------------------------------------
   // Scaffold tool with plugins
   // -----------------------------------------------------------------------
@@ -1466,23 +1602,23 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(13);
+      expect(tools).toHaveLength(14);
       expect(tools.map((t) => t.name).sort()).toEqual([
-        "build", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
+        "build", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
         "op-approve", "op-list", "op-report", "op-run", "op-status",
         "scaffold", "search",
       ]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
-      expect(resources).toHaveLength(8);
+      expect(resources).toHaveLength(9);
     });
 
     test("server with empty plugins array works", async () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(13);
+      expect(tools).toHaveLength(14);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -6,6 +6,7 @@ import { importTool, handleImport } from "./tools/import";
 import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
+import { compositesTool, createCompositesHandler } from "./tools/composites";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
@@ -90,8 +91,10 @@ export class McpServer {
   private tools: Map<string, ToolDefinition> = new Map();
   private toolHandlers: Map<string, ToolHandler> = new Map();
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
+  private plugins: LexiconPlugin[];
 
   constructor(plugins?: LexiconPlugin[]) {
+    this.plugins = plugins ?? [];
     // Register core tools
     this.registerTool(buildTool, handleBuild);
     this.registerTool(lintTool, handleLint);
@@ -99,6 +102,7 @@ export class McpServer {
     this.registerTool(explainTool, handleExplain);
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
+    this.registerTool(compositesTool, createCompositesHandler(plugins ?? []));
 
     // Register state tools
     const snapshot = createSnapshotTool(plugins ?? []);
@@ -252,7 +256,7 @@ export class McpServer {
         return buildResourcesList(this.pluginResources);
 
       case "resources/read":
-        return handleResourcesRead(params, this.pluginResources);
+        return handleResourcesRead(params, this.pluginResources, this.plugins);
 
       default:
         throw new Error(`Unknown method: ${method}`);

package/src/cli/mcp/tools/composites.ts

@@ -0,0 +1,98 @@
+import type { CompositeEntry, LexiconPlugin } from "../../../lexicon";
+
+/**
+ * The `composites` tool (#2662): what composites the loaded lexicons export,
+ * what each one bundles and what it takes. "What composites do you have for
+ * aws?" is `{ lexicon: "aws" }`.
+ *
+ * Everything here reads `LexiconPlugin.composites()`, which is static catalog
+ * data. No composite is loaded or called and no provider is asked anything.
+ */
+export const compositesTool = {
+  name: "composites",
+  description:
+    "List the composites the loaded lexicons export: what each builds, the resource kinds it bundles, and its parameters",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      lexicon: {
+        type: "string",
+        description: "Only composites from this lexicon (e.g. 'aws', 'k8s')",
+      },
+      query: {
+        type: "string",
+        description: "Keyword matched against the composite's name, description, bundled resource kinds and parameter names",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of composites to return (default: 50)",
+      },
+    },
+  },
+};
+
+/**
+ * Every composite the plugins contribute, in plugin order. A plugin whose
+ * `composites()` throws contributes nothing rather than failing the listing.
+ */
+export function collectComposites(plugins: LexiconPlugin[]): CompositeEntry[] {
+  const entries: CompositeEntry[] = [];
+  for (const plugin of plugins) {
+    let contributed: CompositeEntry[] = [];
+    try {
+      contributed = plugin.composites?.() ?? [];
+    } catch {
+      contributed = [];
+    }
+    for (const entry of contributed) entries.push({ ...entry, lexicon: entry.lexicon || plugin.name });
+  }
+  return entries;
+}
+
+/**
+ * How well an entry matches a lowercased keyword: 0 for no match, higher for
+ * better. A name match beats a bundled kind, which beats a word in the
+ * description or a parameter name, so `queue` lists `LambdaSqs` ahead of a
+ * composite that merely mentions queues.
+ */
+export function compositeMatchScore(entry: CompositeEntry, lowerQuery: string): number {
+  const name = entry.name.toLowerCase();
+  if (name.startsWith(lowerQuery)) return 4;
+  if (name.includes(lowerQuery)) return 3;
+  if (entry.bundles.some((b) => b.toLowerCase().includes(lowerQuery))) return 2;
+  if (entry.description.toLowerCase().includes(lowerQuery)) return 1;
+  if (entry.params.some((p) => p.name.toLowerCase().includes(lowerQuery))) return 1;
+  return 0;
+}
+
+export function createCompositesHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const lexicon = typeof params.lexicon === "string" && params.lexicon !== "" ? params.lexicon : undefined;
+    const query = typeof params.query === "string" && params.query !== "" ? params.query : undefined;
+    const limit = typeof params.limit === "number" ? params.limit : 50;
+
+    let entries = collectComposites(plugins);
+    if (lexicon) entries = entries.filter((e) => e.lexicon === lexicon);
+
+    if (query) {
+      const lowerQuery = query.toLowerCase();
+      entries = entries
+        .map((entry) => ({ entry, score: compositeMatchScore(entry, lowerQuery) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+        .map(({ entry }) => entry);
+    }
+
+    return {
+      ...(lexicon ? { lexicon } : {}),
+      ...(query ? { query } : {}),
+      // The loaded lexicons, so an empty answer for `lexicon: "cedar"` reads
+      // as "cedar exports none" when cedar is listed, and "not loaded" when not.
+      lexicons: plugins.map((p) => p.name),
+      total: entries.length,
+      composites: entries.slice(0, limit),
+    };
+  };
+}

package/src/cli/mcp/tools/search.ts

@@ -1,17 +1,20 @@
 import type { LexiconPlugin } from "../../../lexicon";
+import { collectComposites, compositeMatchScore } from "./composites";
 
 /**
  * Search tool definition for MCP
  */
 export const searchTool = {
   name: "search",
-  description: "Search the resource catalog across loaded lexicons by keyword",
+  description:
+    "Search the resource catalog and the composite catalog across loaded lexicons by keyword; a composite comes back with kind 'composite'",
   inputSchema: {
     type: "object" as const,
     properties: {
       query: {
         type: "string",
-        description: "Search query — matches against resource type, class name, and kind",
+        description:
+          "Search query: matches a resource's type, class name and kind, and a composite's name, description and the resource kinds it bundles",
       },
       lexicon: {
         type: "string",
@@ -32,6 +35,20 @@ interface CatalogEntry {
   kind?: string;
 }
 
+/** A composite in search results (#2662): `kind` is always `"composite"`. */
+interface CompositeResult {
+  kind: "composite";
+  name: string;
+  description: string;
+  bundles: string[];
+}
+
+type SearchResult = (CatalogEntry | CompositeResult) & { lexicon: string; score: number };
+
+function sortKey(result: SearchResult): string {
+  return "resourceType" in result ? result.resourceType ?? "" : result.name;
+}
+
 /**
  * Create a search handler with access to loaded plugins
  */
@@ -44,7 +61,7 @@ export function createSearchHandler(
     const limit = (params.limit as number) ?? 20;
 
     const lowerQuery = query.toLowerCase();
-    const results: Array<CatalogEntry & { lexicon: string; score: number }> = [];
+    const results: SearchResult[] = [];
 
     const candidates = lexiconFilter
       ? plugins.filter((p) => p.name === lexiconFilter)
@@ -86,10 +103,35 @@ export function createSearchHandler(
       }
     }
 
-    // Sort: prefix matches first, then alphabetical by resourceType
+    // Composites (#2662), so one query finds both a resource type and the
+    // composite that bundles it. A name or bundled-kind prefix ranks with the
+    // resource prefix matches. The full entry (params included) is the
+    // `composites` tool's answer; search keeps a result short.
+    for (const entry of collectComposites(candidates)) {
+      const score = compositeMatchScore(entry, lowerQuery);
+      if (score === 0) continue;
+      const isPrefix =
+        entry.name.toLowerCase().startsWith(lowerQuery) ||
+        entry.bundles.some((b) => b.toLowerCase().startsWith(lowerQuery));
+      results.push({
+        kind: "composite",
+        name: entry.name,
+        description: entry.description,
+        bundles: entry.bundles,
+        lexicon: entry.lexicon,
+        score: isPrefix ? 1 : 0,
+      });
+    }
+
+    // Sort: prefix matches first; within a tier composites ahead of resource
+    // types, since a handful of composites would otherwise sort behind every
+    // `AWS::...` type the same word prefixes; then alphabetical.
     results.sort((a, b) => {
       if (a.score !== b.score) return b.score - a.score;
-      return (a.resourceType ?? "").localeCompare(b.resourceType ?? "");
+      const aComposite = a.kind === "composite" ? 0 : 1;
+      const bComposite = b.kind === "composite" ? 0 : 1;
+      if (aComposite !== bComposite) return aComposite - bComposite;
+      return sortKey(a).localeCompare(sortKey(b));
     });
 
     const limited = results.slice(0, limit);

package/src/cli/registry.ts

@@ -283,6 +283,12 @@ export interface ParsedArgs {
   at?: string;
   /** `chant workspace records --kind <path>` (#2546): the record kind file to read records through. */
   kind?: string;
+  /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
+  kinds?: string[];
+  /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
+  composites?: boolean;
+  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
+  intent?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */

package/src/components/cli-support.test.ts

@@ -389,6 +389,22 @@ export const backup =
     expect(result.composites?.["aws-plane"]).toEqual(["ArtifactBucket", "OperatorRole"]);
     expect(result.composites?.plain).toBeUndefined();
   });
+
+  test("carries each component's archetype, declared or inferred (#2662)", async () => {
+    await writeFile(
+      join(testDir, "lib.component.ts"),
+      `export const lib = { name: "lib", archetype: "service", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "plain.component.ts"),
+      `export const plain = { name: "plain", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+
+    const result = await computeComponentGraph(testDir);
+
+    expect(result.success).toBe(true);
+    expect(result.archetypes).toEqual({ lib: "service", plain: "infra" });
+  });
 });
 
 // ── runComponents (#585) ─────────────────────────────────────────────────────

package/src/components/cli-support.ts

@@ -25,7 +25,7 @@
 import { lexiconModulePath, lexiconNames } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
-import { projectToJson, type Archetype } from "./component";
+import { inferArchetype, projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
   runInterpretDriver,
@@ -152,6 +152,10 @@ export interface ComponentGraphResult {
    * entirely rather than defaulting to a guess; a consumer with no entry here
    * keeps applying its own naming-convention default. */
   composites?: Record<string, string[]>;
+  /** Component name → its archetype, declared or inferred from the composition
+   * (`inferArchetype`), so a reader can label a component without its source
+   * (#2662). */
+  archetypes?: Record<string, Archetype>;
   error?: string;
 }
 
@@ -187,7 +191,9 @@ export async function computeComponentGraph(
   // component name → declared composite kind(s) (#1492), only for components
   // that declared them — no identity fallback (see ComponentGraphResult doc).
   const composites: Record<string, string[]> = {};
+  const archetypes: Record<string, Archetype> = {};
   for (const [name, discovered] of result.components) {
+    archetypes[name] = discovered.component.archetype ?? inferArchetype(discovered.component);
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
     liveNames[name] = declared && declared.length > 0 ? [...declared] : [name];
@@ -201,7 +207,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames, composites };
+    return { success: true, order, waves, edges, files, liveNames, composites, archetypes };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };

package/src/composite.ts

@@ -71,6 +71,15 @@ export function isCompositeInstance(value: unknown): value is CompositeInstance
   );
 }
 
+/**
+ * Type guard: is this value a composite definition, what `Composite()` and
+ * `withDefaults()` return? A lexicon's composite catalog test uses it to find
+ * the composites a module exports (#2662).
+ */
+export function isCompositeDefinition(value: unknown): value is CompositeDefinition<unknown> {
+  return typeof value === "function" && typeof (value as { compositeName?: unknown }).compositeName === "string";
+}
+
 /**
  * Global registry of composite definitions.
  */

package/src/lexicon.ts

@@ -28,6 +28,7 @@ import type { BehaviourKinds } from "./behaviour-kinds";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
+import type { Archetype } from "./components/component";
 
 // Re-exported so a lexicon that hosts Op runs (#2121) can type its
 // `opRuntime` from the same entry it imports the plugin contract from.
@@ -929,6 +930,45 @@ export interface AuditEntitiesInput {
   baseDir?: string;
 }
 
+/**
+ * One parameter of a composite, read from the composite's declared props type
+ * (#2662).
+ */
+export interface CompositeParam {
+  /** The prop name as a caller writes it. */
+  name: string;
+  /** The declared TypeScript type, as source text (long inline types are shortened). */
+  type: string;
+  /** False when the prop is optional. */
+  required: boolean;
+  /** The prop's JSDoc summary, when it has one. */
+  description?: string;
+}
+
+/**
+ * A composite this lexicon exports, as static catalog data (#2662).
+ *
+ * The catalog is what `chant serve mcp` answers "what composites do you have
+ * for aws?" from: the `composites` tool, the `chant://composites` resource and
+ * `search` results of kind `composite` all read it, and none of them calls a
+ * provider. A lexicon writes it once, from source, and a test in the lexicon
+ * holds it to the composites the package actually exports.
+ */
+export interface CompositeEntry {
+  /** The exported name a caller imports (an alias gets its own entry). */
+  name: string;
+  /** The lexicon that exports it. */
+  lexicon: string;
+  /** One line saying what it builds. */
+  description: string;
+  /** Resource kinds (the lexicon's class names) its members are, nested composites flattened. */
+  bundles: string[];
+  /** Its props, from the declared props type. */
+  params: CompositeParam[];
+  /** The component archetype that ships it, when that is known. */
+  archetype?: Archetype;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -1212,6 +1252,13 @@ export interface LexiconPlugin {
   /** Generate documentation pages */
   docs?(options?: { verbose?: boolean }): Promise<void>;
 
+  /**
+   * The composites this lexicon exports, as static data (#2662). Read by the
+   * MCP `composites` tool, the `chant://composites` resource and `search`.
+   * Omit for a lexicon that exports no composites.
+   */
+  composites?(): CompositeEntry[];
+
   // MCP
   /** Return MCP tool contributions */
   mcpTools?(): McpToolContribution[];