@agentmarkup/astro 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @agentmarkup/astro
 
-Build-time `llms.txt`, optional `llms-full.txt`, JSON-LD, markdown mirrors, AI crawler `robots.txt`, headers, and validation for Astro websites.
+Build-time `llms.txt`, optional `llms-full.txt`, optional A2A Agent Cards, JSON-LD, markdown mirrors, AI crawler `robots.txt`, headers, and validation for Astro websites.
 
 `@agentmarkup/astro` is the Astro adapter in the `agentmarkup` package family. Framework-agnostic helpers live in `@agentmarkup/core`, Vite sites use `@agentmarkup/vite`, and Next.js sites use `@agentmarkup/next`.
 
@@ -91,6 +91,7 @@ export default defineConfig({
 
 ## What It Does
 
+- Generates optional `/.well-known/agent-card.json` for existing A2A services
 - Injects JSON-LD into built HTML pages during the Astro build
 - Generates `/llms.txt` from config
 - Generates optional `/llms-full.txt` with inlined same-site markdown content
@@ -114,6 +115,8 @@ When markdown mirrors are enabled, same-site page entries in `llms.txt` automati
 
 Enable `llmsFullTxt` when you want a richer companion file for agents that can consume more than the compact `llms.txt` manifest. The generated `llms-full.txt` keeps the same section structure but inlines same-site markdown mirror content when those mirrors exist.
 
+Enable `agentCard` when you already run a real A2A-compatible agent service and want Astro builds to publish its discovery file at `/.well-known/agent-card.json`. agentmarkup only emits and validates the static Agent Card. It does not implement the A2A runtime server or transport endpoints for you. When enabled, provide a `version`, at least one `supportedInterfaces` entry, and a non-empty description through either the top-level `description` or `agentCard.description`.
+
 ## Maintainer
 
 Copyright (c) 2026 [Sebastian Cochinescu](https://www.cochinescu.com). MIT License.

package/dist/index.js

@@ -1,11 +1,13 @@
 // src/index.ts
 import { existsSync } from "fs";
-import { readdir, readFile, writeFile } from "fs/promises";
-import { join, relative } from "path";
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path";
 import { fileURLToPath } from "url";
 import {
+  A2A_AGENT_CARD_FILE_NAME,
   collectSchemasForPage,
   filterJsonLdByExistingTypes,
+  generateAgentCard,
   generateLlmsFullTxt,
   generateLlmsTxtDiscoveryLink,
   generateMarkdownAlternateLink,
@@ -24,6 +26,8 @@ import {
   presetToJsonLd,
   printReport,
   resolveLlmsTxtSections,
+  validateAgentCardConfig,
+  validateAgentCardJson,
   validateExistingJsonLd,
   validateHtmlContent,
   validateLlmsTxt,
@@ -36,6 +40,7 @@ import {
 export * from "@agentmarkup/core";
 function agentmarkup(config) {
   const validationResults = [];
+  let agentCardStatus = "none";
   let llmsTxtEntries = 0;
   let llmsTxtSections = 0;
   let llmsTxtStatus = "none";
@@ -63,6 +68,7 @@ function agentmarkup(config) {
         const markdownByUrl = {};
         const availableMarkdownUrls = /* @__PURE__ */ new Set();
         const finalHtmlByFile = /* @__PURE__ */ new Map();
+        const shouldManageAgentCard = Boolean(config.agentCard) && config.agentCard?.enabled !== false;
         const advertiseLlmsTxt = Boolean(config.llmsTxt) || Boolean(publicDir && existsSync(join(publicDir, "llms.txt")));
         for (const htmlFile of htmlFiles) {
           const pagePath = pagePathFromOutputFile(outDir, htmlFile);
@@ -195,6 +201,39 @@ function agentmarkup(config) {
             );
           }
         }
+        if (shouldManageAgentCard) {
+          const outputAgentCardPath = join(outDir, A2A_AGENT_CARD_FILE_NAME);
+          const existingOutputAgentCard = await readTextFileIfExists(outputAgentCardPath);
+          const existingAgentCard = existingOutputAgentCard ?? (publicDir ? await readTextFileIfExists(join(publicDir, A2A_AGENT_CARD_FILE_NAME)) : null);
+          if (existingAgentCard && !config.agentCard?.replaceExisting) {
+            agentCardStatus = "preserved";
+            if (!existingOutputAgentCard) {
+              await writeTextFile(outputAgentCardPath, existingAgentCard);
+            }
+            if (!config.validation?.disabled) {
+              validationResults.push(...validateAgentCardJson(existingAgentCard));
+            }
+          } else {
+            const agentCardConfigIssues = validateAgentCardConfig(
+              config,
+              `/${A2A_AGENT_CARD_FILE_NAME}`
+            );
+            if (!config.validation?.disabled) {
+              validationResults.push(...agentCardConfigIssues);
+            }
+            if (!agentCardConfigIssues.some((result) => result.severity === "error")) {
+              const agentCardContent = generateAgentCard(config);
+              if (!agentCardContent) {
+                throw new Error("Agent Card generation returned no output for a valid config");
+              }
+              agentCardStatus = "generated";
+              await writeTextFile(outputAgentCardPath, agentCardContent);
+              if (!config.validation?.disabled) {
+                validationResults.push(...validateAgentCardJson(agentCardContent));
+              }
+            }
+          }
+        }
         const llmsTxtContent = generateLlmsTxt(config);
         if (llmsTxtContent) {
           const outputLlmsPath = join(outDir, "llms.txt");
@@ -289,6 +328,7 @@ function agentmarkup(config) {
         }
         printReport({
           label: "@agentmarkup/astro",
+          agentCardStatus,
           llmsTxtEntries,
           llmsTxtSections,
           llmsTxtStatus,
@@ -318,6 +358,10 @@ async function readTextFileIfExists(filePath) {
     throw error;
   }
 }
+async function writeTextFile(filePath, content) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, ensureTrailingNewline(content), "utf8");
+}
 async function findHtmlFiles(rootDir) {
   const entries = await readdir(rootDir, { withFileTypes: true });
   const htmlFiles = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentmarkup/astro",
-  "version": "0.4.0",
-  "description": "Build-time llms.txt, llms-full.txt, JSON-LD, markdown mirrors, headers, AI crawler controls, and validation for Astro",
+  "version": "0.5.0",
+  "description": "Build-time llms.txt, llms-full.txt, A2A Agent Cards, JSON-LD, markdown mirrors, headers, AI crawler controls, and validation for Astro",
   "type": "module",
   "license": "MIT",
   "author": "Sebastian Cochinescu <hello@animafelix.com> (https://animafelix.com)",
@@ -18,6 +18,8 @@
     "astro",
     "llms-txt",
     "llms-full",
+    "a2a",
+    "agent-card",
     "json-ld",
     "markdown",
     "schema-org",
@@ -27,6 +29,7 @@
     "headers",
     "ai-crawler",
     "machine-readable",
+    "seo",
     "validation",
     "geo"
   ],
@@ -42,7 +45,7 @@
     "dist"
   ],
   "dependencies": {
-    "@agentmarkup/core": "0.4.0"
+    "@agentmarkup/core": "0.5.0"
   },
   "peerDependencies": {
     "astro": ">=4.0.0"