blume 0.0.0 → 0.1.0

package/src/cli/commands/add.ts

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { defineCommand } from "citty";
+import { dirname, join } from "pathe";
+
+import { findItem, packageSrc, registry } from "../../registry/registry.ts";
+import { rewriteImports } from "../../registry/rewrite-imports.ts";
+import { logger } from "../log.ts";
+
+export const addCommand = defineCommand({
+  args: {
+    force: { description: "Overwrite existing files.", type: "boolean" },
+    name: {
+      description: "Registry item to install.",
+      required: false,
+      type: "positional",
+    },
+  },
+  meta: {
+    description: "Install a source component or template from the registry.",
+    name: "add",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+
+    if (!args.name) {
+      logger.info("Available registry items:");
+      for (const item of registry) {
+        process.stdout.write(`  ${item.name} — ${item.description}\n`);
+      }
+      return;
+    }
+
+    const item = findItem(args.name);
+    if (!item) {
+      logger.error(`Unknown registry item: ${args.name}`);
+      logger.info(`Run \`blume add\` to list available items.`);
+      process.exit(1);
+    }
+
+    const plan = item.files.map((file) => ({
+      file,
+      skip: existsSync(join(root, file.target)) && !args.force,
+      target: join(root, file.target),
+    }));
+
+    await Promise.all(
+      plan
+        .filter((entry) => !entry.skip)
+        .map(async (entry) => {
+          const source = join(packageSrc, entry.file.source);
+          const raw = await readFile(source, "utf-8");
+          // Built-in components carry relative imports into the package; rewrite
+          // them to `blume/*` so the installed copy resolves them.
+          const content = entry.file.rewrite
+            ? rewriteImports(raw, source, packageSrc)
+            : raw;
+          await mkdir(dirname(entry.target), { recursive: true });
+          await writeFile(entry.target, content, "utf-8");
+        })
+    );
+
+    for (const entry of plan) {
+      if (entry.skip) {
+        logger.warn(
+          `Skipped existing ${entry.file.target} (use --force to overwrite)`
+        );
+      } else {
+        logger.success(`Added ${entry.file.target}`);
+      }
+    }
+
+    if (item.postInstall.length > 0) {
+      process.stdout.write(`\nNext steps:\n`);
+      for (const line of item.postInstall) {
+        process.stdout.write(`  ${line}\n`);
+      }
+    }
+  },
+});

package/src/cli/commands/build.ts

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+
+import { build } from "astro";
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { buildLlmsFiles } from "../../ai/llms.ts";
+import { serverFeatures } from "../../core/server-features.ts";
+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 { logger } from "../log.ts";
+import { prepareProject } from "../prepare.ts";
+
+export const buildCommand = defineCommand({
+  args: {
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean",
+    },
+    strict: { description: "Fail on diagnostics.", type: "boolean" },
+  },
+  meta: {
+    description: "Build the docs site for production.",
+    name: "build",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const project = await prepareProject({
+      mode: "build",
+      preview: args.preview,
+      root,
+      strict: args.strict,
+    });
+
+    logger.start(
+      `Building ${project.graph.pages.length} page(s) (${project.config.deployment.output} output)`
+    );
+
+    await build({
+      logLevel: "info",
+      root: project.context.outDir,
+    });
+
+    const distDir = join(root, "dist");
+
+    if (project.config.search.provider === "pagefind") {
+      logger.start("Building search index");
+      const indexed = await buildSearchIndex(distDir);
+      logger.success(`Indexed ${indexed} page(s) for search`);
+    }
+
+    // Upload the index to a hosted provider (Algolia, Orama Cloud, Typesense).
+    // Skipped with a warning when its admin key isn't configured.
+    await syncSearchProvider(project, {
+      start: (message) => logger.start(message),
+      success: (message) => logger.success(message),
+      warn: (message) => logger.warn(message),
+    });
+
+    if (project.config.ai.llmsTxt) {
+      const { index, full } = await buildLlmsFiles(project);
+      await Promise.all([
+        writeFile(join(distDir, "llms.txt"), index, "utf-8"),
+        writeFile(join(distDir, "llms-full.txt"), full, "utf-8"),
+      ]);
+      logger.success("Generated llms.txt and llms-full.txt");
+    }
+
+    // A user's own public/ file (copied into dist by Astro) always wins.
+    const sitemap = buildSitemap(project);
+    if (sitemap && !existsSync(join(distDir, "sitemap.xml"))) {
+      await writeFile(join(distDir, "sitemap.xml"), sitemap, "utf-8");
+      logger.success("Generated sitemap.xml");
+    }
+
+    const robots = buildRobots(project);
+    if (robots && !existsSync(join(distDir, "robots.txt"))) {
+      await writeFile(join(distDir, "robots.txt"), robots, "utf-8");
+      logger.success("Generated robots.txt");
+    }
+
+    const { config } = project;
+    const features = serverFeatures(config);
+    logger.box(
+      [
+        `Output     ${config.deployment.output}`,
+        `Adapter    ${config.deployment.adapter ?? "none"}`,
+        `Site       ${config.deployment.site ?? "not set"}`,
+        `Search     ${config.search.provider}`,
+        `Redirects  ${config.redirects.length}`,
+        `Sitemap    ${sitemap ? "yes" : "no (set deployment.site)"}`,
+        `Robots     ${robots ? "yes" : "no"}`,
+        `LLM files  ${config.ai.llmsTxt ? "yes" : "no"}`,
+        `Server features  ${features.length > 0 ? features.join(", ") : "none"}`,
+      ].join("\n")
+    );
+
+    logger.success(`Built to ${distDir}`);
+  },
+});

