@pablozaiden/webapp 0.2.0 → 0.2.1

package/README.md

@@ -21,6 +21,7 @@ Both examples run with Bun native hot reload through `bun --hot`, with no standa
 | `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
 | `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
+| `@pablozaiden/webapp/cli` | One-binary command helpers, device-auth credentials and generic API CLI caller |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |
 
 See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Use `bun run screenshots` for reproducible manual visual captures. Release/publishing details for this package are in `docs/release.md`.

package/docs/cli.md

@@ -0,0 +1,45 @@
+# CLI helpers
+
+Apps built with the framework should be one app and one binary. The binary can expose subcommands such as `serve`, `version`, `update`, app-specific commands, and optional framework-backed commands like `auth`, `status`, `api` and `schema`.
+
+Use `@pablozaiden/webapp/cli` for small composable helpers, not a mandatory CLI framework:
+
+```ts
+import { dispatchCliCommand, printCliResult } from "@pablozaiden/webapp/cli";
+
+const result = await dispatchCliCommand({
+  args: Bun.argv.slice(2),
+  help: "Usage: my-app <serve|version|notify>",
+  defaultCommand: "serve",
+  commands: {
+    serve: async () => {
+      app.start();
+      await new Promise(() => undefined);
+      return { exitCode: 0 };
+    },
+    version: () => ({ exitCode: 0, output: version }),
+    notify: (args) => runNotifyCommand(args),
+  },
+});
+
+process.exitCode = printCliResult(result);
+```
+
+Device-auth CLI helpers can be composed into apps that need authenticated CLI calls. Public-token commands, such as webhook notification commands, can stay app-owned and do not need framework auth.
+
+Route metadata can power generic API commands:
+
+```ts
+import { runApiCliCommand } from "@pablozaiden/webapp/cli";
+import { createRouteCatalog } from "@pablozaiden/webapp/server";
+
+const catalog = createRouteCatalog(routes);
+const result = await runApiCliCommand({
+  catalog,
+  args,
+  baseUrl: "http://localhost:3000",
+  credentials,
+});
+```
+
+`runApiCliCommand` can list endpoints, print schema metadata, call endpoints with `--method` and `--payload`, attach bearer credentials, and refresh once on `401`.

package/docs/deployment.md

@@ -22,8 +22,11 @@ Run the binary with the same CLI contract:
 ```bash
 MY_APP_PORT=3300 ./dist/my-app serve
 ./dist/my-app version
+./dist/my-app api items
 ```
 
+Keep server and CLI modes in the same binary. App-specific commands and framework-backed commands should be subcommands of that binary rather than separate executables.
+
 ## Docker
 
 Examples include Dockerfiles that copy a Bun-compiled Linux binary into a runtime image. Build the binary for the container architecture first, then build the image:

package/docs/getting-started.md

