hatchkit 0.1.28 → 0.1.30

package/dist/templates/build-pipeline/Dockerfile.client.hbs

@@ -3,8 +3,26 @@
 # Static-site image for {{name}}.
 # Built by .github/workflows/deploy.yml, pushed to GHCR, pulled by
 # Coolify via docker-compose.yml. nginx serves the built bundle —
-# no runtime Node, so dotenvx encryption isn't relevant here
-# (anything sensitive should never reach the browser bundle anyway).
+# no runtime Node, so any sensitive values must be build-time-only
+# (baked into the static bundle) or non-sensitive.
+#
+# .env.production is committed to the repo dotenvx-encrypted. The
+# build stage decrypts it via the dotenvx_private_key BuildKit secret
+# (passed by .github/workflows/deploy.yml from the GH Actions secret
+# DOTENV_PRIVATE_KEY_PRODUCTION) so `pnpm build` sees the plain values
+# when it bakes them into the static output.
+#
+# Why BuildKit secrets and not ARG: ARG values land in `docker history`
+# and the image manifest. BuildKit secrets are mounted as tmpfs at
+# build time and never persist — `docker history` won't show them, the
+# final image won't either. Requires BuildKit (default in modern
+# Docker; the GH Actions workflow uses docker/setup-buildx-action
+# which enables it).
+#
+# What ends up in the bundle: NEXT_PUBLIC_* / VITE_* / similar values
+# that the framework explicitly inlines into client JS. What does NOT:
+# any non-public values, since this static site has no runtime to
+# read them.
 ARG NODE_VERSION={{nodeMajor}}
 
 FROM node:${NODE_VERSION}-alpine AS build
@@ -12,7 +30,19 @@ WORKDIR /app
 COPY package.json pnpm-lock.yaml* ./
 RUN corepack enable && pnpm install --frozen-lockfile
 COPY . .
-RUN pnpm build
+# `--mount=type=secret,id=dotenvx_private_key,env=DOTENV_PRIVATE_KEY_PRODUCTION`
+# exposes the secret value as the env var the wrapped command reads,
+# only for the duration of this RUN. dotenvx picks it up, decrypts
+# .env.production in memory, and re-exports each KEY=VALUE for
+# `pnpm build`. If the secret isn't supplied, dotenvx silently skips
+# decryption and the build would bake `encrypted:...` strings into
+# asset URLs — fail fast instead.
+RUN --mount=type=secret,id=dotenvx_private_key,env=DOTENV_PRIVATE_KEY_PRODUCTION \
+    if [ -z "$DOTENV_PRIVATE_KEY_PRODUCTION" ]; then \
+      echo "ERROR: dotenvx_private_key build secret not supplied. The workflow at .github/workflows/deploy.yml should pass it via 'secrets:' from the GH Actions secret DOTENV_PRIVATE_KEY_PRODUCTION." >&2; \
+      exit 1; \
+    fi && \
+    pnpm dlx @dotenvx/dotenvx run -- pnpm build
 
 FROM nginx:alpine AS runner
 COPY --from=build /app/dist /usr/share/nginx/html

package/dist/templates/build-pipeline/Dockerfile.server.hbs

@@ -2,10 +2,23 @@
 #
 # Server / fullstack image for {{name}}.
 # Built by .github/workflows/deploy.yml, pushed to GHCR, pulled by
-# Coolify via docker-compose.yml. Uses dotenvx at runtime so the
-# committed encrypted .env.production decrypts only inside the
-# container (the private key comes from DOTENV_PRIVATE_KEY_PRODUCTION,
-# set on the Coolify app's env).
+# Coolify via docker-compose.yml. dotenvx decrypts the committed
+# encrypted .env.production at TWO points:
+#
+#   1. Build stage — uses the dotenvx_private_key BuildKit secret
+#      (passed by the workflow from the GH Actions secret
+#      DOTENV_PRIVATE_KEY_PRODUCTION) to decrypt in-memory before
+#      running `pnpm build`. Required for fullstack builds that bake
+#      NEXT_PUBLIC_* / VITE_* values into a static client bundle —
+#      those values are inlined at build time and unreachable from
+#      the runtime CMD. The secret is mounted as tmpfs and never
+#      lands in `docker history` or any image layer.
+#
+#   2. Runtime CMD — `dotenvx run` reads the same .env.production and
+#      decrypts again, this time using DOTENV_PRIVATE_KEY_PRODUCTION
+#      from the container env (forwarded by docker-compose.yml from
+#      Coolify's app env). This covers server-side values the runtime
+#      reads with `process.env.X`.
 ARG NODE_VERSION={{nodeMajor}}
 
 FROM node:${NODE_VERSION}-alpine AS deps
