blume 0.0.0 → 0.1.0

package/src/cli/commands/validate.ts

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+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 { logger, reportDiagnostics } from "../log.ts";
+
+export const validateCommand = defineCommand({
+  args: {
+    external: {
+      description: "Check external (HTTP) links over the network.",
+      type: "boolean",
+    },
+    strict: {
+      description: "Treat warnings as errors.",
+      type: "boolean",
+    },
+  },
+  meta: {
+    description: "Validate internal, anchor, asset, and external links.",
+    name: "validate",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const diagnostics: Diagnostic[] = [];
+
+    try {
+      const project = await scanProject(root, { mode: "build" });
+      // Surface content/graph problems too: a page that fails to parse is a
+      // link-validation blind spot, so silently passing would be misleading.
+      diagnostics.push(...project.diagnostics);
+
+      const publicDir = join(root, "public");
+      diagnostics.push(
+        ...(await validateLinks(project.graph, {
+          checkExternal: Boolean(args.external),
+          publicDir: existsSync(publicDir) ? publicDir : null,
+        }))
+      );
+    } catch (error) {
+      if (error instanceof BlumeError) {
+        diagnostics.push(error.diagnostic);
+      } else {
+        throw error;
+      }
+    }
+
+    const hadErrors = reportDiagnostics(diagnostics, root);
+    if (diagnostics.length === 0) {
+      logger.success("No broken links found.");
+    }
+    if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+      process.exit(1);
+    }
+  },
+});

package/src/cli/index.ts

@@ -0,0 +1,35 @@
+import { defineCommand, runMain } from "citty";
+
+import { getBlumeVersion } from "../core/version.ts";
+import { addCommand } from "./commands/add.ts";
+import { buildCommand } from "./commands/build.ts";
+import { devCommand } from "./commands/dev.ts";
+import { doctorCommand } from "./commands/doctor.ts";
+import { ejectCommand } from "./commands/eject.ts";
+import { initCommand } from "./commands/init.ts";
+import { migrateCommand } from "./commands/migrate.ts";
+import { previewCommand } from "./commands/preview.ts";
+import { syncCommand } from "./commands/sync.ts";
+import { validateCommand } from "./commands/validate.ts";
+
+const main = defineCommand({
+  meta: {
+    description: "Markdown-first documentation powered by Astro and Vite.",
+    name: "blume",
+    version: getBlumeVersion(),
+  },
+  subCommands: {
+    add: addCommand,
+    build: buildCommand,
+    dev: devCommand,
+    doctor: doctorCommand,
+    eject: ejectCommand,
+    init: initCommand,
+    migrate: migrateCommand,
+    preview: previewCommand,
+    sync: syncCommand,
+    validate: validateCommand,
+  },
+});
+
+runMain(main);

package/src/cli/log.ts

