fix(cli): reject sub-second gen types timeouts that disable the bound

`--query-timeout 1ms` rounded to 0 and silently dropped both timeout
guards. Parse through the shared Go duration helper, refuse rounded-to-0
except explicit disable, and document native TS/Python shape diffs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: avallete

apps/cli/src/legacy/commands/gen/types/SIDE_EFFECTS.md

@@ -54,11 +54,13 @@ remote targets and the `--dns-resolver` DoH mode), runs the package's
 introspection queries against `pg_catalog`/`information_schema`, and renders the
 requested language locally. `--query-timeout` is applied as the session's
 `statement_timeout` (the flag wins over a DSN `statement_timeout`) and as a
-client-side bound around `introspect()`; `0` disables both. When the connection
-string carries no explicit `connect_timeout`, a positive `--query-timeout` is
-also used as the connect timeout — `0` leaves the driver's default (10s remote,
-2s local). `--local` connects to the host-mapped database port from
-`supabase/config.toml` (`db.port`).
+client-side bound around `introspect()`; `0` / `0s` / `0ms` disable both. A
+positive duration that rounds below 1s (`1ms`, `400ms`) is rejected rather than
+treated as disable. When the connection string carries no explicit
+`connect_timeout`, a positive `--query-timeout` is also used as the connect
+timeout — `0` leaves the driver's default (10s remote, 2s local). `--local`
+connects to the host-mapped database port from `supabase/config.toml`
+(`db.port`).
 
 For a remote target whose DSN carries no explicit `sslmode`, a raw TCP
 `SSLRequest` probe (the shared pg-delta probe, default 10s timeout) is opened
