feat(workers): bring the command family's output onto one shape (#6389)

## Summary

The workers commands each grew their own way of saying "here is what
happened" and "here is what to run next". This settles them on the
shapes the rest of the legacy shell already uses. **No command changes
what it does** — this is output, plus the coverage that pins it.

- **Success trailers.** "What to run next" lines in `new`, `push`,
`delete` and `status` move to `emitSuccessTrailer`, the way `stop`,
`bootstrap`, `migration repair` and `gen signing-key` already emit
theirs: printed once at the end of the run rather than inline, so a
multi-worker push does not bury each worker's hint under the next
worker's output. The commands within them are aqua'd.
- **`list` advisories.** Both take the yellow `WARNING:` prefix and the
two-line consequence shape `start`'s Docker notice uses. Each was one
long sentence that re-flowed at a different width, directly under a
table that lines its columns up.
- **`list` drops the URL column.** Every worker's URL is the same host
and prefix with the name on the end, and carrying it pushed the table
past 130 columns for one derivable field — `renderGlamourTable` sizes
each column to its widest cell and never wraps. `status` still renders
it vertically, and every machine format still carries `url` per worker.
- **`push` progress.** Per-worker announcements are counted (`Deploying
Worker 1/2:`) and a multi-worker run closes with a summary. Each worker
takes minutes; the name alone said nothing about how much of the run was
left.
- **`push` names what it never attempted.** The loop stops at the first
failure and the error only names the worker that broke, leaving the rest
to be reconstructed from argument order. On stderr in every format,
machine ones included: that run is a CI run.
- **`--project-ref` survives into `push`'s retry suggestions**, via the
`legacyWorkersProjectRefSuffix` helper `status` and `delete` already
use. A suggestion is copy-pasted verbatim, so one that dropped it
re-resolved against whatever this checkout was linked to.

Also adds unit coverage for `legacyRenderWorkerDetails`, pins the shared
`-o env` refusal, and adds a guard (own commit) asserting no legacy
boolean flag ships required — `Flag.boolean` alone builds a *required*
param, and nothing in the existing suites notices.

## Stack

