run402 1.60.2 → 1.61.0

package/sdk/dist/namespaces/deploy.js

@@ -20,6 +20,7 @@
  */
 import { isCiSessionCredentials } from "../ci-credentials.js";
 import { assertCiDeployableSpec } from "./ci.js";
+import { ROUTE_HTTP_METHODS } from "./deploy.types.js";
 import { ApiError, LocalError, NetworkError, PaymentRequired, Run402DeployError, Unauthorized, } from "../errors.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const PLAN_BODY_LIMIT_BYTES = 5 * 1024 * 1024;
@@ -764,6 +765,47 @@ async function startInternal(client, spec, opts) {
         },
     };
 }
+const RELEASE_SPEC_FIELDS = new Set([
+    "project",
+    "base",
+    "database",
+    "secrets",
+    "functions",
+    "site",
+    "subdomains",
+    "routes",
+    "checks",
+]);
+const DEPLOYABLE_SPEC_FIELDS = [
+    "database",
+    "site",
+    "functions",
+    "secrets",
+    "subdomains",
+    "routes",
+    "checks",
+];
+const BASE_SPEC_FIELDS = new Set(["release", "release_id"]);
+const DATABASE_SPEC_FIELDS = new Set(["migrations", "expose", "zero_downtime"]);
+const MIGRATION_SPEC_FIELDS = new Set(["id", "checksum", "sql", "sql_ref", "transaction"]);
+const FUNCTIONS_SPEC_FIELDS = new Set(["replace", "patch"]);
+const FUNCTIONS_PATCH_FIELDS = new Set(["set", "delete"]);
+const FUNCTION_SPEC_FIELDS = new Set([
+    "runtime",
+    "source",
+    "files",
+    "entrypoint",
+    "config",
+    "schedule",
+]);
+const FUNCTION_CONFIG_FIELDS = new Set(["timeoutSeconds", "memoryMb"]);
+const SITE_SPEC_FIELDS = new Set(["replace", "patch"]);
+const SITE_PATCH_FIELDS = new Set(["put", "delete"]);
+const SUBDOMAINS_SPEC_FIELDS = new Set(["set", "add", "remove"]);
+const ROUTES_SPEC_FIELDS = new Set(["replace"]);
+const ROUTE_ENTRY_FIELDS = new Set(["pattern", "methods", "target"]);
+const ROUTE_TARGET_FIELDS = new Set(["type", "name"]);
+const ROUTE_METHOD_SET = new Set(ROUTE_HTTP_METHODS);
 function validateSpec(spec) {
     if (!spec || typeof spec !== "object") {
         throw new Run402DeployError("ReleaseSpec must be an object", {
@@ -775,6 +817,11 @@ function validateSpec(spec) {
             context: "validating spec",
         });
     }
+    const raw = spec;
+    validateKnownFields(raw, "spec", RELEASE_SPEC_FIELDS, {
+        project_id: "Use `project` in ReleaseSpec, or call `loadDeployManifest()` / `normalizeDeployManifest()` for MCP/CLI-style manifests.",
+        subdomain: "Use `subdomains: { set: [name] }`.",
+    });
     if (!spec.project || typeof spec.project !== "string") {
         throw new Run402DeployError("ReleaseSpec.project is required", {
             code: "INVALID_SPEC",
@@ -785,7 +832,17 @@ function validateSpec(spec) {
             context: "validating spec",
         });
     }
-    if (spec.subdomains?.set && spec.subdomains.set.length > 1) {
+    validateBaseSpec(raw.base);
+    validateDatabaseSpec(raw.database);
+    validateFunctionsSpec(raw.functions);
+    validateSiteSpec(raw.site);
+    validateSubdomainsSpec(raw.subdomains);
+    validateRoutesSpec(raw.routes);
+    validateChecksSpec(raw.checks);
+    validateSecretsSpec(raw.secrets);
+    const subdomains = raw.subdomains;
+    const set = subdomains?.set;
+    if (set && set.length > 1) {
         throw new Run402DeployError("subdomains.set accepts at most one subdomain per project; multi-subdomain support is not yet available", {
             code: "SUBDOMAIN_MULTI_NOT_SUPPORTED",
             phase: "validate",
@@ -795,7 +852,297 @@ function validateSpec(spec) {
             context: "validating spec",
         });
     }
-    validateSecretsSpec(spec.secrets);
+    if (!hasDeployableContent(raw)) {
+        throw new Run402DeployError(`ReleaseSpec contains no deployable sections. Expected at least one non-empty section: ${DEPLOYABLE_SPEC_FIELDS.join(", ")}`, {
+            code: "MANIFEST_EMPTY",
+            phase: "validate",
+            resource: "spec",
+            retryable: false,
+            fix: { action: "set_field", path: "site.replace" },
+            body: { deployable_fields: DEPLOYABLE_SPEC_FIELDS },
+            context: "validating spec",
+        });
+    }
+}
+function validateBaseSpec(base) {
+    if (base === undefined)
+        return;
+    const obj = requireObject(base, "base");
+    validateKnownFields(obj, "base", BASE_SPEC_FIELDS);
+    if (hasOwn(obj, "release") && hasOwn(obj, "release_id")) {
+        throw invalidSpec("ReleaseSpec.base must use either release or release_id, not both", "base");
+    }
+}
+function validateDatabaseSpec(database) {
+    if (database === undefined)
+        return;
+    const obj = requireObject(database, "database");
+    validateKnownFields(obj, "database", DATABASE_SPEC_FIELDS);
+    if (obj.migrations !== undefined) {
+        if (!Array.isArray(obj.migrations)) {
+            throw invalidSpec("ReleaseSpec.database.migrations must be an array", "database.migrations");
+        }
+        for (const [index, migration] of obj.migrations.entries()) {
+            const m = requireObject(migration, `database.migrations.${index}`);
+            validateKnownFields(m, `database.migrations.${index}`, MIGRATION_SPEC_FIELDS);
+        }
+    }
+    if (obj.expose !== undefined) {
+        requireObject(obj.expose, "database.expose");
+    }
+}
+function validateFunctionsSpec(functions) {
+    if (functions === undefined)
+        return;
+    const obj = requireObject(functions, "functions");
+    validateKnownFields(obj, "functions", FUNCTIONS_SPEC_FIELDS);
+    if (obj.replace !== undefined) {
+        validateFunctionMap(obj.replace, "functions.replace");
+    }
+    if (obj.patch !== undefined) {
+        const patch = requireObject(obj.patch, "functions.patch");
+        validateKnownFields(patch, "functions.patch", FUNCTIONS_PATCH_FIELDS);
+        if (patch.set !== undefined)
+            validateFunctionMap(patch.set, "functions.patch.set");
+        if (patch.delete !== undefined)
+            validateStringArray(patch.delete, "functions.patch.delete");
+    }
+}
+function validateFunctionMap(value, resource) {
+    const map = requireObject(value, resource);
+    for (const [name, fn] of Object.entries(map)) {
+        const entry = requireObject(fn, `${resource}.${name}`);
+        validateKnownFields(entry, `${resource}.${name}`, FUNCTION_SPEC_FIELDS);
+        if (entry.config !== undefined) {
+            const config = requireObject(entry.config, `${resource}.${name}.config`);
+            validateKnownFields(config, `${resource}.${name}.config`, FUNCTION_CONFIG_FIELDS);
+        }
+        if (entry.files !== undefined) {
+            requireObject(entry.files, `${resource}.${name}.files`);
+        }
+    }
+}
+function validateSiteSpec(site) {
+    if (site === undefined)
+        return;
+    const obj = requireObject(site, "site");
+    validateKnownFields(obj, "site", SITE_SPEC_FIELDS, {
+        file: "Use `site.replace` or `site.patch.put` with a path-keyed file map.",
+        files: "Use `site.replace` or `site.patch.put` with a path-keyed file map.",
+    });
+    if (hasOwn(obj, "replace") && hasOwn(obj, "patch")) {
+        throw invalidSpec("ReleaseSpec.site must use either replace or patch, not both", "site");
+    }
+    if (obj.replace !== undefined) {
+        requireObject(obj.replace, "site.replace");
+    }
+    if (obj.patch !== undefined) {
+        const patch = requireObject(obj.patch, "site.patch");
+        validateKnownFields(patch, "site.patch", SITE_PATCH_FIELDS);
+        if (patch.put !== undefined)
+            requireObject(patch.put, "site.patch.put");
+        if (patch.delete !== undefined)
+            validateStringArray(patch.delete, "site.patch.delete");
+    }
+}
+function validateSubdomainsSpec(subdomains) {
+    if (subdomains === undefined)
+        return;
+    const obj = requireObject(subdomains, "subdomains");
+    validateKnownFields(obj, "subdomains", SUBDOMAINS_SPEC_FIELDS);
+    if (obj.set !== undefined)
+        validateStringArray(obj.set, "subdomains.set");
+    if (obj.add !== undefined)
+        validateStringArray(obj.add, "subdomains.add");
+    if (obj.remove !== undefined)
+        validateStringArray(obj.remove, "subdomains.remove");
+}
+function validateRoutesSpec(routes) {
+    if (routes === undefined)
+        return;
+    if (routes === null)
+        return;
+    const obj = requireObject(routes, "routes");
+    for (const key of Object.keys(obj)) {
+        if (key.startsWith("/")) {
+            throw invalidRouteSpec(`Unknown ReleaseSpec field: routes.${key}. ${routeShapeHints(obj)[key]}`, `routes.${key}`);
+        }
+    }
+    validateKnownFields(obj, "routes", ROUTES_SPEC_FIELDS, routeShapeHints(obj));
+    if (!hasOwn(obj, "replace")) {
+        throw invalidRouteSpec("ReleaseSpec.routes must be null or { replace: [{ pattern, target: { type: \"function\", name } }] }. Path-keyed route maps are not supported.", "routes");
+    }
+    if (!Array.isArray(obj.replace)) {
+        throw invalidRouteSpec("ReleaseSpec.routes.replace must be an array of route entries", "routes.replace");
+    }
+    for (const [index, route] of obj.replace.entries()) {
+        validateRouteEntry(route, `routes.replace.${index}`);
+    }
+}
+function routeShapeHints(obj) {
+    const hints = {};
+    for (const key of Object.keys(obj)) {
+        if (key.startsWith("/")) {
+            hints[key] = "Use `routes.replace[]` entries like `{ pattern, target: { type: \"function\", name } }` instead of a path-keyed route map.";
+        }
+    }
+    return hints;
+}
+function validateRouteEntry(route, resource) {
+    const entry = requireObject(route, resource);
+    validateKnownFields(entry, resource, ROUTE_ENTRY_FIELDS);
+    if (typeof entry.pattern !== "string" || entry.pattern.length === 0) {
+        throw invalidRouteSpec(`ReleaseSpec.${resource}.pattern must be a non-empty string`, `${resource}.pattern`);
+    }
+    if (entry.methods !== undefined) {
+        if (!Array.isArray(entry.methods)) {
+            throw invalidRouteSpec(`ReleaseSpec.${resource}.methods must be an array of HTTP methods`, `${resource}.methods`);
+        }
+        if (entry.methods.length === 0) {
+            throw invalidRouteSpec(`ReleaseSpec.${resource}.methods must not be empty; omit methods to allow all supported methods`, `${resource}.methods`);
+        }
+        for (const method of entry.methods) {
+            if (typeof method !== "string" || !ROUTE_METHOD_SET.has(method)) {
+                throw invalidRouteSpec(`Unsupported route method ${JSON.stringify(method)} at ReleaseSpec.${resource}.methods. Supported methods: ${ROUTE_HTTP_METHODS.join(", ")}`, `${resource}.methods`);
+            }
+        }
+    }
+    validateRouteTarget(entry.target, `${resource}.target`);
+}
+function validateRouteTarget(target, resource) {
+    const obj = requireObject(target, resource);
+    if (hasOwn(obj, "function") && !hasOwn(obj, "type")) {
+        throw invalidRouteSpec(`ReleaseSpec.${resource} uses an unsupported target shorthand. Use { type: "function", name: "api" }.`, resource);
+    }
+    validateKnownFields(obj, resource, ROUTE_TARGET_FIELDS);
+    if (obj.type === undefined) {
+        throw invalidRouteSpec(`ReleaseSpec.${resource}.type is required; use "function"`, `${resource}.type`);
+    }
+    if (obj.type !== "function") {
+        throw invalidRouteSpec(`Unsupported route target type ${JSON.stringify(obj.type)} at ReleaseSpec.${resource}.type; Phase 1 routes support only "function" targets`, `${resource}.type`);
+    }
+    if (typeof obj.name !== "string" || obj.name.length === 0) {
+        throw invalidRouteSpec(`ReleaseSpec.${resource}.name is required for function route targets`, `${resource}.name`);
+    }
+}
+function validateChecksSpec(checks) {
+    if (checks === undefined)
+        return;
+    if (!Array.isArray(checks)) {
+        throw invalidSpec("ReleaseSpec.checks must be an array", "checks");
+    }
+}
+function validateKnownFields(obj, resource, allowed, hints = {}) {
+    for (const key of Object.keys(obj)) {
+        if (allowed.has(key))
+            continue;
+        const field = resource === "spec" ? `spec.${key}` : `${resource}.${key}`;
+        const hint = hints[key] ? ` ${hints[key]}` : "";
+        throw invalidSpec(`Unknown ReleaseSpec field: ${field}.${hint}`, field);
+    }
+}
+function requireObject(value, resource) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidSpec(`ReleaseSpec.${resource} must be an object`, resource);
+    }
+    return value;
+}
+function validateStringArray(value, resource) {
+    if (!Array.isArray(value)) {
+        throw invalidSpec(`ReleaseSpec.${resource} must be an array`, resource);
+    }
+    if (value.some((entry) => typeof entry !== "string")) {
+        throw invalidSpec(`ReleaseSpec.${resource} entries must be strings`, resource);
+    }
+}
+function hasDeployableContent(spec) {
+    return (hasDatabaseContent(spec.database) ||
+        hasSiteContent(spec.site) ||
+        hasFunctionsContent(spec.functions) ||
+        hasSecretsContent(spec.secrets) ||
+        hasSubdomainsContent(spec.subdomains) ||
+        hasRecordEntries(spec.routes) ||
+        hasArrayEntries(spec.checks));
+}
+function hasDatabaseContent(database) {
+    if (!isRecord(database))
+        return false;
+    return hasArrayEntries(database.migrations) || hasRecordEntries(database.expose);
+}
+function hasSiteContent(site) {
+    if (!isRecord(site))
+        return false;
+    if (hasRecordEntries(site.replace))
+        return true;
+    if (!isRecord(site.patch))
+        return false;
+    return hasRecordEntries(site.patch.put) || hasArrayEntries(site.patch.delete);
+}
+function hasFunctionsContent(functions) {
+    if (!isRecord(functions))
+        return false;
+    if (hasRecordEntries(functions.replace))
+        return true;
+    if (!isRecord(functions.patch))
+        return false;
+    return hasRecordEntries(functions.patch.set) || hasArrayEntries(functions.patch.delete);
+}
+function hasSecretsContent(secrets) {
+    if (!isRecord(secrets))
+        return false;
+    return hasArrayEntries(secrets.require) || hasArrayEntries(secrets.delete);
+}
+function hasSubdomainsContent(subdomains) {
+    if (!isRecord(subdomains))
+        return false;
+    return (hasArrayEntries(subdomains.set) ||
+        hasArrayEntries(subdomains.add) ||
+        hasArrayEntries(subdomains.remove));
+}
+function hasRecordEntries(value) {
+    return isRecord(value) && Object.keys(value).length > 0;
+}
+function hasArrayEntries(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function invalidSpec(message, resource) {
+    return new Run402DeployError(message, {
+        code: "INVALID_SPEC",
+        phase: "validate",
+        resource,
+        retryable: false,
+        fix: { action: "set_field", path: resource.replace(/^spec\./, "") },
+        context: "validating spec",
+    });
+}
+function invalidRouteSpec(message, resource) {
+    return new Run402DeployError(message, {
+        code: "INVALID_SPEC",
+        phase: "validate",
+        resource,
+        retryable: false,
+        fix: {
+            action: "set_field",
+            path: "routes.replace",
+            example: {
+                routes: {
+                    replace: [
+                        {
+                            pattern: "/api/*",
+                            target: { type: "function", name: "api" },
+                        },
+                    ],
+                },
+            },
+        },
+        context: "validating spec",
+    });
 }
 function normalizePlanResponse(plan) {
     const raw = plan;
@@ -810,6 +1157,7 @@ function normalizePlanResponse(plan) {
             functions: raw.functions,
             secrets: raw.secrets,
             subdomains: raw.subdomains,
+            routes: raw.routes,
         };
         return {
             ...plan,
@@ -939,8 +1287,9 @@ async function normalizeReleaseSpec(client, spec) {
         normalized.base = spec.base;
     if (spec.subdomains)
         normalized.subdomains = spec.subdomains;
-    if (spec.routes)
+    if (hasOwn(spec, "routes")) {
         normalized.routes = spec.routes;
+    }
     if (spec.checks)
         normalized.checks = spec.checks;
     if (spec.secrets)