hatchkit 0.1.40 → 0.1.42

package/dist/adopt.js

@@ -100,9 +100,19 @@ export async function runAdopt(cwd, opts = {}) {
                 : state.clientDir
                     ? "client-only"
                     : "client-only");
+    // Auto-suggest gh-pages when (a) the manifest already recorded it,
+    // or (b) the manifest is silent AND the project looks client-only
+    // AND there's no Coolify app already wired up. Otherwise default
+    // to coolify (the existing behaviour).
+    const inferredDeploymentMode = m?.deploymentMode === "gh-pages"
+        ? "gh-pages"
+        : m?.deploymentMode === "scaffold-only"
+            ? "scaffold-only"
+            : "coolify";
     let plan = {
         name: m?.name ?? state.packageName ?? "",
         domain: m?.domain ?? "",
+        deploymentMode: inferredDeploymentMode,
         // Description resolution order:
         //   1. Persisted manifest value (`--resume` recovery — a previous
         //      run already settled this).
@@ -147,7 +157,50 @@ export async function runAdopt(cwd, opts = {}) {
         // redundant in that branch.
         pushKey: !!state.coolifyAppMatch,
     };
+    // When the plan starts in gh-pages mode (from a `--resume` of an
+    // earlier adopt, or a manifest the user committed by hand), run
+    // the heuristics once up front. Block before even entering the
+    // review loop on findings that would make Pages refuse to build —
+    // the user needs to either fix the project or switch back to
+    // coolify. The edit-step handler runs the same check when the
+    // user *switches into* gh-pages from inside the loop, so this
+    // covers the gap where they never edit the deploymentMode row.
+    if (plan.deploymentMode === "gh-pages") {
+        const { detectPagesIncompatibilities, hasBlockingFinding } = await import("./scaffold/pages-heuristics.js");
+        const findings = detectPagesIncompatibilities(state.projectDir);
+        if (findings.length > 0) {
+            console.log(chalk.bold("\n  Pages compatibility findings:\n"));
+            for (const f of findings) {
+                const tag = f.level === "block"
+                    ? chalk.red("✗ block")
+                    : f.level === "warn"
+                        ? chalk.yellow("! warn")
+                        : chalk.dim("· info");
+                console.log(`  ${tag}  ${chalk.bold(f.title)}`);
+                console.log(chalk.dim(`         ${f.detail}`));
+                for (const ev of f.evidence) {
+                    console.log(chalk.dim(`         → ${ev}`));
+                }
+            }
+            console.log();
+            if (hasBlockingFinding(findings)) {
+                console.log(chalk.red("  Blocking findings — Pages can't host this project as-is. Fix the issues above\n" +
+                    "  or pick a different deployment mode in the review screen."));
+            }
+        }
+    }
     plan = await reviewLoop(state, plan);
+    // Re-check after the review loop in case the user kept (or switched
+    // back to) gh-pages despite blockers being present. The edit handler
+    // refuses the switch into gh-pages over blockers, but it can't catch
+    // the case where blockers exist on entry AND the user stays put.
+    if (plan.deploymentMode === "gh-pages") {
+        const { detectPagesIncompatibilities, hasBlockingFinding } = await import("./scaffold/pages-heuristics.js");
+        const findings = detectPagesIncompatibilities(state.projectDir);
+        if (hasBlockingFinding(findings)) {
+            throw new Error("Pages compatibility blockers still present — refusing to adopt with gh-pages mode. Fix the issues listed above or re-run adopt and pick coolify/scaffold-only.");
+        }
+    }
     await executePlan(state, plan, {
         resume: !!opts.resume,
         regeneratePipeline: !!opts.regeneratePipeline,
@@ -612,70 +665,85 @@ function buildAdoptGroups(state, plan) {
                 },
             ],
         },
-        {
-            title: "Build pipeline",
-            steps: [
+        // The Docker + GH Actions pipeline is Coolify-targeted (it
+        // configures the redeploy webhook + builds an image). gh-pages
+        // ships its own workflow that uploads to Pages instead, so we
+        // hide this group when the user picks Pages.
+        ...(plan.deploymentMode === "coolify"
+            ? [
                 {
-                    key: "scaffoldBuildPipeline",
-                    label: "Docker + GH Actions",
-                    set: true,
-                    summary: renderBuildPipelineSummary(state, plan),
+                    title: "Build pipeline",
+                    steps: [
+                        {
+                            key: "scaffoldBuildPipeline",
+                            label: "Docker + GH Actions",
+                            set: true,
+                            summary: renderBuildPipelineSummary(state, plan),
+                        },
+                    ],
                 },
-            ],
-        },
+            ]
+            : []),
         {
             title: "Deploy",
             steps: [
-                (() => {
-                    // Visibility row. Picking the wrong path here is the #1
-                    // cause of "Permission denied (publickey)" deploy failures
-                    // (Coolify tries SSH against a repo whose GitHub App isn't
-                    // installed). Mark `set: false` when we couldn't auto-detect
-                    // visibility from `gh repo view`, so the cursor parks on it.
-                    const detected = state.gitRemoteIsPrivate;
-                    const summaryBase = plan.isPrivate
-                        ? "private — Coolify clones via GitHub App SSH key"
-                        : "public — Coolify clones via HTTPS";
-                    const detectedHint = detected === undefined && state.gitRemoteUrl
-                        ? chalk.dim(" (couldn't auto-detect — confirm)")
-                        : detected !== undefined && detected !== plan.isPrivate
-                            ? chalk.yellow(` (gh says ${detected ? "private" : "public"} — overridden)`)
-                            : "";
-                    return {
-                        key: "isPrivate",
-                        label: "Repo visibility",
-                        // `set: false` when we have a remote but couldn't detect
-                        // (forces the user to confirm before Adopt). Otherwise true.
-                        set: !(detected === undefined && !!state.gitRemoteUrl),
-                        summary: `${summaryBase}${detectedHint}`,
-                    };
-                })(),
-                (() => {
-                    // Preflight: when adopt will be wiring a private repo into
-                    // Coolify and Coolify has zero GitHub App sources, the wire
-                    // step will throw at execute time with "no Coolify GitHub
-                    // source configured". Surface that here so the cursor parks
-                    // on this row and the user fixes it before hitting Adopt.
-                    const missingSource = plan.wireCoolify &&
-                        plan.isPrivate &&
-                        state.coolifyConfigured &&
-                        state.coolifyGithubSourceCount === 0;
-                    const baseSummary = plan.wireCoolify
-                        ? state.coolifyAppMatch
-                            ? chalk.dim(`existing app "${state.coolifyAppMatch.name}" — will reconcile build pack`)
-                            : `yes — create app + upsert DNS (port ${plan.appPort})`
-                        : state.coolifyAppMatch
-                            ? chalk.dim(`already exists: ${state.coolifyAppMatch.name}`)
-                            : chalk.dim("no");
-                    return {
-                        key: "wireCoolify",
-                        label: "Coolify + DNS",
-                        set: !missingSource,
-                        summary: missingSource
-                            ? `${baseSummary}  ${chalk.yellow("(needs Coolify GitHub App — install one or set visibility to public)")}`
-                            : baseSummary,
-                    };
-                })(),
+                // Top-line choice: where this project deploys. Hides the
+                // Coolify-specific rows when set to gh-pages.
+                {
+                    key: "deploymentMode",
+                    label: "Deployment mode",
+                    set: true,
+                    summary: renderAdoptDeploymentModeSummary(plan.deploymentMode, plan.surfaces),
+                },
+                // Coolify-specific rows — only shown when actually deploying
+                // to Coolify. gh-pages skips this branch entirely.
+                ...(plan.deploymentMode === "coolify"
+                    ? [
+                        (() => {
+                            // Visibility row. Picking the wrong path here is the #1
+                            // cause of "Permission denied (publickey)" deploy failures
+                            // (Coolify tries SSH against a repo whose GitHub App isn't
+                            // installed). Mark `set: false` when we couldn't auto-detect
+                            // visibility from `gh repo view`, so the cursor parks on it.
+                            const detected = state.gitRemoteIsPrivate;
+                            const summaryBase = plan.isPrivate
+                                ? "private — Coolify clones via GitHub App SSH key"
+                                : "public — Coolify clones via HTTPS";
+                            const detectedHint = detected === undefined && state.gitRemoteUrl
+                                ? chalk.dim(" (couldn't auto-detect — confirm)")
+                                : detected !== undefined && detected !== plan.isPrivate
+                                    ? chalk.yellow(` (gh says ${detected ? "private" : "public"} — overridden)`)
+                                    : "";
+                            return {
+                                key: "isPrivate",
+                                label: "Repo visibility",
+                                set: !(detected === undefined && !!state.gitRemoteUrl),
+                                summary: `${summaryBase}${detectedHint}`,
+                            };
+                        })(),
+                        (() => {
+                            const missingSource = plan.wireCoolify &&
+                                plan.isPrivate &&
+                                state.coolifyConfigured &&
+                                state.coolifyGithubSourceCount === 0;
+                            const baseSummary = plan.wireCoolify
+                                ? state.coolifyAppMatch
+                                    ? chalk.dim(`existing app "${state.coolifyAppMatch.name}" — will reconcile build pack`)
+                                    : `yes — create app + upsert DNS (port ${plan.appPort})`
+                                : state.coolifyAppMatch
+                                    ? chalk.dim(`already exists: ${state.coolifyAppMatch.name}`)
+                                    : chalk.dim("no");
+                            return {
+                                key: "wireCoolify",
+                                label: "Coolify + DNS",
+                                set: !missingSource,
+                                summary: missingSource
+                                    ? `${baseSummary}  ${chalk.yellow("(needs Coolify GitHub App — install one or set visibility to public)")}`
+                                    : baseSummary,
+                            };
+                        })(),
+                    ]
+                    : []),
             ],
         },
         {
@@ -687,20 +755,39 @@ function buildAdoptGroups(state, plan) {
                     set: true,
                     summary: plan.services.length > 0 ? plan.services.join(", ") : chalk.dim("skip provisioning"),
                 },
-                {
-                    key: "pushKey",
-                    label: "Push key to Coolify",
-                    set: true,
-                    summary: plan.pushKey
-                        ? state.coolifyAppMatch
-                            ? `yes (${state.coolifyAppMatch.name})`
-                            : "yes — Coolify app must exist by name"
-                        : chalk.dim("no"),
-                },
+                // `pushKey` only matters when a Coolify app is the deploy
+                // target — Pages reads no secrets from a Coolify env, so the
+                // row would just be noise on the gh-pages path.
+                ...(plan.deploymentMode === "coolify"
+                    ? [
+                        {
+                            key: "pushKey",
+                            label: "Push key to Coolify",
+                            set: true,
+                            summary: plan.pushKey
+                                ? state.coolifyAppMatch
+                                    ? `yes (${state.coolifyAppMatch.name})`
+                                    : "yes — Coolify app must exist by name"
+                                : chalk.dim("no"),
+                        },
+                    ]
+                    : []),
             ],
         },
     ];
 }
