blume 0.2.0 → 0.4.0

package/src/cli/commands/check.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+
+import { check } from "@astrojs/check";
+import { sync } from "astro";
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { logger } from "../log.ts";
+import { prepareProject } from "../prepare.ts";
+
+export const checkCommand = defineCommand({
+  args: {
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean",
+    },
+    strict: {
+      description: "Fail on content diagnostics as well as type errors.",
+      type: "boolean",
+    },
+  },
+  meta: {
+    description: "Type-check the docs site with astro check.",
+    name: "check",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const project = await prepareProject({
+      mode: "build",
+      preview: args.preview,
+      root,
+      strict: args.strict,
+    });
+
+    const { outDir } = project.context;
+
+    // Generate Astro's content/collection and font types into `.blume/.astro`
+    // so `astro:*` virtual modules resolve during the check.
+    await sync({ logLevel: "warn", root: outDir });
+
+    // The project-root tsconfig is what covers the authored `pages/` and config;
+    // without it astro check only sees the generated `.blume` project. Falls back
+    // to the generated project's own tsconfig when the project has none.
+    const tsconfig = join(root, "tsconfig.json");
+
+    logger.start(`Type-checking ${project.graph.pages.length} page(s)`);
+    const failed = await check({
+      minimumFailingSeverity: "error",
+      minimumSeverity: "hint",
+      root: outDir,
+      tsconfig: existsSync(tsconfig) ? tsconfig : undefined,
+      watch: false,
+    });
+
+    if (failed) {
+      logger.error("Type check failed.");
+      process.exit(1);
+    }
+
+    logger.success("No type errors.");
+  },
+});

package/src/cli/commands/dev.ts

