@dbx-tools/cli 0.9.58 → 0.9.61

package/src/genie-code/options.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI projection of the shared managed Genie Code options.
+ *
+ * @module
+ */
+
+export {
+  GenieCodeOptionsSchema as GenieCodeCliOptionsSchema,
+  resolveGenieCodeOptions as resolveGenieCodeCliOptions,
+} from "@dbx-tools/shared-genie-code/options";
+export type {
+  GenieCodeOptions as GenieCodeCliOptions,
+  ResolvedGenieCodeOptions as ResolvedGenieCodeCliOptions,
+} from "@dbx-tools/shared-genie-code/options";

package/src/genie-code/runner.ts

@@ -0,0 +1,106 @@
+/**
+ * Internal readiness gate and interactive Genie Code child process.
+ *
+ * @module
+ */
+
+import { AppKitChildProcess } from "@dbx-tools/appkit/child-process";
+import { asyncUtils, log } from "@dbx-tools/shared-core";
+import { GenieCodeRunnerOptionsSchema } from "@dbx-tools/shared-genie-code/options";
+
+/** Private environment field carrying serialized runner options. */
+const RUNNER_OPTIONS_ENV = "DBX_TOOLS_GENIE_RUNNER_OPTIONS";
+const logger = log.logger("genie-code:runner");
+
+/** Parse the serialized runner boundary from its private environment field. */
+export function genieCodeRunnerOptions(environment: NodeJS.ProcessEnv = process.env) {
+  const serialized = environment[RUNNER_OPTIONS_ENV];
+  if (!serialized) throw new Error(`${RUNNER_OPTIONS_ENV} is required`);
+  return GenieCodeRunnerOptionsSchema.parse(JSON.parse(serialized));
+}
+
+/** Wait until the guarded model-gateway health route accepts the runner token. */
+export async function waitForGenieCodeGateway(
+  healthUrl: string,
+  bearerToken: string,
+  timeoutMs: number,
+): Promise<void> {
+  for await (const ready of asyncUtils.poll(
+    async ({ signal }) => {
+      try {
+        const response = await fetch(healthUrl, {
+          headers: { authorization: `Bearer ${bearerToken}` },
+          signal,
+        });
+        return response.ok;
+      } catch {
+        return false;
+      }
+    },
+    {
+      intervalMs: 200,
+      timeoutMs,
+      predicate: (ready) => !ready,
+    },
+  )) {
+    if (ready) return;
+  }
+}
+
+/** Run Genie Code with inherited terminal streams after its gateway is ready. */
+export async function runGenieCodeChild(
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const options = genieCodeRunnerOptions(environment);
+  logger.info("waiting for model gateway", {
+    gateway: options.gatewayHealthUrl,
+    timeoutMs: options.startupTimeoutMs,
+  });
+  await waitForGenieCodeGateway(
+    options.gatewayHealthUrl,
+    options.bearerToken,
+    options.startupTimeoutMs,
+  );
+  logger.info("model gateway ready; starting Genie Code", {
+    executable: options.executable,
+    home: options.home,
+  });
+  const child = new AppKitChildProcess(
+    [
+      options.executable,
+      [...options.arguments],
+      {
+        cwd: process.cwd(),
+        env: {
+          ...environment,
+          GENIE_HOME: options.home,
+        },
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      },
+    ],
+    {
+      gracefulTimeoutMs: 5_000,
+      forceTimeoutMs: 1_000,
+    },
+  );
+  const running = child.start();
+  const shutdown = () => {
+    void child.shutdown();
+  };
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.once(signal, shutdown);
+  }
+  try {
+    const result = await running;
+    if (result.exitCode !== 0) process.exitCode = result.exitCode;
+  } finally {
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+      process.off(signal, shutdown);
+    }
+    await child.shutdown();
+  }
+}
+
+export { RUNNER_OPTIONS_ENV };

package/src/genie-code/runtime.ts

