@hunsu/config 0.1.0

package/dist/index.js

@@ -0,0 +1,408 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_LOCAL_HUB_API_URL = "http://127.0.0.1:8787";
+const DEFAULT_STUDIO_WEB_URL = "https://hunsu.app/studio";
+export const HUNSU_PORT_SPECS = {
+    localApi: {
+        name: "localApi",
+        defaultHost: DEFAULT_HOST,
+        hostEnv: ["HUNSU_LOCAL_HOST", "HOST"],
+        defaultPort: 19687,
+        portEnv: ["HUNSU_LOCAL_PORT", "PORT"],
+        reserved: false,
+        allowPortZero: false
+    },
+    studioWeb: {
+        name: "studioWeb",
+        defaultHost: DEFAULT_HOST,
+        hostEnv: ["HUNSU_WEB_HOST"],
+        defaultPort: 19688,
+        portEnv: ["HUNSU_WEB_PORT"],
+        reserved: false,
+        allowPortZero: false
+    },
+    agentPreview: {
+        name: "agentPreview",
+        defaultHost: DEFAULT_HOST,
+        hostEnv: ["HUNSU_AGENT_PREVIEW_HOST"],
+        defaultPort: 19673,
+        portEnv: ["HUNSU_AGENT_PREVIEW_PORT"],
+        reserved: true,
+        allowPortZero: false
+    }
+};
+export const HUNSU_ACTIVE_SERVICE_PORTS = ["localApi", "studioWeb"];
+export const HUNSU_STUDIO_WEB_ACTIVE_PORTS = ["localApi", "studioWeb"];
+const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"];
+const CODEX_APPROVAL_POLICIES = ["never", "on-request", "on-failure", "untrusted"];
+const CODEX_APPROVALS_REVIEWERS = ["user", "auto_review"];
+const LOCAL_TEST_RUNNERS = ["deterministic"];
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function mapConfigResult(result, transform) {
+    return result.ok ? ok(transform(result.value)) : result;
+}
+export function flatMapConfigResult(result, transform) {
+    return result.ok ? transform(result.value) : result;
+}
+export function unwrapConfigResult(result) {
+    if (result.ok) {
+        return result.value;
+    }
+    throw new Error(result.error.message);
+}
+export function resolveHunsuPorts(env, options = {}) {
+    const localApi = resolveEndpoint(HUNSU_PORT_SPECS.localApi, env, options.overrides?.localApi);
+    if (!localApi.ok) {
+        return localApi;
+    }
+    const studioWeb = resolveEndpoint(HUNSU_PORT_SPECS.studioWeb, env, options.overrides?.studioWeb);
+    if (!studioWeb.ok) {
+        return studioWeb;
+    }
+    const agentPreview = resolveEndpoint(HUNSU_PORT_SPECS.agentPreview, env, options.overrides?.agentPreview);
+    if (!agentPreview.ok) {
+        return agentPreview;
+    }
+    return ok({
+        localApi: localApi.value,
+        studioWeb: studioWeb.value,
+        agentPreview: agentPreview.value
+    });
+}
+export function resolveValidatedHunsuPorts(env, options) {
+    return flatMapConfigResult(resolveHunsuPorts(env, options), config => validateNoPortConflicts(config, options.activePortNames));
+}
+export function resolveStudioWebServerConfig(env) {
+    return flatMapConfigResult(resolveValidatedHunsuPorts(env, { activePortNames: HUNSU_STUDIO_WEB_ACTIVE_PORTS }), ports => flatMapConfigResult(readConfigBoolean(env, "HUNSU_WEB_STRICT_PORT", true), strictPort => flatMapConfigResult(readOptionalUrl(env, "VITE_HUNSU_LOCAL_URL"), browserLocalUrl => flatMapConfigResult(readFirstOptionalUrl(env, ["VITE_HUNSU_HUB_API_URL", "HUNSU_HUB_PUBLIC_API_URL"], defaultBrowserHubApiUrl(env)), browserHubApiUrl => mapConfigResult(readFirstUrl(env, ["HUNSU_LOCAL_API_PROXY_TARGET"], browserLocalUrl ?? endpointUrl(ports.localApi)), apiProxyTarget => ({
+        web: ports.studioWeb,
+        localApi: ports.localApi,
+        strictPort,
+        apiProxyTarget,
+        browserLocalUrl,
+        browserHubApiUrl
+    }))))));
+}
+export function resolveStudioLauncherConfig(env) {
+    return mapConfigResult(readConfigUrl(env, "HUNSU_WEB_URL", DEFAULT_STUDIO_WEB_URL), webUrl => ({ webUrl }));
+}
+export function currentProcessEnv() {
+    return process.env;
+}
+function defaultBrowserHubApiUrl(env) {
+    const target = firstNonEmpty(env, ["HUNSU_DEPLOY_TARGET"])?.value;
+    if (target === undefined || target === "local") {
+        return DEFAULT_LOCAL_HUB_API_URL;
+    }
+    return undefined;
+}
+export function resolveLocalApiServerConfig(env) {
+    return mapConfigResult(resolveValidatedHunsuPorts(env, { activePortNames: ["localApi"] }), ports => ({ localApi: ports.localApi }));
+}
+export function resolveLocalRuntimeConfig(env, options = {}) {
+    const processEnv = filterEnv(options.processEnv ?? env);
+    return flatMapConfigResult(resolveLocalApiServerConfig(env), ({ localApi }) => flatMapConfigResult(resolveRequiredConfiguredPath(options.roadmapRegistryPath, env, "HUNSU_ROADMAP_REGISTRY_PATH", join(options.homeDir ?? homedir(), ".config", "hunsu", "roadmaps.json"), options.cwd), roadmapRegistryPath => flatMapConfigResult(resolveConfiguredPath(options.routeWorktreeRoot, env, "HUNSU_ROUTE_WORKTREE_ROOT", undefined, options.cwd), routeWorktreeRoot => flatMapConfigResult(resolveConfiguredPath(options.actionWorktreeRoot, env, "HUNSU_ACTION_WORKTREE_ROOT", undefined, options.cwd), actionWorktreeRoot => flatMapConfigResult(readOptionalEnum(env, "HUNSU_LOCAL_TEST_RUNNER", LOCAL_TEST_RUNNERS), testRunner => flatMapConfigResult(resolveCodexAppServerConfig(env, options.codexAppServer), codexAppServer => mapConfigResult(resolveCodexThreadOptions(env, options.codexThreadOptions), codexThreadOptions => ({
+        localApi,
+        processEnv,
+        roadmapRegistryPath,
+        routeWorktreeRoot,
+        actionWorktreeRoot,
+        testRunner,
+        codexAppServer,
+        codexThreadOptions
+    }))))))));
+}
+export function validateNoPortConflicts(config, activePortNames) {
+    for (let i = 0; i < activePortNames.length; i += 1) {
+        const left = config[activePortNames[i]];
+        if (left.port === 0) {
+            continue;
+        }
+        for (let j = i + 1; j < activePortNames.length; j += 1) {
+            const right = config[activePortNames[j]];
+            if (right.port !== left.port || right.port === 0) {
+                continue;
+            }
+            if (hostsMayConflict(left.host, right.host)) {
+                return err({
+                    code: "port_conflict",
+                    message: `Hunsu port conflict: ${left.name} and ${right.name} both use ${left.host}:${left.port}.`,
+                    port: left.port
+                });
+            }
+        }
+    }
+    return ok(config);
+}
+export function endpointUrl(endpoint) {
+    return `http://${endpoint.host}:${endpoint.port}`;
+}
+export function readConfigBoolean(env, envName, fallback) {
+    const raw = env[envName];
+    if (raw === undefined || raw.trim() === "") {
+        return ok(fallback);
+    }
+    return parseConfigBoolean(envName, raw);
+}
+export function readConfigEnum(env, envName, allowed, fallback) {
+    const raw = env[envName];
+    if (raw === undefined || raw.trim() === "") {
+        return ok(fallback);
+    }
+    return parseConfigEnum(envName, raw, allowed);
+}
+export function readConfigOptionalString(env, envName) {
+    const raw = env[envName];
+    return ok(raw === undefined || raw.trim() === "" ? undefined : raw);
+}
+export function readConfigUrl(env, envName, fallback) {
+    const raw = env[envName];
+    return validateUrl(raw === undefined || raw.trim() === "" ? fallback : raw, envName);
+}
+export function readConfigJsonStringArray(env, envName, fallback = []) {
+    const raw = env[envName];
+    if (raw === undefined || raw.trim() === "") {
+        return ok([...fallback]);
+    }
+    return parseJsonStringArray(envName, raw);
+}
+export function readConfigPath(env, envName, fallback, cwd) {
+    const raw = env[envName];
+    return validatePath(raw === undefined || raw.trim() === "" ? fallback : raw, envName, cwd);
+}
+export function resolveCodexAppServerConfig(env, overrides = {}) {
+    const command = overrides.command ?? firstNonEmpty(env, ["HUNSU_CODEX_APP_SERVER_COMMAND"])?.value ?? "codex";
+    if (command.trim() === "") {
+        return err({
+            code: "missing_required_env",
+            env: "HUNSU_CODEX_APP_SERVER_COMMAND",
+            message: "Invalid HUNSU_CODEX_APP_SERVER_COMMAND: expected a non-empty command."
+        });
+    }
+    return mapConfigResult(resolveCodexAppServerArgs(env, overrides.args), args => ({
+        command,
+        args,
+        environment: filterEnv(overrides.environment ?? env)
+    }));
+}
+export function resolveCodexThreadOptions(env, overrides = {}) {
+    return flatMapConfigResult(readOptionalEnum(env, "HUNSU_CODEX_SANDBOX_MODE", CODEX_SANDBOX_MODES), sandboxMode => flatMapConfigResult(readOptionalEnum(env, "HUNSU_CODEX_APPROVAL_POLICY", CODEX_APPROVAL_POLICIES), approvalPolicy => flatMapConfigResult(readOptionalEnum(env, "HUNSU_CODEX_APPROVALS_REVIEWER", CODEX_APPROVALS_REVIEWERS), approvalsReviewer => flatMapConfigResult(readOptionalBoolean(env, "HUNSU_CODEX_NETWORK_ACCESS"), networkAccessEnabled => mapConfigResult(readCommaSeparatedList(env, "HUNSU_CODEX_ADDITIONAL_DIRECTORIES"), additionalDirectories => ({
+        ...(sandboxMode === undefined ? {} : { sandboxMode }),
+        ...(approvalPolicy === undefined ? {} : { approvalPolicy }),
+        ...(approvalsReviewer === undefined ? {} : { approvalsReviewer }),
+        ...(networkAccessEnabled === undefined ? {} : { networkAccessEnabled }),
+        ...(additionalDirectories.length === 0 ? {} : { additionalDirectories }),
+        ...overrides
+    }))))));
+}
+function resolveEndpoint(spec, env, override) {
+    const hostValue = override?.host !== undefined
+        ? { value: override.host, source: "override", env: undefined }
+        : firstNonEmpty(env, spec.hostEnv) ?? { value: spec.defaultHost, source: "default", env: undefined };
+    const portValue = override?.port !== undefined
+        ? mapConfigResult(validatePort(override.port, spec, undefined), port => ({ value: port, source: "override", env: undefined }))
+        : readPort(env, spec);
+    return mapConfigResult(portValue, port => ({
+        name: spec.name,
+        host: hostValue.value,
+        hostSource: hostValue.source,
+        hostEnv: hostValue.env,
+        port: port.value,
+        portSource: port.source,
+        portEnv: port.env,
+        reserved: spec.reserved
+    }));
+}
+function readPort(env, spec) {
+    const envValue = firstNonEmpty(env, spec.portEnv);
+    if (!envValue) {
+        return ok({ value: spec.defaultPort, source: "default" });
+    }
+    return mapConfigResult(validatePort(envValue.value, spec, envValue.env), port => ({
+        value: port,
+        source: "env",
+        env: envValue.env
+    }));
+}
+function validatePort(value, spec, envName) {
+    const port = typeof value === "number" ? value : Number(value);
+    const min = spec.allowPortZero ? 0 : 1;
+    if (!Number.isInteger(port) || port < min || port > 65535) {
+        return err({
+            code: "invalid_port",
+            env: envName,
+            portName: spec.name,
+            message: envName
+                ? `Invalid ${envName}: ${value}. Expected an integer port from ${min} to 65535.`
+                : `Invalid ${spec.name} port: ${value}. Expected an integer port from ${min} to 65535.`
+        });
+    }
+    return ok(port);
+}
+function parseConfigBoolean(envName, raw) {
+    if (/^(1|true|yes|on)$/i.test(raw)) {
+        return ok(true);
+    }
+    if (/^(0|false|no|off)$/i.test(raw)) {
+        return ok(false);
+    }
+    return err({
+        code: "invalid_boolean",
+        env: envName,
+        message: `Invalid ${envName}: ${raw}. Expected true, false, 1, 0, yes, no, on, or off.`
+    });
+}
+function readOptionalBoolean(env, envName) {
+    const raw = env[envName];
+    return raw === undefined || raw.trim() === "" ? ok(undefined) : parseConfigBoolean(envName, raw);
+}
+function parseConfigEnum(envName, value, allowed) {
+    if (allowed.includes(value)) {
+        return ok(value);
+    }
+    return err({
+        code: "invalid_enum",
+        env: envName,
+        value,
+        allowed,
+        message: `Invalid ${envName}: ${value}. Expected one of: ${allowed.join(", ")}.`
+    });
+}
+function readOptionalEnum(env, envName, allowed) {
+    const raw = env[envName];
+    return raw === undefined || raw.trim() === "" ? ok(undefined) : parseConfigEnum(envName, raw, allowed);
+}
+function readOptionalUrl(env, envName) {
+    const raw = env[envName];
+    return raw === undefined || raw.trim() === "" ? ok(undefined) : validateUrl(raw, envName);
+}
+function readFirstUrl(env, envNames, fallback) {
+    const raw = firstNonEmpty(env, envNames);
+    return validateUrl(raw?.value ?? fallback, raw?.env ?? envNames[0]);
+}
+function readFirstOptionalUrl(env, envNames, fallback) {
+    const raw = firstNonEmpty(env, envNames);
+    const value = raw?.value ?? fallback;
+    return value === undefined ? ok(undefined) : validateUrl(value, raw?.env ?? envNames[0]);
+}
+function validateUrl(value, envName) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            throw new Error("Unsupported protocol");
+        }
+        return ok(url.toString().replace(/\/$/, ""));
+    }
+    catch (_error) {
+        return err({
+            code: "invalid_url",
+            env: envName,
+            value,
+            message: envName
+                ? `Invalid ${envName}: ${value}. Expected an http or https URL.`
+                : `Invalid URL: ${value}. Expected an http or https URL.`
+        });
+    }
+}
+function resolveConfiguredPath(override, env, envName, fallback, cwd) {
+    if (override !== undefined) {
+        return validatePath(override, undefined, cwd);
+    }
+    const raw = env[envName];
+    if (raw !== undefined && raw.trim() !== "") {
+        return validatePath(raw, envName, cwd);
+    }
+    return fallback === undefined ? ok(undefined) : validatePath(fallback, undefined, cwd);
+}
+function resolveRequiredConfiguredPath(override, env, envName, fallback, cwd) {
+    return mapConfigResult(resolveConfiguredPath(override, env, envName, fallback, cwd), path => path ?? resolve(cwd ?? ".", fallback));
+}
+function validatePath(value, envName, cwd = ".") {
+    if (value.trim() === "" || value.includes("\0")) {
+        return err({
+            code: "invalid_path",
+            env: envName,
+            path: value,
+            message: envName
+                ? `Invalid ${envName}: expected a non-empty filesystem path.`
+                : "Invalid filesystem path: expected a non-empty path."
+        });
+    }
+    return ok(resolve(cwd, value));
+}
+function resolveCodexAppServerArgs(env, override) {
+    if (override !== undefined) {
+        return ok([...override]);
+    }
+    const raw = env.HUNSU_CODEX_APP_SERVER_ARGS;
+    if (raw === undefined || raw.trim() === "") {
+        return ok(["app-server", "--stdio"]);
+    }
+    if (raw.trim().startsWith("[")) {
+        return parseJsonStringArray("HUNSU_CODEX_APP_SERVER_ARGS", raw);
+    }
+    return ok(raw.split(/\s+/).filter(Boolean));
+}
+function parseJsonStringArray(envName, raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) && parsed.every(item => typeof item === "string")) {
+            return ok(parsed);
+        }
+    }
+    catch (_error) {
+        return err({
+            code: "invalid_json",
+            env: envName,
+            value: raw,
+            message: `Invalid ${envName}: expected a JSON string array.`
+        });
+    }
+    return err({
+        code: "invalid_json",
+        env: envName,
+        value: raw,
+        message: `Invalid ${envName}: expected a JSON string array.`
+    });
+}
+function readCommaSeparatedList(env, envName) {
+    const raw = env[envName];
+    return ok(raw === undefined || raw.trim() === ""
+        ? []
+        : raw.split(",").map(value => value.trim()).filter(Boolean));
+}
+function filterEnv(env) {
+    const next = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined) {
+            next[key] = value;
+        }
+    }
+    return next;
+}
+function firstNonEmpty(env, names) {
+    for (const name of names) {
+        const value = env[name];
+        if (value !== undefined && value.trim() !== "") {
+            return { value, source: "env", env: name };
+        }
+    }
+    return undefined;
+}
+function hostsMayConflict(left, right) {
+    const normalizedLeft = normalizeHost(left);
+    const normalizedRight = normalizeHost(right);
+    return normalizedLeft === normalizedRight || isWildcardHost(normalizedLeft) || isWildcardHost(normalizedRight);
+}
+function normalizeHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return normalized === "localhost" ? DEFAULT_HOST : normalized;
+}
+function isWildcardHost(host) {
+    return host === "0.0.0.0" || host === "::" || host === "[::]";
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@hunsu/config",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Hunsu app-boundary configuration helpers.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cloudflare": {
+      "development": "./src/cloudflare.ts",
+      "types": "./src/cloudflare.ts",
+      "import": "./dist/cloudflare.js",
+      "default": "./dist/cloudflare.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/cloudflare.ts

@@ -0,0 +1,233 @@
+export type ConfigResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: CloudflareConfigError };
+
+export type CloudflareConfigError = {
+  code: "invalid_enum" | "invalid_url" | "missing_required_env";
+  message: string;
+  env?: string;
+  value?: string;
+  allowed?: readonly string[];
+};
+
+export type HunsuDeployTarget = "local" | "dev" | "production";
+
+export type HubCloudflareConfig = {
+  target: HunsuDeployTarget;
+  workerName: string;
+  workerMain: string;
+  compatibilityDate: string;
+  compatibilityFlags: string[];
+  originName: string;
+  publicHubApiUrl: string;
+  d1DatabaseName: string;
+  d1DatabaseId: string;
+  r2BucketName: string;
+  publishQueueName?: string;
+};
+
+export type HubApiWorkerRuntimeConfig = {
+  originName: string;
+  publicHubApiUrl?: string;
+  adminToken?: string;
+};
+
+export type HubApiWorkerRuntimeEnv = {
+  HUNSU_HUB_ORIGIN_NAME?: string;
+  HUNSU_HUB_PUBLIC_API_URL?: string;
+  HUNSU_HUB_ADMIN_TOKEN?: string;
+};
+
+export type Env = Record<string, string | undefined>;
+
+export const HUNSU_DEPLOY_TARGETS = ["local", "dev", "production"] as const;
+export const HUB_WRANGLER_GENERATED_CONFIG_PATH = ".wrangler/generated.toml";
+export const HUB_WORKER_MAIN = "../src/index.ts";
+export const HUB_WORKER_COMPATIBILITY_DATE = "2026-06-25";
+export const HUB_WORKER_COMPATIBILITY_FLAGS = ["nodejs_compat"] as const;
+
+const LOCAL_HUB_DEFAULTS = {
+  HUNSU_HUB_WORKER_NAME: "hunsu-hub-api-local",
+  HUNSU_HUB_ORIGIN_NAME: "hunsu-local",
+  HUNSU_HUB_PUBLIC_API_URL: "http://127.0.0.1:8787",
+  HUNSU_HUB_D1_DATABASE_NAME: "hunsu_hub_local",
+  HUNSU_HUB_D1_DATABASE_ID: "hunsu-hub-local",
+  HUNSU_HUB_R2_BUCKET_NAME: "hunsu-hub-packages-local"
+} as const;
+
+export function resolveHubCloudflareConfig(env: Env): ConfigResult<HubCloudflareConfig> {
+  return flatMapConfigResult(readDeployTarget(env), target =>
+    flatMapConfigResult(readRequiredString(env, "HUNSU_HUB_WORKER_NAME", target), workerName =>
+      flatMapConfigResult(readRequiredString(env, "HUNSU_HUB_ORIGIN_NAME", target), originName =>
+        flatMapConfigResult(readRequiredUrl(env, "HUNSU_HUB_PUBLIC_API_URL", target), publicHubApiUrl =>
+          flatMapConfigResult(readRequiredString(env, "HUNSU_HUB_D1_DATABASE_NAME", target), d1DatabaseName =>
+            flatMapConfigResult(readRequiredString(env, "HUNSU_HUB_D1_DATABASE_ID", target), d1DatabaseId =>
+              mapConfigResult(readRequiredString(env, "HUNSU_HUB_R2_BUCKET_NAME", target), r2BucketName => ({
+                target,
+                workerName,
+                workerMain: HUB_WORKER_MAIN,
+                compatibilityDate: HUB_WORKER_COMPATIBILITY_DATE,
+                compatibilityFlags: [...HUB_WORKER_COMPATIBILITY_FLAGS],
+                originName,
+                publicHubApiUrl,
+                d1DatabaseName,
+                d1DatabaseId,
+                r2BucketName,
+                publishQueueName: readOptionalString(env, "HUNSU_HUB_PUBLISH_QUEUE_NAME")
+              }))
+            )
+          )
+        )
+      )
+    )
+  );
+}
+
+export function resolveHubApiWorkerRuntimeConfig(env: HubApiWorkerRuntimeEnv): ConfigResult<HubApiWorkerRuntimeConfig> {
+  return flatMapConfigResult(readRequiredRuntimeString(env, "HUNSU_HUB_ORIGIN_NAME"), originName =>
+    mapConfigResult(readOptionalRuntimeUrl(env, "HUNSU_HUB_PUBLIC_API_URL"), publicHubApiUrl => ({
+      originName,
+      publicHubApiUrl,
+      adminToken: readOptionalRuntimeString(env, "HUNSU_HUB_ADMIN_TOKEN")
+    }))
+  );
+}
+
+export function renderHubWranglerToml(config: HubCloudflareConfig): string {
+  const lines = [
+    "# Generated by @hunsu/config/cloudflare. Do not edit by hand.",
+    `name = ${tomlString(config.workerName)}`,
+    `main = ${tomlString(config.workerMain)}`,
+    `compatibility_date = ${tomlString(config.compatibilityDate)}`,
+    `compatibility_flags = [${config.compatibilityFlags.map(tomlString).join(", ")}]`,
+    "",
+    "[vars]",
+    `HUNSU_HUB_ORIGIN_NAME = ${tomlString(config.originName)}`,
+    `HUNSU_HUB_PUBLIC_API_URL = ${tomlString(config.publicHubApiUrl)}`,
+    "",
+    "[[d1_databases]]",
+    `binding = ${tomlString("HUB_DB")}`,
+    `database_name = ${tomlString(config.d1DatabaseName)}`,
+    `database_id = ${tomlString(config.d1DatabaseId)}`,
+    `migrations_dir = ${tomlString("../migrations")}`,
+    "",
+    "[[r2_buckets]]",
+    `binding = ${tomlString("HUB_PACKAGES")}`,
+    `bucket_name = ${tomlString(config.r2BucketName)}`
+  ];
+
+  if (config.publishQueueName) {
+    lines.push(
+      "",
+      "[[queues.producers]]",
+      `binding = ${tomlString("HUB_PUBLISH_QUEUE")}`,
+      `queue = ${tomlString(config.publishQueueName)}`
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function ok<T>(value: T): ConfigResult<T> {
+  return { ok: true, value };
+}
+
+function err(error: CloudflareConfigError): ConfigResult<never> {
+  return { ok: false, error };
+}
+
+function mapConfigResult<T, U>(result: ConfigResult<T>, transform: (value: T) => U): ConfigResult<U> {
+  return result.ok ? ok(transform(result.value)) : result;
+}
+
+function flatMapConfigResult<T, U>(result: ConfigResult<T>, transform: (value: T) => ConfigResult<U>): ConfigResult<U> {
+  return result.ok ? transform(result.value) : result;
+}
+
+function readDeployTarget(env: Env): ConfigResult<HunsuDeployTarget> {
+  const raw = readOptionalString(env, "HUNSU_DEPLOY_TARGET") ?? "local";
+  if (isDeployTarget(raw)) {
+    return ok(raw);
+  }
+  return err({
+    code: "invalid_enum",
+    env: "HUNSU_DEPLOY_TARGET",
+    value: raw,
+    allowed: HUNSU_DEPLOY_TARGETS,
+    message: `Invalid HUNSU_DEPLOY_TARGET: ${raw}. Expected one of: ${HUNSU_DEPLOY_TARGETS.join(", ")}.`
+  });
+}
+
+function isDeployTarget(value: string): value is HunsuDeployTarget {
+  return (HUNSU_DEPLOY_TARGETS as readonly string[]).includes(value);
+}
+
+function readRequiredString(env: Env, envName: keyof typeof LOCAL_HUB_DEFAULTS, target: HunsuDeployTarget): ConfigResult<string> {
+  const raw = readOptionalString(env, envName) ?? (target === "local" ? LOCAL_HUB_DEFAULTS[envName] : undefined);
+  if (raw) {
+    return ok(raw);
+  }
+  return missing(envName);
+}
+
+function readRequiredUrl(env: Env, envName: "HUNSU_HUB_PUBLIC_API_URL", target: HunsuDeployTarget): ConfigResult<string> {
+  const raw = readOptionalString(env, envName) ?? (target === "local" ? LOCAL_HUB_DEFAULTS[envName] : undefined);
+  if (!raw) {
+    return missing(envName);
+  }
+  return validateUrl(raw, envName);
+}
+
+function readRequiredRuntimeString(env: HubApiWorkerRuntimeEnv, envName: "HUNSU_HUB_ORIGIN_NAME"): ConfigResult<string> {
+  const raw = readOptionalRuntimeString(env, envName);
+  if (raw) {
+    return ok(raw);
+  }
+  return missing(envName);
+}
+
+function readOptionalRuntimeUrl(env: HubApiWorkerRuntimeEnv, envName: "HUNSU_HUB_PUBLIC_API_URL"): ConfigResult<string | undefined> {
+  const raw = readOptionalRuntimeString(env, envName);
+  return raw === undefined ? ok(undefined) : validateUrl(raw, envName);
+}
+
+function readOptionalString(env: Env, envName: string): string | undefined {
+  const raw = env[envName];
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readOptionalRuntimeString(env: HubApiWorkerRuntimeEnv, envName: keyof HubApiWorkerRuntimeEnv): string | undefined {
+  const raw = env[envName];
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function validateUrl(value: string, envName: string): ConfigResult<string> {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error("Unsupported protocol");
+    }
+    return ok(url.toString().replace(/\/$/, ""));
+  } catch {
+    return err({
+      code: "invalid_url",
+      env: envName,
+      value,
+      message: `Invalid ${envName}: ${value}. Expected an http or https URL.`
+    });
+  }
+}
+
+function missing(envName: string): ConfigResult<never> {
+  return err({
+    code: "missing_required_env",
+    env: envName,
+    message: `Missing required ${envName}.`
+  });
+}
+
+function tomlString(value: string): string {
+  return JSON.stringify(value);
+}