blume 2.0.0 → 2.0.2

package/src/cli/init/scaffold.ts

@@ -1,8 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
+import { loadAll } from "js-yaml";
 import { detect } from "package-manager-detector/detect";
 import { basename, dirname, isAbsolute, join, relative } from "pathe";
+import picomatch from "picomatch";
+import { z } from "zod";
 
 import { blumePackageJson, toPackageName } from "../../core/package-json.ts";
 import { contentful } from "../../sources/contentful.ts";
@@ -14,6 +17,7 @@ import { payload } from "../../sources/payload.ts";
 import type { AnySourceAdapter } from "../../sources/registry.ts";
 import { sanity } from "../../sources/sanity.ts";
 import { strapi } from "../../sources/strapi.ts";
+import { STARTER_OPENAPI_JSON } from "./starter-spec.ts";
 
 export const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
 export type Template = (typeof TEMPLATES)[number];
@@ -64,6 +68,11 @@ interface Starter {
   /** Import lines the fragment needs, placed after the `defineConfig` import. */
   configImports: string[];
   files: (contentDir: string) => { content: string; path: string }[];
+  /**
+   * Files the config itself reads (the `api` starter's spec), written beside
+   * it whichever content sources are selected.
+   */
+  projectFiles?: { content: string; path: string }[];
 }
 
 const page = (title: string, description: string, body: string): string =>
@@ -77,8 +86,8 @@ export const STARTERS = {
       route: "/api",
       sources: [
         {
-          label: "Petstore",
-          spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+          label: "Pet Store",
+          spec: "./openapi.json",
         },
       ],
     }),
@@ -89,11 +98,12 @@ export const STARTERS = {
         content: page(
           "API Reference",
           "Reference documentation for the API, generated from its OpenAPI spec, with every endpoint, its parameters, request bodies, and responses.",
-          "Your OpenAPI spec renders at [`/api`](/api). Point `openapi()` at your own spec in `blume.config.ts`."
+          "The example spec in `openapi.json` renders at [`/api`](/api). Replace it with your own, or point `openapi()` at your spec in `blume.config.ts`."
         ),
         path: join(dir, "index.mdx"),
       },
     ],
+    projectFiles: [{ content: STARTER_OPENAPI_JSON, path: "openapi.json" }],
   },
   changelog: {
     configExtra: `
@@ -173,6 +183,20 @@ export const commandsFor = (pm: PackageManager) => ({
   install: `${pm} install`,
 });
 
+// A path every shell (POSIX, cmd, PowerShell) takes as one bare word.
+const SHELL_SAFE_PATH = /^[\w./:-]+$/u;
+// What a double-quoted POSIX word still interprets.
+const DOUBLE_QUOTE_SPECIAL = /["$\\`]/gu;
+
+/**
+ * The `cd` into the new project, quoting a directory a shell would split or
+ * expand: `blume init "my docs"` prints `cd "my docs"`, not `cd my docs`.
+ */
+export const cdCommand = (directory: string): string =>
+  SHELL_SAFE_PATH.test(directory)
+    ? `cd ${directory}`
+    : `cd "${directory.replaceAll(DOUBLE_QUOTE_SPECIAL, String.raw`\$&`)}"`;
+
 const isPackageManager = (value: string): value is PackageManager =>
   PACKAGE_MANAGERS.some((pm) => pm === value);
 
