From 904f10a4bff343e2ae4a2c35b61f80c2b8d137af Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Mon, 6 Jul 2026 21:24:52 +0100 Subject: [PATCH 1/3] docs(cli): disclose --high-availability as TS-only, fix its telemetry safe-list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --high-availability has no Go CLI equivalent (Go's create.Run never sets HighAvailability even though the API field exists), but was undisclosed — unlike --reveal on projects api-keys, which explicitly documents itself as TS-only. It was also listed in safeFlags alongside org-id, implying Go parity that doesn't exist (Go marks only org-id telemetry-safe). Since it's a boolean flag, this has no runtime telemetry effect (boolean values are always logged verbatim regardless of safeFlags), but the array wrongly implied otherwise. Disclosed in SIDE_EFFECTS.md and a code comment, matching the --reveal precedent, and removed high-availability from safeFlags. Fixes CLI-1870. --- .../commands/projects/create/SIDE_EFFECTS.md | 29 ++++++++++--------- .../projects/create/create.command.ts | 10 ++++++- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md index 0726aaa348..abe2b476f9 100644 --- a/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md +++ b/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md @@ -40,22 +40,22 @@ ## Telemetry Events Fired -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` (`--org-id`, `--high-availability` are telemetry-safe) | +| Event | When | Notable properties / groups | +| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- | +| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` (`--org-id` is telemetry-safe, matching Go) | ## Flags -| Flag | Type | Required (non-interactive) | Description | -| --------------------- | ------ | -------------------------- | ----------------------------------------------- | -| `[project name]` | arg | yes (non-interactive) | Name of the project (positional argument) | -| `--org-id` | string | yes (non-interactive) | Organization ID (slug) to create the project in | -| `--db-password` | string | yes (non-interactive) | Database password for the project | -| `--region` | enum | yes (non-interactive) | AWS region for the project | -| `--size` | enum | no | Desired instance size | -| `--high-availability` | bool | no | Enable high availability for the project | -| `--interactive` | bool | no (default: true) | Enable interactive mode (hidden flag) | -| `--plan` | string | no | Plan selection (hidden flag) | +| Flag | Type | Required (non-interactive) | Description | +| --------------------- | ------ | -------------------------- | ---------------------------------------------------------------------------- | +| `[project name]` | arg | yes (non-interactive) | Name of the project (positional argument) | +| `--org-id` | string | yes (non-interactive) | Organization ID (slug) to create the project in | +| `--db-password` | string | yes (non-interactive) | Database password for the project | +| `--region` | enum | yes (non-interactive) | AWS region for the project | +| `--size` | enum | no | Desired instance size | +| `--high-availability` | bool | no | Enable high availability for the project (**TS-only, no Go CLI equivalent**) | +| `--interactive` | bool | no (default: true) | Enable interactive mode (hidden flag) | +| `--plan` | string | no | Plan selection (hidden flag) | ## Output @@ -93,4 +93,7 @@ One `result` event on success. flags and the positional project name argument are required. - The `--size` flag, when provided, sets the `desired_instance_size` field in the request body. - The `--high-availability` flag, when provided, sets the `high_availability` field in the request body. + This is a TS-only flag with no Go CLI equivalent (`apps/cli-go/cmd/projects.go:133-143` never sets + `HighAvailability`, even though the underlying API field exists) — matching how `--reveal` is disclosed + on `projects api-keys`. - The `--plan` flag is hidden and reserved. diff --git a/apps/cli/src/legacy/commands/projects/create/create.command.ts b/apps/cli/src/legacy/commands/projects/create/create.command.ts index 2486931973..be57cd7674 100644 --- a/apps/cli/src/legacy/commands/projects/create/create.command.ts +++ b/apps/cli/src/legacy/commands/projects/create/create.command.ts @@ -69,6 +69,9 @@ const config = { Flag.withDescription("Select a desired instance size for your project."), Flag.optional, ), + // TS-only, no Go CLI equivalent (Go's create.Run never sets HighAvailability + // even though the API field exists) — disclosed in SIDE_EFFECTS.md, matching + // how `--reveal` is disclosed on `projects api-keys`. highAvailability: Flag.boolean("high-availability").pipe( Flag.withDescription("Enable high availability for the project."), Flag.optional, @@ -99,7 +102,12 @@ export const legacyProjectsCreateCommand = Command.make("create", config).pipe( ]), Command.withHandler((flags) => legacyProjectsCreate(flags).pipe( - withLegacyCommandInstrumentation({ flags, safeFlags: ["org-id", "high-availability"] }), + // `high-availability` is intentionally not in `safeFlags`: Go marks only + // `org-id` telemetry-safe (`markFlagTelemetrySafe`), and it's a boolean flag + // anyway — boolean values are always logged verbatim by the instrumentation + // regardless of `safeFlags`. See the same pattern on `projects api-keys`'s + // `--reveal`. + withLegacyCommandInstrumentation({ flags, safeFlags: ["org-id"] }), withJsonErrorHandling, ), ), From b78197ea48fb00efb868f19e6e3c6890972fbcd4 Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Mon, 6 Jul 2026 21:28:49 +0100 Subject: [PATCH 2/3] docs(cli): record --high-availability in go-cli-porting-status.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Missed from the initial disclosure commit — the "Flag divergences from the Go reference" section already tracks --reveal for exactly this purpose (apps/cli/CLAUDE.md requires updating this doc when a command's flag surface changes). --- apps/cli/docs/go-cli-porting-status.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md index 42d783057c..8dbe6f1cd1 100644 --- a/apps/cli/docs/go-cli-porting-status.md +++ b/apps/cli/docs/go-cli-porting-status.md @@ -323,3 +323,6 @@ Flag divergences from the Go reference: `reveal=true` so the Management API returns the full secret keys (`sb_secret_...`) in full instead of redacting them, addressing issue #4775. Default behavior (omitted flag) matches Go exactly. +- `projects create` has a TS-only `--high-availability` flag (no Go equivalent). It sets + `high_availability` in the create request body. Default behavior (omitted flag) matches + Go exactly. From 6ebdeab200301731bb3184402face9361619f567 Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Mon, 6 Jul 2026 21:30:51 +0100 Subject: [PATCH 3/3] docs(cli): tighten Go source citation for --high-availability disclosure The architect reviewer noted the previous citation (cmd/projects.go:133-143) pointed at the flag-registration block, which proves the flag doesn't exist, but the comment's claim about the request body was better evidenced by the RunE closure's body construction a few lines earlier. Cite both. --- .../src/legacy/commands/projects/create/SIDE_EFFECTS.md | 7 ++++--- .../src/legacy/commands/projects/create/create.command.ts | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md index abe2b476f9..e3d7a8a1a6 100644 --- a/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md +++ b/apps/cli/src/legacy/commands/projects/create/SIDE_EFFECTS.md @@ -93,7 +93,8 @@ One `result` event on success. flags and the positional project name argument are required. - The `--size` flag, when provided, sets the `desired_instance_size` field in the request body. - The `--high-availability` flag, when provided, sets the `high_availability` field in the request body. - This is a TS-only flag with no Go CLI equivalent (`apps/cli-go/cmd/projects.go:133-143` never sets - `HighAvailability`, even though the underlying API field exists) — matching how `--reveal` is disclosed - on `projects api-keys`. + This is a TS-only flag with no Go CLI equivalent: `apps/cli-go/cmd/projects.go`'s `init()` (~line 133) + never registers a `high-availability` flag, and the create command's `RunE` closure (~line 74) never sets + `HighAvailability` on the request body, even though the underlying API field exists — matching how + `--reveal` is disclosed on `projects api-keys`. - The `--plan` flag is hidden and reserved. diff --git a/apps/cli/src/legacy/commands/projects/create/create.command.ts b/apps/cli/src/legacy/commands/projects/create/create.command.ts index be57cd7674..bb005fb41d 100644 --- a/apps/cli/src/legacy/commands/projects/create/create.command.ts +++ b/apps/cli/src/legacy/commands/projects/create/create.command.ts @@ -69,9 +69,10 @@ const config = { Flag.withDescription("Select a desired instance size for your project."), Flag.optional, ), - // TS-only, no Go CLI equivalent (Go's create.Run never sets HighAvailability - // even though the API field exists) — disclosed in SIDE_EFFECTS.md, matching - // how `--reveal` is disclosed on `projects api-keys`. + // TS-only, no Go CLI equivalent: `cmd/projects.go`'s `init()` never registers a + // `high-availability` flag, and the `RunE` closure's `api.V1CreateProjectBody{...}` + // never sets `HighAvailability` even though the API field exists — disclosed in + // SIDE_EFFECTS.md, matching how `--reveal` is disclosed on `projects api-keys`. highAvailability: Flag.boolean("high-availability").pipe( Flag.withDescription("Enable high availability for the project."), Flag.optional,