@pithy-sh/cli 0.1.0

package/src/dev/hostWorkers.ts

@@ -0,0 +1,290 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { messageOf, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
+import type { WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import { composeCapabilities } from "../capabilities/compose";
+import {
+  HOST_WORKERS,
+  type HostDeliveryIdentity,
+  type HostWorkerSpec,
+  hostTemplatePath,
+  hostWorkerFor,
+  readHostTemplate as readHostTemplateDefault,
+} from "../capabilities/hostRegistry";
+import { writeFileAtomic } from "../project/atomic";
+import { allCapabilities, loadWorkerConfig } from "../project/config";
+import { DEFAULT_READY_SIGNAL } from "../project/workerManifest";
+import type { WorkerTarget } from "../project/workers";
+
+/**
+ * **The dev set is app Workers plus the host Worker of every capability they compose.**
+ *
+ * `apps/` is the app-Worker registry and stays exactly that. Beside it, each composed capability that
+ * owns Workflows contributes the prebuilt host Worker `pithy <capability> provision` would deploy —
+ * resolved through the same seam the provisioners use ({@link HOST_WORKERS}), materialized into a
+ * git-ignored directory, and handed to the orchestrator as an ordinary {@link WorkerTarget}. From
+ * there it is not a special case: it gets a pinned port out of `.dev.config.json`, a label and a
+ * color, an entry in `.dev-state.json`, and it is reaped with everything else.
+ *
+ * ## The name is the wire
+ *
+ * A host is registered under its **capability name** — `email`, not `acme-dev-email`. `buildWorkerEnv`
+ * derives `<STEM>_ORIGIN` from whatever name a worker carries in the dev config, so `email` is what
+ * makes an app Worker's `EMAIL_ORIGIN` resolve, and that is the address core's loopback dispatcher
+ * posts a Workflow dispatch to. A host named after its deployed script would publish
+ * `ACME_DEV_EMAIL_ORIGIN`, which nothing looks up. An `apps/` Worker already holding that name is
+ * therefore refused rather than shadowed — the wire would be silently wrong, which is the whole
+ * failure this issue is about.
+ *
+ * ## Where the config lands, and why it is generated at all
+ *
+ * Under `<project>/.wrangler/pithy/hosts/<capability>/`, following `provision/featureConfig.ts`: every
+ * scaffolded project has ignored `.wrangler/` at any depth since the first release, so a generated
+ * config can never be committed and `git add -A` cannot reach it. It is generated rather than shipped
+ * because a host template is a *template* — its database ids, its base URL and its theme are the
+ * adopter's, and only a resolution knows them.
+ *
+ * Two dev-shaped edits happen after the capability's own resolver has run, and both are here rather
+ * than in the resolvers because both are true of every host at once:
+ *
+ * - **`main` becomes absolute.** wrangler resolves `main` relative to the config file, and this config
+ *   sits nowhere near the entry it names — the entry is inside `node_modules`.
+ * - **`secrets_store_secrets` is dropped.** There is no Secrets Store locally; the master key reaches
+ *   a local Worker as a `.dev.vars` value, exactly as it reaches the app Worker.
+ *
+ * Database ids are the third, and are the registry's own job: {@link HostResolveContext.databaseId}
+ * answers the binding name, because local D1 identity is `database_id ?? binding` — wrangler's chain,
+ * and the one `pithy migrate --env dev` keyed the Miniflare store by. A host resolved with anything
+ * else opens an empty database and fails `no such table` on its first query.
+ */
+
+/** Where a materialized host config lives, under the already-ignored `.wrangler/`. */
+export function hostWorkerDir(projectDir: string, capability: string): string {
+  return join(projectDir, ".wrangler", "pithy", "hosts", capability);
+}
+
+/** One discovered host: the dev-set member, the capability it belongs to, and how to resolve it. */
+export interface HostWorker {
+  /** The capability that owns the host — its dev-set name and the key into the registry. */
+  capability: string;
+  /** The dev-set member handed to the orchestrator. Ordinary in every respect. */
+  worker: WorkerTarget;
+  /** The registry entry that fills this host's template. */
+  spec: HostWorkerSpec;
+  /** The composed capability object, when a Worker's config carried one this resolver can read. */
+  composed?: Capability;
+  /**
+   * The app Worker whose composition brought this host into the set — the directory its `.dev.vars`
+   * is generated into, and therefore the one this host copies. A host reads the same secrets the
+   * Worker that composes it does (the master key above all), and it has no `pithy.config.ts` of its
+   * own for the generator to resolve targets from.
+   */
+  sourceDir: string;
+}
+
+/** What discovery found, and anything it had to survive on the way. */
+export interface HostWorkerDiscovery {
+  hosts: HostWorker[];
+  /** Non-fatal lines for the terminal. A Worker whose config will not load is one; silence would not be. */
+  notes: string[];
+}
+
+/** Options for {@link discoverHostWorkers}. */
+export interface DiscoverHostWorkersOptions {
+  projectDir: string;
+  /** Every discovered app Worker. Their composed capabilities decide the host set. */
+  workers: readonly WorkerTarget[];
+  /** Seam: the capabilities one Worker composes. Defaults to loading its `apps/<name>/pithy.config.ts`. */
+  capabilitiesFor?: (workerDir: string) => Promise<Capability[]>;
+}
+
+/** The dev block a host Worker runs under: it must be up for the local loop to work, so it autostarts. */
+function hostDev(): WorkerTarget["dev"] {
+  return { autostart: true, readySignal: DEFAULT_READY_SIGNAL };
+}
+
+/**
+ * Every host Worker the project's app Workers compose, in registry order.
+ *
+ * A Worker whose `pithy.config.ts` will not load contributes nothing and is named — the same trade
+ * the entitlement check makes. `pithy dev` reports wiring; a config that will not import is
+ * wrangler's error to raise, and refusing to run the whole session over it would be a worse trade.
+ */
+export async function discoverHostWorkers(options: DiscoverHostWorkersOptions): Promise<HostWorkerDiscovery> {
+  const capabilitiesFor =
+    options.capabilitiesFor ?? (async (dir: string) => allCapabilities(await loadWorkerConfig(dir)));
+
+  const notes: string[] = [];
+  const composed = new Map<string, { capability: Capability; dir: string }>();
+  for (const worker of options.workers) {
+    let capabilities: Capability[];
+    try {
+      capabilities = await capabilitiesFor(worker.dir);
+    } catch (error) {
+      notes.push(`${worker.name}: its capabilities could not be read, so its capability hosts will not run.`);
+      notes.push(`  ${messageOf(error)}`);
+      continue;
+    }
+    // First declaration wins. Two Workers composing one capability share one host, exactly as they
+    // share a D1 by declaring one binding name — the host is the capability's, not the Worker's.
+    for (const capability of capabilities) {
+      if (!composed.has(capability.name)) composed.set(capability.name, { capability, dir: worker.dir });
+    }
+  }
+
+  // **Assembled before a single host reads one of them.** A capability object is a placeholder for
+  // half of what it reports until its `compose` hook has run, and the email host's resolver reads
+  // exactly such a value: `hostCatalogs()` answers `{}` on an unassembled capability, so `pithy dev`
+  // materialized an English-only host for a project that speaks two languages. The app Worker enqueued
+  // a Spanish subject and stored `locale='es'`; the local host re-rendered in English and — because
+  // `runSend` overwrites the stored subject with its own render — threw the Spanish one away. That is
+  // the two-Workers-disagree failure the `EMAIL_MESSAGES` var exists to close, reproduced on a
+  // developer's machine. See `capabilities/compose.ts`, and `emailProvisioner.ts` for the deployed half.
+  //
+  // **Degraded, not fatal, for the same reason the read above is.** A compose hook throws — `auth`
+  // refuses a plugin claiming a kit table, `payments` checks its ledger grants — and this sweep runs
+  // them over the **project-wide union** rather than any one Worker's own set. So a pair of Workers can
+  // collide here on something neither of them would refuse at its own boot, and an uncaught throw would
+  // end the whole `pithy dev` session rather than the one host it concerns. A session that starts
+  // without the email host and says why is worth more than one that does not start.
+  try {
+    composeCapabilities([...composed.values()].map((entry) => entry.capability));
+  } catch (error) {
+    notes.push("The capability hosts could not be assembled, so none of them will run.");
+    notes.push(`  ${messageOf(error)}`);
+    return { hosts: [], notes };
+  }
+
+  const taken = new Set(options.workers.map((worker) => worker.name));
+  const hosts: HostWorker[] = [];
+  for (const spec of HOST_WORKERS) {
+    const owner = composed.get(spec.capability);
+    if (!owner) continue;
+    if (taken.has(spec.capability)) {
+      throw new ValidationError({
+        message: `A Worker in apps/ is named "${spec.capability}", which is also the ${spec.capability} capability's host.`,
+        action: `Rename that Worker with pithy worker add, or move it, so ${spec.capability.toUpperCase()}_ORIGIN names one process.`,
+        detail: "Sibling addresses are keyed by worker name; two workers sharing one would publish one address.",
+      });
+    }
+    hosts.push({
+      capability: spec.capability,
+      spec,
+      composed: owner.capability,
+      sourceDir: owner.dir,
+      worker: {
+        name: spec.capability,
+        dir: hostWorkerDir(options.projectDir, spec.capability),
+        hasWrangler: true,
+        dev: hostDev(),
+      },
+    });
+  }
+
+  return { hosts, notes };
+}
+
+/** Options for {@link materializeHostConfigs}. */
+export interface MaterializeHostConfigsOptions {
+  projectDir: string;
+  /** The project name — the leading segment of every name a resolution derives. Never guessed. */
+  project: string;
+  /** The app Worker's local origin, which callback links in a locally sent message are built against. */
+  baseUrl: string;
+  hosts: readonly HostWorker[];
+  /** No message may leave this machine — the delivery preflight's verdict, passed to every resolver. */
+  simulateDelivery?: boolean;
+  /** Seam: read a capability's committed template. Defaults to the file beside its worker entry. */
+  readTemplate?: (entry: string) => Promise<WorkflowHostTemplate>;
+}
+
+/**
+ * What materialization produced: the lines to say, and the hosts that have no config on disk.
+ *
+ * The second list is not decoration. A host whose resolution threw has no directory — `mkdir` runs on
+ * the write path and never got there — so spawning `wrangler dev` in it fails with ENOENT, the
+ * orchestrator's spawn-error handler tears the whole session down, and every Worker that was running
+ * fine dies for one capability nobody could resolve. The note already said "it will not run"; this is
+ * what makes that sentence true.
+ */
+export interface HostMaterialization {
+  /** Non-fatal lines for the terminal, in the order they happened. */
+  notes: string[];
+  /** The capability names whose host has no config, and which therefore must not be started. */
+  failed: string[];
+}
+
+/**
+ * Resolve and write each host's local `wrangler.jsonc`. Returns non-fatal notes and the hosts that got
+ * none: a capability whose package will not load is named and dropped, because one unresolvable host is
+ * not a reason to refuse to run the Workers that are fine — nor to start one in a directory that is
+ * not there.
+ */
+export async function materializeHostConfigs(options: MaterializeHostConfigsOptions): Promise<HostMaterialization> {
+  const readTemplate = options.readTemplate ?? readHostTemplateDefault;
+  const notes: string[] = [];
+  const failed: string[] = [];
+
+  for (const host of options.hosts) {
+    try {
+      const template = await readTemplate(host.spec.entry);
+      const resolved = await host.spec.resolve(template, {
+        project: options.project,
+        env: LOCAL_ENVIRONMENT,
+        baseUrl: options.baseUrl,
+        databaseId: (binding) => binding,
+        capability: host.composed,
+        simulateDelivery: options.simulateDelivery,
+      });
+      const config = forLocalDev(resolved, host.spec.entry);
+      const path = join(host.worker.dir, "wrangler.jsonc");
+      await mkdir(dirname(path), { recursive: true });
+      await writeFileAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
+    } catch (error) {
+      notes.push(`${host.capability}: its host worker could not be resolved, so it will not run.`);
+      notes.push(`  ${messageOf(error)}`);
+      failed.push(host.capability);
+    }
+  }
+
+  return { notes, failed };
+}
+
+/** The two edits that are true of every host locally, applied after the capability's own resolver. */
+function forLocalDev(resolved: WorkflowHostTemplate, entry: string): WorkflowHostTemplate {
+  const config: WorkflowHostTemplate = { ...resolved };
+  if (!isAbsolute(config.main)) config.main = join(dirname(hostTemplatePath(entry)), config.main);
+  config.secrets_store_secrets = undefined;
+  return config;
+}
+
+/** Whether a capability owns a host Worker at all — the question `pithy doctor` and `migrate` both ask. */
+export function capabilityHostsWorkflows(capability: string): boolean {
+  return hostWorkerFor(capability) !== undefined;
+}
+
+/**
+ * What this project would put on the wire from the developer's machine, asked of every host rather
+ * than of the one capability that answers. `pithy dev`'s delivery preflight reads this, so the dev
+ * command branches on no capability — a tenth host that sends something implements `delivery` and is
+ * preflighted with no change here or there.
+ *
+ * A host whose package will not load answers nothing rather than failing the session: the
+ * materialization that follows names that same failure, and once is enough.
+ */
+export async function hostDeliveryIdentity(hosts: readonly HostWorker[]): Promise<HostDeliveryIdentity | undefined> {
+  for (const host of hosts) {
+    try {
+      const identity = await host.spec.delivery?.(host.composed);
+      if (identity) return identity;
+    } catch {
+      // Named by materializeHostConfigs, which reaches the same package on the same run.
+    }
+  }
+  return undefined;
+}

package/src/dev/keys.ts

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Single-keypress input for the dev supervisor — the smallest thing that can turn `l` into an action.
+ *
+ * A key has to be read in **raw mode**, because line mode does not deliver a character until Enter, and
+ * the whole point of `l` is that it is one keystroke. Raw mode is also the reason this module is
+ * careful: it takes the terminal's own handling away, so Ctrl-C stops generating `SIGINT` and becomes a
+ * `\x03` byte like any other. A key reader that forgot that would leave `pithy dev` unstoppable.
+ *
+ * **Non-TTY never enters raw mode, and never listens.** CI, a piped `pithy dev`, and `pithy dev --json`
+ * consumed by a script all land there. `setRawMode` on a non-TTY throws, and a `data` listener on stdin
+ * keeps the process alive after every worker has exited — a supervisor that will not exit is a worse
+ * bug than a keypress that is missing. So the reader answers `active: false` and does nothing at all.
+ *
+ * One binding is registered today. The shape takes a list so a second is one line, and deliberately
+ * offers no default set: `r` to restart and `o` to open the app are obvious neighbors and neither is
+ * this issue.
+ */
+
+/** The `\x03` byte Ctrl-C becomes once raw mode has taken the terminal's own handling away. */
+const ETX = "\x03";
+
+/** The slice of `process.stdin` a key reader uses — an interface so a test can assert what it did *not* do. */
+export interface KeyStream {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => unknown;
+  setEncoding: (encoding: string) => unknown;
+  resume: () => unknown;
+  pause: () => unknown;
+  on: (event: "data", listener: (chunk: string) => void) => unknown;
+  off: (event: "data", listener: (chunk: string) => void) => unknown;
+}
+
+/** One key, and what it does. `key` is a single character, compared literally. */
+export interface KeyBinding {
+  /** The character that triggers it. */
+  key: string;
+  /** What to do. May be async; a rejection goes to `onError`, never to an unhandled rejection. */
+  run: () => void | Promise<void>;
+}
+
+/** A live key reader. `active` says whether anything is listening at all. */
+export interface KeyReader {
+  /** Whether raw mode was entered and bindings are live. `false` on every non-TTY. */
+  active: boolean;
+  /** Restore the terminal and stop listening. Idempotent — shutdown can be reached more than once. */
+  stop: () => void;
+}
+
+/** Everything {@link readKeys} needs. `onInterrupt` is not optional: raw mode is what makes it necessary. */
+export interface ReadKeysOptions {
+  stdin?: KeyStream;
+  bindings: readonly KeyBinding[];
+  /** What Ctrl-C means now that the terminal no longer raises `SIGINT` for it. */
+  onInterrupt: () => void;
+  /** Where a binding's failure is reported. Without one a rejection is swallowed rather than thrown. */
+  onError?: (error: unknown) => void;
+}
+
+/** A reader that never touched the terminal — what every non-TTY gets. */
+const inert: KeyReader = { active: false, stop: () => {} };
+
+/**
+ * Start reading single keypresses, or answer that there is no terminal to read from.
+ *
+ * A chunk can carry more than one character (a paste, or a fast repeat), so each is dispatched in turn
+ * rather than the chunk being compared as a whole.
+ */
+export function readKeys(options: ReadKeysOptions): KeyReader {
+  const stdin = options.stdin ?? (process.stdin as unknown as KeyStream);
+  const setRawMode = stdin.setRawMode;
+  if (!stdin.isTTY || typeof setRawMode !== "function") return inert;
+
+  const onError = options.onError ?? (() => {});
+  const bindings = new Map(options.bindings.map((binding) => [binding.key, binding.run]));
+
+  const onData = (chunk: string): void => {
+    for (const character of chunk) {
+      if (character === ETX) {
+        options.onInterrupt();
+        return;
+      }
+      const run = bindings.get(character);
+      if (!run) continue;
+      try {
+        void Promise.resolve(run()).catch(onError);
+      } catch (error) {
+        onError(error);
+      }
+    }
+  };
+
+  setRawMode.call(stdin, true);
+  stdin.setEncoding("utf8");
+  stdin.resume();
+  stdin.on("data", onData);
+
+  let stopped = false;
+  return {
+    active: true,
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      stdin.off("data", onData);
+      setRawMode.call(stdin, false);
+      stdin.pause();
+    },
+  };
+}

package/src/dev/logging.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching the ANSI ESC (\x1b) is required to strip color codes.
+const ANSI_RX = /\x1b\[[0-9;]*m/g;
+
+/** Strip ANSI color codes — the terminal keeps color, the `logs/dev.log` file stays plain text. */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_RX, "");
+}
+
+/** Normalize CRLF and bare CR to LF — wrangler's progress spinner uses bare `\r`, one frame per line. */
+export function normalizeNewlines(text: string): string {
+  return text.replace(/\r\n?/g, "\n");
+}
+
+/**
+ * A stateful splitter that buffers stream chunks and emits one complete line at a time (newlines
+ * normalized first). `flush()` emits any trailing partial line when the stream ends. A stream yields
+ * arbitrary chunk boundaries, so line assembly must span chunks — this is that assembler.
+ */
+export function createLineSplitter(onLine: (line: string) => void): {
+  push: (chunk: string) => void;
+  flush: () => void;
+} {
+  let buffer = "";
+  return {
+    push(chunk: string) {
+      buffer = normalizeNewlines(buffer + chunk);
+      for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
+        onLine(buffer.slice(0, nl));
+        buffer = buffer.slice(nl + 1);
+      }
+    },
+    flush() {
+      if (buffer.length > 0) {
+        onLine(buffer);
+        buffer = "";
+      }
+    },
+  };
+}
+
+/** What {@link teeStream} does with each assembled line. */
+export interface TeeSinks {
+  /** The prefixed, colorized line for the terminal (`[name] …`). */
+  terminal: (line: string) => void;
+  /** The prefixed, ANSI-stripped line for `logs/dev.log`. */
+  log: (line: string) => void;
+  /** The raw line, for ready-signal matching. */
+  line: (line: string) => void;
+}
+
+/** A minimal readable stream — a real `child.stdout`, or a fake `EventEmitter`/`PassThrough` in tests. */
+export interface DataStream {
+  on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+  on(event: "end" | "close", listener: () => void): unknown;
+}
+
+/**
+ * Tee one child stream to three sinks: a colorized `[label] line` to the terminal, an ANSI-stripped
+ * `[label] line` to the log file, and the raw line to ready-signal matching. CR-normalized and line-split
+ * so wrangler's spinner and partial chunks each land as clean lines. Resolves when the stream ends.
+ */
+export function teeStream(args: {
+  stream: DataStream;
+  label: string;
+  paint: (text: string) => string;
+  sinks: TeeSinks;
+}): Promise<void> {
+  const { stream, label, paint, sinks } = args;
+  const prefix = paint(`[${label}]`);
+  const splitter = createLineSplitter((raw) => {
+    sinks.terminal(`${prefix} ${raw}`);
+    sinks.log(`[${label}] ${stripAnsi(raw)}`);
+    sinks.line(raw);
+  });
+  return new Promise((resolve) => {
+    stream.on("data", (chunk) => splitter.push(typeof chunk === "string" ? chunk : chunk.toString("utf8")));
+    const done = () => {
+      splitter.flush();
+      resolve();
+    };
+    stream.on("end", done);
+    stream.on("close", done);
+  });
+}