@@ -171,21 +173,32 @@ go`/`--lang swift`/`--lang python` — the defaults-only claim above holds only
   intentionally). `--local` still forces v9 compat when the local PostgREST image tag
   contains `v9`.
 - `--query-timeout` sets the maximum timeout for the introspection queries (default
-  15s). It is mutually exclusive with an _explicit_ `--linked`/`--project-id`; on
-  the implicit linked fallback it is accepted, and honored for
-  `--lang go`/`--lang swift`/`--lang python` (silently unused only for the implicit
-  linked TypeScript case, since that path never opens a database connection).
+  15s). Parsed as a Go `time.Duration` (bare `0` is valid and disables). A
+  positive value that rounds to 0 seconds is rejected — use `0` to disable, or
+  at least `500ms`. It is mutually exclusive with an _explicit_ `--linked`/
+  `--project-id`; on the implicit linked fallback it is accepted, and honored
+  for `--lang go`/`--lang swift`/`--lang python` (silently unused only for the
+  implicit linked TypeScript case, since that path never opens a database
+  connection).
 - `--db-url` is parsed by the shared connection resolver (libpq keywords, `PG*` env
   fallbacks, `options=reference=<ref>` pooler tenants, `sslmode`), matching every
   other `--db-url` command. An absent dbname follows libpq (`PGDATABASE`, then the
   connection user) rather than forcing `postgres`.
 - The legacy positional language argument (`supabase gen types typescript`) is still accepted;
   any other positional language requires an explicit `--lang` flag.
-- Go and Python output now lists entities in the canonical sorted order
+- Go output lists entities in the canonical sorted order
   (`sortGeneratorMetadata`) instead of pg-meta's environment-dependent SQL row
-  order; the rendered content is otherwise identical (Swift verified
-  byte-identical — its template sorts internally). TypeScript is formatted by
-  oxfmt (postgrest-typegen ≥ 0.2.0) instead of pg-meta's prettier: content is
-  identical, with minor whitespace differences in how long union types wrap.
+  order; the rendered structs are otherwise the same. Swift is byte-identical
+  (its template sorts internally). Python is not a drop-in of pg-meta: it emits
+  `JsonValue` instead of pydantic `Json`, and imports `NotRequired`/`TypeAlias`
+  from `typing` rather than `typing_extensions`. TypeScript is formatted by
+  oxfmt (postgrest-typegen ≥ 0.2.0) instead of pg-meta's prettier, and native
+  generation differs in shape from both pg-meta and the Management API
+  `--linked`/`--project-id` TypeScript path: empty-arg RPCs are
+  `Args: Record<PropertyKey, never>` rather than `never`; some `Json` fields
+  become `NonNullable<Json>`; generated `path_tokens` is `never` rather than
+  `string[] | null`. The Management API payload also injects
+  `__InternalSupabase.PostgrestVersion`, which native `--local`/`--db-url`
+  generation omits.
 - The linked-project telemetry cache is written only when a project ref is resolved
   (`--linked`/`--project-id`/fallback) — it's skipped when no ref is available.

apps/cli/src/legacy/commands/gen/types/types.handler.ts

@@ -1,6 +1,6 @@
 import { loadCliConfig } from "@supabase/config/internal";
 import { ChildProcessSpawner } from "effect/unstable/process";
-import { Effect, FileSystem, Option, Path, Stdio, Stream } from "effect";
+import { Effect, FileSystem, Option, Path, Stdio } from "effect";
 import { LegacyDnsResolverFlag } from "../../../../shared/legacy/global-flags.ts";
 import { Output } from "../../../../shared/output/output.service.ts";
 import {
@@ -15,7 +15,7 @@ import {
   LegacyProjectRefResolver,
   PROJECT_NOT_LINKED_MESSAGE,
 } from "../../../config/legacy-project-ref.service.ts";
-import { spawnContainerCli } from "../../../shared/legacy-container-cli.ts";
+import { legacyCollectText, spawnContainerCli } from "../../../shared/legacy-container-cli.ts";
 import { legacyIsIPv6ConnectivityErrorCause } from "../../../shared/legacy-connect-errors.ts";
 import { mapLegacyHttpError } from "../../../shared/legacy-http-errors.ts";
 import { LegacyDbConfigResolver } from "../../../shared/legacy-db-config.service.ts";
@@ -123,38 +123,10 @@ const GEN_TYPES_SCAN_SPEC = {
   valueFlagShorthands: new Map([["s", "schema"], ...PERSISTENT_VALUE_FLAG_SHORTHANDS]),
 } as const;
 
-function collectByteStream(stream: Stream.Stream<Uint8Array, unknown>) {
-  const decoder = new TextDecoder();
-  return Stream.runFold(
-    stream,
-    () => "",
-    (text, chunk) => text + decoder.decode(chunk, { stream: true }),
-  ).pipe(Effect.map((text) => text + decoder.decode()));
-}
-
-// Keep these two sets in sync with the value-bearing flags on the root command
-// (shared/legacy/global-flags.ts) and the `gen types` command (types.command.ts).
-// They let `findLegacyPositionalLanguage` skip a flag's value so it is not
-// mistaken for the legacy positional language argument (e.g. `gen types typescript`).
-const LONG_FLAGS_WITH_VALUES = new Set([
-  "db-url",
-  "project-id",
-  "lang",
-  "schema",
-  "swift-access-control",
-  "query-timeout",
-  "profile",
-  "workdir",
-  "network-id",
-  "dns-resolver",
-  "output",
-  "output-format",
-  "log-level",
-  "completions",
-  "agent",
-]);
-
-const SHORT_FLAGS_WITH_VALUES = new Set(["s", "o"]);
+// Positional `typescript` scanning must skip the same value tokens pflag
+// consumes — derive from the scan spec so a new value flag cannot drift.
+const LONG_FLAGS_WITH_VALUES = GEN_TYPES_SCAN_SPEC.valueFlagNames;
+const SHORT_FLAGS_WITH_VALUES = new Set(GEN_TYPES_SCAN_SPEC.valueFlagShorthands.keys());
 
 function findLegacyPositionalLanguage(rawArgs: ReadonlyArray<string>): Option.Option<string> {
   const commandIndex = rawArgs.findIndex(
@@ -409,7 +381,7 @@ export const legacyGenTypes = Effect.fn("legacy.gen.types")(function* (flags: Le
         );
         const [exitCode, stderr] = yield* Effect.all([
           child.exitCode.pipe(Effect.map(Number)),
-          collectByteStream(child.stderr),
+          legacyCollectText(child.stderr),
         ]);
         if (exitCode !== 0) {
           const message = stderr.trim();

apps/cli/src/legacy/commands/gen/types/types.integration.test.ts

@@ -806,6 +806,28 @@ describe("legacy gen types", () => {
     });
   });
 
+  it.live("rejects a sub-second --query-timeout that would disable the bound", () => {
+    const { layer, telemetry } = setup({
+      args: ["gen", "types", "--db-url", "postgresql://postgres@127.0.0.1:5432/postgres"],
+    });
+
+    return Effect.gen(function* () {
+      const exit = yield* legacyGenTypes(
+        defaultFlags({
+          dbUrl: Option.some("postgresql://postgres@127.0.0.1:5432/postgres"),
+          queryTimeout: "1ms",
+        }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(String(exit.cause)).toContain('invalid duration "1ms"');
+        expect(String(exit.cause)).toContain("use 0 to disable, or at least 500ms");
+      }
+      expect(telemetry.flushed).toBe(false);
+    });
+  });
+
   it.live("silently ignores --query-timeout for implicit linked TypeScript generation", () => {
     const { layer, out, api } = setup({
       args: ["gen", "types", "--query-timeout", "20s"],

apps/cli/src/legacy/commands/gen/types/types.shared.ts

@@ -1,81 +1,47 @@
 import { Effect } from "effect";
 
 import type { LegacyPgConnInput } from "../../../shared/legacy-db-connection.service.ts";
+import { legacyParseGoDuration } from "../../../shared/legacy-go-duration.ts";
 import { LegacyInvalidGenTypesDurationError } from "./types.errors.ts";
 
 // The local Docker container id is hoisted to `legacy/shared` so the declarative
 // seam can derive the same `supabase_db_<id>` name when checking the local stack.
 export { localDbContainerId } from "../../../shared/legacy-docker-ids.ts";
 
-const DURATION_UNITS_TO_MILLIS = {
-  ns: 1 / 1_000_000,
-  us: 1 / 1_000,
-  "\u00b5s": 1 / 1_000,
-  "\u03bcs": 1 / 1_000,
-  ms: 1,
-  s: 1_000,
-  m: 60_000,
-  h: 3_600_000,
-} as const;
-
-const DURATION_PART_PATTERN = new RegExp(
-  String.raw`([+-]?(?:\d+\.?\d*|\.\d+))(ns|us|\u00b5s|\u03bcs|ms|s|m|h)`,
-  "g",
-);
-
 export function defaultSchemas(extraSchemas: ReadonlyArray<string> = []) {
   return [...new Set(["public", ...extraSchemas])];
 }
 
+function invalidQueryTimeout(raw: string, detail?: string) {
+  return new LegacyInvalidGenTypesDurationError({
+    message:
+      detail === undefined
+        ? `invalid duration ${JSON.stringify(raw)}`
+        : `invalid duration ${JSON.stringify(raw)}: ${detail}`,
+  });
+}
+
 export function parseQueryTimeoutSeconds(
   raw: string,
 ): Effect.Effect<number, LegacyInvalidGenTypesDurationError> {
-  return Effect.gen(function* () {
-    const input = raw.trim();
-    if (input.length === 0) {
-      return yield* Effect.fail(
-        new LegacyInvalidGenTypesDurationError({
-          message: `invalid duration ${JSON.stringify(raw)}`,
-        }),
-      );
-    }
-
-    let totalMillis = 0;
-    let consumed = 0;
-    DURATION_PART_PATTERN.lastIndex = 0;
-    for (const match of input.matchAll(DURATION_PART_PATTERN)) {
-      const [token, rawNumber, rawUnit] = match;
-      if (
-        token === undefined ||
-        rawNumber === undefined ||
-        rawUnit === undefined ||
-        match.index === undefined
-      ) {
-        continue;
+  return Effect.try({
+    try: () => legacyParseGoDuration(raw),
+    catch: () => invalidQueryTimeout(raw),
+  }).pipe(
+    Effect.flatMap((nanos) => {
+      if (nanos < 0) {
+        return Effect.fail(invalidQueryTimeout(raw));
       }
-      if (match.index !== consumed) {
-        return yield* Effect.fail(
-          new LegacyInvalidGenTypesDurationError({
-            message: `invalid duration ${JSON.stringify(raw)}`,
-          }),
-        );
+      // Whole-second `statement_timeout` / client bound. `0` is the disable
+      // sentinel — a positive duration that rounds into it would silently
+      // drop the user's requested cap.
+      const seconds = Math.round(nanos / 1_000_000_000);
+      if (seconds === 0 && nanos !== 0) {
+        return Effect.fail(invalidQueryTimeout(raw, "use 0 to disable, or at least 500ms"));
       }
-      const amount = Number.parseFloat(rawNumber);
-      const unitMillis = DURATION_UNITS_TO_MILLIS[rawUnit as keyof typeof DURATION_UNITS_TO_MILLIS];
-      totalMillis += amount * unitMillis;
-      consumed += token.length;
-    }
-
-    if (!Number.isFinite(totalMillis) || consumed !== input.length || totalMillis < 0) {
-      return yield* Effect.fail(
-        new LegacyInvalidGenTypesDurationError({
-          message: `invalid duration ${JSON.stringify(raw)}`,
-        }),
-      );
-    }
-
-    return Math.round(totalMillis / 1_000);
-  });
+      return Effect.succeed(seconds);
+    }),
+  );
 }
 
 export function localDbPassword() {

apps/cli/src/legacy/commands/gen/types/types.unit.test.ts

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "@effect/vitest";
 import { Effect, Exit } from "effect";
 import {
@@ -8,6 +11,13 @@ import {
   parseQueryTimeoutSeconds,
 } from "./types.shared.ts";
 
+function expectInvalidDuration(exit: Exit.Exit<unknown, unknown>, raw: string) {
+  expect(Exit.isFailure(exit)).toBe(true);
+  if (Exit.isFailure(exit)) {
+    expect(String(exit.cause)).toContain(`invalid duration ${JSON.stringify(raw)}`);
+  }
+}
+
 const BASE_CONN = {
   host: "db.example.com",
   port: 5432,
@@ -44,52 +54,55 @@ describe("parseQueryTimeoutSeconds", () => {
     }),
   );
 
-  it.effect("rounds sub-second durations to whole seconds", () =>
+  it.effect("accepts Go's bare 0 as disable", () =>
+    Effect.gen(function* () {
+      expect(yield* parseQueryTimeoutSeconds("0")).toBe(0);
+      expect(yield* parseQueryTimeoutSeconds("0s")).toBe(0);
+      expect(yield* parseQueryTimeoutSeconds("0ms")).toBe(0);
+    }),
+  );
+
+  it.effect("rounds 500ms up to a still-applied 1s bound", () =>
     Effect.gen(function* () {
       expect(yield* parseQueryTimeoutSeconds("500ms")).toBe(1);
-      expect(yield* parseQueryTimeoutSeconds("400ms")).toBe(0);
+    }),
+  );
+
+  it.effect("rejects a positive duration that would disable the timeout", () =>
+    Effect.gen(function* () {
+      for (const raw of ["1ms", "400ms", `15${"µ"}s`, `15${"μ"}s`]) {
+        expectInvalidDuration(yield* parseQueryTimeoutSeconds(raw).pipe(Effect.exit), raw);
+      }
     }),
   );
 
   it.effect("rejects an empty duration", () =>
     Effect.gen(function* () {
-      const exit = yield* parseQueryTimeoutSeconds("  ").pipe(Effect.exit);
-      expect(Exit.isFailure(exit)).toBe(true);
+      expectInvalidDuration(yield* parseQueryTimeoutSeconds("  ").pipe(Effect.exit), "  ");
     }),
   );
 
   it.effect("rejects a duration with a leading non-duration prefix", () =>
     Effect.gen(function* () {
-      const exit = yield* parseQueryTimeoutSeconds("x15s").pipe(Effect.exit);
-      expect(Exit.isFailure(exit)).toBe(true);
+      expectInvalidDuration(yield* parseQueryTimeoutSeconds("x15s").pipe(Effect.exit), "x15s");
     }),
   );
 
   it.effect("rejects a duration with trailing junk", () =>
     Effect.gen(function* () {
-      const exit = yield* parseQueryTimeoutSeconds("15s30").pipe(Effect.exit);
-      expect(Exit.isFailure(exit)).toBe(true);
+      expectInvalidDuration(yield* parseQueryTimeoutSeconds("15s30").pipe(Effect.exit), "15s30");
     }),
   );
 
   it.effect("rejects a string with no recognizable units", () =>
     Effect.gen(function* () {
-      const exit = yield* parseQueryTimeoutSeconds("abc").pipe(Effect.exit);
-      expect(Exit.isFailure(exit)).toBe(true);
+      expectInvalidDuration(yield* parseQueryTimeoutSeconds("abc").pipe(Effect.exit), "abc");
     }),
   );
 
   it.effect("rejects a negative duration", () =>
     Effect.gen(function* () {
-      const exit = yield* parseQueryTimeoutSeconds("-5s").pipe(Effect.exit);
-      expect(Exit.isFailure(exit)).toBe(true);
-    }),
-  );
-
-  it.effect("accepts Go-style microsecond duration aliases", () =>
-    Effect.gen(function* () {
-      expect(yield* parseQueryTimeoutSeconds(`15${"µ"}s`)).toBe(0);
-      expect(yield* parseQueryTimeoutSeconds(`15${"μ"}s`)).toBe(0);
+      expectInvalidDuration(yield* parseQueryTimeoutSeconds("-5s").pipe(Effect.exit), "-5s");
     }),
   );
 });
@@ -148,3 +161,25 @@ describe("schema and password helpers", () => {
     expect(withEnv("SUPABASE_DB_PASSWORD", "secret", () => localDbPassword())).toBe("secret");
   });
 });
+
+describe("oxfmt binding pin", () => {
+  it("stays on the oxfmt version postgrest-typegen resolves", () => {
+    const cliPackageJson = fileURLToPath(new URL("../../../../../package.json", import.meta.url));
+    const cliPkg = JSON.parse(readFileSync(cliPackageJson, "utf8")) as {
+      readonly devDependencies: Readonly<Record<string, string>>;
+    };
+    const typegenReq = createRequire(cliPackageJson);
+    const typegenPkg = typegenReq("@supabase/postgrest-typegen/package.json") as {
+      readonly dependencies: Readonly<Record<string, string>>;
+    };
+    const oxfmtVersion = typegenPkg.dependencies["oxfmt"];
+    expect(oxfmtVersion).toEqual(expect.stringMatching(/^\d+\.\d+\.\d+/));
+    const bindingPins = Object.entries(cliPkg.devDependencies).filter(([name]) =>
+      name.startsWith("@oxfmt/binding-"),
+    );
+    expect(bindingPins.length).toBeGreaterThan(0);
+    for (const [, version] of bindingPins) {
+      expect(version).toBe(oxfmtVersion);
+    }
+  });
+});