@@ -0,0 +1,212 @@
+/**
+ * Supervise Genie Code and its authenticated local model gateway.
+ *
+ * @module
+ */
+
+import { randomBytes } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { delimiter, dirname } from "node:path";
+import { DatabricksModelRegistry, models } from "@dbx-tools/appkit-model-gateway";
+import * as auth from "@dbx-tools/auth";
+import { resolveServicePackageBin } from "@dbx-tools/cli-service/definition";
+import type { BinContext } from "@dbx-tools/core/bin";
+import { workspaceClient } from "@dbx-tools/databricks";
+import { log } from "@dbx-tools/shared-core";
+import {
+  resolveGenieCodeOptions,
+  type GenieCodeOptions,
+  type GenieCodeRunnerOptions,
+} from "@dbx-tools/shared-genie-code/options";
+import concurrently from "concurrently";
+import getPort from "get-port";
+
+import { writeGenieCodeConfig, type GenieCodeHome } from "./config.ts";
+import { installGenieCode } from "./install.ts";
+import { RUNNER_OPTIONS_ENV } from "./runner.ts";
+
+const logger = log.logger("genie-code");
+
+/** Injectable owners used to prepare and supervise managed Genie Code. */
+export interface GenieCodeRuntimeDependencies {
+  createAuthClient: typeof auth.client.createAuthClient;
+  install: typeof installGenieCode;
+  port(options: { host: string; port?: number }): Promise<number>;
+  resolveBin(packageReference: string, binName: string): string;
+  resolveCodexModel(model: string, profile: string): Promise<string>;
+  supervise: typeof concurrently;
+  token(): string;
+  writeConfig: typeof writeGenieCodeConfig;
+}
+
+const DEFAULT_DEPENDENCIES: GenieCodeRuntimeDependencies = {
+  createAuthClient: auth.client.createAuthClient,
+  install: installGenieCode,
+  port: ({ host, port }) => getPort({ host, ...(port ? { port } : {}) }),
+  resolveBin: resolveServicePackageBin,
+  resolveCodexModel,
+  supervise: concurrently,
+  token: () => randomBytes(32).toString("base64url"),
+  writeConfig: writeGenieCodeConfig,
+};
+
+/** Resolve a Genie `--model` value to the Codex catalogue slug the gateway publishes. */
+async function resolveCodexModel(model: string, profile: string): Promise<string> {
+  const client = await workspaceClient.createWorkspaceClient({ profile });
+  const target = await new DatabricksModelRegistry({ client }).resolve(model, {
+    requiresTools: true,
+  });
+  if (!target) throw new Error(`Genie Code model not found: ${model}`);
+  return models.codexModelSlug(target);
+}
+
+/** Inputs accepted by managed Genie Code preparation and execution. */
+export interface RunGenieCodeOptions {
+  cwd?: string;
+  dependencies?: Partial<GenieCodeRuntimeDependencies>;
+  genieArgs?: readonly string[];
+  options?: GenieCodeOptions;
+}
+
+/** Resolved installation, auth, listener, and home for one invocation. */
+export interface PreparedGenieCodeRuntime {
+  bearerToken: string;
+  gatewayBaseUrl: string;
+  gatewayHealthUrl: string;
+  gatewayListen: string;
+  gatewayPort: number;
+  home: GenieCodeHome;
+  installation: BinContext;
+  model: string;
+  profile: string;
+}
+
+/** Resolve auth, installation, listener, and configuration before spawning children. */
+export async function prepareGenieCodeRuntime(
+  input: RunGenieCodeOptions = {},
+): Promise<PreparedGenieCodeRuntime> {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...input.dependencies };
+  const options = resolveGenieCodeOptions(input.options);
+  logger.info("resolving Databricks authentication", {
+    requestedProfile: options.profile,
+  });
+  const authClient = await dependencies.createAuthClient(
+    options.profile ? { profile: options.profile } : {},
+  );
+  const profile = authClient.profile;
+  if (!profile) {
+    throw new Error("Genie Code requires a configured Databricks profile");
+  }
+  logger.info("preparing Genie Code runtime", {
+    profile,
+    model: options.model,
+  });
+  const installation = await dependencies.install();
+  const host = options.gatewayListen.host;
+  const requestedPort = options.gatewayListen.port;
+  const gatewayPort = await dependencies.port({
+    host,
+    ...(requestedPort > 0 ? { port: requestedPort } : {}),
+  });
+  if (requestedPort > 0 && gatewayPort !== requestedPort) {
+    throw new Error(`Genie Code gateway port ${requestedPort} is already in use`);
+  }
+  const model = await dependencies.resolveCodexModel(options.model, profile);
+  logger.info("resolved Genie Code model", { requested: options.model, model });
+  const urlHost = host.includes(":") ? `[${host}]` : host;
+  const gatewayBaseUrl = `http://${urlHost}:${gatewayPort}/v1`;
+  const gatewayHealthUrl = `http://${urlHost}:${gatewayPort}/api/healthz`;
+  const gatewayListen = `tcp://${urlHost}:${gatewayPort}`;
+  const bearerToken = dependencies.token();
+  const home = await dependencies.writeConfig({
+    bearerToken,
+    gatewayBaseUrl,
+    model,
+    profile,
+    projectDirectory: input.cwd ?? process.cwd(),
+  });
+  return {
+    bearerToken,
+    gatewayBaseUrl,
+    gatewayHealthUrl,
+    gatewayListen,
+    gatewayPort,
+    home,
+    installation,
+    model,
+    profile,
+  };
+}
+
+function shellExecutable(path: string): string {
+  if (process.platform === "win32") return `"${path.replaceAll('"', '""')}"`;
+  return `'${path.replaceAll("'", "'\\''")}'`;
+}
+
+function childPath(...paths: string[]): string {
+  return [...new Set([...paths.map(dirname), process.env.PATH].filter(Boolean))].join(delimiter);
+}
+
+/** Run Genie Code and the model gateway until either process exits. */
+export async function runGenieCode(input: RunGenieCodeOptions = {}): Promise<void> {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...input.dependencies };
+  const prepared = await prepareGenieCodeRuntime({
+    ...input,
+    dependencies,
+  });
+  const gatewayBin = dependencies.resolveBin(import.meta.url, "dbx-model-gateway");
+  const runnerBin = dependencies.resolveBin(import.meta.url, "dbx-genie");
+  const path = childPath(gatewayBin, runnerBin);
+  const runnerOptions: GenieCodeRunnerOptions = {
+    executable: prepared.installation.path,
+    arguments: ["-p", prepared.home.overlayName, ...(input.genieArgs ?? [])],
+    home: prepared.home.home,
+    gatewayHealthUrl: prepared.gatewayHealthUrl,
+    bearerToken: prepared.bearerToken,
+    startupTimeoutMs: 60_000,
+  };
+  const { result } = dependencies.supervise(
+    [
+      {
+        command: shellExecutable(gatewayBin),
+        name: "gateway",
+        env: {
+          ...process.env,
+          PATH: path,
+          LISTEN: prepared.gatewayListen,
+          DATABRICKS_CONFIG_PROFILE: prepared.profile,
+          DBX_TOOLS_MODEL_GATEWAY_BEARER_TOKEN: prepared.bearerToken,
+        },
+      },
+      {
+        command: shellExecutable(runnerBin),
+        name: "genie",
+        env: {
+          ...process.env,
+          PATH: path,
+          DATABRICKS_CONFIG_PROFILE: prepared.profile,
+          [RUNNER_OPTIONS_ENV]: JSON.stringify(runnerOptions),
+        },
+      },
+    ],
+    {
+      cwd: input.cwd ?? process.cwd(),
+      raw: true,
+      killOthersOn: ["failure", "success"],
+      killSignal: "SIGTERM",
+      killTimeout: 17_000,
+      successCondition: "command-genie",
+    },
+  );
+  logger.info("started Genie Code and model gateway", {
+    profile: prepared.profile,
+    model: prepared.model,
+    gateway: prepared.gatewayBaseUrl,
+    home: prepared.home.home,
+  });
+  try {
+    await result;
+  } finally {
+    await rm(prepared.home.overlayPath, { force: true });
+  }
+}

