alchemy 2.0.0-beta.76 → 2.0.0-beta.77

package/src/Cli/components/view/statusStyle.ts

@@ -0,0 +1,97 @@
+/**
+ * The one mapping from plan actions / apply statuses to brand colors and
+ * icons — shared by the plan tree, the live progress view, and the plain
+ * logging CLI so an action never renders two different hues.
+ */
+import type { ApplyStatus } from "../../../Report.ts";
+import { theme, type GlyphName } from "../../CliKit/index.ts";
+
+/** Every verb a plan row can carry (resource CRUD + namespace/action rollups). */
+export type PlanAction =
+  | "create"
+  | "update"
+  | "adopted"
+  | "delete"
+  | "orphaned"
+  | "replace"
+  | "noop"
+  | "mixed"
+  | "run";
+
+export const actionStyle: Record<
+  PlanAction,
+  { readonly color: string; readonly icon: GlyphName }
+> = {
+  create: { color: theme.color.success, icon: "add" },
+  update: { color: theme.color.warning, icon: "edit" },
+  adopted: { color: theme.color.magenta, icon: "adopt" },
+  delete: { color: theme.color.danger, icon: "delete" },
+  orphaned: { color: theme.color.coral, icon: "orphan" },
+  replace: { color: theme.color.magenta, icon: "replace" },
+  noop: { color: theme.color.muted, icon: "bullet" },
+  mixed: { color: theme.color.info, icon: "info" },
+  run: { color: theme.color.info, icon: "run" },
+};
+
+export const applyStatusColor = (
+  status: ApplyStatus | "no change",
+): string | undefined => {
+  switch (status) {
+    case "no change":
+    case "pending":
+    case "skipped":
+      return theme.color.muted;
+    case "attaching":
+    case "post-attach":
+    case "pre-creating":
+      return theme.color.info;
+    case "creating":
+    case "creating replacement":
+    case "created":
+    case "orphaning":
+    case "orphaned":
+      return theme.color.success;
+    case "updating":
+    case "adopting":
+    case "replacing":
+    case "replaced":
+    case "updated":
+    case "adopted":
+      return theme.color.warning;
+    case "deleting":
+    case "deleted":
+      return theme.color.danger;
+    case "running":
+    case "ran":
+      return theme.color.info;
+    case "fail":
+      return theme.color.danger;
+    default:
+      return undefined;
+  }
+};
+
+/** Settled states — the row will not change again. */
+export const isTerminalStatus = (status: ApplyStatus): boolean =>
+  status === "created" ||
+  status === "updated" ||
+  status === "adopted" ||
+  status === "deleted" ||
+  status === "orphaned" ||
+  status === "replaced" ||
+  status === "ran" ||
+  status === "skipped" ||
+  status === "fail";
+
+export const isInProgress = (status: ApplyStatus): boolean =>
+  status === "attaching" ||
+  status === "post-attach" ||
+  status === "pre-creating" ||
+  status === "creating" ||
+  status === "creating replacement" ||
+  status === "updating" ||
+  status === "adopting" ||
+  status === "deleting" ||
+  status === "orphaning" ||
+  status === "replacing" ||
+  status === "running";

package/src/Cli/components/view/usePlanPresentation.ts

