blume 1.7.2 → 2.0.0

package/src/migrate/migrate.ts

@@ -0,0 +1,149 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+/**
+ * `blume migrate`'s logic, kept out of the command module so it runs (and is
+ * covered) in-process. Migration is judgment work — idiomatic navigation,
+ * component rewrites, what to drop — so it stays in the `blume-migrate` skill,
+ * shipped inside the package; this module only names the source (from the
+ * argument, or detected from the repo's own files) and writes the prompt that
+ * points a coding agent at the skill and that source's mappings.
+ */
+
+/** The docs frameworks the skill has a mapping reference for. */
+export const MIGRATE_SOURCES = [
+  "mintlify",
+  "fumadocs",
+  "docusaurus",
+  "starlight",
+  "nextra",
+] as const;
+
+export type MigrateSourceId = (typeof MIGRATE_SOURCES)[number];
+
+/** Display names, for messages and the prompt. */
+export const MIGRATE_SOURCE_NAMES: Record<MigrateSourceId, string> = {
+  docusaurus: "Docusaurus",
+  fumadocs: "Fumadocs",
+  mintlify: "Mintlify",
+  nextra: "Nextra",
+  starlight: "Starlight",
+};
+
+/** The skill's directory inside the published package. */
+export const MIGRATE_SKILL_DIR = join("skills", "blume-migrate");
+
+export const isMigrateSource = (value: string): value is MigrateSourceId =>
+  MIGRATE_SOURCES.some((source) => source === value);
+
+/** A detected source and the file or dependency that gave it away. */
+export interface DetectedSource {
+  evidence: string;
+  source: MigrateSourceId;
+}
+
+/** The slice of `package.json` detection reads. */
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+/** Every dependency the project's `package.json` names, or none when unreadable. */
+const dependencyNames = async (root: string): Promise<Set<string>> => {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return new Set();
+  }
+  try {
+    // SAFETY: package.json is a JSON object; only its dependency maps are read.
+    const pkg = JSON.parse(await readFile(path, "utf-8")) as PackageJson;
+    return new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+  } catch {
+    // A malformed package.json is the agent's to deal with; detection just
+    // falls back to the other signals.
+    return new Set();
+  }
+};
+
+/**
+ * Each source's tell, in the order the skill's workflow checks them: a config
+ * file the framework owns, or a dependency only it installs.
+ */
+const SIGNALS: {
+  deps?: string[];
+  files?: string[];
+  source: MigrateSourceId;
+}[] = [
+  { files: ["docs.json", "mint.json"], source: "mintlify" },
+  {
+    files: [
+      "docusaurus.config.ts",
+      "docusaurus.config.js",
+      "docusaurus.config.mjs",
+      "docusaurus.config.cjs",
+    ],
+    source: "docusaurus",
+  },
+  {
+    deps: ["fumadocs-core", "fumadocs-ui", "fumadocs-mdx"],
+    files: ["source.config.ts"],
+    source: "fumadocs",
+  },
+  { deps: ["nextra"], source: "nextra" },
+  { deps: ["@astrojs/starlight"], source: "starlight" },
+];
+
+/**
+ * Detect the docs framework a project is built on from its own files, or
+ * null when nothing gives it away (the skill still migrates any framework,
+ * working from its general model instead of a mapping reference).
+ */
+export const detectMigrateSource = async (
+  root: string
+): Promise<DetectedSource | null> => {
+  const deps = await dependencyNames(root);
+  for (const { deps: tells = [], files = [], source } of SIGNALS) {
+    const file = files.find((name) => existsSync(join(root, name)));
+    if (file) {
+      return { evidence: file, source };
+    }
+    const dep = tells.find((name) => deps.has(name));
+    if (dep) {
+      return { evidence: `${dep} in package.json`, source };
+    }
+  }
+  return null;
+};
+
+/**
+ * The handoff prompt: follow the skill, where its mappings for this source
+ * are, and the few rules worth restating — the target version, and that no
+ * page or URL is lost.
+ */
+export const migratePrompt = (options: {
+  detected: DetectedSource | null;
+  skillDir: string;
+  source: MigrateSourceId | null;
+  version: string;
+}): string => {
+  const { detected, skillDir, source, version } = options;
+  const evidence =
+    detected && detected.source === source
+      ? ` (detected from ${detected.evidence})`
+      : "";
+  const sourceLine = source
+    ? `The source is ${MIGRATE_SOURCE_NAMES[source]}${evidence}. Its exact mappings are in ${join(skillDir, "references", `${source}.md`)}.`
+    : `The source framework wasn't detected, so inventory the repo first. If it's ${MIGRATE_SOURCES.map((id) => MIGRATE_SOURCE_NAMES[id]).join(", ")}, read that framework's file in ${join(skillDir, "references")}; otherwise follow the skill's mental model directly.`;
+  return `Migrate this documentation project to Blume ${version}.
+
+Follow the blume-migrate skill: read ${join(skillDir, "SKILL.md")} first and work through its migration workflow. Wherever the skill says \`<skill>\`, it means ${skillDir}.
+
+${sourceLine}
+
+Add \`blume@^${version}\` as the docs package's dependency. Keep every page, and add a redirect for any URL that moves. Report everything you drop or approximate, and run the skill's verification steps before you finish.`;
+};

