@velajs/cli 1.23.0 → 1.24.0

package/dist/index.js

@@ -1,15 +1,46 @@
 #!/usr/bin/env node
-import { defineVelaConfig, loadConfig } from "./config.js";
+import { defineVelaConfig, loadConfig, resolveConfig } from "./config.js";
 import { t as generateClientContract } from "./client-contract-C7P2btFE.js";
 import { Builtins, Cli, Command, Option, UsageError } from "clipanion";
 import { lstat, mkdir, open, readFile, readdir, rmdir, unlink, writeFile } from "node:fs/promises";
-import { createOpenApiDocument, describeToken, getEntrypointKinds } from "@velajs/vela";
-import { dirname, join } from "node:path";
+import { createOpenApiDocument, describeToken, getEntrypointKinds, parseCron, parseCronMetadata } from "@velajs/vela";
+import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import { runSeeders } from "@velajs/vela/seeder";
+import { SeederRegistry, runSeeders } from "@velajs/vela/seeder";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import { parse } from "jsonc-parser";
+import { parse as parse$1 } from "smol-toml";
 //#region package.json
-var version = "1.23.0";
+var version = "1.24.0";
+//#endregion
+//#region src/with-app.ts
+/** Own one app for the whole command, including output and long-lived transports. */
+async function withApp(config, work, warn) {
+	const app = await config.createApp();
+	const report = (error) => {
+		try {
+			warn(`Warning: teardown failed: ${String(error)}`);
+		} catch {}
+	};
+	try {
+		return await work(app);
+	} finally {
+		try {
+			if (typeof app.dispose === "function") await app.dispose();
+			else await app.getContainer().dispose();
+		} catch (error) {
+			report(error);
+			try {
+				await app.getContainer().dispose();
+			} catch (cleanupError) {
+				report(cleanupError);
+			}
+		}
+	}
+}
 //#endregion
 //#region src/format.ts
 /**
@@ -148,17 +179,9 @@ var AppCommand = class extends Command {
 	config = Option.String("--config", { description: "Path to the vela config file." });
 	json = Option.Boolean("--json", false, { description: "Emit machine-readable JSON." });
 	async execute() {
-		const app = await (await loadConfig(process.cwd(), this.config)).createApp();
-		try {
-			return await this.run(app);
-		} finally {
-			const dispose = app.dispose;
-			if (typeof dispose === "function") try {
-				await dispose.call(app);
-			} catch (error) {
-				this.context.stderr.write(`Warning: teardown failed: ${String(error)}\n`);
-			}
-		}
+		return withApp(await loadConfig(process.cwd(), this.config), (app) => this.run(app), (message) => {
+			this.context.stderr.write(`${message}\n`);
+		});
 	}
 	print(text) {
 		this.context.stdout.write(`${text}\n`);
@@ -261,12 +284,12 @@ var OpenApiDumpCommand = class extends Command {
 			this.context.stderr.write("openapi dump needs the root module. Add it to your vela.config:\n\n  export default defineVelaConfig({\n    rootModule: AppModule,\n    async createApp() { ... },\n  });\n");
 			return 1;
 		}
-		const app = await velaConfig.createApp();
-		try {
+		const rootModule = velaConfig.rootModule;
+		return withApp(velaConfig, async (app) => {
 			const info = {};
 			if (this.title) info.title = this.title;
 			if (this.apiVersion) info.version = this.apiVersion;
-			const document = createOpenApiDocument(velaConfig.rootModule, {
+			const document = createOpenApiDocument(rootModule, {
 				globalPrefix: this.globalPrefix ?? app.getGlobalPrefix(),
 				...Object.keys(info).length > 0 ? { info } : {}
 			});
@@ -276,14 +299,7 @@ var OpenApiDumpCommand = class extends Command {
 				this.context.stdout.write(`Wrote ${this.out}\n`);
 			} else this.context.stdout.write(`${text}\n`);
 			return 0;
-		} finally {
-			const dispose = app.dispose;
-			if (typeof dispose === "function") try {
-				await dispose.call(app);
-			} catch (error) {
-				this.context.stderr.write(`Warning: teardown failed: ${String(error)}\n`);
-			}
-		}
+		}, (message) => this.context.stderr.write(`${message}\n`));
 	}
 };
 //#endregion
@@ -354,10 +370,8 @@ function describeToken$1(app, token) {
 * introspection as the `route`/`module`/`entrypoint`/`openapi` commands, so an
 * AI agent can query a Vela app's shape over the Model Context Protocol.
 *
-* Deliberately does NOT extend `AppCommand`: that base disposes the app in its
-* `finally` the moment `run()` returns, but an MCP server must stay alive until
-* the transport closes. stdout is reserved for JSON-RPC framing; every human
-* message goes to stderr.
+* The application lifetime includes the transport's close promise. stdout is
+* reserved for JSON-RPC framing; every human message goes to stderr.
 */
 var McpServeCommand = class extends Command {
 	static paths = [["mcp", "serve"]];
@@ -375,10 +389,10 @@ var McpServeCommand = class extends Command {
 			this.context.stderr.write(`${message}\n`);
 		};
 		const velaConfig = await loadConfig(process.cwd(), this.config);
-		const app = await velaConfig.createApp();
 		const rootModule = velaConfig.rootModule;
-		try {
-			const server = new McpServer(await readCliIdentity());
+		return withApp(velaConfig, async (app) => {
+			const identity = await readCliIdentity();
+			const server = new McpServer(identity);
 			server.registerTool("route_list", {
 				description: "The app's HTTP route table: framework-composed controller routes (method, full path, Controller#handler) plus everything else mounted on the router, labeled (mounted). Empty when the app builds no HTTP routes.",
 				inputSchema: {}
@@ -434,14 +448,7 @@ var McpServeCommand = class extends Command {
 			log(`vela mcp serve — ready (5 tools${rootModule ? " + vela://openapi resource" : ""}). Awaiting client on stdio; stdout is JSON-RPC only.`);
 			await closed;
 			return 0;
-		} finally {
-			const dispose = app.dispose;
-			if (typeof dispose === "function") try {
-				await dispose.call(app);
-			} catch (error) {
-				this.context.stderr.write(`Warning: teardown failed: ${String(error)}\n`);
-			}
-		}
+		}, log);
 	}
 };
 //#endregion
@@ -453,22 +460,44 @@ var SeedCommand = class extends Command {
 		category: "Database",
 		description: "Run database seeders for the Vela app.",
 		details: "Loads vela.config.{js,mjs,ts}, builds the app, and runs all @Seeder() classes in order.",
-		examples: [["Run all seeders", "vela db seed"], ["Use a specific config", "vela db seed --config ./config/vela.config.js"]]
+		examples: [
+			["Run all seeders", "vela db seed"],
+			["Use a specific config", "vela db seed --config ./config/vela.config.js"],
+			["List seeders and their module owners", "vela db seed --list --json"]
+		]
 	});
 	config = Option.String("--config", { description: "Path to the vela config file." });
 	continueOnError = Option.Boolean("--continue-on-error", false, { description: "Run all seeders even if one fails." });
+	list = Option.Boolean("--list", false, { description: "List registered seeders and their owners without running them." });
+	json = Option.Boolean("--json", false, { description: "Emit --list inventory as JSON." });
 	async execute() {
-		const { createApp } = await loadConfig(process.cwd(), this.config);
-		const app = await createApp();
-		this.context.stdout.write("Running seeders…\n");
-		const code = formatSeedResults(await runSeeders(app, { stopOnError: !this.continueOnError }), (message) => this.context.stdout.write(`${message}\n`));
-		const dispose = app.dispose;
-		if (typeof dispose === "function") try {
-			await dispose.call(app);
-		} catch (error) {
-			this.context.stderr.write(`Warning: teardown failed after seeding: ${String(error)}\n`);
-		}
-		return code;
+		if (this.json && !this.list) throw new UsageError("--json requires --list.");
+		if (this.list && this.continueOnError) throw new UsageError("--list cannot be combined with --continue-on-error.");
+		return withApp(await loadConfig(process.cwd(), this.config), async (app) => {
+			if (this.list) {
+				const inventory = app.get(SeederRegistry).list().map((seeder) => ({
+					name: seeder.name,
+					order: seeder.order,
+					target: describeToken(seeder.target),
+					moduleId: seeder.moduleId ?? null
+				}));
+				const output = this.json ? JSON.stringify(inventory, null, 2) : renderTable([
+					"ORDER",
+					"NAME",
+					"MODULE",
+					"TARGET"
+				], inventory.map((entry) => [
+					String(entry.order),
+					entry.name,
+					entry.moduleId ?? "(unknown)",
+					entry.target
+				])).join("\n");
+				this.context.stdout.write(`${output}\n`);
+				return 0;
+			}
+			this.context.stdout.write("Running seeders…\n");
+			return formatSeedResults(await runSeeders(app, { stopOnError: !this.continueOnError }), (message) => this.context.stdout.write(`${message}\n`));
+		}, (message) => this.context.stderr.write(`${message}\n`));
 	}
 };
 //#endregion
