blume 2.0.0 → 2.0.2

package/src/cli/commands/audit.ts

@@ -11,6 +11,7 @@ import { formatCatalog, formatReport, reportJson } from "../../audit/report.ts";
 import { NoBuildError, runAudit } from "../../audit/run.ts";
 import type { AuditResult } from "../../audit/run.ts";
 import { checkTerms, unknownCheckTerms } from "../../audit/terms.ts";
+import { isHttpUrl } from "../../audit/url.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
@@ -154,7 +155,7 @@ export const auditCommand = defineCommand({
       (kind) => args[kind]
     );
     if (agents.length > 1) {
-      logger.error("Pass at most one of --claude or --codex.");
+      logger.error("Pass at most one of --codex or --claude.");
       process.exit(1);
     }
     const [agent] = agents;
@@ -162,6 +163,12 @@ export const auditCommand = defineCommand({
       logger.error(`--json and --${agent} are mutually exclusive.`);
       process.exit(1);
     }
+    if (args.url !== undefined && !isHttpUrl(args.url)) {
+      logger.error(
+        `Invalid --url "${args.url}": pass the deployment's full URL, scheme included (e.g. https://${args.url}).`
+      );
+      process.exit(1);
+    }
     const only = splitTerms(args.only);
     const skip = splitTerms(args.skip);
     rejectUnknownTerms([...only, ...skip]);

package/src/cli/commands/build.ts

@@ -6,6 +6,7 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { publishBuildProject } from "../../astro/integration.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
 import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
@@ -21,10 +22,11 @@ import {
   removedBuildFlags,
   removedBuildFlagsAdvice,
 } from "../../upgrade/upgrade.ts";
+import { astroBuildDiagnostics } from "../build-failure.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { refuseIfEjected } from "../eject-scripts.ts";
-import { logger } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 const BUDGET_JS = "budget-js";
@@ -333,10 +335,22 @@ export const buildCommand = defineCommand({
       publishBuildProject(project);
     }
 
-    await build({
-      logLevel: "info",
-      root: project.context.outDir,
-    });
+    try {
+      await build({
+        logLevel: "info",
+        root: project.context.outDir,
+      });
+    } catch (error) {
+      // Astro rejects when the site fails to compile or render (MDX that
+      // doesn't parse, a component that throws): report that as a build error
+      // at the file it names, not as an internal error blaming Blume. A
+      // BlumeError keeps its own diagnostic.
+      if (error instanceof BlumeError || !(error instanceof Error)) {
+        throw error;
+      }
+      reportDiagnostics(astroBuildDiagnostics(error), root);
+      process.exit(1);
+    }
 
     // A real build also prunes the cache; an isolated verify must not evict
     // cards a live dev server is still serving.

package/src/cli/commands/check.ts

@@ -8,6 +8,7 @@ import { join } from "pathe";
 import { ensureGitignore } from "../../core/gitignore.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
+import { refuseIfEjected } from "../eject-scripts.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -30,6 +31,7 @@ export const checkCommand = defineCommand({
   meta: commandMeta.check,
   async run({ args }) {
     const root = process.cwd();
+    await refuseIfEjected(root, "check");
 
     // `blume check` regenerates `.blume` just like `build`, so it must refuse a
     // live dev server unless isolated. `--isolated` (or BLUME_RUNTIME_DIR)

package/src/cli/commands/doctor.ts

@@ -153,12 +153,14 @@ export const doctorCommand = defineCommand({
         logger.info(
           `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`
         );
-        const { ask } = config.ai;
-        let askSummary = "off";
-        if (ask?.enabled) {
-          askSummary = ask.endpoint ? "external endpoint" : ask.provider.kind;
+        const { assistant } = config.ai;
+        let assistantSummary = "off";
+        if (assistant?.enabled) {
+          assistantSummary = assistant.endpoint
+            ? "external endpoint"
+            : assistant.provider.kind;
         }
-        logger.info(`Ask AI: ${askSummary}`);
+        logger.info(`Assistant: ${assistantSummary}`);
       }
     } catch (error) {
       if (error instanceof BlumeError) {

package/src/cli/commands/eval.ts

@@ -19,7 +19,7 @@ import {
   warningLines,
   writeEvalReport,
 } from "../../eval/report.ts";
-import { runEval } from "../../eval/run.ts";
+import { passFraction, runEval } from "../../eval/run.ts";
 import type { EvalResult } from "../../eval/run.ts";
 import { EvalsFileError, loadEvalsFile } from "../../eval/schema.ts";
 import { commandMeta } from "../command-meta.ts";
@@ -63,12 +63,6 @@ const launchAgentCode = async (
   }
 };
 
-/** The fraction of run (non-skipped) questions that passed. */
-export const passFraction = (result: EvalResult): number => {
-  const ran = result.results.length - result.counts.skip;
-  return ran === 0 ? 1 : result.counts.pass / ran;
-};
-
 interface EvalFlags {
   action?: string;
   agent: string;
@@ -82,7 +76,7 @@ interface EvalFlags {
 /** Validate the flag surface, exiting with a message on the first offense. */
 const parseFlags = (args: EvalFlags) => {
   if (!isAgentKind(args.agent)) {
-    logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
+    logger.error(`Invalid --agent "${args.agent}" (use codex | claude).`);
     process.exit(1);
   }
   if (args.action !== undefined && args.action !== "init") {
@@ -152,8 +146,8 @@ export const evalCommand = defineCommand({
       type: "positional",
     },
     agent: {
-      default: "claude",
-      description: "Agent CLI that reads and grades the docs: claude | codex.",
+      default: "codex",
+      description: "Agent CLI that reads and grades the docs: codex | claude.",
       type: "string",
     },
     file: {

package/src/cli/commands/init.ts

@@ -11,9 +11,11 @@ import { collectAnswers } from "../init/questions.ts";
 import {
   applyPlan,
   buildPlan,
+  cdCommand,
   commandsFor,
   detectPackageManager,
   nextSteps,
+  outsidePnpmWorkspace,
   PACKAGE_MANAGERS,
   readExistingPackage,
   TEMPLATES,
@@ -25,7 +27,7 @@ import { logger } from "../log.ts";
 
 /** The `cd` line that opens every next-steps hint, when one is needed. */
 const cdStep = (answers: InitAnswers): string[] =>
-  answers.directory === "." ? [] : [`cd ${answers.directory}`];
+  answers.directory === "." ? [] : [cdCommand(answers.directory)];
 
 /**
  * Install the scaffolded project's dependencies. Interactive runs hide the
@@ -99,8 +101,13 @@ const ejectScaffold = async (
   } catch (error) {
     // SAFETY: eject and the script rewrite throw Error instances; only the
     // message is surfaced in the fallback hint.
+    const { message } = error as Error;
+    // Only a skipped install explains the failure; after an install that ran,
+    // the error itself is the reason.
     logger.warn(
-      `Scaffolded, but eject needs the project's dependencies installed to load blume.config.ts: ${(error as Error).message}`
+      needsInstall
+        ? `Scaffolded, but eject needs the project's dependencies installed to load blume.config.ts: ${message}`
+        : `Scaffolded, but eject failed: ${message}`
     );
     const steps = [...cd, ...install, `${commands.exec} blume eject --yes`];
     logger.box(`Next steps:\n\n  ${steps.join("\n  ")}`);
@@ -229,7 +236,7 @@ export const initCommand = defineCommand({
         { cwd, userAgent: process.env.npm_config_user_agent }
       );
       if (collected === null) {
-        clack.cancel("Cancelled — nothing was written.");
+        clack.cancel("Canceled — nothing was written.");
         process.exit(0);
       }
       answers = collected;
@@ -279,8 +286,11 @@ export const initCommand = defineCommand({
     }
 
     // A newly written package.json is the only one `init` knows lists blume;
-    // an existing one is left alone, and so are its dependencies.
-    const shouldInstall = createdPackage && args.install;
+    // an existing one is left alone, and so are its dependencies. In a pnpm
+    // workspace that doesn't list the folder, an install would exit 0 without
+    // installing it, so that one waits until the note's change is made.
+    const shouldInstall =
+      createdPackage && args.install && !outsidePnpmWorkspace(root, answers);
     if (note) {
       (interactive ? clack.log : logger).warn(note);
     }

package/src/cli/commands/migrate.ts

@@ -53,7 +53,7 @@ export const migrateCommand = defineCommand({
       (kind) => args[kind]
     );
     if (agents.length > 1) {
-      logger.error("Pass at most one of --claude or --codex.");
+      logger.error("Pass at most one of --codex or --claude.");
       process.exit(1);
     }
     const [agent] = agents;
@@ -88,7 +88,7 @@ export const migrateCommand = defineCommand({
       // plus the install line that puts the skill where agents look for it.
       if (!agent) {
         process.stderr.write(
-          `  blume migrate runs the migration with a coding agent: rerun with --claude or --codex.\n  Using another agent? Point it at ${join(skillDir, "SKILL.md")},\n  or install the skill where your agent looks for skills: npx skills add haydenbleasel/blume --skill blume-migrate\n`
+          `  blume migrate runs the migration with a coding agent: rerun with --codex or --claude.\n  Using another agent? Point it at ${join(skillDir, "SKILL.md")},\n  or install the skill where your agent looks for skills: npx skills add haydenbleasel/blume --skill blume-migrate\n`
         );
         return;
       }

package/src/cli/commands/preview.ts

@@ -7,8 +7,10 @@ import { join } from "pathe";
 import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
 import { deployOutputDir } from "../../deploy/adapter-output.ts";
+import { deployPlatform } from "../../deploy/platforms/index.ts";
 import { parsePort } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
+import { refuseIfEjected } from "../eject-scripts.ts";
 import { normalizeHost } from "../host-args.ts";
 import { logger } from "../log.ts";
 
@@ -20,9 +22,22 @@ export const previewCommand = defineCommand({
   meta: commandMeta.preview,
   async run({ args }) {
     const root = process.cwd();
+    await refuseIfEjected(root, "preview");
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
 
+    // Astro previews a server build through its adapter's preview entrypoint,
+    // and the Vercel and Netlify adapters declare none, so Astro would throw
+    // mid-command. Say so up front, with what to run instead.
+    const { deployment } = config;
+    const platform = deployPlatform(deployment);
+    if (deployment.options.output === "server" && platform.previewDeploy) {
+      logger.error(
+        `\`blume preview\` can't serve a ${deployment.kind}() server build: ${platform.astro?.package} has no local preview server. Run \`blume dev\` to try the site locally, or deploy a preview with \`${platform.previewDeploy}\`.`
+      );
+      process.exit(1);
+    }
+
     // `blume dev` writes `.blume/astro.config.mjs` too, so the runtime alone
     // doesn't mean there's anything to serve: the build output must exist.
     if (

package/src/cli/commands/sync.ts

@@ -10,6 +10,7 @@ import {
 } from "../../core/project.ts";
 import { commandMeta } from "../command-meta.ts";
 import { readDevLock } from "../dev-lock.ts";
+import { refuseIfEjected } from "../eject-scripts.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -28,6 +29,7 @@ export const syncCommand = defineCommand({
   meta: commandMeta.sync,
   async run({ args }) {
     const root = process.cwd();
+    await refuseIfEjected(root, "sync");
 
     // `--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.

package/src/cli/commands/translate.ts

@@ -4,7 +4,6 @@ import { AGENTS } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { i18nEnabled, localeCodes } from "../../core/i18n.ts";
-import { scanProject } from "../../core/project-graph.ts";
 import type { ResolvedI18nConfig } from "../../core/schema.ts";
 import { DEFAULT_TRANSLATE_TIMEOUT_MS } from "../../translate/agents.ts";
 import {
@@ -25,7 +24,10 @@ import {
   translateSummaryLine,
 } from "../../translate/report.ts";
 import { runTranslate } from "../../translate/run.ts";
-import { computeWorkList } from "../../translate/work-list.ts";
+import {
+  computeWorkList,
+  scanForTranslation,
+} from "../../translate/work-list.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
@@ -63,18 +65,18 @@ const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
     (kind) => args[kind]
   );
   if (agents.length > 1) {
-    logger.error("Pass exactly one of --claude or --codex.");
+    logger.error("Pass exactly one of --codex or --claude.");
     process.exit(1);
   }
   if (args.check && agents.length > 0) {
     logger.error(
-      "--check is read-only and never runs an agent; drop --claude/--codex."
+      "--check is read-only and never runs an agent; drop --codex/--claude."
     );
     process.exit(1);
   }
   if (!args.check && agents.length === 0) {
     logger.error(
-      "Pass --claude or --codex to choose the agent CLI that translates."
+      "Pass --codex or --claude to choose the agent CLI that translates."
     );
     process.exit(1);
   }
@@ -188,10 +190,11 @@ export const translateCommand = defineCommand({
     const { agent, concurrency, timeoutS } = parseFlags(args);
 
     try {
-      // `scanProject`, not `prepareProject`: translation reads the content
-      // tree and writes source files, never `.blume/`, so it doesn't contend
-      // with a running dev server. Same reasoning as `blume audit`/`eval`.
-      const project = await scanProject(root, { mode: "build" });
+      // A scan, not `prepareProject`: translation reads the content tree and
+      // writes source files, never `.blume/`, so it doesn't contend with a
+      // running dev server. Same reasoning as `blume audit`/`eval`. Drafts
+      // are included (see `scanForTranslation`).
+      const project = await scanForTranslation(root);
       if (!i18nEnabled(project.config)) {
         logger.error(
           "i18n is not configured — add `i18n.locales` to blume.config to use `blume translate`."

package/src/cli/commands/upgrade.ts

@@ -12,6 +12,7 @@ import {
   bumpBlumeDependency,
   collectUpgradeFindings,
   isOutsideBlumeProject,
+  manualBumpAdvice,
   upgradePrompt,
 } from "../../upgrade/upgrade.ts";
 import { commandMeta } from "../command-meta.ts";
@@ -56,7 +57,7 @@ export const upgradeCommand = defineCommand({
       (kind) => args[kind]
     );
     if (agents.length > 1) {
-      logger.error("Pass at most one of --claude or --codex.");
+      logger.error("Pass at most one of --codex or --claude.");
       process.exit(1);
     }
     const [agent] = agents;
@@ -94,10 +95,20 @@ export const upgradeCommand = defineCommand({
         logger.warn(
           `No \`blume\` dependency in ./package.json; add blume@^${version} to the package that uses it.`
         );
+      } else if (bump.status === "manual") {
+        logger.warn(manualBumpAdvice(bump.range, version));
       }
 
       const findings = await collectUpgradeFindings(root);
       if (findings.length === 0) {
+        // Until the range the bump couldn't rewrite moves, the project still
+        // installs the old Blume, so it isn't ready yet.
+        if (bump.status === "manual") {
+          process.stderr.write(
+            `  The config, components.ts, and pages check out for Blume ${version}. Update blume's version as above, reinstall, then run \`${runner} blume build\` to confirm.\n`
+          );
+          process.exit(1);
+        }
         process.stderr.write(
           `  Ready for Blume ${version}: the config, components.ts, and pages check out. Run \`${runner} blume build\` to confirm.\n`
         );
@@ -109,7 +120,7 @@ export const upgradeCommand = defineCommand({
 
       if (!agent) {
         process.stderr.write(
-          `  Each change is covered in the upgrade guide: ${UPGRADE_GUIDE_URL}\n  Rerun with --claude or --codex to hand them to a coding agent.\n`
+          `  Each change is covered in the upgrade guide: ${UPGRADE_GUIDE_URL}\n  Rerun with --codex or --claude to hand them to a coding agent.\n`
         );
         process.exit(1);
       }

package/src/cli/eject-scripts.ts

@@ -6,6 +6,7 @@ import { join } from "pathe";
 import { EJECTED_CONFIG_HEADER } from "../astro/templates.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { commandsFor, detectProjectPackageManager } from "./init/scaffold.ts";
+import type { PackageManager } from "./init/scaffold.ts";
 import { logger } from "./log.ts";
 
 /** A JSON value, as `JSON.parse` of a manifest can return. */
@@ -136,22 +137,46 @@ export const isEjectedProject = (root: string): boolean => {
   );
 };
 
+/** The Blume commands that run the hidden `.blume/` copy of the site. */
+export type RuntimeCommand = "build" | "check" | "dev" | "preview" | "sync";
+
+/**
+ * What an ejected app runs in place of each {@link RuntimeCommand}: its own
+ * `dev`/`build`/`preview` scripts (eject writes them), or Astro's CLI for the
+ * check and the content sync.
+ */
+const ejectedEquivalent = (
+  pm: PackageManager,
+  command: RuntimeCommand
+): string => {
+  const { build, dev, exec } = commandsFor(pm);
+  return {
+    build,
+    check: `${exec} astro check`,
+    dev,
+    // Spelled like `dev`: npm runs a custom script only through `run`.
+    preview: pm === "npm" ? "npm run preview" : `${pm} preview`,
+    sync: `${exec} astro sync`,
+  }[command];
+};
+
 /**
- * Stop `blume dev`/`blume build` in an ejected app. Either would regenerate
- * `.blume/` from `blume.config.ts` and run that hidden copy, ignoring every
- * edit made to the app since eject, so point at the app's own script under
- * the project's package manager instead.
+ * Stop a command that works on the hidden runtime in an ejected app. `dev`,
+ * `build`, `check`, and `sync` would regenerate `.blume/` from
+ * `blume.config.ts` and run that hidden copy, ignoring every edit made to the
+ * app since eject, and `preview` would look for that copy's build; point at
+ * the app's own command under the project's package manager instead.
  */
 export const refuseIfEjected = async (
   root: string,
-  script: "build" | "dev"
+  command: RuntimeCommand
 ): Promise<void> => {
   if (!isEjectedProject(root)) {
     return;
   }
-  const commands = commandsFor(await detectProjectPackageManager(root));
+  const pm = await detectProjectPackageManager(root);
   logger.error(
-    `This project was ejected to a standalone Astro app, so \`blume ${script}\` would run a regenerated copy of the site instead of it. Run \`${commands[script]}\` instead.`
+    `This project was ejected to a standalone Astro app, so \`blume ${command}\` would run a regenerated copy of the site instead of it. Run \`${ejectedEquivalent(pm, command)}\` instead.`
   );
   process.exit(1);
 };

package/src/cli/env.ts

@@ -19,6 +19,11 @@ import { dirname, join, resolve } from "pathe";
  * these files at build time, so a value means the same thing to the pre-boot
  * content scan and the built site — including multi-line double-quoted values
  * (PEM keys), which a line-based parser silently truncates.
+ *
+ * `NODE_ENV` is never taken from these files: it picks the mode Vite and Astro
+ * run in, so a monorepo root `.env` that sets it for another app would turn
+ * every `blume build` into a development build (or `blume dev` into a
+ * production one).
  */
 export const loadEnvFiles = (startDir: string): void => {
   const paths: string[] = [];
@@ -31,5 +36,11 @@ export const loadEnvFiles = (startDir: string): void => {
     done = existsSync(join(dir, ".git")) || parent === dir;
     dir = parent;
   }
-  config({ path: paths, quiet: true });
+  const loaded: Record<string, string> = {};
+  config({ path: paths, processEnv: loaded, quiet: true });
+  for (const [key, value] of Object.entries(loaded)) {
+    if (key !== "NODE_ENV" && process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
 };