+function renderAdoptDeploymentModeSummary(mode, surfaces) {
+    switch (mode) {
+        case "coolify":
+            return "Coolify (full-stack on Hetzner)";
+        case "gh-pages":
+            return surfaces === "client-only"
+                ? "GitHub Pages (static)"
+                : chalk.yellow("GitHub Pages — needs surfaces=client-only");
+        case "scaffold-only":
+            return "scaffold only (no deploy)";
+    }
+}
 async function editAdoptStep(state, plan, step) {
     if (step === "name") {
         const name = (await input({
@@ -744,9 +831,19 @@ async function editAdoptStep(state, plan, step) {
         // Adjust the dir fields when the surface changes — dropping
         // server/client dirs that are no longer relevant, and setting
         // sane defaults for newly-relevant ones.
+        // Also: switching away from client-only invalidates gh-pages
+        // (Pages can't host a backend). Snap deploymentMode back to
+        // coolify in that case so the user doesn't keep an invalid combo.
+        const nextDeploymentMode = plan.deploymentMode === "gh-pages" && next !== "client-only"
+            ? "coolify"
+            : plan.deploymentMode;
+        if (plan.deploymentMode === "gh-pages" && next !== "client-only") {
+            console.log(chalk.yellow("  ⚠ gh-pages requires client-only surfaces — switched deployment mode back to coolify."));
+        }
         return {
             ...plan,
             surfaces: next,
+            deploymentMode: nextDeploymentMode,
             serverDir: next === "client-only"
                 ? undefined
                 : (plan.serverDir ?? state.serverDir ?? state.projectDir),
@@ -755,6 +852,58 @@ async function editAdoptStep(state, plan, step) {
                 : (plan.clientDir ?? state.clientDir ?? state.projectDir),
         };
     }
+    if (step === "deploymentMode") {
+        const choices = [
+            { name: "Coolify (full-stack on Hetzner)", value: "coolify" },
+        ];
+        if (plan.surfaces === "client-only") {
+            choices.push({ name: "GitHub Pages (static)", value: "gh-pages" });
+        }
+        choices.push({ name: "Scaffold only — don't deploy", value: "scaffold-only" });
+        const next = await select({
+            message: "Where do you want to deploy?",
+            choices,
+            default: plan.deploymentMode,
+        });
+        // When switching INTO gh-pages, run the static-site sanity checks
+        // and surface any blockers before letting the user proceed. They
+        // can still pick gh-pages over a "warn" finding, but "block"
+        // (e.g. Next without `output: "export"`) requires they either fix
+        // the project first or step back to coolify.
+        if (next === "gh-pages" && plan.deploymentMode !== "gh-pages") {
+            const { detectPagesIncompatibilities, hasBlockingFinding } = await import("./scaffold/pages-heuristics.js");
+            const findings = detectPagesIncompatibilities(state.projectDir);
+            if (findings.length > 0) {
+                console.log(chalk.bold("\n  Pages compatibility findings:\n"));
+                for (const f of findings) {
+                    const tag = f.level === "block"
+                        ? chalk.red("✗ block")
+                        : f.level === "warn"
+                            ? chalk.yellow("! warn")
+                            : chalk.dim("· info");
+                    console.log(`  ${tag}  ${chalk.bold(f.title)}`);
+                    console.log(chalk.dim(`         ${f.detail}`));
+                    for (const ev of f.evidence) {
+                        console.log(chalk.dim(`         → ${ev}`));
+                    }
+                }
+                console.log();
+                if (hasBlockingFinding(findings)) {
+                    console.log(chalk.red("  Blocking findings present — Pages won't be able to host this project as-is."));
+                    console.log(chalk.dim("  Fix the issues above (or stay on coolify) and re-pick."));
+                    // Don't switch — leave plan.deploymentMode unchanged.
+                    return plan;
+                }
+                const proceed = await confirm({
+                    message: "Proceed with gh-pages despite the warnings?",
+                    default: false,
+                });
+                if (!proceed)
+                    return plan;
+            }
+        }
+        return { ...plan, deploymentMode: next };
+    }
     if (step === "serverDir") {
         const picked = (await input({
             message: "Server env directory (relative to project root):",
@@ -811,10 +960,15 @@ async function editAdoptStep(state, plan, step) {
                     checked: plan.services.includes("openpanel"),
                 },
                 {
-                    name: "Resend (email)",
+                    name: "Resend (transactional email)",
                     value: "resend",
                     checked: plan.services.includes("resend"),
                 },
+                {
+                    name: "Email forwarding (Cloudflare Email Routing → your inbox)",
+                    value: "email",
+                    checked: plan.services.includes("email"),
+                },
             ],
         });
         return { ...plan, services };
@@ -976,10 +1130,18 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // anything that already exists, so this is idempotent across re-runs.
         // Must run BEFORE Coolify wiring so the docker-compose.yml exists
         // by the time Coolify clones the repo for the first deploy.
-        if (plan.scaffoldBuildPipeline) {
+        //
+        // Gated on coolify mode — the Coolify-targeted Dockerfile + deploy
+        // webhook workflow aren't useful for gh-pages, which uses its own
+        // `gh-pages.yml` workflow written later in step 3c-pages.
+        let scaffoldedAbsPaths = [];
+        let overwrittenAbsPaths = [];
+        if (plan.scaffoldBuildPipeline && plan.deploymentMode === "coolify") {
             const pipeResult = await scaffoldBuildPipelineNow(state, plan, remoteUrl, {
                 force: !!opts.regeneratePipeline,
             });
+            scaffoldedAbsPaths = pipeResult.createdAbsPaths;
+            overwrittenAbsPaths = pipeResult.overwrittenAbsPaths;
             // Record only files we *created*. The `overwritten` list is
             // deliberately not recorded — those files existed before this
             // run (the user's), and a later `hatchkit destroy` must never
@@ -995,7 +1157,9 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // DNS-provider REST endpoints with credentials we already have in
         // keychain. Idempotent on the DNS side (upsert); not yet on the
         // app-create side (Coolify accepts duplicate app names).
-        if (plan.wireCoolify && remoteUrl) {
+        //
+        // Skipped for gh-pages — Pages handles its own DNS in step 3c-pages.
+        if (plan.wireCoolify && plan.deploymentMode === "coolify" && remoteUrl) {
             try {
                 const { wireProjectIntoCoolify } = await import("./deploy/coolify-app.js");
                 coolifyResult = await wireProjectIntoCoolify({
@@ -1102,8 +1266,10 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // created" and "app already existed before adopt" branches. Need
         // an app uuid in either case. Run BEFORE the initial git push
         // (below) so the workflow's first run has the secrets in place.
+        //
+        // Skipped for gh-pages — there's no Coolify webhook to hit.
         const appUuidForSecrets = coolifyResult?.appUuid ?? state.coolifyAppMatch?.uuid;
-        if (plan.scaffoldBuildPipeline && appUuidForSecrets) {
+        if (plan.scaffoldBuildPipeline && plan.deploymentMode === "coolify" && appUuidForSecrets) {
             const slug = repoSlugFromRemote(remoteUrl);
             if (slug) {
                 await setCoolifyDeploySecrets({
@@ -1127,7 +1293,10 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // a Coolify one) — gates only on having the build pipeline + a
         // resolvable repo slug. Best-effort: failure surfaces as a caveat
         // with a copy-pasteable manual recipe so adopt finishes cleanly.
-        if (plan.scaffoldBuildPipeline) {
+        //
+        // gh-pages doesn't need this secret — the Pages workflow builds
+        // the client without consuming server-side env.
+        if (plan.scaffoldBuildPipeline && plan.deploymentMode === "coolify") {
             const slug = repoSlugFromRemote(remoteUrl);
             if (slug) {
                 const secretName = "DOTENV_PRIVATE_KEY_PRODUCTION";
@@ -1157,13 +1326,104 @@ async function executePlan(state, plan, opts = { resume: false }) {
                 console.log(chalk.dim("  · Couldn't resolve owner/repo from git remote — push DOTENV_PRIVATE_KEY_PRODUCTION to Actions manually."));
             }
         }
-        // Step 3d: push the working branch to origin. Done AFTER secrets
-        // are set so the workflow's first run can hit the Coolify webhook
-        // without falling through to the "secret not set" branch. Skipped
-        // when there's no remote yet (e.g. user opted out of GitHub) or
-        // when origin already had history before adopt.
-        if (plan.setupGitHub && remoteUrl && !state.gitRemoteUrl) {
-            await pushInitialBranch(state.projectDir);
+        // Step 3c-pages: GitHub Pages setup (gh-pages mode only).
+        // Writes .github/workflows/gh-pages.yml + CNAME locally and
+        // configures the remote side (enable Pages, register cname,
+        // wire DNS, poll for the Let's Encrypt cert, flip
+        // https_enforced). Must happen BEFORE the push step below so
+        // the new files land in the same push and the workflow runs.
+        //
+        // Auto-detect heuristic: for a client-only project we deploy
+        // the client dir (typically `packages/client/`). The detected
+        // shape mirrors what gh-pages's own pickSite would have chosen
+        // — node-build, pnpm, root-level build script.
+        if (plan.deploymentMode === "gh-pages" && remoteUrl) {
+            try {
+                const { runPagesSetupProgrammatic } = await import("./deploy/pages.js");
+                const { exec: bashExec } = await import("./utils/exec.js");
+                const slug = repoSlugFromRemote(remoteUrl) ?? plan.name;
+                // For adopt we don't know the exact build layout of the
+                // user's project. Best-guess for a client-only Next.js
+                // app: `packages/client/out` (post-`output: export` build).
+                // If the user has a different layout they can re-run
+                // `hatchkit gh-pages` from the project dir to override.
+                const clientDir = plan.clientDir
+                    ? relative(state.projectDir, plan.clientDir)
+                    : "packages/client";
+                const detected = {
+                    kind: "node-build",
+                    publishDir: clientDir ? `${clientDir}/out` : "out",
+                    packageManager: "pnpm",
+                    buildScript: "build",
+                    workDir: "",
+                };
+                const { pageUrl } = await runPagesSetupProgrammatic(state.projectDir, {
+                    detected,
+                    domain: plan.domain || null,
+                });
+                ledger.record({
+                    kind: "ghPages",
+                    repo: slug,
+                    projectDir: state.projectDir,
+                    cname: plan.domain || undefined,
+                });
+                // Stage and commit so the next push picks up the workflow
+                // + CNAME file. If nothing changed (idempotent re-run), the
+                // status check skips the commit entirely.
+                await bashExec("git", ["add", "-A"], { cwd: state.projectDir, silent: true });
+                const status = await bashExec("git", ["status", "--porcelain"], {
+                    cwd: state.projectDir,
+                    silent: true,
+                });
+                if (status.stdout.trim()) {
+                    await bashExec("git", ["commit", "-m", "ci: GitHub Pages setup"], {
+                        cwd: state.projectDir,
+                        silent: true,
+                    });
+                }
+                console.log(chalk.green(`  ✓ GitHub Pages will publish at ${pageUrl}`));
+            }
+            catch (err) {
+                caveats.push({
+                    title: "GitHub Pages not wired",
+                    reason: err.message,
+                    recovery: [
+                        `Re-run from the project dir: hatchkit gh-pages`,
+                        `(it'll pick up where this left off and is idempotent).`,
+                    ],
+                });
+            }
+        }
+        // Step 3d: push to origin so GitHub Actions builds + pushes the
+        // GHCR image. Done AFTER Coolify wiring + secrets so the workflow's
+        // first run can hit the redeploy webhook on its own.
+        //
+        // Two paths:
+        //   · Brand-new remote (this run just ran `gh repo create`) →
+        //     pushInitialBranch pushes the whole tree.
+        //   · Pre-existing remote → commitAndPushScaffold makes a
+        //     pathspec-scoped commit of just the files hatchkit wrote
+        //     (manifest + build-pipeline scaffold) and pushes it. Without
+        //     this push the workflow file lives only in the working tree,
+        //     Actions never fires, and the GHCR-wait below times out.
+        //
+        // `pushedThisRun` gates the GHCR step below — we only wait for a
+        // new image when a push actually went out.
+        let pushedThisRun = false;
+        if (remoteUrl) {
+            if (plan.setupGitHub && !state.gitRemoteUrl) {
+                pushedThisRun = await pushInitialBranch(state.projectDir);
+            }
+            else if (state.gitRemoteUrl) {
+                const result = await commitAndPushScaffold(state, {
+                    scaffoldedAbsPaths,
+                    overwrittenAbsPaths,
+                    manifestPath,
+                });
+                pushedThisRun = result.pushed;
+                if (result.caveat)
+                    caveats.push(result.caveat);
+            }
         }
         // Step 3e: GHCR setup. Two paths, gated on the user's earlier
         // public/private choice:
@@ -1186,7 +1446,25 @@ async function executePlan(state, plan, opts = { resume: false }) {
             remoteUrl &&
             coolifyResult !== undefined) {
             const slug = repoSlugFromRemote(remoteUrl);
-            if (slug) {
+            if (slug && !pushedThisRun && !plan.isPrivate) {
+                // No push went out (either nothing changed on disk this run,
+                // or the auto-commit-push failed). Without a push the
+                // build-and-deploy workflow doesn't run, so polling GHCR for
+                // a brand-new image would just time out. Defer the visibility
+                // PATCH to the next `--resume` once the user has pushed.
+                caveats.push({
+                    title: "GHCR visibility not set — no push triggered",
+                    reason: "Adopt didn't push to origin this run, so the build-and-deploy workflow hasn't been triggered to publish the GHCR image.",
+                    recovery: [
+                        "Commit + push so the workflow runs:",
+                        `  cd ${state.projectDir}`,
+                        `  git add . && git commit -m "chore: adopt hatchkit"`,
+                        `  git push`,
+                        "Then re-run: hatchkit adopt --resume",
+                    ],
+                });
+            }
+            else if (slug) {
                 const { makeGhcrPackagePublic, registerGhcrCredsWithCoolify } = await import("./deploy/ghcr.js");
                 if (plan.isPrivate) {
                     // Read the full GHCR config (token + the PAT owner's GitHub
@@ -1264,6 +1542,44 @@ async function executePlan(state, plan, opts = { resume: false }) {
                     else if (event.service === "resend") {
                         ledger.record({ kind: "resend", client: event.client });
                     }
+                    else if (event.service === "email") {
+                        // Email setup creates three kinds of mutable state on
+                        // Cloudflare: the destination address (account-scoped), the
+                        // forwarding rules (zone-scoped), and the apex MX/SPF/DMARC
+                        // records (also zone-scoped). We only record what THIS run
+                        // created — `destinationCreatedThisRun` and `r.created` /
+                        // `dnsRecords` (which the provision orchestrator already
+                        // pre-filtered to `created: true` entries). MX/SPF/DMARC
+                        // upserts on a zone that already had them stay out of the
+                        // ledger so destroy never yanks pre-existing records.
+                        if (event.destinationCreatedThisRun) {
+                            ledger.record({
+                                kind: "cloudflareEmailDestination",
+                                accountId: event.accountId,
+                                destinationId: event.destinationId,
+                                email: event.destinationEmail,
+                            });
+                        }
+                        for (const dns of event.dnsRecords) {
+                            ledger.record({
+                                kind: "cloudflareDnsRecord",
+                                zoneId: event.zoneId,
+                                recordId: dns.id,
+                                name: dns.name,
+                                type: dns.type,
+                            });
+                        }
+                        for (const rule of event.rules) {
+                            if (!rule.created)
+                                continue;
+                            ledger.record({
+                                kind: "cloudflareEmailRoutingRule",
+                                zoneId: event.zoneId,
+                                ruleId: rule.id,
+                                address: rule.address,
+                            });
+                        }
+                    }
                 },
             });
         }
@@ -1714,6 +2030,267 @@ async function ensureEnvProductionCommitted(state, plan) {
             `      git -C ${relativeTo(state.projectDir)} commit -m "chore(dotenvx): commit encrypted .env.production" -- ${relativeTo(prodPath, state.projectDir)}`));
     }
 }
+/**
+ * Sniff the working tree for state that would make auto-commit + push
+ * surprising or destructive. We refuse to touch git when:
+ *
+ *   · A merge / rebase / cherry-pick / revert / bisect is in progress
+ *     — adopt isn't allowed to add commits on top of half-resolved
+ *     conflicts.
+ *   · Any tracked file *outside* hatchkit's path list has unstaged or
+ *     staged changes. Even though the commit itself is pathspec-scoped
+ *     (so the user's modifications wouldn't be swept in), the push
+ *     would still land hatchkit's commit on top of the user's WIP on
+ *     the same branch — entangling their unpushed work with the
+ *     hatchkit commit on origin. Make them park or commit it first.
+ *
+ * Untracked files (status `??`) are deliberately ignored — they're
+ * common debris (editor swaps, build artifacts not in gitignore, etc.)
+ * and never end up in our pathspec commit anyway.
+ */
+async function detectUserWip(projectDir, hatchkitAbsPaths) {
+    // In-progress operations: probe the .git dir for marker files. We
+    // resolve --git-dir via git itself so this works in worktrees (where
+    // .git is a file, not a directory) and submodules.
+    const gitDirRes = await exec("git", ["rev-parse", "--git-dir"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (gitDirRes.exitCode === 0) {
+        const raw = gitDirRes.stdout.trim();
+        const gitDir = raw.startsWith("/") ? raw : join(projectDir, raw);
+        const markers = [
+            ["MERGE_HEAD", "merge"],
+            ["CHERRY_PICK_HEAD", "cherry-pick"],
+            ["REVERT_HEAD", "revert"],
+            ["rebase-merge", "rebase"],
+            ["rebase-apply", "rebase"],
+            ["BISECT_LOG", "bisect"],
+        ];
+        for (const [marker, op] of markers) {
+            if (existsSync(join(gitDir, marker)))
+                return { kind: "in-progress", op };
+        }
+    }
+    // Repo-root-relative path matching. `git status --porcelain` emits
+    // paths relative to the repo root, not necessarily our cwd, so we
+    // normalize hatchkit's absolute paths the same way before comparing.
+    const rootRes = await exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (rootRes.exitCode !== 0) {
+        return { kind: "error", reason: "git rev-parse --show-toplevel failed" };
+    }
+    const repoRoot = rootRes.stdout.trim();
+    const hatchkitRelToRoot = new Set(hatchkitAbsPaths.map((p) => relative(repoRoot, p)));
+    const status = await exec("git", ["status", "--porcelain", "--untracked-files=no"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (status.exitCode !== 0) {
+        return { kind: "error", reason: "git status failed" };
+    }
+    const userFiles = [];
+    for (const line of status.stdout.split("\n")) {
+        if (line.length < 4)
+            continue;
+        const code = line.slice(0, 2);
+        let rest = line.slice(3);
+        // Renames/copies show up as "OLD -> NEW". We want the new path.
+        if (rest.includes(" -> "))
+            rest = rest.split(" -> ").pop() ?? rest;
+        // Git quotes paths with special chars in C-style. If a path is
+        // quoted we conservatively treat it as user WIP rather than try
+        // to unquote and risk a false negative.
+        const path = rest.startsWith('"') && rest.endsWith('"') ? rest.slice(1, -1) : rest;
+        if (!hatchkitRelToRoot.has(path)) {
+            userFiles.push({ status: code, path });
+        }
+    }
+    if (userFiles.length > 0)
+        return { kind: "user-changes", files: userFiles };
+    return { kind: "ok" };
+}
+/**
+ * Commit + push the files hatchkit wrote this run (manifest +
+ * scaffolded build pipeline) to a pre-existing remote so the
+ * build-and-deploy workflow fires.
+ *
+ * Pathspec-scoped on purpose: a plain `git add -A` would sweep up
+ * whatever WIP the user happened to have in the working tree —
+ * surprising behavior for an adopt. By listing only the paths
+ * hatchkit just wrote, the resulting commit is exactly "the adopt
+ * step", and anything else stays staged in the user's hands.
+ *
+ * Hard-stops with a caveat when `detectUserWip` finds unrelated user
+ * changes or an in-progress git operation. The push would otherwise
+ * land hatchkit's commit on top of WIP that isn't part of adopt — a
+ * surprise we explicitly refuse to do.
+ *
+ * Returns `{ pushed: false }` (no caveat) for the idempotent case —
+ * everything hatchkit wrote was already byte-identical to HEAD, so
+ * there was nothing to push. Failures during commit/push surface as
+ * a caveat with a copy-pasteable manual recipe.
+ */
+async function commitAndPushScaffold(state, paths) {
+    const all = [
+        ...paths.scaffoldedAbsPaths,
+        ...paths.overwrittenAbsPaths,
+        paths.manifestPath,
+    ].filter((p, i, arr) => arr.indexOf(p) === i && existsSync(p));
+    if (all.length === 0)
+        return { pushed: false };
+    // Hard stop: refuse to auto-commit on top of in-progress git ops
+    // or unrelated user changes. See detectUserWip docstring for the
+    // exact policy.
+    const wip = await detectUserWip(state.projectDir, all);
+    if (wip.kind === "in-progress") {
+        return {
+            pushed: false,
+            caveat: {
+                title: `Refusing to auto-commit — git ${wip.op} in progress`,
+                reason: `A ${wip.op} is in progress in ${state.projectDir}. Adopt won't stack commits on top of half-resolved git state.`,
+                recovery: [
+                    `Finish or abort the ${wip.op}, then re-run adopt:`,
+                    wip.op === "rebase"
+                        ? `  git rebase --continue   # or: git rebase --abort`
+                        : `  git ${wip.op} --abort   # or finish it manually and commit`,
+                    "Then: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    if (wip.kind === "user-changes") {
+        const preview = wip.files.slice(0, 8).map((f) => `    ${f.status} ${f.path}`);
+        const extra = wip.files.length > 8 ? [`    ... and ${wip.files.length - 8} more`] : [];
+        return {
+            pushed: false,
+            caveat: {
+                title: "Refusing to auto-commit — working tree has unrelated changes",
+                reason: `Found ${wip.files.length} modified file(s) outside the hatchkit scaffold. Auto-committing + pushing now would land the adopt commit on top of WIP that isn't part of the adopt step.`,
+                recovery: [
+                    "Hatchkit wanted to commit + push these files:",
+                    ...all.map((p) => `    + ${relativeTo(p, state.projectDir)}`),
+                    "",
+                    "Your working tree also has changes to:",
+                    ...preview,
+                    ...extra,
+                    "",
+                    "Park, commit, or discard your WIP first — whichever fits:",
+                    `  git stash push -u -m "pre-hatchkit-adopt"   # park on the side`,
+                    `  # or: git add . && git commit -m "..."        # keep in history`,
+                    `  # or: git checkout -- <file>                 # discard a file`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    if (wip.kind === "error") {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Refusing to auto-commit — couldn't verify a clean working tree",
+                reason: `Working-tree detection failed: ${wip.reason}. Adopt won't auto-commit without knowing what else is in the tree.`,
+                recovery: [
+                    "Commit + push the scaffold manually:",
+                    `  cd ${state.projectDir}`,
+                    `  git add ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest"`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    // Definitive pre-commit notice. The user opted into adopt, but an
+    // auto-commit-and-push on a pre-existing remote is a meaningful
+    // side effect — they should see exactly what's happening before it
+    // lands on origin.
+    console.log();
+    console.log(chalk.bold.yellow("  ⚠ hatchkit is about to commit + push to origin:"));
+    for (const p of all) {
+        console.log(chalk.yellow(`      + ${relativeTo(p, state.projectDir)}`));
+    }
+    console.log(chalk.dim("    (working tree verified clean of unrelated changes — auto-commit is safe)"));
+    console.log();
+    // Pathspec stage: only the hatchkit-owned files. `--` separates
+    // pathspecs from refs so a file named "main" doesn't get confused
+    // for a branch.
+    const stage = await exec("git", ["add", "--", ...all], {
+        cwd: state.projectDir,
+        silent: true,
+    });
+    if (stage.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Couldn't stage hatchkit scaffold for commit",
+                reason: (stage.stderr || stage.stdout).split(/\r?\n/)[0] || "git add failed",
+                recovery: [
+                    "Stage + commit + push manually so the workflow runs:",
+                    `  cd ${state.projectDir}`,
+                    `  git add ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest"`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    // Nothing in the staged index means every file was byte-identical
+    // to HEAD — this is the idempotent re-run case. No push needed.
+    const cleanStaged = await execOk("git", ["diff", "--cached", "--quiet"], {
+        cwd: state.projectDir,
+    });
+    if (cleanStaged)
+        return { pushed: false };
+    // Pathspec on the commit too — anything else the user happened to
+    // stage themselves before running adopt stays out of this commit.
+    const commit = await exec("git", ["commit", "-m", "chore(hatchkit): adopt scaffold + manifest", "--", ...all], { cwd: state.projectDir, silent: true });
+    if (commit.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Couldn't commit hatchkit scaffold automatically",
+                reason: (commit.stderr || commit.stdout).split(/\r?\n/)[0] || "git commit failed",
+                recovery: [
+                    "Commit + push the scaffold manually:",
+                    `  cd ${state.projectDir}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest" -- ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    console.log(chalk.green(`  ✓ Committed hatchkit scaffold (${all.length} files)`));
+    const headRes = await exec("git", ["symbolic-ref", "--short", "HEAD"], {
+        cwd: state.projectDir,
+        silent: true,
+    });
+    const branch = headRes.exitCode === 0 ? headRes.stdout.trim() : "main";
+    const push = await exec("git", ["push", "origin", branch], {
+        cwd: state.projectDir,
+        spinner: `Pushing ${branch} to origin...`,
+    });
+    if (push.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: `Couldn't push ${branch} to origin`,
+                reason: (push.stderr || push.stdout).split(/\r?\n/)[0] || `git push exited ${push.exitCode}`,
+                recovery: [
+                    "Push the new commit so Actions can build the image:",
+                    `  cd ${state.projectDir}`,
+                    `  git push origin ${branch}`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    return { pushed: true };
+}
 async function setupGitHubRemote(state, plan) {
     // Pre-flight gh CLI auth. ensureGitHub prompts the user to log in
     // when needed; if they cancel, surface a clear "you can do this
@@ -1828,6 +2405,10 @@ function writeAdoptManifest(projectDir, plan) {
         mlServices: [],
         s3Provider: (() => (plan.features.includes("s3") ? "existing" : "none"))(),
         deployTarget: "existing",
+        // Persist deployment mode so `--resume` recovers the gh-pages
+        // path without re-asking the user. Same back-compat invariant
+        // as `surfaces` — readers without this field fall back to coolify.
+        deploymentMode: plan.deploymentMode,
         ports: { server: 3000, client: 3001 },
         // Persist the surface choice so `--resume` doesn't re-infer
         // "server-only" just because there's no client/ directory in the