@ultimat3/cli 1.0.0

package/src/dev-replicator.ts

@@ -0,0 +1,92 @@
+// Single responsibility: the `replicator` role under `x dev` — the one place the Postgres logical
+// replication feed is selected, locked and pumped into the transport. Everything it starts is what
+// a `ROLE=replicator` container starts; the only difference is that this process also runs the
+// roles reading the other end of that transport.
+
+import { describeEntities } from '@ultimat3/entity';
+import type { Replicator, Transport } from '@ultimat3/realtime';
+import {
+  createReplicator,
+  ReplicatorSlotHeldError,
+  replicatorLockKey,
+  selectChangeFeed,
+} from '@ultimat3/realtime';
+import type { DevServices, Env } from './dev-services';
+import { BadFlagError } from './errors';
+
+export interface StartReplicatorOptions {
+  readonly services: DevServices;
+  readonly env: Env;
+  readonly transport: Transport;
+}
+
+export interface RunningReplicator {
+  readonly replicator: Replicator;
+  /** The slot this process holds — the thing an operator greps for when two of these exist. */
+  readonly slot: string;
+  /** The env key that selected the feed, never the URL behind it: it carries a password. */
+  readonly detail: string;
+  stop(): Promise<void>;
+}
+
+/**
+ * PGlite is a single-process WASM database with no walsender, so `--role replicator` against the
+ * embedded default cannot ever work. Refused with the env var that makes it work rather than with
+ * "not a dev role", which is what this used to say and sent an agent looking for a flag instead of
+ * a database. Same code as before (`X_CLI_BAD_FLAG`) because it is the same invocation.
+ */
+const embeddedRefusal = (): BadFlagError =>
+  new BadFlagError({
+    flag: 'role',
+    command: 'dev',
+    reason:
+      'the replicator decodes a write-ahead log, and the embedded database is PGlite — it has ' +
+      'no walsender to decode',
+    fix: 'DATABASE_URL=postgres://user:password@localhost:5432/app x dev --role replicator',
+  });
+
+/**
+ * An entity list is the feed's filter, so an empty one is a replicator that decodes every change
+ * and forwards none. Refused here rather than inside the feed: this is the layer that knows the
+ * list came from the app's own registry, so it can name the command that adds to it.
+ */
+const noEntitiesRefusal = (): BadFlagError =>
+  new BadFlagError({
+    flag: 'role',
+    command: 'dev',
+    reason: 'no entities are registered, so the replicator would decode changes nothing matches',
+    fix: 'x g entity Post title:text — then x dev --role replicator',
+  });
+
+/**
+ * Lock first, feed second. A replicator that opened its slot before losing the lock race would
+ * have already consumed WAL the holder is responsible for, and `pg_try_advisory_lock` is the only
+ * thing standing between two containers and every change delivered twice.
+ */
+export async function startReplicator(options: StartReplicatorOptions): Promise<RunningReplicator> {
+  if (options.services.db.mode === 'embedded') throw embeddedRefusal();
+  const entities = describeEntities().map((entity) => entity.name);
+  if (entities.length === 0) throw noEntitiesRefusal();
+
+  const selection = selectChangeFeed(options.env, { entities });
+  const slot = selection.slot ?? '';
+  const replicator = createReplicator({
+    feed: selection.feed,
+    transport: options.transport,
+    lock: selection.lock,
+  });
+  // `start()` answers `false` for the one condition that is not this process's fault. A dev boot
+  // has nothing to fail over to — the standby loop belongs to a container an orchestrator
+  // restarts — so it is terminal here, with the code the topology docs already promised.
+  if (!(await replicator.start())) {
+    throw new ReplicatorSlotHeldError({ key: replicatorLockKey(slot) });
+  }
+  return {
+    replicator,
+    slot,
+    detail: selection.detail,
+    async stop() {
+      await replicator.stop();
+    },
+  };
+}

package/src/dev-roles.ts