@@ -0,0 +1,82 @@
+import {
+  measureElement,
+  useProgress,
+  useTitle,
+  type DOMElement,
+} from "@alchemy.run/sigil";
+import { useLayoutEffect, useRef, useState } from "react";
+import { useTerminalSize } from "../ui/index.ts";
+import type { PlanTree, PlanTreeState } from "./PlanTree.ts";
+
+export const usePlanPresentation = (options: {
+  readonly tree: PlanTree;
+  readonly state: PlanTreeState;
+  readonly busy: boolean;
+  readonly collapsible: boolean;
+  readonly hasFooter: boolean;
+}) => {
+  const { tree, state, busy, collapsible, hasFooter } = options;
+  const { mode } = tree;
+  const { label, expanded, viewport, outcome } = state;
+  const { completed, failures, total } = tree.progress();
+  const collapsed = collapsible && !expanded;
+  const settled = !busy && completed >= total;
+
+  useProgress(
+    mode === "apply"
+      ? {
+          state:
+            outcome === "failure" || failures > 0
+              ? "error"
+              : busy
+                ? "normal"
+                : "inactive",
+          value: total === 0 ? undefined : (completed / total) * 100,
+        }
+      : { state: "inactive" },
+  );
+  const titleProgress = settled || total === 0 ? "" : ` ${completed}/${total}`;
+  const titleDetail = tree.titleDetail ? ` · ${tree.titleDetail}` : "";
+  useTitle(
+    mode === "apply" ? `${label}${titleProgress}${titleDetail}` : undefined,
+  );
+
+  const beforeRef = useRef<DOMElement>(null);
+  const summaryRef = useRef<DOMElement>(null);
+  const controlsRef = useRef<DOMElement>(null);
+  const afterRef = useRef<DOMElement>(null);
+  const [chromeRows, setChromeRows] = useState<number>();
+  const { rows: terminalRows } = useTerminalSize();
+  const showControls =
+    mode === "apply" || (!collapsed && (collapsible || hasFooter));
+
+  useLayoutEffect(() => {
+    if (collapsed || viewport !== "virtual") return;
+    const height = (ref: { readonly current: DOMElement | null }) =>
+      ref.current === null ? 0 : measureElement(ref.current).height;
+    const measured =
+      height(beforeRef) +
+      height(summaryRef) +
+      height(controlsRef) +
+      height(afterRef) +
+      1 +
+      (showControls ? 1 : 0);
+    setChromeRows((current) => (current === measured ? current : measured));
+  });
+
+  const lineBudget =
+    viewport === "virtual"
+      ? Math.max(
+          1,
+          terminalRows - (mode === "apply" ? 3 : 0) - (chromeRows ?? 8),
+        )
+      : Number.POSITIVE_INFINITY;
+
+  return {
+    progress: { completed, failures, total },
+    collapsed,
+    showControls,
+    lineBudget,
+    refs: { beforeRef, summaryRef, controlsRef, afterRef },
+  } as const;
+};

package/src/Cli/components/view/usePlanViewport.ts