@@ -17,7 +30,18 @@ FROM node:${NODE_VERSION}-alpine AS build
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
-RUN corepack enable && pnpm build
+# Build-time decryption — see the header comment for the rationale.
+# `if [ -z "$DOTENV_PRIVATE_KEY_PRODUCTION" ]` fails fast when the
+# workflow forgot to pass the secret; without it dotenvx would
+# silently export zero env vars and the build would bake broken
+# `encrypted:...` strings into the static bundle.
+RUN --mount=type=secret,id=dotenvx_private_key,env=DOTENV_PRIVATE_KEY_PRODUCTION \
+    if [ -z "$DOTENV_PRIVATE_KEY_PRODUCTION" ]; then \
+      echo "ERROR: dotenvx_private_key build secret not supplied. The workflow at .github/workflows/deploy.yml should pass it via 'secrets:' from the GH Actions secret DOTENV_PRIVATE_KEY_PRODUCTION." >&2; \
+      exit 1; \
+    fi && \
+    corepack enable && \
+    pnpm dlx @dotenvx/dotenvx run -- pnpm build
 
 FROM node:${NODE_VERSION}-alpine AS runner
 WORKDIR /app
@@ -27,5 +51,6 @@ COPY --from=build /app /app
 EXPOSE {{port}}
 # `dotenvx run` reads .env.production (encrypted, committed) and
 # decrypts in-process using DOTENV_PRIVATE_KEY_PRODUCTION before
-# spawning the actual server.
+# spawning the actual server. corepack isn't enabled in this stage,
+# so we fetch dotenvx via npx instead of pnpm dlx.
 CMD ["sh", "-c", "npx --yes @dotenvx/dotenvx run -- node {{entrypoint}}"]

package/dist/templates/build-pipeline/deploy.yml.hbs

@@ -8,8 +8,19 @@
 # Required repo secrets (hatchkit sets these via `gh secret set`
 # during adopt / create; rotate via the GitHub UI / `gh` whenever
 # needed):
-#   COOLIFY_WEBHOOK_URL — full URL incl. uuid query param
-#   COOLIFY_TOKEN       — bearer token for the deploy endpoint
+#   COOLIFY_WEBHOOK_URL           — full URL incl. uuid query param
+#   COOLIFY_TOKEN                 — bearer token for the deploy endpoint
+#   DOTENV_PRIVATE_KEY_PRODUCTION — dotenvx private key; passed to the
+#                                   docker build as a BuildKit secret
+#                                   (mounted as tmpfs, never written
+#                                   to a layer or `docker history`).
+#                                   The Dockerfile uses it to decrypt
+#                                   .env.production in memory and bake
+#                                   build-time values (NEXT_PUBLIC_*
+#                                   etc.) into the output. Stored in
+#                                   your OS keychain under
+#                                   `dotenvx:<project>:production-private-key`
+#                                   — `hatchkit keys show <project>` to retrieve.
 #
 # GHCR auth uses the workflow's built-in GITHUB_TOKEN. For Coolify
 # to pull a private package, configure GHCR credentials in the
@@ -69,6 +80,14 @@ jobs:
           cache-from: type=gha
           cache-to: type=gha,mode=max
           platforms: linux/amd64
+          # BuildKit secret for decrypting .env.production at build
+          # time. Mounted as tmpfs inside the Dockerfile's RUN step,
+          # never written to a layer or `docker history`. The Dockerfile
+          # exposes it as the DOTENV_PRIVATE_KEY_PRODUCTION env var for
+          # `dotenvx run -- pnpm build`, which decrypts in memory and
+          # bakes NEXT_PUBLIC_* / VITE_* values into the bundle.
+          secrets: |
+            dotenvx_private_key=${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}
 
       - name: Trigger Coolify deploy
         env:

package/dist/utils/dockerignore.d.ts

@@ -0,0 +1,23 @@
+export interface EnsureDockerignoreResult {
+    /** Absolute path we inspected (whether or not it existed). */
+    path: string;
+    /** True iff there was no `.dockerignore` before this call. We never
+     *  create one — see the module docstring for why. */
+    fileExisted: boolean;
+    /** True iff we appended a hatchkit-managed line. False when the
+     *  negation was already present, or when there was no file. */
+    modified: boolean;
+}
+/** Idempotently ensure `<repoRoot>/.dockerignore` allows `.env.production`
+ *  through. Appends `!.env.production` (with a `# hatchkit:` bread crumb)
+ *  when the negation is missing AND a `.dockerignore` exists.
+ *
+ *  The negation is a safe append — if nothing actually excluded
+ *  `.env.production`, the line is a redundant no-op. We don't try to
+ *  parse the user's patterns to decide whether the line is needed; the
+ *  parsing surface area (globs, `**`, anchored vs. unanchored, repeated
+ *  rule overrides) isn't worth getting subtly wrong when the redundant
+ *  case is harmless.
+ */
+export declare function ensureDockerignoreAllowsEnvProduction(repoRoot: string): EnsureDockerignoreResult;
+//# sourceMappingURL=dockerignore.d.ts.map

