feat(cli): add supabase workers new

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,89 @@
+# `supabase workers new <name>`
+
+> **Local-disk only.** Nothing is deployed and no Management API route is
+> called; `workers push` is what talks to the platform.
+
+## Files Read
+
+| Path | Format | When |
+| ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml` | TOML | always — decoded to refuse a worker that is already recorded, then re-read as text to append the new entry |
+| `<destination>/` | dir | always, to refuse a destination that is not empty |
+| `<SUPABASE_HOME or ~/.supabase>/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set — names the profile, defaulting to `supabase` |
+| `<SUPABASE_PROFILE>` (YAML) | YAML | when `SUPABASE_PROFILE` is a filesystem path rather than a built-in name; a read failure aborts the command |
+
+## Files Written
+
+| Path | Format | When |
+| ----------------------------------------------- | ------ | -------------------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml` | TOML | on success — appends `[workers.<name>]`, preserving surrounding formatting |
+| `<workdir>/supabase/workers/<name>/*` | varies | on success, unless `--source` names another directory |
+| `<workdir>/<source>/*` | varies | on success, when `--source` is given |
+| `<SUPABASE_HOME or ~/.supabase>/telemetry.json` | JSON | whenever the handler runs — flushed on success and on failure |
+
+Workers are recorded in `config.toml` only. The project config loader prefers
+`supabase/config.json` when one exists, but the entry writer is a TOML text
+editor, so this command pins the loader to `config.toml` (`tomlOnly`). In a
+project that has a `config.json`, the worker is therefore written to
+`config.toml` — which that loader lists in `ignoredPaths` — and the `config.json`
+is left byte-for-byte alone. A rendered edit that would not parse is refused
+before anything reaches disk.
+
+`<workdir>` above is exact: the loader is pinned to it (`search: false`, the
+same resolver `start`/`stop`/`status` use) and never climbs to an ancestor. A
+`--workdir` pointing at a bare directory inside another Supabase project
+therefore records the worker in that directory's own `config.toml` — created if
+absent — rather than in the ancestor project's.
+
+Writes to `config.toml` are append-only. A worker already recorded under
+`[workers.<name>]` is refused outright — before the runtime and size prompts,
+and before anything reaches disk — because editing an entry the user owns is
+not this command's job.
+
+Nothing at the destination is ever removed or overwritten: a destination that
+exists and is not empty is refused, and clearing it is left to the user.
+`--source` is refused when it resolves to the project root, `supabase/`,
+`supabase/functions/`, `supabase/migrations/`, or outside the project. Symlinks
+are resolved first, so a path inside the project that points outside it is
+refused too. A relative `--source` is resolved against the directory the command
+was run in; a `source` recorded in `config.toml` is resolved against the project
+root.
+
+## API Routes
+
+| Method | Path | Auth | Request body | Response (used fields) |
+| ------ | ---- | ---- | ------------ | ---------------------- |
+| — | — | — | — | — |
+
+## Exit Codes
+
+| Code | Condition |
+| ---- | ----------------------------------------------------------------------------------- |
+| `0` | success |
+| `1` | invalid worker name — the name must be a DNS label |
+| `1` | bad `--source`: outside the project, or a path the CLI owns |
+| `1` | destination exists and is not empty |
+| `1` | the worker is already recorded in `config.toml`, in any form |
+| `1` | the rendered `config.toml` would not parse, or `[workers]` is a sealed inline table |
+
+## Environment Variables
+
+| Variable | Purpose | Required? |
+| ------------------ | --------------------------------------- | ------------------------------------------------------ |
+| `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) |
+| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) |
+
+## Telemetry Events Fired
+
+| Event | When | Notable properties / groups |
+| ---------------------- | ---------------------------------------------- | ----------------------------------- |
+| `cli_command_executed` | post-handler, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` |
+
+No custom events — only the `cli_command_executed` that the instrumentation
+wrapper emits for every command.
+
+Nothing is emitted for a failure the parser catches, such as a missing worker
+name or a `--runtime`/`--size` value outside the choice list. The wrapper is
+installed by `Command.withHandler`, so a command that never reaches its handler
+never reaches the instrumentation either — and `telemetry.json` is not written.

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

@@ -0,0 +1,74 @@
+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 { WORKER_RUNTIMES, WORKER_SIZES } from "../../../../shared/workers/worker-runtimes.ts";
+import { legacyCliSettingsLayer } from "../../../config/legacy-cli-settings.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, and its hostname."),
+ ),
+ 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.withDescription(
+ "Scaffold the worker here instead of the default workers directory, recorded as `source` in supabase/config.toml.",
+ ),
+ Flag.optional,
+ ),
+} as const;
+
+export type LegacyWorkersNewFlags = CliCommand.Command.Config.Infer<typeof config>;
+
+const cliSettings = legacyCliSettingsLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
+
+/** Local-disk only: no Management API, so no platform stack is built. */
+const legacyWorkersNewRuntimeLayer = Layer.mergeAll(
+ cliSettings,
+ legacyTelemetryStateLayer,
+ 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 api",
+ description: "Scaffold supabase/workers/api, 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),
+);