@@ -0,0 +1,172 @@
+import { useMemo, useState } from "react";
+import { useTerminalInput } from "../ui/index.ts";
+import { stackOutputLineCount } from "./StackOutputs.tsx";
+import {
+  type PlanRow,
+  type PlanTree,
+  type PlanTreeState,
+  type PlanView,
+} from "./PlanTree.ts";
+import { isTerminalStatus } from "./statusStyle.ts";
+
+export type VirtualPlanLine =
+  | { readonly kind: "row"; readonly row: PlanRow }
+  | {
+      readonly kind: "yaml";
+      readonly key: string;
+      readonly line: string;
+      readonly paddingLeft: number;
+    }
+  | {
+      readonly kind: "note";
+      readonly key: string;
+      readonly paddingLeft: number;
+    };
+
+const planLines = (
+  rows: readonly PlanRow[],
+  detailed: boolean,
+): VirtualPlanLine[] =>
+  rows.flatMap((row): VirtualPlanLine[] => {
+    const lines: VirtualPlanLine[] = [{ kind: "row", row }];
+    if (row.type !== "resource") return lines;
+    const showYaml = detailed || row.propertyYaml?.kind === "drift";
+    if (!showYaml) return lines;
+    if (row.propertyYaml !== undefined) {
+      lines.push(
+        ...row.propertyYaml.lines.map((line, index) => ({
+          kind: "yaml" as const,
+          key: `${row.key}:yaml:${index}`,
+          line,
+          paddingLeft: row.depth * 2 + 2,
+        })),
+      );
+    } else if (
+      row.action === "update" ||
+      row.action === "adopted" ||
+      row.action === "replace"
+    ) {
+      lines.push({
+        kind: "note",
+        key: `${row.key}:note`,
+        paddingLeft: row.depth * 2 + 2,
+      });
+    }
+    return lines;
+  });
+
+export interface PlanWindow {
+  readonly selectedView: PlanView;
+  readonly hasOutput: boolean;
+  readonly virtual: boolean;
+  readonly budget: number;
+  readonly offset: number;
+  readonly hiddenBelow: number;
+  readonly planLines: readonly VirtualPlanLine[] | undefined;
+}
+
+export const usePlanViewport = (options: {
+  readonly tree: PlanTree;
+  readonly state: PlanTreeState;
+  readonly lineBudget: number;
+  readonly collapsible: boolean;
+  readonly collapsed: boolean;
+}): PlanWindow => {
+  const { tree, state, lineBudget, collapsible, collapsed } = options;
+  const { rows, detailed } = tree;
+  const { tasks, output, view, viewport } = state;
+  const hasOutput = output !== undefined;
+  const selectedView = view === "output" && hasOutput ? "output" : "plan";
+  const virtual = viewport === "virtual";
+  const expandedLines = useMemo(
+    () => planLines(rows, detailed),
+    [rows, detailed],
+  );
+  const available =
+    lineBudget === Number.POSITIVE_INFINITY
+      ? rows.length
+      : Math.max(1, Math.floor(lineBudget));
+  const length =
+    selectedView === "output"
+      ? stackOutputLineCount(output)
+      : virtual
+        ? expandedLines.length
+        : rows.length;
+  // Overflow markers render above and below the content window, so they must
+  // consume its budget rather than extending the complete widget. Reserve
+  // both even when following the end (where only the upper marker is shown),
+  // because manual scrolling can make both visible without changing height.
+  const budget =
+    virtual && length > available ? Math.max(1, available - 2) : available;
+  const maxOffset = Math.max(0, length - budget);
+  const activeRow = tree.progressRows.find((row) => {
+    const status = tasks.get(row.key)?.status;
+    return status !== undefined && !isTerminalStatus(status);
+  });
+  const activeRowIndex = activeRow === undefined ? -1 : rows.indexOf(activeRow);
+  const activeLineIndex = virtual
+    ? expandedLines.findIndex(
+        (line) => line.kind === "row" && line.row === rows[activeRowIndex],
+      )
+    : activeRowIndex;
+  const followedOffset =
+    selectedView === "output"
+      ? maxOffset
+      : Math.min(
+          maxOffset,
+          Math.max(
+            0,
+            (activeLineIndex < 0 ? length : activeLineIndex) -
+              Math.floor(budget / 3),
+          ),
+        );
+  const [manualOffsets, setManualOffsets] = useState<
+    Record<PlanView, number | undefined>
+  >({ plan: undefined, output: undefined });
+  const offset = virtual
+    ? Math.min(maxOffset, manualOffsets[selectedView] ?? followedOffset)
+    : 0;
+  const setOffset = (
+    update: (current: number | undefined) => number | undefined,
+  ) =>
+    setManualOffsets((current) => ({
+      ...current,
+      [selectedView]: update(current[selectedView]),
+    }));
+
+  useTerminalInput((input, key) => {
+    if (collapsible && !key.ctrl && !key.meta && input.toLowerCase() === "p") {
+      tree.setExpanded(collapsed);
+      return;
+    }
+    if (collapsed) return;
+    if (hasOutput && (key.left || key.right)) {
+      tree.setView(selectedView === "plan" ? "output" : "plan");
+      return;
+    }
+    if (!virtual) return;
+    const page = Math.max(1, Math.floor(lineBudget));
+    if (key.up) setOffset((current) => Math.max(0, (current ?? offset) - 1));
+    else if (key.down)
+      setOffset((current) => Math.min(maxOffset, (current ?? offset) + 1));
+    else if (key.pageUp)
+      setOffset((current) => Math.max(0, (current ?? offset) - page));
+    else if (key.pageDown)
+      setOffset((current) => Math.min(maxOffset, (current ?? offset) + page));
+    else if (key.home) setOffset(() => 0);
+    else if (key.end) setOffset(() => undefined);
+  });
+
+  return {
+    selectedView,
+    hasOutput,
+    virtual,
+    budget,
+    offset,
+    hiddenBelow: virtual ? Math.max(0, length - offset - budget) : 0,
+    planLines:
+      virtual && selectedView === "plan"
+        ? expandedLines.slice(offset, offset + budget)
+        : undefined,
+  };
+};

package/src/Cli/exec.ts

@@ -1,51 +1,297 @@
+import * as Cause from "effect/Cause";
+import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
+import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { watchImport } from "@alchemy.run/node-utils/watch-import";
+import { trackBunImports } from "@alchemy.run/node-utils/watch-import-bun";
+import { fileURLToPath } from "node:url";
 
 import { AlchemyContextLive } from "../AlchemyContext.ts";
