@geekmidas/cli 10.0.0-alpha.81 → 10.0.0-alpha.83

package/dist/index.cjs

@@ -5,22 +5,22 @@ const require_run = require("./run-fVZ-rLnc.cjs");
 const require_credentials = require("./credentials-BVs7mrtw.cjs");
 const require_discover = require("./discover-D1It5r_h.cjs");
 const require_derive = require("./derive-DAbo49sm.cjs");
-const require_workspace = require("./workspace-Bp8FEkF-.cjs");
+const require_workspace = require("./workspace-4i6Jwsoa.cjs");
 const require_config = require("./config.cjs");
-const require_seeds = require("./seeds-BjHiy9tW.cjs");
-const require_EndpointGenerator = require("./EndpointGenerator-CP6sBvQV.cjs");
+const require_seeds = require("./seeds-Ccju3zGl.cjs");
+const require_EndpointGenerator = require("./EndpointGenerator-cKlnllIu.cjs");
 const require_openapi = require("./openapi.cjs");
-const require_SubscriberGenerator = require("./SubscriberGenerator-CajwOa5W.cjs");
+const require_SubscriberGenerator = require("./SubscriberGenerator-CYriX5BV.cjs");
 const require_appPorts = require("./appPorts-Cu79hJF6.cjs");
-const require_drivers = require("./drivers-BdvtCKc7.cjs");
+const require_drivers = require("./drivers-CJx76mcb.cjs");
 const require_emit = require("./emit-Dmc1nvdS.cjs");
-const require_sniffer = require("./sniffer-BjG-1mlD.cjs");
-const require_deploy = require("./deploy-DuHRWNeJ.cjs");
-const require_compose = require("./compose-76ho0pUg.cjs");
+const require_sniffer = require("./sniffer-DeyYI9Iv.cjs");
+const require_deploy = require("./deploy-BlZx6J5x.cjs");
+const require_compose = require("./compose-CGyxYe-h.cjs");
 const require_credentialSchemas = require("./credentialSchemas-DCR4Wd1W.cjs");
-const require_LocalStateStore = require("./LocalStateStore-Bocb8dmZ.cjs");
+const require_LocalStateStore = require("./LocalStateStore-BsFHdSeA.cjs");
 const require_utils = require("./utils-D2Nk1Nv2.cjs");
-const require_ready = require("./ready-BB9xS4S9.cjs");
+const require_ready = require("./ready-4kx2pAhm.cjs");
 let node_path = require("node:path");
 let commander = require("commander");
 let node_process = require("node:process");
@@ -53,7 +53,7 @@ crypto = require_rolldown_runtime.__toESM(crypto, 1);
 let _geekmidas_constructs_functions = require("@geekmidas/constructs/functions");
 let _geekmidas_constructs_topic = require("@geekmidas/constructs/topic");
 //#region package.json