On top of the `workers new` name prompt (#6349). Above it: `workers
logs` (#6410), then `push --wait` (#6371) last, so the output work can
ship independently of both.

## Linked issue


[FUNC-851](https://linear.app/supabase/issue/FUNC-851/general-output-polish).
Supabase maintainer, exempt from the `open-for-contribution` flow.

## Checklist

- [x] The PR title follows [Conventional
Commits](https://www.conventionalcommits.org/)

---------

Co-authored-by: kanad <git@kanad.dev>

Author: johnstonmatt

apps/cli/src/legacy/cli/legacy-boolean-flag-defaults.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { Primitive, type Command } from "effect/unstable/cli";
+import {
+  legacyCommandInternals,
+  legacyFlattenSubcommands,
+  legacyUserGlobalFlagParams,
+} from "../docs/legacy-docs-introspection.ts";
+import { legacyUnwrapParam } from "../shared/legacy-param-introspection.ts";
+import { legacyRoot } from "./root.ts";
+
+/**
+ * `Flag.boolean(name)` builds a bare `Single` param, and a bare `Single` is
+ * *required* — omitting it fails the whole command with a missing-flag error
+ * before the handler ever runs. Every boolean flag therefore has to be closed
+ * off with `Flag.withDefault(false)` or `Flag.optional`.
+ *
+ * Nothing else catches this: handler integration tests build their flags record
+ * directly, so they never touch the parser, and the required-ness is invisible
+ * to the type checker because a required boolean flag still infers as
+ * `boolean`. The flag only misbehaves when a real invocation omits it, which is
+ * precisely the invocation no handler test makes — so the guard walks the
+ * command tree instead of waiting for a command to be exercised end to end.
+ */
+
+/**
+ * The published getter for a primitive's kind — `Primitive.getTypeName`, whose
+ * own doc example pins `Primitive.boolean` to `"boolean"`. Reading
+ * `primitiveType._tag` instead would couple this guard to effect's runtime
+ * representation, which this repo forbids in tests as well as in source.
+ *
+ * Derived from `Primitive.boolean` rather than written as the literal
+ * `"boolean"`: were that name to change upstream, a hardcoded literal would
+ * match nothing and leave the guard silently passing every command, which is
+ * the one failure mode a regression test must not have.
+ */
+const BOOLEAN_TYPE_NAME = Primitive.getTypeName(Primitive.boolean);
+
+function booleanFlagsRequiringAValue(command: Command.Command.Any): ReadonlyArray<string> {
+  const internals = legacyCommandInternals(command);
+  // All three parameter sets a command can be parsed with, not just its own:
+  // `Command.withSharedFlags` puts inherited flags on `contextConfig`, and the
+  // root's persistent flags arrive as `globalFlags`. A bare boolean introduced
+  // through either would break every command that inherits it while a guard
+  // reading only `config.flags` stayed green.
+  const params = [
+    ...internals.config.flags,
+    ...internals.contextConfig.flags,
+    ...legacyUserGlobalFlagParams(command),
+  ];
+
+  // Throws rather than skipping if effect's internal shape moves, so this
+  // cannot quietly degrade into a test that inspects nothing.
+  const own = params.flatMap((flag) => {
+    const unwrapped = legacyUnwrapParam(flag);
+    if (unwrapped === undefined) {
+      throw new Error(`Unrecognizable flag param on "${command.name}".`);
+    }
+    const { single, isOptional } = unwrapped;
+    return Primitive.getTypeName(single.primitiveType) === BOOLEAN_TYPE_NAME && !isOptional
+      ? [`${command.name} --${single.name}`]
+      : [];
+  });
+
+  return [...own, ...legacyFlattenSubcommands(command).flatMap(booleanFlagsRequiringAValue)];
+}
+
+describe("legacy boolean flag wiring", () => {
+  it("gives every boolean flag a default, so omitting it is not a parse error", () => {
+    expect(booleanFlagsRequiringAValue(legacyRoot)).toEqual([]);
+  });
+});

apps/cli/src/legacy/commands/experimental/workers/delete/SIDE_EFFECTS.md

@@ -77,11 +77,17 @@ wrapper emits for every command.
 
 ## Output Formats
 
-| Mode                          | stdout                                                                                        | stderr                                        |
-| ----------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| text (default)                | the confirmation prompt, then what was deleted and kept                                       | that nothing local was kept, when nothing was |
-| `--output-format json`        | one structured result carrying `worker_name`, `project_ref`, `kept_*`                         | as above                                      |
-| `--output-format stream-json` | the same result as a single terminal event                                                    | as above                                      |
-| `-o json` / `yaml` / `toml`   | the same payload in that encoding, and nothing else                                           | as above                                      |
-| `-o pretty` / `table` / `csv` | the text rendering — these fall through rather than encoding                                  | as above                                      |
-| `-o env`                      | refused **before** the DELETE; discovering it at emit time deleted the worker and then failed | the error                                     |
+| Mode                          | stdout                                                                                        | stderr                                                              |
+| ----------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| text (default)                | the confirmation prompt, then what was deleted and kept                                       | that nothing local was kept when nothing was, and the redeploy hint |
+| `--output-format json`        | one structured result carrying `worker_name`, `project_ref`, `kept_*`                         | neither — both are text-only                                        |
+| `--output-format stream-json` | the same result as a single terminal event                                                    | neither — both are text-only                                        |
+| `-o json` / `yaml` / `toml`   | the same payload in that encoding, and nothing else                                           | neither — both are text-only                                        |
+| `-o pretty` / `table` / `csv` | the text rendering — these fall through rather than encoding                                  | both, as in text                                                    |
+| `-o env`                      | refused **before** the DELETE; discovering it at emit time deleted the worker and then failed | the error                                                           |
+
+A structured emission is the end of the run: the handler returns at
+`legacyEmitWorkersMachineOutput` or at `output.success`, so nothing in the text
+branch below it — the kept-nothing notice and the redeploy trailer — is reached.
+`-o pretty`, `table` and `csv` are the exception, since they encode nothing and
+fall through to that same text branch.

apps/cli/src/legacy/commands/experimental/workers/delete/delete.handler.ts

@@ -1,5 +1,6 @@
 import { Effect, Option } from "effect";
 import { Output } from "../../../../../shared/output/output.service.ts";
+import { emitSuccessTrailer } from "../../../../../shared/cli/success-trailer.ts";
 import { legacyAqua } from "../../../../shared/legacy-colors.ts";
 import { legacyRenderWorkerDetails } from "../workers.format.ts";
 import {
@@ -232,8 +233,9 @@ export const legacyWorkersDelete = Effect.fn("legacy.experimental.workers.delete
         // alone is not enough to redeploy from, so `push` would fail on the very
         // command this line recommends.
         if (keptSource !== undefined) {
-          yield* output.raw(
-            `Redeploy it with supabase experimental workers push ${name}${refSuffix}.\n`,
+          // Trailer, like every other "what to run next" line in this shell.
+          yield* emitSuccessTrailer(
+            `Redeploy it with ${legacyAqua(`supabase experimental workers push ${name}${refSuffix}`)}.\n`,
           );
         }
       } else {

apps/cli/src/legacy/commands/experimental/workers/delete/delete.integration.test.ts

@@ -72,13 +72,14 @@ describe("legacy workers delete", () => {
       // Nothing local is touched — that is what makes `push` a one-command undo.
       expect(existsSync(join(repo.dir, "supabase", "workers", "api", "index.js"))).toBe(true);
       expect(readFileSync(join(repo.dir, "supabase", "config.toml"), "utf8")).toBe(CONFIG);
-      expect(out.stdoutText).toContain("supabase experimental workers push api");
+      // The redeploy hint is a success trailer, which lands on stderr.
+      expect(out.stderrText).toContain("supabase experimental workers push api");
     }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
   });
 
-  // The refusal used to live at emit time, which on this command is *after* the
-  // DELETE: `--yes -o env` removed the worker and then exited non-zero with no
-  // payload, which a script reads as "the delete failed" and may retry.
+  // The refusal has to precede the DELETE. At emit time `--yes -o env` would
+  // remove the worker and then exit non-zero with no payload, which a script
+  // reads as "the delete failed" and may retry.
   // Deletion never touches local files, so a malformed local config has no
   // business standing between the user and a worker they named explicitly.
   it.live("deletes a remote worker despite an unparseable local config", () => {
@@ -327,8 +328,8 @@ describe("legacy workers delete", () => {
     }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
   });
 
-  // `interactive` follows stdout, so a plain `>` redirect reaches this branch
-  // even from a live terminal — the case that used to delete without asking.
+  // `interactive` follows stdout, so a plain `>` redirect reaches this branch even
+  // from a live terminal — the case where deleting without asking would be worst.
   it.live("refuses when stdout is redirected and no --yes was given", () => {
     const repo = project();
     const { layer, http } = setupLegacyWorkers({
@@ -541,6 +542,63 @@ describe("legacy workers delete", () => {
     }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
   });
 
+  it.live("pluralizes the live instance count in the confirmation", () => {
+    const repo = project();
+    const { layer, out } = setupLegacyWorkers({
+      workdir: repo.dir,
+      promptTextResponses: ["api"],
+      routes: {
+        ...routes,
+        [getRoute]: {
+          status: 200,
+          body: {
+            data: workerResource({
+              name: "api",
+              instances: 3,
+              instanceCounts: { declared: 3, live: 2, ready: 2, stale: 0 },
+            }),
+          },
+        },
+      },
+    });
+
+    return Effect.gen(function* () {
+      yield* legacyWorkersDelete({ name: "api", projectRef: Option.none() });
+
+      expect(out.stdoutText).toContain("2 running instances will be terminated");
+    }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
+  });
+
+  // Scaled to zero: there is a tally, and it says nothing is running. Warning
+  // about terminated instances there would invent a consequence.
+  it.live("promises no terminations when nothing is running", () => {
+    const repo = project();
+    const { layer, out } = setupLegacyWorkers({
+      workdir: repo.dir,
+      promptTextResponses: ["api"],
+      routes: {
+        ...routes,
+        [getRoute]: {
+          status: 200,
+          body: {
+            data: workerResource({
+              name: "api",
+              instances: 2,
+              instanceCounts: { declared: 2, live: 0, ready: 0, stale: 0 },
+            }),
+          },
+        },
+      },
+    });
+
+    return Effect.gen(function* () {
+      yield* legacyWorkersDelete({ name: "api", projectRef: Option.none() });
+
+      expect(out.stdoutText).toContain("permanently deletes");
+      expect(out.stdoutText).not.toContain("will be terminated");
+    }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
+  });
+
   // An orphan — deployed from another checkout — has no local entry and no local
   // directory, so there is nothing that was "kept" and `push` has no source to
   // redeploy from.
@@ -604,7 +662,7 @@ describe("legacy workers delete", () => {
     }).pipe(Effect.provide(layer), Effect.ensuring(Effect.sync(repo.cleanup)));
   });
 
-  // Deletion never reads the local source, so a `source` that no longer resolves
+  // Deletion never reads the local source, so a `source` that does not resolve
   // inside the project must not block removing the remote worker.
   it.live("deletes the remote worker even when the configured source is unusable", () => {
     const repo = project('project_id = "demo"\n\n[workers.api]\nsource = "../../elsewhere"\n');

apps/cli/src/legacy/commands/experimental/workers/list/SIDE_EFFECTS.md

@@ -67,3 +67,7 @@ wrapper emits for every command.
 | `-o json` / `yaml` / `toml`   | the same payload in that encoding, and nothing else                                                      | as above                                             |
 | `-o pretty` / `table` / `csv` | the text rendering — these fall through rather than encoding                                             | as above                                             |
 | `-o env`                      | refused before any request; the payload carries a `workers` array a flat `KEY=value` list cannot express | the error                                            |
+
+The text table omits each worker's URL — it is the same host and prefix on
+every row, and carrying it made the table 137 columns wide. Every machine
+format still carries `url` per worker, and `workers status` renders it.

apps/cli/src/legacy/commands/experimental/workers/list/list.handler.ts

@@ -1,5 +1,7 @@
 import { Effect } from "effect";
 import { Output } from "../../../../../shared/output/output.service.ts";
+import { legacyAqua, legacyYellow } from "../../../../shared/legacy-colors.ts";
+import { displayPath } from "../../../../../shared/workers/worker-paths.ts";
 import { renderGlamourTable } from "../../../../output/legacy-glamour-table.ts";
 import { legacyEmitWorkersMachineOutput, legacyRejectWorkersEnvOutput } from "../workers.output.ts";
 import { LegacyPlatformApi } from "../../../../auth/legacy-platform-api.service.ts";
@@ -28,7 +30,15 @@ import type { LegacyWorkersListFlags } from "./list.command.ts";
  * count from the spec. `status` is where the live tally lives.
  */
 
-const HEADERS = ["NAME", "RUNTIME", "SIZE", "STATE", "INSTANCES", "URL"] as const;
+/**
+ * No URL column. Every worker's URL is the same 40-odd characters of host and
+ * prefix with the name on the end, which pushed the table past 130 columns to
+ * carry one derivable field — `renderGlamourTable` sizes each column to its
+ * widest cell and never wraps. `workers status` renders it, vertically, for the
+ * same reason (see `workers.format.ts`), and every machine format still carries
+ * `url` per worker.
+ */
+const HEADERS = ["NAME", "RUNTIME", "SIZE", "STATE", "INSTANCES"] as const;
 
 interface WorkerRow {
   readonly name: string;
@@ -68,14 +78,21 @@ function runtimeLabel(row: WorkerRow): string {
   return runtimeLabelFor(row) ?? "-";
 }
 
+/**
+ * `api is` / `api, box are` — the subject of both advisories below, which only
+ * ever differ in the verb.
+ */
+function nameList(names: ReadonlyArray<string>): string {
+  return `${names.join(", ")} ${names.length === 1 ? "is" : "are"}`;
+}
+
 function toCells(row: WorkerRow): ReadonlyArray<string> {
   return [
     row.name,
     runtimeLabel(row),
     row.deployed === undefined ? "-" : formatApiSize(row.deployed.spec.size),
     stateLabel(row),
     row.deployed === undefined ? "-" : String(row.deployed.spec.instances),
-    row.url ?? "-",
   ];
 }
 
@@ -165,7 +182,7 @@ export const legacyWorkersList = Effect.fn("legacy.experimental.workers.list")(f
 
     if (rows.length === 0) {
       yield* output.raw(
-        "No workers found. Scaffold one with supabase experimental workers new <name>.\n",
+        `No workers found. Scaffold one with ${legacyAqua("supabase experimental workers new <name>", process.stdout)}.\n`,
       );
       return;
     }
@@ -178,14 +195,20 @@ export const legacyWorkersList = Effect.fn("legacy.experimental.workers.list")(f
     // the source directory *before* inferring a runtime and fails with
     // `WorkerSourceMissingError`, so telling that user about runtime guessing
     // points them at the wrong prerequisite.
+    //
+    // Both are written the way this shell writes every other heads-up that is
+    // not a failure: a yellow `WARNING:` prefix, then the consequence on its own
+    // line (`start`'s Docker-on-Windows notice is the same two-line shape). A
+    // single long sentence re-flows differently at every terminal width, right
+    // under a table that lines its columns up.
     const unconfigured = rows
       .filter((row) => row.deployed !== undefined && !row.configured && row.local)
       .map((row) => row.name);
     if (unconfigured.length > 0) {
+      const configDisplay = displayPath(project.projectRoot, project.configPath);
       yield* output.raw(
-        `${unconfigured.join(", ")} ${
-          unconfigured.length === 1 ? "is" : "are"
-        } deployed but absent from supabase/config.toml: pushing from here would have to guess the runtime.\n`,
+        `${legacyYellow("WARNING:")} ${nameList(unconfigured)} deployed but not in ${configDisplay}.\n` +
+          `Pushing from here would have to guess the runtime.\n`,
         "stderr",
       );
     }
@@ -195,9 +218,8 @@ export const legacyWorkersList = Effect.fn("legacy.experimental.workers.list")(f
       .map((row) => row.name);
     if (remoteOnly.length > 0) {
       yield* output.raw(
-        `${remoteOnly.join(", ")} ${
-          remoteOnly.length === 1 ? "is" : "are"
-        } deployed but ${remoteOnly.length === 1 ? "has" : "have"} no source in this project: scaffold or restore it before pushing from here.\n`,
+        `${legacyYellow("WARNING:")} ${nameList(remoteOnly)} deployed with no source in this project.\n` +
+          `Scaffold or restore before pushing from here.\n`,
         "stderr",
       );
     }