@gusnips/vite 0.8.43 → 0.8.45

package/src/discovery.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { llmsTxt, mcpDiscoveryJson, type McpDiscoveryDocument } from "./discovery.ts";
+
+describe("llmsTxt", () => {
+  it("writes the title, summary and links in the supplied order", () => {
+    expect(
+      llmsTxt({
+        title: "Example",
+        summary: "Read and update tasks.\nSign in before making changes.",
+        sections: [
+          {
+            title: "Reference",
+            links: [
+              {
+                title: "Connect",
+                url: "https://example.com/docs/mcp",
+                description: "Set up access.",
+              },
+              { title: "Full reference", url: "https://example.com/llms-full.txt" },
+            ],
+          },
+        ],
+      }),
+    ).toBe(
+      "# Example\n\n" +
+        "> Read and update tasks.\n> Sign in before making changes.\n\n" +
+        "## Reference\n\n" +
+        "- [Connect](https://example.com/docs/mcp): Set up access.\n" +
+        "- [Full reference](https://example.com/llms-full.txt)\n",
+    );
+  });
+
+  it("keeps app-owned Markdown and writes exactly one final newline", () => {
+    const body = '## Tools\n\n```json\n{"name":"list_tasks"}\n```\n\n';
+    expect(llmsTxt({ title: "Example", body })).toBe(`# Example\n\n${body.trimEnd()}\n`);
+    expect(llmsTxt({ title: "Example" })).toBe("# Example\n");
+  });
+
+  it("refuses an empty title", () => {
+    expect(() => llmsTxt({ title: " " })).toThrow(/title.*empty.*Name/);
+  });
+});
+
+const DOCUMENT: McpDiscoveryDocument = {
+  name: "Example",
+  homepage: "https://example.com",
+  documentation: "https://example.com/docs/mcp",
+  llmsTxt: "https://example.com/llms.txt",
+  llmsFullTxt: "https://example.com/llms-full.txt",
+  openApi: "https://api.example.com/openapi.json",
+  servers: [
+    {
+      name: "full",
+      transport: "streamable-http",
+      url: "https://api.example.com/mcp",
+      authentication: [
+        {
+          type: "oauth2",
+          protectedResourceMetadata:
+            "https://api.example.com/.well-known/oauth-protected-resource/mcp",
+        },
+        { type: "api-key", in: "header", name: "Authorization", prefix: "Bearer " },
+      ],
+      tools: [
+        {
+          name: "update_task",
+          title: "Update a task",
+          description: "Change a task's title.",
+          inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" }, title: { type: "string", minLength: 1 } },
+            required: ["id", "title"],
+            additionalProperties: false,
+          },
+          annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+        },
+      ],
+    },
+    {
+      name: "read-only",
+      transport: "streamable-http",
+      url: "https://api.example.com/mcp/read",
+      authentication: [{ type: "none" }],
+      tools: ["list_tasks"],
+    },
+    {
+      name: "local",
+      transport: "stdio",
+      command: "bunx",
+      args: ["example-mcp"],
+      authentication: [
+        { type: "session", description: "Connect the local app before you run a tool." },
+        { type: "api-key", in: "environment", name: "EXAMPLE_API_KEY" },
+      ],
+    },
+  ],
+};
+
+describe("mcpDiscoveryJson", () => {
+  it("keeps per-server transports, access methods and full tool cards unchanged", () => {
+    const output = mcpDiscoveryJson(DOCUMENT);
+    expect(JSON.parse(output)).toEqual(DOCUMENT);
+    expect(output.startsWith('{\n  "name": "Example",')).toBe(true);
+    expect(output.endsWith("\n")).toBe(true);
+    expect(output.endsWith("\n\n")).toBe(false);
+    expect(output).not.toContain('"url": "stdio');
+    expect(output).not.toContain('"tools": []');
+  });
+
+  it("refuses empty names, server lists or access declarations", () => {
+    expect(() => mcpDiscoveryJson({ ...DOCUMENT, name: " " })).toThrow(/name.*empty/);
+    expect(() => mcpDiscoveryJson({ ...DOCUMENT, servers: [] })).toThrow(/servers.*empty/);
+    expect(() =>
+      mcpDiscoveryJson({
+        ...DOCUMENT,
+        servers: [{ name: "local", transport: "stdio", command: "bunx", authentication: [] }],
+      }),
+    ).toThrow(/local.*no authentication.*Declare/);
+  });
+});

