feat(cli): add supabase workers new

apps/cli/docs/go-cli-divergences.md

@@ -10,13 +10,14 @@ something the old Go CLI didn't — it is not a compatibility promise.
 
 These commands exist in the TS CLI today but have no direct top-level equivalent in the old Go CLI reference.
 
-| TS command        | TS path                                                                                                            | Notes                                                                                                                                                                                         |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dev`             | `planned`                                                                                                          | Reserved for a TS-native long-running local development workflow command that watches files and orchestrates subcommands. Track this as TS-only unless a direct Go equivalent emerges.        |
-| `logs`            | [`../src/next/commands/logs/logs.command.ts`](../src/next/commands/logs/logs.command.ts)                           | Streams local stack logs. No top-level `logs` command exists in the old Go CLI reference.                                                                                                     |
-| `api`             | [`../src/next/commands/platform/api.command.ts`](../src/next/commands/platform/api.command.ts)                     | Low-level Management API client. It supersedes the old generated tree with explicit discovery via `supabase api routes` and execution via `supabase api request <route> [--method <METHOD>]`. |
-| `stack`           | [`../src/next/cli/root.ts`](../src/next/cli/root.ts)                                                               | TS-only local runtime namespace exposing `stack start`, `stack stop`, `stack status`, `stack list`, and `stack update`. Top-level `start`, `stop`, and `status` remain aliases.               |
-| `branches switch` | [`../src/next/commands/branches/switch/switch.command.ts`](../src/next/commands/branches/switch/switch.command.ts) | No direct Go equivalent. Updates local active-branch state so subsequent commands target the selected branch.                                                                                 |
+| TS command        | TS path                                                                                                            | Notes                                                                                                                                                                                                                                                                                         |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dev`             | `planned`                                                                                                          | Reserved for a TS-native long-running local development workflow command that watches files and orchestrates subcommands. Track this as TS-only unless a direct Go equivalent emerges.                                                                                                        |
+| `logs`            | [`../src/next/commands/logs/logs.command.ts`](../src/next/commands/logs/logs.command.ts)                           | Streams local stack logs. No top-level `logs` command exists in the old Go CLI reference.                                                                                                                                                                                                     |
+| `api`             | [`../src/next/commands/platform/api.command.ts`](../src/next/commands/platform/api.command.ts)                     | Low-level Management API client. It supersedes the old generated tree with explicit discovery via `supabase api routes` and execution via `supabase api request <route> [--method <METHOD>]`.                                                                                                 |
+| `stack`           | [`../src/next/cli/root.ts`](../src/next/cli/root.ts)                                                               | TS-only local runtime namespace exposing `stack start`, `stack stop`, `stack status`, `stack list`, and `stack update`. Top-level `start`, `stop`, and `status` remain aliases.                                                                                                               |
+| `branches switch` | [`../src/next/commands/branches/switch/switch.command.ts`](../src/next/commands/branches/switch/switch.command.ts) | No direct Go equivalent. Updates local active-branch state so subsequent commands target the selected branch.                                                                                                                                                                                 |
+| `workers`         | [`../src/legacy/commands/workers/workers.command.ts`](../src/legacy/commands/workers/workers.command.ts)           | No Go equivalent. Manages Supabase Workers — containers deployed from `supabase/workers/<name>/` — via the v2 Management API (`/v2/projects/{ref}/workers`). Notably the first legacy-shell command to call a **v2** route; every other legacy command is a Go-parity port and calls v1 only. |
 
 ## Flag divergences from the Go reference
 

apps/cli/package.json

