blume 0.3.0 → 0.4.0

package/src/astro/static-assets.ts

@@ -0,0 +1,117 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { cp } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { extname, join, relative, resolve, sep } from "pathe";
+
+import type { AssetMount } from "../core/assets.ts";
+
+/** Content types for the asset extensions a docs project commonly serves. */
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mp4": "video/mp4",
+  ".otf": "font/otf",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+const mimeType = (file: string): string =>
+  MIME_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+
+/** Whether `child` is `parent` itself or a path nested under it. */
+const isContained = (parent: string, child: string): boolean => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep));
+};
+
+/** Resolve a request URL to an on-disk file within one of the mounts, if any. */
+const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
+  const pathname = decodeURIComponent(
+    (url.split("?")[0] ?? "").split("#")[0] ?? ""
+  );
+  for (const mount of mounts) {
+    if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
+      continue;
+    }
+    // `.` + rel keeps the join relative so an absolute-looking suffix can't
+    // escape the mount; the containment check rejects `..` traversal outright.
+    const file = resolve(mount.dir, `.${pathname.slice(mount.url.length)}`);
+    if (isContained(mount.dir, file)) {
+      return file;
+    }
+  }
+  return null;
+};
+
+/** `statSync` that returns null instead of throwing on a missing file. */
+const statFile = (file: string): Stats | null => {
+  try {
+    return statSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * A dev-server middleware that serves `content.assets` mounts (top-level dirs
+ * kept in place, e.g. a migrated `images/`) at their site URL. Astro only serves
+ * `publicDir` in dev, so without this those references would 404. Non-matching
+ * requests, and any path that isn't a real file, fall through to Astro. Stat is
+ * synchronous — this is dev-only middleware and mirrors how sirv serves statics.
+ */
+export const serveAssetMounts =
+  (mounts: AssetMount[]) =>
+  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    if ((req.method !== "GET" && req.method !== "HEAD") || !req.url) {
+      next();
+      return;
+    }
+    const file = resolveRequest(req.url, mounts);
+    const stats = file ? statFile(file) : null;
+    if (!(file && stats?.isFile())) {
+      next();
+      return;
+    }
+    res.setHeader("Content-Type", mimeType(file));
+    res.setHeader("Content-Length", String(stats.size));
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    createReadStream(file).pipe(res);
+  };
+
+/**
+ * Copy every asset mount into the build output, mirroring what Astro does with
+ * `publicDir`. Runs on `astro:build:done` so in-place asset dirs ship in the
+ * final `dist/`. A missing source dir is skipped (it may be referenced but
+ * absent); `cp` handles both directories and single files.
+ */
+export const copyAssetMounts = async (
+  mounts: AssetMount[],
+  outDir: string
+): Promise<void> => {
+  for (const mount of mounts) {
+    if (!existsSync(mount.dir)) {
+      continue;
+    }
+    const dest = join(outDir, mount.url.replace(/^\/+/u, ""));
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs copies
+    await cp(mount.dir, dest, { recursive: true });
+  }
+};

package/src/astro/templates.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
+import { resolveAssetMounts } from "../core/assets.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { searchProviderMeta } from "../search/providers.ts";
@@ -304,10 +305,12 @@ export const astroConfigTemplate = (options: {
   if (needsSvelte) {
     integrations.push("svelte()");
   }
-  // Always mounted: injects user pages (a no-op when there are none) and wires
-  // up dev-server `Accept: text/markdown` negotiation over the content routes.
+  // Always mounted: injects user pages (a no-op when there are none), serves
+  // `content.assets` mounts, and wires up dev-server `Accept: text/markdown`
+  // negotiation over the content routes.
+  const assets = resolveAssetMounts(context.root, config.content.assets);
   integrations.push(
-    `blumeIntegration(${JSON.stringify({ contentRoutes, pages })})`
+    `blumeIntegration(${JSON.stringify({ assets, base: deployment.base, contentRoutes, pages })})`
   );
 
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
@@ -459,32 +462,49 @@ export const askEndpointTemplate = (
   if (grounded) {
     imports.push(
       'import { createAskContext } from "blume/ai/ask-context.ts";',
-      'import askData from "../generated/ask-data.json";'
+      'import askData from "../../generated/ask-data.json";'
     );
     setup += "\nconst ground = createAskContext(askData);\n";
   }
-  const handler = grounded
-    ? `export const POST: APIRoute = async ({ request }) => {
-  const { messages, page } = await request.json();
-  const system =
-    (await ground(messages, page)) ??
-    "You are a helpful documentation assistant. Answer using the project's documentation.";
-  const result = streamText({
-    model: ${modelExpr},
-    system,
-    messages,
-  });
-  return result.toTextStreamResponse();
-};`
-    : `export const POST: APIRoute = async ({ request }) => {
-  const { messages } = await request.json();
-  const result = streamText({
-    model: ${modelExpr},
-    system:
-      "You are a helpful documentation assistant. Answer using the project's documentation.",
-    messages,
-  });
-  return result.toTextStreamResponse();
+  // Validate the client-supplied body and cap its size. The endpoint is
+  // unauthenticated, so bounding message count/length limits how much a caller
+  // can spend against the model per request; front it with a rate limiter (or
+  // your provider's limits) for stronger protection.
+  const validate = `  const body = await request.json().catch(() => null);
+  const messages = body?.messages;
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.length > 40 ||
+    JSON.stringify(messages).length > 24_000
+  ) {
+    return new Response("Invalid request: send 1-40 messages.", {
+      status: 400,
+    });
+  }`;
+  const stream = grounded
+    ? `    const system =
+      (await ground(messages, body.page)) ??
+      "You are a helpful documentation assistant. Answer using the project's documentation.";
+    const result = streamText({
+      model: ${modelExpr},
+      system,
+      messages,
+    });`
+    : `    const result = streamText({
+      model: ${modelExpr},
+      system:
+        "You are a helpful documentation assistant. Answer using the project's documentation.",
+      messages,
+    });`;
+  const handler = `export const POST: APIRoute = async ({ request }) => {
+${validate}
+  try {
+${stream}
+    return result.toTextStreamResponse();
+  } catch {
+    return new Response("Failed to generate a response.", { status: 500 });
+  }
 };`;
   return `// Generated by Blume. Do not edit.
 ${imports.join("\n")}
@@ -905,6 +925,7 @@ import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
+import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
@@ -950,6 +971,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
 };

package/src/cli/args.ts

@@ -0,0 +1,23 @@
+import { logger } from "./log.ts";
+
+const MAX_PORT = 65_535;
+
+/**
+ * Parse a `--port` value into a valid port number, or `undefined` when unset.
+ * A non-integer or out-of-range value (`--port abc` → `NaN`) exits with an
+ * error rather than propagating `localhost:NaN` into the dev server and the
+ * `deployment.site` fallback.
+ */
+export const parsePort = (value?: string): number | undefined => {
+  if (value === undefined) {
+    return;
+  }
+  const port = Number(value);
+  if (!(Number.isInteger(port) && port >= 1 && port <= MAX_PORT)) {
+    logger.error(
+      `Invalid --port "${value}" (expected an integer 1-${MAX_PORT}).`
+    );
+    process.exit(1);
+  }
+  return port;
+};

package/src/cli/commands/build.ts

@@ -17,11 +17,32 @@ import { buildRobots } from "../../deploy/robots.ts";
 import { buildSitemap } from "../../deploy/sitemap.ts";
 import { buildSearchIndex } from "../../search/build.ts";
 import { syncSearchProvider } from "../../search/sync/index.ts";
+import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+/**
+ * Reject a non-numeric performance budget. `Number("250kb")` is `NaN` and
+ * `total > NaN` is always false, so a typo'd flag would silently pass the gate;
+ * fail up front instead.
+ */
+const validateBudgetFlags = (args: {
+  "budget-css"?: string;
+  "budget-js"?: string;
+}): void => {
+  for (const flag of ["budget-js", "budget-css"] as const) {
+    const value = args[flag];
+    if (value !== undefined && !(Number(value) > 0)) {
+      logger.error(
+        `Invalid --${flag} "${value}" (expected a positive number of kB).`
+      );
+      process.exit(1);
+    }
+  }
+};
+
 /**
  * Emit platform redirect files for a static build (adapters wire redirects
  * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
@@ -186,6 +207,7 @@ export const buildCommand = defineCommand({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "building");
 
     if (args.output && args.output !== "static" && args.output !== "server") {
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
@@ -197,6 +219,7 @@ export const buildCommand = defineCommand({
       );
       process.exit(1);
     }
+    validateBudgetFlags(args);
 
     const project = await prepareProject({
       mode: "build",

package/src/cli/commands/dev.ts

@@ -6,6 +6,8 @@ import { defineCommand } from "citty";
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
+import { parsePort } from "../args.ts";
+import { acquireDevLock } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -41,7 +43,8 @@ export const devCommand = defineCommand({
     // Astro's dev server defaults to 4321 when no port is passed. Feeding the
     // resolved URL in as the `deployment.site` fallback lets site-gated features
     // (OG images, canonicals, sitemap) work locally without configuring a site.
-    const port = args.port ? Number(args.port) : 4321;
+    const explicitPort = parsePort(args.port);
+    const port = explicitPort ?? 4321;
     const devServerUrl = `http://localhost:${port}`;
     const project = await prepareProject({
       devServerUrl,
@@ -58,13 +61,18 @@ export const devCommand = defineCommand({
       );
     }
 
+    // Claim the shared `.blume` dir so a concurrent build/eject/sync refuses
+    // rather than regenerating or deleting it out from under this server.
+    const releaseLock = acquireDevLock(project.context.outDir);
+    process.on("exit", releaseLock);
+
     const server = await dev({
       logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
       server: {
         host: args.host ?? false,
         open: args.open ?? false,
-        port: args.port ? Number(args.port) : undefined,
+        port: explicitPort,
       },
     });
 
@@ -118,6 +126,7 @@ export const devCommand = defineCommand({
       for (const dispose of disposers) {
         dispose();
       }
+      releaseLock();
       await server.stop();
       process.exit(0);
     };

package/src/cli/commands/doctor.ts

@@ -5,7 +5,12 @@ import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 const MIN_NODE_MAJOR = 20;
 
@@ -74,7 +79,11 @@ export const doctorCommand = defineCommand({
     }
 
     if (args.json) {
+      // Drain stdout before exiting non-zero: `process.exit` would otherwise
+      // truncate the JSON payload mid-write when stdout is a pipe — exactly how
+      // `--json` is consumed in CI/editors.
       if (reportDiagnosticsJson(diagnostics, root)) {
+        await flushStdout();
         process.exit(1);
       }
       return;

package/src/cli/commands/eject.ts

@@ -4,6 +4,7 @@ import { defineCommand } from "citty";
 import { join, relative } from "pathe";
 
 import { eject } from "../../registry/eject.ts";
+import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 
 const updatePackageScripts = async (root: string): Promise<void> => {
@@ -34,10 +35,11 @@ export const ejectCommand = defineCommand({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "ejecting");
 
     if (!args.yes) {
       logger.warn(
-        "Eject is one-way: it writes astro.config.mjs and src/ into your project and removes .blume."
+        "Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched."
       );
       logger.info("Re-run with --yes to proceed.");
       return;

package/src/cli/commands/init.ts

@@ -2,8 +2,9 @@ import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 
 import { defineCommand } from "citty";
-import { basename, dirname, join } from "pathe";
+import { basename, dirname, isAbsolute, join, relative } from "pathe";
 
+import { ensureGitignore } from "../../core/gitignore.ts";
 import { getBlumeVersion } from "../../core/version.ts";
 import { eject } from "../../registry/eject.ts";
 import { logger } from "../log.ts";
@@ -190,6 +191,17 @@ export const initCommand = defineCommand({
   async run({ args }) {
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
+    // The content dir is joined into every scaffolded file path, so an absolute
+    // or `../`-escaping value would write outside the project. Reject it.
+    if (
+      isAbsolute(contentDir) ||
+      relative(root, join(root, contentDir)).startsWith("..")
+    ) {
+      logger.error(
+        `Invalid --content-dir "${contentDir}" (must be a path inside the project).`
+      );
+      process.exit(1);
+    }
 
     const template = (args.template ?? "docs") as Template;
     if (!TEMPLATES.includes(template)) {
@@ -218,6 +230,14 @@ export const initCommand = defineCommand({
         .map((file) => writeFileSafe(join(root, file.path), file.content))
     );
 
+    // Keep Blume's generated runtime (`.blume/`) and build output (`dist/`) out
+    // of version control. Idempotent: creates `.gitignore` when absent and skips
+    // entries already present (trailing-slash agnostic).
+    const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+    if (ignored.length > 0) {
+      logger.success(`Added ${ignored.join(", ")} to .gitignore`);
+    }
+
     const commands = commandsFor(pm);
 
     if (args.eject) {

package/src/cli/commands/preview.ts

@@ -6,6 +6,7 @@ import { join } from "pathe";
 
 import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
+import { parsePort } from "../args.ts";
 import { logger } from "../log.ts";
 
 export const previewCommand = defineCommand({
@@ -32,7 +33,7 @@ export const previewCommand = defineCommand({
       root: context.outDir,
       server: {
         host: args.host ?? false,
-        port: args.port ? Number(args.port) : undefined,
+        port: parsePort(args.port),
       },
     });
   },

package/src/cli/commands/validate.ts

@@ -3,12 +3,18 @@ import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { resolveAssetMounts } from "../../core/assets.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { validateLinks } from "../../core/links.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 export const validateCommand = defineCommand({
   args: {
@@ -42,6 +48,7 @@ export const validateCommand = defineCommand({
       const publicDir = join(root, "public");
       diagnostics.push(
         ...(await validateLinks(project.graph, {
+          assetMounts: resolveAssetMounts(root, project.config.content.assets),
           checkExternal: Boolean(args.external),
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
@@ -57,8 +64,12 @@ export const validateCommand = defineCommand({
     }
 
     if (args.json) {
+      // Drain stdout before exiting non-zero: `process.exit` would otherwise
+      // truncate the JSON payload mid-write when stdout is a pipe — exactly how
+      // `--json` is consumed in CI/editors.
       const hadErrors = reportDiagnosticsJson(diagnostics, root);
       if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+        await flushStdout();
         process.exit(1);
       }
       return;

package/src/cli/dev-lock.ts

@@ -0,0 +1,84 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+
+import { join } from "pathe";
+
+import { logger } from "./log.ts";
+
+/**
+ * A best-effort PID lock in the shared `.blume/` runtime dir. `blume dev`
+ * regenerates and serves `.blume` continuously, so a concurrent `build`,
+ * `eject`, or `sync --force` that regenerates or deletes it out from under the
+ * running Vite server corrupts the dev session. The lock lets those commands
+ * detect a live dev server and refuse.
+ */
+
+const lockPath = (outDir: string): string => join(outDir, "dev.lock");
+
+/**
+ * Whether another live `blume dev` holds the lock on `outDir`. A lock left by a
+ * process that has since exited (stale) is treated as absent.
+ */
+export const isDevLocked = (outDir: string): boolean => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return false;
+  }
+  const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
+  if (!(Number.isInteger(pid) && pid > 0)) {
+    return false;
+  }
+  try {
+    // Signal 0 probes liveness without actually signaling the process.
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Write the current process's dev lock into `outDir` and return a release
+ * function. The release only removes the file if it's still ours, so a newer
+ * dev server's lock is never clobbered.
+ */
+export const acquireDevLock = (outDir: string): (() => void) => {
+  const path = lockPath(outDir);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path, String(process.pid));
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    try {
+      if (
+        existsSync(path) &&
+        readFileSync(path, "utf-8").trim() === String(process.pid)
+      ) {
+        rmSync(path, { force: true });
+      }
+    } catch {
+      // Best-effort cleanup; a stale lock is handled by the liveness check.
+    }
+  };
+};
+
+/**
+ * Exit with an error when a live `blume dev` owns the `.blume` dir under `root`.
+ * `action` names the operation being refused (e.g. "building").
+ */
+export const refuseIfDevRunning = (root: string, action: string): void => {
+  if (isDevLocked(join(root, ".blume"))) {
+    logger.error(
+      `A \`blume dev\` server is running against .blume; ${action} would corrupt it. Stop the dev server first.`
+    );
+    process.exit(1);
+  }
+};