@@ -0,0 +1,37 @@
+import { consola } from "consola";
+
+import {
+  countBySeverity,
+  formatDiagnostic,
+  hasErrors,
+} from "../core/diagnostics.ts";
+import type { Diagnostic } from "../core/types.ts";
+
+export const logger = consola.withTag("blume");
+
+/** Print a batch of diagnostics and return whether any were errors. */
+export const reportDiagnostics = (
+  diagnostics: Diagnostic[],
+  root?: string
+): boolean => {
+  if (diagnostics.length === 0) {
+    return false;
+  }
+
+  for (const diagnostic of diagnostics) {
+    process.stderr.write(`${formatDiagnostic(diagnostic, root)}\n`);
+  }
+
+  const counts = countBySeverity(diagnostics);
+  const summary = [
+    counts.error ? `${counts.error} error(s)` : null,
+    counts.warning ? `${counts.warning} warning(s)` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+  if (summary) {
+    process.stderr.write(`\n${summary}\n`);
+  }
+
+  return hasErrors(diagnostics);
+};

package/src/cli/prepare.ts

@@ -0,0 +1,80 @@
+import { generateRuntime } from "../astro/generate.ts";
+import { BlumeError, hasErrors } from "../core/diagnostics.ts";
+import { scanProject } from "../core/project-graph.ts";
+import type { BlumeProject, BuildMode } from "../core/project-graph.ts";
+import { serverFeatures } from "../core/server-features.ts";
+import { logger, reportDiagnostics } from "./log.ts";
+
+export interface PrepareOptions {
+  root: string;
+  mode?: BuildMode;
+  strict?: boolean;
+  /** Local dev server URL, used as the `deployment.site` fallback (dev only). */
+  devServerUrl?: string;
+  /** Render drafts and fetch unpublished CMS content. */
+  preview?: boolean;
+  /** Force remote sources to re-fetch instead of serving the cached snapshot. */
+  refresh?: boolean;
+}
+
+/**
+ * Scan the project, surface diagnostics, and (re)generate the `.blume` runtime.
+ * In strict mode, any error aborts. Returns the resolved project.
+ */
+export const prepareProject = async (
+  options: PrepareOptions
+): Promise<BlumeProject> => {
+  let project: BlumeProject;
+  try {
+    project = await scanProject(options.root, {
+      devServerUrl: options.devServerUrl,
+      mode: options.mode,
+      preview: options.preview,
+      refresh: options.refresh,
+    });
+  } catch (error) {
+    if (error instanceof BlumeError) {
+      reportDiagnostics([error.diagnostic], options.root);
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  // Hard gate: server-only features cannot ship in a static build.
+  if (
+    options.mode === "build" &&
+    project.config.deployment.output === "static"
+  ) {
+    const features = serverFeatures(project.config);
+    if (features.length > 0) {
+      reportDiagnostics(
+        [
+          {
+            code: "BLUME_SERVER_FEATURE_REQUIRED",
+            message: `${features.join(", ")} require server output, but deployment.output is "static".`,
+            severity: "error",
+            suggestion:
+              'Set deployment: { output: "server", adapter: "vercel" } in blume.config.ts.',
+          },
+        ],
+        options.root
+      );
+      process.exit(1);
+    }
+  }
+
+  const hadErrors = reportDiagnostics(project.diagnostics, options.root);
+  if (hadErrors && options.strict) {
+    logger.error("Aborting due to errors (strict mode).");
+    process.exit(1);
+  }
+  if (hasErrors(project.diagnostics) && !options.strict) {
+    logger.warn("Continuing despite errors. Use --strict to fail the build.");
+  }
+
+  const { warnings } = await generateRuntime(project);
+  for (const warning of warnings) {
+    logger.warn(warning);
+  }
+  return project;
+};

package/src/components/Icon.astro

@@ -0,0 +1,99 @@
+---
+import { resolveIcon } from "../theme/icons.ts";
+
+interface Props {
+  name?: unknown;
+  icon?: unknown;
+  iconType?: string;
+  size?: number;
+  class?: string;
+  className?: string;
+  color?: string;
+  label?: string;
+}
+
+const {
+  color,
+  icon,
+  iconType,
+  name,
+  size = 16,
+  class: astroClass,
+  className,
+  label,
+} = Astro.props;
+const rawIcon = name ?? icon;
+const customIcon =
+  rawIcon !== undefined && rawIcon !== null && typeof rawIcon !== "string"
+    ? rawIcon
+    : null;
+const iconName = typeof rawIcon === "string" ? rawIcon : null;
+const rawSvg =
+  iconName && /^\s*<svg[\s\S]*<\/svg>\s*$/u.test(iconName)
+    ? iconName.trim()
+    : null;
+const isImageIcon = (value: string): boolean =>
+  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)/u.test(value) ||
+  /\.(?:avif|gif|jpe?g|png|svg|webp)$/iu.test(value);
+const imageSrc = iconName && !rawSvg && isImageIcon(iconName) ? iconName : null;
+const resolvedIcon =
+  iconName && !(imageSrc || rawSvg) ? resolveIcon(iconName, iconType) : null;
+const markup = resolvedIcon?.markup;
+const resolvedClass = astroClass ?? className;
+const customStyle = `display:inline-flex;width:${size}px;height:${size}px;${
+  color ? `color:${color}` : ""
+}`;
+const style = color ? `color:${color}` : undefined;
+---
+
+{
+  customIcon ? (
+    <span
+      aria-hidden={label ? undefined : "true"}
+      aria-label={label}
+      class={resolvedClass}
+      role={label ? "img" : undefined}
+      style={customStyle}
+    >
+      {customIcon}
+    </span>
+  ) : rawSvg ? (
+    <span
+      aria-hidden={label ? undefined : "true"}
+      aria-label={label}
+      class={resolvedClass}
+      role={label ? "img" : undefined}
+      set:html={rawSvg}
+      style={customStyle}
+    />
+  ) : imageSrc ? (
+    <img
+      alt={label ?? ""}
+      aria-hidden={label ? undefined : "true"}
+      class={resolvedClass}
+      height={size}
+      src={imageSrc}
+      width={size}
+    />
+  ) : (
+    markup && (
+    <svg
+      aria-hidden={label ? undefined : "true"}
+      aria-label={label}
+      class={resolvedClass}
+      fill="none"
+      height={size}
+      role={label ? "img" : undefined}
+      set:html={markup}
+      stroke="currentColor"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="2"
+      style={style}
+      viewBox="0 0 24 24"
+      width={size}
+      xmlns="http://www.w3.org/2000/svg"
+    />
+    )
+  )
+}

package/src/components/content/Accordion.astro

@@ -0,0 +1,8 @@
+---
+---
+
+<div
+  class="not-prose my-6 overflow-hidden rounded-blume border border-border [&>details:not(:first-of-type)]:border-border [&>details:not(:first-of-type)]:border-t"
+>
+  <slot />
+</div>

package/src/components/content/AccordionItem.astro

@@ -0,0 +1,121 @@
+---
+import Icon from "../Icon.astro";
+
+interface Props {
+  title: string;
+  description?: string;
+  defaultOpen?: boolean;
+  id?: string;
+  icon?: string;
+  iconType?: string;
+}
+
+const { defaultOpen = false, description, icon, iconType, id, title } =
+  Astro.props;
+const slugify = (value: string): string =>
+  value
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^\w\s-]/gu, "")
+    .replaceAll(/[\s_]+/gu, "-")
+    .replaceAll(/-+/gu, "-")
+    .replaceAll(/^-|-$/gu, "");
+const accordionId = id ?? slugify(title);
+---
+
+<details
+  class="not-prose group"
+  data-blume-accordion
+  id={accordionId}
+  open={defaultOpen}
+>
+  <summary
+    class="flex cursor-pointer list-none items-center justify-between p-4 font-medium [&::-webkit-details-marker]:hidden"
+  >
+    <span class="flex min-w-0 items-start gap-2">
+      {
+        icon && (
+          <Icon
+            class="mt-0.5 shrink-0 text-muted-foreground"
+            iconType={iconType}
+            name={icon}
+            size={16}
+          />
+        )
+      }
+      <span class="min-w-0">
+        <span class="block">{title}</span>
+        {
+          description && (
+            <span class="block font-normal text-muted-foreground text-sm">
+              {description}
+            </span>
+          )
+        }
+      </span>
+    </span>
+    <Icon
+      class="text-muted-foreground transition-transform group-open:rotate-180"
+      name="chevron-down"
+      size={16}
+    />
+  </summary>
+  <div class="px-4 pb-4 [&>:first-child]:mt-0! [&>:last-child]:mb-0!">
+    <slot />
+  </div>
+</details>
+
+<script>
+  const state = window as Window & { __blumeAccordionHash?: boolean };
+  if (!state.__blumeAccordionHash) {
+    state.__blumeAccordionHash = true;
+
+    const accordionFromHash = () => {
+      const id = decodeURIComponent(window.location.hash.slice(1));
+      if (!id) {
+        return null;
+      }
+      return document.getElementById(id)?.matches("[data-blume-accordion]")
+        ? (document.getElementById(id) as HTMLDetailsElement)
+        : null;
+    };
+
+    const openHashAccordion = () => {
+      const accordion = accordionFromHash();
+      if (!accordion) {
+        return;
+      }
+      accordion.open = true;
+      requestAnimationFrame(() => {
+        accordion.scrollIntoView({ block: "start" });
+      });
+    };
+
+    document.addEventListener(
+      "toggle",
+      (event) => {
+        const accordion = event.target;
+        if (
+          !(accordion instanceof HTMLDetailsElement) ||
+          !accordion.matches("[data-blume-accordion]") ||
+          !accordion.open ||
+          !accordion.id
+        ) {
+          return;
+        }
+
+        history.replaceState(null, "", `#${encodeURIComponent(accordion.id)}`);
+      },
+      true
+    );
+
+    window.addEventListener("hashchange", openHashAccordion);
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", openHashAccordion, {
+        once: true,
+      });
+    } else {
+      openHashAccordion();
+    }
+  }
+</script>