@@ -525,6 +549,70 @@ const readText = (path: string): string => {
 const pnpmWorkspaceRoot = (root: string): string | null =>
   nearestAncestor(root, (dir) => existsSync(join(dir, "pnpm-workspace.yaml")));
 
+/** The slice of `pnpm-workspace.yaml` the membership check reads. */
+const pnpmWorkspaceSchema = z.looseObject({
+  packages: z.array(z.string()).default([]),
+});
+
+// A glob's leading `./` and trailing `/`, which pnpm ignores.
+const GLOB_EDGES = /^\.\/|\/+$/gu;
+
+/** Whether any of `globs` matches the workspace-relative path `at`. */
+const matchesAny = (globs: string[], at: string): boolean =>
+  globs.length > 0 && picomatch(globs)(at);
+
+/**
+ * Whether the pnpm workspace at `workspace` lists `root` as one of its
+ * packages: the workspace root itself, or a folder its `packages` globs match
+ * and no `!` glob excludes. pnpm installs only those, so an install run in any
+ * other folder beneath it succeeds without installing that folder's
+ * dependencies. A workspace file that doesn't parse counts as listing it, so
+ * `init` never claims what it can't tell.
+ */
+const listsPackage = (workspace: string, root: string): boolean => {
+  const at = relative(workspace, root);
+  if (at === "") {
+    return true;
+  }
+  let parsed: ReturnType<typeof pnpmWorkspaceSchema.safeParse>;
+  try {
+    // `loadAll`, not `load`: js-yaml 5 throws on a file with no document (empty,
+    // or comments only), which pnpm reads as a workspace of the root alone.
+    const [document] = loadAll(
+      readText(join(workspace, "pnpm-workspace.yaml"))
+    );
+    parsed = pnpmWorkspaceSchema.safeParse(document ?? {});
+  } catch {
+    return true;
+  }
+  if (!parsed.success) {
+    return true;
+  }
+  const globs = parsed.data.packages;
+  const pattern = (glob: string): string => glob.replaceAll(GLOB_EDGES, "");
+  const included = globs.filter((glob) => !glob.startsWith("!")).map(pattern);
+  const excluded = globs
+    .filter((glob) => glob.startsWith("!"))
+    .map((glob) => pattern(glob.slice(1)));
+  return matchesAny(included, at) && !matchesAny(excluded, at);
+};
+
+/**
+ * Whether `init` installs with pnpm into a folder that sits inside a pnpm
+ * workspace without being one of its packages. pnpm would install that
+ * workspace's own packages from there and exit 0, leaving `blume` uninstalled.
+ */
+export const outsidePnpmWorkspace = (
+  root: string,
+  answers: InitAnswers
+): boolean => {
+  if (answers.packageManager !== "pnpm") {
+    return false;
+  }
+  const workspace = pnpmWorkspaceRoot(root);
+  return workspace !== null && !listsPackage(workspace, root);
+};
+
 /**
  * The Yarn project enclosing `root`: a directory holding a lockfile, a
  * `.yarnrc.yml`, or a `package.json` that declares workspaces.
@@ -585,10 +673,13 @@ const packageManagerConfigFor = (
   return [];
 };
 
+const ESBUILD_APPROVAL = "  allowBuilds:\n    esbuild: true";
+
 /**
- * What the project still needs from a workspace it joins, when `init` left
- * that workspace's config alone: pnpm's approval for esbuild's build script
- * (pnpm 10 and later fail the install without it), or Yarn Berry's
+ * What the project still needs from a workspace it sits in, when `init` left
+ * that workspace's config alone: a place in a pnpm workspace's `packages`
+ * (pnpm skips a folder it doesn't list), pnpm's approval for esbuild's build
+ * script (pnpm 10 and later fail the install without it), or Yarn Berry's
  * `node_modules` linker. Undefined when the workspace already has it, or the
  * project doesn't sit in one.
  */
@@ -599,11 +690,21 @@ export const workspaceNote = (
 ): string | undefined => {
   if (answers.packageManager === "pnpm") {
     const workspace = pnpmWorkspaceRoot(root);
-    const file = workspace && join(workspace, "pnpm-workspace.yaml");
-    if (!file || readText(file).includes("esbuild")) {
+    if (!workspace) {
+      return;
+    }
+    const file = join(workspace, "pnpm-workspace.yaml");
+    const approved = readText(file).includes("esbuild");
+    if (!listsPackage(workspace, root)) {
+      const entry = `  packages:\n    - ${relative(workspace, root)}`;
+      return approved
+        ? `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing:\n\n${entry}`
+        : `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing, and approve esbuild's build script, or pnpm 10 and later stop the install:\n\n${entry}\n${ESBUILD_APPROVAL}`;
+    }
+    if (approved) {
       return;
     }
-    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 10 and later stop the install:\n\n  allowBuilds:\n    esbuild: true`;
+    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 10 and later stop the install:\n\n${ESBUILD_APPROVAL}`;
   }
   if (answers.packageManager !== "yarn" || yarnMajor(env.userAgent) === 1) {
     return;
@@ -622,6 +723,7 @@ export const buildPlan = (
   answers: InitAnswers,
   env: PlanEnvironment = {}
 ): ScaffoldFile[] => {
+  const starter: Starter = STARTERS[answers.template];
   const files: ScaffoldFile[] = [
     {
       content: blumePackageJson(
@@ -632,11 +734,15 @@ export const buildPlan = (
     },
     ...packageManagerConfigFor(root, answers, env),
     { content: buildConfig(answers), path: join(root, "blume.config.ts") },
+    ...(starter.projectFiles ?? []).map((file) => ({
+      ...file,
+      path: join(root, file.path),
+    })),
   ];
   // Seed pages only make sense when a local filesystem source will read them.
   if (answers.sources.length === 0 || answers.sources.includes("filesystem")) {
     files.push(
-      ...STARTERS[answers.template]
+      ...starter
         .files(answers.contentDir)
         .map((file) => ({ ...file, path: join(root, file.path) }))
     );
@@ -771,7 +877,7 @@ export const nextSteps = (
   const commands = commandsFor(answers.packageManager);
   const lines: string[] = [];
   if (answers.directory !== ".") {
-    lines.push(`cd ${answers.directory}`);
+    lines.push(cdCommand(answers.directory));
   }
   if (needsInstall) {
     lines.push(commands.install);

package/src/cli/init/starter-spec.ts

@@ -0,0 +1,235 @@
+/**
+ * The OpenAPI document the `api` starter writes beside `blume.config.ts`, so a
+ * new project's first build reads a local file instead of depending on a
+ * third-party server. Small, but it exercises what a real reference renders:
+ * path and query parameters, request bodies, shared schemas, error responses,
+ * and bearer auth. Each operation's description is sized so its page's meta
+ * description, with the endpoint sentence Blume appends, fits the range
+ * `blume audit` checks.
+ */
+
+const petId = {
+  description: "The pet's ID.",
+  in: "path",
+  name: "petId",
+  required: true,
+  schema: { type: "string" },
+};
+
+const errorResponse = (description: string) => ({
+  content: {
+    "application/json": { schema: { $ref: "#/components/schemas/Error" } },
+  },
+  description,
+});
+
+const petResponse = (description: string) => ({
+  content: {
+    "application/json": { schema: { $ref: "#/components/schemas/Pet" } },
+  },
+  description,
+});
+
+// Built from entries rather than a literal so the written file keeps the
+// conventional section order (`openapi`, `info`, …) instead of the sorted one.
+const STARTER_SPEC = Object.fromEntries([
+  ["openapi", "3.1.0"],
+  [
+    "info",
+    {
+      description:
+        "A small example API for a pet store: list, create, read, update, and delete pets. Replace openapi.json with your own spec to document your API.",
+      title: "Pet Store API",
+      version: "1.0.0",
+    },
+  ],
+  ["servers", [{ url: "https://api.example.com/v1" }]],
+  ["security", [{ bearerAuth: [] }]],
+  [
+    "tags",
+    [
+      {
+        description:
+          "Every pet in the store, with its name, species, and status.",
+        name: "Pets",
+      },
+    ],
+  ],
+  [
+    "paths",
+    {
+      "/pets": {
+        get: {
+          description:
+            "Returns the pets in the store, newest first, filtered by status and paged with a cursor.",
+          operationId: "listPets",
+          parameters: [
+            {
+              description: "Only return pets with this status.",
+              in: "query",
+              name: "status",
+              schema: { $ref: "#/components/schemas/Status" },
+            },
+            {
+              description: "The most pets to return.",
+              in: "query",
+              name: "limit",
+              schema: {
+                default: 20,
+                maximum: 100,
+                minimum: 1,
+                type: "integer",
+              },
+            },
+            {
+              description: "The `nextCursor` from the previous page.",
+              in: "query",
+              name: "cursor",
+              schema: { type: "string" },
+            },
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/PetList" },
+                },
+              },
+              description: "A page of pets.",
+            },
+          },
+          summary: "List pets",
+          tags: ["Pets"],
+        },
+        post: {
+          description:
+            "Adds a pet to the store and returns it with its new ID and an available status.",
+          operationId: "createPet",
+          requestBody: {
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/NewPet" },
+              },
+            },
+            required: true,
+          },
+          responses: {
+            "201": petResponse("The new pet."),
+            "422": errorResponse("The pet's fields are invalid."),
+          },
+          summary: "Create a pet",
+          tags: ["Pets"],
+        },
+      },
+      "/pets/{petId}": {
+        delete: {
+          description:
+            "Removes a pet from the store for good, or returns a 404 error when no pet has that ID.",
+          operationId: "deletePet",
+          parameters: [petId],
+          responses: {
+            "204": { description: "The pet was deleted." },
+            "404": errorResponse("No pet has that ID."),
+          },
+          summary: "Delete a pet",
+          tags: ["Pets"],
+        },
+        get: {
+          description:
+            "Returns a single pet by its ID, or a 404 error when no pet has that ID.",
+          operationId: "getPet",
+          parameters: [petId],
+          responses: {
+            "200": petResponse("The pet."),
+            "404": errorResponse("No pet has that ID."),
+          },
+          summary: "Get a pet",
+          tags: ["Pets"],
+        },
+        patch: {
+          description:
+            "Changes the fields you send on an existing pet and leaves the rest as they were.",
+          operationId: "updatePet",
+          parameters: [petId],
+          requestBody: {
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/PetUpdate" },
+              },
+            },
+            required: true,
+          },
+          responses: {
+            "200": petResponse("The updated pet."),
+            "404": errorResponse("No pet has that ID."),
+          },
+          summary: "Update a pet",
+          tags: ["Pets"],
+        },
+      },
+    },
+  ],
+  [
+    "components",
+    {
+      schemas: {
+        Error: {
+          properties: {
+            code: { example: "not_found", type: "string" },
+            message: { example: "No pet has that ID.", type: "string" },
+          },
+          required: ["code", "message"],
+          type: "object",
+        },
+        NewPet: {
+          properties: {
+            name: { example: "Mochi", type: "string" },
+            species: { $ref: "#/components/schemas/Species" },
+          },
+          required: ["name", "species"],
+          type: "object",
+        },
+        Pet: {
+          properties: {
+            createdAt: { format: "date-time", type: "string" },
+            id: { example: "pet_01h2x", type: "string" },
+            name: { example: "Mochi", type: "string" },
+            species: { $ref: "#/components/schemas/Species" },
+            status: { $ref: "#/components/schemas/Status" },
+          },
+          required: ["id", "name", "species", "status", "createdAt"],
+          type: "object",
+        },
+        PetList: {
+          properties: {
+            data: {
+              items: { $ref: "#/components/schemas/Pet" },
+              type: "array",
+            },
+            nextCursor: {
+              description: "Pass as `cursor` to fetch the next page.",
+              type: ["string", "null"],
+            },
+          },
+          required: ["data", "nextCursor"],
+          type: "object",
+        },
+        PetUpdate: {
+          properties: {
+            name: { type: "string" },
+            status: { $ref: "#/components/schemas/Status" },
+          },
+          type: "object",
+        },
+        Species: { enum: ["cat", "dog", "bird", "rabbit"], type: "string" },
+        Status: { enum: ["available", "pending", "adopted"], type: "string" },
+      },
+      securitySchemes: {
+        bearerAuth: { scheme: "bearer", type: "http" },
+      },
+    },
+  ],
+]);
+
+/** The starter spec as the `openapi.json` text `init` writes. */
+export const STARTER_OPENAPI_JSON = `${JSON.stringify(STARTER_SPEC, null, 2)}\n`;

package/src/cli/required-secrets.ts

@@ -24,12 +24,12 @@ export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
     });
   };
 