package/src/graphiti/cli.ts

@@ -0,0 +1,75 @@
+/**
+ * Commander-owned Graphiti CLI and shared current-user service definition.
+ *
+ * This module owns every user-facing Graphiti command. The shared Graphiti Zod
+ * schema owns its options, environment names, defaults, and validation. The
+ * Node Graphiti package owns runtime and Python interaction.
+ *
+ * @module
+ */
+import { addArgs, parseArgs, serializeArgs } from "@dbx-tools/cli-args";
+import { buildServiceCommand, type CliServiceCliDependencies } from "@dbx-tools/cli-service/cli";
+import { defineService, type CliServiceDefinition } from "@dbx-tools/cli-service/definition";
+import { runGraphiti, type GraphitiRuntimeOptions } from "@dbx-tools/graphiti/runtime";
+import { Command } from "commander";
+
+import { PACKAGE_VERSION } from "../../index.ts";
+import {
+  GraphitiCliOptionsSchema,
+  GraphitiOptionsSchema,
+  type GraphitiOptions,
+} from "./options.ts";
+
+/** Injectable runtime and service lifecycle boundaries for CLI callers. */
+export interface GraphitiCliDependencies {
+  /** Run the Graphiti stack through the Node runtime owner. */
+  run(options: GraphitiRuntimeOptions): Promise<void>;
+  /** Shared service command dependencies for tests and embedding. */
+  readonly service?: CliServiceCliDependencies;
+}
+
+/** Runtime options persisted when installing the Graphiti desktop service. */
+export type GraphitiServiceOptions = GraphitiOptions;
+
+/** Define a Graphiti service without duplicating installation or lifecycle policy. */
+export function graphitiServiceDefinition(
+  options: GraphitiServiceOptions = {},
+): CliServiceDefinition {
+  return defineService(import.meta.url, {
+    id: "dbx-tools.cli-graphiti",
+    name: "dbx graphiti",
+    pythonPackage: { name: "dbx-tools-graphiti" },
+    command: {
+      binName: "dbx-graphiti",
+      arguments: serializeArgs(GraphitiOptionsSchema.parse(options)),
+    },
+  });
+}
+
+/** Build foreground execution and shared desktop-service commands. */
+export function buildProgram(
+  name = "dbx graphiti",
+  dependencies: GraphitiCliDependencies = { run: runGraphiti },
+): Command {
+  const program = addArgs(
+    new Command()
+      .name(name)
+      .description("Run Graphiti or manage its current-user desktop service")
+      .version(PACKAGE_VERSION, "-v, --version"),
+    GraphitiCliOptionsSchema,
+  ).action(async () => {
+    await dependencies.run(graphitiOptions(program));
+  });
+
+  program.addCommand(
+    buildServiceCommand(
+      () => graphitiServiceDefinition(graphitiOptions(program)),
+      dependencies.service,
+    ),
+  );
+  return program;
+}
+
+function graphitiOptions(command: Command): GraphitiOptions {
+  return GraphitiOptionsSchema.parse(parseArgs(command, GraphitiCliOptionsSchema));
+}