package/src/components/content/AutoTypeTable.astro

@@ -0,0 +1,51 @@
+---
+// Generate a <TypeTable> from a TypeScript interface or type alias. Point it at
+// a file (`path`, relative to the project root) and a type `name`, or pass inline
+// source via `type`. Extraction runs at build time through the TypeScript
+// compiler API; failures degrade to an inline notice rather than breaking the
+// build.
+import { extractTypeTable } from "./auto-type-table.ts";
+import TypeTable from "./TypeTable.astro";
+
+interface Props {
+  name: string;
+  path?: string;
+  type?: string;
+}
+
+const { name, path, type: source } = Astro.props;
+
+let typeMap: Record<
+  string,
+  { default?: string; description?: string; required: boolean; type: string }
+> = {};
+let error: string | undefined;
+
+try {
+  const rows = await extractTypeTable({ name, path, source });
+  typeMap = Object.fromEntries(
+    rows.map((row) => [
+      row.name,
+      {
+        default: row.default,
+        description: row.description,
+        required: row.required,
+        type: row.type,
+      },
+    ])
+  );
+} catch (cause) {
+  error = cause instanceof Error ? cause.message : String(cause);
+}
+---
+
+{
+  error ? (
+    <div class="not-prose my-6 rounded-blume border border-border px-3 py-2 text-muted-foreground text-sm">
+      Could not generate a type table for <code class="font-mono">{name}</code>:{" "}
+      {error}
+    </div>
+  ) : (
+    <TypeTable type={typeMap} />
+  )
+}

