@void/deploy-core 0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Cloudflare, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @void/deploy-core
+
+Shared deployment contracts for the Void SDK and hosted Void platform.
+
+This package owns the wire types exchanged by the `void` CLI and the managed
+platform, including deployment manifests, progress events, assets, routing
+rules, queues, append-only Durable Object migration planning and metadata, normalized upload artifacts, runtime
+manifest validation, and provider-neutral resource planning. It has no
+dependency on either deployment target and must remain usable from Node.js and
+Cloudflare Workers.
+
+The package also defines the adapter boundary implemented by deployment
+targets. Target-specific orchestration belongs in `void` or `platform/`, not
+here.

package/dist/index.d.mts

@@ -0,0 +1,400 @@
+//#region src/validate.d.ts
+export declare const MANIFEST_REDIRECT_RULE_STATUSES: ReadonlySet<number>;
+export declare const MAX_ROUTING_RULES = 2e3;
+export declare const MAX_REVALIDATE_QUERY_ALLOWLIST_ENTRIES: number;
+export declare function validateManifestShape(parsed: unknown): string | null;
+//#endregion
+//#region src/resource-plan.d.ts
+type DeployResource = {
+  type: "d1";
+  bindingName: string;
+} | {
+  type: "kv";
+  bindingName: string;
+} | {
+  type: "r2";
+  bindingName: string;
+} | {
+  type: "queue";
+  bindingName: string;
+  resourceName: string;
+  consumer: QueueMeta;
+} | {
+  type: "hyperdrive";
+  bindingName: string;
+};
+type DeployResourcePlan = {
+  resources: Array<DeployResource>;
+  runtime: {
+    ai: boolean;
+    schedules: NonNullable<DeployManifest["schedules"]>;
+    websocket: DeployManifest["websocket"] | null;
+    sandbox: DeployManifest["sandbox"] | null;
+    live: DeployManifest["live"] | null;
+  };
+};
+/**
+ * Convert a deployment manifest into provider-neutral resource intent.
+ *
+ * Resource names, remote ids, and injected platform bindings belong to the
+ * target adapter and are deliberately absent from this plan.
+ */
+export declare function createDeployResourcePlan(manifest: DeployManifest): DeployResourcePlan;
+//#endregion
+//#region src/target.d.ts
+/** A concrete destination that can execute a Void deployment. */
+type DeployTarget = "cloudflare" | "void";
+type DeployAppType = "void" | "spa" | "static" | "framework";
+type DeployCapabilitySupport = "supported" | "partial" | "unsupported";
+/**
+ * Cross-target capabilities used by CLI planning and user-facing diagnostics.
+ *
+ * A target reports what it can execute today. Capability declarations must not
+ * be aspirational: feature gates are removed only when the corresponding
+ * adapter and end-to-end coverage exist.
+ */
+type DeployTargetCapabilities = {
+  managedProjects: boolean;
+  skipBuild: boolean;
+  appTypes: Readonly<Record<DeployAppType, DeployCapabilitySupport>>;
+  features: Readonly<{
+    auth: DeployCapabilitySupport;
+    cron: DeployCapabilitySupport;
+    queues: DeployCapabilitySupport;
+    durableState: DeployCapabilitySupport;
+    webSockets: DeployCapabilitySupport;
+    live: DeployCapabilitySupport;
+    sandbox: DeployCapabilitySupport;
+    isr: DeployCapabilitySupport;
+    remoteDevelopment: DeployCapabilitySupport;
+    deploymentHistory: DeployCapabilitySupport;
+    rollback: DeployCapabilitySupport;
+    secrets: DeployCapabilitySupport;
+    domains: DeployCapabilitySupport;
+    logs: DeployCapabilitySupport;
+  }>;
+};
+/**
+ * Boundary implemented by deployment targets.
+ *
+ * Build classification and packaging stay outside the adapter; provider
+ * credentials, resource names, remote ids, and execution stay inside it.
+ */
+type DeployTargetAdapter<TOptions, TContext> = {
+  readonly target: DeployTarget;
+  readonly capabilities: DeployTargetCapabilities;
+  deploy(root: string, options: TOptions, context: TContext): Promise<void>;
+};
+//#endregion
+//#region src/intent.d.ts
+type DeployRuntimeFeatures = Readonly<{
+  assets: boolean;
+  auth: boolean;
+  cron: boolean;
+  queues: boolean;
+  migrations: boolean;
+  ai: boolean;
+  durableObjects: boolean;
+  webSockets: boolean;
+  live: boolean;
+  sandbox: boolean;
+  isr: boolean;
+  prerender: boolean;
+}>;
+/** Canonical, target-neutral interpretation of a deployment manifest. */
+type DeployIntent = Readonly<{
+  appType: DeployAppType;
+  hasWorker: boolean;
+  manifest: DeployManifest;
+  resourcePlan: DeployResourcePlan;
+  features: DeployRuntimeFeatures;
+}>;
+/**
+ * Interpret a manifest once before a target assigns provider names and ids.
+ * This function performs no I/O and does not mutate the manifest.
+ */
+export declare function createDeployIntent(manifest: DeployManifest): DeployIntent;
+//#endregion
+//#region src/artifact.d.ts
+export declare const DEPLOY_ARTIFACT_VERSION: 1;
+/** Content-addressed metadata for one static asset in a deployment artifact. */
+type DeployAssetManifestEntry = {
+  blake3: string;
+  md5: string;
+  size: number;
+  /** @deprecated v1 alias of `blake3`. */
+  hash: string;
+};
+/** Target-neutral output of packaging a Void application for deployment. */
+type DeployArtifact = Readonly<{
+  artifactVersion: typeof DEPLOY_ARTIFACT_VERSION;
+  manifest: Readonly<DeployManifest>;
+  assetManifest: Readonly<Record<string, Readonly<DeployAssetManifestEntry>>>;
+  /** Worker module bytes keyed by relative path, base64-encoded for transport. */
+  workerFiles?: Readonly<Record<string, string>>;
+}>;
+type DeploySourceMetadata = {
+  source: string | null;
+  commit: string | null;
+  repositoryUrl: string | null;
+  commitUrl: string | null;
+  gitRef: string | null;
+};
+/** JSON payload accepted by the managed deployment API. */
+type DeployUploadPayload = {
+  manifest: DeployManifest;
+  assetManifest: Record<string, DeployAssetManifestEntry>;
+  workerFiles?: Record<string, string>;
+} & DeploySourceMetadata & {
+  preflight: "true" | null;
+};
+/** Asset declaration accepted by the direct-upload URL endpoint. */
+type DeployAssetUploadRequest = {
+  blake3: string;
+  md5: string;
+  size: number;
+  contentType: string;
+};
+/** Build one target-neutral artifact before either target adds provider state. */
+export declare function createDeployArtifact(input: {
+  manifest: DeployManifest;
+  assetManifest: Record<string, DeployAssetManifestEntry>;
+  workerFiles?: Record<string, string>;
+}): DeployArtifact;
+/** Convert the canonical artifact into the stable hosted-platform wire shape. */
+export declare function createDeployUploadPayload(artifact: DeployArtifact, metadata: DeploySourceMetadata & {
+  preflight: "true" | null;
+}): DeployUploadPayload;
+//#endregion
+//#region src/index.d.ts
+export declare const SUPPORTED_MANIFEST_VERSIONS: ReadonlyArray<number>;
+export type MigrationMeta = {
+  name: string;
+  destructive: boolean;
+};
+export type ScheduleMeta = {
+  name: string;
+  cron: string;
+};
+export type QueueMeta = {
+  name: string;
+  bindingName: string;
+  maxBatchSize?: number;
+  maxBatchTimeout?: number;
+  maxRetries?: number;
+  retryDelay?: number;
+};
+export type HeaderRule = {
+  pattern: string;
+  headers: Array<[string, string]>;
+};
+/** Public wire shape of a redirect, rewrite, or fallback rule. */
+export type RedirectRule = {
+  source: string;
+  destination: string;
+  status: number;
+  /** Lowercase literal hostname. Path-only rules omit this field. */
+  host?: string;
+};
+export type AssetConfig = {
+  not_found_handling?: "none" | "single-page-application" | "404-page";
+  html_handling?: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none";
+  /** Native Cloudflare Workers Assets routing; ignored by managed dispatch. */
+  run_worker_first?: boolean | Array<string>;
+};
+export type WebSocketRouteMeta = {
+  pattern: string;
+  filePath: string;
+  className: string;
+  bindingName?: string;
+  mode: "room" | "socket";
+  hasAuthGate: boolean;
+};
+export type WebSocketMigrationMeta = {
+  tag: string;
+  newClasses?: ReadonlyArray<string>;
+  newSqliteClasses?: ReadonlyArray<string>;
+  deletedClasses?: ReadonlyArray<string>;
+};
+export type DurableObjectMigrationStep = {
+  tag?: string;
+  new_classes?: ReadonlyArray<string>;
+  new_sqlite_classes?: ReadonlyArray<string>;
+  deleted_classes?: ReadonlyArray<string>;
+  renamed_classes?: ReadonlyArray<{
+    from: string;
+    to: string;
+  }>;
+  transferred_classes?: ReadonlyArray<{
+    from: string;
+    from_script: string;
+    to: string;
+  }>;
+};
+export type PlannedWebSocketMigrations = {
+  classes: ReadonlyArray<string>;
+  migrations: ReadonlyArray<WebSocketMigrationMeta>;
+  changed: boolean;
+  nextVersion: number;
+};
+/**
+ * Preserve an existing WebSocket class history while assigning every genuinely
+ * new class to SQLite-backed Durable Object storage.
+ */
+export declare function planWebSocketMigrations(input: {
+  nextClasses: ReadonlyArray<string> | undefined;
+  previousClasses: ReadonlyArray<string> | undefined;
+  previousMigrations: ReadonlyArray<WebSocketMigrationMeta> | undefined;
+  currentVersion: number;
+  tagPrefix?: string;
+}): PlannedWebSocketMigrations;
+/** Append one SQLite class step without reclassifying an existing namespace. */
+export declare function appendSqliteClassMigration(migrations: ReadonlyArray<DurableObjectMigrationStep>, classes: ReadonlyArray<string>, baseTag: string, knownExistingClasses?: ReadonlyArray<string>): {
+  migrations: ReadonlyArray<DurableObjectMigrationStep>;
+  added: boolean;
+};
+export type WebSocketManifestMeta = {
+  routes: ReadonlyArray<WebSocketRouteMeta>;
+  classes: ReadonlyArray<string>;
+  migrations?: ReadonlyArray<WebSocketMigrationMeta>;
+};
+export type SandboxMigrationMeta = {
+  tag: string;
+  newSqliteClasses?: ReadonlyArray<string>;
+  deletedClasses?: ReadonlyArray<string>;
+};
+export type SandboxManifestMeta = {
+  bindingName: string;
+  className: string;
+  containerName: string;
+  image: string;
+  instanceType?: string;
+  maxInstances?: number;
+  migrations?: ReadonlyArray<SandboxMigrationMeta>;
+};
+export type LiveMigrationMeta = {
+  tag: string;
+  newSqliteClasses?: ReadonlyArray<string>;
+};
+export type LiveManifestMeta = {
+  bindingName: string;
+  className: string;
+  storage: "sqlite";
+  classes: ReadonlyArray<string>;
+  migrations?: ReadonlyArray<LiveMigrationMeta>;
+};
+export type DeployManifest = {
+  version: number;
+  assetManifestVersion?: 1 | 2;
+  auth?: boolean;
+  bindings: {
+    d1?: Array<string>;
+    kv?: Array<string>;
+    r2?: Array<string>;
+    ai?: boolean;
+    hyperdrive?: Array<string>;
+  };
+  migrations?: {
+    dialect: "sqlite" | "postgresql" | "mysql";
+    pending: number;
+    protocolVersion?: 2;
+    classifierVersion?: number;
+    migrationListHash?: string;
+    stability?: "stable" | "legacy";
+  };
+  schedules?: Array<ScheduleMeta>;
+  queues?: Array<QueueMeta>;
+  ssr?: boolean;
+  framework?: string;
+  type?: "void" | "spa" | "static" | "framework";
+  /** @deprecated Legacy v1 static deployment discriminator. */
+  static?: "spa" | "ssg";
+  revalidate?: number | Record<string, number>;
+  revalidateQueryAllowlist?: Record<string, Array<string>>;
+  pages?: Array<{
+    pattern: string;
+    revalidate?: number;
+  }>;
+  pathRevalidate?: Record<string, number>;
+  prerender?: Array<string>;
+  assetConfig?: AssetConfig;
+  vars?: Record<string, string>;
+  workerMain?: string;
+  compatibilityDate?: string;
+  compatibilityFlags?: Array<string>;
+  limits?: {
+    cpuMs?: number;
+  };
+  hashedAssetsPrefix?: string;
+  headerRules?: Array<HeaderRule>;
+  redirectRules?: Array<RedirectRule>;
+  fallbackRules?: Array<RedirectRule>;
+  websocket?: WebSocketManifestMeta;
+  sandbox?: SandboxManifestMeta;
+  live?: LiveManifestMeta;
+};
+export type DeployEvent = {
+  event: "start";
+  deploymentId: string;
+} | {
+  event: "heartbeat";
+  deploymentId?: string;
+  step: string;
+} | {
+  event: "asset_upload";
+  total: number;
+  new: number;
+  cached: number;
+} | {
+  event: "asset_upload_done";
+} | {
+  event: "provisioning";
+  bindings: Array<string>;
+} | {
+  event: "provisioning_done";
+} | {
+  event: "worker_readiness";
+} | {
+  event: "migration_start";
+  pending: number;
+} | {
+  event: "migration";
+  name: string;
+  durationMs: number;
+  stability?: "stable" | "legacy";
+} | {
+  event: "migration_warning";
+  message: string;
+} | {
+  event: "worker_upload";
+  modules: number;
+} | {
+  event: "worker_upload_done";
+} | {
+  event: "queue_setup";
+  queues: Array<string>;
+} | {
+  event: "queue_consumer_conflict";
+  queue: string;
+  ownerScript: string;
+} | {
+  event: "prerender";
+  pages: number;
+} | {
+  event: "prerender_done";
+} | {
+  event: "done";
+  deployment: string;
+  url: string;
+  urls: Array<string>;
+  assets: number;
+  workers: number;
+  migrations?: number;
+  published?: boolean;
+} | {
+  event: "error";
+  message: string;
+  step: string;
+};
+//#endregion
+export type { DeployAppType, DeployArtifact, DeployAssetManifestEntry, DeployAssetUploadRequest, DeployCapabilitySupport, DeployIntent, DeployResource, DeployResourcePlan, DeployRuntimeFeatures, DeploySourceMetadata, DeployTarget, DeployTargetAdapter, DeployTargetCapabilities, DeployUploadPayload };