package/src/dev/openUrl.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { spawn } from "node:child_process";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+
+/**
+ * Open a URL in whatever browser the machine already prefers.
+ *
+ * **The default browser, and nothing cleverer.** No browser automation, no CDP, no launching a
+ * controlled profile — because the thing being opened sets a cookie, and a cookie is only useful in the
+ * browser the developer is actually looking at. Handing the OS a URL is also the only approach that
+ * works from a second profile or an incognito window, which is precisely the case that made pasting a
+ * cookie tedious in the first place.
+ *
+ * Detached and unref'd: the browser is not a child of the dev session. `pithy dev` exiting must not
+ * close a window someone is reading, and a browser that stays open must not keep the supervisor alive.
+ */
+
+/** The spawn seam — narrow to what this module drives, so a test asserts the argv rather than a browser. */
+export type OpenSpawn = (command: string, args: string[], options: { detached: boolean; stdio: "ignore" }) => OpenChild;
+
+/** The two events that settle an open: the child started, or it never did. */
+export interface OpenChild {
+  once: (event: "spawn" | "error", listener: (error: Error) => void) => unknown;
+  unref: () => unknown;
+}
+
+/** Everything {@link openUrl} needs. Both default to the real platform and the real `spawn`. */
+export interface OpenUrlOptions {
+  platform?: NodeJS.Platform;
+  spawn?: OpenSpawn;
+}
+
+/**
+ * The opener for one platform. macOS and Windows ship their own; everything else is `xdg-open`, which
+ * is the freedesktop standard and present on any Linux with a desktop session.
+ *
+ * The empty string on Windows is not noise: `start` reads its first quoted argument as the *window
+ * title*, so a URL passed without it is consumed as a title and nothing opens.
+ */
+export function openCommand(url: string, platform: NodeJS.Platform): { command: string; args: string[] } {
+  if (platform === "darwin") return { command: "open", args: [url] };
+  if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", url] };
+  return { command: "xdg-open", args: [url] };
+}
+
+/**
+ * Hand the URL to the platform opener.
+ *
+ * Settles on `spawn` or `error` — the child started, or it never did — and **not** on anything about
+ * what the browser then did. There is no signal for "a page rendered", and waiting for one would hang
+ * the supervisor. A spawn failure (no `xdg-open` on a headless box, most often) becomes a refusal
+ * carrying the URL, so the answer to "it did not open" is a line the developer can click.
+ */
+export function openUrl(url: string, options: OpenUrlOptions = {}): Promise<void> {
+  const platform = options.platform ?? process.platform;
+  const spawnChild = options.spawn ?? ((command, args, opts) => spawn(command, args, opts));
+  const { command, args } = openCommand(url, platform);
+
+  return new Promise<void>((resolve, reject) => {
+    const child = spawnChild(command, args, { detached: true, stdio: "ignore" });
+    child.once("spawn", () => resolve());
+    child.once("error", (error) => {
+      reject(
+        new InternalError({
+          message: "Could not open a browser.",
+          action: `Open ${url} yourself.`,
+          detail: `${command} failed: ${error.message}`,
+        }),
+      );
+    });
+    child.unref();
+  });
+}