feat(workers): add exposure control and new --instances flag

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

@@ -14,12 +14,12 @@
 
 ## 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              |
+| Path                                            | Format | When                                                                                                                                                                       |
+| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml`                | TOML   | on success — appends `[workers.<name>]` with `runtime`, `size`, `exposure`, and `instances`/`source` when those differ from the default, 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
@@ -40,13 +40,22 @@ prompt refuses a name that is not a DNS label or that `config.toml` already
 records — so nothing is asked, and nothing written, for a name the command was
 going to refuse. With `-o json|yaml|toml|env`, a redirected stdout, or a stdin
 that is not a terminal, there is nowhere to ask, and the command fails instead
-of defaulting: unlike the runtime and size, the name has no default to fall back
-on. Every prompt is gated on both streams, so
+of defaulting: unlike the runtime, size and exposure, the name has no default to
+fall back on. Every prompt is gated on both streams, so
 `printf 'api\n' | supabase experimental workers new` takes that failure path
 rather than reading the worker name off the pipe.
 
+`runtime`, `size` and `exposure` are always written, defaults included: they are
+closed sets the command prompts for, and pinning the answer is the point of
+recording it. `instances` is written only when it differs from the default of 1 —
+it has no prompt, because how many instances a worker needs is not something a
+scaffold can guess, and an absent `instances` means exactly what `instances = 1`
+means to `push`. A `0` is an explicit count that scales the worker to nothing, so
+it is written like any other. It is rendered as a bare TOML number rather than a
+quoted string, because the config schema types it as a number.
+
 Writes to `config.toml` are append-only. A worker already recorded under
-`[workers.<name>]` is refused outright — before the runtime and size prompts,
+`[workers.<name>]` is refused outright — before the dial prompts,
 and before anything reaches disk — because editing an entry the user owns is
 not this command's job.
 
@@ -95,7 +104,8 @@ 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
-`--runtime`/`--size` value outside the choice list. The wrapper is installed by
+`--runtime`/`--size`/`--exposure` value outside the choice list, or a negative
+`--instances`. 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. A missing name
 is _not_ one of those: the argument is optional, so a bare `workers new` reaches

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

@@ -3,7 +3,11 @@ 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 {
+  WORKER_EXPOSURES,
+  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";
@@ -29,6 +33,24 @@ const config = {
     ),
     Flag.optional,
   ),
+  exposure: Flag.choice("exposure", WORKER_EXPOSURES).pipe(
+    Flag.withDescription(
+      "Whether the worker is reachable from the internet, recorded as `exposure` in supabase/config.toml. Prompted when omitted.",
+    ),
+    Flag.optional,
+  ),
+  instances: Flag.integer("instances").pipe(
+    // Bounded at the parser, the same way `push --instances` and the config
+    // schema's own `instances` are.
+    Flag.filter(
+      (instances) => instances >= 0,
+      (instances) => `--instances ${instances} is negative; pass zero or more.`,
+    ),
+    Flag.withDescription(
+      "Number of instances to record in supabase/config.toml. Not prompted for, and recorded only when it differs from the default of 1.",
+    ),
+    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.",
@@ -50,22 +72,30 @@ const legacyWorkersNewRuntimeLayer = Layer.mergeAll(
 
 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.",
+    "Scaffold a worker directory from a runtime's starter files and record the choices in supabase/config.toml. Nothing is deployed.",
   ),
   Command.withShortDescription("Scaffold a worker locally"),
   Command.withExamples([
     {
       command: "supabase experimental workers new",
-      description: "Prompt for the name, then for runtime and size",
+      description: "Prompt for the name, then for runtime, size and exposure",
     },
     {
       command: "supabase experimental workers new api",
-      description: "Scaffold supabase/workers/api, prompting for runtime and size",
+      description: "Scaffold supabase/workers/api, prompting for runtime, size and exposure",
     },
     {
       command: "supabase experimental workers new api --runtime node",
       description: "Scaffold supabase/workers/api on the node runtime",
     },
+    {
+      command: "supabase experimental workers new api --exposure private",
+      description: "Scaffold a worker with no internet-facing URL",
+    },
+    {
+      command: "supabase experimental workers new api --instances 3",
+      description: "Scaffold a worker that deploys at three instances",
+    },
     {
       command: "supabase experimental workers new api --source packages/api",
       description: "Scaffold the worker outside the workers directory",

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

@@ -22,15 +22,21 @@ import {
   resolveWorkerSource,
 } from "../../../../../shared/workers/worker-paths.ts";
 import {
+  DEFAULT_WORKER_EXPOSURE,
+  DEFAULT_WORKER_INSTANCES,
   DEFAULT_WORKER_RUNTIME,
   DEFAULT_WORKER_SIZE,
+  parseWorkerExposure,
   parseWorkerRuntime,
   parseWorkerSize,
   validateWorkerNameMessage,
   vcpuForSize,
+  WORKER_EXPOSURE_DESCRIPTIONS,
+  WORKER_EXPOSURES,
   WORKER_RUNTIME_DESCRIPTIONS,
   WORKER_RUNTIMES,
   WORKER_SIZES,
+  type WorkerExposure,
   type WorkerRuntime,
   type WorkerSize,
 } from "../../../../../shared/workers/worker-runtimes.ts";
@@ -51,8 +57,10 @@ import type { LegacyWorkersNewFlags } from "./new.command.ts";
  * chosen runtime's starter files and record the choice in `config.toml`.
  * Nothing is deployed; this is entirely local-disk work.
  *
- * The name, runtime and size are all resolved *before* anything is written, so a
- * cancelled prompt leaves nothing behind for this worker at all.
+ * The name, runtime, size and exposure are all resolved *before* anything is
+ * written, so a cancelled prompt leaves nothing behind for this worker at all.
+ * `--instances` is recorded rather than resolved: it has no prompt, and it only
+ * reaches `config.toml` when it differs from the default.
  */
 
 /** `values`, with `defaultValue` first, so a prompt pre-selects what it shows first. */
@@ -174,6 +182,55 @@ const resolveSize = Effect.fnUntraced(function* (options: {
   return DEFAULT_WORKER_SIZE;
 });
 
+/**
+ * Recorded on every scaffold, not just when it is asked for: `push` sends a
+ * complete spec each time, so a worker whose `exposure` is absent from
+ * `config.toml` is deployed public by the next bare `push`. Writing the value
+ * down — default included, the way `runtime` and `size` are — is what makes
+ * `--exposure private` stick past the deploy that chose it.
+ */
+const resolveExposure = Effect.fnUntraced(function* (options: {
+  readonly explicit: Option.Option<WorkerExposure>;
+  /** Whether there is a terminal to ask on — see `canPromptFor`. */
+  readonly canPrompt: boolean;
+}) {
+  if (Option.isSome(options.explicit)) {
+    return options.explicit.value;
+  }
+
+  if (options.canPrompt) {
+    const output = yield* Output;
+    const selected = yield* output.promptSelect(
+      "Should this worker be reachable from the internet?",
+      defaultFirst([...WORKER_EXPOSURES], DEFAULT_WORKER_EXPOSURE).map((exposure) => ({
+        value: exposure,
+        label: exposure,
+        hint: WORKER_EXPOSURE_DESCRIPTIONS[exposure],
+      })),
+    );
+    return parseWorkerExposure(selected) ?? DEFAULT_WORKER_EXPOSURE;
+  }
+
+  return DEFAULT_WORKER_EXPOSURE;
+});
+
+/**
+ * The instance count to record, and whether to record it at all.
+ *
+ * Not prompted for, unlike the other dials: how many instances a worker needs is
+ * an operational answer nobody has while scaffolding it, so the flag records
+ * one when it is given and the file stays quiet when it is not.
+ *
+ * `undefined` — meaning "write no key" — for the default count, because an
+ * absent `instances` and `instances = 1` mean the same thing to `push`, and a
+ * scaffold should not commit a line that says nothing. A `0` is not that: it
+ * scales the worker to nothing, so it is written like any other explicit count.
+ */
+function recordedInstances(explicit: Option.Option<number>): number | undefined {
+  const instances = Option.getOrUndefined(explicit);
+  return instances === undefined || instances === DEFAULT_WORKER_INSTANCES ? undefined : instances;
+}
+
 /**
  * Whether the destination is free for a scaffold: nothing there, or an empty
  * directory. A plain file counts as occupied, so it is refused by name rather
@@ -226,11 +283,13 @@ export const legacyWorkersNew = Effect.fn("legacy.experimental.workers.new")(fun
       );
     }
 
-    // Resolved before anything is written, so cancelling either prompt leaves
+    // Resolved before anything is written, so cancelling any prompt leaves
     // nothing behind — the name included. With nowhere to ask, the defaults
     // stand; only the name has nothing to fall back to.
     const runtime = yield* resolveRuntime({ explicit: flags.runtime, canPrompt });
     const size = yield* resolveSize({ explicit: flags.size, canPrompt });
+    const exposure = yield* resolveExposure({ explicit: flags.exposure, canPrompt });
+    const instances = recordedInstances(flags.instances);
 
     // Validated before anything is written: this is the directory the starter
     // files land in, so a value naming the project root, `supabase/`, or
@@ -289,6 +348,8 @@ export const legacyWorkersNew = Effect.fn("legacy.experimental.workers.new")(fun
       patch: {
         runtime,
         size,
+        exposure,
+        ...(instances === undefined ? {} : { instances }),
         ...(source === undefined ? {} : { source }),
       },
     });
@@ -310,6 +371,11 @@ export const legacyWorkersNew = Effect.fn("legacy.experimental.workers.new")(fun
       runtime,
       size,
       vcpu: vcpuForSize(size),
+      exposure,
+      // The count a deploy will use, whether or not it was written down — a
+      // payload that omitted it for the default would read as "unknown" rather
+      // than "one".
+      instances: instances ?? DEFAULT_WORKER_INSTANCES,
       source: sourceDisplay,
       config_path: project.configPath,
     };
@@ -335,7 +401,10 @@ export const legacyWorkersNew = Effect.fn("legacy.experimental.workers.new")(fun
       legacyRenderWorkerDetails([
         ["Runtime", runtime],
         ["Size", `${size} (${vcpuForSize(size)} vCPU)`],
-        ["Access", "public"],
+        ["Access", exposure],
+        // `declared`, the way `workers status` labels the same number: nothing
+        // is running yet, so a bare count would read as a live tally.
+        ["Instances", `${instances ?? DEFAULT_WORKER_INSTANCES} declared`],
       ]),
     );
     // On the success trailer rather than inline, the way `bootstrap` emits its