package/src/cli/commands/dev.ts

@@ -0,0 +1,108 @@
+import { watch } from "node:fs";
+
+import { dev } from "astro";
+import { defineCommand } from "citty";
+
+import { generateRuntime } from "../../astro/generate.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import { logger } from "../log.ts";
+import { prepareProject } from "../prepare.ts";
+
+export const devCommand = defineCommand({
+  args: {
+    host: { description: "Network host to bind.", type: "string" },
+    open: { description: "Open the browser on start.", type: "boolean" },
+    port: { description: "Port to listen on.", type: "string" },
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean",
+    },
+    strict: { description: "Fail on diagnostics.", type: "boolean" },
+  },
+  meta: {
+    description: "Start the Blume development server.",
+    name: "dev",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const preview = args.preview ?? false;
+    // 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 devServerUrl = `http://localhost:${port}`;
+    const project = await prepareProject({
+      devServerUrl,
+      mode: "dev",
+      preview,
+      root,
+      strict: args.strict,
+    });
+
+    if (project.bridge) {
+      logger.info(
+        'Detected docs.json — running in Mintlify bridge mode (no migration). Run "blume migrate mintlify" to convert permanently.'
+      );
+    }
+
+    const server = await dev({
+      logLevel: "info",
+      root: project.context.outDir,
+      server: {
+        host: args.host ?? false,
+        open: args.open ?? false,
+        port: args.port ? Number(args.port) : undefined,
+      },
+    });
+
+    // Watch user inputs and regenerate the runtime data on change. Astro/Vite
+    // hot-reloads the generated data module so nav and routes stay in sync.
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const regenerate = () => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(async () => {
+        try {
+          const next = await scanProject(root, {
+            devServerUrl,
+            mode: "dev",
+            preview,
+          });
+          await generateRuntime(next);
+        } catch (error) {
+          logger.error(`Regeneration failed: ${(error as Error).message}`);
+        }
+      }, 80);
+    };
+
+    // Content is watched per source (filesystem uses fs.watch; remote sources
+    // are frozen for the session). The remaining project inputs — user pages,
+    // config, theme, and component overrides — are watched directly.
+    const fileTargets = [
+      project.context.pagesRoot,
+      project.context.configFile,
+      project.context.themeFile,
+      project.context.componentsFile,
+    ].filter((target) => target !== null);
+
+    const disposers = [
+      ...project.sources.map((source) => source.watch?.(regenerate)),
+      ...fileTargets.map((target) => {
+        const watcher = watch(target, { recursive: true }, regenerate);
+        return () => watcher.close();
+      }),
+    ].filter((dispose) => dispose !== undefined);
+
+    const shutdown = async () => {
+      for (const dispose of disposers) {
+        dispose();
+      }
+      await server.stop();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  },
+});

package/src/cli/commands/doctor.ts

