blume 2.0.1 → 2.0.2

package/src/audit/report.ts

@@ -33,12 +33,47 @@ const TIER_FLAGS: { tier: AuditTier; flag: string }[] = [
 interface CheckRollup {
   id: CheckId;
   count: number;
+  /** Distinct affected URLs — one page can carry several findings. */
+  pages: number;
   severity: DiagnosticSeverity;
   category: AuditCategory;
   title: string;
   findings: Diagnostic[];
 }
 
+const SEVERITY_ORDER = {
+  error: 0,
+  info: 2,
+  warning: 1,
+} satisfies Record<DiagnosticSeverity, number>;
+
+/**
+ * The group's severity: the worst of its findings'. A check can downgrade a
+ * finding at runtime (an external link answering 503 is a warning, not the
+ * catalog's error), and the group's glyph must agree with the summary counts.
+ */
+const worstSeverity = (findings: Diagnostic[]): DiagnosticSeverity => {
+  let worst: DiagnosticSeverity = "info";
+  for (const finding of findings) {
+    if (SEVERITY_ORDER[finding.severity] < SEVERITY_ORDER[worst]) {
+      worst = finding.severity;
+    }
+  }
+  return worst;
+};
+
+/** The first finding per affected URL, in report order. */
+const firstPerPage = (findings: Diagnostic[]): Diagnostic[] => {
+  const seen = new Set<string | undefined>();
+  return findings.filter((finding) => {
+    if (seen.has(finding.url)) {
+      return false;
+    }
+    seen.add(finding.url);
+    return true;
+  });
+};
+
 /**
  * Group findings by check. This is the difference between a report people read
  * and one they close: 214 pages × 6 findings is an unreadable wall, but "Meta
@@ -55,22 +90,18 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
     }
   }
 
-  const order = {
-    error: 0,
-    info: 2,
-    warning: 1,
-  } satisfies Record<DiagnosticSeverity, number>;
   const checks = [...groups.entries()].map(([id, findings]) => {
     // SAFETY: audit findings are only ever created through `finding()`, whose
     // codes are the check catalog's ids.
     const checkId = id as CheckId;
-    const { category, severity, title } = checkMeta(checkId);
+    const { category, title } = checkMeta(checkId);
     return {
       category,
       count: findings.length,
       findings,
       id: checkId,
-      severity,
+      pages: firstPerPage(findings).length,
+      severity: worstSeverity(findings),
       title,
     };
   });
@@ -80,7 +111,7 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
   // and print "content" three separate times.
   const worst = new Map<AuditCategory, number>();
   for (const check of checks) {
-    const rank = order[check.severity];
+    const rank = SEVERITY_ORDER[check.severity];
     worst.set(
       check.category,
       Math.min(worst.get(check.category) ?? rank, rank)
@@ -91,7 +122,7 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
     (a, b) =>
       (worst.get(a.category) ?? 0) - (worst.get(b.category) ?? 0) ||
       a.category.localeCompare(b.category) ||
-      order[a.severity] - order[b.severity] ||
+      SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
       b.count - a.count
   );
 };
@@ -176,14 +207,16 @@ export const formatReport = (
     }
 
     const color = SEVERITY_COLOR[group.severity];
-    const pages = `${group.count} page${group.count === 1 ? "" : "s"}`;
+    const pages = `${group.pages} page${group.pages === 1 ? "" : "s"}`;
     lines.push(
       `  ${color(`${GLYPH[group.severity]} ${group.title}`)}  ${colors.dim(pages)}`
     );
 
+    // The preview lists affected pages, each once; --verbose lists every
+    // finding, since each one's message names a different specific.
     const shown = options.verbose
       ? group.findings
-      : group.findings.slice(0, PREVIEW);
+      : firstPerPage(group.findings).slice(0, PREVIEW);
     for (const diagnostic of shown) {
       lines.push(findingLine(diagnostic, root));
       // The message names the specifics the rolled-up line can't — which target
@@ -192,16 +225,20 @@ export const formatReport = (
         lines.push(`        ${colors.dim(diagnostic.message)}`);
       }
     }
-    const hidden = group.count - shown.length;
+    const hidden = options.verbose ? 0 : group.pages - shown.length;
     if (hidden > 0) {
       lines.push(`      ${colors.dim(`… and ${hidden} more (--verbose)`)}`);
     }
 
-    // Every finding in a group shares the catalog's fix unless it overrode it,
-    // so showing the first one's is showing the group's.
-    const [first] = group.findings;
-    const fix = first?.suggestion;
-    if (fix) {
+    // Findings share the catalog's fix unless one overrode it (a navigation
+    // entry, a page generated from an API spec), so each distinct fix is
+    // printed once.
+    const fixes = new Set(
+      group.findings.flatMap((finding) =>
+        finding.suggestion ? [finding.suggestion] : []
+      )
+    );
+    for (const fix of fixes) {
       lines.push(`      ${colors.cyan(`fix: ${fix}`)}`);
     }
     lines.push("");

package/src/audit/run.ts

@@ -137,6 +137,7 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
 
   const crawl = await crawlStaticDir({
     basePath,
+    deployBase: normalizeBasePath(project.config.deployment.options.base),
     manifest: project.manifest,
     staticDir,
   });

package/src/audit/types.ts

@@ -113,6 +113,16 @@ export interface RedirectResolution {
   outcome: "ok" | "loop" | "broken" | "chain";
 }
 
+/** One urlset file behind a sitemap, for the per-file size limits. */
+export interface SitemapPart {
+  file: string;
+  /** Site path the file is served at, e.g. `/sitemap-1.xml`. */
+  url: string;
+  bytes: number;
+  /** How many `<url>` entries the file lists. */
+  urls: number;
+}
+
 /** A parsed `sitemap.xml`. */
 export interface SitemapDoc {
   file: string;
@@ -121,6 +131,14 @@ export interface SitemapDoc {
   urls: string[];
   /** Each `<url>` block's `<lastmod>`, keyed by its `<loc>`. */
   lastmod?: Map<string, string>;
+  /**
+   * The child sitemaps' `<loc>`s, when `sitemap.xml` is a sitemap index —
+   * Blume writes one past 50,000 URLs. The crawler reads each child from the
+   * build and merges its URLs into `urls` and `lastmod`.
+   */
+  sitemaps?: string[];
+  /** The index's child urlset files, once the crawler has read them. */
+  parts?: SitemapPart[];
   /** Parse failure, when the document isn't usable. */
   error?: string;
 }

package/src/audit/url.ts

@@ -43,11 +43,21 @@ export type ResolvedHref =
   | { kind: "internal"; path: string; hash: string }
   /** An absolute URL that resolves back to this site — should have been a path. */
   | { kind: "self-origin"; path: string; hash: string }
+  /**
+   * A path on this origin that lacks `deployment.base`. The host serves the
+   * whole build under the base, so nothing answers here — `path` is the path
+   * as requested, base missing.
+   */
+  | { kind: "outside-base"; path: string }
   /** An absolute URL on another origin. */
   | { kind: "external"; url: string }
   /** In-page anchor, `mailto:`, `tel:`, `javascript:`, data URI — not a page link. */
   | { kind: "ignored" };
 
+/** Whether a served path sits under the deployment base (always, without one). */
+const underBase = (deployBase: string, path: string): boolean =>
+  !deployBase || path === deployBase || path.startsWith(`${deployBase}/`);
+
 const NON_HTTP_SCHEME = /^(?!https?:)[a-z][a-z0-9+.-]*:/iu;
 
 /**
@@ -65,6 +75,20 @@ export const decodePath = (path: string): string => {
   }
 };
 
+/**
+ * Whether a `--url` value is an absolute http(s) URL the network tier can
+ * probe. A bare host (`example.com`) has no scheme, and `localhost:4321`
+ * parses with `localhost:` as its scheme — both are rejected.
+ */
+export const isHttpUrl = (input: string): boolean => {
+  try {
+    const { protocol } = new URL(input);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+
 /** The origin of `deployment.site`, or null when no site is configured. */
 export const siteOrigin = (site?: string): string | null => {
   if (!site) {
@@ -113,12 +137,14 @@ export const resolveHref = (
       return { kind: "ignored" };
     }
     if (origin && parsed.origin === origin) {
+      const served = decodePath(parsed.pathname);
+      if (!underBase(deployBase, served)) {
+        return { kind: "outside-base", path: normalizePath(served) };
+      }
       return {
         hash: parsed.hash.slice(1),
         kind: "self-origin",
-        path: normalizePath(
-          stripBasePath(deployBase, decodePath(parsed.pathname))
-        ),
+        path: normalizePath(stripBasePath(deployBase, served)),
       };
     }
     return { kind: "external", url: parsed.toString() };
@@ -140,11 +166,16 @@ export const resolveHref = (
   } catch {
     return { kind: "ignored" };
   }
+  const served = decodePath(resolved.pathname);
+  // Only a root-relative href names the served path outright; a relative one
+  // (`./auth`) was resolved against the base-less page URL above, so it
+  // inherits the page's base by construction.
+  if (target.startsWith("/") && !underBase(deployBase, served)) {
+    return { kind: "outside-base", path: normalizePath(served) };
+  }
   return {
     hash: resolved.hash.slice(1),
     kind: "internal",
-    path: normalizePath(
-      stripBasePath(deployBase, decodePath(resolved.pathname))
-    ),
+    path: normalizePath(stripBasePath(deployBase, served)),
   };
 };

package/src/cli/build-failure.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+import type { Diagnostic } from "../core/types.ts";
+
+/**
+ * The fields of an `astro build` rejection the report reads. Rolldown bundles
+ * every plugin failure (an MDX compile error, say) into one error whose
+ * `errors` holds each; a failure carries `loc` where the compiler pinned it,
+ * or only `id`, the module that failed.
+ */
+const buildErrorSchema = z.looseObject({
+  errors: z.array(z.instanceof(Error)).optional(),
+  id: z.string().optional(),
+  loc: z
+    .looseObject({
+      column: z.number().optional(),
+      file: z.string().optional(),
+      line: z.number().optional(),
+    })
+    .optional(),
+});
+
+/** One failure as a diagnostic at the file (and position) it names. */
+const failureDiagnostic = (error: Error): Diagnostic => {
+  const parsed = buildErrorSchema.safeParse(error);
+  const { id, loc } = parsed.success ? parsed.data : {};
+  // A named error (`MDXError`, `CompilerError`) says which step failed.
+  const name = error.name === "Error" ? "" : `${error.name}: `;
+  return {
+    code: "BLUME_BUILD_FAILED",
+    column: loc?.column,
+    file: loc?.file ?? id,
+    line: loc?.line,
+    message: `${name}${error.message}`,
+    severity: "error",
+  };
+};
+
+/**
+ * What `astro build` rejected with, as build diagnostics: one per failure
+ * Rolldown collected, else the error itself. A page Blume's own checks pass
+ * can still fail Astro's compile (MDX that doesn't parse) or render, and that
+ * is a problem in the site, reported at its file, rather than an internal
+ * error blaming Blume.
+ */
+export const astroBuildDiagnostics = (error: Error): Diagnostic[] => {
+  const parsed = buildErrorSchema.safeParse(error);
+  const failures = parsed.success ? (parsed.data.errors ?? []) : [];
+  return (failures.length > 0 ? failures : [error]).map(failureDiagnostic);
+};

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";
@@ -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/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;

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/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";
@@ -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";
@@ -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`
         );

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);
 };