sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Cli/ commands/ dev.ts

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,
  envFile,
  force,
  include,
  exclude,
  devStage,
  optionalConfig,
  profile,
  resolveStackArgs,
} from "./flags.ts";
import { logCommandFailure, VersionCheck } from "./instrument.ts";

/**
 * Trust the Floci emulator CA in `alchemy dev` so cross-cloud data planes
 * terminated by the emulator's self-signed cert (e.g. an AWS Lambda MicroVM
 * bound to a local Cloudflare Worker) are reachable from local workerd. workerd
 * reads its trusted certificates from `NODE_EXTRA_CA_CERTS` at runtime init, so
 * this must be present in the env of every spawned child (the exec worker, the
 * RPC sidecar, and the workerd instances they start). `ensureFloci` refreshes
 * the bundle at this stable path (and sets the variable itself once written);
 * never clobber a value the caller set, and don't point at a missing file —
 * Node/Bun warn about it on every startup.
 */

export const devCommand = Command.make(
  "dev",
  {
    force,
    include,
    exclude,
    config: optionalConfig,
    configPath,
    envFile,
    stage: devStage,
    profile,
  },
  Effect.fn(
    function* (rawArgs) {
      const args = yield* resolveStackArgs("dev")(rawArgs);
      // This process is only the exec child's supervisor; the child owns the
      // terminal and announces the Ctrl+C shutdown. Without this, a SIGINT
      // hits both processes and the interrupt message prints twice.
      yield* suppressInterruptMessages;
      const options = yield* Schema.encodeEffect(DevOptions)(args);
      // A missing entry is this process's error to report, not a stack
      // trace out of the exec child.
      yield* resolveStackEntrypoint(options.main);
      // Providers' dev environment (e.g. a local emulator's CA bundle). Set on
      // THIS process, so the RPC spawner's sidecars (and the workerd they
      // launch) inherit it — they are forked from here, not from the exec
      // child below.
      const env = yield* Contributions.devEnv().pipe(
        Effect.catchTag("ContributionError", (error) =>
          Effect.logWarning(error.message).pipe(Effect.as({})),
        ),
      );
      for (const [key, value] of Object.entries(env)) {
        process.env[key] ??= value;
      }
      const spawner = yield* RpcSpawner.RpcSpawner;
      // Neither runtime uses its native `--watch`: those hard-restart the exec
      // child with no teardown, leaving the previous generation's widget in
      // scrollback and never saying what changed. exec.ts watches the user's
      // stack graph itself. Under Node it reloads the graph in-process; under
      // Bun (which cannot evict evaluated modules) it tears down and exits
      // with DEV_RELOAD_EXIT_CODE, and this supervisor starts a fresh child.
      let command: [string, ...string[]];
      const entry = fileURLToPath(import.meta.resolve("alchemy/bin/exec.js"));
      if (typeof globalThis.Bun !== "undefined") {
        command = ["bun", "run", ...process.execArgv, entry];
      } else {
        // Node: the exec entry runs with alchemy's Oxc loader hooks,
        // exactly as bin/cli.js started this process. Select the loader from
        // this module's source or compiled location; the entry is always JS.
        // Node's own TypeScript support is never relied on. `process.execPath`,
        // not "node": the hooks are gated on THIS node's version. A
        // duplicate --import inherited via execArgv is harmless — the
        // second import of the same URL hits the module cache.
        command = [
          process.execPath,
          ...process.execArgv,
          ...nodeLoaderArgs(import.meta.url),
          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",
        stderr: "inherit",
        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) =>
          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
      // handle before the replacement starts; the sidecar spawner lives in
      // the command scope and survives every restart.
      yield* Effect.repeat(runChild, {
        until: (code) => code !== DEV_RELOAD_EXIT_CODE,
      });
    },
    (effect, args) =>
      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"));