package/dist/index.mjs

@@ -0,0 +1,473 @@
+//#region src/validate.ts
+const MANIFEST_REDIRECT_RULE_STATUSES = /* @__PURE__ */ new Set([
+	200,
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+const MAX_ROUTING_RULES = 2e3;
+const MAX_REVALIDATE_QUERY_ALLOWLIST_ENTRIES = MAX_ROUTING_RULES;
+const MAX_PAGES = 5e3;
+/**
+* Strict literal-hostname regex used to validate `redirectRules[].host` /
+* `fallbackRules[].host` on the deploy manifest. Mirrors the regex in
+* `routes/domains.ts` (custom-domain create endpoint) — the source of truth
+* for what counts as a valid project-owned hostname. Rejects scheme prefixes,
+* ports, paths, whitespace, control chars, wildcards, single-label hosts,
+* IPv4 literals, and userinfo. Hostnames are lowercased before testing so
+* the same byte-exact form is what dispatch compares against `url.hostname`
+* (also lowercase per WHATWG).
+*/
+const LITERAL_HOSTNAME_REGEX = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+/**
+* Validate and lowercase-normalize an optional `host` field on a redirect or
+* fallback rule. Mutates `ruleObject.host` in place so the persisted manifest carries
+* the canonical form. Returns an error message string on failure, or `null`
+* on success (including the absent-field case).
+*/
+function validateRuleHost(ruleObject, ruleKind, sourceRef) {
+	if (ruleObject.host === void 0) return null;
+	if (typeof ruleObject.host !== "string") return `invalid manifest shape: ${ruleKind} entry ${sourceRef} host must be a string`;
+	const normalized = ruleObject.host.toLowerCase();
+	if (!LITERAL_HOSTNAME_REGEX.test(normalized)) return `invalid manifest shape: ${ruleKind} entry ${sourceRef} host must be a literal hostname (e.g. "www.example.com"; no scheme, port, path, or wildcards): ${JSON.stringify(ruleObject.host)}`;
+	ruleObject.host = normalized;
+	return null;
+}
+function validateManifestShape(parsed) {
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return "invalid manifest shape: expected a JSON object";
+	const manifest = parsed;
+	if (manifest.bindings == null || typeof manifest.bindings !== "object" || Array.isArray(manifest.bindings)) return "invalid manifest shape: bindings must be an object";
+	const bindings = manifest.bindings;
+	for (const key of [
+		"d1",
+		"kv",
+		"r2",
+		"hyperdrive"
+	]) {
+		const bindingValue = bindings[key];
+		if (bindingValue === void 0) continue;
+		if (!Array.isArray(bindingValue) || !bindingValue.every((value) => typeof value === "string")) return `invalid manifest shape: bindings.${key} must be an array of strings`;
+	}
+	if (manifest.queues !== void 0) {
+		if (!Array.isArray(manifest.queues)) return "invalid manifest shape: queues must be an array";
+		for (const queue of manifest.queues) {
+			if (queue == null || typeof queue !== "object" || Array.isArray(queue)) return "invalid manifest shape: queues entries must be objects";
+			const queueObject = queue;
+			if (typeof queueObject.name !== "string" || typeof queueObject.bindingName !== "string") return "invalid manifest shape: queues entries must have string name and bindingName";
+			for (const tuning of [
+				"maxBatchSize",
+				"maxBatchTimeout",
+				"maxRetries",
+				"retryDelay"
+			]) {
+				const tuningValue = queueObject[tuning];
+				if (tuningValue === void 0) continue;
+				if (typeof tuningValue !== "number" || !Number.isFinite(tuningValue)) return `invalid manifest shape: queues entry ${tuning} must be a finite number`;
+			}
+		}
+	}
+	if (manifest.schedules !== void 0) {
+		if (!Array.isArray(manifest.schedules)) return "invalid manifest shape: schedules must be an array";
+		for (const schedule of manifest.schedules) {
+			if (schedule == null || typeof schedule !== "object" || Array.isArray(schedule)) return "invalid manifest shape: schedules entries must be objects";
+			const scheduleObject = schedule;
+			if (typeof scheduleObject.name !== "string" || typeof scheduleObject.cron !== "string") return "invalid manifest shape: schedules entries must have string name and cron";
+		}
+	}
+	if (manifest.prerender !== void 0) {
+		if (!Array.isArray(manifest.prerender) || !manifest.prerender.every((x) => typeof x === "string")) return "invalid manifest shape: prerender must be an array of strings";
+	}
+	if (manifest.vars !== void 0) {
+		if (manifest.vars == null || typeof manifest.vars !== "object" || Array.isArray(manifest.vars)) return "invalid manifest shape: vars must be an object";
+		for (const [k, v] of Object.entries(manifest.vars)) if (typeof v !== "string") return `invalid manifest shape: vars.${k} must be a string`;
+	}
+	if (manifest.migrations !== void 0) {
+		if (manifest.migrations == null || typeof manifest.migrations !== "object" || Array.isArray(manifest.migrations)) return "invalid manifest shape: migrations must be an object";
+		const mig = manifest.migrations;
+		if (mig.dialect !== void 0) {
+			const allowed = [
+				"sqlite",
+				"postgresql",
+				"mysql"
+			];
+			if (typeof mig.dialect !== "string" || !allowed.includes(mig.dialect)) return `invalid manifest shape: migrations.dialect must be one of ${allowed.join(", ")}`;
+		}
+		if (mig.pending !== void 0) {
+			if (typeof mig.pending !== "number" || !Number.isInteger(mig.pending) || mig.pending < 0) return "invalid manifest shape: migrations.pending must be a non-negative integer";
+		}
+		if (mig.protocolVersion !== void 0 && mig.protocolVersion !== 2) return "invalid manifest shape: migrations.protocolVersion must be 2";
+		if (mig.classifierVersion !== void 0 && (typeof mig.classifierVersion !== "number" || !Number.isInteger(mig.classifierVersion))) return "invalid manifest shape: migrations.classifierVersion must be an integer";
+		if (mig.migrationListHash !== void 0 && typeof mig.migrationListHash !== "string") return "invalid manifest shape: migrations.migrationListHash must be a string";
+		if (mig.stability !== void 0 && mig.stability !== "stable" && mig.stability !== "legacy") return "invalid manifest shape: migrations.stability must be stable or legacy";
+	}
+	if (manifest.auth !== void 0 && typeof manifest.auth !== "boolean") return "invalid manifest shape: auth must be a boolean";
+	if (manifest.ssr !== void 0 && typeof manifest.ssr !== "boolean") return "invalid manifest shape: ssr must be a boolean";
+	for (const key of [
+		"workerMain",
+		"compatibilityDate",
+		"hashedAssetsPrefix",
+		"framework"
+	]) if (manifest[key] !== void 0 && typeof manifest[key] !== "string") return `invalid manifest shape: ${key} must be a string`;
+	if (manifest.assetManifestVersion !== void 0) {
+		if (manifest.assetManifestVersion !== 1 && manifest.assetManifestVersion !== 2) return "invalid manifest shape: assetManifestVersion must be 1 or 2";
+	}
+	if (manifest.compatibilityFlags !== void 0) {
+		if (!Array.isArray(manifest.compatibilityFlags) || !manifest.compatibilityFlags.every((x) => typeof x === "string")) return "invalid manifest shape: compatibilityFlags must be an array of strings";
+	}
+	if (manifest.limits !== void 0) {
+		if (manifest.limits == null || typeof manifest.limits !== "object" || Array.isArray(manifest.limits)) return "invalid manifest shape: limits must be an object";
+		const limits = manifest.limits;
+		if (limits.cpuMs !== void 0) {
+			if (typeof limits.cpuMs !== "number" || !Number.isSafeInteger(limits.cpuMs) || limits.cpuMs < 1) return "invalid manifest shape: limits.cpuMs must be a positive integer";
+		}
+	}
+	if (manifest.type !== void 0) {
+		const allowed = [
+			"void",
+			"spa",
+			"static",
+			"framework"
+		];
+		if (typeof manifest.type !== "string" || !allowed.includes(manifest.type)) return `invalid manifest shape: type must be one of ${allowed.join(", ")}`;
+	}
+	if (manifest.assetConfig !== void 0) {
+		if (manifest.assetConfig == null || typeof manifest.assetConfig !== "object" || Array.isArray(manifest.assetConfig)) return "invalid manifest shape: assetConfig must be an object";
+		const assetConfig = manifest.assetConfig;
+		if (assetConfig.not_found_handling !== void 0 && ![
+			"none",
+			"single-page-application",
+			"404-page"
+		].includes(assetConfig.not_found_handling)) return "invalid manifest shape: assetConfig.not_found_handling must be one of none, single-page-application, 404-page";
+		if (assetConfig.html_handling !== void 0 && ![
+			"auto-trailing-slash",
+			"force-trailing-slash",
+			"drop-trailing-slash",
+			"none"
+		].includes(assetConfig.html_handling)) return "invalid manifest shape: assetConfig.html_handling must be one of auto-trailing-slash, force-trailing-slash, drop-trailing-slash, none";
+	}
+	if (manifest.revalidate !== void 0) {
+		if (typeof manifest.revalidate === "number") {} else if (manifest.revalidate == null || typeof manifest.revalidate !== "object" || Array.isArray(manifest.revalidate)) return "invalid manifest shape: revalidate must be a number or object";
+		else for (const [pathname, value] of Object.entries(manifest.revalidate)) if (typeof value !== "number") return `invalid manifest shape: revalidate.${pathname} must be a number`;
+	}
+	if (manifest.headerRules !== void 0) {
+		if (!Array.isArray(manifest.headerRules)) return "invalid manifest shape: headerRules must be an array";
+		for (const rule of manifest.headerRules) {
+			if (rule == null || typeof rule !== "object" || Array.isArray(rule)) return "invalid manifest shape: headerRules entries must be objects";
+			const ruleObject = rule;
+			if (typeof ruleObject.pattern !== "string") return "invalid manifest shape: headerRules entries must have a string pattern";
+			if (!Array.isArray(ruleObject.headers)) return "invalid manifest shape: headerRules entries must have a headers array";
+			for (const pair of ruleObject.headers) if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string" || typeof pair[1] !== "string") return "invalid manifest shape: headerRules headers entries must be [name, value] string pairs";
+		}
+	}
+	if (manifest.redirectRules !== void 0) {
+		if (!Array.isArray(manifest.redirectRules)) return "invalid manifest shape: redirectRules must be an array";
+		if (manifest.redirectRules.length > 2e3) return `invalid manifest shape: redirectRules has ${manifest.redirectRules.length} entries, exceeds the ${MAX_ROUTING_RULES} per-list limit`;
+		for (const rule of manifest.redirectRules) {
+			if (rule == null || typeof rule !== "object" || Array.isArray(rule)) return "invalid manifest shape: redirectRules entries must be objects";
+			const ruleObject = rule;
+			if (typeof ruleObject.source !== "string" || typeof ruleObject.destination !== "string" || typeof ruleObject.status !== "number") return "invalid manifest shape: redirectRules entries must have string source, string destination, and numeric status";
+			const sourceRef = JSON.stringify(ruleObject.source);
+			if (!MANIFEST_REDIRECT_RULE_STATUSES.has(ruleObject.status)) return `invalid manifest shape: redirectRules entry ${sourceRef} status must be one of ${[...MANIFEST_REDIRECT_RULE_STATUSES].join(", ")} (200 = rewrite, 3xx = redirect)`;
+			const destination = ruleObject.destination;
+			const isRewrite = ruleObject.status === 200;
+			if (isRewrite && destination.includes("?")) return `invalid manifest shape: redirectRules entry ${sourceRef} destination must not contain a query string when status is 200`;
+			if (isRewrite && !destination.startsWith("/")) return `invalid manifest shape: redirectRules entry ${sourceRef} destination must be path-absolute (start with "/") when status is 200`;
+			if (isRewrite && destination.startsWith("//")) return `invalid manifest shape: redirectRules entry ${sourceRef} destination must not start with "//" (protocol-relative URLs parse cross-origin; use a single-slash path-absolute destination)`;
+			const hostError = validateRuleHost(ruleObject, "redirectRules", sourceRef);
+			if (hostError) return hostError;
+		}
+	}
+	if (manifest.revalidateQueryAllowlist !== void 0) {
+		if (manifest.revalidateQueryAllowlist == null || typeof manifest.revalidateQueryAllowlist !== "object" || Array.isArray(manifest.revalidateQueryAllowlist)) return "invalid manifest shape: revalidateQueryAllowlist must be an object";
+		const entries = Object.entries(manifest.revalidateQueryAllowlist);
+		if (entries.length > 2e3) return `invalid manifest shape: revalidateQueryAllowlist has ${entries.length} entries, exceeds the ${MAX_REVALIDATE_QUERY_ALLOWLIST_ENTRIES} entry limit`;
+		for (const [pattern, value] of entries) {
+			if (pattern === "") return "invalid manifest shape: revalidateQueryAllowlist must not include an empty pattern";
+			if (!Array.isArray(value)) return `invalid manifest shape: revalidateQueryAllowlist entry ${JSON.stringify(pattern)} must be an array of strings`;
+			for (const param of value) if (typeof param !== "string") return `invalid manifest shape: revalidateQueryAllowlist entry ${JSON.stringify(pattern)} must contain only strings`;
+		}
+	}
+	if (manifest.pages !== void 0) {
+		if (!Array.isArray(manifest.pages)) return "invalid manifest shape: pages must be an array";
+		if (manifest.pages.length > MAX_PAGES) return `invalid manifest shape: pages has ${manifest.pages.length} entries, exceeds the ${MAX_PAGES} entry limit`;
+		for (const entry of manifest.pages) {
+			if (entry == null || typeof entry !== "object" || Array.isArray(entry)) return "invalid manifest shape: each pages entry must be an object";
+			const e = entry;
+			if (typeof e.pattern !== "string" || e.pattern === "") return "invalid manifest shape: pages entry pattern must be a string";
+			if (e.revalidate !== void 0 && typeof e.revalidate !== "number") return "invalid manifest shape: pages entry revalidate must be a number";
+		}
+	}
+	if (manifest.pathRevalidate !== void 0) {
+		if (manifest.pathRevalidate == null || typeof manifest.pathRevalidate !== "object" || Array.isArray(manifest.pathRevalidate)) return "invalid manifest shape: pathRevalidate must be an object";
+		for (const [pathname, value] of Object.entries(manifest.pathRevalidate)) if (typeof value !== "number") return `invalid manifest shape: pathRevalidate.${pathname} must be a number`;
+	}
+	if (manifest.fallbackRules !== void 0) {
+		if (!Array.isArray(manifest.fallbackRules)) return "invalid manifest shape: fallbackRules must be an array";
+		if (manifest.fallbackRules.length > 2e3) return `invalid manifest shape: fallbackRules has ${manifest.fallbackRules.length} entries, exceeds the ${MAX_ROUTING_RULES} per-list limit`;
+		for (const rule of manifest.fallbackRules) {
+			if (rule == null || typeof rule !== "object" || Array.isArray(rule)) return "invalid manifest shape: fallbackRules entries must be objects";
+			const ruleObject = rule;
+			if (typeof ruleObject.source !== "string" || typeof ruleObject.destination !== "string" || typeof ruleObject.status !== "number") return "invalid manifest shape: fallbackRules entries must have string source, string destination, and numeric status";
+			const sourceRef = JSON.stringify(ruleObject.source);
+			if (ruleObject.status !== 200) return `invalid manifest shape: fallbackRules entry ${sourceRef} status must be 200 (fallbacks are rewrites only)`;
+			const destination = ruleObject.destination;
+			if (destination.includes("?")) return `invalid manifest shape: fallbackRules entry ${sourceRef} destination must not contain a query string`;
+			if (!destination.startsWith("/")) return `invalid manifest shape: fallbackRules entry ${sourceRef} destination must be path-absolute (start with "/")`;
+			if (destination.startsWith("//")) return `invalid manifest shape: fallbackRules entry ${sourceRef} destination must not start with "//" (protocol-relative URLs parse cross-origin; use a single-slash path-absolute destination)`;
+			const hostError = validateRuleHost(ruleObject, "fallbackRules", sourceRef);
+			if (hostError) return hostError;
+		}
+	}
+	if (manifest.websocket !== void 0) {
+		if (manifest.websocket == null || typeof manifest.websocket !== "object" || Array.isArray(manifest.websocket)) return "invalid manifest shape: websocket must be an object";
+		const websocket = manifest.websocket;
+		if (!Array.isArray(websocket.routes)) return "invalid manifest shape: websocket.routes must be an array";
+		for (const route of websocket.routes) {
+			if (route == null || typeof route !== "object" || Array.isArray(route)) return "invalid manifest shape: websocket.routes entries must be objects";
+			const routeObject = route;
+			if (typeof routeObject.className !== "string") return "invalid manifest shape: websocket.routes entries must have a string className";
+			if (routeObject.bindingName !== void 0 && typeof routeObject.bindingName !== "string") return "invalid manifest shape: websocket.routes entry bindingName must be a string";
+		}
+		if (!Array.isArray(websocket.classes) || !websocket.classes.every((x) => typeof x === "string")) return "invalid manifest shape: websocket.classes must be an array of strings";
+		if (websocket.migrations !== void 0) {
+			if (!Array.isArray(websocket.migrations)) return "invalid manifest shape: websocket.migrations must be an array";
+			for (const migration of websocket.migrations) {
+				if (migration == null || typeof migration !== "object" || Array.isArray(migration)) return "invalid manifest shape: websocket.migrations entries must be objects";
+				const migrationObject = migration;
+				if (typeof migrationObject.tag !== "string" || migrationObject.tag.length === 0) return "invalid manifest shape: websocket.migrations entries must have a non-empty string tag";
+				for (const field of [
+					"newClasses",
+					"newSqliteClasses",
+					"deletedClasses"
+				]) {
+					const value = migrationObject[field];
+					if (value !== void 0 && (!Array.isArray(value) || !value.every((className) => typeof className === "string"))) return `invalid manifest shape: websocket.migrations ${field} must be an array of strings`;
+				}
+			}
+		}
+	}
+	if (manifest.sandbox !== void 0) {
+		if (manifest.type === "static" || manifest.type === "spa") return "sandbox is not supported for static/spa deployments";
+		if (manifest.sandbox == null || typeof manifest.sandbox !== "object" || Array.isArray(manifest.sandbox)) return "invalid manifest shape: sandbox must be an object";
+		const sandbox = manifest.sandbox;
+		for (const key of [
+			"bindingName",
+			"className",
+			"containerName",
+			"image"
+		]) if (typeof sandbox[key] !== "string" || sandbox[key].length === 0) return `invalid manifest shape: sandbox.${key} must be a non-empty string`;
+		if (isLocalImageReference(sandbox.image)) return "invalid manifest shape: sandbox.image must be a registry image reference";
+		if (sandbox.instanceType !== void 0 && typeof sandbox.instanceType !== "string") return "invalid manifest shape: sandbox.instanceType must be a string";
+		if (sandbox.maxInstances !== void 0 && (typeof sandbox.maxInstances !== "number" || !Number.isInteger(sandbox.maxInstances) || sandbox.maxInstances < 1)) return "invalid manifest shape: sandbox.maxInstances must be a positive integer";
+		if (sandbox.migrations !== void 0) {
+			if (!Array.isArray(sandbox.migrations)) return "invalid manifest shape: sandbox.migrations must be an array";
+			for (const migration of sandbox.migrations) {
+				if (migration == null || typeof migration !== "object" || Array.isArray(migration)) return "invalid manifest shape: sandbox.migrations entries must be objects";
+				const migrationObject = migration;
+				if (typeof migrationObject.tag !== "string") return "invalid manifest shape: sandbox.migrations entries must have a string tag";
+				if (migrationObject.newSqliteClasses !== void 0 && (!Array.isArray(migrationObject.newSqliteClasses) || !migrationObject.newSqliteClasses.every((value) => typeof value === "string"))) return "invalid manifest shape: sandbox.migrations newSqliteClasses must be an array of strings";
+				if (migrationObject.deletedClasses !== void 0 && (!Array.isArray(migrationObject.deletedClasses) || !migrationObject.deletedClasses.every((value) => typeof value === "string"))) return "invalid manifest shape: sandbox.migrations deletedClasses must be an array of strings";
+			}
+		}
+	}
+	if (manifest.live !== void 0) {
+		if (manifest.live == null || typeof manifest.live !== "object" || Array.isArray(manifest.live)) return "invalid manifest shape: live must be an object";
+		const live = manifest.live;
+		for (const key of ["bindingName", "className"]) if (typeof live[key] !== "string" || live[key].length === 0) return `invalid manifest shape: live.${key} must be a non-empty string`;
+		if (live.storage !== "sqlite") return "invalid manifest shape: live.storage must be \"sqlite\"";
+		if (!Array.isArray(live.classes) || !live.classes.every((x) => typeof x === "string")) return "invalid manifest shape: live.classes must be an array of strings";
+		if (live.migrations !== void 0) {
+			if (!Array.isArray(live.migrations)) return "invalid manifest shape: live.migrations must be an array";
+			for (const migration of live.migrations) {
+				if (migration == null || typeof migration !== "object" || Array.isArray(migration)) return "invalid manifest shape: live.migrations entries must be objects";
+				const migrationObject = migration;
+				if (typeof migrationObject.tag !== "string") return "invalid manifest shape: live.migrations entries must have a string tag";
+				if (migrationObject.newSqliteClasses !== void 0 && (!Array.isArray(migrationObject.newSqliteClasses) || !migrationObject.newSqliteClasses.every((value) => typeof value === "string"))) return "invalid manifest shape: live.migrations newSqliteClasses must be an array of strings";
+			}
+		}
+	}
+	return null;
+}
+function isLocalImageReference(image) {
+	const lowerImage = image.toLowerCase();
+	return image.startsWith(".") || image.startsWith("/") || lowerImage === "dockerfile" || lowerImage.includes("dockerfile") || lowerImage.endsWith("/dockerfile") || lowerImage.endsWith("\\dockerfile");
+}
+//#endregion
+//#region src/resource-plan.ts
+/**
+* Convert a deployment manifest into provider-neutral resource intent.
+*
+* Resource names, remote ids, and injected platform bindings belong to the
+* target adapter and are deliberately absent from this plan.
+*/
+function createDeployResourcePlan(manifest) {
+	const resources = [];
+	for (const bindingName of manifest.bindings.d1 ?? []) resources.push({
+		type: "d1",
+		bindingName
+	});
+	for (const bindingName of manifest.bindings.kv ?? []) resources.push({
+		type: "kv",
+		bindingName
+	});
+	for (const bindingName of manifest.bindings.r2 ?? []) resources.push({
+		type: "r2",
+		bindingName
+	});
+	for (const consumer of manifest.queues ?? []) resources.push({
+		type: "queue",
+		bindingName: consumer.bindingName,
+		resourceName: consumer.name,
+		consumer
+	});
+	for (const bindingName of manifest.bindings.hyperdrive ?? []) resources.push({
+		type: "hyperdrive",
+		bindingName
+	});
+	return {
+		resources,
+		runtime: {
+			ai: manifest.bindings.ai === true,
+			schedules: manifest.schedules ?? [],
+			websocket: manifest.websocket ?? null,
+			sandbox: manifest.sandbox ?? null,
+			live: manifest.live ?? null
+		}
+	};
+}
+//#endregion
+//#region src/intent.ts
+/**
+* Interpret a manifest once before a target assigns provider names and ids.
+* This function performs no I/O and does not mutate the manifest.
+*/
+function createDeployIntent(manifest) {
+	const appType = manifest.type ?? (manifest.framework ? "framework" : "void");
+	const webSockets = (manifest.websocket?.classes.length ?? 0) > 0;
+	const live = manifest.live !== void 0;
+	const sandbox = manifest.sandbox !== void 0;
+	return {
+		appType,
+		hasWorker: appType === "void" || appType === "framework",
+		manifest,
+		resourcePlan: createDeployResourcePlan(manifest),
+		features: {
+			assets: manifest.assetConfig !== void 0,
+			auth: manifest.auth === true,
+			cron: (manifest.schedules?.length ?? 0) > 0,
+			queues: (manifest.queues?.length ?? 0) > 0,
+			migrations: (manifest.migrations?.pending ?? 0) > 0,
+			ai: manifest.bindings.ai === true,
+			durableObjects: webSockets || live || sandbox,
+			webSockets,
+			live,
+			sandbox,
+			isr: manifest.revalidate !== void 0 || manifest.pathRevalidate !== void 0 || (manifest.pages?.some((page) => page.revalidate !== void 0) ?? false),
+			prerender: (manifest.prerender?.length ?? 0) > 0
+		}
+	};
+}
+//#endregion
+//#region src/artifact.ts
+const DEPLOY_ARTIFACT_VERSION = 1;
+/** Build one target-neutral artifact before either target adds provider state. */
+function createDeployArtifact(input) {
+	return {
+		artifactVersion: 1,
+		manifest: input.manifest,
+		assetManifest: input.assetManifest,
+		...input.workerFiles && Object.keys(input.workerFiles).length > 0 ? { workerFiles: input.workerFiles } : {}
+	};
+}
+/** Convert the canonical artifact into the stable hosted-platform wire shape. */
+function createDeployUploadPayload(artifact, metadata) {
+	return {
+		manifest: {
+			...artifact.manifest,
+			bindings: { ...artifact.manifest.bindings }
+		},
+		assetManifest: { ...artifact.assetManifest },
+		...artifact.workerFiles ? { workerFiles: { ...artifact.workerFiles } } : {},
+		...metadata
+	};
+}
+//#endregion
+//#region src/index.ts
+const SUPPORTED_MANIFEST_VERSIONS = [3];
+/**
+* Preserve an existing WebSocket class history while assigning every genuinely
+* new class to SQLite-backed Durable Object storage.
+*/
+function planWebSocketMigrations(input) {
+	const nextClasses = sortUniqueStrings(input.nextClasses);
+	const previousClasses = sortUniqueStrings(input.previousClasses);
+	const previousMigrations = input.previousMigrations ?? [];
+	if (!!sameStringSet(nextClasses, previousClasses)) return {
+		classes: nextClasses,
+		migrations: previousMigrations,
+		changed: false,
+		nextVersion: input.currentVersion
+	};
+	const existingClasses = new Set(previousClasses);
+	for (const migration of previousMigrations) {
+		for (const name of migration.newClasses ?? []) existingClasses.add(name);
+		for (const name of migration.newSqliteClasses ?? []) existingClasses.add(name);
+		for (const name of migration.deletedClasses ?? []) existingClasses.delete(name);
+	}
+	const additions = nextClasses.filter((name) => !existingClasses.has(name));
+	if (additions.length === 0) return {
+		classes: nextClasses,
+		migrations: previousMigrations,
+		changed: true,
+		nextVersion: input.currentVersion
+	};
+	const nextVersion = input.currentVersion + 1;
+	return {
+		classes: nextClasses,
+		migrations: [...previousMigrations, {
+			tag: `${input.tagPrefix ?? "ws"}-v${nextVersion}`,
+			newSqliteClasses: additions
+		}],
+		changed: true,
+		nextVersion
+	};
+}
+/** Append one SQLite class step without reclassifying an existing namespace. */
+function appendSqliteClassMigration(migrations, classes, baseTag, knownExistingClasses = []) {
+	const existingClasses = new Set(knownExistingClasses);
+	for (const migration of migrations) {
+		for (const name of migration.new_classes ?? []) existingClasses.add(name);
+		for (const name of migration.new_sqlite_classes ?? []) existingClasses.add(name);
+		for (const rename of migration.renamed_classes ?? []) {
+			existingClasses.delete(rename.from);
+			existingClasses.add(rename.to);
+		}
+		for (const transfer of migration.transferred_classes ?? []) existingClasses.add(transfer.to);
+		for (const name of migration.deleted_classes ?? []) existingClasses.delete(name);
+	}
+	const additions = sortUniqueStrings(classes).filter((name) => !existingClasses.has(name));
+	if (additions.length === 0) return {
+		migrations,
+		added: false
+	};
+	const tags = new Set(migrations.map((migration) => migration.tag).filter(Boolean));
+	let tag = baseTag;
+	for (let suffix = 2; tags.has(tag); suffix++) tag = `${baseTag}-${suffix}`;
+	return {
+		migrations: [...migrations, {
+			tag,
+			new_sqlite_classes: additions
+		}],
+		added: true
+	};
+}
+function sortUniqueStrings(values) {
+	return [...new Set(values ?? [])].sort((a, b) => a.localeCompare(b));
+}
+function sameStringSet(a, b) {
+	return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+//#endregion
+export { DEPLOY_ARTIFACT_VERSION, MANIFEST_REDIRECT_RULE_STATUSES, MAX_REVALIDATE_QUERY_ALLOWLIST_ENTRIES, MAX_ROUTING_RULES, SUPPORTED_MANIFEST_VERSIONS, appendSqliteClassMigration, createDeployArtifact, createDeployIntent, createDeployResourcePlan, createDeployUploadPayload, planWebSocketMigrations, validateManifestShape };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@void/deploy-core",
+  "version": "0.20.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voidzero-dev/void.git",
+    "directory": "packages/deploy-core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vite-plus": "0.3.1"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}