package/src/discovery.ts

@@ -0,0 +1,103 @@
+/** Static discovery files. Content, addresses and access rules stay in the app. */
+
+export interface LlmsLink {
+  title: string;
+  url: string;
+  description?: string;
+}
+
+export interface LlmsSection {
+  title: string;
+  links: readonly LlmsLink[];
+}
+
+export interface LlmsTxtOptions {
+  title: string;
+  /** A short description, written as a blockquote. */
+  summary?: string;
+  /** Markdown kept as supplied. Use this for the text in llms-full.txt. */
+  body?: string;
+  sections?: readonly LlmsSection[];
+}
+
+/** llms.txt or llms-full.txt, as Markdown with a trailing newline. */
+export function llmsTxt({ title, summary, body, sections = [] }: LlmsTxtOptions): string {
+  if (title.trim() === "") throw new Error("llms: `title` is empty. Name the site or package.");
+  const parts = [`# ${title}`];
+  if (summary)
+    parts.push(
+      summary
+        .split(/\r?\n/)
+        .map((line) => `> ${line}`)
+        .join("\n"),
+    );
+  if (body) parts.push(body);
+  for (const section of sections) {
+    parts.push(`## ${section.title}`);
+    parts.push(
+      section.links
+        .map(
+          (link) =>
+            `- [${link.title}](${link.url})${link.description ? `: ${link.description}` : ""}`,
+        )
+        .join("\n"),
+    );
+  }
+  return `${parts.join("\n\n").trimEnd()}\n`;
+}
+
+/** Declare each accepted method. This is documentation, not an access check. */
+export type McpDiscoveryAuthentication = (
+  | { type: "oauth2"; protectedResourceMetadata: string }
+  | { type: "api-key"; in: "header" | "environment"; name: string; prefix?: string }
+  | { type: "none" }
+  | { type: "session"; description: string }
+) & { description?: string; documentation?: string };
+
+/** A tool as this server exposes it, not the combined catalog of every server. */
+export interface McpDiscoveryTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: object;
+  annotations?: object;
+}
+
+export type McpDiscoveryServer = {
+  name: string;
+  /** Several entries mean the server accepts any one of these methods. */
+  authentication: readonly McpDiscoveryAuthentication[];
+  tools?: readonly (string | McpDiscoveryTool)[];
+} & (
+  | { transport: "streamable-http"; url: string }
+  | { transport: "stdio"; command: string; args?: readonly string[] }
+);
+
+export interface McpDiscoveryDocument {
+  name: string;
+  description?: string;
+  homepage: string;
+  documentation: string;
+  llmsTxt?: string;
+  llmsFullTxt?: string;
+  openApi?: string;
+  servers: readonly McpDiscoveryServer[];
+}
+
+/**
+ * /.well-known/mcp.json, as JSON with a trailing newline. This is a discovery convention,
+ * not a standard client configuration or a replacement for MCP tools/list.
+ * No transport, access rule or tool is inferred, and supplied schemas and annotations are kept.
+ */
+export function mcpDiscoveryJson(document: McpDiscoveryDocument): string {
+  if (document.name.trim() === "")
+    throw new Error("mcp discovery: `name` is empty. Name the site or package.");
+  if (document.servers.length === 0)
+    throw new Error("mcp discovery: `servers` is empty. List the servers this file describes.");
+  for (const server of document.servers)
+    if (server.authentication.length === 0)
+      throw new Error(
+        `mcp discovery: "${server.name}" has no authentication entry. Declare how access works, including type "none" when it is public.`,
+      );
+  return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/fixtures/contrast/tokens/ok-media.css

@@ -0,0 +1,32 @@
+/* The same palette with both dark blocks wrapped in @media. */
+:root {
+  --ground: #ffffff;
+  --ink: #1a1a1a;
+  --muted: #555555;
+  --line: #767676;
+  --accent: #0b5cad;
+  --accent-ink: #fff;
+  --radius: 8px;
+}
+
+@media screen {
+  :root[data-theme="dark"] {
+    --ground: #121212;
+    --ink: #f2f2f2;
+    --muted: #b3b3b3;
+    --line: #8a8a8a;
+    --accent: #7ab7ff;
+    --accent-ink: #0a1a2b;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme]) {
+      --ground: #121212;
+      --ink: #f2f2f2;
+      --muted: #b3b3b3;
+      --line: #8a8a8a;
+      --accent: #7ab7ff;
+      --accent-ink: #0a1a2b;
+    }
+  }
+}

