@moku-labs/worker 0.3.0 → 0.4.0

package/dist/cli.cjs

@@ -28,6 +28,169 @@ let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_fs = require("node:fs");
+//#region src/plugins/deploy/infra/cloudflare.ts
+/**
+* @file deploy plugin — Cloudflare REST discovery client (infra preflight).
+*
+* Lists what already exists in a Cloudflare account so the deploy pipeline can create only the
+* missing resources (idempotent provisioning) and recover real ids for existing kv/d1 bindings.
+* Authenticated with the `.env` API token (CLOUDFLARE_API_TOKEN) — never an interactive login.
+* Uses the global `fetch`; node-only, never imported by the runtime Worker bundle.
+*/
+const API_BASE = "https://api.cloudflare.com/client/v4";
+/**
+* GET a Cloudflare API path with the bearer token and unwrap the `result`.
+*
+* @param token - The Cloudflare API token (CLOUDFLARE_API_TOKEN).
+* @param path - API path beneath the v4 base (e.g. "/accounts").
+* @returns The unwrapped `result` payload, typed by the caller.
+* @throws {Error} When the HTTP request fails or the API reports `success: false`.
+* @example
+* ```ts
+* const accounts = await cfGet<Array<{ id: string }>>(token, "/accounts");
+* ```
+*/
+const cfGet = async (token, path) => {
+	const response = await fetch(`${API_BASE}${path}`, { headers: {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json"
+	} });
+	const body = await response.json();
+	if (!response.ok || !body.success) {
+		const detail = body.errors?.map((error) => error.message).join("; ") || `HTTP ${response.status}`;
+		throw new Error(`[moku-worker] Cloudflare API request failed (${path}): ${detail}`);
+	}
+	return body.result;
+};
+/**
+* Resolve the Cloudflare account (id + display name) accessible to the token. Used when the
+* consumer did not pin CLOUDFLARE_ACCOUNT_ID; the first accessible account is chosen.
+*
+* @param token - The Cloudflare API token.
+* @returns The resolved account id and name.
+* @throws {Error} When the token can access no account.
+* @example
+* ```ts
+* const { id, name } = await resolveAccount(token);
+* ```
+*/
+const resolveAccount = async (token) => {
+	const first = (await cfGet(token, "/accounts"))[0];
+	if (!first) throw new Error("[moku-worker] No Cloudflare account is accessible with this API token.");
+	return {
+		id: first.id,
+		name: first.name
+	};
+};
+/**
+* List every kv / d1 / r2 / queue resource that already exists in the account (one request per
+* kind, in parallel), indexed for the preflight diff.
+*
+* @param token - The Cloudflare API token.
+* @param accountId - The Cloudflare account id to scope the listings to.
+* @returns The existing resources, indexed by kind.
+* @throws {Error} When any listing request fails.
+* @example
+* ```ts
+* const existing = await listExisting(token, accountId);
+* if (existing.kv.has("SESSIONS")) { ... }
+* ```
+*/
+const listExisting = async (token, accountId) => {
+	const base = `/accounts/${accountId}`;
+	const [kv, d1, r2, queues] = await Promise.all([
+		cfGet(token, `${base}/storage/kv/namespaces`),
+		cfGet(token, `${base}/d1/database`),
+		cfGet(token, `${base}/r2/buckets`),
+		cfGet(token, `${base}/queues`)
+	]);
+	return {
+		kv: new Map(kv.map((namespace) => [namespace.title, namespace.id])),
+		d1: new Map(d1.map((database) => [database.name, database.uuid])),
+		r2: new Set((r2.buckets ?? []).map((bucket) => bucket.name)),
+		queue: new Set(queues.map((queue) => queue.queue_name))
+	};
+};
+//#endregion
+//#region src/plugins/deploy/infra/plan.ts
+/**
+* Decide whether a single declared resource already exists in the account, recovering its id
+* (kv/d1) when it does. Durable Objects are config-only (they ship with the script), so they are
+* always treated as "missing" — provisioning them is a no-op that just records the binding.
+*
+* @param resource - The declared resource descriptor.
+* @param existing - The indexed set of resources already in the account.
+* @returns Whether it exists, plus the captured id for kv/d1.
+* @example
+* ```ts
+* checkExisting({ kind: "kv", binding: "SESSIONS" }, existing); // { exists: true, id: "ns123" }
+* ```
+*/
+const checkExisting = (resource, existing) => {
+	switch (resource.kind) {
+		case "kv": {
+			const id = existing.kv.get(resource.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "d1": {
+			const id = existing.d1.get(resource.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "r2": return { exists: existing.r2.has(resource.bucket) };
+		case "queue": return { exists: resource.producers.every((producer) => existing.queue.has(producer)) };
+		case "do": return { exists: false };
+	}
+};
+/**
+* Run the read-only infra preflight: resolve the account, list existing resources, diff against
+* the manifest, emit `provision:plan`, and return the plan. Writes nothing.
+*
+* @param ctx - The deploy plugin context (env + emit).
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @returns The infra plan: existing (with ids) vs missing resources.
+* @throws {Error} When the token is absent/invalid or a Cloudflare listing fails.
+* @example
+* ```ts
+* const plan = await planInfra(ctx, manifest);
+* ```
+*/
+const planInfra = async (ctx, manifest) => {
+	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
+	const pinnedAccountId = ctx.env.get("CLOUDFLARE_ACCOUNT_ID");
+	const account = pinnedAccountId ? {
+		id: pinnedAccountId,
+		name: pinnedAccountId
+	} : await resolveAccount(token);
+	const existing = await listExisting(token, account.id);
+	const exists = [];
+	const missing = [];
+	for (const resource of manifest.resources) {
+		const check = checkExisting(resource, existing);
+		if (check.exists) exists.push(check.id === void 0 ? { resource } : {
+			resource,
+			id: check.id
+		});
+		else missing.push(resource);
+	}
+	ctx.emit("provision:plan", {
+		exists: exists.length,
+		missing: missing.length,
+		account: account.name
+	});
+	return {
+		account: account.name,
+		accountId: account.id,
+		exists,
+		missing
+	};
+};
+//#endregion
 //#region src/plugins/deploy/runner.ts
 /**
 * @file deploy plugin — wrangler subprocess wrapper (node:child_process).
@@ -101,26 +264,43 @@ const runWrangler = (args) => new Promise((resolve, reject) => {
 /**
 * @file deploy plugin — D1 provisioning adapter.
 *
-* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`.
+* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`, captures the created
+* database id from wrangler's output (so writeWranglerConfig can write a real `database_id`
+* instead of an empty placeholder), and applies migrations when declared.
 * Node-only; never imported by the runtime Worker bundle.
 */
 /**
-* Provision a D1 database via `wrangler d1 create` and apply migrations.
+* Parse the created D1 database id from `wrangler d1 create` output.
+* Wrangler prints the new binding as JSON (`"database_id": "..."`) or TOML
+* (`database_id = "..."`); the leading boundary keeps the match anchored to the field name.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The database id, or undefined when none is found.
+* @example
+* ```ts
+* parseD1DatabaseId('{ "database_id": "uuid-1234" }'); // "uuid-1234"
+* ```
+*/
+const parseD1DatabaseId = (output) => {
+	return /(?:^|[\s,{])"?database_id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
+/**
+* Provision a D1 database via `wrangler d1 create`, capture its id, and apply migrations.
 *
 * @param manifest - The D1 resource descriptor.
 * @param _ci - Whether running non-interactively.
-* @returns Resolves once the database is created (and migrations applied when specified).
+* @returns The captured database id when wrangler reported one, else an empty outcome.
 * @example
 * ```ts
-* await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
+* const { id } = await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
 * ```
 */
 const provisionD1 = async (manifest, _ci) => {
-	await runWrangler([
+	const id = parseD1DatabaseId(await runWrangler([
 		"d1",
 		"create",
 		manifest.binding
-	]);
+	]));
 	if (manifest.migrations) await runWrangler([
 		"d1",
 		"migrations",
@@ -128,6 +308,7 @@ const provisionD1 = async (manifest, _ci) => {
 		manifest.binding,
 		"--local"
 	]);
+	return id ? { id } : {};
 };
 //#endregion
 //#region src/plugins/deploy/providers/do.ts
@@ -150,27 +331,46 @@ const provisionDurableObject = async (_manifest, _ci) => {};
 /**
 * @file deploy plugin — KV provisioning adapter.
 *
-* Creates a Cloudflare KV namespace via `wrangler kv namespace create <binding>`.
-* Node-only; never imported by the runtime Worker bundle.
+* Creates a Cloudflare KV namespace via `wrangler kv namespace create <binding>` and captures
+* the created namespace id from wrangler's output, so writeWranglerConfig can write a real `id`
+* (not an empty placeholder) into the generated wrangler config — otherwise the binding resolves
+* to nothing at runtime. Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Parse the created KV namespace id from `wrangler kv namespace create` output.
+* Wrangler prints the new binding as JSON (`"id": "..."`) or TOML (`id = "..."`); the leading
+* boundary (start / whitespace / `{` / `,`) keeps the match off a longer identifier such as
+* `kv_namespace_id`.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The namespace id, or undefined when none is found.
+* @example
+* ```ts
+* parseKvNamespaceId('{ "id": "abc123" }'); // "abc123"
+* ```
 */
+const parseKvNamespaceId = (output) => {
+	return /(?:^|[\s,{])"?id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
 /**
-* Provision a KV namespace via `wrangler kv namespace create`.
+* Provision a KV namespace via `wrangler kv namespace create` and capture its id.
 *
 * @param manifest - The KV resource descriptor.
 * @param _ci - Whether running non-interactively (passed through; wrangler respects env vars).
-* @returns Resolves once the namespace is created.
+* @returns The captured namespace id when wrangler reported one, else an empty outcome.
 * @example
 * ```ts
-* await provisionKv({ kind: "kv", binding: "CACHE" }, false);
+* const { id } = await provisionKv({ kind: "kv", binding: "CACHE" }, false);
 * ```
 */
 const provisionKv = async (manifest, _ci) => {
-	await runWrangler([
+	const id = parseKvNamespaceId(await runWrangler([
 		"kv",
 		"namespace",
 		"create",
 		manifest.binding
-	]);
+	]));
+	return id ? { id } : {};
 };
 //#endregion
 //#region src/plugins/deploy/providers/queues.ts
@@ -282,30 +482,26 @@ const uploadDirToR2 = async (bucket, directory) => {
 *
 * @param resource - The resource descriptor to provision.
 * @param ci - Whether running non-interactively.
-* @returns Resolves once the resource is provisioned.
+* @returns The provisioning outcome — `{ id }` for kv/d1, `{}` for r2/queue/do.
 * @example
 * ```ts
-* await provisionResource({ kind: "kv", binding: "CACHE" }, false);
-* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false);
+* const { id } = await provisionResource({ kind: "kv", binding: "CACHE" }, false);
+* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false); // {}
 * ```
 */
 const provisionResource = async (resource, ci) => {
 	switch (resource.kind) {
-		case "kv":
-			await provisionKv(resource, ci);
-			break;
+		case "kv": return provisionKv(resource, ci);
+		case "d1": return provisionD1(resource, ci);
 		case "r2":
 			await provisionR2(resource, ci);
-			break;
-		case "d1":
-			await provisionD1(resource, ci);
-			break;
+			return {};
 		case "queue":
 			await provisionQueue(resource, ci);
-			break;
+			return {};
 		case "do":
 			await provisionDurableObject(resource, ci);
-			break;
+			return {};
 	}
 };
 //#endregion
@@ -339,15 +535,16 @@ const parseJsonc = (source) => {
 * Build the wrangler `kv_namespaces` array from the manifest's kv resources.
 *
 * @param resources - All resource descriptors from the manifest.
-* @returns One wrangler KV namespace entry per kv resource.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `id` is filled from here.
+* @returns One wrangler KV namespace entry per kv resource (real `id` when known, else "").
 * @example
 * ```ts
-* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }]);
+* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
 * ```
 */
-const buildKvNamespaces = (resources) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
 	binding: resource.binding,
-	id: ""
+	id: ids[resource.binding] ?? ""
 }));
 /**
 * Build the wrangler `r2_buckets` array from the manifest's r2 resources.
@@ -367,17 +564,18 @@ const buildR2Buckets = (resources) => resources.filter((resource) => resource.ki
 * Build the wrangler `d1_databases` array from the manifest's d1 resources.
 *
 * @param resources - All resource descriptors from the manifest.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `database_id` is filled from here.
 * @returns One wrangler D1 database entry per d1 resource (migrations_dir set when present).
 * @example
 * ```ts
-* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }]);
+* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }], { DB: "uuid-1234" });
 * ```
 */
-const buildD1Databases = (resources) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
 	const entry = {
 		binding: resource.binding,
 		database_name: resource.binding.toLowerCase(),
-		database_id: ""
+		database_id: ids[resource.binding] ?? ""
 	};
 	if (resource.migrations) entry.migrations_dir = resource.migrations;
 	return entry;
@@ -426,22 +624,24 @@ const buildDurableObjects = (resources) => {
 *
 * @param configFile - Path to the wrangler config file.
 * @param manifest - The assembled deploy manifest.
+* @param ids - Captured Cloudflare ids keyed by binding (kv namespace id, d1 database id). Defaults
+*   to an empty map, in which case `id`/`database_id` are written as "" (e.g. the universal path).
 * @returns Resolves once the file is written.
 * @example
 * ```ts
-* await writeWranglerConfig("wrangler.jsonc", manifest);
+* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123", DB: "uuid-1234" });
 * ```
 */
-const writeWranglerConfig = async (configFile, manifest) => {
+const writeWranglerConfig = async (configFile, manifest, ids = {}) => {
 	let existing = {};
 	if ((0, node_fs.existsSync)(configFile)) try {
 		existing = parseJsonc((0, node_fs.readFileSync)(configFile, "utf8"));
 	} catch {
 		existing = {};
 	}
-	const kvNamespaces = buildKvNamespaces(manifest.resources);
+	const kvNamespaces = buildKvNamespaces(manifest.resources, ids);
 	const r2Buckets = buildR2Buckets(manifest.resources);
-	const d1Databases = buildD1Databases(manifest.resources);
+	const d1Databases = buildD1Databases(manifest.resources, ids);
 	const queues = buildQueues(manifest.resources);
 	const durableObjects = buildDurableObjects(manifest.resources);
 	const updated = {
@@ -480,21 +680,22 @@ const scaffoldWranglerAndCi = async (configFile, _ci) => {
 //#endregion
 //#region src/plugins/deploy/api.ts
 /**
-* @file deploy plugin — API factory (run, dev, init).
+* @file deploy plugin — API factory (run, dev, init, checkInfra, provisionInfra).
 *
 * Pure ctx-taking factory. Assembles the deploy manifest from each resource plugin's own
-* deployManifest() api (never sibling pluginConfigs — design F6), provisions resources,
-* generates/updates the wrangler config, uploads the R2 upload dir, and runs wrangler deploy.
-* Emits only global events: deploy:phase, deploy:complete, provision:resource.
+* deployManifest() api (never sibling pluginConfigs — design F6), runs an infra preflight
+* (check-before-create + capture real ids), generates/updates the wrangler config, uploads the
+* R2 upload dir, and runs wrangler deploy. Emits only global events: deploy:phase,
+* deploy:complete, provision:resource, provision:plan, provision:skip.
 *
-* Node-only: uses node:child_process (via runner.ts) and node:fs (via wrangler-config.ts).
-* Never called in the deployed Worker runtime.
+* Node-only: uses node:child_process (via runner.ts), node:fs (via wrangler-config.ts), and the
+* Cloudflare REST API (via infra/). Never called in the deployed Worker runtime.
 */
 /**
-* Derive a human-readable name string from a resource descriptor (used in provision:resource).
+* Derive a human-readable name string from a resource descriptor (used in provision events).
 *
 * @param resource - The resource descriptor.
-* @returns A name suitable for the provision:resource event payload.
+* @returns A name suitable for the provision:resource / provision:skip event payload.
 * @example
 * ```ts
 * resourceName({ kind: "kv", binding: "CACHE" }); // "CACHE"
@@ -509,12 +710,74 @@ const resourceName = (resource) => {
 	}
 };
 /**
-* Create the deploy api. Assembles the manifest from each resource plugin's own
-* deployManifest() (never sibling config), provisions, generates config, uploads,
-* and runs `wrangler deploy`, emitting global deploy events along the way.
+* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api,
+* gated by ctx.has(name) so absent plugins are skipped — never sibling pluginConfigs (F6).
+*
+* @param ctx - The deploy plugin context.
+* @returns The assembled manifest (name, compatibilityDate, resources).
+* @example
+* ```ts
+* const manifest = assembleManifest(ctx);
+* ```
+*/
+const assembleManifest = (ctx) => ({
+	name: ctx.global.name,
+	compatibilityDate: ctx.global.compatibilityDate,
+	resources: [
+		ctx.has("storage") ? ctx.require(require_storage.storagePlugin).deployManifest() : void 0,
+		ctx.has("kv") ? ctx.require(require_storage.kvPlugin).deployManifest() : void 0,
+		ctx.has("d1") ? ctx.require(require_storage.d1Plugin).deployManifest() : void 0,
+		ctx.has("queues") ? ctx.require(require_storage.queuesPlugin).deployManifest() : void 0,
+		ctx.has("durableObjects") ? ctx.require(require_storage.durableObjectsPlugin).deployManifest() : void 0
+	].filter((resource) => resource !== void 0)
+});
+/**
+* Act on an infra plan: skip the resources that already exist (reusing their ids), create only
+* the missing ones (capturing each new id), and announce each via provision:skip / :resource.
+*
+* @param ctx - The deploy plugin context.
+* @param plan - The infra plan from planInfra (existing vs missing).
+* @returns The provisioning result: created, skipped, and the merged binding → id map.
+* @example
+* ```ts
+* const { ids } = await applyPlan(ctx, plan);
+* ```
+*/
+const applyPlan = async (ctx, plan) => {
+	const ids = {};
+	for (const ref of plan.exists) {
+		if (ref.id !== void 0 && (ref.resource.kind === "kv" || ref.resource.kind === "d1")) ids[ref.resource.binding] = ref.id;
+		ctx.emit("provision:skip", {
+			kind: ref.resource.kind,
+			name: resourceName(ref.resource)
+		});
+	}
+	const created = [];
+	for (const resource of plan.missing) {
+		const { id } = await provisionResource(resource, ctx.config.ci);
+		if (id !== void 0 && (resource.kind === "kv" || resource.kind === "d1")) ids[resource.binding] = id;
+		created.push(id === void 0 ? { resource } : {
+			resource,
+			id
+		});
+		ctx.emit("provision:resource", {
+			kind: resource.kind,
+			name: resourceName(resource)
+		});
+	}
+	return {
+		created,
+		skipped: plan.exists,
+		ids
+	};
+};
+/**
+* Create the deploy api. Assembles the manifest from each resource plugin's own deployManifest(),
+* runs an infra preflight (check-before-create + id capture), generates config, uploads, and runs
+* `wrangler deploy`, emitting global deploy events along the way.
 *
-* @param ctx - Plugin context (own config + require + has + emit + global).
-* @returns The app.deploy api: run / dev / init.
+* @param ctx - Plugin context (own config + require + has + emit + global + env).
+* @returns The app.deploy api: run / dev / init / checkInfra / provisionInfra.
 * @example
 * ```ts
 * const api = createDeployApi(ctx);
@@ -523,12 +786,13 @@ const resourceName = (resource) => {
 */
 const createDeployApi = (ctx) => ({
 	/**
-	* Run the full deploy pipeline: detect → provision → wrangler-config → upload → deploy.
-	* When opts.manifest is supplied, it is used verbatim (universal path).
+	* Run the full deploy pipeline: detect → preflight (check-before-create) → provision (only the
+	* missing) → wrangler-config (with real ids) → upload → deploy. When opts.manifest is supplied
+	* it is used verbatim (universal path).
 	*
 	* @param opts - Optional run options.
-	* @param opts.guided - Enable interactive confirmation steps (skipped when ci=true).
-	* @param opts.yes - Auto-confirm all prompts.
+	* @param opts.guided - Enable interactive confirmation steps (wired in a later phase).
+	* @param opts.yes - Auto-confirm all prompts (wired in a later phase).
 	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
 	* @returns Resolves once the deploy completes.
 	* @example
@@ -539,27 +803,11 @@ const createDeployApi = (ctx) => ({
 	*/
 	async run(opts) {
 		ctx.emit("deploy:phase", { phase: "detect" });
-		const manifest = opts?.manifest ?? {
-			name: ctx.global.name,
-			compatibilityDate: ctx.global.compatibilityDate,
-			resources: [
-				ctx.has("storage") ? ctx.require(require_storage.storagePlugin).deployManifest() : void 0,
-				ctx.has("kv") ? ctx.require(require_storage.kvPlugin).deployManifest() : void 0,
-				ctx.has("d1") ? ctx.require(require_storage.d1Plugin).deployManifest() : void 0,
-				ctx.has("queues") ? ctx.require(require_storage.queuesPlugin).deployManifest() : void 0,
-				ctx.has("durableObjects") ? ctx.require(require_storage.durableObjectsPlugin).deployManifest() : void 0
-			].filter((resource) => resource !== void 0)
-		};
+		const manifest = opts?.manifest ?? assembleManifest(ctx);
 		ctx.emit("deploy:phase", { phase: "provision" });
-		for (const resource of manifest.resources) {
-			await provisionResource(resource, ctx.config.ci);
-			ctx.emit("provision:resource", {
-				kind: resource.kind,
-				name: resourceName(resource)
-			});
-		}
+		const { ids } = await applyPlan(ctx, await planInfra(ctx, manifest));
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
-		await writeWranglerConfig(ctx.config.configFile, manifest);
+		await writeWranglerConfig(ctx.config.configFile, manifest, ids);
 		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
 		if (r2Resource?.upload) {
 			const count = await uploadDirToR2(r2Resource.bucket, r2Resource.upload);
@@ -610,7 +858,29 @@ const createDeployApi = (ctx) => ({
 	*/
 	init: async (opts) => {
 		await scaffoldWranglerAndCi(ctx.config.configFile, opts?.ci ?? ctx.config.ci);
-	}
+	},
+	/**
+	* Read-only infra preflight: assemble the manifest, resolve the account, list what exists in
+	* Cloudflare, diff, emit provision:plan, and return the plan. Writes nothing.
+	*
+	* @returns The infra plan (existing vs missing resources, with captured ids).
+	* @example
+	* ```ts
+	* const plan = await api.checkInfra();
+	* ```
+	*/
+	checkInfra: () => planInfra(ctx, assembleManifest(ctx)),
+	/**
+	* Create only the resources missing from the plan (skipping existing), capturing each id.
+	*
+	* @param plan - A plan produced by checkInfra().
+	* @returns The provisioning result: created, skipped, and the merged id map.
+	* @example
+	* ```ts
+	* const { created } = await api.provisionInfra(await api.checkInfra());
+	* ```
+	*/
+	provisionInfra: (plan) => applyPlan(ctx, plan)
 });
 /**
 * Complex tier (node-only) — build-time deploy orchestrator over the five resource plugins.
@@ -723,6 +993,18 @@ const createCliHooks = (ctx) => ({
 		ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
 	},
 	/**
+	* Log the infra preflight summary: "infra · N exist, M to create · account".
+	*
+	* @param p - The provision:plan event payload.
+	* @example
+	* ```ts
+	* handler({ exists: 2, missing: 1, account: "Play Co" }); // "infra · 2 exist, 1 to create · Play Co"
+	* ```
+	*/
+	"provision:plan"(p) {
+		ctx.log.info(`infra · ${p.exists} exist, ${p.missing} to create · ${p.account}`);
+	},
+	/**
 	* Log one clean line per provisioned resource: "kind name".
 	*
 	* @param p - The provision:resource event payload.
@@ -735,6 +1017,18 @@ const createCliHooks = (ctx) => ({
 		ctx.log.info(`${p.kind} ${p.name}`);
 	},
 	/**
+	* Log one clean line per already-existing resource (skipped): "kind name (exists)".
+	*
+	* @param p - The provision:skip event payload.
+	* @example
+	* ```ts
+	* handler({ kind: "kv", name: "KV" }); // "kv KV (exists)"
+	* ```
+	*/
+	"provision:skip"(p) {
+		ctx.log.info(`${p.kind} ${p.name} (exists)`);
+	},
+	/**
 	* Log the terminal success line with the deployed URL.
 	*
 	* @param p - The deploy:complete event payload.

package/dist/cli.d.cts

@@ -111,6 +111,33 @@ type ExternalManifest = {
   compatibilityDate: string; /** Resource descriptors to provision. */
   resources: ResourceManifest[];
 };
+/**
+ * A resource that already exists in the account (the infra preflight discovered it), with its
+ * captured Cloudflare id when the kind has one (kv namespace id, d1 database id).
+ */
+type ProvisionedRef = {
+  /** The resource descriptor from the manifest. */resource: ResourceManifest; /** The existing resource's Cloudflare id (kv/d1 only). */
+  id?: string;
+};
+/**
+ * Read-only infra preflight result: which declared resources already exist in the Cloudflare
+ * account versus which are still missing and must be created. Produced by `checkInfra()`.
+ */
+type InfraPlan = {
+  /** Resolved account display name (or id when the name is unknown). */account: string; /** Resolved Cloudflare account id used for the existence checks. */
+  accountId: string; /** Declared resources that already exist (with their captured ids where applicable). */
+  exists: ProvisionedRef[]; /** Declared resources that do not yet exist and must be created. */
+  missing: ResourceManifest[];
+};
+/**
+ * Outcome of acting on an {@link InfraPlan}: the resources just created, those skipped because
+ * they already existed, and the merged id map (binding → Cloudflare id) for the config writer.
+ */
+type ProvisionResult = {
+  /** Resources created during this run. */created: ProvisionedRef[]; /** Resources skipped because they already existed. */
+  skipped: ProvisionedRef[]; /** Merged binding → Cloudflare id map (existing + created) for writeWranglerConfig. */
+  ids: Record<string, string>;
+};
 //#endregion
 //#region src/plugins/deploy/index.d.ts
 /**
@@ -137,6 +164,8 @@ declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", C
   init: (opts?: {
     ci?: boolean;
   }) => Promise<void>;
+  checkInfra: () => Promise<InfraPlan>;
+  provisionInfra: (plan: InfraPlan) => Promise<ProvisionResult>;
 }, {}> & Record<never, never>;
 //#endregion
 export { type ExternalManifest, type ResourceManifest, cliPlugin, deployPlugin };