@hgdc/agents 0.1.2 → 0.2.0

package/README.md

@@ -20,6 +20,22 @@ const fetch = withMarkdown(handler.fetch, {
 export default createServerEntry({ fetch })
 ```
 
+Pour un site servi à la racine de son hôte (Status, Portal, Account), les options ajoutent ce que les agents vérifient avant de recommander un site :
+
+```ts
+import { HGDC_TRUST_PAGES, productJsonLd, withMarkdown } from "@hgdc/agents"
+
+withMarkdown(handler.fetch, {
+  footer,
+  redirects: HGDC_TRUST_PAGES, // /about, /contact, /privacy → pages de hgdc.ch (301)
+  jsonLd: productJsonLd({ name: "Status", url: "https://status.hgdc.ch", description: "…" }),
+  canonicalOrigin: "https://status.hgdc.ch", // <link rel="canonical"> des pages en 200
+  apiPrefix: "/api", // 404 sous /api en application/problem+json
+})
+```
+
+Le JSON-LD et l'adresse canonique s'insèrent en flux avant `</head>`, seulement si la page n'en porte pas déjà : le rendu SSR en streaming n'est pas retenu au-delà du `<head>`.
+
 Seuls les GET et HEAD qui préfèrent le Markdown sont convertis (`prefersMarkdown` : `text/markdown` accepté avec une qualité au moins égale à `text/html` ; un joker ne compte pas). Une redirection, un fichier ou du JSON passent tels quels.
 
 ## Site prérendu (Astro, sortie Build Output API)
@@ -40,12 +56,14 @@ config.routes.splice(-1, 0, ...miss) // juste avant la page 404 de l'adaptateur
 
 ## Référence
 
-| Export                                        | Rôle                                                 |
-| --------------------------------------------- | ---------------------------------------------------- |
-| `htmlToMarkdown(html, url)`                   | Markdown du contenu d'une page, liens rendus absolus |
-| `prefersMarkdown(accept)`                     | La requête préfère-t-elle le Markdown ?              |
-| `withMarkdown(fetch, { footer })`             | Handler `fetch` qui sert le Markdown aux agents      |
-| `linksFooter(links)`                          | Pied de page : liens séparés par « · »               |
-| `varyOnAccept(headers)`                       | Ajoute `Accept` à `Vary`                             |
-| `writeMarkdownPages(dir, options)` (`/build`) | Écrit les `.md` d'un build prérendu                  |
-| `markdownRoutes(pages, options)` (`/build`)   | Routes Build Output API v3 qui les servent           |
+| Export                                                            | Rôle                                                      |
+| ----------------------------------------------------------------- | --------------------------------------------------------- |
+| `htmlToMarkdown(html, url)`                                       | Markdown du contenu d'une page, liens rendus absolus      |
+| `prefersMarkdown(accept)`                                         | La requête préfère-t-elle le Markdown ?                   |
+| `withMarkdown(fetch, { footer })`                                 | Handler `fetch` qui sert le Markdown aux agents           |
+| `linksFooter(links)`                                              | Pied de page : liens séparés par « · »                    |
+| `HGDC_TRUST_PAGES`, `HGDC_ORGANIZATION`, `productJsonLd(product)` | Pages de confiance et données structurées de l'entreprise |
+| `injectIntoHead(body, extra)`                                     | Insère des balises avant `</head>` d'un flux HTML         |
+| `varyOnAccept(headers)`                                           | Ajoute `Accept` à `Vary`                                  |
+| `writeMarkdownPages(dir, options)` (`/build`)                     | Écrit les `.md` d'un build prérendu                       |
+| `markdownRoutes(pages, options)` (`/build`)                       | Routes Build Output API v3 qui les servent                |

package/dist/fetch.d.ts

@@ -1,6 +1,16 @@
 export type MarkdownOptions = {
     /** Markdown ajouté en pied de chaque page, après une ligne `---` : liens vers llms.txt, sitemap, contact. */
     footer?: string;
+    /** Redirections permanentes (301) d'un chemin exact vers une adresse : pages de confiance (`HGDC_TRUST_PAGES`). */
+    redirects?: Readonly<Record<string, string>>;
+    /** JSON-LD posé dans le `<head>` de chaque page HTML qui n'en porte pas (`productJsonLd`). */
+    jsonLd?: unknown;
+    /** Origine publique (`https://status.hgdc.ch`) : `<link rel="canonical">` sur chaque page HTML en 200 qui n'en a pas. */
+    canonicalOrigin?: string;
+    /** Préfixe d'API (`/api`) : une page introuvable sous ce préfixe devient une erreur JSON (RFC 9457). */
+    apiPrefix?: string;
+    /** Indication donnée dans ces erreurs JSON : où lire l'API. */
+    apiHint?: string;
 };
 /** Pied de page standard : une ligne de liens, `[libellé](adresse)` séparés par « · ». */
 export declare function linksFooter(links: {
@@ -10,8 +20,8 @@ export declare function linksFooter(links: {
 /**
  * Enrobe un handler `fetch` : une requête GET ou HEAD qui préfère `text/markdown` reçoit la page HTML
  * convertie, au même statut (404 compris), avec `Content-Type: text/markdown` et `Vary: Accept`. Les autres
- * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`. Une redirection, un fichier
- * ou du JSON ne sont jamais convertis.
+ * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`, et selon les options le
+ * JSON-LD et l'adresse canonique. Une redirection, un fichier ou du JSON ne sont jamais convertis.
  *
  * TanStack Start refuse en 406 une requête sans `text/html` ni `*\/*` : le handler reçoit donc la requête
  * avec `Accept: text/html`.

package/dist/fetch.js

@@ -1,4 +1,6 @@
-// Version Markdown des pages d'une app rendue côté serveur (TanStack Start, ou tout handler `fetch`).
+// Ce qu'une app rendue côté serveur (TanStack Start, ou tout handler `fetch`) montre aux agents : la page en
+// Markdown, ses données structurées et son adresse canonique, les pages de confiance, des erreurs d'API en JSON.
+import { canonicalLink, injectIntoHead, jsonLdScript } from "./head.js";
 import { htmlToMarkdown } from "./markdown.js";
 import { prefersMarkdown, varyOnAccept } from "./negotiate.js";
 /** Pied de page standard : une ligne de liens, `[libellé](adresse)` séparés par « · ». */
@@ -6,13 +8,13 @@ export function linksFooter(links) {
     return links.map((l) => `[${l.label}](${l.href})`).join(" · ");
 }
 const isHtml = (response) => /^text\/html\b/i.test(response.headers.get("content-type") ?? "");
-// En-têtes qui décrivent le corps HTML et deviennent faux pour le Markdown.
+// En-têtes qui décrivent le corps HTML et deviennent faux pour un autre corps.
 const BODY_HEADERS = ["content-type", "content-length", "content-encoding", "etag", "last-modified", "content-md5"];
 /**
  * Enrobe un handler `fetch` : une requête GET ou HEAD qui préfère `text/markdown` reçoit la page HTML
  * convertie, au même statut (404 compris), avec `Content-Type: text/markdown` et `Vary: Accept`. Les autres
- * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`. Une redirection, un fichier
- * ou du JSON ne sont jamais convertis.
+ * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`, et selon les options le
+ * JSON-LD et l'adresse canonique. Une redirection, un fichier ou du JSON ne sont jamais convertis.
  *
  * TanStack Start refuse en 406 une requête sans `text/html` ni `*\/*` : le handler reçoit donc la requête
  * avec `Accept: text/html`.
@@ -20,22 +22,26 @@ const BODY_HEADERS = ["content-type", "content-length", "content-encoding", "eta
 export function withMarkdown(handler, options = {}) {
     return async (request, ...rest) => {
         const read = request.method === "GET" || request.method === "HEAD";
-        if (!read || !prefersMarkdown(request.headers.get("accept"))) {
-            const response = await handler(request, ...rest);
-            if (read && isHtml(response))
-                return withHeaders(response, response.body, varyOnAccept);
+        const url = new URL(request.url);
+        const redirect = read ? options.redirects?.[url.pathname.replace(/(.)\/$/, "$1")] : undefined;
+        if (redirect)
+            return new Response(null, { status: 301, headers: { location: redirect } });
+        const markdown = read && prefersMarkdown(request.headers.get("accept"));
+        const response = markdown
+            ? await handler(
+            // Requête reconstruite depuis l'URL : le Request de Nitro (srvx) n'est pas celui d'undici, et
+            // `new Request(request, …)` le refuse. HEAD est rendu en GET, sinon le corps à convertir serait vide.
+            new Request(request.url, { method: "GET", headers: htmlAccept(request.headers), signal: request.signal }), ...rest)
+            : await handler(request, ...rest);
+        if (!read || !isHtml(response))
             return response;
-        }
-        const headers = new Headers(request.headers);
-        headers.set("accept", "text/html");
-        // Requête reconstruite depuis l'URL : le Request de Nitro (srvx) n'est pas celui d'undici, et
-        // `new Request(request, …)` le refuse. HEAD est rendu en GET, sinon le corps à convertir serait vide.
-        const response = await handler(new Request(request.url, { method: "GET", headers, signal: request.signal }), ...rest);
-        if (!isHtml(response) || response.status < 200 || (response.status >= 300 && response.status < 400))
-            return withHeaders(response, request.method === "HEAD" ? null : response.body, varyOnAccept);
-        const html = await response.text();
-        const markdown = htmlToMarkdown(html, request.url) + (options.footer ? `\n---\n\n${options.footer}\n` : "");
-        return withHeaders(response, request.method === "HEAD" ? null : markdown, (out) => {
+        if (options.apiPrefix && response.status === 404 && isUnder(url.pathname, options.apiPrefix))
+            return apiNotFound(url.pathname, options.apiHint);
+        const redirected = response.status >= 300 && response.status < 400;
+        if (!markdown || response.status < 200 || redirected)
+            return withHeaders(response, request.method === "HEAD" ? null : enrichHead(response, url, options), varyOnAccept);
+        const text = htmlToMarkdown(await response.text(), request.url) + (options.footer ? `\n---\n\n${options.footer}\n` : "");
+        return withHeaders(response, request.method === "HEAD" ? null : text, (out) => {
             for (const name of BODY_HEADERS)
                 out.delete(name);
             out.set("content-type", "text/markdown; charset=utf-8");
@@ -43,8 +49,47 @@ export function withMarkdown(handler, options = {}) {
         });
     };
 }
+function htmlAccept(original) {
+    const headers = new Headers(original);
+    headers.set("accept", "text/html");
+    return headers;
+}
+const isUnder = (path, prefix) => path === prefix || path.startsWith(`${prefix.replace(/\/$/, "")}/`);
+/** Corps HTML avec le JSON-LD et l'adresse canonique des options, s'il y a lieu. */
+function enrichHead(response, url, options) {
+    const canonical = options.canonicalOrigin && response.status === 200 ? `${options.canonicalOrigin}${url.pathname}` : null;
+    if (!response.body || (!options.jsonLd && !canonical))
+        return response.body;
+    return injectIntoHead(response.body, (head) => {
+        let extra = "";
+        if (options.jsonLd && !/application\/ld\+json/i.test(head))
+            extra += jsonLdScript(options.jsonLd);
+        if (canonical && !/rel=["']?canonical/i.test(head))
+            extra += canonicalLink(canonical);
+        return extra;
+    });
+}
+/** Adresse inconnue sous l'API : erreur JSON au format RFC 9457 plutôt qu'une page HTML. */
+function apiNotFound(path, hint) {
+    const problem = {
+        type: "about:blank",
+        title: "Ressource introuvable",
+        status: 404,
+        code: "not_found",
+        detail: `Aucune ressource à ${path}.`,
+        ...(hint ? { hint } : {}),
+    };
+    return new Response(JSON.stringify(problem), {
+        status: 404,
+        headers: { "content-type": "application/problem+json", vary: "Accept" },
+    });
+}
 function withHeaders(response, body, edit) {
     const headers = new Headers(response.headers);
+    // Corps réécrit (Markdown, <head> enrichi) : longueur et empreinte d'origine ne valent plus.
+    if (body !== response.body)
+        for (const name of ["content-length", "etag", "content-md5"])
+            headers.delete(name);
     edit(headers);
     return new Response(body, { status: response.status, statusText: response.statusText, headers });
 }

package/dist/head.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Corps HTML avec `extra(head)` inséré juste avant `</head>`. `extra` reçoit le `<head>` déjà rendu, pour
+ * ne rien ajouter que la page porte déjà ; une chaîne vide n'ajoute rien.
+ */
+export declare function injectIntoHead(body: ReadableStream<Uint8Array>, extra: (head: string) => string): ReadableStream<Uint8Array>;
+/** JSON-LD sûr dans un `<script>` : `<` échappé, la balise ne peut pas se fermer avant la fin. */
+export declare const jsonLdScript: (data: unknown) => string;
+/** `<link rel="canonical">` pour une adresse absolue. */
+export declare const canonicalLink: (href: string) => string;

package/dist/head.js

@@ -0,0 +1,37 @@
+// Ajout de balises dans le <head> d'une page HTML servie en flux (rendu SSR en streaming) : le début du
+// document est retenu jusqu'à `</head>`, la suite passe telle quelle.
+/** Au-delà, la page n'a pas de `</head>` lisible : elle passe sans ajout. */
+const MAX_HEAD = 256 * 1024;
+/**
+ * Corps HTML avec `extra(head)` inséré juste avant `</head>`. `extra` reçoit le `<head>` déjà rendu, pour
+ * ne rien ajouter que la page porte déjà ; une chaîne vide n'ajoute rien.
+ */
+export function injectIntoHead(body, extra) {
+    const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
+    let buffer = "";
+    let done = false;
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            if (done)
+                return controller.enqueue(chunk);
+            buffer += decoder.decode(chunk, { stream: true });
+            const end = buffer.search(/<\/head>/i);
+            if (end === -1 && buffer.length < MAX_HEAD)
+                return;
+            done = true;
+            const out = end === -1 ? buffer : buffer.slice(0, end) + extra(buffer.slice(0, end)) + buffer.slice(end);
+            controller.enqueue(encoder.encode(out));
+            buffer = "";
+        },
+        flush(controller) {
+            if (!done && buffer)
+                controller.enqueue(encoder.encode(buffer + decoder.decode()));
+        },
+    }));
+}
+/** JSON-LD sûr dans un `<script>` : `<` échappé, la balise ne peut pas se fermer avant la fin. */
+export const jsonLdScript = (data) => `<script type="application/ld+json">${JSON.stringify(data).replace(/</g, "\\u003c")}</script>`;
+const escapeAttribute = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+/** `<link rel="canonical">` pour une adresse absolue. */
+export const canonicalLink = (href) => `<link rel="canonical" href="${escapeAttribute(href)}">`;

package/dist/hgdc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pages de confiance (`/about`, `/contact`, `/privacy`) que les agents cherchent sur chaque hôte : celles
+ * de l'entreprise, sur hgdc.ch. Pour l'option `redirects` de `withMarkdown`.
+ */
+export declare const HGDC_TRUST_PAGES: Readonly<Record<string, string>>;
+/** Nœud schema.org de l'entreprise, même `@id` que sur hgdc.ch. */
+export declare const HGDC_ORGANIZATION: {
+    readonly "@type": "Organization";
+    readonly "@id": "https://hgdc.ch/#organization";
+    readonly name: "Hugo Gebel Développement Conseil";
+    readonly alternateName: "HGDC";
+    readonly url: "https://hgdc.ch";
+    readonly description: "Entreprise individuelle suisse : agence web, accompagnement IA, outils en ligne de la H Collection et logiciel Stratta, pour les entreprises en Suisse.";
+    readonly email: "contact@hgdc.ch";
+    readonly contactPoint: {
+        readonly "@type": "ContactPoint";
+        readonly contactType: "customer service";
+        readonly email: "contact@hgdc.ch";
+        readonly url: "https://hgdc.ch/contact";
+        readonly areaServed: "CH";
+        readonly availableLanguage: "fr";
+    };
+    readonly address: {
+        readonly "@type": "PostalAddress";
+        readonly streetAddress: "Chemin des Vignes 6";
+        readonly postalCode: "1135";
+        readonly addressLocality: "Denens";
+        readonly addressRegion: "VD";
+        readonly addressCountry: "CH";
+    };
+};
+/** Graphe JSON-LD d'un produit : l'entreprise et le site du produit, qu'elle publie. */
+export declare function productJsonLd(product: {
+    name: string;
+    url: string;
+    description: string;
+}): {
+    "@context": string;
+    "@graph": Record<string, unknown>[];
+};

package/dist/hgdc.js

@@ -0,0 +1,55 @@
+// Ce que chaque site de HGDC dit de l'entreprise aux agents : pages de confiance et données structurées.
+// Mêmes valeurs que les mentions légales de hgdc.ch, qui font foi.
+/**
+ * Pages de confiance (`/about`, `/contact`, `/privacy`) que les agents cherchent sur chaque hôte : celles
+ * de l'entreprise, sur hgdc.ch. Pour l'option `redirects` de `withMarkdown`.
+ */
+export const HGDC_TRUST_PAGES = {
+    "/about": "https://hgdc.ch/a-propos",
+    "/contact": "https://hgdc.ch/contact",
+    "/privacy": "https://hgdc.ch/confidentialite",
+};
+/** Nœud schema.org de l'entreprise, même `@id` que sur hgdc.ch. */
+export const HGDC_ORGANIZATION = {
+    "@type": "Organization",
+    "@id": "https://hgdc.ch/#organization",
+    name: "Hugo Gebel Développement Conseil",
+    alternateName: "HGDC",
+    url: "https://hgdc.ch",
+    description: "Entreprise individuelle suisse : agence web, accompagnement IA, outils en ligne de la H Collection et logiciel Stratta, pour les entreprises en Suisse.",
+    email: "contact@hgdc.ch",
+    contactPoint: {
+        "@type": "ContactPoint",
+        contactType: "customer service",
+        email: "contact@hgdc.ch",
+        url: "https://hgdc.ch/contact",
+        areaServed: "CH",
+        availableLanguage: "fr",
+    },
+    address: {
+        "@type": "PostalAddress",
+        streetAddress: "Chemin des Vignes 6",
+        postalCode: "1135",
+        addressLocality: "Denens",
+        addressRegion: "VD",
+        addressCountry: "CH",
+    },
+};
+/** Graphe JSON-LD d'un produit : l'entreprise et le site du produit, qu'elle publie. */
+export function productJsonLd(product) {
+    return {
+        "@context": "https://schema.org",
+        "@graph": [
+            { ...HGDC_ORGANIZATION },
+            {
+                "@type": "WebSite",
+                "@id": `${product.url}/#website`,
+                url: product.url,
+                name: product.name,
+                description: product.description,
+                inLanguage: "fr-CH",
+                publisher: { "@id": HGDC_ORGANIZATION["@id"] },
+            },
+        ],
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { htmlToMarkdown, pageTitle } from "./markdown.js";
 export { prefersMarkdown, varyOnAccept } from "./negotiate.js";
 export { linksFooter, withMarkdown, type MarkdownOptions } from "./fetch.js";
+export { canonicalLink, injectIntoHead, jsonLdScript } from "./head.js";
+export { HGDC_ORGANIZATION, HGDC_TRUST_PAGES, productJsonLd } from "./hgdc.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { htmlToMarkdown, pageTitle } from "./markdown.js";
 export { prefersMarkdown, varyOnAccept } from "./negotiate.js";
 export { linksFooter, withMarkdown } from "./fetch.js";
+export { canonicalLink, injectIntoHead, jsonLdScript } from "./head.js";
+export { HGDC_ORGANIZATION, HGDC_TRUST_PAGES, productJsonLd } from "./hgdc.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/agents",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Sites lisibles par les agents IA : version Markdown des pages (Accept: text/markdown), 404 en Markdown, routes Build Output API pour les sites prérendus.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/hugogebel-boop/hgdc-kit/tree/main/packages/agents#readme",