feat(cli): add supabase workers push

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

@@ -0,0 +1,57 @@
+# `supabase workers push [name...] (alias: deploy)`
+
+> **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 each worker's runtime, size, source |
+| `<worker source>/**`             | any    | always — packaged into the build context        |
+
+## Files Written
+
+| Path | Format | When |
+| ---- | ------ | ---- |
+| —    | —      | —    |
+
+## API Routes
+
+| Method | Path                                         | Auth                                        | Request body                                        | Response (used fields)                                 |
+| ------ | -------------------------------------------- | ------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------ |
+| `POST` | `/v2/projects/{ref}/workers/{name}/uploads`  | Bearer token                                | none                                                | `data.id`, `data.attributes.url/method`                |
+| `PUT`  | presigned upload URL (control-plane storage) | URL signature — **no** Supabase credentials | `.tar.gz` build context                             | status only                                            |
+| `POST` | `/v2/projects/{ref}/workers/{name}/deploy`   | Bearer token                                | `{data:{type,attributes:{spec,context_upload_id}}}` | `data.attributes.build_state`                          |
+| `GET`  | `/v2/projects/{ref}/workers/{name}`          | Bearer token                                | none                                                | `build_state`, `state_reason`, `image_version`, `spec` |
+
+`GET` is polled until `build_state` leaves `building`.
+
+## Exit Codes
+
+| Code | Condition                                            |
+| ---- | ---------------------------------------------------- |
+| `0`  | success                                              |
+| `1`  | no workers named and none found in the project       |
+| `1`  | a worker's source directory is missing or empty      |
+| `1`  | build context upload failed                          |
+| `1`  | the build reached `failed`, or never left `building` |
+| `1`  | API error, or project not enrolled in the alpha      |
+
+## 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/push/push.command.ts

@@ -0,0 +1,52 @@
+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 { legacyManagementApiRuntimeLayer } from "../../../shared/legacy-management-api-runtime.layer.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyWorkersPush } from "./push.handler.ts";
+
+const config = {
+  names: Argument.string("name").pipe(
+    Argument.withDescription("Workers to deploy. Deploys every worker in the project if omitted."),
+    Argument.variadic(),
+  ),
+  instances: Flag.integer("instances").pipe(
+    Flag.withDescription("Number of instances to run."),
+    Flag.withDefault(1),
+  ),
+  projectRef: Flag.string("project-ref").pipe(
+    Flag.withDescription("Project ref of the Supabase project."),
+    Flag.optional,
+  ),
+} as const;
+
+export type LegacyWorkersPushFlags = CliCommand.Command.Config.Infer<typeof config>;
+
+export const legacyWorkersPushCommand = Command.make("push", config).pipe(
+  Command.withAlias("deploy"),
+  Command.withDescription(
+    "Build and deploy workers into the linked Supabase project. Reads each worker's runtime, size and source directory from supabase/config.toml.",
+  ),
+  Command.withShortDescription("Build and deploy workers"),
+  Command.withExamples([
+    {
+      command: "supabase workers push",
+      description: "Deploy every worker in the project",
+    },
+    {
+      command: "supabase workers push api",
+      description: "Deploy a single worker",
+    },
+    {
+      command: "supabase workers push api web",
+      description: "Deploy several workers by name",
+    },
+  ]),
+  Command.withHandler((flags) =>
+    legacyWorkersPush(flags).pipe(
+      withLegacyCommandInstrumentation({ flags }),
+      withJsonErrorHandling,
+    ),
+  ),
+  Command.provide(legacyManagementApiRuntimeLayer(["workers", "push"])),
+);