@moku-labs/worker 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,743 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_storage = require("./storage-BaQ6BBtl.cjs");
+let node_child_process = require("node:child_process");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+node_path = require_storage.__toESM(node_path, 1);
+let node_fs = require("node:fs");
+//#region src/plugins/deploy/runner.ts
+/**
+* @file deploy plugin — wrangler subprocess wrapper (node:child_process).
+*
+* Spawns `wrangler` with the given args and resolves the deployed URL
+* (extracted from stdout for `wrangler deploy`), or the full stdout for other verbs.
+* This module is node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Extract the deployed URL from `wrangler deploy` stdout.
+* Wrangler prints a line like: "Published my-worker (1.23 sec)  https://..."
+* or "Deployed my-worker (1.23 sec) https://...".
+*
+* @param output - The combined stdout from wrangler deploy.
+* @returns The deployed URL, or empty string when not found.
+* @example
+* ```ts
+* extractDeployedUrl("Deployed my-worker (0.5 sec) https://my-worker.workers.dev");
+* // "https://my-worker.workers.dev"
+* ```
+*/
+const extractDeployedUrl = (output) => {
+	return /https:\/\/[^\s]+\.workers\.dev[^\s]*/u.exec(output)?.[0] ?? "";
+};
+/**
+* Spawn `wrangler` with the given args and resolve the output string.
+* For `wrangler deploy`, the resolved value is the deployed URL parsed from stdout.
+* For all other verbs (dev, kv namespace create, etc.), the resolved value is stdout.
+*
+* @param args - Wrangler CLI arguments (e.g. ["deploy", "--config", "wrangler.jsonc"]).
+* @returns Resolves with the deployed URL (deploy verb) or full stdout (other verbs).
+* @throws {Error} When wrangler exits with a non-zero code.
+* @example
+* ```ts
+* const url = await runWrangler(["deploy", "--config", "wrangler.jsonc"]);
+* await runWrangler(["kv", "namespace", "create", "CACHE"]);
+* ```
+*/
+const runWrangler = (args) => new Promise((resolve, reject) => {
+	const chunks = [];
+	const errChunks = [];
+	const child = (0, node_child_process.spawn)("wrangler", args, {
+		env: { ...process.env },
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	child.stdout.on("data", (chunk) => {
+		chunks.push(chunk);
+	});
+	child.stderr.on("data", (chunk) => {
+		errChunks.push(chunk);
+	});
+	child.on("error", (err) => {
+		reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${err.message}`));
+	});
+	child.on("close", (code) => {
+		const stdout = Buffer.concat(chunks).toString("utf8");
+		const stderr = Buffer.concat(errChunks).toString("utf8");
+		if (code !== 0) {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.\n  ${stderr || stdout}`));
+			return;
+		}
+		resolve(args[0] === "deploy" ? extractDeployedUrl(stdout) : stdout);
+	});
+});
+//#endregion
+//#region src/plugins/deploy/providers/d1.ts
+/**
+* @file deploy plugin — D1 provisioning adapter.
+*
+* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision a D1 database via `wrangler d1 create` 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).
+* @example
+* ```ts
+* await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
+* ```
+*/
+const provisionD1 = async (manifest, _ci) => {
+	await runWrangler([
+		"d1",
+		"create",
+		manifest.binding
+	]);
+	if (manifest.migrations) await runWrangler([
+		"d1",
+		"migrations",
+		"apply",
+		manifest.binding,
+		"--local"
+	]);
+};
+//#endregion
+//#region src/plugins/deploy/providers/do.ts
+/**
+* Provision Durable Object bindings. DOs are config-driven (no `wrangler do create` command
+* exists) — the actual binding entries are written by writeWranglerConfig. This function is
+* a resolved no-op for the dispatch step.
+*
+* @param _manifest - The Durable Objects resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves immediately (DOs are config-only provisioning).
+* @example
+* ```ts
+* await provisionDurableObject({ kind: "do", bindings: { counter: "COUNTER" } }, false);
+* ```
+*/
+const provisionDurableObject = async (_manifest, _ci) => {};
+//#endregion
+//#region src/plugins/deploy/providers/kv.ts
+/**
+* @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.
+*/
+/**
+* Provision a KV namespace via `wrangler kv namespace create`.
+*
+* @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.
+* @example
+* ```ts
+* await provisionKv({ kind: "kv", binding: "CACHE" }, false);
+* ```
+*/
+const provisionKv = async (manifest, _ci) => {
+	await runWrangler([
+		"kv",
+		"namespace",
+		"create",
+		manifest.binding
+	]);
+};
+//#endregion
+//#region src/plugins/deploy/providers/queues.ts
+/**
+* @file deploy plugin — Queues provisioning adapter.
+*
+* Creates Cloudflare Queues via `wrangler queues create <name>` for each producer.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision queues via `wrangler queues create` for each declared producer.
+*
+* @param manifest - The queue resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves once all queues are created.
+* @example
+* ```ts
+* await provisionQueue({ kind: "queue", producers: ["orders"] }, false);
+* ```
+*/
+const provisionQueue = async (manifest, _ci) => {
+	for (const producer of manifest.producers) await runWrangler([
+		"queues",
+		"create",
+		producer
+	]);
+};
+//#endregion
+//#region src/plugins/deploy/providers/r2.ts
+/**
+* @file deploy plugin — R2 provisioning + asset upload adapter.
+*
+* Provides two exports:
+* - `provisionR2`: creates an R2 bucket via `wrangler r2 bucket create`.
+* - `uploadDirToR2`: walks a directory recursively and uploads each file via
+*   `wrangler r2 object put`, returning the uploaded file count.
+*
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision an R2 bucket via `wrangler r2 bucket create`.
+*
+* @param manifest - The R2 resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves once the bucket is created.
+* @example
+* ```ts
+* await provisionR2({ kind: "r2", bucket: "ASSETS" }, false);
+* ```
+*/
+const provisionR2 = async (manifest, _ci) => {
+	await runWrangler([
+		"r2",
+		"bucket",
+		"create",
+		manifest.bucket
+	]);
+};
+/**
+* Walk a directory recursively and return all file paths (absolute).
+*
+* @param directory - Directory path to walk.
+* @returns All file paths found under the directory.
+* @example
+* ```ts
+* const files = await walkDir("./public");
+* ```
+*/
+const walkDir = async (directory) => {
+	const entries = await (0, node_fs_promises.readdir)(directory);
+	const results = [];
+	for (const entry of entries) {
+		const fullPath = node_path.default.join(directory, entry);
+		if ((await (0, node_fs_promises.stat)(fullPath)).isDirectory()) {
+			const nested = await walkDir(fullPath);
+			results.push(...nested);
+		} else results.push(fullPath);
+	}
+	return results;
+};
+/**
+* Upload a directory to an R2 bucket and return the uploaded file count.
+* Each file is uploaded via `wrangler r2 object put <bucket>/<key> --file <path>`.
+*
+* @param bucket - The R2 bucket binding name.
+* @param directory - The directory to upload.
+* @returns The number of files uploaded.
+* @example
+* ```ts
+* const count = await uploadDirToR2("ASSETS", "./public");
+* ```
+*/
+const uploadDirToR2 = async (bucket, directory) => {
+	const files = await walkDir(directory);
+	for (const filePath of files) await runWrangler([
+		"r2",
+		"object",
+		"put",
+		`${bucket}/${node_path.default.relative(directory, filePath)}`,
+		"--file",
+		filePath
+	]);
+	return files.length;
+};
+//#endregion
+//#region src/plugins/deploy/providers/index.ts
+/**
+* Dispatch a resource descriptor to the matching provider's provisioning routine.
+*
+* @param resource - The resource descriptor to provision.
+* @param ci - Whether running non-interactively.
+* @returns Resolves once the resource is provisioned.
+* @example
+* ```ts
+* 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 "r2":
+			await provisionR2(resource, ci);
+			break;
+		case "d1":
+			await provisionD1(resource, ci);
+			break;
+		case "queue":
+			await provisionQueue(resource, ci);
+			break;
+		case "do":
+			await provisionDurableObject(resource, ci);
+			break;
+	}
+};
+//#endregion
+//#region src/plugins/deploy/wrangler-config.ts
+/**
+* @file deploy plugin — wrangler config generation + scaffold.
+*
+* Provides two exports:
+* - `writeWranglerConfig`: generates/updates a wrangler.jsonc file from an ExternalManifest.
+*   Non-destructive: preserves existing top-level keys not managed by deploy.
+* - `scaffoldWranglerAndCi`: creates a minimal starter wrangler config when the file does not
+*   exist yet; idempotent (leaves existing files untouched).
+*
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Strip JSONC line- and block-comments, then JSON.parse the result.
+*
+* @param source - Raw JSONC file contents.
+* @returns The parsed object.
+* @example
+* ```ts
+* const cfg = parseJsonc('{ "name": "w" } // trailing comment');
+* ```
+*/
+const parseJsonc = (source) => {
+	const stripped = source.replaceAll(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu, "");
+	return JSON.parse(stripped);
+};
+/**
+* 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.
+* @example
+* ```ts
+* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }]);
+* ```
+*/
+const buildKvNamespaces = (resources) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
+	binding: resource.binding,
+	id: ""
+}));
+/**
+* Build the wrangler `r2_buckets` array from the manifest's r2 resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns One wrangler R2 bucket entry per r2 resource.
+* @example
+* ```ts
+* const r2 = buildR2Buckets([{ kind: "r2", bucket: "ASSETS" }]);
+* ```
+*/
+const buildR2Buckets = (resources) => resources.filter((resource) => resource.kind === "r2").map((resource) => ({
+	binding: resource.bucket,
+	bucket_name: resource.bucket.toLowerCase()
+}));
+/**
+* Build the wrangler `d1_databases` array from the manifest's d1 resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns One wrangler D1 database entry per d1 resource (migrations_dir set when present).
+* @example
+* ```ts
+* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }]);
+* ```
+*/
+const buildD1Databases = (resources) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+	const entry = {
+		binding: resource.binding,
+		database_name: resource.binding.toLowerCase(),
+		database_id: ""
+	};
+	if (resource.migrations) entry.migrations_dir = resource.migrations;
+	return entry;
+});
+/**
+* Build the wrangler `queues` producers section from the manifest's queue resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns The queues section, or undefined when there are no queue resources.
+* @example
+* ```ts
+* const q = buildQueues([{ kind: "queue", producers: ["jobs"] }]);
+* ```
+*/
+const buildQueues = (resources) => {
+	const queueResources = resources.filter((resource) => resource.kind === "queue");
+	if (queueResources.length === 0) return void 0;
+	return { producers: queueResources.flatMap((resource) => resource.producers.map((producer) => ({
+		queue: producer,
+		binding: producer.toUpperCase()
+	}))) };
+};
+/**
+* Build the wrangler `durable_objects` bindings section from the manifest's do resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns The durable_objects section, or undefined when there are no do resources.
+* @example
+* ```ts
+* const dobj = buildDurableObjects([{ kind: "do", bindings: { Counter: "COUNTER" } }]);
+* ```
+*/
+const buildDurableObjects = (resources) => {
+	const doResources = resources.filter((resource) => resource.kind === "do");
+	if (doResources.length === 0) return void 0;
+	return { bindings: doResources.flatMap((resource) => Object.entries(resource.bindings).map(([className, bindingName]) => ({
+		name: bindingName,
+		class_name: className
+	}))) };
+};
+/**
+* Generate/update the wrangler config file from a manifest (non-destructive merge).
+* If the file exists, its top-level keys are preserved and only deploy-managed keys
+* (name, compatibility_date, kv_namespaces, r2_buckets, d1_databases, queues,
+* durable_objects) are updated.
+*
+* @param configFile - Path to the wrangler config file.
+* @param manifest - The assembled deploy manifest.
+* @returns Resolves once the file is written.
+* @example
+* ```ts
+* await writeWranglerConfig("wrangler.jsonc", manifest);
+* ```
+*/
+const writeWranglerConfig = async (configFile, manifest) => {
+	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 r2Buckets = buildR2Buckets(manifest.resources);
+	const d1Databases = buildD1Databases(manifest.resources);
+	const queues = buildQueues(manifest.resources);
+	const durableObjects = buildDurableObjects(manifest.resources);
+	const updated = {
+		...existing,
+		name: manifest.name,
+		compatibility_date: manifest.compatibilityDate
+	};
+	if (kvNamespaces.length > 0) updated.kv_namespaces = kvNamespaces;
+	if (r2Buckets.length > 0) updated.r2_buckets = r2Buckets;
+	if (d1Databases.length > 0) updated.d1_databases = d1Databases;
+	if (queues !== void 0) updated.queues = queues;
+	if (durableObjects !== void 0) updated.durable_objects = durableObjects;
+	await (0, node_fs_promises.writeFile)(configFile, JSON.stringify(updated, void 0, 2));
+};
+/**
+* Scaffold a starting wrangler config and, when ci is set, CI workflow files.
+* Idempotent: an existing config file is left completely untouched.
+*
+* @param configFile - Path to the wrangler config file.
+* @param _ci - Whether to also scaffold CI workflow files.
+* @returns Resolves once scaffolding is written.
+* @example
+* ```ts
+* await scaffoldWranglerAndCi("wrangler.jsonc", true);
+* ```
+*/
+const scaffoldWranglerAndCi = async (configFile, _ci) => {
+	if ((0, node_fs.existsSync)(configFile)) return;
+	const starter = {
+		name: "my-worker",
+		main: "src/worker.ts",
+		compatibility_date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+	};
+	await (0, node_fs_promises.writeFile)(configFile, JSON.stringify(starter, void 0, 2));
+};
+//#endregion
+//#region src/plugins/deploy/api.ts
+/**
+* @file deploy plugin — API factory (run, dev, init).
+*
+* 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.
+*
+* Node-only: uses node:child_process (via runner.ts) and node:fs (via wrangler-config.ts).
+* Never called in the deployed Worker runtime.
+*/
+/**
+* Derive a human-readable name string from a resource descriptor (used in provision:resource).
+*
+* @param resource - The resource descriptor.
+* @returns A name suitable for the provision:resource event payload.
+* @example
+* ```ts
+* resourceName({ kind: "kv", binding: "CACHE" }); // "CACHE"
+* ```
+*/
+const resourceName = (resource) => {
+	switch (resource.kind) {
+		case "r2": return resource.bucket;
+		case "do": return Object.values(resource.bindings).join(",");
+		case "queue": return resource.producers.join(",");
+		default: return resource.binding;
+	}
+};
+/**
+* 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.
+*
+* @param ctx - Plugin context (own config + require + has + emit + global).
+* @returns The app.deploy api: run / dev / init.
+* @example
+* ```ts
+* const api = createDeployApi(ctx);
+* await api.run();
+* ```
+*/
+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).
+	*
+	* @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.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
+	* @returns Resolves once the deploy completes.
+	* @example
+	* ```ts
+	* await api.run({ guided: true });
+	* await api.run({ manifest: { name: "w", compatibilityDate: "2026-06-17", resources: [] } });
+	* ```
+	*/
+	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)
+		};
+		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)
+			});
+		}
+		ctx.emit("deploy:phase", { phase: "wrangler-config" });
+		await writeWranglerConfig(ctx.config.configFile, manifest);
+		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
+		if (r2Resource?.upload) {
+			const count = await uploadDirToR2(r2Resource.bucket, r2Resource.upload);
+			ctx.emit("deploy:phase", {
+				phase: "upload",
+				detail: `${String(count)} files`
+			});
+		}
+		ctx.emit("deploy:phase", { phase: "deploy" });
+		const url = await runWrangler([
+			"deploy",
+			"--config",
+			ctx.config.configFile
+		]);
+		ctx.emit("deploy:complete", { url });
+	},
+	/**
+	* Start a local Cloudflare dev session via `wrangler dev`.
+	*
+	* @param opts - Optional options.
+	* @param opts.port - Local dev port (default 8787).
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev({ port: 8787 });
+	* ```
+	*/
+	dev: async (opts) => {
+		await runWrangler([
+			"dev",
+			"--port",
+			String(opts?.port ?? 8787),
+			"--config",
+			ctx.config.configFile
+		]);
+	},
+	/**
+	* Scaffold a starting wrangler config (and CI files when ci is set).
+	* Idempotent: an existing config file is left untouched.
+	*
+	* @param opts - Optional options.
+	* @param opts.ci - Also scaffold CI workflow files.
+	* @returns Resolves once scaffolding is written.
+	* @example
+	* ```ts
+	* await api.init({ ci: true });
+	* ```
+	*/
+	init: async (opts) => {
+		await scaffoldWranglerAndCi(ctx.config.configFile, opts?.ci ?? ctx.config.ci);
+	}
+});
+/**
+* Complex tier (node-only) — build-time deploy orchestrator over the five resource plugins.
+*
+* Assembles each resource plugin's deployManifest() via ctx.require, provisions resources,
+* generates/updates wrangler config, uploads the R2 upload dir, and runs wrangler deploy.
+* Also supports a universal path: run({ manifest }) uses a caller-supplied manifest verbatim.
+*
+* @see README.md
+*/
+const deployPlugin = require_storage.createPlugin("deploy", {
+	config: {
+		configFile: "wrangler.jsonc",
+		ci: false
+	},
+	depends: [
+		require_storage.storagePlugin,
+		require_storage.kvPlugin,
+		require_storage.d1Plugin,
+		require_storage.queuesPlugin,
+		require_storage.durableObjectsPlugin
+	],
+	api: (ctx) => createDeployApi(ctx)
+});
+//#endregion
+//#region src/plugins/cli/api.ts
+/**
+* Builds app.cli.* — thin passthroughs to the deploy plugin via ctx.require(deployPlugin).
+* Both verbs forward their opts verbatim; `dev` defaults port to ctx.config.port when no
+* opts are supplied.
+*
+* @param ctx - CLI plugin context (own config + typed require to deployPlugin).
+* @returns The cli API object with `dev` and `deploy` methods.
+* @example
+* ```ts
+* const api = createCliApi(ctx);
+* await api.dev();            // → deploy.dev({ port: 8787 })
+* await api.deploy({ yes: true }); // → deploy.run({ yes: true })
+* ```
+*/
+const createCliApi = (ctx) => ({
+	/**
+	* Run the Worker locally; defaults port to ctx.config.port (8787) when no opts supplied.
+	*
+	* @param opts - Optional local dev options.
+	* @param opts.port - Local dev port to bind. Defaults to ctx.config.port (8787).
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev();            // port 8787
+	* await api.dev({ port: 3000 }); // port 3000
+	* ```
+	*/
+	dev(opts) {
+		return ctx.require(deployPlugin).dev(opts ?? { port: ctx.config.port });
+	},
+	/**
+	* One-command guided Cloudflare deploy; forwards flags verbatim to deploy.run.
+	* Passes `undefined` when called with no opts (not a default empty object).
+	*
+	* @param opts - Optional deploy options.
+	* @param opts.guided - Walk through each step interactively.
+	* @param opts.yes - Skip confirmation prompts (non-interactive / CI).
+	* @returns Resolves once the deploy completes.
+	* @example
+	* ```ts
+	* await api.deploy({ guided: true });
+	* await api.deploy({ yes: true }); // CI
+	* await api.deploy(); // opts === undefined
+	* ```
+	*/
+	deploy(opts) {
+		return ctx.require(deployPlugin).run(opts);
+	}
+});
+//#endregion
+//#region src/plugins/cli/handlers.ts
+/**
+* Builds the hook handlers that turn global deploy events into a live progress TUI
+* via ctx.log. Pure observers — print and return; never mutate state, never block
+* the deploy pipeline (fire-and-forget, spec/07 §3,§4).
+*
+* @param ctx - CLI plugin context with injected log core API.
+* @returns Hook map for the three global deploy events.
+* @example
+* ```ts
+* const hooks = createCliHooks(ctx);
+* hooks["deploy:phase"]({ phase: "detect" }); // logs "> detect"
+* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "  + kv KV"
+* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // logs "done -> https://x.workers.dev"
+* ```
+*/
+const createCliHooks = (ctx) => ({
+	/**
+	* Print one line per pipeline phase: "> phase" or "> phase - detail".
+	*
+	* @param p - The deploy:phase event payload.
+	* @example
+	* ```ts
+	* handler({ phase: "detect" }); // "> detect"
+	* handler({ phase: "upload", detail: "3 files" }); // "> upload - 3 files"
+	* ```
+	*/
+	"deploy:phase"(p) {
+		const detail = p.detail ? ` - ${p.detail}` : "";
+		ctx.log.info(`> ${p.phase}${detail}`);
+	},
+	/**
+	* Print one indented line per provisioned resource: "  + kind name".
+	*
+	* @param p - The provision:resource event payload.
+	* @example
+	* ```ts
+	* handler({ kind: "kv", name: "KV" }); // "  + kv KV"
+	* ```
+	*/
+	"provision:resource"(p) {
+		ctx.log.info(`  + ${p.kind} ${p.name}`);
+	},
+	/**
+	* Print the terminal success line with the deployed URL.
+	*
+	* @param p - The deploy:complete event payload.
+	* @example
+	* ```ts
+	* handler({ url: "https://my-worker.workers.dev" }); // "done -> https://my-worker.workers.dev"
+	* ```
+	*/
+	"deploy:complete"(p) {
+		ctx.log.info(`done -> ${p.url}`);
+	}
+});
+/**
+* Standard tier (node-only) — developer-facing CLI surface.
+*
+* Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
+* Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
+* and print a live progress TUI via the injected ctx.log core API.
+*
+* Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
+* are constrained to `WorkerEvents` keys (spec/15 §5).
+*
+* @see README.md
+*/
+const cliPlugin = require_storage.createPlugin("cli", {
+	depends: [deployPlugin],
+	config: { port: 8787 },
+	api: (ctx) => createCliApi(ctx),
+	hooks: (ctx) => createCliHooks(ctx)
+});
+//#endregion
+exports.cliPlugin = cliPlugin;
+exports.deployPlugin = deployPlugin;