@moku-labs/web 0.1.0-alpha.1 → 0.1.0-alpha.4

package/README.md

@@ -28,10 +28,45 @@ await app.build.run()
 
 ## Architecture
 
-- **9 domain-grouped plugins** wired via `@moku-labs/core` micro-kernel
+- **10 domain-grouped plugins** (`log`, `env`, `site`, `i18n`, `content`, `router`, `head`, `build`, `spa`, `deploy`) wired via `@moku-labs/core` micro-kernel
 - **Bun-native bundler** (no Vite subprocess)
 - **Generic-preserving `createApp` wrapper** projects flat config → `pluginConfigs`
 - **Dev mode** lives in `bin/moku.ts dev` (NOT a plugin)
+- **Cloudflare Pages deploy** via the `deploy` plugin and `moku deploy` CLI (see `src/plugins/deploy/README.md`)
+
+## Writing custom plugins
+
+Consumer apps can extend the framework with their own plugins using the framework-bound `createPlugin` (NOT the raw one from `@moku-labs/core`):
+
+```ts
+import { createApp, createPlugin, i18n, type Site } from '@moku-labs/web'
+
+const analytics = createPlugin('analytics', {
+  depends: [i18n],
+  config: { trackingId: '' },
+  createState: () => ({ events: [] as string[] }),
+  api: (ctx) => ({ track: (name: string) => { ctx.state.events.push(name) } }),
+})
+
+const siteConfig: Site.SiteConfig = {
+  name: 'My Blog',
+  url: 'https://example.com',
+  author: 'Jane Doe',
+  description: 'Personal blog',
+}
+```
+
+All 10 plugin instances (`log, env, site, i18n, content, router, head, build, spa, deploy`) and their namespaced config types (`Log, Env, Site, I18n, Content, Router, Head, Build, Spa, Deploy`) are exported from the main entry — use them for `ctx.require(...)` access and for typing `pluginConfigs` overrides.
+
+## Test helpers (`@moku-labs/web/test`)
+
+Framework-aware test factories for isolating plugin behavior in unit tests:
+
+```ts
+import { createTestApp, createTestLog, createTestEnv } from '@moku-labs/web/test'
+```
+
+Each factory returns a FRESH instance per call — never a module-level singleton — safe for parallel vitest workers.
 
 ## License
 

package/dist/bin/moku.cjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
-const require_project = require('../project-C1vtMxE8.cjs');
+const require_project = require('../project-B8z4jeMC.cjs');
+const require_wrangler = require('../wrangler-Bomk9mU-.cjs');
 let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let node_util = require("node:util");
 
@@ -25,6 +27,7 @@ Commands:
   build [folder]    Build static site (default folder: src/)
   dev [folder]      Start dev server with watch + rebuild
   preview [folder]  Build and serve site for local preview
