fix: feedback

- Fix TS2379/TS2375/TS2322 errors from `exactOptionalPropertyTypes` by
  normalizing zod-parsed error bodies into `SerializedError` and by
  conditionally spreading optional options.
- Cast `retryPolicy` to `RetryPolicy` and step-attempt `context` to
  `StepAttemptContext | null` at the HTTP boundary.
- Work around TS2589 deep-instantiation in Hono's `JSONParsed<T>` by
  routing complex response bodies through a `jsonResponse` helper and
  splitting step-attempt routes across sub-apps.
- Re-export `RetryPolicy`, `SerializedError`, and `StepAttemptContext`
  from `openworkflow/internal` so the server package can reference them.
- Drop unused `BACKEND_ERROR_CODES` and `HttpValidationError` exports,
  and deduplicate the worker-lease schemas to satisfy knip.
- Reformat server sources with prettier.

Author: jamescmartinez

knip.json

@@ -19,7 +19,8 @@
     "**/openworkflow.config.*",
     "openworkflow/**/*.ts",
     "packages/dashboard/src/components/ui/*.tsx",
-    "packages/docs/style.css"
+    "packages/docs/style.css",
+    "packages/openworkflow/http.ts"
   ],
   "ignoreIssues": {
     "packages/dashboard/src/components/ui/*.tsx": ["exports"],

package-lock.json

@@ -5,7 +5,7 @@ import {
   getConfigFileName,
   getExampleWorkflowFileName,
   getRunFileName,
-  validateDashboardPort,
+  validatePort,
 } from "./commands.js";
 import fs from "node:fs";
 import os from "node:os";
@@ -164,27 +164,29 @@ describe("getDashboardSpawnOptions", () => {
   });
 });
 