@@ -11,6 +11,9 @@ const items: Array<{ id: string; userId: string; title: string }> = [];
 const routes = defineRoutes({
   "/api/items": {
     auth: "user",
+    description: "List or create items.",
+    cliPath: "items",
+    tags: ["items"],
     GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items)),
     async POST(req, ctx) {
       const user = ctx.requireUser();
@@ -40,6 +43,17 @@ const app = createWebAppServer({
 await app.runFromCli();
 ```
 
+Apps should stay one app and one binary. Use subcommands for different modes:
+
+```bash
+my-app serve
+my-app version
+my-app api items
+my-app notify --message "optional app-owned command"
+```
+
+See `docs/cli.md` for framework CLI helpers and generic API command support.
+
 Frontend entrypoints should use `renderWebApp` so Bun/browser hot reload reuses the existing React root instead of calling `createRoot()` twice. Import the framework CSS explicitly so Bun hot reload observes style changes:
 
 ```tsx

package/docs/server.md

@@ -6,6 +6,9 @@ Use `createWebAppServer` with `defineRoutes`. Route patterns support exact path
 const routes = defineRoutes<AppEvent>({
   "/api/projects": {
     auth: "user",
+    description: "List or create projects.",
+    cliPath: "projects",
+    tags: ["projects"],
     GET: (_req, ctx) => {
       return jsonResponse(ctx.filterOwned(projects));
     },
@@ -45,6 +48,18 @@ Route defaults are intentionally secure:
 
 Set `auth: "public", sameOrigin: "never"` only for deliberate unauthenticated endpoints such as health probes, webhooks or callback receivers.
 
+Route definitions can include optional metadata. This keeps the API route table as the single source of truth for handlers, CLI endpoint listing, schema output and docs:
+
+| Field | Meaning |
+| --- | --- |
+| `description` | Human-readable route description |
+| `cliPath` | CLI-friendly path; defaults to the API path without `/api/` |
+| `tags` | Grouping labels for docs/CLI |
+| `requestSchema`, `querySchema`, `responseSchema` | Optional schema objects for CLI/docs |
+| `catalog: false` | Exclude a route from generated catalogs |
+
+Use `createRouteCatalog(routes)` and `findRouteCatalogEntry(catalog, input)` to power app CLI commands without maintaining a second route catalog.
+
 Prefer explicit `auth: "user"`, `auth: "admin"` or `auth: "owner"` on app routes. They enforce the role before the handler runs, including API-key and device bearer requests.
 
 Route context is user-aware:
@@ -78,3 +93,38 @@ Built-in endpoints include:
 | `/api/preferences/theme`, `/api/preferences/log-level` | Settings persistence |
 | `/api/server/kill` | Authenticated server shutdown |
 | `/api/ws` | Realtime websocket by default |
+
+## Public/static routes
+
+Declare public non-API assets explicitly with `publicRoutes`:
+
+```ts
+createWebAppServer({
+  // ...
+  publicRoutes: {
+    "/manifest.webmanifest": {
+      headers: { "content-type": "application/manifest+json" },
+      GET: manifestJson,
+    },
+    "/service-worker": serviceWorker,
+  },
+});
+```
+
+Only declared public routes are served this way. Unknown `/api/*` paths still return `404`, while normal frontend paths still return the React index.
+
+## App-owned websocket upgrades
+
+Normal app state should use framework realtime. For raw transports such as terminals, VNC, or port-forward proxies, route handlers may call `ctx.server?.upgrade(...)` and return `undefined`:
+
+```ts
+"/api/terminal": {
+  auth: "user",
+  sameOrigin: "always",
+  GET: (req, ctx) => ctx.server?.upgrade(req, {
+    data: { webappSocketHandler: "terminal", sessionId: ctx.params.id },
+  }) ? undefined : new Response("Upgrade failed", { status: 400 }),
+}
+```
+
+Register matching handlers with `websockets`. Framework auth and same-origin checks run before the upgrade route handler.

package/docs/settings.md

@@ -11,6 +11,10 @@ Settings is framework-owned so apps stay consistent. It includes:
 - Admin server kill
 - Version/about
 
+Destructive actions in Settings use the framework `ConfirmDialog` before mutating. This includes deleting users, deleting API keys, deleting passkeys, revoking device-auth sessions, and killing the server.
+
+The server kill control follows the normal Settings row layout: explanation on the left, action on the right. After confirmation and a successful response, Settings shows a 15-second shutdown countdown progress bar that visibly drains before reloading the page.
+
 Apps can append structured custom sections:
 
 ```tsx

package/docs/ui-guidelines.md

@@ -54,6 +54,8 @@ Generated screenshots live in `artifacts/screenshots`:
 
 Use `bun run screenshots` to regenerate these captures with Playwright. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
 
-Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles.
+Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles. When screenshots are captured to validate a visual change, review them against the specific goal; capturing files without checking the result is not validation.
+
+All destructive delete actions must use the framework `ConfirmDialog` before calling the delete endpoint. Server lifecycle actions such as kill/reboot must also require confirmation and show the standard 15-second shutdown countdown progress bar after the request succeeds.
 
 Prefer the framework action-menu pattern for app commands. Actions such as New task, New note, New project, archive, delete, or state transitions should live in `SidebarNode.actions` and/or `WebAppRoot.header.getActions` so they appear behind the three-line title-bar/item action menus. Use discrete buttons mainly for form submission or inline controls that cannot reasonably live in an action menu.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
     "./web": "./src/web/index.ts",
     "./web/styles.css": "./src/web/styles.css",
     "./contracts": "./src/contracts/index.ts",
+    "./cli": "./src/cli/index.ts",
     "./build": "./src/build/index.ts"
   },
   "scripts": {

package/src/cli/api-command.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { findRouteCatalogEntry, type RouteCatalogEntry } from "../server/route-catalog";
+import { getAuthorizedHeaders, refreshDeviceCredentials, type StoredDeviceCredentials } from "./device-auth";
+import { readOption, type CliCommandResult } from "./runtime";
+
+export interface ApiCliCredentialsStore {
+  read(): Promise<StoredDeviceCredentials | undefined>;
+  write(value: StoredDeviceCredentials): Promise<void>;
+}
+
+export interface ApiCliCommandOptions {
+  catalog: readonly RouteCatalogEntry[];
+  args: string[];
+  mode?: "api" | "schema";
+  baseUrl?: string;
+  credentials?: ApiCliCredentialsStore;
+  fetchFn?: typeof fetch;
+  now?: () => Date;
+}
+
+function schemaJson(schema: unknown): unknown {
+  if (!schema) return undefined;
+  try {
+    return z.toJSONSchema(schema as z.ZodTypeAny);
+  } catch {
+    return schema;
+  }
+}
+
+function listOutput(catalog: readonly RouteCatalogEntry[]): string {
+  return catalog
+    .filter((entry) => entry.path.startsWith("/api/"))
+    .map((entry) => `${entry.methods.join(", ")} ${entry.cliPath}${entry.description ? ` - ${entry.description}` : ""}`)
+    .join("\n");
+}
+
+function schemaOutput(entry: RouteCatalogEntry): string {
+  return JSON.stringify({
+    path: entry.path,
+    cliPath: entry.cliPath,
+    methods: entry.methods,
+    auth: entry.auth,
+    sameOrigin: entry.sameOrigin,
+    scopes: entry.scopes,
+    description: entry.description,
+    tags: entry.tags,
+    querySchema: schemaJson(entry.querySchema),
+    requestSchema: schemaJson(entry.requestSchema),
+    responseSchema: schemaJson(entry.responseSchema),
+  }, null, 2);
+}
+
+function endpointArg(args: string[]): string | undefined {
+  return args.find((arg) => !arg.startsWith("--"));
+}
+
+async function authHeaders(input: ApiCliCommandOptions): Promise<Headers> {
+  const headers = new Headers({ accept: "application/json" });
+  const stored = await input.credentials?.read();
+  if (!stored) return headers;
+  const refreshed = await refreshDeviceCredentials({
+    credentials: stored,
+    store: input.credentials,
+    fetchFn: input.fetchFn,
+    now: input.now,
+  });
+  return refreshed ? getAuthorizedHeaders(refreshed, headers) : headers;
+}
+
+export async function runApiCliCommand(input: ApiCliCommandOptions): Promise<CliCommandResult> {
+  const endpoint = endpointArg(input.args);
+  if (!endpoint) {
+    return { exitCode: 0, output: listOutput(input.catalog) };
+  }
+  const match = findRouteCatalogEntry(input.catalog, endpoint);
+  if (!match) {
+    return { exitCode: 1, error: `Unknown API endpoint: ${endpoint}` };
+  }
+  if (input.mode === "schema") {
+    return { exitCode: 0, output: schemaOutput(match.entry) };
+  }
+  const method = (readOption(input.args, ["--method", "-X"]) ?? match.entry.methods[0] ?? "GET").toUpperCase();
+  if (!match.entry.methods.includes(method as never)) {
+    return { exitCode: 1, error: `Method ${method} is not available for ${match.entry.cliPath}` };
+  }
+  const payload = readOption(input.args, ["--payload", "--data", "-d"]);
+  const baseUrl = (input.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+  const url = new URL(`${baseUrl}${match.path}`);
+  const headers = await authHeaders(input);
+  let body: string | undefined;
+  if (payload !== undefined) {
+    JSON.parse(payload) as unknown;
+    body = payload;
+    headers.set("content-type", "application/json");
+  }
+  const send = () => (input.fetchFn ?? fetch)(url, { method, headers, body });
+  let response = await send();
+  if (response.status === 401 && input.credentials) {
+    const stored = await input.credentials.read();
+    if (stored) {
+      const refreshed = await refreshDeviceCredentials({ credentials: { ...stored, accessTokenExpiresAt: new Date(0).toISOString() }, store: input.credentials, fetchFn: input.fetchFn, now: input.now });
+      if (refreshed) {
+        headers.set("authorization", `${refreshed.tokenType} ${refreshed.accessToken}`);
+      }
+      response = await send();
+    }
+  }
+  const text = await response.text();
+  let parsed: unknown = text;
+  try {
+    parsed = text ? JSON.parse(text) as unknown : null;
+  } catch {
+    parsed = text || null;
+  }
+  return {
+    exitCode: response.ok ? 0 : 1,
+    output: JSON.stringify({ status: { code: response.status, ok: response.ok, text: response.statusText }, response: parsed }, null, 2),
+  };
+}

package/src/cli/credentials.ts

@@ -0,0 +1,67 @@
+import { chmodSync } from "node:fs";
+import { mkdir, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface JsonFileStore<T> {
+  path(): string;
+  read(): Promise<T | undefined>;
+  write(value: T): Promise<void>;
+  clear(): Promise<void>;
+}
+
+function chmodIfPossible(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // Not all platforms/filesystems support POSIX modes.
+  }
+}
+
+export function createJsonFileStore<T>(input: {
+  appDirectoryName: string;
+  fileName: string;
+  envHome?: string;
+  parse(value: unknown): T;
+  home?: string;
+}): JsonFileStore<T> {
+  const stateDir = () => {
+    const explicit = input.envHome ? process.env[input.envHome]?.trim() : undefined;
+    const home = input.home ?? process.env["HOME"]?.trim();
+    if (explicit) return explicit;
+    if (!home) throw new Error("HOME is not set");
+    return join(home, input.appDirectoryName);
+  };
+  const filePath = () => join(stateDir(), input.fileName);
+  return {
+    path: filePath,
+    async read() {
+      try {
+        return input.parse(JSON.parse(await readFile(filePath(), "utf8")) as unknown);
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+    async write(value) {
+      const target = filePath();
+      const dir = dirname(target);
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      chmodIfPossible(dir, 0o700);
+      const temp = join(dir, `.${input.fileName}.${process.pid}.${crypto.randomUUID()}.tmp`);
+      try {
+        await Bun.write(temp, `${JSON.stringify(value, null, 2)}\n`);
+        chmodIfPossible(temp, 0o600);
+        await rename(temp, target);
+        chmodIfPossible(target, 0o600);
+      } catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+      }
+    },
+    async clear() {
+      await rm(filePath(), { force: true });
+    },
+  };
+}

package/src/cli/device-auth.ts

@@ -0,0 +1,179 @@
+import { createJsonFileStore, type JsonFileStore } from "./credentials";
+
+export interface StoredDeviceCredentials {
+  baseUrl: string;
+  clientId: string;
+  accessToken: string;
+  refreshToken: string;
+  tokenType: "Bearer";
+  scope: string;
+  accessTokenExpiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export function normalizeBaseUrl(value: string): string {
+  const url = new URL(value.trim());
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Invalid base URL protocol: ${url.protocol}`);
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+export function parseStoredDeviceCredentials(value: unknown): StoredDeviceCredentials {
+  if (!value || typeof value !== "object") {
+    throw new Error("Stored credentials must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  const credentials = {
+    baseUrl: String(record["baseUrl"] ?? ""),
+    clientId: String(record["clientId"] ?? ""),
+    accessToken: String(record["accessToken"] ?? ""),
+    refreshToken: String(record["refreshToken"] ?? ""),
+    tokenType: record["tokenType"],
+    scope: String(record["scope"] ?? ""),
+    accessTokenExpiresAt: String(record["accessTokenExpiresAt"] ?? ""),
+    createdAt: String(record["createdAt"] ?? ""),
+    updatedAt: String(record["updatedAt"] ?? ""),
+  };
+  if (!credentials.baseUrl || !credentials.clientId || !credentials.accessToken || !credentials.refreshToken || credentials.tokenType !== "Bearer") {
+    throw new Error("Stored credentials are invalid");
+  }
+  return credentials as StoredDeviceCredentials;
+}
+
+export function createDeviceCredentialsStore(input: {
+  appDirectoryName: string;
+  envHome?: string;
+  fileName?: string;
+  home?: string;
+}): JsonFileStore<StoredDeviceCredentials> {
+  return createJsonFileStore({
+    appDirectoryName: input.appDirectoryName,
+    fileName: input.fileName ?? "device-auth.json",
+    envHome: input.envHome,
+    home: input.home,
+    parse: parseStoredDeviceCredentials,
+  });
+}
+
+export function getAuthorizedHeaders(credentials: StoredDeviceCredentials, headers?: HeadersInit): Headers {
+  const result = new Headers(headers);
+  result.set("authorization", `${credentials.tokenType} ${credentials.accessToken}`);
+  return result;
+}
+
+function isExpired(credentials: StoredDeviceCredentials, now: Date): boolean {
+  return new Date(credentials.accessTokenExpiresAt).getTime() <= now.getTime();
+}
+
+async function requestJson(fetchFn: typeof fetch, url: string, init?: RequestInit): Promise<{ response: Response; body: unknown }> {
+  const headers = new Headers(init?.headers);
+  headers.set("accept", "application/json");
+  const response = await fetchFn(url, { ...init, headers });
+  const text = await response.text();
+  if (!text) {
+    return { response, body: undefined };
+  }
+  try {
+    return { response, body: JSON.parse(text) as unknown };
+  } catch {
+    return { response, body: text };
+  }
+}
+
+function tokenError(body: unknown, status: number): string {
+  if (body && typeof body === "object") {
+    const record = body as Record<string, unknown>;
+    return String(record["error_description"] ?? record["message"] ?? record["error"] ?? `Request failed with status ${status}`);
+  }
+  return `Request failed with status ${status}`;
+}
+
+function tokenCredentials(baseUrl: string, clientId: string, tokenSet: Record<string, unknown>, now: Date): StoredDeviceCredentials {
+  const expiresIn = Number(tokenSet["expires_in"] ?? 0);
+  return {
+    baseUrl,
+    clientId,
+    accessToken: String(tokenSet["access_token"] ?? ""),
+    refreshToken: String(tokenSet["refresh_token"] ?? ""),
+    tokenType: "Bearer",
+    scope: String(tokenSet["scope"] ?? ""),
+    accessTokenExpiresAt: new Date(now.getTime() + expiresIn * 1000).toISOString(),
+    createdAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  };
+}
+
+export async function refreshDeviceCredentials(input: {
+  credentials: StoredDeviceCredentials;
+  store?: { write(value: StoredDeviceCredentials): Promise<void> };
+  fetchFn?: typeof fetch;
+  now?: () => Date;
+}): Promise<StoredDeviceCredentials | undefined> {
+  if (!isExpired(input.credentials, (input.now ?? (() => new Date()))())) {
+    return input.credentials;
+  }
+  const now = input.now?.() ?? new Date();
+  const { response, body } = await requestJson(input.fetchFn ?? fetch, `${input.credentials.baseUrl}/api/auth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      refresh_token: input.credentials.refreshToken,
+      client_id: input.credentials.clientId,
+    }),
+  });
+  if (!response.ok) {
+    return undefined;
+  }
+  const next = tokenCredentials(input.credentials.baseUrl, input.credentials.clientId, body as Record<string, unknown>, now);
+  await input.store?.write(next);
+  return next;
+}
+
+export async function runDeviceAuthCommand(input: {
+  baseUrl: string;
+  clientId: string;
+  store: JsonFileStore<StoredDeviceCredentials>;
+  scope?: string;
+  fetchFn?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+  out?: (message: string) => void;
+}): Promise<number> {
+  const baseUrl = normalizeBaseUrl(input.baseUrl);
+  const fetchFn = input.fetchFn ?? fetch;
+  const now = input.now ?? (() => new Date());
+  const out = input.out ?? console.log;
+  const start = await requestJson(fetchFn, `${baseUrl}/api/auth/device`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ clientId: input.clientId, scope: input.scope }),
+  });
+  if (!start.response.ok) throw new Error(tokenError(start.body, start.response.status));
+  const started = start.body as Record<string, unknown>;
+  out(`Open: ${String(started["verification_uri_complete"] ?? started["verification_uri"])}`);
+  out(`Code: ${String(started["user_code"] ?? "")}`);
+  const interval = Number(started["interval"] ?? 5) * 1000;
+  while (true) {
+    await (input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(interval);
+    const token = await requestJson(fetchFn, `${baseUrl}/api/auth/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: started["device_code"],
+        client_id: input.clientId,
+      }),
+    });
+    if (token.response.ok) {
+      await input.store.write(tokenCredentials(baseUrl, input.clientId, token.body as Record<string, unknown>, now()));
+      out(`Authenticated with ${baseUrl}`);
+      return 0;
+    }
+    const error = (token.body as Record<string, unknown> | undefined)?.["error"];
+    if (error === "authorization_pending" || error === "slow_down") continue;
+    throw new Error(tokenError(token.body, token.response.status));
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,4 @@
+export * from "./runtime";
+export * from "./credentials";
+export * from "./device-auth";
+export * from "./api-command";

package/src/cli/runtime.ts

@@ -0,0 +1,51 @@
+export interface CliCommandResult {
+  exitCode: number;
+  output?: string;
+  error?: string;
+}
+
+export type CliCommandHandler = (args: string[]) => CliCommandResult | Promise<CliCommandResult>;
+
+export function printCliResult(result: CliCommandResult, output: Pick<Console, "log" | "error"> = console): number {
+  if (result.output) {
+    output.log(result.output);
+  }
+  if (result.error) {
+    output.error(result.error);
+  }
+  return result.exitCode;
+}
+
+export function readOption(args: readonly string[], names: readonly string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    for (const name of names) {
+      if (arg === name) return args[index + 1];
+      if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+    }
+  }
+  return undefined;
+}
+
+export function hasFlag(args: readonly string[], names: readonly string[]): boolean {
+  return args.some((arg) => names.includes(arg));
+}
+
+export async function dispatchCliCommand(input: {
+  args: string[];
+  commands: Record<string, CliCommandHandler>;
+  defaultCommand?: string;
+  help: string;
+}): Promise<CliCommandResult> {
+  const [rawCommand, ...rest] = input.args;
+  const command = rawCommand && !rawCommand.startsWith("-") ? rawCommand : input.defaultCommand;
+  if (!command || rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+    return { exitCode: rawCommand ? 0 : 1, output: input.help };
+  }
+  const handler = input.commands[command];
+  if (!handler) {
+    return { exitCode: 1, error: `Unknown command: ${command}`, output: input.help };
+  }
+  return await handler(rawCommand === command ? rest : input.args);
+}