alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Cli/checkVersion.ts

@@ -1,21 +1,22 @@
 import { AlchemyContext } from "alchemy/AlchemyContext";
 import * as Clock from "effect/Clock";
-import * as Console from "effect/Console";
+import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as FileSystem from "effect/FileSystem";
 import * as HttpClient from "effect/http/HttpClient";
 import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as SemVer from "effect/SemVer";
 import packageJson from "../../package.json" with { type: "json" };
-import {
-  ANSI_RESET,
-  ansiFg,
-  colorsEnabled,
-  glyphsFor,
-  theme,
-  unicodeEnabled,
-} from "./CliKit/index.ts";
+
+export class CheckVersionUnexpectedResponse extends Data.TaggedError(
+  "CheckVersionUnexpectedResponse",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
 
 const NPM_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/alchemy/dist-tags";
 
@@ -31,61 +32,14 @@ interface VersionCheckCache {
   distTags?: Record<string, string>;
 }
 
-const parseVersion = (v: string) => {
-  const [core = "", pre] = v.split("-", 2);
-  return {
-    core: core.split(".").map(Number),
-    pre: pre === undefined ? [] : pre.split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id)),
-  };
-};
-
 /**
- * Semver precedence (semver.org §11): negative when a < b, positive when
- * a > b. Enough of the spec for registry versions — numeric core, dotted
- * prerelease identifiers, release > prerelease.
+ * Semver precedence: negative when a < b, positive when a > b. Versions that
+ * don't parse compare equal, so they never trigger an upgrade notice.
  */
 const compareVersions = (a: string, b: string): number => {
-  const pa = parseVersion(a);
-  const pb = parseVersion(b);
-  for (let i = 0; i < 3; i++) {
-    const d = (pa.core[i] ?? 0) - (pb.core[i] ?? 0);
-    if (d !== 0) return d;
-  }
-  // A release outranks any prerelease of the same core.
-  if (pa.pre.length === 0 || pb.pre.length === 0) {
-    return pb.pre.length - pa.pre.length;
-  }
-  for (let i = 0; i < Math.max(pa.pre.length, pb.pre.length); i++) {
-    const x = pa.pre[i];
-    const y = pb.pre[i];
-    if (x === undefined) return -1;
-    if (y === undefined) return 1;
-    if (x === y) continue;
-    if (typeof x === "number" && typeof y === "number") return x - y;
-    // Numeric identifiers rank below alphanumeric ones.
-    if (typeof x === "number") return -1;
-    if (typeof y === "number") return 1;
-    return x < y ? -1 : 1;
-  }
-  return 0;
-};
-
-/**
- * Pick the dist-tag matching the current channel. For pre-release versions
- * like `2.0.0-beta.33`, we match the prerelease identifier (`beta`, `next`,
- * etc.), falling back through `next` → `latest`. Because our releases can
- * force prereleases onto `latest`, it may run ahead of the channel tag —
- * in that case offer `latest` instead of the channel pick.
- */
-const pickDistTag = (current: string, distTags: Record<string, string>): string | undefined => {
-  const pre = current.split("-", 2)[1];
-  if (!pre) return distTags.latest;
-  const id = pre.split(".")[0];
-  const channelPick = (id && distTags[id]) || distTags.next;
-  const { latest } = distTags;
-  if (channelPick === undefined) return latest;
-  if (latest === undefined) return channelPick;
-  return compareVersions(latest, channelPick) > 0 ? latest : channelPick;
+  const pa = Result.getOrUndefined(SemVer.parse(a));
+  const pb = Result.getOrUndefined(SemVer.parse(b));
+  return pa === undefined || pb === undefined ? 0 : SemVer.Order(pa, pb);
 };
 
 const readCache = Effect.fn(
@@ -113,7 +67,7 @@ const fetchDistTags = Effect.gen(function* () {
   const response = yield* http.get(NPM_DIST_TAGS_URL);
   const distTags = (yield* response.json) as Record<string, string> | null;
   if (typeof distTags !== "object" || distTags === null) {
-    return yield* Effect.fail(new Error("malformed dist-tags response"));
+    return yield* new CheckVersionUnexpectedResponse({ message: "malformed dist-tags response" });
   }
   return distTags;
 });
@@ -142,8 +96,7 @@ const refreshDistTags = Effect.fn(function* (cachePath: string) {
 });
 
 /**
- * Warn if a newer `alchemy` version is published on the dist-tag matching
- * the current channel. Runs to completion before any interactive prompts so
+ * Warn if a newer `alchemy` version is published on the `latest` dist-tag. Runs to completion before any interactive prompts so
  * the warning never interleaves with prompt rendering, and is bounded so it
  * can never stall the CLI: dist-tags are cached in
  * `.alchemy/version-check.json` for a day (failed attempts included), so at
@@ -164,27 +117,21 @@ export const checkLatestVersion = Effect.gen(function* () {
   if (distTags === undefined) return;
 
   const current = packageJson.version;
-  const latest = pickDistTag(current, distTags);
-  // Strictly newer only: a dist-tag pointing at (or behind) the installed
-  // version — e.g. a stale `next` after a force-latest release — must not
-  // prompt a "downgrade".
+  const { latest } = distTags;
+  // Strictly newer only: `latest` at (or behind) the installed version must
+  // not prompt a "downgrade".
   if (latest === undefined || compareVersions(latest, current) <= 0) return;
 
   const installCmd =
     typeof process !== "undefined" && process.versions.bun !== undefined
       ? `bun add alchemy@${latest}`
       : `pnpm add alchemy@${latest}`;
-  // Print via the Console service, not Effect.logWarning: this is a
-  // user-facing notice, not a log record, so it should reach the terminal
-  // regardless of the installed loggers or the configured log floor.
-  const useColor = colorsEnabled();
-  const glyphs = glyphsFor(unicodeEnabled());
-  const message =
-    `alchemy ${latest} is available (you're on ${current}). ` + `Run \`${installCmd}\` to upgrade.`;
-  yield* Console.warn(
-    useColor ? `${ansiFg(theme.color.warning)}${glyphs.warning} ${message}${ANSI_RESET}` : message,
+  // A warning record: above the default console floor, and a JSON record
+  // under --log-format json (commands run this check, after the flags parse).
+  yield* Effect.logWarning(
+    `alchemy ${latest} is available (you're on ${current}). Run \`${installCmd}\` to upgrade.`,
   );
 }).pipe(Effect.ignore);
 
 // Exported for tests.
-export const _internal = { pickDistTag, compareVersions };
+export const _internal = { compareVersions };

package/src/Cli/commands/confirm.ts

@@ -1,7 +1,7 @@
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Runtime from "effect/Runtime";
-import * as CliKit from "../CliKit/index.ts";
+import * as Interaction from "../../Interaction.ts";
 import { exitDeclined } from "./errors.ts";
 
 /**
@@ -31,14 +31,14 @@ export const confirmOrDecline = Effect.fn(function* (options: {
   readonly abortMessage?: string;
 }) {
   if (options.yes) return;
-  const approved = yield* CliKit.accessors.prompt.confirm({
+  const approved = yield* Interaction.confirm({
     message: options.message,
     initialValue: false,
     confirmLabel: options.confirmLabel,
     cancelLabel: options.cancelLabel,
   });
   if (approved) return;
-  yield* CliKit.accessors.output.info(options.abortMessage ?? "Aborted.");
+  yield* Interaction.info(options.abortMessage ?? "Aborted.");
   yield* exitDeclined;
   return yield* new ConfirmationDeclined();
 });

package/src/Cli/commands/deploy.ts

@@ -2,10 +2,10 @@ import * as Command from "effect/cli/Command";
 import * as Flag from "effect/cli/Flag";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import * as Drift from "../../Alchemist/routes/drift.ts";
-import * as Stacks from "../../Alchemist/routes/stack.ts";
+import * as Alchemist from "../../Alchemist/index.ts";
+import * as Interaction from "../../Interaction.ts";
 import { Cli } from "../../Report.ts";
-import * as CliKit from "../CliKit/index.ts";
+import { renderApply } from "../../Report.ts";
 import { planDecisionScreen } from "../components/view/PlanDecision.tsx";
 import { stackOutputsView } from "../components/view/StackOutputs.tsx";
 import { exitDeclined } from "./errors.ts";
@@ -24,7 +24,7 @@ import {
   yes,
 } from "./flags.ts";
 import { instrumentCommand } from "./instrument.ts";
-import { renderApply, renderPlanning } from "./render.ts";
+import { renderPlanning } from "./render.ts";
 
 interface StackCommandOptions {
   readonly main: string;
@@ -72,41 +72,42 @@ const detectDrift = Flag.Boolean("detect-drift").pipe(
   Flag.withDefault(false),
 );
 
-const detectAndMaybeRepairDrift = Effect.fn(function* (
-  target: Stacks.StackTarget,
+const detectAndMaybeRepairDrift = Effect.fn(function* <E, R>(
+  scanDrift: Effect.Effect<Alchemist.Drift.DriftScan, E, R>,
   options: {
+    readonly stage: string;
     readonly yes?: boolean;
     readonly detailed?: boolean;
     readonly dryRun?: boolean;
   },
 ) {
   const cli = yield* Cli;
-  const snapshot = yield* Drift.inspect(target).pipe(
+  const snapshot = yield* scanDrift.pipe(
     renderPlanning({
       operation: "Drift",
-      stage: target.stage,
+      stage: options.stage,
       computingLabel: "Checking drift",
       readyLabel: "Drift check complete",
     }),
   );
-  if (!Drift.hasDrift(snapshot)) return true;
+  if (!Alchemist.Drift.hasDrift(snapshot)) return true;
 
   if (options.dryRun) {
-    yield* cli.displayPlan(snapshot.repairPlan.native, {
+    yield* cli.displayPlan(snapshot.native, {
       detailed: options.detailed,
-      stage: target.stage,
+      stage: options.stage,
     });
     return true;
   }
 
   let decision: "repair" | "deploy" | "cancel" = options.yes ? "repair" : "cancel";
   if (!options.yes) {
-    const terminal = yield* CliKit.CliKit;
+    const terminal = yield* Interaction.Interaction;
     if (terminal.terminal.input) {
       decision = yield* terminal.prompt
-        .custom(
+        .screen(
           planDecisionScreen({
-            plan: snapshot.repairPlan.native,
+            plan: snapshot.native,
             message: "Drift detected",
             choices: [
               {
@@ -127,21 +128,21 @@ const detectAndMaybeRepairDrift = Effect.fn(function* (
         )
         .pipe(Effect.catchTag("TerminalCancelled", () => Effect.succeed("cancel" as const)));
     } else {
-      yield* cli.displayPlan(snapshot.repairPlan.native, {
+      yield* cli.displayPlan(snapshot.native, {
         detailed: options.detailed,
-        stage: target.stage,
+        stage: options.stage,
       });
-      yield* CliKit.accessors.output.warning(
+      yield* Interaction.warning(
         "Drift detected in a non-interactive terminal. Re-run with --yes to repair and deploy.",
       );
     }
   }
 
   if (decision === "repair") {
-    yield* Drift.repair(snapshot).pipe(
-      renderApply(snapshot.repairPlan.native, {
+    yield* Alchemist.Drift.execute(snapshot).pipe(
+      renderApply(snapshot.native, {
         detailed: options.detailed,
-        stage: target.stage,
+        stage: options.stage,
       }),
     );
   }
@@ -152,12 +153,14 @@ const runStack = Effect.fn(function* (options: StackCommandOptions) {
   yield* validateSelectionOptions(options);
   const cli = yield* Cli;
   const display = { detailed: options.detailed, stage: options.stage };
-  const target = {
-    entrypoint: options.main,
+  const buildOptions = {
     stage: options.stage,
     profile: options.profile,
     envFile: Option.getOrUndefined(options.envFile),
+    adopt: options.adopt,
+    updateStateStore: options.yes,
   };
+  const stack = Alchemist.importStack(options.main);
 
   const operation = options.destroy ? "Destroy" : options.dryRun ? "Plan" : "Deploy";
   const withPlanningProgress = renderPlanning({
@@ -166,48 +169,54 @@ const runStack = Effect.fn(function* (options: StackCommandOptions) {
   });
 
   if (options.detectDrift && !options.destroy) {
-    const proceed = yield* detectAndMaybeRepairDrift(target, options);
+    // The drift check closes its build before the deploy builds again: a
+    // remote state store holds one lease per stage per build.
+    const proceed = yield* detectAndMaybeRepairDrift(
+      Effect.flatMap(stack, (stack) => Alchemist.Drift.scan({ ...buildOptions, stack })),
+      options,
+    ).pipe(Effect.scoped);
     if (!proceed) {
-      yield* CliKit.accessors.output.info("Deploy aborted: drift was detected and not approved.");
+      yield* Interaction.info("Deploy aborted: drift was detected and not approved.");
       return yield* exitDeclined;
     }
   }
 
-  const snapshot = yield* Stacks.plan({
-    target,
-    operation: options.destroy ? "destroy" : "deploy",
-    force: options.force,
-    include: options.include,
-    exclude: options.exclude,
-    adopt: options.adopt,
-    updateStateStore: options.yes,
-  }).pipe(withPlanningProgress);
+  const snapshot = yield* Effect.flatMap(stack, (stack) =>
+    Alchemist.plan(
+      options.destroy
+        ? { ...buildOptions, stack, operation: "destroy" }
+        : {
+            ...buildOptions,
+            stack,
+            operation: "deploy",
+            force: options.force,
+            include: options.include,
+            exclude: options.exclude,
+          },
+    ),
+  ).pipe(withPlanningProgress);
 
   if (options.dryRun) {
     return yield* cli.displayPlan(snapshot.native, display);
   }
 
-  if (!options.yes && Stacks.hasChanges(snapshot.summary)) {
+  if (!options.yes && Alchemist.hasChanges(snapshot)) {
     const approved = yield* cli.approvePlan(snapshot.native, display).pipe(
       Effect.tap((approved) =>
-        approved
-          ? Effect.void
-          : CliKit.accessors.output.info(`${operation} aborted: plan declined.`),
+        approved ? Effect.void : Interaction.info(`${operation} aborted: plan declined.`),
       ),
       Effect.catchTag("NonInteractiveTerminal", () =>
-        CliKit.accessors.output
-          .warning(
-            `Cannot prompt for approval in a non-interactive terminal. Nothing was changed — re-run with --yes to ${operation.toLowerCase()}.`,
-          )
-          .pipe(Effect.as(false)),
+        Interaction.warning(
+          `Cannot prompt for approval in a non-interactive terminal. Nothing was changed — re-run with --yes to ${operation.toLowerCase()}.`,
+        ).pipe(Effect.as(false)),
       ),
     );
     if (!approved) return yield* exitDeclined;
   }
 
-  const result = yield* Stacks.apply(snapshot).pipe(renderApply(snapshot.native, display));
+  const result = yield* Alchemist.apply(snapshot).pipe(renderApply(snapshot.native, display));
   if (result !== undefined) {
-    const kit = yield* CliKit.CliKit;
+    const kit = yield* Interaction.Interaction;
     yield* kit.output.print(stackOutputsView(result));
   }
 });

package/src/Cli/commands/dev.ts

@@ -1,15 +1,22 @@
 import { fileURLToPath } from "node:url";
 import * as Command from "effect/cli/Command";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { resolveStackEntrypoint } from "../../Alchemist/Entrypoint.ts";
 import * as Contributions from "../../Contributions.ts";
 import { SPAWNER_URL_ENV_KEY } from "../../Local/RpcProviderProxy.ts";
 import * as RpcSpawner from "../../Local/RpcSpawner.ts";
+import { LOG_FD_ENV, parseRecord, replayRecord } from "../../Util/LogRecord.ts";
 import { nodeLoaderArgs } from "../../Util/Node.ts";
+import { timedShutdownStep } from "../../Util/Shutdown.ts";
+import { traceParentEnv } from "../../Util/TraceParent.ts";
 import { DEV_RELOAD_EXIT_CODE, DevOptions } from "../DevOptions.ts";
+import { consoleSettingsEnv, currentConsoleSettings, RunLog } from "../GlobalLog.ts";
 import { suppressInterruptMessages } from "./errors.ts";
 import {
   configPath,
@@ -22,6 +29,7 @@ import {
   profile,
   resolveStackArgs,
 } from "./flags.ts";
+import { logCommandFailure, VersionCheck } from "./instrument.ts";
 
 /**
  * Trust the Floci emulator CA in `alchemy dev` so cross-cloud data planes
@@ -96,6 +104,10 @@ export const devCommand = Command.make(
           entry,
         ];
       }
+      const runLog = yield* RunLog;
+      const consoleSettings = yield* currentConsoleSettings;
+      // The child's records and spans join this command's trace.
+      const traceEnv = yield* traceParentEnv;
       const runChild = ChildProcess.make(command[0], command.slice(1), {
         stdin: "inherit",
         stdout: "inherit",
@@ -103,17 +115,60 @@ export const devCommand = Command.make(
         env: {
           ALCHEMY_EXEC_OPTIONS: JSON.stringify(options),
           ALCHEMY_DEV: "true",
+          [LOG_FD_ENV]: "3",
+          // The exec child renders the run's logs but never sees this argv.
+          ...consoleSettingsEnv(consoleSettings),
           ...(process.env.NODE_EXTRA_CA_CERTS
             ? { NODE_EXTRA_CA_CERTS: process.env.NODE_EXTRA_CA_CERTS }
             : {}),
           [SPAWNER_URL_ENV_KEY]: spawner.url,
+          ...traceEnv,
         },
         extendEnv: true,
         // Same process group as this supervisor: the exec child owns the
         // terminal (TUI stdin), so the tty's Ctrl+C must reach it directly.
         detached: false,
+        // The child's log records, for the run log this process writes.
+        additionalFds: { fd3: { type: "output" } },
       }).pipe(
-        Effect.flatMap((child) => child.exitCode),
+        Effect.flatMap((child) =>
+          Effect.gen(function* () {
+            const records = yield* child.getOutputFd(3).pipe(
+              Stream.decodeText(),
+              Stream.splitLines,
+              // Already rendered by the child: into the run log only. A line
+              // that doesn't decode is skipped, never ends the reader.
+              Stream.runForEach((line) => {
+                const record = parseRecord(line);
+                return record === undefined
+                  ? Effect.void
+                  : replayRecord(record).pipe(
+                      Effect.provideService(Logger.CurrentLoggers, new Set([runLog])),
+                    );
+              }),
+              Effect.ignore,
+              Effect.forkScoped,
+            );
+            // The pipe closes with the child: take its last records before
+            // this scope (and the reader with it) closes.
+            const drain = Fiber.join(records).pipe(Effect.timeout("2 seconds"), Effect.ignore);
+            const code = yield* child.exitCode.pipe(
+              // Ctrl+C reaches the child too (same process group): let it
+              // finish its own shutdown and report it before this scope
+              // kills whatever is left.
+              Effect.onInterrupt(() =>
+                child.exitCode.pipe(
+                  Effect.timeout("5 seconds"),
+                  Effect.ignore,
+                  Effect.andThen(drain),
+                  timedShutdownStep("stopped exec child"),
+                ),
+              ),
+            );
+            yield* drain;
+            return code;
+          }),
+        ),
         Effect.scoped,
       );
       // Each child gets its own scope so a reload exit releases the old
@@ -124,11 +179,14 @@ export const devCommand = Command.make(
       });
     },
     (effect, args) =>
-      Effect.provide(
-        RpcSpawner.layerServer({
-          profile: args.profile,
-          envFile: Option.getOrUndefined(args.envFile),
-        }),
-      )(effect),
+      Effect.andThen(
+        Effect.flatten(VersionCheck),
+        Effect.provide(
+          RpcSpawner.layerServer({
+            profile: args.profile,
+            envFile: Option.getOrUndefined(args.envFile),
+          }),
+        )(effect),
+      ).pipe(logCommandFailure),
   ),
 ).pipe(Command.withDescription("Develop a stack with live reload"));

package/src/Cli/commands/drift.ts

@@ -2,13 +2,14 @@ import * as Command from "effect/cli/Command";
 import * as Flag from "effect/cli/Flag";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import * as Drift from "../../Alchemist/routes/drift.ts";
+import * as Alchemist from "../../Alchemist/index.ts";
+import * as Interaction from "../../Interaction.ts";
 import { Cli } from "../../Report.ts";
-import * as CliKit from "../CliKit/index.ts";
+import { renderApply } from "../../Report.ts";
 import { planDecisionScreen } from "../components/view/PlanDecision.tsx";
 import { config, envFile, profile, resolveStage, stage } from "./flags.ts";
 import { instrumentCommand } from "./instrument.ts";
-import { renderApply, renderPlanning } from "./render.ts";
+import { renderPlanning } from "./render.ts";
 
 const repairFlag = Flag.Boolean("repair").pipe(
   Flag.withDescription("Repair detected drift without prompting"),
@@ -31,12 +32,15 @@ const routeDrift = Effect.fn(function* ({
   repair = false,
 }: SyncArgs) {
   const cli = yield* Cli;
-  const snapshot = yield* Drift.inspect({
-    entrypoint: main,
-    stage,
-    profile,
-    envFile: Option.getOrUndefined(envFile),
-  }).pipe(
+  const snapshot = yield* Alchemist.importStack(main).pipe(
+    Effect.flatMap((stack) =>
+      Alchemist.Drift.scan({
+        stack,
+        stage,
+        profile,
+        envFile: Option.getOrUndefined(envFile),
+      }),
+    ),
     renderPlanning({
       operation: "Drift",
       stage,
@@ -44,19 +48,19 @@ const routeDrift = Effect.fn(function* ({
       readyLabel: "Drift check complete",
     }),
   );
-  if (!Drift.hasDrift(snapshot)) {
-    return yield* cli.displayPlan(snapshot.repairPlan.native);
+  if (!Alchemist.Drift.hasDrift(snapshot)) {
+    return yield* cli.displayPlan(snapshot.native);
   }
 
   if (!repair) {
-    const terminal = yield* CliKit.CliKit;
+    const terminal = yield* Interaction.Interaction;
     if (!terminal.terminal.input) {
-      return yield* cli.displayPlan(snapshot.repairPlan.native);
+      return yield* cli.displayPlan(snapshot.native);
     }
     const decision = yield* terminal.prompt
-      .custom(
+      .screen(
         planDecisionScreen({
-          plan: snapshot.repairPlan.native,
+          plan: snapshot.native,
           message: "Drift detected",
           choices: [
             {
@@ -75,7 +79,7 @@ const routeDrift = Effect.fn(function* ({
     if (decision === "cancel") return;
   }
 
-  yield* Drift.repair(snapshot).pipe(renderApply(snapshot.repairPlan.native));
+  yield* Alchemist.Drift.execute(snapshot).pipe(renderApply(snapshot.native));
 });
 
 export const driftCommand = Command.make(

package/src/Cli/commands/errors.ts

@@ -11,10 +11,9 @@ import {
   ANSI_RESET,
   ansiFg,
   colorsEnabled,
-  glyphsFor,
-  theme,
   unicodeEnabled,
-} from "../CliKit/index.ts";
+} from "../../Util/Terminal.ts";
+import { glyphsFor, theme } from "../../Util/Theme.ts";
 
 const isTerminalCancelled = Schema.is(
   Schema.Struct({ _tag: Schema.Literals(["TerminalCancelled"]) }),

package/src/Cli/commands/instrument.ts

@@ -1,13 +1,41 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import { routeCacheLayer } from "../../Alchemist/Session.ts";
+import { identity } from "effect/Function";
+import { authRegistryLayer } from "../../Alchemist/AuthRegistry.ts";
 import { recordCli } from "../../Telemetry/Metrics.ts";
+import { globalLogs } from "../../Util/LogRecord.ts";
 
 /**
- * Wraps a command handler as one traced, metered unit that is also one
- * route-cache scope: the stack sessions and auth registries its routes open
- * are memoized for the command's duration (`routeCacheLayer`). Commands that
- * never open a session (`dev`, which only supervises the exec child) stay
- * off this wrapper and therefore never load `Alchemist/Session`.
+ * Commands about the account, not a project: their logs go to the global run
+ * log (`~/.alchemy/logs`), so running one outside a project creates nothing
+ * there.
+ */
+const isGlobalCommand = (command: string) =>
+  /^(profile|provider)(\.|$)/.test(command) ||
+  command === "state.bootstrap" ||
+  command === "state.teardown";
+
+/**
+ * The terminal shows a failed command's friendly message; this keeps its
+ * full cause chain in the command's run log.
+ */
+export const logCommandFailure = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.tapCause(effect, (cause) => Effect.logDebug(`command failed:\n${Cause.pretty(cause)}`));
+
+/**
+ * The pre-command version check. The CLI entrypoint sets it with its
+ * services already provided; elsewhere (tests, the API) it does nothing.
+ */
+export const VersionCheck = Context.Reference<Effect.Effect<void>>("alchemy/Cli/VersionCheck", {
+  defaultValue: () => Effect.void,
+});
+
+/**
+ * Wraps a command handler as one traced, metered unit. A best-effort check
+ * for a newer published version runs first, so its warning prints before
+ * any interactive prompt; it is cached for a day and bounded by a short
+ * timeout, so this stays fast.
  */
 export const instrumentCommand =
   <AttrsArgs = unknown>(command: string, attrs?: (args: AttrsArgs) => Record<string, unknown>) =>
@@ -15,10 +43,13 @@ export const instrumentCommand =
     handler: (args: Args) => Effect.Effect<A, E, R>,
   ): ((args: Args) => Effect.Effect<A, E, R>) =>
   (args) =>
-    handler(args).pipe(
+    Effect.andThen(Effect.flatten(VersionCheck), handler(args)).pipe(
       Effect.withSpan(`cli.${command}`, {
         attributes: attrs ? attrs(args) : {},
       }),
       recordCli(command),
-      Effect.provide(routeCacheLayer),
+      logCommandFailure,
+      isGlobalCommand(command) ? globalLogs : identity,
+      // Auth registries are memoized for the command's duration.
+      Effect.provide(authRegistryLayer),
     );