-describe("validateDashboardPort", () => {
+describe("validatePort", () => {
   test("returns undefined when no custom port is provided", () => {
-    expect(validateDashboardPort()).toBeUndefined();
+    expect(validatePort(undefined, "dashboard")).toBeUndefined();
   });
 
   test("returns the port when it is within range", () => {
-    expect(validateDashboardPort(3001)).toBe(3001);
+    expect(validatePort(3001, "dashboard")).toBe(3001);
   });
 
   test("throws for non-integer ports", () => {
-    expect(() => validateDashboardPort(Number.NaN)).toThrow(
+    expect(() => validatePort(Number.NaN, "dashboard")).toThrow(
       "Invalid dashboard port.",
     );
-    expect(() => validateDashboardPort(3000.5)).toThrow(
+    expect(() => validatePort(3000.5, "dashboard")).toThrow(
       "Invalid dashboard port.",
     );
   });
 
   test("throws for out-of-range ports", () => {
-    expect(() => validateDashboardPort(0)).toThrow("Invalid dashboard port.");
-    expect(() => validateDashboardPort(65_536)).toThrow(
+    expect(() => validatePort(0, "dashboard")).toThrow(
+      "Invalid dashboard port.",
+    );
+    expect(() => validatePort(65_536, "dashboard")).toThrow(
       "Invalid dashboard port.",
     );
   });

packages/cli/commands.test.ts

@@ -35,11 +35,7 @@ interface CommandOptions {
   config?: string;
 }
 
-interface DashboardOptions extends CommandOptions {
-  port?: number;
-}
-
-interface ServerStartOptions extends CommandOptions {
+interface PortedOptions extends CommandOptions {
   port?: number;
 }
 
@@ -362,19 +358,23 @@ export function getDashboardSpawnOptions(port?: number): {
 }
 
 /**
- * Validate dashboard port option.
- * @param port - Optional dashboard port.
- * @returns Validated dashboard port.
- * @throws {CLIError} If the provided port is not an integer in the 1-65535 range.
+ * Validate a port option.
+ * @param port - Optional port number.
+ * @param label - Label used in the error message (e.g. "dashboard", "server").
+ * @returns Validated port, or undefined if not provided.
+ * @throws {CLIError} If the port is not an integer in the 1-65535 range.
  */
-export function validateDashboardPort(port?: number): number | undefined {
+export function validatePort(
+  port: number | undefined,
+  label: string,
+): number | undefined {
   if (port === undefined) {
     return undefined;
   }
 
   if (!Number.isInteger(port) || port < 1 || port > 65_535) {
     throw new CLIError(
-      "Invalid dashboard port.",
+      `Invalid ${label} port.`,
       "Use an integer between 1 and 65535, for example `--port 3001`.",
     );
   }
@@ -387,9 +387,9 @@ export function validateDashboardPort(port?: number): number | undefined {
  * @param options - Dashboard command options.
  * @returns Resolves when the dashboard process exits.
  */
-export async function dashboard(options: DashboardOptions = {}): Promise<void> {
+export async function dashboard(options: PortedOptions = {}): Promise<void> {
   const configPath = options.config;
-  const port = validateDashboardPort(options.port);
+  const port = validatePort(options.port, "dashboard");
   consola.start("Starting dashboard...");
 
   const { configFile } = await loadConfigWithEnv(configPath);
@@ -451,21 +451,15 @@ export async function dashboard(options: DashboardOptions = {}): Promise<void> {
   });
 }
 
-export type { ServerStartOptions };
-
 /**
  * openworkflow server start
- * Start the OpenWorkflow HTTP API server.
  * @param options - Server start options.
  */
-export async function serverStart(
-  options: ServerStartOptions = {},
-): Promise<void> {
-  const { config: configPath, port: rawPort } = options;
-  const port = rawPort ?? 3000;
+export async function serverStart(options: PortedOptions = {}): Promise<void> {
+  const port = validatePort(options.port, "server") ?? 3000;
   consola.start("Starting server...");
 
-  const { configFile, config } = await loadConfigWithEnv(configPath);
+  const { configFile, config } = await loadConfigWithEnv(options.config);
   if (!configFile) {
     throw new CLIError(
       "No config file found.",
@@ -474,32 +468,32 @@ export async function serverStart(
   }
   consola.info(`Using config: ${configFile}`);
 
-  let createServer: typeof import("@openworkflow/server").createServer;
-  let serve: typeof import("@openworkflow/server").serve;
-  try {
-    ({ createServer, serve } = await import("@openworkflow/server"));
-  } catch {
-    throw new CLIError(
-      "@openworkflow/server is not installed.",
-      'Run `npm install @openworkflow/server` to enable the "server start" command.',
-    );
-  }
-
   const backend = config.backend;
-  const server = createServer(backend, {
-    logRequests: true,
-    onError: (error, ctx) => {
-      consola.error(`[${ctx.method} ${ctx.path}]`, error);
-    },
-  });
-  const handle = serve(server, { port });
-  consola.success(`Server listening on http://localhost:${String(port)}`);
-
-  registerGracefulShutdown({
+  let handle: { close(): Promise<void> } | null = null;
+  const gracefulShutdown = registerGracefulShutdown({
     noun: "server",
-    stopApp: () => handle.close(),
+    stopApp: async () => {
+      await handle?.close();
+    },
     backend,
   });
+
+  try {
+    // still dynamic to defer hono's ~150KB until `server start` is invoked
+    const { createServer, serve } = await import("@openworkflow/server");
+
+    const server = createServer(backend, {
+      logRequests: true,
+      onError: (error, ctx) => {
+        consola.error(`[${ctx.method} ${ctx.path}]`, error);
+      },
+    });
+    handle = serve(server, { port });
+    consola.success(`Server listening on http://localhost:${String(port)}`);
+  } catch (error) {
+    await gracefulShutdown();
+    throw error;
+  }
 }
 
 // -----------------------------------------------------------------------------
@@ -514,11 +508,10 @@ interface ShutdownOptions {
 }
 
 /**
- * Wire SIGINT/SIGTERM to a graceful shutdown. The HTTP handle / worker is
- * stopped first (so no new work starts), then the backend is stopped even if
- * the app-level close fails.
+ * Wire SIGINT/SIGTERM to a graceful shutdown. `stopApp` runs first; the
+ * backend is stopped even if `stopApp` throws.
  * @param options - What to stop on shutdown
- * @returns The shutdown function (also registered against SIGINT/SIGTERM)
+ * @returns The shutdown function
  */
 function registerGracefulShutdown(
   options: ShutdownOptions,

packages/cli/commands.ts

@@ -28,14 +28,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
+    "@openworkflow/server": "*",
     "commander": "^14.0.3",
     "consola": "^3.4.2",
     "dotenv": "^17.4.2",
     "jiti": "^2.6.1",
     "nypm": "^0.6.5"
   },
   "devDependencies": {
-    "@openworkflow/server": "*",
     "openworkflow": "*",
     "vitest": "^4.0.18"
   },

packages/cli/package.json

@@ -7,32 +7,17 @@ export interface SerializedError {
   [key: string]: JsonValue;
 }
 
-/**
- * Runtime tuple of every known Backend error code. Single source of truth —
- * the `BackendErrorCode` type is derived from this list so adding a code is
- * one edit.
- */
-export const BACKEND_ERROR_CODES = ["NOT_FOUND", "CONFLICT"] as const;
+export type BackendErrorCode = "NOT_FOUND" | "CONFLICT";
 
 /**
- * Error codes for typed Backend errors that can be mapped to HTTP status codes.
- */
-export type BackendErrorCode = (typeof BACKEND_ERROR_CODES)[number];
-
-/**
- * Type guard narrowing an arbitrary string to a known {@link BackendErrorCode}.
- * @param code - Candidate code string (e.g. from a server response)
- * @returns Whether `code` is a recognized backend error code
+ * Type guard for {@link BackendErrorCode}.
+ * @param code - The string to test
+ * @returns True if `code` is a known backend error code
  */
 export function isBackendErrorCode(code: string): code is BackendErrorCode {
-  return (BACKEND_ERROR_CODES as readonly string[]).includes(code);
+  return code === "NOT_FOUND" || code === "CONFLICT";
 }
 
-/**
- * A typed error thrown by Backend implementations to signal well-known failure
- * modes. Consumers (e.g. the HTTP server) can inspect `code` to choose the
- * appropriate response status.
- */
 // eslint-disable-next-line functional/no-classes, functional/no-class-inheritance
 export class BackendError extends Error {
   readonly code: BackendErrorCode;

packages/openworkflow/core/error.ts

@@ -4,10 +4,7 @@ import type { JsonValue } from "./json.js";
 import type { Result } from "./result.js";
 import { err, ok } from "./result.js";
 
-/**
- * Runtime tuple of every known step kind. Single source of truth — the
- * `StepKind` type is derived from this list so adding a kind is one edit.
- */
+/** Runtime tuple of step kinds; {@link StepKind} is derived from it. */
 export const STEP_KINDS = [
   "function",
   "sleep",

packages/openworkflow/core/step-attempt.ts

@@ -0,0 +1 @@
+export { BackendHttp, type BackendHttpOptions } from "./http/backend.js";