-  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
+  if (config.ai.assistant?.enabled && !config.ai.assistant.endpoint) {
     // The adapter descriptor names the env vars its route reads.
-    const { provider } = config.ai.ask;
+    const { provider } = config.ai.assistant;
     const backend = resolveAskBackend(provider);
     for (const env of provider.requiredSecrets) {
-      requireSecret(`Ask AI (${backend.label})`, env, backend.secretNote);
+      requireSecret(`Assistant (${backend.label})`, env, backend.secretNote);
     }
   }
 

package/src/components/content/AccordionItem.astro

@@ -97,29 +97,33 @@ const accordionId = id ?? componentSlug(title);
       });
     };
 
-    document.addEventListener(
-      "toggle",
-      (event) => {
-        const accordion = event.target;
-        if (
-          !(accordion instanceof HTMLDetailsElement) ||
-          !accordion.matches("[data-blume-accordion]") ||
-          !accordion.open ||
-          !accordion.id
-        ) {
-          return;
-        }
+    // Only the reader opening an item points the hash at it, so this keys on
+    // the summary's click (pointer, Enter, or Space) rather than `toggle`: a
+    // `defaultOpen` item a client-router swap inserts fires `toggle` too, and
+    // that must not overwrite the hash the reader arrived with.
+    document.addEventListener("click", (event) => {
+      const summary =
+        event.target instanceof Element ? event.target.closest("summary") : null;
+      const accordion = summary?.parentElement;
+      if (
+        event.defaultPrevented ||
+        !(accordion instanceof HTMLDetailsElement) ||
+        !accordion.matches("[data-blume-accordion]") ||
+        // Open now means this click closes it.
+        accordion.open ||
+        !accordion.id
+      ) {
+        return;
+      }
 
-        // Keep the entry's state: the client router ignores a popstate whose
-        // state is null, so Back to this page would change only the URL.
-        history.replaceState(
-          history.state,
-          "",
-          `#${encodeURIComponent(accordion.id)}`
-        );
-      },
-      true
-    );
+      // Keep the entry's state: the client router ignores a popstate whose
+      // state is null, so Back to this page would change only the URL.
+      history.replaceState(
+        history.state,
+        "",
+        `#${encodeURIComponent(accordion.id)}`
+      );
+    });
 
     const init = () => {
       dedupeAccordionIds();

package/src/components/content/Badge.astro

@@ -1,6 +1,7 @@
 ---
 import { STROKE, TINT } from "../colors.ts";
 import Icon from "../Icon.astro";
+import { badgeColorName } from "./badge-color.ts";
 
 type BadgeVariant = "default" | "accent" | "success" | "warning" | "danger";
 type BadgeSize = "xs" | "sm" | "md" | "lg";
@@ -34,15 +35,7 @@ const {
 
 const activeStroke = stroke === true || stroke === "true";
 const isDisabled = disabled === true || disabled === "true";
-const colorName =
-  color ??
-  {
-    accent: "blue",
-    danger: "red",
-    default: "gray",
-    success: "green",
-    warning: "orange",
-  }[variant];
+const colorName = badgeColorName(variant, color);
 const customColor = colorName.startsWith("#") ? colorName : null;
 
 // The hue rows come from the shared table (see colors.ts for the contrast

package/src/components/content/Card.astro

@@ -80,7 +80,7 @@ const variantClass = {
       <p class="mt-0! mb-1.5! flex items-center gap-1.5 font-medium text-foreground">
         {title}
         {showArrow && (
-          <Icon class="text-muted-foreground" name="arrow-right" size={14} />
+          <Icon class="text-muted-foreground rtl:-scale-x-100" name="arrow-right" size={14} />
         )}
       </p>
     )
@@ -92,7 +92,7 @@ const variantClass = {
     cta && (
       <p class="mt-4! mb-0! flex items-center gap-1.5 font-medium text-accent text-sm">
         {cta}
-        {showArrow && <Icon name="arrow-right" size={14} />}
+        {showArrow && <Icon class="rtl:-scale-x-100" name="arrow-right" size={14} />}
       </p>
     )
   }

package/src/components/content/Component.astro

@@ -14,6 +14,7 @@ import { CODE_PADDING_BLOCK_REM } from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { withBase } from "../islands/base-path.ts";
+import { contentStrings } from "./content-strings.ts";
 import { EXAMPLE_PANE_MIN_PX } from "./example-pane.ts";
 import Tab from "./Tab.astro";
 import Tabs from "./Tabs.astro";
@@ -26,6 +27,7 @@ interface Props {
 
 const { path } = Astro.props;
 const entry = examples[path];
+const { content: strings } = contentStrings(data, Astro.currentLocale);
 
 // The live preview renders in its own generated route, embedded as an iframe:
 // the frame boundary is what keeps the docs CSS (prose typography, component
@@ -103,17 +105,21 @@ const paneClass =
       <Tab
         class={`overflow-hidden p-0! ${paneClass}`}
         style={paneStyle}
-        title="Preview"
+        title={strings.preview}
       >
         <iframe
           class="h-full w-full"
           data-blume-example-frame
           loading="lazy"
           src={previewSrc}
-          title={`Preview of ${path}`}
+          title={`${strings.preview}: ${path}`}
         />
       </Tab>
-      <Tab class={`overflow-hidden ${paneClass}`} style={paneStyle} title="Code">
+      <Tab
+        class={`overflow-hidden ${paneClass}`}
+        style={paneStyle}
+        title={strings.code}
+      >
         <Fragment set:html={codeHtml} />
       </Tab>
     </Tabs>

package/src/components/content/Expandable.astro

@@ -1,7 +1,11 @@
 ---
+import data from "blume:data";
+
 import AccordionItem from "./AccordionItem.astro";
+import { contentStrings } from "./content-strings.ts";
 
-const { defaultOpen = false, title = "Show more" } = Astro.props;
+const { content: strings } = contentStrings(data, Astro.currentLocale);
+const { defaultOpen = false, title = strings.showMore } = Astro.props;
 ---
 
 <div class="not-prose my-4 overflow-hidden rounded-blume border border-border">

package/src/components/content/Frame.astro

@@ -1,7 +1,5 @@
 ---
-import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
-
-import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+import { renderInlineMarkdown } from "./inline-markdown.ts";
 
 interface Props {
   caption?: string;
@@ -10,10 +8,7 @@ interface Props {
 
 const { caption, hint } = Astro.props;
 
-const markdownProcessor = await createSatteriMarkdownProcessor();
-const captionHtml = caption
-  ? unwrapParagraph((await markdownProcessor.render(escapeRawHtml(caption))).code)
-  : undefined;
+const captionHtml = caption ? await renderInlineMarkdown(caption) : undefined;
 ---
 
 <blume-frame class="not-prose my-6 block">