blume 2.0.1 → 2.0.3

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,10 +24,14 @@ 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 { parseTimeoutSeconds } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { flushStdout, logger, reportDiagnostics } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 
 /** Wall-clock ceiling per file, in seconds. */
 const DEFAULT_TIMEOUT_S = DEFAULT_TRANSLATE_TIMEOUT_MS / 1000;
@@ -78,12 +81,7 @@ const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
     );
     process.exit(1);
   }
-  const timeoutS =
-    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
-  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
-    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
-    process.exit(1);
-  }
+  const timeoutS = parseTimeoutSeconds(args.timeout, DEFAULT_TIMEOUT_S);
   const concurrency =
     args.concurrency === undefined
       ? DEFAULT_CONCURRENCY
@@ -188,10 +186,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`."
@@ -225,8 +224,9 @@ export const translateCommand = defineCommand({
           process.stdout.write(checkReportJson(workList));
         }
         if (hasDrift(workList)) {
-          await flushStdout();
-          process.exit(1);
+          // Set the code and return rather than `process.exit`, which waits for
+          // neither a piped stderr (the drift report) nor a piped stdout.
+          process.exitCode = 1;
         }
         return;
       }
@@ -287,9 +287,9 @@ export const translateCommand = defineCommand({
       }
       if (result.counts.failed > 0 || result.counts.partial > 0) {
         // The ledger write above already persisted every success, so a failed
-        // rerun only retries what actually failed.
-        await flushStdout();
-        process.exit(1);
+        // rerun only retries what actually failed. Set the code rather than
+        // `process.exit`, which would cut off a piped stderr summary.
+        process.exitCode = 1;
       }
     } catch (error) {
       if (error instanceof BlumeError) {

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/commands/validate.ts

@@ -119,7 +119,9 @@ export const validateCommand = defineCommand({
       logger.success("No broken links found.");
     }
     if (hadErrors || strictFailure) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long diagnostic list would be cut off.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/dev-lock.ts

@@ -1,8 +1,11 @@
 import {
   existsSync,
+  linkSync,
   mkdirSync,
   readFileSync,
+  renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 
@@ -29,6 +32,83 @@ export interface DevLockInfo {
 
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
+/** The mutex a process holds while it clears a stale lock. */
+const reapPath = (outDir: string): string => join(outDir, "dev.lock.reap");
+
+/**
+ * How long a lock file that doesn't parse counts as one being written right
+ * now. Blume creates a lock with its whole content in place (see
+ * {@link createExclusive}), but one left empty or cut off — by a crash, or by
+ * an older Blume that opened the file before writing it — would otherwise
+ * read as stale the instant it appears. Past this age it's debris.
+ */
+const PARTIAL_LOCK_GRACE_MS = 2000;
+
+/** Pause between claim attempts while another process is mid-claim. */
+const RETRY_DELAY_MS = 5;
+
+const pause = (ms: number): void => {
+  // A synchronous sleep: the claim is synchronous, and what it waits on is
+  // another process, so there's nothing in this one to yield to.
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/** Per-process counter that keeps concurrent temp file names apart. */
+let tempSequence = 0;
+
+/** A private sibling of `path` to stage a write in. */
+const tempPath = (path: string): string => {
+  tempSequence += 1;
+  return `${path}.${process.pid}.${tempSequence}.tmp`;
+};
+
+/**
+ * Create `path` holding `payload`, atomically and exclusively. The payload
+ * goes to a private temp file first, which is then hard-linked into place:
+ * the link fails when `path` exists, exactly like a `wx` open, but the file
+ * appears with its whole content — no reader ever sees it empty or half
+ * written. Returns false when `path` already exists.
+ */
+const createExclusive = (path: string, payload: string): boolean => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  try {
+    linkSync(temp, path);
+    return true;
+  } catch (error) {
+    // SAFETY: `linkSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    return false;
+  } finally {
+    rmSync(temp, { force: true });
+  }
+};
+
+/** Replace `path` with `payload` in one step, so readers see old or new. */
+const replaceFile = (path: string, payload: string): void => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  renameSync(temp, path);
+};
+
+/** A file's text, or null when it doesn't exist (anymore). */
+const readIfExists = (
+  path: string
+): { raw: string; mtimeMs: number } | null => {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return { mtimeMs: statSync(path).mtimeMs, raw };
+  } catch (error) {
+    // SAFETY: `readFileSync`/`statSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+    return null;
+  }
+};
+
 /** What `JSON.parse` can yield for a lock file body. */
 type LockFileValue =
   | string
@@ -85,17 +165,44 @@ const isProcessAlive = (pid: number): boolean => {
   }
 };
 