+import { StackModuleLoader } from "../Alchemist/Session.ts";
+import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
-import { ProfileLive } from "../Auth/Profile.ts";
+import { ProfileStoreLive } from "../Auth/Profile.ts";
+import { makeDevLogOpener } from "../Local/DevLog.ts";
 import * as RpcProviderProxy from "../Local/RpcProviderProxy.ts";
 import { forwardSidecarLogs } from "../Local/RpcSpawner.ts";
+import { TelemetryLive } from "../Telemetry/Layer.ts";
+import { initialCwd } from "../Util/Node.ts";
 import { PlatformServices } from "../Util/PlatformServices.ts";
-import { execStack, ExecStackOptions } from "./commands/deploy.ts";
-import { LoggingCli } from "./LoggingCli.ts";
-import { selectCli } from "./selectCli.ts";
-
-// `alchemy dev` is a long-running session whose primary output is the log
-// stream (worker starts, cron fires, request logs) interleaved with
-// re-applies on file change. Ink's insertion model stacks inserted lines
-// ABOVE the animated region, so runtime logs end up above the plan/apply
-// output in scrollback. Append-only chronological rendering is the correct
-// model for a dev server (plan → status → logs, strictly in order), so dev
-// always takes the line renderer; deploy/destroy keep the interactive TUI.
-const makeServices = (dev: boolean | undefined) =>
-  Layer.merge(dev ? LoggingCli : selectCli(), RpcProviderProxy.fromEnv()).pipe(
-    Layer.provideMerge(
-      Layer.mergeAll(AlchemyContextLive, ProfileLive, CredentialsStoreLive),
+import * as Stacks from "../Alchemist/routes/stack.ts";
+import { DEV_RELOAD_EXIT_CODE, DevOptions } from "./DevOptions.ts";
+import { ConsoleLogLive } from "./GlobalLog.ts";
+import { handleCliErrors, installShutdownFeedback } from "./commands/errors.ts";
+import { renderApply, renderPlanning } from "./commands/render.ts";
+import * as CliKit from "./CliKit/index.ts";
+import { stackOutputsView } from "./components/view/StackOutputs.tsx";
+import { selectCliServices } from "./selectCli.ts";
+
+// Interactive dev/deploy runs use the Sigil progress UI; CI, redirected output,
+// and other non-interactive terminals still select the append-only renderer.
+// `ALCHEMY_TUI` remains the explicit override in either direction.
+const services = Layer.mergeAll(
+  Layer.provideMerge(
+    Layer.mergeAll(selectCliServices(), CliKit.CliKitInteraction),
+    CliKit.layer(),
+  ),
+  RpcProviderProxy.fromEnv(),
+  Layer.succeed(ArtifactStore, createArtifactStore()),
+  // Dev runs live in this exec child, not the `alchemy` CLI process, so
+  // without this layer they'd export no telemetry at all. No root
+  // `cli.dev` span though: dev remains alive across reloads, so a wrapping
+  // span would not end (and export) until shutdown — plan/apply spans are the
+  // trace roots instead.
+  //
+  // Telemetry is layered *on top of* the console logger so the OTLP logger
+  // merges with it. As `mergeAll` siblings the last `CurrentLoggers` wins,
+  // and telemetry would replace the console logger — every `Effect.log*`
+  // (plan, apply progress, stack outputs) silently vanished from the
+  // terminal whenever telemetry was enabled.
+  Layer.provideMerge(TelemetryLive, ConsoleLogLive),
+).pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(AlchemyContextLive, ProfileStoreLive, CredentialsStoreLive),
+  ),
+  Layer.provideMerge(
+    Layer.mergeAll(
+      PlatformServices,
+      FetchHttpClient.layer,
+      ConfigProvider.layer(ConfigProvider.fromEnv()),
+    ),
+  ),
+);
+
+/** `alchemy dev` normally parks forever; set for single-pass runs (tests). */
+const devOnce = Config.string("ALCHEMY_DEV_ONCE").pipe(
+  Config.withDefault(""),
+  Effect.map((value) => value === "1" || value === "true"),
+);
+
+const runDev = Effect.fn(function* (options: DevOptions) {
+  const target = {
+    entrypoint: options.main,
+    stage: options.stage,
+    profile: options.profile,
+    envFile: Option.getOrUndefined(options.envFile),
+  };
+  const snapshot = yield* Stacks.plan({
+    target,
+    operation: "deploy",
+    force: options.force,
+    updateStateStore: true,
+    dev: true,
+  }).pipe(renderPlanning({ operation: "Dev", stage: options.stage }));
+  const once = yield* devOnce;
+  const applyPlan = Stacks.apply(snapshot).pipe(
+    renderApply(snapshot.native, {
+      stage: options.stage,
+      dev: !once,
+    }),
+  );
+  const result = yield* once
+    ? applyPlan
+    : applyPlan.pipe(
+        Effect.catchCause((cause) =>
+          Console.error(
+            describeFailure(
+              "apply",
+              cause,
+              "keeping dev alive so healthy resources keep serving",
+            ),
+          ).pipe(Effect.as(undefined)),
+        ),
+      );
+  if (result !== undefined && once) {
+    const kit = yield* CliKit.CliKit;
+    yield* kit.output.print(stackOutputsView(result));
+  }
+  return once ? undefined : yield* Effect.never;
+});
+
+/**
+ * Resolves with the files behind the next debounced change batch. The
+ * listener detaches itself on delivery — `Effect.callback` only runs its
+ * cleanup on interruption, so a listener left behind would fire once per
+ * past generation on every later change.
+ */
+const nextChange = (watcher: {
+  subscribe: (
+    listener: (change: { paths: ReadonlySet<string> }) => void,
+  ) => () => void;
+}) =>
+  Effect.callback<ReadonlySet<string>>((resume) => {
+    const unsubscribe = watcher.subscribe(({ paths }) => {
+      unsubscribe();
+      resume(Effect.succeed(paths));
+    });
+    return Effect.sync(unsubscribe);
+  });
+
+const logReload = Effect.fn(function* (paths: ReadonlySet<string>) {
+  const path = yield* Path.Path;
+  yield* Effect.logInfo(
+    `Reloading stack: changed ${[...paths]
+      .map((file) => path.relative(initialCwd, file))
+      .join(", ")}`,
+  );
+});
+
+/**
+ * Node: one process, many generations. The Oxc loader imports the stack graph
+ * under a fresh namespace each time; a change to any file it loaded
+ * interrupts the parked run (whose scope tears down the dev widget) and the
+ * loop imports the next generation.
+ */
+const runNodeDevWatcher = Effect.fn(function* (options: DevOptions) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  // Node reports real paths for loaded files (symlinked checkouts, macOS
+  // `/tmp`), so the project root the graph is scoped to must be real too.
+  // Scope to the invocation directory, not the entrypoint's directory: a
+  // config under `infra/` commonly imports application code from `src/`.
+  const entrypoint = yield* fs.realPath(path.resolve(options.main));
+  const root = yield* fs.realPath(initialCwd);
+  const nodeModules = `${path.sep}node_modules${path.sep}`;
+  return yield* Effect.acquireRelease(
+    Effect.sync(() =>
+      watchImport<{ readonly default?: unknown }>(entrypoint, {
+        parentURL: import.meta.url,
+        shouldInvalidate: (url) => {
+          if (!url.startsWith("file:")) return false;
+          const file = fileURLToPath(url);
+          const relative = path.relative(root, file);
+          return (
+            !file.includes(nodeModules) &&
+            (relative === "" ||
+              (relative !== ".." &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative)))
+          );
+        },
+      }),
     ),
-    Layer.provideMerge(
-      Layer.mergeAll(
-        PlatformServices,
-        FetchHttpClient.layer,
-        ConfigProvider.layer(ConfigProvider.fromEnv()),
+    (watcher) => Effect.promise(() => watcher.close()),
+  ).pipe(
+    Effect.flatMap((watcher) => {
+      const generation = devKeepAlive(runDev(options)).pipe(
+        Effect.provideService(StackModuleLoader, {
+          import: () => watcher.import().then(({ value }) => value),
+        }),
+        Effect.scoped,
+      );
+      return Effect.forever(
+        Effect.raceFirst(generation, nextChange(watcher)).pipe(
+          Effect.flatMap((paths) =>
+            paths === undefined ? Effect.void : logReload(paths),
+          ),
+        ),
+      );
+    }),
+  );
+});
+
+/**
+ * Bun: one process per generation. Bun cannot evict evaluated modules, so the
+ * tracker only records which project files the stack graph loads; the first
+ * change to one of them logs, lets the generation scope tear down the dev
+ * widget, and exits with DEV_RELOAD_EXIT_CODE for the supervisor to respawn.
+ */
+const runBunDevWatcher = (options: DevOptions) =>
+  Effect.acquireRelease(
+    Effect.sync(() =>
+      // Match Node's project-wide graph: the stack entrypoint may live in a
+      // subdirectory while importing sibling source trees.
+      trackBunImports({ root: initialCwd }),
+    ),
+    (tracker) => Effect.promise(() => tracker.close()),
+  ).pipe(
+    Effect.flatMap((tracker) =>
+      Effect.raceFirst(
+        devKeepAlive(runDev(options)).pipe(Effect.scoped),
+        nextChange(tracker),
       ),
     ),
+    Effect.flatMap((paths) =>
+      paths === undefined
+        ? Effect.void
+        : logReload(paths).pipe(
+            Effect.andThen(
+              Effect.sync(() => {
+                process.exitCode = DEV_RELOAD_EXIT_CODE;
+              }),
+            ),
+          ),
+    ),
   );
 
