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

package/src/Cli/exec.ts

@@ -4,7 +4,6 @@ import { trackBunImports } from "@alchemy.run/node-utils/watch-import-bun";
 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 FetchHttpClient from "effect/http/FetchHttpClient";
@@ -13,21 +12,24 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import { resolveStackEntrypoint } from "../Alchemist/Entrypoint.ts";
-import * as Stacks from "../Alchemist/routes/stack.ts";
-import { StackModuleLoader } from "../Alchemist/Session.ts";
+import { StackModuleLoader } from "../Alchemist/Entrypoint.ts";
+import * as Alchemist from "../Alchemist/index.ts";
 import { AlchemyContextLive } from "../AlchemyContext.ts";
 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import { ProfileStoreLive } from "../Auth/Profile.ts";
-import { makeDevLogOpener } from "../Local/DevLog.ts";
+import * as Interaction from "../Interaction.ts";
 import * as RpcProviderProxy from "../Local/RpcProviderProxy.ts";
 import { forwardSidecarLogs } from "../Local/RpcSpawner.ts";
+import { renderApply } from "../Report.ts";
 import { TelemetryLive } from "../Telemetry/Layer.ts";
+import { LogProcess, parentLogLayer } from "../Util/LogRecord.ts";
 import { initialCwd } from "../Util/Node.ts";
 import { PlatformServices } from "../Util/PlatformServices.ts";
-import * as CliKit from "./CliKit/index.ts";
+import { logShutdown } from "../Util/Shutdown.ts";
+import { processTrace, withTraceParent } from "../Util/TraceParent.ts";
 import { handleCliErrors, installShutdownFeedback } from "./commands/errors.ts";
-import { renderApply, renderPlanning } from "./commands/render.ts";
+import { renderPlanning } from "./commands/render.ts";
 import { stackOutputsView } from "./components/view/StackOutputs.tsx";
 import { DEV_RELOAD_EXIT_CODE, DevOptions } from "./DevOptions.ts";
 import { ConsoleLogLive } from "./GlobalLog.ts";
@@ -37,7 +39,7 @@ import { selectCliServices } from "./selectCli.ts";
 // 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()),
+  Layer.provideMerge(selectCliServices(), Interaction.layer()),
   RpcProviderProxy.fromEnv(),
   Layer.succeed(ArtifactStore, createArtifactStore()),
   // Dev runs live in this exec child, not the `alchemy` CLI process, so
@@ -45,13 +47,8 @@ const services = Layer.mergeAll(
   // `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),
+  TelemetryLive,
+  ConsoleLogLive,
 ).pipe(
   Layer.provideMerge(Layer.mergeAll(AlchemyContextLive, ProfileStoreLive, CredentialsStoreLive)),
   Layer.provideMerge(
@@ -70,39 +67,41 @@ const devOnce = Config.String("ALCHEMY_DEV_ONCE").pipe(
 );
 
 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,
-    include: options.include,
-    exclude: options.exclude,
-    updateStateStore: true,
-    dev: true,
-  }).pipe(renderPlanning({ operation: "Dev", stage: options.stage }));
+  const snapshot = yield* Alchemist.importStack(options.main).pipe(
+    Effect.flatMap((stack) =>
+      Alchemist.plan({
+        stack,
+        operation: "deploy",
+        stage: options.stage,
+        profile: options.profile,
+        envFile: Option.getOrUndefined(options.envFile),
+        updateStateStore: true,
+        dev: true,
+        force: options.force,
+        include: options.include,
+        exclude: options.exclude,
+      }),
+    ),
+    renderPlanning({ operation: "Dev", stage: options.stage }),
+  );
   const once = yield* devOnce;