@@ -122,7 +122,8 @@
     "ignore": [
       "scripts/*.ts",
       "tests/**/*.ts",
-      "src/shared/telemetry/event-catalog.ts"
+      "src/shared/telemetry/event-catalog.ts",
+      "src/shared/workers/stacks/**"
     ],
     "ignoreBinaries": [
       "nx",

apps/cli/scripts/build-binary.ts

@@ -7,8 +7,7 @@ import { bundleServeMainTemplate } from "../src/shared/functions/serve-main-bund
  * Compile a single CLI shell to a standalone binary, embedding the pre-bundled
  * edge-runtime template via the `SUPABASE_FUNCTIONS_SERVE_MAIN_TEMPLATE` define so
  * the binary serves Functions offline without bundling at runtime
- * (supabase/supabase#45570). Used by the `build:next` / `build:legacy` scripts; the
- * multi-target release build in `build.ts` injects the same define.
+ * (supabase/supabase#45570). Used by the `build:next` / `build:legacy` scripts.
  */
 const shell = process.argv[2];
 if (shell !== "next" && shell !== "legacy") {

apps/cli/src/legacy/cli/root.ts

@@ -35,6 +35,7 @@ import { legacyStorageCommand } from "../commands/storage/storage.command.ts";
 import { legacyTestCommand } from "../commands/test/test.command.ts";
 import { legacyTelemetryCommand } from "../commands/telemetry/telemetry.command.ts";
 import { legacyUnlinkCommand } from "../commands/unlink/unlink.command.ts";
+import { legacyWorkersCommand } from "../commands/workers/workers.command.ts";
 import { legacyVanitySubdomainsCommand } from "../commands/vanity-subdomains/vanity-subdomains.command.ts";
 import { OutputFormatFlag } from "../../shared/cli/global-flags.ts";
 import { outputLayerFor } from "../../shared/output/output.layer.ts";
@@ -70,6 +71,7 @@ export const legacyRoot = Command.make("supabase").pipe(
     legacyDomainsCommand,
     legacyEncryptionCommand,
     legacyFunctionsCommand,
+    legacyWorkersCommand,
     legacyGenCommand,
     legacyInitCommand,
     legacyInspectCommand,

apps/cli/src/legacy/commands/workers/new/SIDE_EFFECTS.md

@@ -0,0 +1,56 @@
+# `supabase workers new [name]`
+
+> **TS-only command.** `supabase workers` has no Go counterpart — there is no
+> `apps/cli-go/internal/workers` to match, and nothing is proxied. See
+> `docs/go-cli-divergences.md`.
+
+## Files Read
+
+| Path                             | Format | When                                                        |
+| -------------------------------- | ------ | ----------------------------------------------------------- |
+| `<workdir>/supabase/config.toml` | TOML   | always, for `[workers]` root and any existing entry         |
+| `<destination>/`                 | dir    | always, to refuse a non-empty destination without `--force` |
+
+## Files Written
+
+| Path                                 | Format | When                                                                      |
+| ------------------------------------ | ------ | ------------------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml`     | TOML   | always — appends/updates `[workers.<name>]` in place, preserving comments |
+| `<workdir>/supabase/<root>/<name>/*` | varies | always, unless `--source` names another directory                         |
+| `<workdir>/<source>/*`               | varies | when `--source` is given                                                  |
+
+Existing files at the destination are **deleted** when `--force` is passed.
+`--source` is refused when it resolves to the project root, `supabase/`,
+`supabase/functions/`, `supabase/migrations/`, or outside the project.
+
+## API Routes
+
+| Method | Path | Auth | Request body | Response (used fields) |
+| ------ | ---- | ---- | ------------ | ---------------------- |
+| —      | —    | —    | —            | —                      |
+
+## Exit Codes
+
+| Code | Condition                                                             |
+| ---- | --------------------------------------------------------------------- |
+| `0`  | success                                                               |
+| `1`  | invalid or reserved worker name, unknown runtime/size, bad `--source` |
+| `1`  | destination exists and is not empty without `--force`                 |
+| `1`  | `config.toml` records a worker in a form that cannot be edited safely |
+
+## Environment Variables
+
+| Variable                | Purpose                                              | Required?                                               |
+| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
+| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
+| `SUPABASE_PROFILE`      | built-in profile name or YAML file path              | no (falls back to `~/.supabase/profile` -> `supabase`)  |
+| `SUPABASE_WORKDIR`      | project directory the command acts on                | no (falls back to `--workdir`, then the ancestor walk)  |
+
+## Telemetry Events Fired
+
+| Event                  | When                                       | Notable properties / groups         |
+| ---------------------- | ------------------------------------------ | ----------------------------------- |
+| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` |
+
+No custom events. `workers` has no Go counterpart, so there is no
+`phtelemetry.*` call to reproduce.

apps/cli/src/legacy/commands/workers/new/new.command.ts

@@ -0,0 +1,81 @@
+import { Layer } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import type * as CliCommand from "effect/unstable/cli/Command";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { commandRuntimeLayer } from "../../../../shared/runtime/command-runtime.layer.ts";
+import { randomLayer } from "../../../../shared/runtime/random.layer.ts";
+import { WORKER_RUNTIMES, WORKER_SIZES } from "../../../../shared/workers/worker-runtimes.ts";
+import { legacyCliConfigLayer } from "../../../config/legacy-cli-config.layer.ts";
+import { legacyDebugLoggerLayer } from "../../../shared/legacy-debug-logger.layer.ts";
+import { legacyTelemetryStateLayer } from "../../../telemetry/legacy-telemetry-state.layer.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyWorkersNew } from "./new.handler.ts";
+
+const config = {
+  name: Argument.string("name").pipe(
+    Argument.withDescription("Worker name. Doubles as its directory; generated when omitted."),
+    Argument.optional,
+  ),
+  runtime: Flag.choice("runtime", WORKER_RUNTIMES).pipe(
+    Flag.withDescription(
+      "Runtime to scaffold and record in supabase/config.toml. Prompted when omitted.",
+    ),
+    Flag.optional,
+  ),
+  size: Flag.choice("size", WORKER_SIZES).pipe(
+    Flag.withDescription(
+      "Instance size to record in supabase/config.toml. Each size implies its own vCPU count, so there is no separate --cpu. Prompted when omitted.",
+    ),
+    Flag.optional,
+  ),
+  source: Flag.string("source").pipe(
+    Flag.withAlias("p"),
+    Flag.withDescription(
+      "Scaffold the worker here instead of the default workers directory, recorded as `source` in supabase/config.toml.",
+    ),
+    Flag.optional,
+  ),
+  force: Flag.boolean("force").pipe(
+    Flag.withDescription("Replace the destination if it already exists and is not empty."),
+  ),
+} as const;
+
+export type LegacyWorkersNewFlags = CliCommand.Command.Config.Infer<typeof config>;
+
+const cliConfig = legacyCliConfigLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
+
+/** Local-disk only: no Management API, so no platform stack is built. */
+const legacyWorkersNewRuntimeLayer = Layer.mergeAll(
+  cliConfig,
+  legacyTelemetryStateLayer,
+  randomLayer,
+  commandRuntimeLayer(["workers", "new"]),
+);
+
+export const legacyWorkersNewCommand = Command.make("new", config).pipe(
+  Command.withDescription(
+    "Scaffold a worker directory from a runtime's starter files and record the choice in supabase/config.toml. Nothing is deployed.",
+  ),
+  Command.withShortDescription("Scaffold a worker locally"),
+  Command.withExamples([
+    {
+      command: "supabase workers new",
+      description: "Scaffold a worker, prompting for runtime and size",
+    },
+    {
+      command: "supabase workers new api --runtime node",
+      description: "Scaffold supabase/workers/api on the node runtime",
+    },
+    {
+      command: "supabase workers new api --source packages/api",
+      description: "Scaffold the worker outside the workers directory",
+    },
+  ]),
+  Command.withHandler((flags) =>
+    legacyWorkersNew(flags).pipe(
+      withLegacyCommandInstrumentation({ flags, config }),
+      withJsonErrorHandling,
+    ),
+  ),
+  Command.provide(legacyWorkersNewRuntimeLayer),
+);