package/src/components/content/Badge.astro

@@ -0,0 +1,124 @@
+---
+import Icon from "../Icon.astro";
+
+type BadgeVariant = "default" | "accent" | "success" | "warning" | "danger";
+type BadgeSize = "xs" | "sm" | "md" | "lg";
+type BadgeShape = "rounded" | "pill";
+
+interface Props {
+  variant?: BadgeVariant;
+  color?: string;
+  disabled?: boolean | string;
+  icon?: unknown;
+  iconType?: string;
+  shape?: BadgeShape;
+  size?: BadgeSize;
+  stroke?: boolean | string;
+  tooltip?: string;
+  class?: string;
+  className?: string;
+}
+
+const {
+  color,
+  disabled = false,
+  icon,
+  iconType,
+  shape = "rounded",
+  size = "md",
+  stroke = false,
+  tooltip,
+  variant = "default",
+  class: astroClass,
+  className,
+} = Astro.props;
+
+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 customColor = colorName.startsWith("#") ? colorName : null;
+
+const filledColorClass: Record<string, string> = {
+  blue: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  gray: "bg-muted text-muted-foreground",
+  green: "bg-green-500/15 text-green-700 dark:text-green-300",
+  orange: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
+  purple: "bg-purple-500/15 text-purple-700 dark:text-purple-300",
+  red: "bg-red-500/15 text-red-700 dark:text-red-300",
+  surface: "bg-background text-muted-foreground ring-1 ring-border",
+  "surface-destructive":
+    "bg-background text-red-700 ring-1 ring-red-500/30 dark:text-red-300",
+  white: "bg-white text-muted-foreground ring-1 ring-border dark:bg-white/10",
+  "white-destructive":
+    "bg-white text-red-700 ring-1 ring-red-500/30 dark:bg-white/10 dark:text-red-300",
+  yellow: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
+};
+
+const strokeColorClass: Record<string, string> = {
+  blue: "border-blue-500/40 text-blue-700 dark:text-blue-300",
+  gray: "border-border text-muted-foreground",
+  green: "border-green-500/40 text-green-700 dark:text-green-300",
+  orange: "border-orange-500/40 text-orange-700 dark:text-orange-300",
+  purple: "border-purple-500/40 text-purple-700 dark:text-purple-300",
+  red: "border-red-500/40 text-red-700 dark:text-red-300",
+  surface: "border-border text-muted-foreground",
+  "surface-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
+  white: "border-border text-muted-foreground",
+  "white-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
+  yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
+};
+
+const sizeClass: Record<BadgeSize, string> = {
+  lg: "gap-1.5 px-2.5 py-1 text-sm",
+  md: "gap-1 px-2 py-0.5 text-xs",
+  sm: "gap-1 px-1.5 py-0.5 text-[0.6875rem]",
+  xs: "gap-0.5 px-1.5 py-px text-[0.625rem]",
+};
+
+const iconSize: Record<BadgeSize, number> = {
+  lg: 14,
+  md: 12,
+  sm: 11,
+  xs: 10,
+};
+
+const shapeClass: Record<BadgeShape, string> = {
+  pill: "rounded-full",
+  rounded: "rounded-md",
+};
+
+const resolvedClass = astroClass ?? className;
+const colorClass = activeStroke
+  ? strokeColorClass[colorName] ?? strokeColorClass.gray
+  : filledColorClass[colorName] ?? filledColorClass.gray;
+const customStyle = customColor
+  ? activeStroke
+    ? `border-color:${customColor};color:${customColor}`
+    : `background:${customColor}20;color:${customColor}`
+  : undefined;
+---
+
+<span
+  class:list={[
+    "not-prose inline-flex w-fit items-center border font-medium leading-5",
+    activeStroke ? "bg-transparent" : "border-transparent",
+    colorClass,
+    sizeClass[size],
+    shapeClass[shape],
+    isDisabled ? "opacity-50" : "",
+    resolvedClass,
+  ]}
+  style={customStyle}
+  title={tooltip}
+>
+  {icon && <Icon icon={icon} iconType={iconType} size={iconSize[size]} />}
+  <slot />
+</span>