package/src/graphiti/options.ts

@@ -0,0 +1,20 @@
+/**
+ * Graphiti CLI option surface.
+ *
+ * The Node Graphiti runtime owns the complete shared option contract. This
+ * module re-exports that surface without creating parallel CLI policy.
+ *
+ * @module
+ */
+
+export {
+  GRAPHITI_DEFAULTS,
+  GraphitiCliOptionsSchema,
+  GraphitiOptionsSchema,
+  ResolvedGraphitiOptionsSchema,
+  graphitiOptionOverrides,
+  graphitiOptionsEnvironment,
+  graphitiOptionsFromEnvironment,
+  resolveGraphitiOptions,
+} from "@dbx-tools/graphiti/options";
+export type { GraphitiOptions, ResolvedGraphitiOptions } from "@dbx-tools/graphiti/options";

package/src/lakebase-proxy/cancellation.ts

@@ -0,0 +1,116 @@
+/** PostgreSQL cancellation key translation and TLS forwarding. */
+
+import { randomBytes } from "node:crypto";
+import { createConnection, isIP, type Socket } from "node:net";
+import { connect as connectTls, type TLSSocket } from "node:tls";
+
+import { cancelRequest, sslRequest, type CancelMessage } from "./protocol.ts";
+
+/** Upstream PostgreSQL backend key used to forward a cancellation request. */
+export interface CancellationTarget {
+  host: string;
+  port: number;
+  processId: number;
+  secretKey: number;
+}
+
+/** Sends one PostgreSQL cancellation request to its upstream backend. */
+export type CancellationForwarder = (target: CancellationTarget) => Promise<void>;
+
+let nextProcessId = 10_000;
+
+/** Maps synthetic local backend keys onto real upstream cancellation targets. */
+export class CancellationRegistry {
+  private readonly targets = new Map<string, CancellationTarget>();
+
+  constructor(private readonly forwarder: CancellationForwarder = forwardCancellation) {}
+
+  register(target: CancellationTarget): CancelMessage {
+    const processId = nextProcessId++;
+    const secretKey = randomBytes(4).readInt32BE(0);
+    this.targets.set(key(processId, secretKey), target);
+    return { kind: "cancel", processId, secretKey };
+  }
+
+  remove(message: CancelMessage): void {
+    this.targets.delete(key(message.processId, message.secretKey));
+  }
+
+  async forward(message: CancelMessage): Promise<boolean> {
+    const target = this.targets.get(key(message.processId, message.secretKey));
+    if (!target) return false;
+    await this.forwarder(target);
+    return true;
+  }
+}
+
+/** Forward a PostgreSQL cancellation request over a verified TLS connection. */
+export async function forwardCancellation(target: CancellationTarget): Promise<void> {
+  const socket = createConnection({ host: target.host, port: target.port });
+  await event(socket, "connect");
+  socket.write(sslRequest());
+  const response = await readByte(socket);
+  if (response !== "S".charCodeAt(0)) {
+    socket.destroy();
+    throw new Error("Lakebase upstream refused TLS for cancellation");
+  }
+  const tls = connectTls({
+    socket,
+    rejectUnauthorized: true,
+    ...(isIP(target.host) === 0 ? { servername: target.host } : {}),
+  });
+  await event(tls, "secureConnect");
+  await writeAndClose(tls, cancelRequest(target.processId, target.secretKey));
+}
+
+function key(processId: number, secretKey: number): string {
+  return `${processId}:${secretKey}`;
+}
+
+function event(socket: Socket | TLSSocket, name: "connect" | "secureConnect"): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onEvent = () => finish();
+    const onError = (error: Error) => finish(error);
+    const finish = (error?: Error) => {
+      socket.off(name, onEvent);
+      socket.off("error", onError);
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.once(name, onEvent);
+    socket.once("error", onError);
+  });
+}
+
+function readByte(socket: Socket): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const onData = (chunk: Buffer) => {
+      finish();
+      if (chunk.length > 1) socket.unshift(chunk.subarray(1));
+      resolve(chunk[0]!);
+    };
+    const onError = (error: Error) => {
+      finish();
+      reject(error);
+    };
+    const onEnd = () => {
+      finish();
+      reject(new Error("Lakebase upstream closed during TLS negotiation"));
+    };
+    const finish = () => {
+      socket.off("data", onData);
+      socket.off("error", onError);
+      socket.off("end", onEnd);
+    };
+    socket.once("data", onData);
+    socket.once("error", onError);
+    socket.once("end", onEnd);
+  });
+}
+
+function writeAndClose(socket: TLSSocket, packet: Buffer): Promise<void> {
+  return new Promise((resolve, reject) => {
+    socket.end(packet, () => resolve());
+    socket.once("error", reject);
+  });
+}