-  const applyPlan = Stacks.apply(snapshot).pipe(
+  const applyAndRender = Alchemist.apply(snapshot).pipe(
     renderApply(snapshot.native, {
       stage: options.stage,
       dev: !once,
     }),
   );
   const result = yield* once
-    ? applyPlan
-    : applyPlan.pipe(
+    ? applyAndRender
+    : applyAndRender.pipe(
         Effect.catchCause((cause) =>
-          Console.error(
+          Effect.logError(
             describeFailure("apply", cause, "keeping dev alive so healthy resources keep serving"),
           ).pipe(Effect.as(undefined)),
         ),
       );
   if (result !== undefined && once) {
-    const kit = yield* CliKit.CliKit;
+    const kit = yield* Interaction.Interaction;
     yield* kit.output.print(stackOutputsView(result));
   }
   return once ? undefined : yield* Effect.never;
@@ -234,7 +233,7 @@ const describeFailure = (what: string, cause: Cause.Cause<unknown>, next: string
 export const devKeepAlive = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
   effect.pipe(
     Effect.catchCause((cause) =>
-      Console.error(
+      Effect.logError(
         describeFailure("run", cause, "waiting for the next file change to retry"),
       ).pipe(Effect.andThen(Effect.never)),
     ),
@@ -249,11 +248,10 @@ const makeExec = () => {
     // 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}`));
+    // racing the shared tty. No-op outside dev. Like every record of this
+    // process, they also go up to the `alchemy dev` process, which writes
+    // the run log (see `parentLogLayer`).
+    yield* forwardSidecarLogs;
     // 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)
@@ -261,7 +259,16 @@ const makeExec = () => {
       : process.versions.bun !== undefined
         ? runBunDevWatcher(options)
         : runNodeDevWatcher(options);
-  }).pipe(Effect.provide(services), Effect.scoped, handleCliErrors);
+  }).pipe(
+    logShutdown("exec"),
+    // Spans join the trace `alchemy dev` passed down, like the records
+    // logged outside them already do.
+    withTraceParent(processTrace),
+    Effect.provide(Layer.provideMerge(parentLogLayer(), services)),
+    Effect.provideService(LogProcess, "exec"),
+    Effect.scoped,
+    handleCliErrors,
+  );
 };
 
 /** Fully wired sidecar CLI program. */

package/src/Cli/main.ts

@@ -1,4 +1,4 @@
-import { AlchemyContextLive } from "alchemy/AlchemyContext";
+import { AlchemyContext, AlchemyContextLive } from "alchemy/AlchemyContext";
 import { ArtifactStore, createArtifactStore } from "alchemy/Artifacts";
 import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
 import { ProfileStoreLive } from "alchemy/Auth/Profile";
@@ -6,26 +6,32 @@ import * as Contributions from "alchemy/Contributions";
 import { TelemetryLive } from "alchemy/Telemetry/Layer";
 import { moduleExtension } from "alchemy/Util/Node";
 import { PlatformServices } from "alchemy/Util/PlatformServices";
-import * as Cause from "effect/Cause";
 import * as CliConfig from "effect/cli/CliConfig";
 import * as CliError from "effect/cli/CliError";
 import * as Command from "effect/cli/Command";
 import * as Flag from "effect/cli/Flag";
 import * as GlobalFlag from "effect/cli/GlobalFlag";
 import * as ConfigProvider from "effect/ConfigProvider";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as HttpClient from "effect/http/HttpClient";
 import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Scope from "effect/Scope";
 import packageJson from "../../package.json" with { type: "json" };
+import * as Interaction from "../Interaction.ts";
+import { logShutdown } from "../Util/Shutdown.ts";
 import { checkLatestVersion } from "./checkVersion.ts";
-import * as CliKit from "./CliKit/index.ts";
 import {
   compatibilityCommand,
   compatibilityCommands,
   type CompatibilityCommand,
 } from "./commands/compat.ts";
 import { handleCliErrors } from "./commands/errors.ts";
-import { GlobalLogLive, logRunHeader } from "./GlobalLog.ts";
+import { VersionCheck } from "./commands/instrument.ts";
+import { GlobalLogLive, LogFormatFlag, LogLevelFlag } from "./GlobalLog.ts";
 import { selectCliServices } from "./selectCli.ts";
 
 const commandMetadata = [
@@ -107,7 +113,7 @@ const commands = await Promise.all(
   commandMetadata.map(([name, description]) =>
     loadEveryCommand || name === requestedCommand
       ? loadCommand(name)
-      : placeholderCommand(name, description),
+      : Promise.resolve(placeholderCommand(name, description)),
   ),
 );
 
@@ -126,6 +132,21 @@ const NoInput = GlobalFlag.Setting("no-input")({
   ),
 });
 
+/**
+ * `--fast-distilled` loads distilled SDKs through their lazy service stubs
+ * under Node. The launcher (`bin/cli.js`) reads it from argv before any
+ * module loads and passes it on as `ALCHEMY_FAST_DISTILLED=1`; this
+ * registration exists so the parser accepts the flag.
+ */
+const FastDistilled = GlobalFlag.Setting("fast-distilled")({
+  flag: Flag.Boolean("fast-distilled").pipe(
+    Flag.withDescription(
+      "Load distilled SDK operations on first use (Node only; lowers startup memory)",
+    ),
+    Flag.withDefault(false),
+  ),
+});
+
 const root = Command.make("alchemy", {}, () =>
   Effect.fail(CliError.ShowHelp.make({ commandPath: ["alchemy"], errors: [] })),
 ).pipe(
@@ -144,7 +165,7 @@ const root = Command.make("alchemy", {}, () =>
       compatibilityCommand(name as CompatibilityCommand),
     ),
   ]),
-  Command.withGlobalFlags([NoInput]),
+  Command.withGlobalFlags([NoInput, FastDistilled, LogLevelFlag, LogFormatFlag]),
 );
 
 /**
@@ -170,7 +191,7 @@ const cli = Command.run(root, {
 
 const services = Layer.mergeAll(
   CliConfig.layer({
-    builtIns: [GlobalFlag.Help, GlobalFlag.Version, GlobalFlag.Completions, GlobalFlag.LogLevel],
+    builtIns: [GlobalFlag.Help, GlobalFlag.Version, GlobalFlag.Completions],
   }),
   Layer.provideMerge(AlchemyContextLive, PlatformServices),
   Layer.provide(ProfileStoreLive, PlatformServices),
@@ -181,37 +202,35 @@ const services = Layer.mergeAll(
   Layer.succeed(ArtifactStore, createArtifactStore()),
   FetchHttpClient.layer,
   ConfigProvider.layer(ConfigProvider.fromEnv()),
-  Layer.provide(
-    Layer.provideMerge(
-      Layer.mergeAll(selectCliServices(), CliKit.CliKitInteraction),
-      CliKit.layer(),
-    ),
-    PlatformServices,
-  ),
-  // Debug run log under ~/.alchemy/logs — the console noise floor stays at
+  Layer.provide(Layer.provideMerge(selectCliServices(), Interaction.layer()), PlatformServices),
+  // Debug run log in the project's .alchemy/log — the console noise floor stays at
   // Info, but full causes and auth-flow breadcrumbs land in the file so
   // support can ask users for it.
-  //
-  // Telemetry sits on top of the console/file loggers so its OTLP logger
-  // merges with them. Listed as `mergeAll` siblings, whichever came last
-  // would win the `CurrentLoggers` slot and silently drop the other.
-  Layer.provideMerge(TelemetryLive, Layer.provide(GlobalLogLive, PlatformServices)),
+  Layer.provide(GlobalLogLive, PlatformServices),
+  TelemetryLive,
 );
 
 const program = Effect.gen(function* () {
-  yield* logRunHeader;
-  // Best-effort check for a newer published version. Runs to completion
-  // before the command so the warning prints before any interactive
-  // prompts; the registry response is cached for a day and the fetch is
-  // bounded by a short timeout, so this stays fast.
-  yield* checkLatestVersion;
-  return yield* cli;
-}).pipe(
-  // The terminal shows the friendly message; the run log keeps the full
-  // cause chain. Must sit inside the service provision so the file logger
-  // is still installed.
-  Effect.tapCause((cause) => Effect.logDebug(`command failed:\n${Cause.pretty(cause)}`)),
-);
+  // Best-effort check for a newer published version, run by each command
+  // before its handler: the console flags are parsed by then, and the
+  // warning prints before any interactive prompt. Cached for a day and
+  // bounded by a short timeout, so it stays fast. Its fetch may finish in
+  // the background, in this scope.
+  // Only the check's own services, so the command's flags and loggers win.
+  const services = Context.pick(
+    AlchemyContext,
+    FileSystem.FileSystem,
+    HttpClient.HttpClient,
+    Path.Path,
+    Scope.Scope,
+  )(
+    yield* Effect.context<
+      AlchemyContext | FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | Scope.Scope
+    >(),
+  );
+  const check = yield* Effect.cached(Effect.provideContext(checkLatestVersion, services));
+  return yield* cli.pipe(Effect.provideService(VersionCheck, check));
+}).pipe(logShutdown("cli"));
 
 const mainEffect = program.pipe(
   // $USER and $ALCHEMY_STAGE are set by the environment

package/src/Cli/selectCli.ts

@@ -2,18 +2,18 @@ import * as CliOutput from "effect/cli/CliOutput";
 import type * as Prompt from "effect/cli/Prompt";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { Interaction } from "../Interaction.ts";
 import type { Cli } from "../Report.ts";
-import { CliKit } from "./CliKit/CliKit.ts";
 import { LoggingCli } from "./LoggingCli.ts";
 import { plainCliFormatter } from "./PlainCliFormatter.ts";
 
-type SelectedCli = Layer.Layer<Cli, never, CliKit | Prompt.Environment>;
+type SelectedCli = Layer.Layer<Cli, never, Interaction | Prompt.Environment>;
 
 /** Select the interactive or append-only root renderer. */
 export const selectCliServices = () =>
   Layer.unwrap(
     Effect.gen(function* () {
-      const cli = yield* CliKit;
+      const cli = yield* Interaction;
       if (!cli.terminal.input) {
         const plain: SelectedCli = Layer.mergeAll(
           LoggingCli,

package/src/Command/Command.ts

@@ -170,7 +170,7 @@ const TERMINATION_SIGNAL_DISPATCH_TIMEOUT = Duration.millis(25);
 const parseExecutionTimeout = (
   props: CommandRunProps,
 ): Effect.Effect<Duration.Duration | undefined, CommandError> => {
-  if (props.timeout === undefined) return Effect.succeed(undefined);
+  if (props.timeout === undefined) return Effect.undefined;
   const decoded = Duration.fromInput(props.timeout);
   if (
     Option.isNone(decoded) ||

package/src/Command/Dev.ts

@@ -1,21 +1,44 @@
+import * as NodeNet from "node:net";
 import { stripVTControlCharacters } from "node:util";
-import * as ConsoleService from "effect/Console";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import { SystemError } from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
-import { FQN_SEPARATOR } from "../FQN.ts";
-import { makeDevLogOpener } from "../Local/DevLog.ts";
 import * as LocalProvider from "../Local/LocalProvider.ts";
 import * as ProviderLayer from "../Local/ProviderLayer.ts";
 import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
-import { Stage } from "../Stage.ts";
 import { moduleExtension } from "../Util/Node.ts";
 import { makeResourceOutput } from "../Util/ResourceOutput.ts";
 import { CommandExecutor, UnexpectedExit, makeCommandError, type CommandProps } from "./Command.ts";
 import { makeCommandRedactor } from "./Redaction.ts";
 
-export interface DevProps extends CommandProps {}
+export interface DevProps extends CommandProps {
+  /**
+   * Make the URL required: the resource is ready only once the command
+   * prints a URL, however long that takes, and fails if the command exits
+   * first. Without it, the resource waits 5 seconds and settles with
+   * `url: undefined` when no URL appears.
+   *
+   * A localhost/IP URL is still preferred: when the first URL printed is
+   * another one, the resource waits up to 5 seconds more for a local one
+   * before settling with it.
+   *
+   * @default false
+   */
+  waitForUrl?: boolean;
+  /**
+   * The port the command listens on. Alchemy sets `PORT` to it, over any
+   * `env.PORT`, and the resource is ready once the port accepts a
+   * connection, however long that takes. Output isn't scanned for a URL,
+   * so `waitForUrl` has no effect: `url` is `http://localhost:<port>`.
+   *
+   * The resource fails if the command exits before the port opens, or if
+   * another process already listens on the port when the command starts.
+   */
+  port?: number;
+}
 
 export interface Dev extends Resource<
   "Command.Dev",
@@ -25,7 +48,9 @@ export interface Dev extends Resource<
      * URL extracted from stdout/stderr. A `localhost`/IP URL (the dev
      * server's own address) is preferred over any other URL the command
      * prints; a non-local URL is only used as a fallback if no local one
-     * appears. Best-effort: `undefined` if no URL appears within 5 seconds.
+     * appears. Best-effort: `undefined` if no URL appears within 5 seconds,
+     * unless `waitForUrl` is set, which waits until one does. With `port`,
+     * it is `http://localhost:<port>`.
      */
     url: string | undefined;
   }
@@ -58,6 +83,36 @@ export interface Dev extends Resource<
  * yield* Console.log(dev.url); // e.g. "http://localhost:5173"
  * ```
  *
+ * ### Requiring a URL
+ * By default the resource waits 5 seconds for a URL and settles with
+ * `url: undefined` if none appears. Set `waitForUrl` when downstream
+ * resources depend on the URL: the resource is ready only once the
+ * command prints one, however long the server takes to start, and fails
+ * if the command exits first.
+ *
+ * **Example:** Wait for a slow server's URL
+ * ```typescript
+ * const engine = yield* Dev("Engine", {
+ *   command: "rivet-engine start",
+ *   waitForUrl: true,
+ * });
+ * ```
+ *
+ * ### Known Port
+ * When you choose the port, pass it as `port`: Alchemy sets `PORT` to it
+ * and the resource is ready once the port accepts a connection, with no
+ * output scanning. This suits servers that print no URL, and wrappers
+ * that route the port elsewhere.
+ *
+ * **Example:** Serve on port 4000
+ * ```typescript
+ * const api = yield* Dev("Api", {
+ *   command: "node server.ts",
+ *   port: 4000,
+ * });
+ * yield* Console.log(api.url); // "http://localhost:4000"
+ * ```
+ *
  * ### Working Directory
  * Use `cwd` to run the command in a subdirectory — useful in
  * monorepos where each package has its own dev server.
@@ -110,27 +165,36 @@ export const DevProviderLocal = () =>
     import.meta.resolve(`./Local${moduleExtension(import.meta.url)}`, import.meta.url),
     Effect.gen(function* () {
       const { spawn } = yield* CommandExecutor;
-      const stage = yield* Stage;
-      const openDevLog = yield* makeDevLogOpener;
-      const baseConsole = yield* ConsoleService.Console;
 
       return {
         // The dev process is spawned into the instance scope the helper
         // provides: it keeps running after `start` returns (readiness) and
         // is killed when the helper closes the scope on restart/delete.
         start: Effect.fn(function* ({ fqn, news: props, invalidate }) {
-          const child = yield* spawn(props);
+          const { port } = props;
+          // A restart has already killed the previous process group, so a
+          // listener now is someone else's (an orphaned server, say), and
+          // the readiness probe below would mistake it for this command.
+          if (port !== undefined && (yield* isListening(port))) {
+            return yield* makeCommandError(
+              props,
+              new SystemError({
+                _tag: "Busy",
+                module: "Command",
+                method: "Dev",
+                pathOrDescriptor: port,
+                description: "another process already listens on this port",
+              }),
+            );
+          }
+          const child = yield* spawn(
+            port === undefined ? props : { ...props, env: { ...props.env, PORT: `${port}` } },
+          );
           const redactor = makeCommandRedactor(props.env);
-          // One log file per process generation, closed with the instance
-          // scope: log/{stage}/{fqn…}/{timestamp}.log (namespaces nest as dirs). Terminal lines
-          // carry the resource's pnpm-style prefix; the file gets raw text.
-          const devLog = yield* openDevLog(stage, ...fqn.split(FQN_SEPARATOR));
-          yield* Effect.log(`[${fqn}] Logs → ${devLog.path}`);
-          // Through the Console SERVICE, never a raw fd write: the process
-          // that owns the terminal runs an ink renderer, and a bare write
-          // to its stdout tears the animated region. The CLI's console
-          // capture inserts these lines above it instead.
-          const prefixed = makeResourceOutput(fqn, baseConsole);
+          // Through the logger, never a raw fd write: the process that owns
+          // the terminal renders the records and writes them to the run log
+          // (and a bare write to its stdout would tear the animated region).
+          const prefixed = yield* makeResourceOutput(fqn);
           yield* Effect.addFinalizer(() =>
             Effect.sync(() => {
               prefixed.stdout.flush();
@@ -145,23 +209,21 @@ export const DevProviderLocal = () =>
           // always wins if one shows up. See issue #695.
           let fallbackUrl: string | undefined;
           const deferred = yield* Deferred.make<string>();
+          // Done when the first URL of any kind appears.
+          const anyUrl = yield* Deferred.make<void>();
 
           const mirror = (sink: "stdout" | "stderr") =>
             child[sink].pipe(
               Stream.decodeText,
               redactor.stream,
-              Stream.tap((text) =>
-                Effect.sync(() => {
-                  prefixed[sink].push(text);
-                  devLog.write(text);
-                }),
-              ),
+              Stream.tap((text) => Effect.sync(() => prefixed[sink].push(text))),
               Stream.tap((text) =>
                 Effect.sync(() => {
                   if (Deferred.isDoneUnsafe(deferred)) return;
                   buffer += text;
                   const url = extractUrl(buffer);
                   if (!url) return;
+                  Deferred.doneUnsafe(anyUrl, Effect.void);
                   if (isLocalUrl(url)) {
                     // The dev server's own address — resolve immediately.
                     Deferred.doneUnsafe(deferred, Effect.succeed(url));
@@ -178,17 +240,30 @@ export const DevProviderLocal = () =>
           yield* mirror("stdout");
           yield* mirror("stderr");
 
-          // Readiness: a URL appears (or the 5s budget elapses), unless the
-          // process exits first — an exit before readiness is a failure.
+          // Readiness: a localhost/IP URL appears, or 5 seconds pass and we
+          // settle with any other URL we saw (`undefined` with none). With
+          // `waitForUrl`, those 5 seconds start only once some URL appears,
+          // so the URL is required and there is no deadline: the only other
+          // way out is the process exiting, which is a failure. With `port`,
+          // readiness is the port opening instead, again with no deadline.
+          const awaitLocalUrl = Deferred.await(deferred).pipe(
+            Effect.timeoutOrElse({
+              duration: "5 seconds",
+              orElse: () => Effect.succeed(fallbackUrl),
+            }),
+          );
           const url = yield* Effect.raceAllFirst([
-            Deferred.await(deferred).pipe(
-              Effect.timeoutOrElse({
-                duration: "5 seconds",
-                // No localhost/IP URL appeared in time — fall back to any
-                // other URL we saw (or `undefined` if it stayed silent).
-                orElse: () => Effect.succeed(fallbackUrl),
-              }),
-            ),
+            port !== undefined
+              ? isListening(port).pipe(
+                  Effect.repeat({
+                    schedule: Schedule.spaced("100 millis"),
+                    until: (listening) => listening,
+                  }),
+                  Effect.as(`http://localhost:${port}`),
+                )
+              : props.waitForUrl
+                ? Deferred.await(anyUrl).pipe(Effect.andThen(awaitLocalUrl))
+                : awaitLocalUrl,
             child.exitCode.pipe(
               Effect.mapError((error) => makeCommandError(props, error.reason)),
               Effect.flatMap((exitCode) =>
@@ -245,3 +320,21 @@ export const extractUrl = (text: string) => {
 };
 
 const isLocalUrl = (url: string) => LOCAL_URL_REGEX.test(url);
+
+// Whether a TCP connection to `port` succeeds on either loopback address:
+// a server bound to `localhost` may listen on only one of them.
+const isListening = (port: number) =>
+  Effect.all([connects("127.0.0.1", port), connects("::1", port)], {
+    concurrency: "unbounded",
+  }).pipe(Effect.map(([ipv4, ipv6]) => ipv4 || ipv6));
+
+const connects = (host: string, port: number) =>
+  Effect.callback<boolean>((resume) => {
+    const socket = NodeNet.connect({ host, port });
+    socket.once("connect", () => {
+      socket.destroy();
+      resume(Effect.succeed(true));
+    });
+    socket.once("error", () => resume(Effect.succeed(false)));
+    return Effect.sync(() => socket.destroy());
+  });

package/src/Command/Memo.ts

@@ -229,7 +229,7 @@ const Memo = Effect.gen(function* () {
                 lockfile ? path.relative(options.cwd, lockfile) : undefined,
               ),
             )
-          : Effect.succeed(undefined),
+          : Effect.undefined,
       ],
       { concurrency: "unbounded" },
     );