package/src/cli/log.ts

@@ -11,6 +11,17 @@ import type { Diagnostic } from "../core/types.ts";
 
 export const logger = consola.withTag("blume");
 
+/**
+ * Resolve once stdout has drained. `process.exit` doesn't flush a piped stdout,
+ * so await this before exiting non-zero after writing machine-readable output
+ * (e.g. `--json`), otherwise the payload can be truncated in CI.
+ */
+export const flushStdout = (): Promise<void> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt stdout's write callback
+  new Promise((resolve) => {
+    process.stdout.write("", () => resolve());
+  });
+
 /**
  * Print diagnostics as a JSON document on stdout for CI and editors: each is
  * enriched with its `docsUrl` and its `file` made root-relative. Returns whether

package/src/components/BlumePage.astro

@@ -50,6 +50,7 @@ import TreeFile from "./content/TreeFile.astro";
 import TreeFolder from "./content/TreeFolder.astro";
 import TypeTable from "./content/TypeTable.astro";
 import Visibility from "./content/Visibility.astro";
+import YouTube from "./content/YouTube.astro";
 
 interface Props {
   /** Astro collection the entry lives in. Defaults to `"docs"`. */
@@ -96,6 +97,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ...extra,
 };
 

package/src/components/content/YouTube.astro

@@ -0,0 +1,35 @@
+---
+import { parseYouTubeId, youtubeEmbedUrl } from "./youtube.ts";
+
+interface Props {
+  /** A YouTube video id (e.g. `dQw4w9WgXcQ`). */
+  id?: string;
+  /** Start playback this many seconds in. */
+  start?: number;
+  /** Accessible title for the embedded player. */
+  title?: string;
+  /** A full YouTube URL to extract the id from, as an alternative to `id`. */
+  url?: string;
+}
+
+const { id, start, title = "YouTube video player", url } = Astro.props;
+
+const videoId = parseYouTubeId(id ?? url ?? "");
+const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
+---
+
+{
+  src && (
+    <div class="not-prose my-6 aspect-video overflow-hidden rounded-blume border border-border bg-muted/30">
+      <iframe
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowfullscreen
+        class="h-full w-full"
+        loading="lazy"
+        referrerpolicy="strict-origin-when-cross-origin"
+        src={src}
+        title={title}
+      />
+    </div>
+  )
+}