-export const exec = () => {
-  const options = Schema.decodeSync(ExecStackOptions)(
-    JSON.parse(process.env.ALCHEMY_EXEC_OPTIONS!),
+/**
+ * A run that ended by itself with nothing but interruptions in its cause was
+ * cancelled from the inside — a provider or engine race, never the user —
+ * so it must be reported like any other failure. Ctrl+C is different: it
+ * interrupts the fiber running this code, so `catchCause` never gets to
+ * park it (a parked `Effect.never` is interrupted straight away too).
+ */
+const describeFailure = (
+  what: string,
+  cause: Cause.Cause<unknown>,
+  next: string,
+) =>
+  Cause.hasInterruptsOnly(cause)
+    ? `alchemy dev: ${what} was interrupted internally (a bug in a provider or the engine — please report it with the trace below); ${next}.\n${Cause.pretty(cause)}`
+    : `alchemy dev: ${what} failed; ${next}.\n${Cause.pretty(cause)}`;
+
+// A mid-edit import or planning failure must keep the watch process alive so
+// the next save can restart it. Ctrl+C still tears the run down.
+export const devKeepAlive = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.catchCause((cause) =>
+      Console.error(
+        describeFailure(
+          "run",
+          cause,
+          "waiting for the next file change to retry",
+        ),
+      ).pipe(Effect.andThen(Effect.never)),
+    ),
   );
-  // Subscribe to the spawner's sidecar log stream BEFORE the stack runs:
-  // this process owns the terminal renderer, so sidecar output printed here
-  // lands in chronological order with the run's own lines instead of racing
-  // the shared tty. No-op outside dev.
-  return forwardSidecarLogs.pipe(
-    Effect.andThen(execStack(options)),
-    Effect.provide(makeServices(options.dev)),
-    Effect.scoped,
+
+const makeExec = () => {
+  const options = Schema.decodeSync(DevOptions)(
+    JSON.parse(process.env.ALCHEMY_EXEC_OPTIONS!),
   );
+  return Effect.gen(function* () {
+    yield* installShutdownFeedback;
+    // Subscribe to the spawner's sidecar log stream BEFORE the stack runs:
+    // this process owns the terminal renderer, so sidecar output printed
+    // here lands in chronological order with the run's own lines instead of
+    // racing the shared tty. No-op outside dev. The mixed tail is also teed
+    // to log/{stage}/{timestamp}.log; per-resource output lands in
+    // log/{stage}/{fqn…}/ via the local providers.
+    const devLog = yield* (yield* makeDevLogOpener)(options.stage);
+    yield* forwardSidecarLogs((entry) =>
+      devLog.writeLine(`[${entry.channel}] ${entry.line}`),
+    );
+    // Single-pass runs park nothing. Otherwise Node reloads the stack graph in
+    // this process; Bun exits for the supervisor to respawn (see above).
+    return yield* (yield* devOnce)
+      ? devKeepAlive(runDev(options))
+      : process.versions.bun !== undefined
+        ? runBunDevWatcher(options)
+        : runNodeDevWatcher(options);
+  }).pipe(Effect.provide(services), Effect.scoped, handleCliErrors);
 };
+
+/** Fully wired sidecar CLI program. */
+export const exec: () => Effect.Effect<
+  void,
+  Effect.Error<ReturnType<typeof makeExec>>
+> = makeExec;