package/src/components/content/Callout.astro

@@ -0,0 +1,73 @@
+---
+import Icon from "../Icon.astro";
+
+type CalloutType =
+  | "info"
+  | "note"
+  | "tip"
+  | "success"
+  | "check"
+  | "warning"
+  | "danger";
+
+interface Props {
+  type?: CalloutType;
+  title?: string;
+  icon?: unknown;
+  iconType?: string;
+  color?: string;
+}
+
+const { color, icon, iconType, type = "info", title } = Astro.props;
+
+const iconByType: Record<CalloutType, string> = {
+  check: "circle-check",
+  danger: "circle-x",
+  info: "info",
+  note: "info",
+  success: "circle-check",
+  tip: "lightbulb",
+  warning: "triangle-alert",
+};
+
+const variantClass: Record<CalloutType, string> = {
+  check: "border-green-500/25 bg-green-500/10",
+  danger: "border-red-500/25 bg-red-500/10",
+  info: "border-blue-500/25 bg-blue-500/10",
+  note: "border-border bg-muted",
+  success: "border-green-500/25 bg-green-500/10",
+  tip: "border-accent/25 bg-accent/10",
+  warning: "border-amber-500/25 bg-amber-500/10",
+};
+
+const iconClass: Record<CalloutType, string> = {
+  check: "text-green-600 dark:text-green-400",
+  danger: "text-red-600 dark:text-red-400",
+  info: "text-blue-600 dark:text-blue-400",
+  note: "text-muted-foreground/70",
+  success: "text-green-600 dark:text-green-400",
+  tip: "text-accent",
+  warning: "text-amber-600 dark:text-amber-400",
+};
+---
+
+<aside
+  class:list={[
+    "not-prose my-5 flex flex-row items-start gap-2 rounded-blume border px-4 py-3 font-sans text-muted-foreground text-sm leading-6 [&_a]:underline [&_a]:decoration-current/50 [&_code]:font-mono",
+    color ? "bg-background" : variantClass[type],
+  ]}
+  style={color ? `border:1px solid ${color};color:${color}` : undefined}
+>
+  <span class:list={["mt-0.5 shrink-0", color ? "" : iconClass[type]]}>
+    <Icon
+      color={color}
+      icon={icon ?? iconByType[type]}
+      iconType={iconType}
+      size={16}
+    />
+  </span>
+  <div class="min-w-0 flex-1 [&>:first-child]:mt-0! [&>:last-child]:mb-0!">
+    {title && <p class="mb-1 font-semibold text-foreground">{title}</p>}
+    <slot />
+  </div>
+</aside>