package/src/openapi/parse.ts

@@ -1,18 +1,24 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 
-import type { AsyncAPIDocument as ConverterDocument } from "@asyncapi/converter";
-import { convert } from "@asyncapi/converter";
+import type * as ConverterModule from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
 import { isAbsolute, join } from "pathe";
+import type * as UndiciModule from "undici";
 
+import {
+  commandsFor,
+  detectProjectPackageManager,
+} from "../cli/init/scaffold.ts";
+import { nodeRequire } from "../core/node-require.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
+import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
  * Spec loading and normalization. Blume reuses Scalar's parser
@@ -83,18 +89,21 @@ export interface SpecFetchOptions {
  * spec is fetched with one configured. Node's built-in `fetch` ignores `*_PROXY`
  * on its own; undici's env proxy agent, installed on the shared global-dispatcher
  * symbol, wires it in without replacing `fetch` (so tests can still stub it).
- * Best-effort and lazy: no proxy env means no undici import at all, and an
+ * Best-effort and lazy: no proxy env means undici never loads, and an
  * unavailable undici just leaves the direct connection in place.
  */
 let proxyInstalled = false;
-const ensureProxyDispatcher = async (): Promise<void> => {
+const ensureProxyDispatcher = (): void => {
   // Only memoize a successful install: with no proxy configured we cheaply
   // re-check each time, so a proxy set later in the process still takes effect.
   if (proxyInstalled || !PROXY_ENV_VARS.some((name) => process.env[name])) {
     return;
   }
   try {
-    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    // `require`, not `import()`: an ejected app scans in `astro:build:done`
+    // (see `core/node-require.ts`).
+    const { EnvHttpProxyAgent, setGlobalDispatcher }: typeof UndiciModule =
+      nodeRequire("undici");
     setGlobalDispatcher(new EnvHttpProxyAgent());
     proxyInstalled = true;
   } catch {
@@ -177,7 +186,7 @@ const retryableFetchError = (
 
 /** Fetch a remote spec's text, retrying transient failures with backoff. */
 const fetchSpecText = async (spec: string): Promise<string> => {
-  await ensureProxyDispatcher();
+  ensureProxyDispatcher();
   return await pRetry(
     async () => {
       const attempt = await attemptFetch(spec);
@@ -323,15 +332,6 @@ export interface ParsedAsyncApiSpec {
   warnings: string[];
 }
 
-/**
- * Read and normalize a spec to an AsyncAPI 3.x document — the AsyncAPI mirror
- * of {@link parseSpec}. 1.x/2.x documents are lifted to 3.0 with the official
- * `@asyncapi/converter` (channels + operations with `send`/`receive` actions),
- * so the extractor and components only ever handle one shape; `$ref`s stay
- * intact, matching the OpenAPI path. Error semantics match `parseSpec`: an
- * unreadable spec throws, a readable non-AsyncAPI document throws
- * {@link InvalidSpecError}, and callers lower both into source diagnostics.
- */
 /**
  * An object carrying a non-empty `asyncapi` version string — the only input
  * the converter and extractor can key on. `normalize` yields undefined for
@@ -346,6 +346,53 @@ const isAsyncApiDocument = <Value>(
   typeof value.asyncapi === "string" &&
   value.asyncapi !== "";
 
+const CONVERTER = "@asyncapi/converter";
+
+/**
+ * Load `@asyncapi/converter`, an optional peer. Only a 1.x/2.x spec needs it,
+ * and it depends on `@asyncapi/parser` — which it never loads — and so on
+ * Spectral and Scarf's telemetry postinstall, an unapproved build script that
+ * pnpm 12 refuses to install past. Leaving it out of a default install keeps
+ * `pnpm dlx blume` working; a spec that needs it gets the install command
+ * instead, through {@link SpecDependencyError}.
+ */
+const loadConverter = async (
+  spec: string,
+  version: string,
+  root: string
+): Promise<typeof ConverterModule> => {
+  try {
+    // `require`, not `import()`: see `core/node-require.ts`.
+    const converter: typeof ConverterModule = nodeRequire(CONVERTER);
+    return converter;
+  } catch (error) {
+    // SAFETY: a failed `require` throws a Node error; `code` and `message`
+    // are the only fields read.
+    const { code, message } = error as NodeJS.ErrnoException;
+    // Only the converter itself missing is the project's to fix; anything
+    // else (a broken install of one of its own dependencies) surfaces as is.
+    if (code !== "MODULE_NOT_FOUND" || !message.includes(`'${CONVERTER}'`)) {
+      throw error;
+    }
+    const { add } = commandsFor(await detectProjectPackageManager(root));
+    throw new SpecDependencyError(
+      `${spec} is AsyncAPI ${version}, and converting it to AsyncAPI 3.0 needs "${CONVERTER}", which isn't installed`,
+      `Install it with \`${add} ${CONVERTER}\`, or convert the spec to AsyncAPI 3.0.`
+    );
+  }
+};
+
+/**
+ * Read and normalize a spec to an AsyncAPI 3.x document — the AsyncAPI mirror
+ * of {@link parseSpec}. 1.x/2.x documents are lifted to 3.0 with the official
+ * `@asyncapi/converter` (channels + operations with `send`/`receive` actions),
+ * so the extractor and components only ever handle one shape; `$ref`s stay
+ * intact, matching the OpenAPI path. Error semantics match `parseSpec`: an
+ * unreadable spec throws, a readable non-AsyncAPI document throws
+ * {@link InvalidSpecError}, a pre-3.0 document without the converter installed
+ * throws {@link SpecDependencyError}, and callers lower all three into source
+ * diagnostics.
+ */
 export const parseAsyncApiSpec = async (
   spec: string,
   root: string,
@@ -361,6 +408,7 @@ export const parseAsyncApiSpec = async (
   const version = normalized.asyncapi;
   let document: AsyncApiDocument = normalized;
   if (!version.startsWith("3.")) {
+    const { convert } = await loadConverter(spec, version, root);
     // The converter reports lossy conversions (e.g. a 2.x parameter schema
     // that 3.0 can't express) through console.warn — capture those as spec
     // warnings instead of letting them leak into CLI output.
@@ -374,7 +422,7 @@ export const parseAsyncApiSpec = async (
       // the 3.0 shape the extractor consumes; the two packages just declare
       // the document type differently.
       document = convert(
-        document as ConverterDocument,
+        document as Parameters<typeof convert>[0],
         "3.0.0"
       ) as AsyncApiDocument;
     } catch (error) {

package/src/openapi/proxy.ts

@@ -1,16 +1,19 @@
 /**
  * The playground's CORS proxy. Browsers block the "Try it" panel's `fetch`
  * whenever the documented API doesn't allow cross-origin requests from the
- * docs site, so `openapi.playground.proxy: true` mounts this handler at
+ * docs site, so `playground: { proxy: true }` on an `openapi()` reference
+ * mounts this handler at
  * `/_api-proxy` (server output only) and the client sends its real request
  * here as `?url=<encoded target>` instead. The handler replays the request
  * upstream and mirrors the response back, so the browser only ever talks
  * same-origin.
  *
- * Kept dependency-free and `fetch`-injectable so it unit-tests without a
+ * Kept dependency-light and `fetch`-injectable so it unit-tests without a
  * network and stays safe to bundle into the generated endpoint file.
  */
 
+import { readCappedBody } from "../core/request-body.ts";
+
 /**
  * Request headers never forwarded upstream: hop-by-hop headers describe this
  * connection (not the upstream one), `host`/`origin`/`referer` would leak or
@@ -60,6 +63,38 @@ const MAX_REDIRECTS = 20;
  */
 const UPSTREAM_TIMEOUT_MS = 30_000;
 
+/**
+ * Largest request body the proxy forwards: 4 MiB, under Vercel's 4.5 MB
+ * function limit, so a request that works on one host works on the others.
+ * The body is buffered before it's replayed, and a self-hosted Node server
+ * has no platform cap of its own, so without this one oversized POST could
+ * allocate its whole size in the server's memory.
+ */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Headers every proxied response carries. The proxy serves another host's
+ * bytes from the docs origin, so an upstream HTML page — an error page that
+ * echoes its input, say — would otherwise run script as the docs site for
+ * anyone who opens a crafted `/_api-proxy?url=…` link. `sandbox` gives such a
+ * page an opaque origin with scripts off, `nosniff` stops a mistyped body
+ * being rendered as HTML, and `same-origin` keeps other sites from embedding
+ * the responses. None of them affect the playground's own `fetch`.
+ */
+const RESPONSE_SECURITY_HEADERS = {
+  "Content-Security-Policy": "sandbox; default-src 'none'",
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "X-Content-Type-Options": "nosniff",
+} satisfies Record<string, string>;
+
+/**
+ * Media types a browser would render as a document when the proxy URL is
+ * opened directly. Their responses are also marked as downloads, so even a
+ * browser that ignores the sandbox saves the page instead of showing it.
+ */
+const DOCUMENT_TYPE =
+  /^\s*(?:text\/html|application\/xhtml\+xml|image\/svg\+xml)\b/iu;
+
 /** A 400 the playground client can render verbatim. */
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
@@ -99,7 +134,7 @@ const forbidden = (origin: string): Response =>
  */
 const followUpstream = async (args: {
   allowed: ReadonlySet<string>;
-  body: ArrayBuffer | undefined;
+  body: Uint8Array<ArrayBuffer> | undefined;
   fetchImpl: typeof fetch;
   headers: Headers;
   /** Hops already followed; the chain is bounded by {@link MAX_REDIRECTS}. */
@@ -166,12 +201,15 @@ const followUpstream = async (args: {
  *
  * `timeoutMs` bounds the upstream exchange (see {@link UPSTREAM_TIMEOUT_MS});
  * an upstream that doesn't answer in time is the same 502 as an unreachable
- * one. Injectable so tests don't wait out the real deadline.
+ * one. Injectable so tests don't wait out the real deadline. A request body
+ * over `maxBodyBytes` (see {@link MAX_BODY_BYTES}) is a 413, and every
+ * mirrored response carries {@link RESPONSE_SECURITY_HEADERS}.
  */
 export const createPlaygroundProxyHandler = (
   origins: readonly string[],
   fetchImpl: typeof fetch = fetch,
-  timeoutMs = UPSTREAM_TIMEOUT_MS
+  timeoutMs = UPSTREAM_TIMEOUT_MS,
+  maxBodyBytes = MAX_BODY_BYTES
 ) => {
   const allowed = new Set(origins);
   return async (request: Request): Promise<Response> => {
@@ -194,11 +232,19 @@ export const createPlaygroundProxyHandler = (
 
     // Buffer the body instead of streaming it: GET/HEAD must not carry one
     // (fetch rejects it), and a buffered body avoids the `duplex` requirement
-    // streaming request bodies have in Node.
-    const body =
-      request.method === "GET" || request.method === "HEAD"
-        ? undefined
-        : await request.arrayBuffer();
+    // streaming request bodies have in Node. The buffer is capped.
+    const bodyless = request.method === "GET" || request.method === "HEAD";
+    const body = bodyless
+      ? undefined
+      : await readCappedBody(request, maxBodyBytes);
+    if (!bodyless && body === undefined) {
+      return Response.json(
+        {
+          error: `The request body is larger than the ${maxBodyBytes}-byte limit the docs proxy forwards.`,
+        },
+        { status: 413 }
+      );
+    }
 
     let upstream: Response;
     try {
@@ -233,6 +279,12 @@ export const createPlaygroundProxyHandler = (
     // Marks proxied responses so the client (and debugging humans) can tell
     // them apart from direct responses.
     headers.set("x-blume-proxy", "1");
+    for (const [name, value] of Object.entries(RESPONSE_SECURITY_HEADERS)) {
+      headers.set(name, value);
+    }
+    if (DOCUMENT_TYPE.test(headers.get("content-type") ?? "")) {
+      headers.set("Content-Disposition", "attachment");
+    }
     return new Response(upstream.body, {
       headers,
       status: upstream.status,