blume 0.3.0 → 0.5.0

package/src/astro/templates.ts

@@ -4,8 +4,10 @@ import { dirname, join } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
+import { resolveAssetMounts } from "../core/assets.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
@@ -98,9 +100,10 @@ export const runtimeDependencies = (options: {
   if (needsSvelte) {
     deps.push("@astrojs/svelte");
   }
-  // The Scalar integration is only declared when an API reference is configured,
-  // so projects that don't use it never pull it into the runtime.
-  if (config.openapi.enabled || config.asyncapi.enabled) {
+  // The Scalar integration is only declared for a Scalar-rendered reference
+  // (the `renderer: "scalar"` fallback, or AsyncAPI). Blume-rendered OpenAPI
+  // parses at generate time and needs no runtime Scalar dependency.
+  if (hasScalarReferences(config)) {
     deps.push("@scalar/astro");
   }
   // Only the configured search provider's SDK is declared, so a project pulls in
@@ -177,6 +180,10 @@ const renderUserAliases = (
     )
     .join("");
 
+/** Astro's build output dir: the runtime's own `distDir`, else `<root>/dist`. */
+const astroOutDir = (context: ProjectContext): string =>
+  context.distDir ?? `${context.root}/dist`;
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -189,6 +196,7 @@ export const astroConfigTemplate = (options: {
   examplesPath: string;
   themePath: string;
   searchClientPath: string;
+  openapiPath: string;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
 }): string => {
@@ -198,6 +206,7 @@ export const astroConfigTemplate = (options: {
     examplesPath,
     needsSvelte,
     needsVue,
+    openapiPath,
     searchClientPath,
   } = options;
   const { deployment } = config;
@@ -304,10 +313,12 @@ export const astroConfigTemplate = (options: {
   if (needsSvelte) {
     integrations.push("svelte()");
   }
-  // Always mounted: injects user pages (a no-op when there are none) and wires
-  // up dev-server `Accept: text/markdown` negotiation over the content routes.
+  // Always mounted: injects user pages (a no-op when there are none), serves
+  // `content.assets` mounts, and wires up dev-server `Accept: text/markdown`
+  // negotiation over the content routes.
+  const assets = resolveAssetMounts(context.root, config.content.assets);
   integrations.push(
-    `blumeIntegration(${JSON.stringify({ contentRoutes, pages })})`
+    `blumeIntegration(${JSON.stringify({ assets, base: deployment.base, contentRoutes, pages })})`
   );
 
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
@@ -319,7 +330,7 @@ ${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapte
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
-  outDir: ${JSON.stringify(`${context.root}/dist`)},
+  outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
   output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}],
@@ -354,6 +365,7 @@ export default defineConfig({
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
+        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
         "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
       },
@@ -459,32 +471,49 @@ export const askEndpointTemplate = (
   if (grounded) {
     imports.push(
       'import { createAskContext } from "blume/ai/ask-context.ts";',
-      'import askData from "../generated/ask-data.json";'
+      'import askData from "../../generated/ask-data.json";'
     );
     setup += "\nconst ground = createAskContext(askData);\n";
   }
-  const handler = grounded
-    ? `export const POST: APIRoute = async ({ request }) => {
-  const { messages, page } = await request.json();
-  const system =
-    (await ground(messages, page)) ??
-    "You are a helpful documentation assistant. Answer using the project's documentation.";
-  const result = streamText({
-    model: ${modelExpr},
-    system,
-    messages,
-  });
-  return result.toTextStreamResponse();
-};`
-    : `export const POST: APIRoute = async ({ request }) => {
-  const { messages } = await request.json();
-  const result = streamText({
-    model: ${modelExpr},
-    system:
-      "You are a helpful documentation assistant. Answer using the project's documentation.",
-    messages,
-  });
-  return result.toTextStreamResponse();
+  // Validate the client-supplied body and cap its size. The endpoint is
+  // unauthenticated, so bounding message count/length limits how much a caller
+  // can spend against the model per request; front it with a rate limiter (or
+  // your provider's limits) for stronger protection.
+  const validate = `  const body = await request.json().catch(() => null);
+  const messages = body?.messages;
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.length > 40 ||
+    JSON.stringify(messages).length > 24_000
+  ) {
+    return new Response("Invalid request: send 1-40 messages.", {
+      status: 400,
+    });
+  }`;
+  const stream = grounded
+    ? `    const system =
+      (await ground(messages, body.page)) ??
+      "You are a helpful documentation assistant. Answer using the project's documentation.";
+    const result = streamText({
+      model: ${modelExpr},
+      system,
+      messages,
+    });`
+    : `    const result = streamText({
+      model: ${modelExpr},
+      system:
+        "You are a helpful documentation assistant. Answer using the project's documentation.",
+      messages,
+    });`;
+  const handler = `export const POST: APIRoute = async ({ request }) => {
+${validate}
+  try {
+${stream}
+    return result.toTextStreamResponse();
+  } catch {
+    return new Response("Failed to generate a response.", { status: 500 });
+  }
 };`;
   return `// Generated by Blume. Do not edit.
 ${imports.join("\n")}
@@ -893,7 +922,10 @@ import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
 import GithubInfo from "blume/components/content/GithubInfo.astro";
 import Panel from "blume/components/content/Panel.astro";
+import ParamField from "blume/components/content/ParamField.astro";
 import Prompt from "blume/components/content/Prompt.astro";
+import RequestField from "blume/components/content/RequestField.astro";
+import ResponseField from "blume/components/content/ResponseField.astro";
 import Step from "blume/components/content/Step.astro";
 import Steps from "blume/components/content/Steps.astro";
 import Tab from "blume/components/content/Tab.astro";
@@ -905,7 +937,10 @@ import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
+import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
+import ApiOverview from "blume/components/openapi/ApiOverview.astro";
+import Operation from "blume/components/openapi/Operation.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
 import data from "../generated/data.json";
@@ -922,6 +957,7 @@ export const prerender = true;
 const components = {
   Accordion,
   AccordionItem,
+  ApiOverview,
   AutoTypeTable,
   Badge,
   Callout,
@@ -939,8 +975,12 @@ const components = {
   Frame,
   GithubInfo,
   Icon,
+  Operation,
   Panel,
+  ParamField,
   Prompt,
+  RequestField,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -950,6 +990,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
 };
@@ -1426,6 +1467,11 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:openapi" {
+  const specs: import("blume/openapi/model.ts").OpenApiData;
+  export default specs;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn

package/src/cli/args.ts

@@ -0,0 +1,23 @@
+import { logger } from "./log.ts";
+
+const MAX_PORT = 65_535;
+
+/**
+ * Parse a `--port` value into a valid port number, or `undefined` when unset.
+ * A non-integer or out-of-range value (`--port abc` → `NaN`) exits with an
+ * error rather than propagating `localhost:NaN` into the dev server and the
+ * `deployment.site` fallback.
+ */
+export const parsePort = (value?: string): number | undefined => {
+  if (value === undefined) {
+    return;
+  }
+  const port = Number(value);
+  if (!(Number.isInteger(port) && port >= 1 && port <= MAX_PORT)) {
+    logger.error(
+      `Invalid --port "${value}" (expected an integer 1-${MAX_PORT}).`
+    );
+    process.exit(1);
+  }
+  return port;
+};

package/src/cli/commands/build.ts

@@ -6,6 +6,8 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { buildLlmsFiles } from "../../ai/llms.ts";
+import { ensureGitignore } from "../../core/gitignore.ts";
+import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import {
@@ -17,11 +19,32 @@ 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 { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+/**
+ * Reject a non-numeric performance budget. `Number("250kb")` is `NaN` and
+ * `total > NaN` is always false, so a typo'd flag would silently pass the gate;
+ * fail up front instead.
+ */
+const validateBudgetFlags = (args: {
+  "budget-css"?: string;
+  "budget-js"?: string;
+}): void => {
+  for (const flag of ["budget-js", "budget-css"] as const) {
+    const value = args[flag];
+    if (value !== undefined && !(Number(value) > 0)) {
+      logger.error(
+        `Invalid --${flag} "${value}" (expected a positive number of kB).`
+      );
+      process.exit(1);
+    }
+  }
+};
+
 /**
  * Emit platform redirect files for a static build (adapters wire redirects
  * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
@@ -148,6 +171,82 @@ const enforceBudget = async (
   return passed ? "pass" : "fail";
 };
 
+/**
+ * Run every deploy post-step of a real (non-isolated) build: the search index +
+ * hosted-provider sync, llms.txt, sitemap/robots, redirect files, the summary
+ * box, and the optional bundle report / budget gate. Exits non-zero if a budget
+ * is exceeded. Isolated verify builds skip all of this.
+ */
+const publishBuildArtifacts = async (
+  project: BlumeProject,
+  distDir: string,
+  args: { analyze?: boolean; "budget-css"?: string; "budget-js"?: string }
+): Promise<void> => {
+  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");
+  }
+
+  await emitRedirectFiles(project.config, distDir);
+
+  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")
+  );
+
+  if (args.analyze) {
+    await reportBundleSizes(distDir);
+  }
+
+  if ((await enforceBudget(distDir, args)) === "fail") {
+    process.exit(1);
+  }
+
+  logger.success(`Built to ${distDir}`);
+};
+
 export const buildCommand = defineCommand({
   args: {
     adapter: {
@@ -170,6 +269,11 @@ export const buildCommand = defineCommand({
       description: "Fail if total client JavaScript exceeds this many kB.",
       type: "string",
     },
+    isolated: {
+      description:
+        "Build into an isolated .blume-verify runtime (and its own dist) so a running dev server and the real dist/ are untouched. For verifying changes while `blume dev` runs.",
+      type: "boolean",
+    },
     output: {
       description: "Output mode: static | server.",
       type: "string",
@@ -187,6 +291,18 @@ export const buildCommand = defineCommand({
   async run({ args }) {
     const root = process.cwd();
 
+    // `--isolated` (or BLUME_RUNTIME_DIR) relocates the whole runtime to a
+    // sibling dir so this build never touches a live dev server's `.blume/` or
+    // the user's real `dist/`. A non-default runtime dir has no dev lock, so the
+    // refusal below lets it proceed; a plain build still refuses.
+    const runtimeDir = args.isolated
+      ? ".blume-verify"
+      : process.env.BLUME_RUNTIME_DIR;
+    refuseIfDevRunning(root, "building", runtimeDir);
+    if (args.isolated) {
+      await ensureGitignore(root, [".blume-verify/"]);
+    }
+
     if (args.output && args.output !== "static" && args.output !== "server") {
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
@@ -197,6 +313,7 @@ export const buildCommand = defineCommand({
       );
       process.exit(1);
     }
+    validateBudgetFlags(args);
 
     const project = await prepareProject({
       mode: "build",
@@ -207,6 +324,7 @@ export const buildCommand = defineCommand({
       },
       preview: args.preview,
       root,
+      runtimeDir,
       strict: args.strict,
     });
 
@@ -219,70 +337,19 @@ export const buildCommand = defineCommand({
       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`);
-    }
+    const distDir = project.context.distDir ?? join(root, "dist");
 
-    // 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");
-    }
-
-    await emitRedirectFiles(project.config, distDir);
-
-    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")
-    );
-
-    if (args.analyze) {
-      await reportBundleSizes(distDir);
-    }
-
-    if ((await enforceBudget(distDir, args)) === "fail") {
-      process.exit(1);
+    // An isolated build is a throwaway verify: it only needs to confirm the site
+    // compiles and renders. Skip the network post-steps (search sync) and
+    // deploy artifacts (index/llms/sitemap/robots/redirects) that only matter
+    // for a real publish and would push to hosted providers.
+    if (runtimeDir) {
+      logger.success(
+        `Isolated build OK — output at ${distDir} (not published).`
+      );
+      return;
     }
 
-    logger.success(`Built to ${distDir}`);
+    await publishBuildArtifacts(project, distDir, args);
   },
 });

package/src/cli/commands/check.ts

@@ -5,11 +5,18 @@ import { sync } from "astro";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { ensureGitignore } from "../../core/gitignore.ts";
+import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 export const checkCommand = defineCommand({
   args: {
+    isolated: {
+      description:
+        "Type-check in an isolated .blume-verify runtime so a running dev server is untouched. For verifying changes while `blume dev` runs.",
+      type: "boolean",
+    },
     preview: {
       description: "Include drafts and unpublished CMS content.",
       type: "boolean",
@@ -25,10 +32,23 @@ export const checkCommand = defineCommand({
   },
   async run({ args }) {
     const root = process.cwd();
+
+    // `blume check` regenerates `.blume` just like `build`, so it must refuse a
+    // live dev server unless isolated. `--isolated` (or BLUME_RUNTIME_DIR)
+    // relocates the runtime to `.blume-verify`, which dev never locks.
+    const runtimeDir = args.isolated
+      ? ".blume-verify"
+      : process.env.BLUME_RUNTIME_DIR;
+    refuseIfDevRunning(root, "checking", runtimeDir);
+    if (args.isolated) {
+      await ensureGitignore(root, [".blume-verify/"]);
+    }
+
     const project = await prepareProject({
       mode: "build",
       preview: args.preview,
       root,
+      runtimeDir,
       strict: args.strict,
     });
 

package/src/cli/commands/dev.ts

@@ -6,6 +6,8 @@ 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";
 
@@ -41,7 +43,8 @@ export const devCommand = defineCommand({
     // 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,
@@ -58,13 +61,18 @@ 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: 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,
       },
     });
 
@@ -118,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

@@ -5,7 +5,12 @@ import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 const MIN_NODE_MAJOR = 20;
 
@@ -74,7 +79,11 @@ export const doctorCommand = defineCommand({
     }
 
     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;

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,8 +2,9 @@ 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";
@@ -190,6 +191,17 @@ 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)) {
@@ -218,6 +230,14 @@ export const initCommand = defineCommand({
         .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) {