package/src/fixtures/contrast/tokens/ok.css

@@ -0,0 +1,30 @@
+/* Flat colour blocks, written the way a plain-CSS app writes them. A {brace} in a comment is no block. */
+:root {
+  --ground: #ffffff;
+  --ink: #1a1a1a;
+  --muted: #555555;
+  --line: #767676;
+  --accent: #0b5cad;
+  --accent-ink: #fff;
+  --radius: 8px;
+}
+
+:root[data-theme="dark"] {
+  --ground: #121212;
+  --ink: #f2f2f2;
+  --muted: #b3b3b3;
+  --line: #8a8a8a;
+  --accent: #7ab7ff;
+  --accent-ink: #0a1a2b;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --ground: #121212;
+    --ink: #f2f2f2;
+    --muted: #b3b3b3;
+    --line: #8a8a8a;
+    --accent: #7ab7ff;
+    --accent-ink: #0a1a2b;
+  }
+}

package/src/head.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { PRERENDERED_ROUTE_ATTR } from "@gusnips/react";
-import { assertRendered, bakeHead, faqJsonLd, ogLocale } from "./head.ts";
+import { assertRendered, bakeHead, faqJsonLd, jsonLd, ogLocale } from "./head.ts";
 
 /**
  * Every failure `bakeHead` has is invisible until somebody reads a search result months later
@@ -433,6 +433,37 @@ describe("assertRendered", () => {
   });
 });
 
+describe("jsonLd", () => {
+  it("keeps the caller's schema and fields", () => {
+    const data = {
+      "@context": "https://schema.org",
+      "@graph": [
+        {
+          "@type": "SoftwareApplication",
+          name: "Example",
+          applicationCategory: "DeveloperApplication",
+        },
+        { "@type": "WebAPI", name: "Example API", documentation: "https://example.com/docs" },
+      ],
+    };
+    const script = jsonLd(data);
+    expect(script.startsWith('<script type="application/ld+json">')).toBe(true);
+    expect(JSON.parse(script.replace(/^<script[^>]*>/, "").replace(/<\/script>$/, ""))).toEqual(
+      data,
+    );
+  });
+
+  it("round-trips HTML parser control text without exposing markup", () => {
+    const data = { name: '</ScRiPt><img src=x onerror="x"> <!-- <script> $$ \\u003c' };
+    const script = jsonLd(data);
+    const inner = script.replace(/^<script[^>]*>/, "").replace(/<\/script>$/, "");
+    expect(inner).not.toContain("<");
+    expect(JSON.parse(inner)).toEqual(data);
+    expect(script.match(/<script/g)).toHaveLength(1);
+    expect(script.match(/<\/script>/g)).toHaveLength(1);
+  });
+});
+
 describe("faqJsonLd", () => {
   // One donor's template carried four questions where the page renders seven: the fix is to
   // generate the block from the same strings, not to keep a second copy beside them.
@@ -448,15 +479,12 @@ describe("faqJsonLd", () => {
     expect(script.match(/"@type":"Question"/g)).toHaveLength(2);
   });
 
-  // A `</script>` inside an answer ends the element early and ships the rest of the JSON as
-  // markup. `<\/` is the same string to a JSON parser and inert to an HTML one.
   it("escapes a script-closing sequence inside an answer", () => {
     const script = faqJsonLd([
       { question: "What if I write code?", answer: "Wrap it: </script> ends the block." },
     ]);
     expect(script).not.toContain("</script> ends");
-    expect(script).toContain("<\\/script> ends");
-    // …and what it emits still parses, back to the original copy.
+    expect(script).toContain("\\u003c/script> ends");
     const json = script.replace(/^<script[^>]*>/, "").replace(/<\/script>$/, "");
     const parsed = JSON.parse(json) as {
       mainEntity: Array<{ acceptedAnswer: { text: string } }>;
@@ -464,11 +492,13 @@ describe("faqJsonLd", () => {
     expect(parsed.mainEntity[0]?.acceptedAnswer.text).toBe("Wrap it: </script> ends the block.");
   });
 
-  // The positive control for the direction that flatters: an answer WITH markup must fail this
-  // test if the escaping ever stops running, not pass because the assertion went missing.
-  it("leaves no raw `</` sequence anywhere in the block", () => {
-    const script = faqJsonLd([{ question: "q", answer: "a </b> b <!-- c" }]);
-    const inner = script.replace(/<script[^>]*>/g, "").replace(/<\/script>/g, "");
-    expect(inner).not.toMatch(/<\//);
+  it("keeps comments valid JSON and inert to the HTML parser", () => {
+    const answer = "a </b> b <!-- <script> c";
+    const script = faqJsonLd([{ question: "q", answer }]);
+    const inner = script.replace(/^<script[^>]*>/, "").replace(/<\/script>$/, "");
+    expect(inner).not.toContain("<");
+    expect(JSON.parse(inner)).toMatchObject({
+      mainEntity: [{ acceptedAnswer: { text: answer } }],
+    });
   });
 });

package/src/head.ts

@@ -193,16 +193,20 @@ export interface FaqEntry {
 }
 
 /**
- * FAQ structured data for `headExtra`, with the script-closing sequence escaped.
+ * Structured data for `headExtra`. The caller owns the schema and its claims.
  *
- * A `</script>` inside an answer ends the element early and ships the rest of the JSON as markup.
- * `<\/` is the same string to a JSON parser and inert to an HTML one, so every `</` becomes `<\/`
- * and `<!--` becomes `<\!--`. `JSON.stringify` never emits `<` outside a string, since the
- * structural characters are all brackets, quotes and digits. The replacement only ever touches
- * copy.
+ * Escape every less-than character as JSON, not HTML: `</script>` can close the element, and
+ * `<!--<script>` can make the HTML parser swallow the real closing tag. Escaping only a slash
+ * misses that second case; adding a backslash before `!` makes the JSON invalid.
  */
