@agentmarkup/astro 0.3.4 → 0.5.0

package/README.md

@@ -1,6 +1,8 @@
 # @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`.
 
 ## Install
 
@@ -89,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
@@ -112,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,15 +1,20 @@
 // 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,
   generatePageMarkdown,
   generateJsonLdTags,
   generateLlmsTxt,
+  hasLlmsTxtDiscoveryLink,
   hasExistingJsonLdScripts,
   injectHeadContent,
   injectJsonLdTags,
@@ -20,18 +25,27 @@ import {
   patchRobotsTxt,
   presetToJsonLd,
   printReport,
+  resolveLlmsTxtSections,
+  validateAgentCardConfig,
+  validateAgentCardJson,
   validateExistingJsonLd,
   validateHtmlContent,
   validateLlmsTxt,
+  validateLlmsTxtMarkdownCoverage,
+  validateMarkdownAlternateLink,
+  validateMarkdownContent,
   validateRobotsTxt,
   validateSchema
 } from "@agentmarkup/core";
 export * from "@agentmarkup/core";
 function agentmarkup(config) {
   const validationResults = [];
+  let agentCardStatus = "none";
   let llmsTxtEntries = 0;
   let llmsTxtSections = 0;
   let llmsTxtStatus = "none";
+  let llmsFullTxtEntries = 0;
+  let llmsFullTxtStatus = "none";
   let jsonLdPages = 0;
   let markdownPages = 0;
   let markdownPagesStatus = "none";
@@ -50,6 +64,12 @@ function agentmarkup(config) {
       "astro:build:done": async ({ dir }) => {
         const outDir = fileURLToPath(dir);
         const htmlFiles = await findHtmlFiles(outDir);
+        const resolvedLlmsSections = resolveLlmsTxtSections(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);
           const html = await readFile(htmlFile, "utf8");
@@ -60,12 +80,18 @@ function agentmarkup(config) {
             validationResults.push(...validateHtmlContent(nextHtml, pagePath));
             validationResults.push(...validateExistingJsonLd(nextHtml, pagePath));
           }
+          if (advertiseLlmsTxt && !hasLlmsTxtDiscoveryLink(nextHtml)) {
+            nextHtml = injectHeadContent(nextHtml, generateLlmsTxtDiscoveryLink());
+          }
           if (isFeatureEnabled(config.markdownPages) && pagePath && !hasMarkdownAlternateLink(nextHtml)) {
             nextHtml = injectHeadContent(
               nextHtml,
               generateMarkdownAlternateLink(pagePath)
             );
           }
+          if (isFeatureEnabled(config.markdownPages) && !config.validation?.disabled) {
+            validationResults.push(...validateMarkdownAlternateLink(nextHtml, pagePath));
+          }
           if (schemas.length === 0) {
             if (pagePath && config.validation?.warnOnMissingSchema && !config.validation.disabled && !hasExistingJsonLd) {
               validationResults.push({
@@ -77,6 +103,7 @@ function agentmarkup(config) {
             if (nextHtml !== html) {
               await writeFile(htmlFile, nextHtml, "utf8");
             }
+            finalHtmlByFile.set(htmlFile, nextHtml);
             continue;
           }
           const jsonLdObjects = schemas.map(presetToJsonLd);
@@ -90,11 +117,13 @@ function agentmarkup(config) {
             if (nextHtml !== html) {
               await writeFile(htmlFile, nextHtml, "utf8");
             }
+            finalHtmlByFile.set(htmlFile, nextHtml);
             continue;
           }
           const tags = generateJsonLdTags(injectables);
           nextHtml = injectJsonLdTags(nextHtml, tags);
           await writeFile(htmlFile, nextHtml, "utf8");
+          finalHtmlByFile.set(htmlFile, nextHtml);
           jsonLdPages += 1;
         }
         if (isFeatureEnabled(config.markdownPages)) {
@@ -104,8 +133,9 @@ function agentmarkup(config) {
             const relativeHtmlPath = relative(outDir, htmlFile).replace(/\\/g, "/");
             const markdownFileName = markdownFileNameFromHtmlFile(relativeHtmlPath);
             const outputMarkdownPath = join(outDir, markdownFileName);
-            const html = await readFile(htmlFile, "utf8");
+            const html = finalHtmlByFile.get(htmlFile) ?? await readFile(htmlFile, "utf8");
             const pagePath = pagePathFromOutputFile(outDir, htmlFile);
+            const markdownAbsoluteUrl = buildAbsoluteMarkdownUrl(config.site, pagePath);
             const markdown = generatePageMarkdown({
               html,
               pagePath,
@@ -118,20 +148,32 @@ function agentmarkup(config) {
             const existingMarkdown = existingOutputMarkdown ?? (publicDir ? await readTextFileIfExists(join(publicDir, markdownFileName)) : null);
             if (existingMarkdown && !config.markdownPages?.replaceExisting) {
               preservedMarkdownPages += 1;
+              markdownByUrl[markdownAbsoluteUrl] = existingMarkdown;
+              availableMarkdownUrls.add(markdownAbsoluteUrl);
               markdownCanonicalEntries.push({
                 markdownPath: `/${markdownFileName}`,
                 canonicalUrl: buildCanonicalUrl(config.site, pagePath)
               });
+              if (!config.validation?.disabled) {
+                validationResults.push(
+                  ...validateMarkdownContent(existingMarkdown, pagePath)
+                );
+              }
               if (!existingOutputMarkdown) {
                 await writeFile(outputMarkdownPath, existingMarkdown, "utf8");
               }
               continue;
             }
             await writeFile(outputMarkdownPath, markdown, "utf8");
+            markdownByUrl[markdownAbsoluteUrl] = markdown;
+            availableMarkdownUrls.add(markdownAbsoluteUrl);
             markdownCanonicalEntries.push({
               markdownPath: `/${markdownFileName}`,
               canonicalUrl: buildCanonicalUrl(config.site, pagePath)
             });
+            if (!config.validation?.disabled) {
+              validationResults.push(...validateMarkdownContent(markdown, pagePath));
+            }
             markdownPages += 1;
           }
           markdownPagesStatus = markdownPages > 0 ? "generated" : preservedMarkdownPages > 0 ? "preserved" : "none";
@@ -150,6 +192,47 @@ function agentmarkup(config) {
               await writeFile(outputHeadersPath, patchedHeaders, "utf8");
             }
           }
+          if (!config.validation?.disabled && resolvedLlmsSections.length > 0) {
+            validationResults.push(
+              ...validateLlmsTxtMarkdownCoverage(
+                resolvedLlmsSections,
+                availableMarkdownUrls
+              )
+            );
+          }
+        }
+        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) {
@@ -177,6 +260,36 @@ function agentmarkup(config) {
             }
           }
         }
+        if (config.llmsFullTxt?.enabled) {
+          const llmsFullTxtContent = generateLlmsFullTxt(config, {
+            contentByUrl: markdownByUrl
+          });
+          if (llmsFullTxtContent) {
+            const outputLlmsFullPath = join(outDir, "llms-full.txt");
+            const inlineEntries = countInlinedLlmsFullEntries(
+              resolvedLlmsSections,
+              markdownByUrl
+            );
+            const existingOutputLlmsFull = await readTextFileIfExists(outputLlmsFullPath);
+            const existingLlmsFull = existingOutputLlmsFull ?? (publicDir ? await readTextFileIfExists(join(publicDir, "llms-full.txt")) : null);
+            if (existingLlmsFull && !config.llmsFullTxt.replaceExisting) {
+              llmsFullTxtStatus = "preserved";
+              if (!existingOutputLlmsFull) {
+                await writeFile(outputLlmsFullPath, existingLlmsFull, "utf8");
+              }
+              if (!config.validation?.disabled) {
+                validationResults.push(...validateLlmsTxt(existingLlmsFull));
+              }
+            } else {
+              llmsFullTxtStatus = "generated";
+              llmsFullTxtEntries = inlineEntries;
+              await writeFile(outputLlmsFullPath, llmsFullTxtContent, "utf8");
+              if (!config.validation?.disabled) {
+                validationResults.push(...validateLlmsTxt(llmsFullTxtContent));
+              }
+            }
+          }
+        }
         if (config.aiCrawlers) {
           const crawlerEntries = Object.entries(config.aiCrawlers).filter(
             ([, value]) => value !== void 0
@@ -215,9 +328,12 @@ function agentmarkup(config) {
         }
         printReport({
           label: "@agentmarkup/astro",
+          agentCardStatus,
           llmsTxtEntries,
           llmsTxtSections,
           llmsTxtStatus,
+          llmsFullTxtEntries,
+          llmsFullTxtStatus,
           jsonLdPages,
           markdownPages,
           markdownPagesStatus,
@@ -233,10 +349,18 @@ function agentmarkup(config) {
   };
 }
 async function readTextFileIfExists(filePath) {
-  if (!existsSync(filePath)) {
-    return null;
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
   }
-  return readFile(filePath, "utf8");
+}
+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 });
@@ -262,6 +386,18 @@ function buildCanonicalUrl(siteUrl, pagePath) {
   const base = siteUrl.replace(/\/$/, "");
   return pagePath === "/" ? `${base}/` : `${base}${pagePath}`;
 }
+function buildAbsoluteMarkdownUrl(siteUrl, pagePath) {
+  const base = siteUrl.replace(/\/$/, "");
+  return pagePath === "/" ? `${base}/index.md` : `${base}${pagePath}.md`;
+}
+function countInlinedLlmsFullEntries(sections, markdownByUrl) {
+  return sections.reduce(
+    (sum, section) => sum + section.entries.filter(
+      (entry) => Boolean(entry.markdownUrl && markdownByUrl[entry.markdownUrl])
+    ).length,
+    0
+  );
+}
 function existingOutputFileExists(filePath) {
   return existsSync(filePath);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentmarkup/astro",
-  "version": "0.3.4",
-  "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.3.4"
+    "@agentmarkup/core": "0.5.0"
   },
   "peerDependencies": {
     "astro": ">=4.0.0"