package/src/lakebase-proxy/cli.ts

@@ -0,0 +1,80 @@
+/** Commander entry point for the pure Node Lakebase proxy. */
+
+import { addArgs, parseArgs, serializeArgs } from "@dbx-tools/cli-args";
+import { buildServiceCommand, type CliServiceCliDependencies } from "@dbx-tools/cli-service/cli";
+import { defineService, type CliServiceDefinition } from "@dbx-tools/cli-service/definition";
+import { connectionUrl } from "@dbx-tools/lakebase";
+import { Command } from "commander";
+
+import { PACKAGE_VERSION } from "../../index.ts";
+import {
+  LakebaseProxyOptionsSchema,
+  LakebaseProxyUrlOptionsSchema,
+  resolveLakebaseProxyOptions,
+  type LakebaseProxyOptions,
+} from "./options.ts";
+import { LakebaseProxy } from "./proxy.ts";
+
+/** Injectable service boundary for Lakebase proxy CLI composition and tests. */
+export interface LakebaseProxyCliDependencies {
+  readonly service?: CliServiceCliDependencies;
+}
+
+/** Build the tray-only Lakebase proxy service definition. */
+export function lakebaseProxyServiceDefinition(
+  options: LakebaseProxyOptions = {},
+): CliServiceDefinition {
+  const resolved = resolveLakebaseProxyOptions(options);
+  return defineService(import.meta.url, {
+    id: "dbx-tools.cli-lakebase-proxy",
+    name: "dbx lakebase proxy",
+    command: {
+      binName: "dbx-lakebase-proxy",
+      arguments: serializeArgs(resolved),
+    },
+  });
+}
+
+/** Build the Lakebase proxy command-line program. */
+export function buildProgram(
+  name = "dbx lakebase-proxy",
+  dependencies: LakebaseProxyCliDependencies = {},
+): Command {
+  const program = addArgs(
+    new Command(name)
+      .description("Run a loopback PostgreSQL proxy for Databricks Lakebase")
+      .version(PACKAGE_VERSION)
+      .enablePositionalOptions(),
+    LakebaseProxyOptionsSchema,
+  ).action(async () => {
+    const proxy = new LakebaseProxy(parseArgs(program, LakebaseProxyOptionsSchema));
+    await proxy.listen();
+    await waitForShutdown();
+    await proxy.close();
+  });
+
+  const urlCommand = addArgs(
+    program.command("url").description("Format a local PostgreSQL URL for a Lakebase target"),
+    LakebaseProxyUrlOptionsSchema,
+  ).action(() => {
+    const options = parseArgs(urlCommand, LakebaseProxyUrlOptionsSchema);
+    const target = options.target ?? options.lakebaseEndpoint!;
+    process.stdout.write(`${connectionUrl(target, options.listen.host, options.listen.port)}\n`);
+  });
+  let installCommand!: Command;
+  const serviceCommand = buildServiceCommand(() => {
+    return lakebaseProxyServiceDefinition(parseArgs(installCommand, LakebaseProxyOptionsSchema));
+  }, dependencies.service);
+  installCommand = serviceCommand.commands.find((command) => command.name() === "install")!;
+  addArgs(installCommand, LakebaseProxyOptionsSchema);
+  program.addCommand(serviceCommand);
+  return program;
+}
+
+function waitForShutdown(): Promise<void> {
+  return new Promise((resolve) => {
+    const shutdown = () => resolve();
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}

package/src/lakebase-proxy/options.ts

@@ -0,0 +1,56 @@
+/**
+ * Lakebase proxy listener, service, and URL command options.
+ *
+ * @module
+ */
+
+import { options } from "@dbx-tools/shared-core";
+import { z } from "zod";
+
+const text = (description: string) => z.string().trim().min(1).optional().describe(description);
+
+export const LakebaseProxyOptionsSchema = z
+  .object({
+    ...options.PostgresOptionsSchema.shape,
+    listen: options
+      .listenAddressSchema({ port: 5432, loopback: true })
+      .describe("Loopback listener address."),
+    startupTimeoutSeconds: z.coerce
+      .number<number>()
+      .int()
+      .nonnegative()
+      .default(30)
+      .describe("Startup timeout in seconds."),
+    profile: options.DatabricksOptionsSchema.shape.profile.describe("Exact Databricks profile."),
+  })
+  .strict()
+  .describe("Lakebase proxy listener and service options.");
+
+export const LakebaseProxyUrlOptionsSchema = z
+  .object({
+    target: text("Lakebase project, resource path, host, or URL."),
+    lakebaseEndpoint: options.LakebaseOptionsSchema.shape.lakebaseEndpoint,
+    listen: options.listenAddressSchema({ port: 5432 }).describe("Local proxy address."),
+  })
+  .strict()
+  .refine(
+    (configured) => configured.target !== undefined || configured.lakebaseEndpoint !== undefined,
+    {
+      message: "URL requires target or endpoint.",
+      path: ["target"],
+    },
+  )
+  .describe("Options for formatting a local Lakebase PostgreSQL URL.");
+
+export type LakebaseProxyOptions = z.input<typeof LakebaseProxyOptionsSchema>;
+
+export type ResolvedLakebaseProxyOptions = z.output<typeof LakebaseProxyOptionsSchema>;
+
+export type LakebaseProxyUrlOptions = z.output<typeof LakebaseProxyUrlOptionsSchema>;
+
+/** Validate and default Lakebase proxy listener options. */
+export function resolveLakebaseProxyOptions(
+  options: LakebaseProxyOptions = {},
+): ResolvedLakebaseProxyOptions {
+  return LakebaseProxyOptionsSchema.parse(options);
+}