-var version = "10.0.0-alpha.81";
+var version = "10.0.0-alpha.83";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -136,7 +136,7 @@ const logger$8 = console;
 * Validate Dokploy token by making a test API call
 */
 async function validateDokployToken(endpoint, token) {
-	const { DokployApi } = await Promise.resolve().then(() => require("./sniffer-BjG-1mlD.cjs")).then((n) => n.dokploy_api_exports);
+	const { DokployApi } = await Promise.resolve().then(() => require("./sniffer-DeyYI9Iv.cjs")).then((n) => n.dokploy_api_exports);
 	return new DokployApi({
 		baseUrl: endpoint,
 		token
@@ -2217,9 +2217,9 @@ async function workspaceDevCommand(configured, options) {
 	for (const { id, port } of fakes) logger$5.log(`🎭 ${id} fake: http://localhost:${port}`);
 	logger$5.log(options.migrate || options.seed ? "🗄️  Migrating the databases" : "🗄️  Checking for pending migrations");
 	if (options.migrate || options.seed) {
-		const { prepareDevDatabases } = await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs"));
+		const { prepareDevDatabases } = await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs"));
 		await prepareDevDatabases(workspace, reconciled.env, { seed: !!options.seed });
-	} else await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs")).then(({ reportPendingMigrations }) => reportPendingMigrations(workspace, reconciled.env)).catch((error) => {
+	} else await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs")).then(({ reportPendingMigrations }) => reportPendingMigrations(workspace, reconciled.env)).catch((error) => {
 		logger$5.log(`⚠️  Could not check for pending migrations: ${error instanceof Error ? error.message : String(error)}`);
 	});
 	const appUrls = {};
@@ -3227,7 +3227,7 @@ async function buildApp(input) {
 		if (production?.bundle && !input.skipBundle) {
 			const outputDir = (0, node_path.join)(appRoot, ".gkm", "server");
 			const entryPoint = await writeSurfaceServer(outputDir, production);
-			const { bundleServer } = await Promise.resolve().then(() => require("./bundler-DeIVbloM.cjs"));
+			const { bundleServer } = await Promise.resolve().then(() => require("./bundler-BkH1kPEX.cjs"));
 			await bundleServer({
 				entryPoint,
 				outputDir: (0, node_path.join)(outputDir, "dist"),
@@ -3351,7 +3351,7 @@ async function buildWorkers(input) {
 		});
 		logger$4.log(`Generated worker ${worker.id}: ${crons.length} crons, ${queues.length} queues, ${subscribers.length} subscribers`);
 		if (!input.bundle) continue;
-		const { bundleServer } = await Promise.resolve().then(() => require("./bundler-DeIVbloM.cjs"));
+		const { bundleServer } = await Promise.resolve().then(() => require("./bundler-BkH1kPEX.cjs"));
 		const outfile = require_seeds.workerBundleName(worker.id);
 		await bundleServer({
 			entryPoint,
@@ -3421,7 +3421,7 @@ async function buildForTarget(target, context, appRoot, workspaceRoot, endpointG
 		let masterKey;
 		if (context.production?.bundle && !skipBundle) {
 			logger$4.log(`\n📦 Bundling production server...`);
-			const { bundleServer } = await Promise.resolve().then(() => require("./bundler-DeIVbloM.cjs"));
+			const { bundleServer } = await Promise.resolve().then(() => require("./bundler-BkH1kPEX.cjs"));
 			const allConstructs = [
 				...endpoints.map((e) => e.construct),
 				...functions.map((f) => f.construct),
@@ -5108,12 +5108,12 @@ const PNPM_VERSION = "pnpm@10.13.1";
 const BIOME_SCHEMA = `https://biomejs.dev/schemas/${DEPENDENCY_VERSIONS["@biomejs/biome"].replace(/^[~^]/, "")}/schema.json`;
 //#endregion
 //#region src/init/versions.ts
-const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+const require$2 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 function loadPackageJson() {
 	try {
-		return require$1("../package.json");
+		return require$2("../package.json");
 	} catch {
-		return require$1("../../package.json");
+		return require$2("../../package.json");
 	}
 }
 /**
@@ -5123,25 +5123,25 @@ function loadPackageJson() {
 * Run: pnpm --filter @geekmidas/cli sync-versions
 */
 const GEEKMIDAS_VERSIONS = {
-	"@geekmidas/audit": "~10.0.0-alpha.81",
-	"@geekmidas/auth": "~10.0.0-alpha.81",
-	"@geekmidas/cache": "~10.0.0-alpha.81",
-	"@geekmidas/client": "~10.0.0-alpha.81",
-	"@geekmidas/cloud": "~10.0.0-alpha.81",
-	"@geekmidas/constructs": "~10.0.0-alpha.81",
-	"@geekmidas/db": "~10.0.0-alpha.81",
-	"@geekmidas/emailkit": "~10.0.0-alpha.81",
-	"@geekmidas/envkit": "~10.0.0-alpha.81",
-	"@geekmidas/errors": "~10.0.0-alpha.81",
-	"@geekmidas/events": "~10.0.0-alpha.81",
-	"@geekmidas/logger": "~10.0.0-alpha.81",
-	"@geekmidas/manifest": "~10.0.0-alpha.81",
-	"@geekmidas/rate-limit": "~10.0.0-alpha.81",
-	"@geekmidas/schema": "~10.0.0-alpha.81",
-	"@geekmidas/services": "~10.0.0-alpha.81",
-	"@geekmidas/storage": "~10.0.0-alpha.81",
-	"@geekmidas/telescope": "~10.0.0-alpha.81",
-	"@geekmidas/testkit": "~10.0.0-alpha.81",
+	"@geekmidas/audit": "~10.0.0-alpha.83",
+	"@geekmidas/auth": "~10.0.0-alpha.83",
+	"@geekmidas/cache": "~10.0.0-alpha.83",
+	"@geekmidas/client": "~10.0.0-alpha.83",
+	"@geekmidas/cloud": "~10.0.0-alpha.83",
+	"@geekmidas/constructs": "~10.0.0-alpha.83",
+	"@geekmidas/db": "~10.0.0-alpha.83",
+	"@geekmidas/emailkit": "~10.0.0-alpha.83",
+	"@geekmidas/envkit": "~10.0.0-alpha.83",
+	"@geekmidas/errors": "~10.0.0-alpha.83",
+	"@geekmidas/events": "~10.0.0-alpha.83",
+	"@geekmidas/logger": "~10.0.0-alpha.83",
+	"@geekmidas/manifest": "~10.0.0-alpha.83",
+	"@geekmidas/rate-limit": "~10.0.0-alpha.83",
+	"@geekmidas/schema": "~10.0.0-alpha.83",
+	"@geekmidas/services": "~10.0.0-alpha.83",
+	"@geekmidas/storage": "~10.0.0-alpha.83",
+	"@geekmidas/telescope": "~10.0.0-alpha.83",
+	"@geekmidas/testkit": "~10.0.0-alpha.83",
 	"@geekmidas/cli": `~${loadPackageJson().version}`
 };
 //#endregion
@@ -5514,6 +5514,38 @@ coverage/
 	return files;
 }
 //#endregion
+//#region src/init/stagesAction.ts
+/**
+* How a scaffolded workflow names the `stages` action.
+*
+* A published CLI pins it to the commit it was released from: the release
+* build is given that commit as `GKM_RELEASE_COMMIT`, which the build writes
+* into the bundle (`define` in tsdown.config.ts). The action at that commit is
+* the one released beside this CLI, and a commit SHA cannot be moved under a
+* project the way a branch or a tag can.
+*
+* A CLI built anywhere else — a checkout, a local build — knows no released
+* commit, and names `main`.
+*/
+const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+function cliVersion() {
+	try {
+		return require$1("../package.json").version;
+	} catch {
+		return require$1("../../package.json").version;
+	}
+}
+/** The action, as a workflow's `uses:` names it before the `@`. */
+const STAGES_ACTION = "geekmidas/toolbox/actions/stages";
+const COMMIT = /^[0-9a-f]{40}$/;
+/**
+* The `uses:` value for the stages action, with a comment saying which CLI
+* release the pinned commit is.
+*/
+function stagesActionUses(commit = "4dee60bc593ffdfbaa59bbf8d8fe9e3e64f23d41", version = cliVersion()) {
+	return commit && COMMIT.test(commit) ? `${STAGES_ACTION}@${commit} # @geekmidas/cli ${version}` : `${STAGES_ACTION}@main # pin to a commit SHA: see the action's README`;
+}
+//#endregion
 //#region src/init/generators/github.ts
 /**
 * The GitHub workflows a scaffold ships with.
@@ -5523,11 +5555,14 @@ coverage/
 *   release, labelled from their titles.
 * - `deploy.yml` — when a deploy target was picked: a push to main deploys the
 *   stages that are not protected, publishing the drafted release deploys the
-*   protected ones.
+*   protected ones, and a manual run deploys the one stage it names.
 *
-* The deploy workflow names no stage. It reads `stages` from gkm.config.ts at
-* run time, so the config stays the one place stages are declared and a
-* workflow cannot fall out of step with it.
+* The deploy workflow names no stage. Its first job runs the
+* `geekmidas/toolbox/actions/stages` action, which asks the project's own
+* `gkm stages --github-output` which stages the run builds and deploys — so
+* the config stays the one place stages are declared, the rules for each event
+* are tested code in the CLI, and a workflow cannot fall out of step with
+* either.
 */
 /** How each package manager is set up, installs, and runs a script. */
 const TOOLING = {
@@ -5713,46 +5748,21 @@ template: |
   **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION
 `;
 }
-function deploy(options) {
-	const pm = tooling(options);
-	const sst = options.deployTarget === "sst";
-	const credentials = sst ? `
-      # An IAM role GitHub assumes through OIDC — no long-lived AWS keys. Set
-      # AWS_ROLE_ARN as a variable on each environment.
-      - uses: aws-actions/configure-aws-credentials@v4
-        with:
-          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
-          aws-region: ${options.region}
-` : "";
-	const keyDir = `~/.gkm/keys/${require_seeds.projectKey({ name: options.name })}`;
-	const stageSecrets = sst ? credentials : `
-      # The stage's secrets are kept in the encrypted .gkm/secrets/<stage>.json,
-      # and each environment holds its key as GKM_SECRETS_KEY. .gkm/ is
-      # gitignored, so a checkout has the key but not the file: set
-      # secrets.store in gkm.config.ts to a store CI can reach before deploying
-      # from here.
-      # Owner-only, as the CLI writes its own keys. The stage reaches the shell
-      # as a variable, never pasted into the script: on a manual run it is
-      # whatever was typed.
-      - name: Stage secrets key
-        run: |
-          mkdir -p -m 700 ${keyDir}
-          (umask 077 && printf '%s' "$KEY" > ${keyDir}/"$STAGE".key)
-        env:
-          KEY: \${{ secrets.GKM_SECRETS_KEY }}
-          STAGE: \${{ matrix.stage }}
-`;
-	const deployEnv = sst ? "" : `
-          DOKPLOY_API_TOKEN: \${{ secrets.DOKPLOY_API_TOKEN }}
-          DOKPLOY_ENDPOINT: \${{ vars.DOKPLOY_ENDPOINT }}`;
+/**
+* What every deploy workflow starts with: its triggers, and the `stages` job,
+* which asks the project's own gkm (through the stages action) which stages
+* this run builds and deploys. Nothing in a workflow names a stage.
+*/
+function deployHeader(build) {
 	return `name: Deploy
 
 # Which stages exist, and which are protected, is read from \`stages\` in
-# gkm.config.ts — nothing here names one:
+# gkm.config.ts by the project's own gkm, through the stages action — nothing
+# here names one:
 #
-#   push to main       every deployed stage that is not protected
+#   push to main       ${build ? "builds every deployed stage, deploys those not protected" : "every deployed stage that is not protected"}
 #   release published  the protected stages (publish the drafted release)
-#   run workflow       the one stage you name
+#   run workflow       the one stage you name, at the ref you name
 on:
   push:
     branches: [main]
@@ -5763,17 +5773,27 @@ on:
       stage:
         description: A deployed stage from gkm.config.ts
         required: true
+        type: string
+      ref:
+        description: The commit, tag or branch to deploy (default the latest on main)
+        required: false
+        type: string
 
 permissions:
   contents: read
-  id-token: write
-
-jobs:
-  stages:
+`;
+}
+function stagesJob(options) {
+	const pm = tooling(options);
+	return `  stages:
     name: Pick stages
     runs-on: ubuntu-latest
     outputs:
-      stages: \${{ steps.pick.outputs.stages }}
+      build: \${{ steps.stages.outputs.build }}
+      deploy: \${{ steps.stages.outputs.deploy }}
+      has-build: \${{ steps.stages.outputs.has-build }}
+      has-deploy: \${{ steps.stages.outputs.has-deploy }}
+      aws-region: \${{ steps.stages.outputs.aws-region }}
     steps:
       - uses: actions/checkout@v4
 
@@ -5781,44 +5801,286 @@ ${pm.setup}
       - name: Install
         run: ${pm.install}
 
+      # Runs \`gkm stages --github-output\`: the rules for each event are the
+      # installed CLI's, and a manual run naming a stage gkm.config.ts does not
+      # deploy fails here.
       - name: Read stages from gkm.config.ts
-        id: pick
+        id: stages
+        uses: ${stagesActionUses()}
+        with:
+          stage: \${{ inputs.stage }}
+`;
+}
+/**
+* The registry login a compose build pushes with: GitHub's own token on
+* ghcr.io, otherwise a username variable and a password secret.
+*/
+function registryLogin(registry) {
+	const host = registry.split("/")[0];
+	const ghcr = host === "ghcr.io";
+	return `      - uses: docker/login-action@v3
+        with:
+          registry: ${host}
+          username: ${ghcr ? "${{ github.actor }}" : "${{ vars.REGISTRY_USERNAME }}"}
+          password: ${ghcr ? "${{ secrets.GITHUB_TOKEN }}" : "${{ secrets.REGISTRY_PASSWORD }}"}
+`;
+}
+/**
+* The compose deploy: images are built and pushed by the runner, where the
+* code is, and pulled by the server, where the stage runs.
+*
+* - `build` (on a push): every deployed stage's images, tagged with the
+*   commit, and their digests kept as the artifact `digests-<stage>`.
+* - `deploy`: the commit the event names — a release's tag, a manual run's
+*   `ref` — then that commit's push build, whose digests pin each image. Over
+*   SSH, with a pinned host key, the server checks the commit out and runs
+*   `gkm compose` on exactly those images.
+*/
+function composeDeploy(options) {
+	const pm = tooling(options);
+	const registry = options.registry ?? "";
+	return `${deployHeader(true)}
+jobs:
+${stagesJob(options)}
+  build:
+    name: Build \${{ matrix.stage }}
+    needs: stages
+    if: needs.stages.outputs.has-build == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        stage: \${{ fromJSON(needs.stages.outputs.build) }}
+    # One GitHub environment per stage: its secrets, variables and approvals.
+    environment: \${{ matrix.stage }}
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+${pm.setup}
+      - name: Install
+        run: ${pm.install}
+
+${registryLogin(registry)}
+      # A site's public URLs are built into it, so the build reads the stage's
+      # secrets store. With secrets.store on SSM or Secrets Manager the job
+      # assumes the stage's role (AWS_ROLE_ARN, set by gkm deploy:github);
+      # with the default 'file' store there is no role to assume.
+      - name: Assume the stage's AWS role
+        if: needs.stages.outputs.aws-region != ''
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+          aws-region: \${{ needs.stages.outputs.aws-region }}
+
+      # Builds and pushes every image the stage runs, tagged with the commit,
+      # and starts nothing.
+      - name: Build and push
+        run: ${pm.exec} gkm compose --stage "$STAGE" --build --push --tag "$SHA" --digests-file digests.json
+        env:
+          STAGE: \${{ matrix.stage }}
+          SHA: \${{ github.sha }}
+
+      # What each tag pointed at when it was pushed. A deploy runs these
+      # digests, so a tag moved since cannot change what is released.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: digests-\${{ matrix.stage }}
+          path: digests.json
+          retention-days: 90
+
+  deploy:
+    name: Deploy \${{ matrix.stage }}
+    needs: [stages, build]
+    # The build is skipped on a release or a manual run: deploy then anyway,
+    # but never after a failed build.
+    if: \${{ !cancelled() && !failure() && needs.stages.outputs.has-deploy == 'true' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        stage: \${{ fromJSON(needs.stages.outputs.deploy) }}
+    environment: \${{ matrix.stage }}
+    concurrency:
+      group: deploy-\${{ matrix.stage }}
+      cancel-in-progress: false
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      # A release deploys its tag's commit, never its target_commitish — the
+      # branch it was drafted against, which has moved on since.
+      - name: Resolve the commit
+        id: commit
+        run: |
+          case "$EVENT" in
+            release) ref="tags/$TAG" ;;
+            workflow_dispatch) ref="\${REF:-$SHA}" ;;
+            *) ref="$SHA" ;;
+          esac
+          sha=$(gh api "repos/$REPO/commits/$ref" --jq .sha)
+          echo "Deploying $sha"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: \${{ github.token }}
+          REPO: \${{ github.repository }}
+          EVENT: \${{ github.event_name }}
+          TAG: \${{ github.event.release.tag_name }}
+          REF: \${{ inputs.ref }}
+          SHA: \${{ github.sha }}
+
+      # The push run of this workflow that built the commit for this stage:
+      # this run on a push, the newest one with the stage's digests otherwise.
+      - name: Find the commit's push build
+        id: build
         run: |
-          ${pm.exec} tsx -e "
-            import config from './gkm.config.ts';
-            const { deployed, protected: kept = [] } = config.stages;
-            const event = process.env.EVENT;
-            if (event === 'workflow_dispatch' && !deployed.includes(process.env.STAGE)) {
-              console.error('Not a deployed stage: ' + process.env.STAGE + ' (deployed: ' + deployed.join(', ') + ')');
-              process.exit(1);
-            }
-            const stages =
-              event === 'workflow_dispatch' ? [process.env.STAGE]
-              : event === 'release' ? kept
-              : deployed.filter((stage) => !kept.includes(stage));
-            console.log('stages=' + JSON.stringify(stages));
-          " >> "$GITHUB_OUTPUT"
+          if [ "$EVENT" = push ]; then
+            echo "run-id=$RUN_ID" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          workflow=\${WORKFLOW_REF%%@*}
+          workflow=\${workflow##*/}
+          for id in $(gh run list --repo "$REPO" --workflow "$workflow" --event push --commit "$SHA" --limit 20 --json databaseId --jq '.[].databaseId'); do
+            found=$(gh api "repos/$REPO/actions/runs/$id/artifacts?name=$ARTIFACT" --jq '[.artifacts[] | select(.expired | not)] | length')
+            if [ "$found" -gt 0 ]; then
+              echo "run-id=$id" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          done
+          echo "run-id=" >> "$GITHUB_OUTPUT"
         env:
+          GH_TOKEN: \${{ github.token }}
+          REPO: \${{ github.repository }}
           EVENT: \${{ github.event_name }}
-          STAGE: \${{ inputs.stage }}
+          RUN_ID: \${{ github.run_id }}
+          WORKFLOW_REF: \${{ github.workflow_ref }}
+          SHA: \${{ steps.commit.outputs.sha }}
+          ARTIFACT: digests-\${{ matrix.stage }}
+
+      - name: Download digests-\${{ matrix.stage }}
+        if: steps.build.outputs.run-id != ''
+        uses: actions/download-artifact@v4
+        with:
+          name: digests-\${{ matrix.stage }}
+          run-id: \${{ steps.build.outputs.run-id }}
+          github-token: \${{ github.token }}
 
+      - name: No digests — deploying by tag
+        if: steps.build.outputs.run-id == ''
+        run: |
+          echo "::warning title=$STAGE deploys by tag, not digest::No push build of $SHA kept digests-$STAGE (never built, or older than 90 days). The server runs whatever the tag $SHA points at in the registry now, which anyone who can push there could have replaced."
+        env:
+          STAGE: \${{ matrix.stage }}
+          SHA: \${{ steps.commit.outputs.sha }}
+
+      # Each environment holds DEPLOY_SSH_KEY (secret) and DEPLOY_KNOWN_HOSTS,
+      # DEPLOY_HOST, DEPLOY_USER and DEPLOY_PATH (variables): the server's
+      # host key is pinned, never accepted on first sight. DEPLOY_PATH is a
+      # clone of this repository, with a docker login to ${registry.split("/")[0]}
+      # and the stage's secrets.
+      #
+      # Every value reaches the server as an argument to a quoted heredoc —
+      # nothing is pasted into the script.
+      - name: Deploy on the server
+        run: |
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
+          (umask 077 && printf '%s\\n' "$SSH_KEY" > ~/.ssh/deploy_key)
+          printf '%s\\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
+          digests=""
+          if [ -f digests.json ]; then digests=$(base64 -w0 < digests.json); fi
+          ssh -i ~/.ssh/deploy_key -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes \\
+            "$DEPLOY_USER@$DEPLOY_HOST" \\
+            "bash -s -- $(printf '%q ' "$STAGE" "$SHA" "$DEPLOY_PATH" "$digests")" <<'REMOTE'
+          set -euo pipefail
+          stage=$1 sha=$2 dir=$3 digests=$4
+          cd "$dir"
+          git fetch --quiet origin
+          git checkout --quiet --detach "$sha"
+          ${pm.install}
+          args=(--stage "$stage" --tag "$sha")
+          if [ -n "$digests" ]; then
+            mkdir -p .gkm
+            printf '%s' "$digests" | base64 -d > ".gkm/digests-$stage.json"
+            args+=(--digests-file ".gkm/digests-$stage.json")
+          fi
+          ${pm.exec} gkm compose "\${args[@]}"
+          REMOTE
+        env:
+          SSH_KEY: \${{ secrets.DEPLOY_SSH_KEY }}
+          KNOWN_HOSTS: \${{ vars.DEPLOY_KNOWN_HOSTS }}
+          DEPLOY_HOST: \${{ vars.DEPLOY_HOST }}
+          DEPLOY_USER: \${{ vars.DEPLOY_USER }}
+          DEPLOY_PATH: \${{ vars.DEPLOY_PATH }}
+          STAGE: \${{ matrix.stage }}
+          SHA: \${{ steps.commit.outputs.sha }}
+`;
+}
+/**
+* Dokploy and SST: `gkm deploy` builds, releases and health-checks a stage in
+* one step, from a checkout, so there is no separate build job — the stages
+* job's `deploy` list is the matrix, and `build` goes unused.
+*/
+function targetDeploy(options) {
+	const pm = tooling(options);
+	const sst = options.deployTarget === "sst";
+	const credentials = sst ? `
+      # An IAM role GitHub assumes through OIDC — no long-lived AWS keys. Set
+      # AWS_ROLE_ARN as a variable on each environment.
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${options.region}
+` : "";
+	const keyDir = `~/.gkm/keys/${require_seeds.projectKey({ name: options.name })}`;
+	const stageSecrets = sst ? credentials : `
+      # The stage's secrets are kept in the encrypted .gkm/secrets/<stage>.json,
+      # and each environment holds its key as GKM_SECRETS_KEY. .gkm/ is
+      # gitignored, so a checkout has the key but not the file: set
+      # secrets.store in gkm.config.ts to a store CI can reach before deploying
+      # from here.
+      # Owner-only, as the CLI writes its own keys. The stage reaches the shell
+      # as a variable, never pasted into the script: on a manual run it is
+      # whatever was typed.
+      - name: Stage secrets key
+        run: |
+          mkdir -p ${keyDir} && chmod 700 ${keyDir}
+          (umask 077 && printf '%s' "$KEY" > ${keyDir}/"$STAGE".key)
+        env:
+          KEY: \${{ secrets.GKM_SECRETS_KEY }}
+          STAGE: \${{ matrix.stage }}
+`;
+	const deployEnv = sst ? "" : `
+          DOKPLOY_API_TOKEN: \${{ secrets.DOKPLOY_API_TOKEN }}
+          DOKPLOY_ENDPOINT: \${{ vars.DOKPLOY_ENDPOINT }}`;
+	return `${deployHeader(false)}
+jobs:
+${stagesJob(options)}
   deploy:
     name: Deploy \${{ matrix.stage }}
     needs: stages
-    if: needs.stages.outputs.stages != '[]'
+    if: needs.stages.outputs.has-deploy == 'true'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        stage: \${{ fromJSON(needs.stages.outputs.stages) }}
+        stage: \${{ fromJSON(needs.stages.outputs.deploy) }}
     # One GitHub environment per stage: its secrets and variables, and any
     # approval rule you put on a protected one.
     environment: \${{ matrix.stage }}
     concurrency:
       group: deploy-\${{ matrix.stage }}
       cancel-in-progress: false
+    permissions:
+      contents: read${sst ? "\n      id-token: write" : ""}
     steps:
+      # The event's own commit — a release's tag, the push — or the ref a
+      # manual run names.
       - uses: actions/checkout@v4
+        with:
+          ref: \${{ inputs.ref }}
 
 ${pm.setup}
       - name: Install
@@ -5832,6 +6094,9 @@ ${stageSecrets}
           STAGE: \${{ matrix.stage }}${deployEnv}
 `;
 }
+function deploy(options) {
+	return options.deployTarget === "compose" ? composeDeploy(options) : targetDeploy(options);
+}
 function generateGithubFiles(options) {
 	const files = [
 		{
@@ -6672,6 +6937,11 @@ export type ListUsersResponse = z.infer<typeof ListUsersResponseSchema>;
 const perStage = (options, command) => Object.fromEntries(options.stages.deployed.map((stage) => [`deploy:${stage}`, command(stage)]));
 function deployPackage(options) {
 	switch (options.deployTarget) {
+		case "compose": return {
+			scripts: perStage(options, (stage) => `gkm compose --stage ${stage}`),
+			dependencies: {},
+			devDependencies: {}
+		};
 		case "dokploy": return {
 			scripts: perStage(options, (stage) => `gkm deploy --stage ${stage}`),
 			dependencies: {},
@@ -7181,6 +7451,13 @@ ${workspaceConstructsGlobs(options.routesStructure, (0, node_path.dirname)(optio
 * `gkm build` builds for, and which backends a cache or a broker resolves to.
 */
 function deployBlock(options) {
+	if (options.deployTarget === "compose") return `
+  // \`gkm compose --stage <stage>\` runs a stage as one Docker Compose stack on
+  // the machine it runs on. CI builds every image and pushes it here; the
+  // server pulls exactly those. On ghcr.io the owner is the repository's —
+  // the user or organisation whose packages the workflow's token can write.
+  deploy: { default: 'compose', registry: '${options.registry}' },
+`;
 	if (options.deployTarget !== "sst") return "";
 	return `
   // \`gkm deploy\` runs \`sst deploy\` on the manifest \`gkm build\` writes to
@@ -9757,6 +10034,11 @@ const deployTargetChoices = [
 		value: "dokploy",
 		description: "Deploy to Dokploy (Docker-based hosting)"
 	},
+	{
+		title: "Server (Docker Compose)",
+		value: "compose",
+		description: "One Docker Compose stack per stage on your own server; CI builds the images"
+	},
 	{
 		title: "AWS (SST)",
 		value: "sst",
@@ -9894,6 +10176,13 @@ async function initCommand(projectName, options = {}) {
 			message: "AWS region (e.g. eu-west-1):",
 			validate: (value) => AWS_REGION.test(value.trim()) || "An AWS region, like eu-west-1"
 		},
+		{
+			type: (_prev, values) => !options.yes && !options.registry && (options.deploy ?? values.deployTarget) === "compose" ? "text" : null,
+			name: "registry",
+			message: "Container registry CI pushes to (e.g. ghcr.io/<your GitHub owner>):",
+			initial: (_prev, values) => defaultRegistry(projectName || options.name || values.name),
+			validate: (value) => value.trim().length > 0 || "A registry, like ghcr.io/acme"
+		},
 		{
 			type: options.yes || options.stages ? null : "text",
 			name: "deployedStages",
@@ -9995,6 +10284,7 @@ async function initCommand(projectName, options = {}) {
 		packageManager: pkgManager,
 		deployTarget,
 		stages: resolveStages(options, answers),
+		...deployTarget === "compose" ? { registry: options.registry ?? answers.registry?.trim() ?? defaultRegistry(name) } : {},
 		...deployTarget === "sst" ? { region: options.region ?? (options.yes ? "eu-west-1" : answers.region?.trim()) } : {},
 		constructs,
 		frontendFramework
@@ -10166,6 +10456,13 @@ function printNextSteps(projectName, options, pkgManager) {
 		for (const stage of deployed) console.log(`  ${require_utils.getRunCommand(pkgManager, `deploy:${stage}`)}`);
 		console.log("");
 	}
+	if (options.deployTarget === "compose") {
+		console.log("🚀 Deployment (Docker Compose, on your server):");
+		console.log(`  Images are pushed to ${options.registry}; .github/workflows/deploy.yml builds them`);
+		console.log("  and runs gkm compose on the server over SSH. See the comments in it for the");
+		console.log("  environment variables and secrets each stage needs.");
+		console.log("");
+	}
 	if (options.deployTarget === "sst") {
 		console.log("🚀 Deployment (AWS, through SST):");
 		for (const stage of deployed) console.log(`  ${require_utils.getRunCommand(pkgManager, `deploy:${stage}`)}  # gkm deploy: build, sst deploy, health checks`);
@@ -10205,6 +10502,14 @@ var UnknownDeployTarget = class extends Error {
 		this.name = "UnknownDeployTarget";
 	}
 };
+/**
+* Where a compose deploy's images go when nobody said: GitHub's registry,
+* under an owner named after the project. The generated config says to change
+* it to the repository's owner, whose packages the workflow's token can write.
+*/
+function defaultRegistry(name) {
+	return `ghcr.io/${(name ?? "my-org").toLowerCase()}`;
+}
 /** `--region` that is not shaped like one, e.g. `europe` for `eu-west-1`. */
 var NotAnAwsRegion = class extends Error {
 	region;
@@ -10909,7 +11214,7 @@ function testDatabases(reconciled) {
 * starts without the reference data the app needs.
 */
 async function migrateTestStage(workspace, env) {
-	const { migrateAndSeed } = await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs"));
+	const { migrateAndSeed } = await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs"));
 	const { discover } = await Promise.resolve().then(() => require("./discover-D1It5r_h.cjs")).then((n) => n.discover_exports);
 	const sources = {};
 	const manifest = await discover({
@@ -11245,7 +11550,7 @@ const program = new commander.Command();
 program.name("gkm").description("GeekMidas backend framework CLI").version(version).option("--cwd <path>", "Change working directory").option("--debug", "Enable debug mode (verbose errors with stack traces)").hook("preAction", () => {
 	if (program.opts().debug);
 });
-program.command("init").description("Scaffold a new project").argument("[name]", "Project name").option("--template <template>", "Project template (minimal, api, serverless, worker)").option("--skip-install", "Skip dependency installation", false).option("-y, --yes", "Skip prompts, use defaults", false).option("--monorepo", "Setup as monorepo with packages/models", false).option("--api-path <path>", "API app path in monorepo (default: apps/api)").option("--pm <manager>", "Package manager (pnpm, npm, yarn, bun)").option("--deploy <target>", "Where it deploys (dokploy, sst, none)").option("--region <region>", "AWS region for an SST deploy (e.g. eu-west-1)").option("--stages <names>", "Deployed stages, comma-separated (e.g. staging,prod)").option("--protected-stage <name>", "Which deployed stage is production").option("--local-stage <name>", "What gkm dev runs as (e.g. dev)").action(async (name, options) => {
+program.command("init").description("Scaffold a new project").argument("[name]", "Project name").option("--template <template>", "Project template (minimal, api, serverless, worker)").option("--skip-install", "Skip dependency installation", false).option("-y, --yes", "Skip prompts, use defaults", false).option("--monorepo", "Setup as monorepo with packages/models", false).option("--api-path <path>", "API app path in monorepo (default: apps/api)").option("--pm <manager>", "Package manager (pnpm, npm, yarn, bun)").option("--deploy <target>", "Where it deploys (dokploy, compose, sst, none)").option("--region <region>", "AWS region for an SST deploy (e.g. eu-west-1)").option("--registry <registry>", "Container registry for a compose deploy (e.g. ghcr.io/acme)").option("--stages <names>", "Deployed stages, comma-separated (e.g. staging,prod)").option("--protected-stage <name>", "Which deployed stage is production").option("--local-stage <name>", "What gkm dev runs as (e.g. dev)").action(async (name, options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -11353,7 +11658,7 @@ program.command("migrate").description("Apply each database construct's migratio
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { migrateCommand } = await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs"));
+		const { migrateCommand } = await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs"));
 		await migrateCommand({
 			...options,
 			...construct ? { construct } : {}
@@ -11367,7 +11672,7 @@ program.command("seed").description("Migrate, then run each database construct's
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { seedCommand } = await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs"));
+		const { seedCommand } = await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs"));
 		await seedCommand({
 			...options,
 			...construct ? { construct } : {}
@@ -11381,7 +11686,7 @@ program.command("migration").description("Write a construct's next migration: an
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { migrationCommand } = await Promise.resolve().then(() => require("./migrate-BlYiMA23.cjs"));
+		const { migrationCommand } = await Promise.resolve().then(() => require("./migrate-BgPWVnAZ.cjs"));
 		await migrationCommand({
 			construct,
 			...name ? { name } : {}
@@ -11406,11 +11711,15 @@ program.command("api").description("Manage REST API endpoints").action(() => {
 	if (globalOptions.cwd) process.chdir(globalOptions.cwd);
 	process.stdout.write("REST API management - coming soon\n");
 });
-program.command("openapi").description("Generate OpenAPI specification from endpoints").option("--app <name>", "Workspace mode: generate for a single named backend app").action(async (options) => {
+program.command("openapi").description("Generate OpenAPI specification from endpoints").option("--app <name>", "Workspace mode: generate for a single named backend app").option("--telemetry [sampleRate]", "Generated clients send W3C trace context to their API by default, at the stage's sample rate (0-1, default 1)").action(async (options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		await require_openapi.openapiCommand({ app: options.app });
+		const telemetry = require_EndpointGenerator.parseTelemetryFlag(options.telemetry);
+		await require_openapi.openapiCommand({
+			app: options.app,
+			...telemetry !== void 0 ? { telemetry } : {}
+		});
 	} catch (error) {
 		console.error(formatError(error));
 		process.exit(1);
@@ -11485,7 +11794,7 @@ program.command("secrets:add").description("Build the keys a stage must be given
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { secretsAddCommand } = await Promise.resolve().then(() => require("./add-DF9IHQov.cjs"));
+		const { secretsAddCommand } = await Promise.resolve().then(() => require("./add-Bwddb4KD.cjs"));
 		await secretsAddCommand(options);
 	} catch (error) {
 		console.error(formatError(error));
@@ -11496,7 +11805,7 @@ program.command("encryption:rotate").description("Add a new current key to an En
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { encryptionRotateCommand } = await Promise.resolve().then(() => require("./encryption-9YA5ThNl.cjs"));
+		const { encryptionRotateCommand } = await Promise.resolve().then(() => require("./encryption-CxTfRx4h.cjs"));
 		await encryptionRotateCommand(construct, options);
 	} catch (error) {
 		console.error(formatError(error));
@@ -11507,7 +11816,7 @@ program.command("encryption:retire").description("Remove an old key from an Encr
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { encryptionRetireCommand } = await Promise.resolve().then(() => require("./encryption-9YA5ThNl.cjs"));
+		const { encryptionRetireCommand } = await Promise.resolve().then(() => require("./encryption-CxTfRx4h.cjs"));
 		await encryptionRetireCommand(construct, key, options);
 	} catch (error) {
 		console.error(formatError(error));
@@ -11550,7 +11859,7 @@ program.command("secrets:reconcile").description("Backfill missing custom secret
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
 		const { loadWorkspaceConfig } = await Promise.resolve().then(() => require("./config.cjs"));
 		const { reconcileMissingSecrets } = await Promise.resolve().then(() => require("./reconcile-CuCQBa5-.cjs"));
-		const { secretsStoreFor } = await Promise.resolve().then(() => require("./seeds-BjHiy9tW.cjs")).then((n) => n.store_exports);
+		const { secretsStoreFor } = await Promise.resolve().then(() => require("./seeds-Ccju3zGl.cjs")).then((n) => n.store_exports);
 		const { workspace } = await loadWorkspaceConfig();
 		const stage = options.stage ?? workspace.stages.local;
 		const store = await secretsStoreFor(workspace, stage);
@@ -11559,7 +11868,7 @@ program.command("secrets:reconcile").description("Backfill missing custom secret
 			console.error(`No secrets found for stage "${stage}". Run "gkm secrets:init --stage ${stage}" first.`);
 			process.exit(1);
 		}
-		const { derivedContainers } = await Promise.resolve().then(() => require("./seeds-BjHiy9tW.cjs")).then((n) => n.workspace_exports);
+		const { derivedContainers } = await Promise.resolve().then(() => require("./seeds-Ccju3zGl.cjs")).then((n) => n.workspace_exports);
 		const result = reconcileMissingSecrets(secrets, workspace, await derivedContainers(workspace, stage));
 		if (!result) {
 			console.log(`\n✓ Secrets for stage "${stage}" are up-to-date`);
@@ -11577,7 +11886,7 @@ program.command("secrets:migrate").description("Copy a deployed stage's secrets
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { secretsMigrateCommand } = await Promise.resolve().then(() => require("./migrate-C440QQvZ.cjs"));
+		const { secretsMigrateCommand } = await Promise.resolve().then(() => require("./migrate-Bemd4tkz.cjs"));
 		await secretsMigrateCommand(options);
 	} catch (error) {
 		console.error(formatError(error));
@@ -11585,7 +11894,7 @@ program.command("secrets:migrate").description("Copy a deployed stage's secrets
 	}
 });
 program.command("deploy").description("Deploy a stage through its target").option("--target <name>", "Deploy target: dokploy, compose, sst, or one named in deploy.targets (default: deploy.default)").option("--provider <provider>", "[DEPRECATED] Use --target instead").requiredOption("--stage <stage>", "Deployment stage (e.g., production, staging)").option("--tag <tag>", "Image tag (default: stage-timestamp; compose: the commit). Compose pulls a given tag").option("--skip-push", "Skip pushing image to registry").option("--skip-build", "Skip build step (use existing build)").option("--json", "Write events as JSON lines instead of progress; never prompts").option("--dry-run", "Show what would be created or reused; change, build and push nothing").option("--atomic", "If the release fails, roll back every app it released, not only the failed ones").option("--allow-dev-services <list>", "Server targets: run MinIO and/or Mailpit (minio,mailpit) for mail and buckets the stage's secrets don't configure. Not production-grade").action(async (options) => {
-	const { deployCli } = await Promise.resolve().then(() => require("./cli-BB1KOkfo.cjs"));
+	const { deployCli } = await Promise.resolve().then(() => require("./cli-DO7DQqCq.cjs"));
 	const globalOptions = program.opts();
 	const code = await deployCli({
 		cwd: (0, node_path.resolve)(globalOptions.cwd ?? process.cwd()),
@@ -11602,7 +11911,7 @@ program.command("deploy").description("Deploy a stage through its target").optio
 });
 program.command("deploy:rollback").description("Put a stage's app back on its previous release (Dokploy): one app with --app, every app with --atomic").requiredOption("--stage <stage>", "A deployed stage").option("--app <app>", "The app to roll back").option("--atomic", "Roll back every app that has an earlier release").action(async (options) => {
 	try {
-		const { rollbackStage } = await Promise.resolve().then(() => require("./rollback-P09wRaW4.cjs")).then((n) => n.rollback_exports);
+		const { rollbackStage } = await Promise.resolve().then(() => require("./rollback-BVQFDjxr.cjs")).then((n) => n.rollback_exports);
 		const { terminalCredentials } = await Promise.resolve().then(() => require("./terminal-BL5E0xbR.cjs"));
 		const globalOptions = program.opts();
 		await rollbackStage({
@@ -11638,13 +11947,24 @@ program.command("deploy:github").description("Let GitHub Actions deploy a stage:
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { deployGithubCommand } = await Promise.resolve().then(() => require("./github-BM-Y9M2G.cjs"));
+		const { deployGithubCommand } = await Promise.resolve().then(() => require("./github-Dukt5cJe.cjs"));
 		await deployGithubCommand(options);
 	} catch (error) {
 		console.error(formatError(error));
 		process.exit(1);
 	}
 });
+program.command("stages").description("The workspace's stages from gkm.config.ts: local, deployed and protected").option("--json", "Print them as JSON").option("--github-output", "Write the stages, and which this workflow run builds and deploys, to $GITHUB_OUTPUT").option("--event <name>", "The event to plan for (default: $GITHUB_EVENT_NAME)").option("--stage <stage>", "The stage a workflow_dispatch deploys").action(async (options) => {
+	try {
+		const globalOptions = program.opts();
+		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
+		const { stagesCommand } = await Promise.resolve().then(() => require("./stages-CwrYVX9u.cjs"));
+		await stagesCommand(options);
+	} catch (error) {
+		console.error(formatError(error));
+		process.exit(1);
+	}
+});
 program.command("deploy:list").description("List Dokploy resources (projects, registries)").option("--endpoint <url>", "Dokploy server URL (uses stored credentials if logged in)").option("--projects", "List projects").option("--registries", "List registries").action(async (options) => {
 	try {
 		const globalOptions = program.opts();