@@ -0,0 +1,74 @@
+import { defineCommand } from "citty";
+
+import { BlumeError } from "../../core/diagnostics.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import { serverFeatures } from "../../core/server-features.ts";
+import type { Diagnostic } from "../../core/types.ts";
+import { logger, reportDiagnostics } from "../log.ts";
+
+const MIN_NODE_MAJOR = 20;
+
+export const doctorCommand = defineCommand({
+  meta: {
+    description: "Diagnose common configuration and content problems.",
+    name: "doctor",
+  },
+  async run() {
+    const root = process.cwd();
+    const diagnostics: Diagnostic[] = [];
+
+    const nodeMajor = Number.parseInt(
+      process.versions.node.split(".")[0] ?? "0",
+      10
+    );
+    if (nodeMajor < MIN_NODE_MAJOR) {
+      diagnostics.push({
+        code: "BLUME_NODE_VERSION",
+        message: `Node ${process.versions.node} is below the supported minimum (${MIN_NODE_MAJOR}).`,
+        severity: "warning",
+      });
+    }
+
+    try {
+      const project = await scanProject(root, { mode: "build" });
+      diagnostics.push(...project.diagnostics);
+
+      const { config } = project;
+      const features = serverFeatures(config);
+      if (features.length > 0 && config.deployment.output === "static") {
+        diagnostics.push({
+          code: "BLUME_SERVER_FEATURE_REQUIRED",
+          message: `${features.join(", ")} require server output.`,
+          severity: "error",
+          suggestion: 'Set deployment.output to "server".',
+        });
+      }
+      if (config.deployment.output === "server" && !config.deployment.adapter) {
+        diagnostics.push({
+          code: "BLUME_ADAPTER_REQUIRED",
+          message: "Server output requires an adapter.",
+          severity: "error",
+          suggestion: 'Set deployment.adapter (e.g. "vercel").',
+        });
+      }
+
+      logger.info(`Pages: ${project.graph.pages.length}`);
+      logger.info(`Output: ${config.deployment.output}`);
+      logger.info(`Search: ${config.search.provider}`);
+    } 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 problems found.");
+    }
+    if (hadErrors) {
+      process.exit(1);
+    }
+  },
+});

package/src/cli/commands/eject.ts

@@ -0,0 +1,57 @@
+import { readFile, writeFile } from "node:fs/promises";
+
+import { defineCommand } from "citty";
+import { join, relative } from "pathe";
+
+import { eject } from "../../registry/eject.ts";
+import { logger } from "../log.ts";
+
+const updatePackageScripts = async (root: string): Promise<void> => {
+  const pkgPath = join(root, "package.json");
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const scripts = (pkg.scripts ?? {}) as Record<string, string>;
+  pkg.scripts = {
+    ...scripts,
+    build: "astro build",
+    dev: "astro dev",
+    preview: "astro preview",
+  };
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+};
+
+export const ejectCommand = defineCommand({
+  args: {
+    yes: { description: "Skip the confirmation prompt.", type: "boolean" },
+  },
+  meta: {
+    description: "Promote the generated runtime into an owned Astro project.",
+    name: "eject",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+
+    if (!args.yes) {
+      logger.warn(
+        "Eject is one-way: it writes astro.config.mjs and src/ into your project and removes .blume."
+      );
+      logger.info("Re-run with --yes to proceed.");
+      return;
+    }
+
+    const files = await eject(root);
+    await updatePackageScripts(root);
+
+    logger.success(`Ejected ${files.length} file(s):`);
+    for (const file of files) {
+      process.stdout.write(`  ${relative(root, file)}\n`);
+    }
+    logger.box(
+      "Your project is now a standalone Astro app.\n\n  bun run dev\n  bun run build\n\nThe blume package remains importable."
+    );
+  },
+});

package/src/cli/commands/init.ts

@@ -0,0 +1,98 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { defineCommand } from "citty";
+import { basename, dirname, join } from "pathe";
+
+import { getBlumeVersion } from "../../core/version.ts";
+import { logger } from "../log.ts";
+
+/**
+ * Derive a valid npm package name from a directory name, falling back to
+ * `docs` when nothing usable remains.
+ */
+const toPackageName = (raw: string): string =>
+  raw
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/gu, "-")
+    .replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
+
+const packageTemplate = (name: string, version: string): string => `{
+  "name": ${JSON.stringify(name)},
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "blume dev",
+    "build": "blume build",
+    "doctor": "blume doctor"
+  },
+  "dependencies": {
+    "blume": "^${version}"
+  }
+}
+`;
+
+const CONFIG_TEMPLATE = `import { defineConfig } from "blume";
+
+export default defineConfig({
+  title: "My Docs",
+  description: "Documentation powered by Blume.",
+});
+`;
+
+const INDEX_TEMPLATE = `---
+title: Introduction
+description: Welcome to your new Blume docs.
+---
+
+# Introduction
+
+Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
+
+Edit \`docs/index.mdx\` to get started, then run \`blume dev\`.
+`;
+
+const writeFileSafe = async (
+  path: string,
+  content: string
+): Promise<boolean> => {
+  if (existsSync(path)) {
+    logger.info(`Skipped existing ${path}`);
+    return false;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, "utf-8");
+  logger.success(`Created ${path}`);
+  return true;
+};
+
+export const initCommand = defineCommand({
+  args: {
+    "content-dir": {
+      default: "docs",
+      description: "Content directory.",
+      type: "string",
+    },
+    yes: { description: "Skip prompts.", type: "boolean" },
+  },
+  meta: {
+    description: "Scaffold a minimal Blume project.",
+    name: "init",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const contentDir = args["content-dir"] ?? "docs";
+
+    const createdPackage = await writeFileSafe(
+      join(root, "package.json"),
+      packageTemplate(toPackageName(basename(root)), getBlumeVersion())
+    );
+    await writeFileSafe(join(root, "blume.config.ts"), CONFIG_TEMPLATE);
+    await writeFileSafe(join(root, contentDir, "index.mdx"), INDEX_TEMPLATE);
+
+    const nextSteps = createdPackage
+      ? "Next steps:\n\n  npm install\n  blume dev\n"
+      : "Next steps:\n\n  blume dev\n";
+    logger.box(nextSteps);
+  },
+});