@@ -482,7 +511,7 @@ var SeedCommand = class extends Command {
 const HOST_PACKAGE = "@velajs/studio-host";
 /** True for a failed dynamic `import()` of a missing module (ESM or CJS code). */
 function isModuleNotFound(error, specifier) {
-	const code = error.code;
+	const code = error !== null && typeof error === "object" && "code" in error ? error.code : void 0;
 	if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") return true;
 	return (error instanceof Error ? error.message : "").includes(specifier);
 }
@@ -520,9 +549,9 @@ var StudioCommand = class extends Command {
 		}
 		let port;
 		if (this.port !== void 0) {
-			port = Number.parseInt(this.port, 10);
-			if (Number.isNaN(port) || port < 0 || port > 65535) {
-				this.context.stderr.write(`vela studio: --port must be a number 0-65535, got: ${this.port}\n`);
+			port = Number(this.port);
+			if (!/^\d+$/.test(this.port) || !Number.isInteger(port) || port < 0 || port > 65535) {
+				this.context.stderr.write(`vela studio: --port must be a decimal integer 0-65535, got: ${this.port}\n`);
 				return 1;
 			}
 		}
@@ -582,7 +611,7 @@ var ClientGenerateCommand = class extends Command {
 	async execute() {
 		if (this.input && this.config) throw new Error("Use either --input or --config, not both.");
 		if (this.check && !this.out) throw new Error("--check requires --out.");
-		const document = this.input ? await this.readDocument(this.input) : await this.fromApp();
+		const document = this.input ? await this.#readDocument(this.input) : await this.#fromApp();
 		const { source, warnings } = generateClientContract(document);
 		for (const warning of warnings) this.context.stderr.write(`Warning: ${warning}\n`);
 		if (this.strict && warnings.length) return 1;
@@ -604,28 +633,22 @@ var ClientGenerateCommand = class extends Command {
 		} else this.context.stdout.write(source);
 		return 0;
 	}
-	async readDocument(file) {
+	async #readDocument(file) {
 		return JSON.parse(await readFile(file, "utf8"));
 	}
-	async fromApp() {
+	async #fromApp() {
 		const config = await loadConfig(process.cwd(), this.config);
 		if (!config.rootModule) throw new Error("client generate needs rootModule in vela.config, or pass --input openapi.json.");
-		const app = await config.createApp();
-		try {
-			const document = createOpenApiDocument(config.rootModule, { globalPrefix: app.getGlobalPrefix() });
+		const rootModule = config.rootModule;
+		return withApp(config, async (app) => {
+			const document = createOpenApiDocument(rootModule, { globalPrefix: app.getGlobalPrefix() });
 			for (const route of app.describeRoutes()) {
 				const path = route.path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, "{$1}");
 				const item = document.paths[path];
 				if (!item || !Object.hasOwn(item, route.method.toLowerCase())) throw new Error(`OpenAPI is missing ${route.method} ${route.path}. Update Vela or pass a complete document with --input.`);
 			}
 			return document;
-		} finally {
-			try {
-				await app.dispose();
-			} catch (error) {
-				this.context.stderr.write(`Warning: teardown failed: ${String(error)}\n`);
-			}
-		}
+		}, (message) => this.context.stderr.write(`${message}\n`));
 	}
 };
 //#endregion
@@ -637,6 +660,7 @@ const files = [
 	"tsconfig.json",
 	".swcrc",
 	"wrangler.jsonc",
+	"vela.config.mjs",
 	"gitignore",
 	"README.md",
 	"src/worker.ts",
@@ -707,6 +731,423 @@ var NewCommand = class extends Command {
 	}
 };
 //#endregion
+//#region src/commands/doctor.command.ts
+/** Read only app-owned description APIs; never resolve providers or serialize their values. */
+function describeApplication(app) {
+	return {
+		globalPrefix: app.getGlobalPrefix(),
+		modules: collectModules(app),
+		routes: collectRoutes(app),
+		entrypoints: app.entrypoints.kinds().flatMap((kind) => app.entrypoints.ofKind(kind).map((entry) => ({
+			kind,
+			target: `${describeToken(entry.token)}${entry.methodName === void 0 ? "" : `#${String(entry.methodName)}`}`,
+			..."moduleId" in entry && typeof entry.moduleId === "string" ? { moduleId: entry.moduleId } : {}
+		})))
+	};
+}
+var DoctorCommand = class extends Command {
+	static paths = [["doctor"]];
+	static usage = Command.Usage({
+		category: "Introspection",
+		description: "Explain config resolution and optionally inspect the application graph.",
+		details: "Checks config file resolution without importing it. --app opts into config import and application bootstrap, then reads app-local module, route and entrypoint snapshots and disposes the app. No files are written, providers are not resolved by the snapshot, and entrypoint metadata is omitted.",
+		examples: [["Explain config selection", "vela doctor --json"], ["Inspect a built app", "vela doctor --app --config vela.config.mjs --json"]]
+	});
+	config = Option.String("--config", { description: "Path to the Vela config file." });
+	app = Option.Boolean("--app", false, { description: "Import config, bootstrap the app and inspect its graph." });
+	json = Option.Boolean("--json", false, { description: "Emit machine-readable diagnostics." });
+	async execute() {
+		const report = {
+			schemaVersion: 1,
+			cwd: process.cwd(),
+			nodeVersion: process.versions.node,
+			config: null,
+			issues: []
+		};
+		try {
+			report.config = await resolveConfig(report.cwd, this.config);
+			if (this.app) report.application = await withApp(await loadConfig(report.cwd, report.config.path), describeApplication, (message) => {
+				report.issues.push(message);
+			});
+		} catch (error) {
+			report.issues.push(error instanceof Error ? error.message : String(error));
+		}
+		if (this.json) this.context.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		else {
+			this.context.stdout.write(`Node ${report.nodeVersion}\nWorking directory: ${report.cwd}\n`);
+			if (report.config) {
+				this.context.stdout.write(`Config: ${report.config.path} (${report.config.source})\n`);
+				for (const candidate of report.config.candidates) this.context.stdout.write(`  Checked: ${candidate}\n`);
+			}
+			if (report.application) {
+				const { modules, routes, entrypoints } = report.application;
+				this.context.stdout.write(`Application: ${modules.length} modules, ${routes?.length ?? 0} routes, ${entrypoints.length} entrypoints\n`);
+				this.context.stdout.write("Use --json for the full graph.\n");
+			} else if (!this.app) this.context.stdout.write("Config was not imported. Use --app to bootstrap and inspect a built application.\n");
+			for (const issue of report.issues) this.context.stderr.write(`${issue}\n`);
+		}
+		return report.issues.length ? 1 : 0;
+	}
+};
+//#endregion
+//#region src/commands/deploy-check.config.ts
+const record = z.record(z.string(), z.unknown());
+const text = z.string().min(1).refine((value) => value.trim() === value && !/\p{Cc}/u.test(value));
+const bindingName = text.regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/u);
+const workerName = text.max(255).regex(/^[a-zA-Z0-9-]+$/u);
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/u).refine((value) => {
+	const parsed = new Date(value);
+	return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+});
+/** Decode only data; parser errors deliberately omit configuration values. */
+function parseDeploymentConfig(source, path) {
+	const extension = extname(path).toLowerCase();
+	if (extension === ".toml") try {
+		return parse$1(source);
+	} catch {
+		throw new Error("Invalid Wrangler TOML configuration.");
+	}
+	if (extension !== ".json" && extension !== ".jsonc") throw new Error("Wrangler configuration must be a .json, .jsonc or .toml file.");
+	const errors = [];
+	const result = parse(source, errors, {
+		allowTrailingComma: extension === ".jsonc",
+		disallowComments: extension === ".json"
+	});
+	if (errors.length > 0) throw new Error("Invalid Wrangler JSON configuration.");
+	return result;
+}
+function checked(schema, value, field) {
+	const result = schema.safeParse(value);
+	if (!result.success) throw new Error(`Invalid Wrangler field: ${field}.`);
+	return result.data;
+}
+/** A projection, not a replacement for Wrangler's full configuration validator. */
+function selectDeploymentTarget(raw, environment) {
+	if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(environment)) throw new Error("An explicit environment name using letters, digits, underscores or dashes is required.");
+	const root = checked(record, raw, "configuration");
+	const environments = checked(record, root.env, "env");
+	if (!Object.hasOwn(environments, environment)) throw new Error("The requested environment is not declared in Wrangler configuration.");
+	const selected = checked(record, environments[environment], `env.${environment}`);
+	const inherit = (key) => Object.hasOwn(selected, key) ? selected[key] : root[key];
+	const worker = checked(workerName, Object.hasOwn(selected, "name") ? selected.name : `${checked(workerName, root.name, "name")}-${environment}`, "name");
+	const main = checked(text.optional(), inherit("main"), "main") ?? null;
+	if (main === null) {
+		const assets = checked(record, inherit("assets"), "assets (required without main)");
+		checked(text, assets.directory, "assets.directory");
+	}
+	const compatibilityDate = checked(date, inherit("compatibility_date"), "compatibility_date");
+	const compatibilityFlags = checked(z.array(text).optional(), inherit("compatibility_flags"), "compatibility_flags") ?? [];
+	const triggers = checked(z.object({ crons: z.array(text) }).optional(), inherit("triggers"), "triggers");
+	const build = checked(z.object({ command: text.optional() }).optional(), inherit("build"), "build");
+	const bindings = [];
+	const names = /* @__PURE__ */ new Set();
+	const add = (name, kind) => {
+		if (names.has(name)) throw new Error(`Duplicate Worker binding name: ${name}.`);
+		names.add(name);
+		bindings.push({
+			name,
+			kind
+		});
+	};
+	const variables = checked(record.optional(), selected.vars, "vars") ?? {};
+	for (const name of Object.keys(variables)) add(checked(bindingName, name, "vars binding name"), "var");
+	for (const kind of [
+		"kv_namespaces",
+		"d1_databases",
+		"r2_buckets",
+		"services",
+		"hyperdrive",
+		"vectorize",
+		"workflows",
+		"analytics_engine_datasets"
+	]) {
+		const rows = checked(z.array(record).optional(), selected[kind], kind) ?? [];
+		for (const row of rows) {
+			add(checked(bindingName, row.binding, `${kind}.binding`), kind);
+			for (const field of [
+				"id",
+				"database_id",
+				"database_name",
+				"bucket_name"
+			]) if (Object.hasOwn(row, field)) checked(text, row[field], `${kind}.${field}`);
+			if (kind === "services") checked(workerName, row.service, "services.service");
+			if (kind === "workflows") checked(text, row.class_name, "workflows.class_name");
+		}
+	}
+	const durable = checked(z.object({ bindings: z.array(z.object({
+		name: bindingName,
+		class_name: text,
+		script_name: workerName.optional()
+	})) }).optional(), selected.durable_objects, "durable_objects");
+	for (const row of durable?.bindings ?? []) add(row.name, "durable_objects");
+	const queues = checked(z.object({
+		producers: z.array(z.object({
+			binding: bindingName,
+			queue: text.optional()
+		})).optional(),
+		consumers: z.array(z.object({ queue: text })).optional()
+	}).optional(), selected.queues, "queues");
+	for (const producer of queues?.producers ?? []) add(producer.binding, "queues");
+	const queueConsumers = queues?.consumers?.map((row) => row.queue) ?? [];
+	if (new Set(queueConsumers).size !== queueConsumers.length) throw new Error("Duplicate queue consumer configuration.");
+	return {
+		environment,
+		worker,
+		main,
+		compatibilityDate,
+		compatibilityFlags,
+		crons: triggers?.crons ?? [],
+		bindings,
+		queueConsumers,
+		customBuild: build?.command !== void 0
+	};
+}
+//#endregion
+//#region src/commands/deploy-check.plan.ts
+const rowsSchema = z.array(z.object({
+	kind: z.string().min(1),
+	target: z.string().min(1),
+	meta: z.unknown()
+}));
+const metadataSchema = z.record(z.string(), z.unknown());
+/** Accept existing `vela entrypoint list --json` output without loading an application. */
+function entrypoints(value) {
+	const parsed = rowsSchema.safeParse(value);
+	if (!parsed.success) throw new Error("Entrypoint snapshot must be an array of { kind, target, meta } rows.");
+	return parsed.data.filter((row) => !(row.target === "(no entrypoints)" && row.meta === "")).map((row) => {
+		let meta = row.meta;
+		if (typeof meta === "string") try {
+			meta = JSON.parse(meta);
+		} catch {
+			throw new Error("Invalid JSON metadata in entrypoint snapshot.");
+		}
+		return {
+			kind: row.kind,
+			meta
+		};
+	});
+}
+/** Compare literal dispatch keys; equivalent cron expressions are not interchangeable. */
+function checkDeployment(rawConfig, environment, snapshot) {
+	const target = selectDeploymentTarget(rawConfig, environment);
+	const errors = [];
+	const warnings = [];
+	const report = (code, message) => errors.push({
+		code,
+		message
+	});
+	const validateCron = (cron) => {
+		if (!parseCron(cron, {
+			dialect: "cloudflare",
+			timeZone: "UTC"
+		})) report("invalid-cron", "A trigger or handler has an invalid Cloudflare cron expression.");
+	};
+	const crons = new Set(target.crons);
+	if (crons.size !== target.crons.length) report("duplicate-cron", "Duplicate cron trigger configuration.");
+	for (const cron of crons) validateCron(cron);
+	const handlerCrons = /* @__PURE__ */ new Set();
+	const handlerQueues = /* @__PURE__ */ new Set();
+	for (const row of entrypoints(snapshot)) {
+		if (row.kind === "schedule:interval") {
+			report("unsupported-interval", "Workers cannot drive @Interval handlers; use a scheduled trigger or a separate Node adapter.");
+			continue;
+		}
+		if (![
+			"cf:scheduled",
+			"cf:vela-cron",
+			"schedule:cron",
+			"cf:queue",
+			"websocket"
+		].includes(row.kind)) continue;
+		const parsed = metadataSchema.safeParse(row.meta);
+		if (!parsed.success) {
+			report("invalid-metadata", `Invalid ${row.kind} metadata.`);
+			continue;
+		}
+		const meta = parsed.data;
+		if (row.kind === "cf:vela-cron" || row.kind === "schedule:cron") try {
+			const cron = parseCronMetadata(meta);
+			if (cron.dialect !== void 0 && cron.dialect !== "cloudflare" || cron.timeZone !== void 0 && cron.timeZone !== "UTC") report("incompatible-cron-options", "A cron handler explicitly requests options incompatible with Cloudflare UTC delivery.");
+		} catch {
+			report("invalid-metadata", `Invalid ${row.kind} metadata.`);
+			continue;
+		}
+		if (row.kind === "websocket") {
+			const options = Object.hasOwn(meta, "options") ? metadataSchema.safeParse(meta.options) : parsed;
+			const binding = options.success ? options.data.binding : void 0;
+			if (typeof binding !== "string" || !target.bindings.some((b) => b.kind === "durable_objects" && b.name === binding)) report("missing-durable-binding", "A WebSocket gateway requires a Durable Object binding in the selected environment.");
+			continue;
+		}
+		const key = row.kind === "cf:scheduled" ? "cron" : row.kind === "cf:queue" ? "queueName" : "expression";
+		const value = meta[key];
+		if (typeof value !== "string" || value.trim().length === 0) {
+			report("invalid-metadata", `Invalid ${row.kind}.${key} metadata.`);
+			continue;
+		}
+		if (row.kind === "cf:queue") handlerQueues.add(value);
+		else {
+			handlerCrons.add(value);
+			validateCron(value);
+		}
+	}
+	for (const cron of handlerCrons) if (!crons.has(cron)) report("missing-cron-trigger", `No exact Wrangler trigger for handler cron ${JSON.stringify(cron)}.`);
+	for (const cron of crons) if (!handlerCrons.has(cron)) report("unhandled-cron-trigger", `No metadata handler for Wrangler cron ${JSON.stringify(cron)}.`);
+	for (const queue of handlerQueues) if (!target.queueConsumers.includes(queue)) report("missing-queue-consumer", `No selected queue consumer for handler queue ${JSON.stringify(queue)}.`);
+	for (const queue of target.queueConsumers) if (!handlerQueues.has(queue)) report("unhandled-queue-consumer", `No metadata handler for selected queue ${JSON.stringify(queue)}.`);
+	warnings.push({
+		code: "static-only",
+		message: "Snapshot freshness, custom platform handlers, deployed resources, secrets and bundle/runtime behavior are not verified. Run Wrangler and native tests separately."
+	});
+	if (target.customBuild) warnings.push({
+		code: "custom-build",
+		message: "Wrangler has a custom build command. It was not executed by this check."
+	});
+	return {
+		status: errors.length ? "failed" : "passed",
+		target,
+		errors,
+		warnings
+	};
+}
+//#endregion
+//#region src/commands/deploy-check.command.ts
+const exec = promisify(execFile);
+const MAX_INPUT_BYTES = 1048576;
+async function readInput(path) {
+	const file = await open(path, "r");
+	try {
+		if (!(await file.stat()).isFile()) throw new Error("Input must be a regular file.");
+		const buffer = Buffer.alloc(1048577);
+		let length = 0;
+		while (length < buffer.length) {
+			const { bytesRead } = await file.read(buffer, length, buffer.length - length, length);
+			if (bytesRead === 0) break;
+			length += bytesRead;
+		}
+		if (length > MAX_INPUT_BYTES) throw new Error("Deployment inputs must not exceed 1 MiB.");
+		return buffer.subarray(0, length).toString("utf8");
+	} finally {
+		await file.close();
+	}
+}
+async function gitProvenance(cwd) {
+	try {
+		const options = {
+			cwd,
+			timeout: 5e3,
+			maxBuffer: 1048576
+		};
+		const [head, status] = await Promise.all([exec("git", [
+			"rev-parse",
+			"--verify",
+			"HEAD"
+		], options), exec("git", [
+			"--no-optional-locks",
+			"-c",
+			"core.fsmonitor=false",
+			"status",
+			"--porcelain=v1",
+			"--untracked-files=normal"
+		], options)]);
+		const commit = head.stdout.trim();
+		if (!/^[a-f0-9]{40,64}$/u.test(commit)) throw new Error("Invalid git commit.");
+		return {
+			commit,
+			dirty: status.stdout.length > 0
+		};
+	} catch {
+		return {
+			commit: null,
+			dirty: null
+		};
+	}
+}
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+/** Static application deployment preflight; never invokes Wrangler or application code. */
+var DeployCheckCommand = class extends Command {
+	static paths = [["deploy", "check"]];
+	static usage = Command.Usage({
+		category: "Deployment",
+		description: "Check an explicit Wrangler target against a saved entrypoint snapshot.",
+		details: "Read-only: no app bootstrap, custom build, credential loading or upload. Compares cron/queue dispatch keys and WebSocket Durable Object bindings. Wrangler remains the deployment tool.",
+		examples: [["Check staging", "vela deploy check --config wrangler.jsonc --env staging --entrypoints entrypoints.json"]]
+	});
+	config = Option.String("--config", {
+		required: true,
+		description: "Explicit Wrangler .json/.jsonc/.toml file."
+	});
+	environment = Option.String("--env", {
+		required: true,
+		description: "Exact named environment in the Wrangler file."
+	});
+	entrypoints = Option.String("--entrypoints", {
+		required: true,
+		description: "Saved vela entrypoint list --json array."
+	});
+	json = Option.Boolean("--json", false, { description: "Emit the redacted report as JSON." });
+	async execute() {
+		try {
+			if (!this.config.trim() || !this.entrypoints.trim()) throw new Error("Explicit configuration and snapshot paths are required.");
+			const configPath = resolve(this.config);
+			const snapshotPath = resolve(this.entrypoints);
+			const [config, snapshot] = await Promise.all([readInput(configPath), readInput(snapshotPath)]);
+			let rows;
+			try {
+				rows = JSON.parse(snapshot);
+			} catch {
+				throw new Error("Invalid entrypoint snapshot JSON.");
+			}
+			const plan = checkDeployment(parseDeploymentConfig(config, configPath), this.environment, rows);
+			const provenance = {
+				...await gitProvenance(dirname(configPath)),
+				checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				config: {
+					path: configPath,
+					sha256: digest(config)
+				},
+				entrypoints: {
+					path: snapshotPath,
+					sha256: digest(snapshot)
+				}
+			};
+			const wrangler = {
+				command: "pnpm",
+				args: [
+					"exec",
+					"wrangler",
+					"deploy",
+					"--config",
+					configPath,
+					"--env",
+					this.environment,
+					"--dry-run"
+				]
+			};
+			const result = {
+				...plan,
+				provenance,
+				nextStep: wrangler
+			};
+			if (this.json) this.context.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			else {
+				this.context.stdout.write(`Deployment check: ${plan.status}\nWorker: ${plan.target.worker}\nEnvironment: ${plan.target.environment}\nConfig: ${configPath}\nCommit: ${provenance.commit ?? "unavailable"} (${provenance.dirty === null ? "cleanliness unknown" : provenance.dirty ? "dirty" : "clean"})\nConfig SHA-256: ${provenance.config.sha256}\nSnapshot SHA-256: ${provenance.entrypoints.sha256}\nBindings: ${plan.target.bindings.map((binding) => `${binding.name} (${binding.kind})`).join(", ") || "(none)"}\n`);
+				for (const issue of plan.errors) this.context.stdout.write(`Error [${issue.code}]: ${issue.message}\n`);
+				for (const issue of plan.warnings) this.context.stdout.write(`Warning [${issue.code}]: ${issue.message}\n`);
+				this.context.stdout.write(`Next step (not executed): ${[wrangler.command, ...wrangler.args].map((arg) => `'${arg.replaceAll("'", "'\\''")}'`).join(" ")}\n`);
+			}
+			return plan.status === "passed" ? 0 : 1;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Deployment check failed.";
+			if (this.json) this.context.stdout.write(`${JSON.stringify({
+				status: "failed",
+				error: message
+			})}\n`);
+			else this.context.stderr.write(`${message}\n`);
+			return 1;
+		}
+	}
+};
+//#endregion
 //#region src/index.ts
 const cli = new Cli({
 	binaryName: "vela",
@@ -724,8 +1165,10 @@ cli.register(OpenApiDumpCommand);
 cli.register(McpServeCommand);
 cli.register(StudioCommand);
 cli.register(ClientGenerateCommand);
+cli.register(DoctorCommand);
+cli.register(DeployCheckCommand);
 cli.runExit(process.argv.slice(2));
 //#endregion
-export { ClientGenerateCommand, EntrypointListCommand, McpServeCommand, ModuleGraphCommand, NewCommand, OpenApiDumpCommand, RouteListCommand, SeedCommand, StudioCommand, collectEntrypoints, collectModules, collectRoutes, defineVelaConfig, formatSeedResults, generateClientContract, loadConfig, renderModuleTree, renderTable };
+export { ClientGenerateCommand, DeployCheckCommand, DoctorCommand, EntrypointListCommand, McpServeCommand, ModuleGraphCommand, NewCommand, OpenApiDumpCommand, RouteListCommand, SeedCommand, StudioCommand, collectEntrypoints, collectModules, collectRoutes, defineVelaConfig, formatSeedResults, generateClientContract, loadConfig, renderModuleTree, renderTable, resolveConfig };
 
 //# sourceMappingURL=index.js.map