@@ -0,0 +1,246 @@
+// Running the roles. In production these are separate containers selected by `ROLE`; `x dev`
+// runs them in one process by starting the same framework objects each container starts, so a
+// job that only works when awaited inline still fails here.
+//
+// `migrate` is absent on purpose: it is run-once (`x db migrate`), not a process. `replicator` is
+// selectable but not default — it takes a replication slot on a shared database, which is not
+// something every `x dev` in a team should do to the same server by simply starting.
+
+import type { Role } from '@ultimat3/core';
+import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
+import type { Route, ServerHandle } from '@ultimat3/http';
+import { createServer, defineHttpConfig } from '@ultimat3/http';
+import type { Scheduler, Worker } from '@ultimat3/jobs';
+import { createScheduler, createWorker } from '@ultimat3/jobs';
+import { listQueries } from '@ultimat3/query';
+import {
+  ChannelHub,
+  createSyncNode,
+  LiveQueryRegistry,
+  listenSyncNode,
+  liveQueryDefinition,
+  PresenceRegistry,
+  RingChangeBuffer,
+  SocketRegistry,
+} from '@ultimat3/realtime';
+import { devHooks } from './dev-hooks';
+import type { RunningReplicator } from './dev-replicator';
+import { startReplicator } from './dev-replicator';
+import type { RunningServices } from './dev-runtime';
+import type { Env } from './dev-services';
+import { BadFlagError } from './errors';
+
+/** The roles `x dev` starts when `--role` names none, in boot order. */
+export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
+
+/**
+ * What `--role` accepts. The replicator is here but not in `DEV_ROLES`: opt-in, because it takes
+ * the one replication slot a database has, and a default that did that would mean two developers
+ * pointed at one staging database silently fighting over it.
+ */
+export const SELECTABLE_ROLES: readonly Role[] = [...DEV_ROLES, 'replicator'];
+
+export interface StartRolesOptions {
+  readonly roles: readonly Role[];
+  readonly port: number;
+  readonly buildId: string;
+  readonly runtime: RunningServices;
+  /** Routes the web role serves: `/_x`, the actions, the pages. */
+  readonly routes: readonly Route[];
+  /** The process environment, for the roles that resolve a driver from it. */
+  readonly env: Env;
+}
+
+export interface RunningRoles {
+  readonly roles: readonly Role[];
+  /** `http://…` once the web role is up; null when it was not selected. */
+  readonly url: string | null;
+  /** Where the sync role accepts websockets; null when it was not selected. */
+  readonly syncUrl: string | null;
+  readonly server: ServerHandle | null;
+  readonly worker: Worker | null;
+  readonly scheduler: Scheduler | null;
+  /** The slot and feed this process holds; null when the replicator was not selected. */
+  readonly replicator: RunningReplicator | null;
+  stop(): Promise<void>;
+}
+
+/**
+ * `--role web,worker` picks a subset. An unknown or out-of-scope role is a flag error with the
+ * working invocation in the fix line, never a silently ignored value — which is what it was.
+ */
+export function selectRoles(flag: string | undefined): readonly Role[] {
+  if (flag === undefined || flag.trim().length === 0) return DEV_ROLES;
+  const wanted = flag
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  const selected: Role[] = [];
+  for (const name of wanted) {
+    if (!isRole(name)) {
+      throw new BadFlagError({
+        flag: 'role',
+        command: 'dev',
+        reason: `"${name}" is not a role (known: ${ROLES.join(', ')})`,
+        fix: `x dev --role ${DEV_ROLES.join(',')}`,
+      });
+    }
+    if (!SELECTABLE_ROLES.includes(name)) {
+      throw new BadFlagError({
+        flag: 'role',
+        command: 'dev',
+        reason: `"${name}" does not run under x dev (it runs once, as \`x db migrate\`)`,
+        fix: `x dev --role ${DEV_ROLES.join(',')}`,
+      });
+    }
+    if (!selected.includes(name)) selected.push(name);
+  }
+  return SELECTABLE_ROLES.filter((role) => selected.includes(role));
+}
+
+function startWeb(options: StartRolesOptions): ServerHandle {
+  return createServer({
+    routes: options.routes,
+    role: 'web',
+    hooks: devHooks(),
+    config: defineHttpConfig({
+      port: options.port,
+      dev: true,
+      buildId: options.buildId,
+      hostname: 'localhost',
+    }),
+  }).start();
+}
+
+/**
+ * Every read the app declared `live: true` becomes a subscribable query on this node, through
+ * `@ultimat3/realtime`'s own bridge. A registry with nothing in it answers every live `subscribe`
+ * with "no live query registered", which is a working socket serving no reads — and it is what
+ * kept the row gate that decides per subscriber from ever running outside a unit test.
+ *
+ * The context is the node's, and it carries no actor: it supplies the services and the clock the
+ * shared read needs, never an authority. Who may subscribe, and which rows they see, is decided
+ * per socket at subscribe time and again for every row of every delivery.
+ */
+function registerLiveQueries(options: StartRolesOptions): LiveQueryRegistry {
+  const registry = new LiveQueryRegistry({
+    source: new RingChangeBuffer(),
+    // A withheld row is a metric, never a frame and never an error: telling a client "there is a
+    // row you may not see" is the leak the gate exists to prevent.
+    onRowDenied: (event) => logger.debug('live.rows_denied', { ...event }),
+  });
+  const ctx = createContext({ role: 'sync', buildId: options.buildId });
+  for (const target of listQueries()) {
+    if (target.isLive) registry.register(liveQueryDefinition(target, { ctx }));
+  }
+  return registry;
+}
+
+/**
+ * The sync role owns its own socket: websockets and the request pipeline drain differently.
+ *
+ * Port 0 is passed straight through rather than incremented — `+ 1` would ask the kernel for
+ * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
+ * never a string built from the port that was requested.
+ */
+async function startSync(
+  options: StartRolesOptions,
+): Promise<{ url: string; stop: () => Promise<void> }> {
+  const sockets = new SocketRegistry();
+  const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
+  const node = createSyncNode({
+    hub,
+    registry: registerLiveQueries(options),
+    transport: options.runtime.transport,
+    buildId: options.buildId,
+    sockets,
+    // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
+    // list at all — the KV bucket the transport just created would hold nothing and every `sync`
+    // container would run a presence-less protocol. It reads and writes `transport.shared`, so it
+    // is exactly as multi-node as the transport behind it: in-process here, the bucket under NATS.
+    presence: new PresenceRegistry({
+      transport: options.runtime.transport,
+      hub,
+      ttlMs: options.runtime.presenceTtlMs,
+    }),
+  });
+  await node.start();
+  try {
+    const listener = listenSyncNode(node, { port: options.port === 0 ? 0 : options.port + 1 });
+    return {
+      url: listener.url,
+      stop: async () => {
+        listener.stop();
+        await node.stop();
+      },
+    };
+  } catch (error) {
+    await node.stop();
+    throw error;
+  }
+}
+
+export async function startRoles(options: StartRolesOptions): Promise<RunningRoles> {
+  const selected = options.roles;
+  // Roles bind sockets in order, so a role that fails to start has to release the ones before it.
+  // Without this a failed `sync` leaves the web server bound and unreachable by any caller.
+  const started: (() => Promise<void>)[] = [];
+  try {
+    const server = selected.includes('web') ? startWeb(options) : null;
+    if (server !== null) started.push(() => server.stop());
+
+    const sync = selected.includes('sync') ? await startSync(options) : null;
+    if (sync !== null) started.push(sync.stop);
+
+    const worker = selected.includes('worker')
+      ? createWorker({
+          driver: options.runtime.jobs,
+          context: () => createContext({ role: 'worker', buildId: options.buildId }),
+        })
+      : null;
+    worker?.start();
+    if (worker !== null) started.push(() => worker.stop('x dev stopped'));
+
+    const scheduler = selected.includes('scheduler')
+      ? createScheduler({ driver: options.runtime.jobs })
+      : null;
+    scheduler?.start();
+    if (scheduler !== null) started.push(() => scheduler.stop());
+
+    // Last, and only after the transport it publishes to exists: a replicator started ahead of the
+    // sync node would decode changes with nothing subscribed to receive them, and the slot it
+    // holds is the one resource here another process can be locked out of.
+    const replicator = selected.includes('replicator')
+      ? await startReplicator({
+          services: options.runtime.services,
+          env: options.env,
+          transport: options.runtime.transport,
+        })
+      : null;
+    if (replicator !== null) started.push(() => replicator.stop());
+
+    return {
+      roles: selected,
+      url: server === null ? null : server.url(),
+      syncUrl: sync?.url ?? null,
+      server,
+      worker,
+      scheduler,
+      replicator,
+      async stop() {
+        // Reverse boot order, so the slot is released before the bus it published to closes.
+        await replicator?.stop();
+        await scheduler?.stop();
+        await worker?.stop('x dev stopped');
+        await sync?.stop();
+        await server?.stop();
+      },
+    };
+  } catch (error) {
+    for (const stop of started.reverse()) {
+      // The role that refused to start is the failure worth reporting, not a stop on the way out.
+      await stop().catch(() => undefined);
+    }
+    throw error;
+  }
+}