+export function jsonLd(data: object): string {
+  const json = JSON.stringify(data).replace(/</g, "\\u003c");
+  return `<script type="application/ld+json">${json}</script>`;
+}
+
+/** FAQ structured data from the same strings the page renders. */
 export function faqJsonLd(faqs: readonly FaqEntry[]): string {
-  const data = {
+  return jsonLd({
     "@context": "https://schema.org",
     "@type": "FAQPage",
     mainEntity: faqs.map((faq) => ({
@@ -210,9 +214,7 @@ export function faqJsonLd(faqs: readonly FaqEntry[]): string {
       name: faq.question,
       acceptedAnswer: { "@type": "Answer", text: faq.answer },
     })),
-  };
-  const json = JSON.stringify(data).replace(/<\//g, "<\\/").replace(/<!--/g, "<\\!--");
-  return `<script type="application/ld+json">${json}</script>`;
+  });
 }
 
 /**

package/src/index.ts

@@ -13,11 +13,22 @@
  * otherwise force on everyone: the vite config preset at `@gusnips/vite/preset` (the React and
  * Tailwind plugins), `renderTree` at `@gusnips/vite/render`, the theme pre-paint plugin at
  * `@gusnips/vite/theme` (both React itself), the catalog check at `@gusnips/vite/i18n`, and the
- * contrast gate at `@gusnips/vite/contrast` (tailwindcss). The last two run in CI and never in a
+ * contrast gate at `@gusnips/vite/contrast` (tailwindcss, for the class reading only). The last two run in CI and never in a
  * build. Nothing here imports React, vite or tailwindcss, so a prerender script, an OG generator
  * and a repo that only wants a sitemap all install exactly what they use.
  */
 export { resolveKey } from "./catalog.ts";
+export {
+  llmsTxt,
+  mcpDiscoveryJson,
+  type LlmsLink,
+  type LlmsSection,
+  type LlmsTxtOptions,
+  type McpDiscoveryAuthentication,
+  type McpDiscoveryDocument,
+  type McpDiscoveryServer,
+  type McpDiscoveryTool,
+} from "./discovery.ts";
 // `headExtra` takes raw markup, so the moment an adopter builds a tag out of its own copy it
 // needs the same escaping every tag this package writes already gets. Exported rather than
 // re-invented per app: an adopter's hand-rolled copy is one that can drift from ours, and the
@@ -28,6 +39,7 @@ export {
   bakeHead,
   EMPTY_ROOT,
   faqJsonLd,
+  jsonLd,
   ogLocale,
   type Alternate,
   type FaqEntry,