@mandujs/core 0.43.1 → 0.45.0

package/src/design/parser.ts

@@ -0,0 +1,555 @@
+/**
+ * DESIGN.md parser — the 9-section heading walker.
+ *
+ * Strategy:
+ *   1. Optional H1 title at the top of the file.
+ *   2. Scan H2 headings. Match each against the 9 canonical sections
+ *      via a fuzzy-but-bounded resolver (lowercase, strip `&` / `'`,
+ *      collapse whitespace). Unrecognized headings land in
+ *      `extraSections` so the file round-trips cleanly.
+ *   3. For each matched section, parse the body into structured
+ *      tokens with a section-specific extractor. Extractors are
+ *      forgiving — a malformed row is skipped, never fatal.
+ *
+ * Parsing must NEVER throw on real-world DESIGN.md files. The 69
+ * brand entries in awesome-design-md vary wildly in formatting; the
+ * parser is the contract that smooths them out for the rest of Mandu.
+ *
+ * @module core/design/parser
+ */
+
+import type {
+  AgentPrompt,
+  AnyDesignSection,
+  ColorToken,
+  ComponentToken,
+  DesignSectionId,
+  DesignSpec,
+  DoDontRule,
+  ResponsiveBreakpoint,
+  ShadowToken,
+  SpacingToken,
+  TypographyToken,
+  ValidationIssue,
+  ValidationResult,
+} from "./types";
+
+import { DESIGN_SECTION_IDS } from "./types";
+
+// ────────────────────────────────────────────────────────────────────
+// Heading → section-id resolution
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Match heading text against the 9 canonical section ids. Returns the
+ * id when the heading "looks like" the section by keyword, else null.
+ * The keyword sets are intentionally redundant to absorb the wording
+ * differences across the awesome-design-md catalog.
+ */
+function resolveSectionId(heading: string): DesignSectionId | null {
+  const h = heading
+    .toLowerCase()
+    .replace(/[&'`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (/^visual|^theme|^philosophy|^vibe|^aesthetic/.test(h)) return "theme";
+  if (/color|palette/.test(h)) return "color-palette";
+  if (/typograph|typeface|font|type scale/.test(h)) return "typography";
+  if (/component|button|card|input/.test(h)) return "components";
+  if (/layout|spacing|grid|whitespace/.test(h)) return "layout";
+  if (/shadow|elevation|depth/.test(h)) return "shadows";
+  if (/do.{0,3}dont|guideline|principle|rule/.test(h)) return "dos-donts";
+  if (/responsive|breakpoint|mobile|tablet|desktop/.test(h)) return "responsive";
+  if (/agent|prompt|llm|ai/.test(h)) return "agent-prompts";
+  return null;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// H2 splitter
+// ────────────────────────────────────────────────────────────────────
+
+interface RawSection {
+  heading: string;
+  /** `1` or `2` — H1 or H2. */
+  level: number;
+  body: string;
+}
+
+/**
+ * Strip HTML comments (`<!-- … -->`) before structural parsing. The
+ * empty-skeleton template uses HTML comments to show example tokens
+ * without having them counted as real tokens; the parser must respect
+ * that convention. Multi-line comments are supported.
+ */
+function stripHtmlComments(source: string): string {
+  return source.replace(/<!--[\s\S]*?-->/g, "");
+}
+
+function splitByHeadings(source: string): {
+  title?: string;
+  sections: RawSection[];
+} {
+  const lines = stripHtmlComments(source).split(/\r?\n/);
+  let title: string | undefined;
+  const sections: RawSection[] = [];
+  let current: RawSection | null = null;
+
+  // H1 detection — first non-empty line is `# Foo` or first `# Foo` before
+  // any H2. Only the first H1 is treated as title.
+  let titleConsumed = false;
+
+  for (const line of lines) {
+    const h1 = /^#\s+(.+?)\s*$/.exec(line);
+    const h2 = /^##\s+(.+?)\s*$/.exec(line);
+    if (h1 && !titleConsumed && current === null) {
+      title = h1[1].trim();
+      titleConsumed = true;
+      continue;
+    }
+    if (h2) {
+      if (current) sections.push(current);
+      current = { heading: h2[1].trim(), level: 2, body: "" };
+      continue;
+    }
+    if (current) {
+      current.body += (current.body ? "\n" : "") + line;
+    }
+  }
+  if (current) sections.push(current);
+  return { title, sections };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Section extractors
+// ────────────────────────────────────────────────────────────────────
+
+const COLOR_VALUE_RX =
+  /(#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|oklch\([^)]+\)|oklab\([^)]+\))/;
+
+function extractColorTokens(body: string): ColorToken[] {
+  const tokens: ColorToken[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim().replace(/^[-*+]\s*/, "").replace(/^\|\s*/, "").replace(/\s*\|.*$/, "");
+    if (!trimmed) continue;
+    const valueMatch = COLOR_VALUE_RX.exec(line);
+    // Try patterns:
+    //   - `name — #hex — role`
+    //   - `name: #hex (role)`
+    //   - `**name** \`#hex\` — role`
+    //   - `| name | #hex | role |` (markdown table row)
+    const stripped = line
+      .replace(/[`*_]/g, "")
+      .replace(/^[\s|>-]+/, "")
+      .replace(/\s*\|.*$/, "");
+    const sepMatch = /^([^:—–\-]+?)[\s]*[:—–\-][\s]*(.+)$/.exec(stripped);
+    let name: string | undefined;
+    let role: string | undefined;
+    if (sepMatch) {
+      name = sepMatch[1].trim();
+      const rest = sepMatch[2];
+      // role is whatever isn't the colour value
+      if (valueMatch) {
+        role = rest.replace(valueMatch[0], "").replace(/[\s—–\-:|]+/g, " ").trim() || undefined;
+      } else {
+        role = rest.trim() || undefined;
+      }
+    }
+    if (!name && valueMatch) {
+      // Fallback — colour value present but no clear "name : value" split.
+      name = stripped.replace(valueMatch[0], "").trim() || valueMatch[0];
+    }
+    if (!name) continue;
+    if (name.length > 100) continue; // garbage line
+    // Filter out heading-like rows ("Color Palette", "Functional Roles", ...).
+    if (/palette|role/i.test(name) && !valueMatch) continue;
+    tokens.push({
+      name,
+      value: valueMatch ? valueMatch[0] : undefined,
+      role,
+    });
+  }
+  return tokens;
+}
+
+function extractTypographyTokens(body: string): TypographyToken[] {
+  const tokens: TypographyToken[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim().replace(/^[-*+]\s*/, "");
+    if (!trimmed) continue;
+    if (trimmed.startsWith("#")) continue; // sub-headings
+    const stripped = trimmed.replace(/[`*_]/g, "");
+    const nameMatch = /^([^:—–]+?)[\s]*[:—–]/.exec(stripped);
+    const name = nameMatch ? nameMatch[1].trim() : stripped.split(/\s{2,}|—|–/)[0]?.trim();
+    if (!name) continue;
+    const fontFamily = /font[\s-]*family[:\s]+([^,;]+)/i.exec(stripped)?.[1]?.trim();
+    const weight = /weight[:\s]+([0-9]{3}|bold|semi-?bold|medium|regular|light|thin)/i.exec(stripped)?.[1]?.trim();
+    const size = /(\d+(?:\.\d+)?(?:px|rem|em|pt))/.exec(stripped)?.[1];
+    const lineHeight = /line[\s-]*height[:\s]+([0-9.]+)/i.exec(stripped)?.[1];
+    tokens.push({
+      name,
+      fontFamily,
+      weight,
+      size,
+      lineHeight,
+      usage: stripped !== name ? stripped : undefined,
+    });
+  }
+  return tokens;
+}
+
+function extractComponentTokens(body: string): ComponentToken[] {
+  // Components are typically organised under H3 sub-headings ("### Button",
+  // "### Card"). When present, treat each H3 as one component; otherwise
+  // fall back to bullet rows.
+  const tokens: ComponentToken[] = [];
+  const h3Rx = /^###\s+(.+?)\s*$/;
+  const lines = body.split(/\r?\n/);
+
+  let current: ComponentToken | null = null;
+  for (const line of lines) {
+    const h3 = h3Rx.exec(line);
+    if (h3) {
+      if (current) tokens.push(current);
+      current = { name: h3[1].trim(), variants: {}, notes: "" };
+      continue;
+    }
+    if (!current) continue;
+    // Variant detection — `variant: primary | secondary | ghost`
+    const variantMatch = /^[\s-]*(\w[\w\s-]*?)[\s]*:[\s]*(.+)$/.exec(line.trim());
+    if (variantMatch) {
+      const key = variantMatch[1].trim();
+      const valuesRaw = variantMatch[2].trim();
+      if (/[|,]/.test(valuesRaw) && valuesRaw.length < 200) {
+        const values = valuesRaw
+          .split(/[|,]/)
+          .map((v) => v.trim().replace(/[`*_"']/g, ""))
+          .filter(Boolean);
+        if (values.length >= 2) {
+          current.variants[key] = values;
+          continue;
+        }
+      }
+    }
+    if (line.trim()) {
+      current.notes = (current.notes ?? "") + (current.notes ? "\n" : "") + line;
+    }
+  }
+  if (current) tokens.push(current);
+
+  if (tokens.length === 0) {
+    // Fallback — flat bullet list of components.
+    for (const line of lines) {
+      const m = /^[\s-*+]+([A-Z][\w\s]+?)(?::|—|–|$)/.exec(line);
+      if (m) tokens.push({ name: m[1].trim(), variants: {}, notes: undefined });
+    }
+  }
+  return tokens;
+}
+
+function extractSpacingTokens(body: string): SpacingToken[] {
+  const tokens: SpacingToken[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    const stripped = line.trim().replace(/^[-*+]\s*/, "").replace(/[`*_]/g, "");
+    if (!stripped) continue;
+    const m = /^([\w-]+)[\s:—–-]+(\d+(?:\.\d+)?(?:px|rem|em|%)?)/.exec(stripped);
+    if (m) tokens.push({ name: m[1], value: m[2] });
+  }
+  return tokens;
+}
+
+function extractShadowTokens(body: string): ShadowToken[] {
+  const tokens: ShadowToken[] = [];
+  // Shadows are typically `name: <css value>` rows. CSS values contain
+  // commas / parens / `0 1px 2px rgba(...)` so we don't attempt to fully
+  // parse them — capture the whole right-hand side verbatim.
+  for (const line of body.split(/\r?\n/)) {
+    const stripped = line.trim().replace(/^[-*+]\s*/, "").replace(/[`*_]/g, "");
+    if (!stripped) continue;
+    const m = /^([\w-]+)\s*[:—–]\s*(.+)$/.exec(stripped);
+    if (m && (m[2].includes("px") || m[2].includes("rgba"))) {
+      tokens.push({ name: m[1], value: m[2].trim() });
+    }
+  }
+  return tokens;
+}
+
+function extractDoDontRules(body: string): DoDontRule[] {
+  const rules: DoDontRule[] = [];
+  let mode: "do" | "dont" | null = null;
+  for (const line of body.split(/\r?\n/)) {
+    const stripped = line.trim();
+    if (!stripped) continue;
+    if (/^#{2,}\s+do\b|^\*\*do\*\*|^do['s]*[:\s]/i.test(stripped) && !/don.?t/i.test(stripped)) {
+      mode = "do";
+      continue;
+    }
+    if (/^#{2,}\s+don.?t|^\*\*don.?t\*\*|^don.?t[s]?[:\s]/i.test(stripped)) {
+      mode = "dont";
+      continue;
+    }
+    const bullet = /^[-*+]\s+(.+)$/.exec(stripped);
+    if (bullet && mode) {
+      // Preserve backticks — they mark identifier tokens
+      // (`btn-hard`, `shadow-hard`) that downstream consumers
+      // (Guard `autoFromDesignMd`) extract from the rule text.
+      rules.push({ kind: mode, text: bullet[1].replace(/[*_]/g, "").trim() });
+    } else if (bullet) {
+      // ✅ / ❌ inline markers.
+      const text = bullet[1];
+      if (text.startsWith("✅") || /^do\b/i.test(text)) {
+        rules.push({ kind: "do", text: text.replace(/^[✅do:\s]+/i, "").trim() });
+      } else if (text.startsWith("❌") || /^don.?t\b/i.test(text)) {
+        rules.push({ kind: "dont", text: text.replace(/^[❌don'?t:\s]+/i, "").trim() });
+      }
+    }
+  }
+  return rules;
+}
+
+function extractBreakpoints(body: string): ResponsiveBreakpoint[] {
+  const bps: ResponsiveBreakpoint[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    const stripped = line.trim().replace(/^[-*+]\s*/, "").replace(/[`*_]/g, "");
+    if (!stripped) continue;
+    const m = /^([\w-]+)[\s:—–-]+(\d+(?:px|rem|em)?)\b(.*)$/.exec(stripped);
+    if (m) {
+      bps.push({
+        name: m[1],
+        value: m[2],
+        notes: m[3].replace(/^[\s—–-]+/, "").trim() || undefined,
+      });
+    }
+  }
+  return bps;
+}
+
+function extractAgentPrompts(body: string): AgentPrompt[] {
+  // Group by H3; everything else collapses into a single "default" prompt.
+  const prompts: AgentPrompt[] = [];
+  const lines = body.split(/\r?\n/);
+  const h3Rx = /^###\s+(.+?)\s*$/;
+  let current: AgentPrompt | null = null;
+  let buf: string[] = [];
+  for (const line of lines) {
+    const h3 = h3Rx.exec(line);
+    if (h3) {
+      if (current) {
+        current.body = buf.join("\n").trim();
+        prompts.push(current);
+      }
+      current = { title: h3[1].trim(), body: "" };
+      buf = [];
+      continue;
+    }
+    buf.push(line);
+  }
+  if (current) {
+    current.body = buf.join("\n").trim();
+    prompts.push(current);
+  } else if (buf.join("").trim()) {
+    prompts.push({ title: "default", body: buf.join("\n").trim() });
+  }
+  return prompts;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────
+
+function emptySections(): DesignSpec["sections"] {
+  return {
+    theme: { id: "theme", present: false, rawBody: "" },
+    "color-palette": { id: "color-palette", present: false, rawBody: "", tokens: [] },
+    typography: { id: "typography", present: false, rawBody: "", tokens: [] },
+    components: { id: "components", present: false, rawBody: "", tokens: [] },
+    layout: { id: "layout", present: false, rawBody: "", tokens: [] },
+    shadows: { id: "shadows", present: false, rawBody: "", tokens: [] },
+    "dos-donts": { id: "dos-donts", present: false, rawBody: "", rules: [] },
+    responsive: { id: "responsive", present: false, rawBody: "", breakpoints: [] },
+    "agent-prompts": { id: "agent-prompts", present: false, rawBody: "", prompts: [] },
+  };
+}
+
+/** Parse a DESIGN.md source string into the structured spec. Never throws. */
+export function parseDesignMd(source: string): DesignSpec {
+  const { title, sections: rawSections } = splitByHeadings(source);
+  const result: DesignSpec = {
+    source,
+    title,
+    sections: emptySections(),
+    extraSections: [],
+  };
+
+  for (const raw of rawSections) {
+    const id = resolveSectionId(raw.heading);
+    if (!id) {
+      result.extraSections.push({ heading: raw.heading, body: raw.body });
+      continue;
+    }
+    const body = raw.body.trim();
+    switch (id) {
+      case "theme": {
+        const summary = body.split(/\n\s*\n/)[0]?.trim() || undefined;
+        result.sections.theme = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          summary,
+        };
+        break;
+      }
+      case "color-palette":
+        result.sections["color-palette"] = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          tokens: extractColorTokens(body),
+        };
+        break;
+      case "typography":
+        result.sections.typography = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          tokens: extractTypographyTokens(body),
+        };
+        break;
+      case "components":
+        result.sections.components = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          tokens: extractComponentTokens(body),
+        };
+        break;
+      case "layout":
+        result.sections.layout = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          tokens: extractSpacingTokens(body),
+        };
+        break;
+      case "shadows":
+        result.sections.shadows = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          tokens: extractShadowTokens(body),
+        };
+        break;
+      case "dos-donts":
+        result.sections["dos-donts"] = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          rules: extractDoDontRules(body),
+        };
+        break;
+      case "responsive":
+        result.sections.responsive = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          breakpoints: extractBreakpoints(body),
+        };
+        break;
+      case "agent-prompts":
+        result.sections["agent-prompts"] = {
+          id,
+          present: true,
+          headingText: raw.heading,
+          rawBody: body,
+          prompts: extractAgentPrompts(body),
+        };
+        break;
+    }
+  }
+  return result;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Validation
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Surface gaps in a parsed DESIGN.md. The validator never returns
+ * errors that block builds — Mandu's enforcement layer (Guard) is the
+ * gate. This function is the diagnostic that tells the user "your
+ * DESIGN.md is missing colour tokens" so they can fill it in.
+ */
+export function validateDesignSpec(spec: DesignSpec): ValidationResult {
+  const issues: ValidationIssue[] = [];
+  for (const id of DESIGN_SECTION_IDS) {
+    const section = spec.sections[id] as AnyDesignSection;
+    if (!section.present) {
+      issues.push({
+        kind: "missing",
+        section: id,
+        message: `Section "${id}" not found. Add a "## ${humanizeSectionId(id)}" heading.`,
+      });
+      continue;
+    }
+    const empty = isSectionEmpty(section);
+    if (empty) {
+      issues.push({
+        kind: "empty",
+        section: id,
+        message: `Section "${id}" is present but has no structured tokens.`,
+      });
+    }
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+function isSectionEmpty(section: AnyDesignSection): boolean {
+  switch (section.id) {
+    case "theme":
+      return !section.summary || section.summary.length === 0;
+    case "color-palette":
+    case "typography":
+    case "components":
+    case "layout":
+    case "shadows":
+      return section.tokens.length === 0;
+    case "dos-donts":
+      return section.rules.length === 0;
+    case "responsive":
+      return section.breakpoints.length === 0;
+    case "agent-prompts":
+      return section.prompts.length === 0;
+  }
+}
+
+function humanizeSectionId(id: DesignSectionId): string {
+  switch (id) {
+    case "theme":
+      return "Visual Theme & Philosophy";
+    case "color-palette":
+      return "Color Palette";
+    case "typography":
+      return "Typography";
+    case "components":
+      return "Components";
+    case "layout":
+      return "Layout";
+    case "shadows":
+      return "Depth & Elevation";
+    case "dos-donts":
+      return "Do's & Don'ts";
+    case "responsive":
+      return "Responsive";
+    case "agent-prompts":
+      return "Agent Prompts";
+  }
+}
+
+export { humanizeSectionId };

package/src/design/scaffold.ts

@@ -0,0 +1,147 @@
+/**
+ * Scaffold + upstream import primitives.
+ *
+ * `EMPTY_DESIGN_MD` is the canonical 9-section skeleton Mandu ships
+ * for `mandu design init` (no `--from`). It contains heading slots and
+ * a one-line hint per section so users / agents can fill it in.
+ *
+ * `fetchUpstreamDesignMd(slug)` pulls a brand DESIGN.md from VoltAgent's
+ * awesome-design-md repository (raw GitHub). The function is a thin
+ * fetch wrapper — caller decides what to do with the body (validate +
+ * write, dry-run + diff, etc.).
+ *
+ * @module core/design/scaffold
+ */
+
+/**
+ * Raw GitHub base for awesome-design-md. Public, MIT licensed.
+ * Each brand lives at `<base>/<slug>/DESIGN.md`.
+ */
+export const AWESOME_DESIGN_MD_RAW_BASE =
+  "https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main";
+
+/**
+ * Empty 9-section DESIGN.md skeleton. Meant to be filled in
+ * incrementally — Mandu's point is that DESIGN.md is a *living*
+ * artifact, not a one-shot deliverable.
+ */
+export const EMPTY_DESIGN_MD = `# DESIGN.md
+
+> Living design system spec for this project. AI agents and developers
+> read this file before touching UI. See
+> https://github.com/VoltAgent/awesome-design-md for examples.
+>
+> Fill sections incrementally — \`mandu design extract\` (coming soon)
+> can propose tokens from your existing code.
+
+## Visual Theme & Philosophy
+
+<!-- One-paragraph "vibe": minimal, playful, dense, premium, … -->
+
+## Color Palette
+
+<!-- Each row: name — value — role.
+- primary — #000000 — brand / primary action
+- surface — #ffffff — page background
+-->
+
+## Typography
+
+<!-- Each row: name — font-family / size / weight / line-height — usage.
+- display — Inter, 48px, weight 700, line-height 1.1 — hero
+- body — Inter, 16px, weight 400, line-height 1.6 — paragraphs
+-->
+
+## Components
+
+<!-- One ### sub-heading per component. Declare variants as
+\`variant: a | b | c\` so tools can index them.
+
+### Button
+variant: primary | secondary | ghost
+size: sm | md | lg
+
+### Card
+variant: surface | bordered
+-->
+
+## Layout
+
+<!-- Spacing scale + grid notes.
+- xs — 4px
+- sm — 8px
+- md — 16px
+- lg — 24px
+- xl — 40px
+-->
+
+## Depth & Elevation
+
+<!-- Shadow tokens.
+- card: 0 1px 2px rgba(0,0,0,.06), 0 1px 3px rgba(0,0,0,.10)
+- popover: 0 4px 12px rgba(0,0,0,.12)
+-->
+
+## Do's & Don'ts
+
+<!-- Add rules under ### Do and ### Don't sub-headings.
+Mandu's Guard rule can lift the don't items into \`forbidInlineClasses\`.
+
+### Do
+- Use design tokens.
+
+### Don't
+- Inline raw colour values.
+-->
+
+
+## Responsive
+
+<!-- Breakpoints + scaling notes.
+- mobile — 0–639px
+- tablet — 640–1023px
+- desktop — 1024px+
+-->
+
+## Agent Prompts
+
+<!-- Ready-made prompts the agent should use when generating UI. Each
+### sub-heading is one prompt; the body is passed verbatim.
+
+### Page hero
+Generate a hero section using \`display\` typography and \`primary\`
+color tokens. Avoid inline shadow values; use the \`card\` shadow token.
+-->
+`;
+
+export interface FetchUpstreamOptions {
+  /** Override base URL (test fixtures, mirrors). */
+  baseUrl?: string;
+  /** AbortSignal so callers can cancel a slow fetch. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Fetch a DESIGN.md from awesome-design-md by brand slug.
+ * Throws on HTTP error — the caller (CLI command) catches and prints
+ * a user-facing message rather than letting it bubble.
+ */
+export async function fetchUpstreamDesignMd(
+  slugOrUrl: string,
+  options: FetchUpstreamOptions = {},
+): Promise<string> {
+  const url = isAbsoluteUrl(slugOrUrl)
+    ? slugOrUrl
+    : `${options.baseUrl ?? AWESOME_DESIGN_MD_RAW_BASE}/${encodeURIComponent(slugOrUrl)}/DESIGN.md`;
+  const res = await fetch(url, { signal: options.signal });
+  if (!res.ok) {
+    throw new Error(
+      `fetchUpstreamDesignMd: GET ${url} → HTTP ${res.status} ${res.statusText}`,
+    );
+  }
+  return res.text();
+}
+
+function isAbsoluteUrl(s: string): boolean {
+  return /^https?:\/\//i.test(s);
+}