package/dist/utils/dockerignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dockerignore.d.ts","sourceRoot":"","sources":["../../src/utils/dockerignore.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb;yDACqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB;mEAC+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CAsBhG"}

package/dist/utils/dockerignore.js

@@ -0,0 +1,58 @@
+/*
+ * Tiny helper for keeping `.env.production` *in* the Docker build context.
+ *
+ * hatchkit-managed projects commit a dotenvx-encrypted `.env.production`
+ * to git (encryption is the whole point — the file's content is
+ * `KEY="encrypted:..."`, safe to ship). Many existing repos already
+ * carry a defensive `.dockerignore` that wildcards out the entire
+ * `.env*` family, which inadvertently strips the encrypted file from
+ * the build context too. dotenvx then can't find the file at build
+ * (or runtime) and silently exports zero env vars — `next build` /
+ * `pnpm build` runs with empty NEXT_PUBLIC_* values, baking broken
+ * URLs into the image.
+ *
+ * The fix is one line: append `!.env.production` so the encrypted file
+ * survives the wildcard. We do NOT remove the user's existing exclude
+ * rules — those still keep plaintext `.env`, `.env.local`, and (most
+ * importantly) `.env.keys` (the private key) out of the image.
+ *
+ * No-op when `.dockerignore` doesn't exist: Docker copies everything by
+ * default, so the encrypted file is already in the context.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const SECTION_HEADER = "# hatchkit: dotenvx-encrypted .env.production must remain in the build context (decrypted in-memory by `dotenvx run`)";
+/** Idempotently ensure `<repoRoot>/.dockerignore` allows `.env.production`
+ *  through. Appends `!.env.production` (with a `# hatchkit:` bread crumb)
+ *  when the negation is missing AND a `.dockerignore` exists.
+ *
+ *  The negation is a safe append — if nothing actually excluded
+ *  `.env.production`, the line is a redundant no-op. We don't try to
+ *  parse the user's patterns to decide whether the line is needed; the
+ *  parsing surface area (globs, `**`, anchored vs. unanchored, repeated
+ *  rule overrides) isn't worth getting subtly wrong when the redundant
+ *  case is harmless.
+ */
+export function ensureDockerignoreAllowsEnvProduction(repoRoot) {
+    const path = join(repoRoot, ".dockerignore");
+    if (!existsSync(path)) {
+        return { path, fileExisted: false, modified: false };
+    }
+    const existing = readFileSync(path, "utf-8");
+    // Match `!.env.production` exactly — trim whitespace, ignore inline
+    // comments. We don't accept `!**/.env.production` or other variants
+    // here; they're rare enough that erring on the side of duplicate
+    // negations is fine.
+    const hasNegate = existing.split(/\r?\n/).some((l) => l.trim() === "!.env.production");
+    if (hasNegate) {
+        return { path, fileExisted: true, modified: false };
+    }
+    // Append with a leading blank line + comment so the appended block
+    // visually separates from whatever the user already had. End with a
+    // trailing newline so a future append doesn't glue onto our line.
+    const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+    const block = `${needsLeadingNewline ? "\n" : ""}\n${SECTION_HEADER}\n!.env.production\n`;
+    writeFileSync(path, existing + block);
+    return { path, fileExisted: true, modified: true };
+}
+//# sourceMappingURL=dockerignore.js.map

package/dist/utils/dockerignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dockerignore.js","sourceRoot":"","sources":["../../src/utils/dockerignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,cAAc,GAClB,uHAAuH,CAAC;AAa1H;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qCAAqC,CAAC,QAAgB;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7C,oEAAoE;IACpE,oEAAoE;IACpE,iEAAiE;IACjE,qBAAqB;IACrB,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,kBAAkB,CAAC,CAAC;IACvF,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAG,GAAG,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,cAAc,sBAAsB,CAAC;IAC1F,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatchkit",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "packageManager": "pnpm@10.33.2",
   "description": "Interactive CLI for scaffolding full-stack projects and provisioning observability/email clients",
   "type": "module",