+/** What the lock file on a dir says, read once. */
+type LockState =
+  | { kind: "absent" }
+  /** Unparseable but brand new: another process is writing it right now. */
+  | { kind: "busy" }
+  | { kind: "live"; lock: DevLockInfo }
+  /** A dead holder's lock, or unparseable debris. */
+  | { kind: "stale" };
+
+const inspectLock = (outDir: string): LockState => {
+  const file = readIfExists(lockPath(outDir));
+  if (!file) {
+    return { kind: "absent" };
+  }
+  const lock = parseLock(file.raw);
+  if (!lock) {
+    return Date.now() - file.mtimeMs < PARTIAL_LOCK_GRACE_MS
+      ? { kind: "busy" }
+      : { kind: "stale" };
+  }
+  return isProcessAlive(lock.pid) ? { kind: "live", lock } : { kind: "stale" };
+};
+
+/**
+ * Whether this process may clear the lock to claim the dir: a dead holder's
+ * lock and debris, or this process's own leftover.
+ */
+const isClaimable = (state: LockState): boolean =>
+  state.kind === "stale" ||
+  (state.kind === "live" && state.lock.pid === process.pid);
+
 /**
  * Read the lock on `outDir` held by a live `blume dev`, or null. A lock left
  * by a process that has since exited (stale) is treated as absent.
  */
 export const readDevLock = (outDir: string): DevLockInfo | null => {
-  const path = lockPath(outDir);
-  if (!existsSync(path)) {
-    return null;
-  }
-  const lock = parseLock(readFileSync(path, "utf-8"));
-  return lock && isProcessAlive(lock.pid) ? lock : null;
+  const state = inspectLock(outDir);
+  return state.kind === "live" ? state.lock : null;
 };
 
 /** Whether another live `blume dev` holds the lock on `outDir`. */
@@ -110,10 +217,6 @@ const lockPayload = (port?: number): string => {
   return JSON.stringify(info);
 };
 
-const writeLock = (outDir: string, port?: number): void => {
-  writeFileSync(lockPath(outDir), lockPayload(port));
-};
-
 /** Thrown when another live `blume dev` already holds the lock. */
 export class DevLockHeldError extends Error {
   readonly lock: DevLockInfo;
@@ -138,43 +241,58 @@ const ownsLock = (outDir: string): boolean => {
 };
 
 /**
- * One atomic claim attempt. Returns `true` when this process wins the `wx`
- * write, `false` when the dir held a stale or our-own leftover lock (now
- * cleared, so the caller should retry). Throws {@link DevLockHeldError} when a
- * live foreign holder owns the dir.
+ * Clear a claimable lock without racing anyone else doing the same. Two
+ * processes can both read the same stale lock; if each simply deleted the
+ * file, the slower one could delete the lock the faster one had claimed in
+ * between, and both would win. So removing a lock takes the reap mutex
+ * (created the same atomic way), and whoever holds it reads the lock again
+ * first: a live lock claimed since is left alone. A mutex whose holder died
+ * mid-reap is cleared for the next attempt.
  */
-const tryClaimLock = (outDir: string, port?: number): boolean => {
-  try {
-    writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
-    return true;
-  } catch (error) {
-    // SAFETY: `writeFileSync` failures are errno exceptions.
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-      throw error;
+const reapStaleLock = (outDir: string): void => {
+  const mutex = reapPath(outDir);
+  if (!createExclusive(mutex, lockPayload())) {
+    const holder = readIfExists(mutex);
+    const pid = holder ? parseLock(holder.raw)?.pid : undefined;
+    if (pid !== undefined && pid !== process.pid && isProcessAlive(pid)) {
+      pause(RETRY_DELAY_MS);
+    } else if (holder) {
+      rmSync(mutex, { force: true });
     }
-    const existing = readDevLock(outDir);
-    if (existing && existing.pid !== process.pid) {
-      throw new DevLockHeldError(existing);
+    return;
+  }
+  try {
+    if (isClaimable(inspectLock(outDir))) {
+      rmSync(lockPath(outDir), { force: true });
     }
-    // Stale or our own leftover: clear it and race for the claim again.
-    rmSync(lockPath(outDir), { force: true });
-    return false;
+  } finally {
+    rmSync(mutex, { force: true });
   }
 };
 
 /**
  * Write the current process's dev lock into `outDir` and return a release
- * function. The claim is atomic (`wx`): two `blume dev` processes racing the
- * same dir can't both pass a check-then-write — the loser gets a
- * {@link DevLockHeldError} naming the live holder. A stale lock (dead pid) or
- * this process's own leftover is cleared and re-claimed. The release only
- * removes the file if it's still ours, so a newer dev server's lock is never
- * clobbered.
+ * function. Two `blume dev` processes starting at the same moment can't both
+ * win: the lock appears whole and exclusively (a hard link, which fails when
+ * the file exists), a lock still being written is waited on rather than read
+ * as stale, and a stale lock (dead pid) or this process's own leftover is only
+ * cleared under the reap mutex — the loser gets a {@link DevLockHeldError}
+ * naming the live holder. 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, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  while (!tryClaimLock(outDir, port)) {
-    // Retry until we win the claim or a live holder makes us throw.
+  const payload = lockPayload(port);
+  while (!createExclusive(lockPath(outDir), payload)) {
+    const state = inspectLock(outDir);
+    if (isClaimable(state)) {
+      reapStaleLock(outDir);
+    } else if (state.kind === "live") {
+      throw new DevLockHeldError(state.lock);
+    } else if (state.kind === "busy") {
+      pause(RETRY_DELAY_MS);
+    }
+    // "absent": the holder released it just now — race for the claim again.
   }
   let released = false;
   return () => {
@@ -199,7 +317,9 @@ export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
  */
 export const updateDevLockPort = (outDir: string, port: number): void => {
   if (ownsLock(outDir)) {
-    writeLock(outDir, port);
+    // Replaced in one step: rewriting in place would leave a moment where a
+    // concurrent claim reads an empty lock.
+    replaceFile(lockPath(outDir), lockPayload(port));
   }
 };
 

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