package/src/dev-runtime.ts

@@ -0,0 +1,203 @@
+// Starting the services `dev-services.ts` resolved. Resolution answers "which database"; this
+// answers "it is running, and every ambient accessor in the framework now points at it" — so
+// `db()`, `jobDriver()`, `mailDriver()` and the realtime transport are the objects a production
+// boot installs, only backed by embedded drivers.
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PurgeDriver } from '@ultimat3/cache';
+import {
+  createCdnTier,
+  isNoopPurgeDriver,
+  registerTier,
+  resetTiers,
+  selectPurgeDriver,
+} from '@ultimat3/cache';
+import type { EventBus, JobDriver } from '@ultimat3/jobs';
+import { createMemoryEventBus, setEventBus } from '@ultimat3/jobs';
+import type { MailDriver } from '@ultimat3/mail';
+import { isMemoryDriver, resetMailDriver, selectMailDriver, setMailDriver } from '@ultimat3/mail';
+import type { Transport, TransportSelection } from '@ultimat3/realtime';
+import { selectTransport } from '@ultimat3/realtime';
+import type { Storage } from '@ultimat3/storage';
+import { defineStorage, localDriver } from '@ultimat3/storage';
+import type { DevDbClient } from './dev-queue';
+import { startQueue } from './dev-queue';
+import type { DevServices, Env } from './dev-services';
+import { msg } from './messages';
+
+export interface RunningServices {
+  readonly services: DevServices;
+  readonly db: DevDbClient;
+  readonly jobs: JobDriver;
+  readonly events: EventBus;
+  readonly transport: Transport;
+  readonly storage: Storage;
+  readonly mail: MailDriver;
+  /**
+   * Which env key selected the transport, or why nothing was selected. The credential itself is
+   * never carried: `SMTP_URL` holds a password, and this string reaches the boot line and `--json`.
+   */
+  readonly mailDetail: string;
+  /** Same rule as `mailDetail`: the env key that selected the bus, never the url behind it. */
+  readonly transportDetail: string;
+  /**
+   * What the sync role must give `PresenceRegistry`. It travels with the transport because the KV
+   * bucket's age limit was derived from it — a registry given a longer TTL than the bucket honours
+   * would show members leaving that never left.
+   */
+  readonly presenceTtlMs: number;
+  readonly purge: PurgeDriver;
+  /** Same rule as `mailDetail`: the env key that selected the CDN, never the token behind it. */
+  readonly purgeDetail: string;
+  stop(): Promise<void>;
+}
+
+/**
+ * `mail=embedded` is the honest report for a process that caught the message instead of sending
+ * it — the same vocabulary the other three bindings use, so an operator reading a boot line sees
+ * at a glance that this replica delivers nothing. This is the machine half: `x dev --json` carries
+ * it verbatim and `wiki/Configuration.md` documents it, so it is a fixed status value and NOT a
+ * catalog lookup — a translated boot line must never move a field a script parses. `mailLabel` is
+ * the human half.
+ */
+export function describeMail(runtime: RunningServices): string {
+  return isMemoryDriver(runtime.mail)
+    ? 'mail=embedded'
+    : `mail=external(${runtime.mail.name} via ${runtime.mailDetail})`;
+}
+
+/**
+ * `cdn=none` rather than `cdn=embedded`: there is no embedded CDN, and a process with no edge in
+ * front of it purges nothing. Saying "embedded" would read as a fifth service this boot started.
+ * Machine half, same rule as `describeMail`; `cdnLabel` is what a human reads.
+ */
+export function describeCdn(runtime: RunningServices): string {
+  return isNoopPurgeDriver(runtime.purge)
+    ? 'cdn=none'
+    : `cdn=external(${runtime.purge.name} via ${runtime.purgeDetail})`;
+}
+
+/**
+ * The boot line's mail label. Same fact as `describeMail`, through the catalog, because this string
+ * is rendered to a person and every rendered string in the CLI is a `messages.ts` key — the status
+ * value stays where `--json` can depend on it.
+ */
+export function mailLabel(runtime: RunningServices): string {
+  return isMemoryDriver(runtime.mail)
+    ? msg('cli.dev.mail.embedded')
+    : msg('cli.dev.mail.external', { driver: runtime.mail.name, detail: runtime.mailDetail });
+}
+
+/** The boot line's CDN label, for the reason `mailLabel` gives. */
+export function cdnLabel(runtime: RunningServices): string {
+  return isNoopPurgeDriver(runtime.purge)
+    ? msg('cli.dev.cdn.none')
+    : msg('cli.dev.cdn.external', { driver: runtime.purge.name, detail: runtime.purgeDetail });
+}
+
+const FILE_SCHEME = 'file://';
+
+function startStorage(services: DevServices): Storage {
+  const binding = services.storage;
+  const root =
+    binding.mode === 'embedded'
+      ? binding.url.slice(FILE_SCHEME.length)
+      : join(services.stateDir, 'storage');
+  mkdirSync(root, { recursive: true });
+  return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
+}
+
+/**
+ * Release what has already started, newest first, and return every failure instead of throwing on
+ * the first: a step that rejects must not skip the ones after it, or one transport that will not
+ * close strands the CDN tier, the ambient mail driver and the queue in the next boot of this
+ * process. The two callers differ only in what they do with the failures.
+ */
+async function release(steps: readonly (() => void | Promise<void>)[]): Promise<unknown[]> {
+  const failures: unknown[] = [];
+  for (const step of [...steps].reverse()) {
+    try {
+      await step();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  return failures;
+}
+
+export async function startServices(services: DevServices, env: Env): Promise<RunningServices> {
+  // Before the queue: selection is pure — it parses `SMTP_URL` and builds a transport, it does
+  // not dial. A typo'd credential must fail on the spot rather than after PGlite has started and
+  // been unwound again, and it must fail at boot rather than on the first mail nobody receives.
+  const selection = selectMailDriver(env);
+  // Same reason, same place: building a purge driver reads env and dials nothing, so a half-set
+  // `FASTLY_API_TOKEN` without its service id fails here rather than on the first stale page.
+  const cdn = selectPurgeDriver(env);
+  // Third of the same kind. `NATS_URL` selects the bus rather than quietly keeping the in-process
+  // one — dev pointed at compose is a parity check, and a parity check that silently ran the
+  // embedded driver is worse than none. Which transport, which KV bucket and which presence TTL is
+  // `@ultimat3/realtime`'s decision, and it is the same call a `ROLE=sync` container makes, so this
+  // process cannot resolve the bus differently from the container it stands in for.
+  const bus: TransportSelection = selectTransport(env);
+  const queue = await startQueue(services);
+  const { db, jobs } = queue;
+  // Boot is a sequence of external resources, and every step after the first can reject — the
+  // queue is already up, so from here an unwind must release it exactly like everything after it.
+  const started: (() => void | Promise<void>)[] = [() => queue.stop()];
+  try {
+    const events = createMemoryEventBus();
+    setEventBus(events);
+    // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
+    // first change nobody receives, and the socket is a resource the unwind below has to release.
+    await bus.connect();
+    started.push(() => bus.transport.close());
+    const storage = startStorage(services);
+    // With no credential this is the memory driver: caught, not sent, so the `/_x` mail panel can
+    // show what a template renders in every locale without a mailbox or a message escaping to a
+    // real address. `SMTP_URL` or `RESEND_API_KEY` makes it a real transport instead — the same
+    // "an unset variable means the embedded default" law the other three bindings follow.
+    const mail = selection.driver;
+    setMailDriver(mail);
+    started.push(() => resetMailDriver());
+    // Registered only when a credential named a real edge. A noop tier would put a `cdn` line in
+    // every invalidation report claiming keys an edge that does not exist had accepted — and the
+    // `/_x` cache panel renders those reports, so the lie would be the thing an agent reads.
+    // Released with `resetTiers()`, which drops the whole registry: this boot is the only thing
+    // that registers one, and a tier left behind would purge for a process that has stopped.
+    const purging = !isNoopPurgeDriver(cdn.driver);
+    if (purging) {
+      registerTier(createCdnTier({ purge: cdn.driver }));
+      started.push(() => resetTiers());
+    }
+
+    return {
+      services,
+      db,
+      jobs,
+      events,
+      transport: bus.transport,
+      storage,
+      mail,
+      mailDetail: selection.detail,
+      transportDetail: bus.detail,
+      presenceTtlMs: bus.presenceTtlMs,
+      purge: cdn.driver,
+      purgeDetail: cdn.detail,
+      // The same list the boot unwind uses, in the same reverse order, so a service added to the
+      // boot is released by both paths — a second copy of these steps is how one of them came to
+      // release three things and the other four. A stop that fails says so, unlike that unwind:
+      // the FIRST failure is rethrown because it is the cause and the rest are its consequences,
+      // and every step still runs, so a refused shutdown never leaks into the next boot.
+      async stop() {
+        const failures = await release(started);
+        if (failures.length > 0) throw failures[0];
+      },
+    };
+  } catch (error) {
+    // The rejection that started the unwind is the one worth reporting; a cleanup failure under it
+    // is noise, so these are collected and dropped rather than allowed to replace the cause.
+    await release(started);
+    throw error;
+  }
+}

package/src/dev-services.ts

@@ -0,0 +1,75 @@
+// Service resolution for `x dev`. No Docker, no env scavenger hunt: an unset variable means the
+// embedded default, and the resolved set is printed at boot so there is never a question about
+// which database a running process is talking to.
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type ServiceMode = 'embedded' | 'external';
+
+export interface ServiceBinding {
+  readonly name: 'db' | 'events' | 'storage';
+  readonly mode: ServiceMode;
+  readonly url: string;
+  /** What the embedded default is, so `x doctor` can explain the difference. */
+  readonly detail: string;
+}
+
+export interface DevServices {
+  readonly db: ServiceBinding;
+  readonly events: ServiceBinding;
+  readonly storage: ServiceBinding;
+  readonly stateDir: string;
+}
+
+export type Env = Readonly<Record<string, string | undefined>>;
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim().length === 0 ? undefined : value;
+
+/**
+ * Embedded Postgres is PGlite on disk under `.x/`, so a restart keeps the data and a `x db reset`
+ * is a directory delete rather than a container dance.
+ */
+export function resolveServices(root: string, env: Env): DevServices {
+  const stateDir = join(root, '.x');
+  mkdirSync(stateDir, { recursive: true });
+  const databaseUrl = nonEmpty(env['DATABASE_URL']);
+  const natsUrl = nonEmpty(env['NATS_URL']);
+  const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
+  return {
+    stateDir,
+    db:
+      databaseUrl === undefined
+        ? {
+            name: 'db',
+            mode: 'embedded',
+            url: `pglite://${join(stateDir, 'pgdata')}`,
+            detail: 'PGlite in this process — set DATABASE_URL to use a real Postgres',
+          }
+        : { name: 'db', mode: 'external', url: databaseUrl, detail: 'DATABASE_URL' },
+    events:
+      natsUrl === undefined
+        ? {
+            name: 'events',
+            mode: 'embedded',
+            url: 'inproc://events',
+            detail: 'in-process fanout — set NATS_URL to use NATS',
+          }
+        : { name: 'events', mode: 'external', url: natsUrl, detail: 'NATS_URL' },
+    storage:
+      s3Endpoint === undefined
+        ? {
+            name: 'storage',
+            mode: 'embedded',
+            url: `file://${join(stateDir, 'storage')}`,
+            detail: 'local directory — set S3_ENDPOINT to use S3',
+          }
+        : { name: 'storage', mode: 'external', url: s3Endpoint, detail: 'S3_ENDPOINT' },
+  };
+}
+
+export const describeServices = (services: DevServices): string =>
+  [services.db, services.events, services.storage]
+    .map((binding) => `${binding.name}=${binding.mode}`)
+    .join(' ');