@@ -4,12 +4,23 @@ import { dev } from "astro";
 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";
 
 export const devCommand = defineCommand({
   args: {
+    "content-dir": {
+      description: "Content folder to scan, overriding config (content.root).",
+      type: "string",
+    },
+    debug: {
+      description: "Verbose Astro/Vite logging for troubleshooting.",
+      type: "boolean",
+    },
     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" },
@@ -26,14 +37,19 @@ export const devCommand = defineCommand({
   async run({ args }) {
     const root = process.cwd();
     const preview = args.preview ?? false;
+    const overrides = args["content-dir"]
+      ? { contentRoot: args["content-dir"] }
+      : undefined;
     // 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,
       mode: "dev",
+      overrides,
       preview,
       root,
       strict: args.strict,
@@ -45,16 +61,25 @@ 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: "info",
+      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,
       },
     });
 
+    // Mirror any initial diagnostics into the browser overlay now the server
+    // (and its HMR channel) is up.
+    showBlumeErrorOverlay(project.diagnostics);
+
     // 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;
@@ -67,9 +92,12 @@ export const devCommand = defineCommand({
           const next = await scanProject(root, {
             devServerUrl,
             mode: "dev",
+            overrides,
             preview,
           });
           await generateRuntime(next);
+          // Surface any content/config errors in the browser overlay too.
+          showBlumeErrorOverlay(next.diagnostics);
         } catch (error) {
           logger.error(`Regeneration failed: ${(error as Error).message}`);
         }
@@ -98,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

@@ -4,16 +4,28 @@ 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";
+import { reportInternalError } from "../internal-error.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 const MIN_NODE_MAJOR = 20;
 
 export const doctorCommand = defineCommand({
+  args: {
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
+  },
   meta: {
     description: "Diagnose common configuration and content problems.",
     name: "doctor",
   },
-  async run() {
+  async run({ args }) {
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];
 
@@ -52,15 +64,29 @@ export const doctorCommand = defineCommand({
         });
       }
 
-      logger.info(`Pages: ${project.graph.pages.length}`);
-      logger.info(`Output: ${config.deployment.output}`);
-      logger.info(`Search: ${config.search.provider}`);
+      if (!args.json) {
+        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;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+
+    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;
     }
 
     const hadErrors = reportDiagnostics(diagnostics, root);

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,9 +2,11 @@ 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";
 
 /**
@@ -32,25 +34,119 @@ const packageTemplate = (name: string, version: string): string => `{
 }
 `;
 
-const CONFIG_TEMPLATE = `import { defineConfig } from "blume";
+const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
+type Template = (typeof TEMPLATES)[number];
+
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+
+/** A starter: the config plus seed content files (path is relative to root). */
+interface Starter {
+  config: string;
+  files: (contentDir: string) => { content: string; path: string }[];
+}
+
+const configFor = (
+  extra: string
+): string => `import { defineConfig } from "blume";
 
 export default defineConfig({
   title: "My Docs",
-  description: "Documentation powered by Blume.",
+  description: "Documentation powered by Blume.",${extra}
 });
 `;
 
-const INDEX_TEMPLATE = `---
-title: Introduction
-description: Welcome to your new Blume docs.
----
-
-# Introduction
+const page = (title: string, description: string, body: string): string =>
+  `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
 
-Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
+const STARTERS: Record<Template, Starter> = {
+  api: {
+    config: configFor(`
+  openapi: {
+    enabled: true,
+    route: "/api",
+    sources: [
+      {
+        label: "Petstore",
+        spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+      },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page(
+          "API Reference",
+          "Explore the API.",
+          "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  changelog: {
+    config: configFor(`
+  navigation: {
+    tabs: [
+      { label: "Docs", path: "/" },
+      { label: "Changelog", path: "/changelog" },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: `---\ntitle: v1.0.0\ntype: changelog\ndate: 2026-01-01\n---\n\nThe first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.\n`,
+        path: join(dir, "changelog", "v1-0-0.mdx"),
+      },
+    ],
+  },
+  docs: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          `# Introduction\n\nWelcome to **Blume** — markdown-first docs powered by Astro and Vite.\n\nEdit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  sdk: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Get started with the SDK.",
+          "# Introduction\n\nInstall the SDK and make your first call. See [Installation](/installation)."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: page(
+          "Installation",
+          "Install the SDK.",
+          "# Installation\n\n```package-install\nyour-sdk\n```"
+        ),
+        path: join(dir, "installation.mdx"),
+      },
+    ],
+  },
+};
 
-Edit \`docs/index.mdx\` to get started, then run \`blume dev\`.
-`;
+/** Install + dev commands to print for the chosen package manager. */
+const commandsFor = (pm: PackageManager): { dev: string; install: string } => ({
+  dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
+  install: `${pm} install`,
+});
 
 const writeFileSafe = async (
   path: string,
@@ -73,6 +169,19 @@ export const initCommand = defineCommand({
       description: "Content directory.",
       type: "string",
     },
+    eject: {
+      description: "Eject to a standalone Astro project after scaffolding.",
+      type: "boolean",
+    },
+    "package-manager": {
+      description:
+        "Package manager for the next-steps hint (npm|pnpm|yarn|bun).",
+      type: "string",
+    },
+    template: {
+      description: "Starter template: docs | api | sdk | changelog.",
+      type: "string",
+    },
     yes: { description: "Skip prompts.", type: "boolean" },
   },
   meta: {
@@ -82,17 +191,76 @@ 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)) {
+      logger.error(
+        `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+    const pm = (args["package-manager"] ?? "npm") as PackageManager;
+    if (!PACKAGE_MANAGERS.includes(pm)) {
+      logger.error(
+        `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+
+    const starter = STARTERS[template];
     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);
+    await writeFileSafe(join(root, "blume.config.ts"), starter.config);
+    await Promise.all(
+      starter
+        .files(contentDir)
+        .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) {
+      // Eject only generates files (no Astro runtime), so it works right after
+      // scaffolding. The standalone app then runs with Astro directly.
+      try {
+        await eject(root);
+        logger.success("Ejected to a standalone Astro project.");
+        logger.box(`Next steps:\n\n  ${commands.install}\n  npx astro dev\n`);
+      } catch (error) {
+        logger.warn(
+          `Scaffolded, but eject failed: ${(error as Error).message}`
+        );
+        logger.box(
+          `Next steps:\n\n  ${commands.install}\n  blume eject --yes\n`
+        );
+      }
+      return;
+    }
 
     const nextSteps = createdPackage
-      ? "Next steps:\n\n  npm install\n  blume dev\n"
-      : "Next steps:\n\n  blume dev\n";
+      ? `Next steps:\n\n  ${commands.install}\n  ${commands.dev}\n`
+      : `Next steps:\n\n  ${commands.dev}\n`;
     logger.box(nextSteps);
   },
 });

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,11 +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 { logger, reportDiagnostics } from "../log.ts";
+import { reportInternalError } from "../internal-error.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 export const validateCommand = defineCommand({
   args: {
@@ -15,6 +22,10 @@ export const validateCommand = defineCommand({
       description: "Check external (HTTP) links over the network.",
       type: "boolean",
     },
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
     strict: {
       description: "Treat warnings as errors.",
       type: "boolean",
@@ -37,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,
@@ -46,8 +58,21 @@ export const validateCommand = defineCommand({
       if (error instanceof BlumeError) {
         diagnostics.push(error.diagnostic);
       } else {
-        throw error;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+
+    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;
     }
 
     const hadErrors = reportDiagnostics(diagnostics, root);

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/index.ts

@@ -3,6 +3,7 @@ import { defineCommand, runMain } from "citty";
 import { getBlumeVersion } from "../core/version.ts";
 import { addCommand } from "./commands/add.ts";
 import { buildCommand } from "./commands/build.ts";
+import { checkCommand } from "./commands/check.ts";
 import { devCommand } from "./commands/dev.ts";
 import { doctorCommand } from "./commands/doctor.ts";
 import { ejectCommand } from "./commands/eject.ts";
@@ -12,6 +13,7 @@ import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { loadEnvFiles } from "./env.ts";
+import { reportInternalError } from "./internal-error.ts";
 
 const main = defineCommand({
   meta: {
@@ -22,6 +24,7 @@ const main = defineCommand({
   subCommands: {
     add: addCommand,
     build: buildCommand,
+    check: checkCommand,
     dev: devCommand,
     doctor: doctorCommand,
     eject: ejectCommand,
@@ -37,4 +40,16 @@ const main = defineCommand({
 // can read their tokens (e.g. `GITHUB_TOKEN`) during the content scan.
 loadEnvFiles(process.cwd());
 
+// Backstop for unexpected async failures that escape a command's own handling
+// (e.g. a rejected timer/watcher in `blume dev`), so even those report through
+// the stable internal-error contract rather than a bare stack trace.
+process.on("uncaughtException", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
+process.on("unhandledRejection", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
+
 runMain(main);