package/src/cli/commands/migrate.ts

@@ -0,0 +1,39 @@
+import { defineCommand } from "citty";
+
+import { migrators } from "../../migrate/migrate.ts";
+import { logger } from "../log.ts";
+
+const makeMigrateCommand = (source: keyof typeof migrators) =>
+  defineCommand({
+    meta: {
+      description: `Migrate a ${source} project to Blume.`,
+      name: source,
+    },
+    async run() {
+      const root = process.cwd();
+      logger.start(`Migrating ${source} project`);
+      const result = await migrators[source]?.(root);
+      if (!result) {
+        logger.error(`No migrator for ${source}.`);
+        process.exit(1);
+      }
+      logger.success(`Migrated ${result.moved} content file(s).`);
+      for (const warning of result.warnings) {
+        logger.warn(warning);
+      }
+      logger.box("Review blume.config.ts and run `blume dev`.");
+    },
+  });
+
+export const migrateCommand = defineCommand({
+  meta: {
+    description: "Migrate from another docs tool to Blume.",
+    name: "migrate",
+  },
+  subCommands: {
+    fumadocs: makeMigrateCommand("fumadocs"),
+    mintlify: makeMigrateCommand("mintlify"),
+    nextra: makeMigrateCommand("nextra"),
+    starlight: makeMigrateCommand("starlight"),
+  },
+});

package/src/cli/commands/preview.ts

@@ -0,0 +1,39 @@
+import { existsSync } from "node:fs";
+
+import { preview } from "astro";
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { loadConfig } from "../../core/config.ts";
+import { resolveProjectContext } from "../../core/project.ts";
+import { logger } from "../log.ts";
+
+export const previewCommand = defineCommand({
+  args: {
+    host: { description: "Network host to bind.", type: "string" },
+    port: { description: "Port to listen on.", type: "string" },
+  },
+  meta: {
+    description: "Preview the last production build.",
+    name: "preview",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const { config } = await loadConfig(root);
+    const context = resolveProjectContext(root, config);
+
+    if (!existsSync(join(context.outDir, "astro.config.mjs"))) {
+      logger.error("No build found. Run `blume build` first.");
+      process.exit(1);
+    }
+
+    await preview({
+      logLevel: "info",
+      root: context.outDir,
+      server: {
+        host: args.host ?? false,
+        port: args.port ? Number(args.port) : undefined,
+      },
+    });
+  },
+});

package/src/cli/commands/sync.ts

@@ -0,0 +1,52 @@
+import { rm } from "node:fs/promises";
+
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { loadConfig } from "../../core/config.ts";
+import { resolveProjectContext } from "../../core/project.ts";
+import { logger } from "../log.ts";
+import { prepareProject } from "../prepare.ts";
+
+export const syncCommand = defineCommand({
+  args: {
+    force: {
+      description: "Clear the source cache before refetching.",
+      type: "boolean",
+    },
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean",
+    },
+    strict: { description: "Fail on diagnostics.", type: "boolean" },
+  },
+  meta: {
+    description: "Re-fetch remote content sources and regenerate the runtime.",
+    name: "sync",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+
+    // `--force` drops the snapshots so a stale or corrupt cache can't be served;
+    // scoped to `.blume/cache`, so a running dev server's runtime is untouched.
+    if (args.force) {
+      const { config } = await loadConfig(root);
+      const context = resolveProjectContext(root, config);
+      await rm(join(context.outDir, "cache"), { force: true, recursive: true });
+      logger.info("Cleared source cache.");
+    }
+
+    // Dev mode keeps drafts and skips the static-build gate; `refresh` forces
+    // remote sources to re-fetch rather than serve their cached snapshot. A
+    // running dev server hot-reloads from the regenerated runtime.
+    await prepareProject({
+      mode: "dev",
+      preview: args.preview,
+      refresh: true,
+      root,
+      strict: args.strict,
+    });
+
+    logger.success("Synced content sources.");
+  },
+});