+  deploy [folder]   Deploy dist/ to Cloudflare Pages (run \`deploy init\` once first)
 
 Options:
   --version         Show version number
@@ -62,6 +65,30 @@ Options:
   --port, -p <n>    Server port (default: 4173)
   --help, -h        Show help`.trim();
 /**
+* Format the help text for `moku deploy`.
+*
+* @returns The help text.
+*/
+const formatDeployHelp = () => `
+Usage: moku deploy [folder] [options]
+       moku deploy init [folder] [options]
+
+Arguments:
+  folder            Source folder containing main.ts (default: src/)
+
+Deploy options:
+  --build           Run \`moku build\` before deploying
+  --branch <name>   Branch to deploy to (default: from wrangler.jsonc workflow)
+  --help, -h        Show help
+
+Init options:
+  --ci              Also generate .github/workflows/deploy.yml
+  --force           Overwrite existing files (warns on slug change)
+  --create-project  Transactionally create the Cloudflare project before writing wrangler.jsonc
+  --check           Diff only, no writes; exits non-zero on drift
+  --branch <name>   Override the auto-detected default branch
+  --help, -h        Show help`.trim();
+/**
 * Format the help text for `moku preview`.
 *
 * @returns The help text.
@@ -224,6 +251,103 @@ const parseDev = (argv) => {
 	}
 };
 /**
+* Parse `moku deploy` arguments.
+*
+* @param argv - Argv after the `deploy` keyword (NOT including `init`).
+* @returns A {@link ParseResult} carrying a {@link DeployArgs} or an error message.
+*/
+const parseDeploy = (argv) => {
+	try {
+		const { values, positionals } = (0, node_util.parseArgs)({
+			args: argv,
+			options: {
+				build: {
+					type: "boolean",
+					default: false
+				},
+				branch: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h",
+					default: false
+				}
+			},
+			allowPositionals: true,
+			strict: true
+		});
+		return {
+			ok: true,
+			value: {
+				folder: positionals[0] ?? "src",
+				help: values.help,
+				build: values.build,
+				...values.branch === void 0 ? {} : { branch: values.branch }
+			}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: error.message
+		};
+	}
+};
+/**
+* Parse `moku deploy init` arguments.
+*
+* @param argv - Argv after the `deploy init` keywords.
+* @returns A {@link ParseResult} carrying a {@link DeployInitArgs} or an error message.
+*/
+const parseDeployInit = (argv) => {
+	try {
+		const { values, positionals } = (0, node_util.parseArgs)({
+			args: argv,
+			options: {
+				ci: {
+					type: "boolean",
+					default: false
+				},
+				force: {
+					type: "boolean",
+					default: false
+				},
+				"create-project": {
+					type: "boolean",
+					default: false
+				},
+				check: {
+					type: "boolean",
+					default: false
+				},
+				branch: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h",
+					default: false
+				}
+			},
+			allowPositionals: true,
+			strict: true
+		});
+		return {
+			ok: true,
+			value: {
+				folder: positionals[0] ?? "src",
+				help: values.help,
+				ci: values.ci,
+				force: values.force,
+				createProject: values["create-project"],
+				check: values.check,
+				...values.branch === void 0 ? {} : { branch: values.branch }
+			}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: error.message
+		};
+	}
+};
+/**
 * Parse `moku preview` arguments.
 *
 * @param argv - Argv after the `preview` keyword.
@@ -376,6 +500,7 @@ const runCli = async (argv, deps) => {
 		case "build": return deps.buildCommand(top.rest);
 		case "dev": return deps.devCommand(top.rest);
 		case "preview": return deps.previewCommand(top.rest);
+		case "deploy": return deps.deployCommand(top.rest);
 		default:
 			deps.stderr(`Unknown command: ${top.command}`);
 			deps.stdout(formatHelp());
@@ -465,6 +590,449 @@ const buildCommand = async (argv, deps) => {
 	return runBuildOnce(prepared.app, deps.stdout, deps.stderr);
 };
 
+//#endregion
+//#region src/plugins/deploy/generators/github-workflow.ts
+/** @file deploy plugin GitHub Actions workflow generator — SHA-pinned, single-source-of-truth wrangler version. */
+/** Pinned SHAs for the standard runner actions. Update on each plugin release. */
+const CHECKOUT_ACTION_SHA = "11bd71901bbe5b1630ceea73d27597364c9af683";
+const SETUP_BUN_ACTION_SHA = "4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5";
+/**
+* Generate the textual contents of `.github/workflows/deploy.yml`.
+*
+* Notes baked in:
+* - SHA-pinned actions (supply-chain hygiene).
+* - `wranglerVersion` pinned via {@link MOKU_WRANGLER_VERSION} — single SoT with `ensureWrangler()`.
+* - Command line uses `buildWranglerArgs(...)` so runtime and CI emit identical argv.
+* - No `--project-name` flag — wrangler reads `name` from `wrangler.jsonc`.
+* - Two-step pattern: `bun run moku build` then `wrangler-action` (enables Actions cache reuse).
+* - `gitHubToken` enables GitHub Deployments status updates on PRs and commits.
+*
+* @param input - Target, outdir, and branch.
+* @returns YAML text suitable for writing to `.github/workflows/deploy.yml`.
+*/
+const generateGitHubWorkflow = (input) => {
+	const args = require_wrangler.buildWranglerArgs(input.target, input.outdir, input.branch).join(" ");
+	return `# .github/workflows/deploy.yml — generated by \`moku deploy init --ci\`.
+# To re-sync after config changes, run \`moku deploy init --ci --force\`.
+
+name: Deploy
+
+on:
+  push:
+    branches: [${input.branch}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${CHECKOUT_ACTION_SHA}
+      - uses: oven-sh/setup-bun@${SETUP_BUN_ACTION_SHA}
+      - run: bun install --frozen-lockfile
+      # Two-step pattern (build then deploy) enables GitHub Actions cache reuse.
+      - run: bun run moku build
+      - uses: cloudflare/wrangler-action@${require_wrangler.WRANGLER_ACTION_SHA}
+        with:
+          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          wranglerVersion: "${require_wrangler.MOKU_WRANGLER_VERSION}"
+          gitHubToken: \${{ secrets.GITHUB_TOKEN }}
+          # buildWranglerArgs() — keep aligned with runtime argv. wrangler.jsonc#name is SSoT
+          # for the project name, so we deliberately do NOT pass --project-name here.
+          command: ${args}
+`;
+};
+/** Resolve the workflow path inside `cwd`. */
+const workflowPath = (cwd) => (0, node_path.join)(cwd, ".github", "workflows", "deploy.yml");
+/** Check whether `.github/workflows/deploy.yml` exists in `cwd`. */
+const githubWorkflowExists = (cwd) => (0, node_fs.existsSync)(workflowPath(cwd));
+/** Write the generated workflow file, creating `.github/workflows/` as needed. */
+const writeGitHubWorkflow = async (cwd, content) => {
+	const path = workflowPath(cwd);
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+	await (0, node_fs_promises.writeFile)(path, content, "utf8");
+};
+
+//#endregion
+//#region src/plugins/deploy/slug.ts
+/** @file deploy plugin slug derivation — Cloudflare Pages project-name validation + slugification. */
+/**
+* Cloudflare Pages project-name regex: lowercase alphanumerics and dashes only,
+* 1–58 chars, no leading/trailing dash, no underscores. Source: workers-sdk #3222.
+*/
+const CLOUDFLARE_PROJECT_NAME_REGEX = /^[a-z0-9][a-z0-9-]{0,56}[a-z0-9]$/;
+const MAX_PROJECT_NAME_LENGTH = 58;
+/**
+* Derive a Cloudflare Pages–valid project slug from an arbitrary site name.
+*
+* Algorithm: lowercase → replace non-alphanumeric with `-` → collapse repeated
+* dashes → strip leading/trailing dashes → truncate to 58 chars → strip
+* trailing dashes again after truncation.
+*
+* @param siteName - The consumer-facing site name (typically `site.name`).
+* @returns A slug matching {@link CLOUDFLARE_PROJECT_NAME_REGEX}.
+* @throws Error when the input slugifies to an empty string or fails regex validation.
+*/
+const slugify = (siteName) => {
+	const raw = siteName.toLowerCase().replaceAll(/[^a-z0-9-]/g, "-").replaceAll(/-+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, MAX_PROJECT_NAME_LENGTH).replace(/-+$/, "");
+	if (raw === "") throw new Error(`deploy: cannot derive a Cloudflare project slug from "${siteName}" — result is empty after sanitization`);
+	if (!CLOUDFLARE_PROJECT_NAME_REGEX.test(raw)) throw new Error(`deploy: derived slug "${raw}" does not match Cloudflare Pages project-name regex`);
+	return raw;
+};
+/**
+* Validate that an explicit project name matches Cloudflare's rules.
+*
+* @param name - Candidate project name.
+* @throws Error if the name violates {@link CLOUDFLARE_PROJECT_NAME_REGEX}.
+*/
+const assertValidProjectName = (name) => {
+	if (!CLOUDFLARE_PROJECT_NAME_REGEX.test(name)) throw new Error(`deploy: project name "${name}" must match ^[a-z0-9][a-z0-9-]{0,56}[a-z0-9]$ (1–58 chars, lowercase alphanumerics and dashes only, no leading/trailing dash, no underscores)`);
+};
+
+//#endregion
+//#region src/plugins/deploy/init.ts
+/** @file deploy plugin init orchestrator — branch detection, slug derivation, generators, checklist. */
+const DEFAULT_BRANCH = "main";
+const sanitizedProcessEnv = () => {
+	const out = {};
+	for (const [k, v] of Object.entries(process.env)) if (typeof v === "string") out[k] = v;
+	return out;
+};
+const getBun = () => globalThis;
+const runGitSymbolicRef = async () => {
+	const { Bun: bun } = getBun();
+	if (bun === void 0) return null;
+	try {
+		const proc = bun.spawn([
+			"git",
+			"symbolic-ref",
+			"refs/remotes/origin/HEAD"
+		], {
+			env: sanitizedProcessEnv(),
+			stdout: "pipe",
+			stderr: "pipe"
+		});
+		const stdout = await new Response(proc.stdout).text();
+		if (await proc.exited !== 0) return null;
+		return stdout.trim().match(/refs\/remotes\/origin\/(.+)$/)?.[1] ?? null;
+	} catch {
+		return null;
+	}
+};
+const runGitInitDefaultBranch = async () => {
+	const { Bun: bun } = getBun();
+	if (bun === void 0) return null;
+	try {
+		const proc = bun.spawn([
+			"git",
+			"config",
+			"--get",
+			"init.defaultBranch"
+		], {
+			env: sanitizedProcessEnv(),
+			stdout: "pipe",
+			stderr: "pipe"
+		});
+		const stdout = (await new Response(proc.stdout).text()).trim();
+		return await proc.exited === 0 && stdout !== "" ? stdout : null;
+	} catch {
+		return null;
+	}
+};
+/** Spawn `git symbolic-ref` with a fallback to `git config --get init.defaultBranch`. */
+const defaultDetectDefaultBranch = async () => {
+	const primary = await runGitSymbolicRef();
+	if (primary !== null) return primary;
+	return await runGitInitDefaultBranch() ?? DEFAULT_BRANCH;
+};
+/** Format a drift list as a printable diff block. */
+const formatDriftReport = (drift) => {
+	if (drift.length === 0) return "No drift detected.";
+	const lines = ["Drift detected:"];
+	for (const entry of drift) {
+		lines.push(`  ${entry.field}:`);
+		lines.push(`    - ${entry.current}`);
+		lines.push(`    + ${entry.proposed}`);
+	}
+	return lines.join("\n");
+};
+/** Print the post-init setup checklist to stdout. */
+const printChecklist = (stdout, slug, branch, createdProject) => {
+	stdout("");
+	stdout("Cloudflare Pages deploy — setup checklist");
+	stdout("");
+	stdout("1. Find your account ID:");
+	stdout("   https://dash.cloudflare.com  → string after dash.cloudflare.com/ in the URL.");
+	stdout("");
+	if (createdProject) stdout(`2. Pages project '${slug}' already exists (created by --create-project).`);
+	else {
+		stdout("2. Create the Pages project (skip if already created):");
+		stdout(`   wrangler pages project create ${slug}`);
+	}
+	stdout("");
+	stdout("3. Mint a Cloudflare API token:");
+	stdout("   https://dash.cloudflare.com/profile/api-tokens");
+	stdout("     → Create Token → Custom Token →");
+	stdout("     → Permissions: Account → Cloudflare Pages → Edit  (NOT \"Read\" — Read causes silent 403)");
+	stdout("   Click \"Create Token\", copy the value (shown only once).");
+	stdout("");
+	stdout("4. Add GitHub Actions secrets:");
+	stdout("   Settings → Secrets and variables → Actions → New repository secret");
+	stdout("   CLOUDFLARE_API_TOKEN  = (the token from step 3)");
+	stdout("   CLOUDFLARE_ACCOUNT_ID = (the ID from step 1)");
+	stdout("");
+	stdout("5. (Optional) Place _headers and _redirects in `public/` to control Cloudflare response headers and redirects.");
+	stdout("");
+	stdout(`6. Push to ${branch} — the generated workflow fires automatically.`);
+	stdout("");
+	stdout("Tip: run `moku deploy init --check` in release CI to assert config freshness.");
+	stdout("Note: Cloudflare dashboard git-push auto-build does NOT recognize wrangler.jsonc — use this workflow.");
+};
+const defaultPromptYesNo = async (_message, defaultYes) => Promise.resolve(defaultYes);
+/** Warn-and-overwrite branch of the slug drift decision (interactive "n" or `--force`). */
+const warnSlugChanged = (ctx, existingName, slug) => {
+	ctx.log.warn("deploy:init:slug-changed", {
+		existing: existingName,
+		computed: slug,
+		note: `Project rename: run \`wrangler pages project create ${slug}\`. The old project remains deployed under ${existingName}.pages.dev.`
+	});
+};
+const promptKeepExisting = async (ctx, existingName, slug) => {
+	return (ctx.promptYesNo ?? defaultPromptYesNo)(`${`wrangler.jsonc#name = "${existingName}" (existing) vs slug("${ctx.siteName}") = "${slug}" (computed).`}\nKeep existing? [Y/n]`, true);
+};
+/** Internal "should we write wrangler.jsonc?" decision around the diff-on-rename gate. */
+const resolveSlugWriteDecision = async (ctx, options, existing, slug, interactive) => {
+	if (existing === null || existing.name === slug) return true;
+	if (options.force === true) {
+		warnSlugChanged(ctx, existing.name, slug);
+		return true;
+	}
+	if (!interactive) {
+		ctx.log.info("deploy:init:slug-keep-existing", {
+			existing: existing.name,
+			computed: slug
+		});
+		return false;
+	}
+	if (await promptKeepExisting(ctx, existing.name, slug)) return false;
+	warnSlugChanged(ctx, existing.name, slug);
+	return true;
+};
+/** Run `wrangler pages project create` for the `--create-project` flag. Treats "already exists" as success. */
+const tryCreateCloudflareProject = async (ctx, slug) => {
+	const env = ctx.env ?? sanitizedProcessEnv();
+	try {
+		await require_wrangler.runWrangler([
+			"pages",
+			"project",
+			"create",
+			slug
+		], env, ctx.spawn);
+		return true;
+	} catch (error) {
+		const wranglerError = error instanceof Error ? error : new Error(String(error));
+		if (/already exists/i.test(wranglerError.message)) return true;
+		throw wranglerError;
+	}
+};
+/** Maybe write the GitHub Actions workflow file. */
+const maybeWriteWorkflow = async (ctx, options, cwd, branch) => {
+	if (options.ci !== true) return;
+	if (githubWorkflowExists(cwd) && options.force !== true) {
+		ctx.log.info("deploy:init:workflow-skipped", { reason: "exists; pass --force to overwrite" });
+		return;
+	}
+	await writeGitHubWorkflow(cwd, generateGitHubWorkflow({
+		target: ctx.config.target,
+		outdir: ctx.config.outdir,
+		branch
+	}));
+};
+/** Emit the "no build plugin registered" informational warning when appropriate. */
+const maybeWarnMissingBuild = (ctx) => {
+	if (!ctx.buildPluginRegistered && ctx.config.outdir === "dist") ctx.log.warn("deploy:init:no-build-plugin", { note: "No 'build' plugin registered and no explicit outdir set — using default 'dist'. Configure pluginConfigs.deploy.outdir if your build output lives elsewhere." });
+};
+/** Handle the `--check` short-circuit. */
+const handleCheckMode = (ctx, cwd, slug, outdir, branch) => {
+	const drift = require_wrangler.diffWranglerConfig(require_wrangler.readWranglerConfig(cwd), {
+		slug,
+		outdir
+	});
+	ctx.stdout(formatDriftReport(drift));
+	return {
+		slug,
+		outdir,
+		branch,
+		drift,
+		wroteFiles: false
+	};
+};
+const resolveInitInputs = async (ctx, options) => {
+	const detectBranch = ctx.detectDefaultBranch ?? defaultDetectDefaultBranch;
+	const branch = options.branch ?? await detectBranch();
+	const slug = ctx.config.projectName ?? slugify(ctx.siteName);
+	assertValidProjectName(slug);
+	const interactive = options.interactive ?? Boolean(process.stdout.isTTY);
+	return {
+		branch,
+		slug,
+		outdir: ctx.config.outdir,
+		interactive
+	};
+};
+/** Compose the writable artifacts step — wrangler.jsonc + workflow + warnings. */
+const writeArtifacts = async (ctx, options, cwd, inputs, writeJsonc) => {
+	if (writeJsonc) await require_wrangler.writeWranglerConfig(cwd, require_wrangler.generateWranglerConfig({
+		slug: inputs.slug,
+		outdir: inputs.outdir
+	}));
+	await maybeWriteWorkflow(ctx, options, cwd, inputs.branch);
+	maybeWarnMissingBuild(ctx);
+};
+/**
+* Run `moku deploy init`.
+*
+* @param ctx - {@link InitContext} carrying logger, stdout, and injectable spawn/git deps.
+* @param options - {@link InitOptions} flag set.
+* @returns A {@link InitResult} summarizing what happened.
+*/
+const runInit = async (ctx, options = {}) => {
+	const cwd = options.cwd ?? process.cwd();
+	const inputs = await resolveInitInputs(ctx, options);
+	if (options.check === true) return handleCheckMode(ctx, cwd, inputs.slug, inputs.outdir, inputs.branch);
+	const writeJsonc = await resolveSlugWriteDecision(ctx, options, require_wrangler.readWranglerConfig(cwd), inputs.slug, inputs.interactive);
+	const projectCreated = options.createProject === true ? await tryCreateCloudflareProject(ctx, inputs.slug) : void 0;
+	await writeArtifacts(ctx, options, cwd, inputs, writeJsonc);
+	const wroteFiles = writeJsonc || options.ci === true;
+	if (wroteFiles) printChecklist(ctx.stdout, inputs.slug, inputs.branch, projectCreated === true);
+	return {
+		slug: inputs.slug,
+		outdir: inputs.outdir,
+		branch: inputs.branch,
+		wroteFiles,
+		...projectCreated === void 0 ? {} : { projectCreated }
+	};
+};
+
+//#endregion
+//#region src/bin/commands/deploy.ts
+/** @file `moku deploy` command — load app, run app.deploy.run() or runInit(). */
+/**
+* Top-level dispatcher for `moku deploy` and `moku deploy init`.
+*
+* @param argv - Argv after the `deploy` keyword.
+* @param deps - Injected IO + loader dependencies.
+* @returns Exit code: 0 ok, 1 load error, 2 deploy error, 3 arg error.
+*/
+const deployCommand = async (argv, deps) => {
+	const [first, ...rest] = argv;
+	if (first === "init") return runInitCommand(rest, deps);
+	return runDeployCommand(argv, deps);
+};
+const runDeployCommand = async (argv, deps) => {
+	const prepared = await prepareApp({
+		argv,
+		parse: parseDeploy,
+		loadApp: deps.loadApp,
+		cwd: deps.cwd
+	});
+	if (prepared.kind === "help") {
+		deps.stdout(formatDeployHelp());
+		return { code: 0 };
+	}
+	if (prepared.kind === "bad-args") {
+		deps.stderr(prepared.message);
+		deps.stdout(formatDeployHelp());
+		return { code: 3 };
+	}
+	if (prepared.kind === "load-failed") {
+		deps.stderr(prepared.message);
+		return { code: 1 };
+	}
+	if (prepared.app.deploy === void 0) {
+		deps.stderr("deploy: this app does not register the deploy plugin.");
+		return { code: 1 };
+	}
+	try {
+		const result = await prepared.app.deploy.run({
+			...prepared.args.branch === void 0 ? {} : { branch: prepared.args.branch },
+			build: prepared.args.build
+		});
+		deps.stdout(`Deployed to ${result.url} (branch=${result.branch}, ${result.durationMs}ms)`);
+		return { code: 0 };
+	} catch (error) {
+		deps.stderr(`Deploy failed: ${error.message}`);
+		return { code: 2 };
+	}
+};
+const resolveDeployConfig = (app) => {
+	const fromAppConfig = app.config?.deploy;
+	if (fromAppConfig !== void 0) return fromAppConfig;
+	return {
+		target: "pages",
+		outdir: "dist",
+		productionBranch: "main"
+	};
+};
+const makeInitLogger = (deps) => ({
+	info: (event, data) => deps.stdout(`[info] ${event} ${data ? JSON.stringify(data) : ""}`),
+	warn: (event, data) => deps.stderr(`[warn] ${event} ${data ? JSON.stringify(data) : ""}`),
+	error: (event, data) => deps.stderr(`[error] ${event} ${data ? JSON.stringify(data) : ""}`)
+});
+const runInitForPreparedApp = async (deps, app, args) => {
+	const siteName = app.site?.name() ?? "";
+	if (siteName === "") {
+		deps.stderr("deploy init: site.name is empty — set it in your app config.");
+		return { code: 1 };
+	}
+	try {
+		const result = await runInit({
+			siteName,
+			config: resolveDeployConfig(app),
+			buildPluginRegistered: app.build !== void 0,
+			log: makeInitLogger(deps),
+			stdout: deps.stdout
+		}, {
+			cwd: deps.cwd,
+			ci: args.ci,
+			force: args.force,
+			createProject: args.createProject,
+			check: args.check,
+			...args.branch === void 0 ? {} : { branch: args.branch }
+		});
+		if (args.check && result.drift !== void 0 && result.drift.length > 0) return { code: 2 };
+		return { code: 0 };
+	} catch (error) {
+		deps.stderr(`Deploy init failed: ${error.message}`);
+		return { code: 2 };
+	}
+};
+const runInitCommand = async (argv, deps) => {
+	const prepared = await prepareApp({
+		argv,
+		parse: parseDeployInit,
+		loadApp: deps.loadApp,
+		cwd: deps.cwd
+	});
+	if (prepared.kind === "help") {
+		deps.stdout(formatDeployHelp());
+		return { code: 0 };
+	}
+	if (prepared.kind === "bad-args") {
+		deps.stderr(prepared.message);
+		deps.stdout(formatDeployHelp());
+		return { code: 3 };
+	}
+	if (prepared.kind === "load-failed") {
+		deps.stderr(prepared.message);
+		return { code: 1 };
+	}
+	return runInitForPreparedApp(deps, prepared.app, prepared.args);
+};
+
 //#endregion
 //#region src/bin/commands/dev.ts
 /** @file `moku dev` command — watch + invalidate + rebuild + serve loop. */
@@ -800,6 +1368,12 @@ const main = async () => {
 			stderr,
 			loadApp,
 			serve: serveStatic
+		}),
+		deployCommand: (argv) => deployCommand(argv, {
+			cwd: process.cwd(),
+			stdout,
+			stderr,
+			loadApp
 		})
 	});
 	process.exit(result.code);