test: cover customer local setup journey

Author: fforootd

.changeset/customer-local-journey.md

@@ -0,0 +1,4 @@
+---
+---
+
+Exercise the customer local setup journey in the consumer e2e gate.

.github/instructions/consumer-journey.instructions.md

@@ -4,11 +4,14 @@ applyTo: "apps/cli-journey-e2e/**,.github/workflows/ci.yml"
 
 # Consumer Journey Review Instructions
 
-Review consumer journey changes as a required fresh-app quality gate, not as a
-demo-app e2e suite.
+Review consumer journey changes as the required customer local setup quality
+gate, not as a demo-app e2e suite.
 
 - CI must consume the current workflow's GoReleaser image and npm package
   tarballs. Do not replace this with public npm packages for Zitadel packages.
+- The journey must exercise the customer local runtime flow through `npx`:
+  `doctor`, `start`, then `setup --framework next --server local` with
+  `--non-interactive --json`.
 - Produce package artifacts with `corepack pnpm --dir <package> pack` and keep
   tarball verification for required package presence plus unresolved
   `catalog:` or `workspace:` dependency specs.
@@ -23,6 +26,7 @@ demo-app e2e suite.
 - Browser tests should run serially with one worker, use `localhost` for
   WebAuthn, and require passkey coverage in CI. `JOURNEY_ENABLE_PASSKEY=0` is
   only a local debugging escape hatch.
-- Failure artifacts should include Playwright output/report, setup JSON,
-  setup stderr, metadata, generated app package manifests, Verdaccio logs, Next
-  logs, and backend logs. Do not upload generated `node_modules` or `.next`.
+- Failure artifacts should include Playwright output/report, doctor/start/setup
+  JSON and stderr, local runtime metadata/logs, metadata, generated app package
+  manifests, Verdaccio logs, and Next logs. Do not upload generated
+  `node_modules` or `.next`.

.github/workflows/ci.yml

@@ -305,75 +305,6 @@ jobs:
           docker load -i goreleaser-dist/nextgen-image.tar
           docker image inspect -f '{{.Os}}/{{.Architecture}}' "$(cat goreleaser-dist/nextgen-image.tag)" | grep -q '^linux/amd64$'
 
-      - name: Smoke test CLI-style local runtime image
-        run: |
-          set -euo pipefail
-          IMAGE="$(cat goreleaser-dist/nextgen-image.tag)"
-          DATA_DIR="$RUNNER_TEMP/nextgen-dev-data"
-          RUNTIME_DIR="$RUNNER_TEMP/nextgen-dev-runtime"
-          HOST_UID="$(id -u)"
-          HOST_GID="$(id -g)"
-          PASSWD_FILE="$RUNTIME_DIR/container-passwd"
-          GROUP_FILE="$RUNTIME_DIR/container-group"
-          mkdir -p "$DATA_DIR" "$RUNTIME_DIR"
-          # Mirror `zitadel start`: run the container as the host user so
-          # bind-mounted state stays editable, and provide passwd/group entries
-          # because embedded Postgres initdb refuses unknown numeric users.
-          {
-            echo "root:x:0:0:root:/root:/bin/sh"
-            echo "nonroot:x:65532:65532:nonroot:/nonexistent:/usr/sbin/nologin"
-            echo "zitadel-local:x:${HOST_UID}:${HOST_GID}:Zitadel local user:/tmp:/usr/sbin/nologin"
-          } > "$PASSWD_FILE"
-          {
-            echo "root:x:0:"
-            echo "nonroot:x:65532:"
-            echo "zitadel-local:x:${HOST_GID}:"
-          } > "$GROUP_FILE"
-          CONTAINER="$(
-            docker run -d \
-              -p 127.0.0.1:18080:8080 \
-              -v "$DATA_DIR:/var/lib/zitadel/nextgen-data" \
-              -v "$PASSWD_FILE:/etc/passwd:ro" \
-              -v "$GROUP_FILE:/etc/group:ro" \
-              --user "${HOST_UID}:${HOST_GID}" \
-              -e NEXTGEN_SERVER_ADDRESS=:8080 \
-              -e NEXTGEN_SERVER_DATA_DIR=/var/lib/zitadel/nextgen-data \
-              "$IMAGE"
-          )"
-          cleanup() {
-            docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
-          }
-          diagnose() {
-            docker logs "$CONTAINER" || true
-          }
-          trap cleanup EXIT
-
-          ready=0
-          for _ in $(seq 1 120); do
-            if curl -fsS http://localhost:18080/healthz >/dev/null; then
-              ready=1
-              break
-            fi
-            sleep 1
-          done
-          if [ "$ready" -ne 1 ]; then
-            echo "::error::timed out waiting for zero-config /healthz"
-            diagnose
-            exit 1
-          fi
-          test -f "$DATA_DIR/server-encryption-key"
-          if ! curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:18080/ui/console/ | grep -q '^200$'; then
-            echo "::error::zero-config /ui/console/ did not return 200"
-            diagnose
-            exit 1
-          fi
-          if ! curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:18080/ui/login/ | grep -q '^200$'; then
-            echo "::error::zero-config /ui/login/ did not return 200"
-            diagnose
-            exit 1
-          fi
-          echo "CLI-style local runtime image smoke test passed"
-
       - name: Prepare quick-start compose stack
         run: |
           mkdir -p nextgen_quickstart
@@ -400,8 +331,9 @@ jobs:
       - name: Start stack and verify HTTP endpoints
         run: |
           set -euo pipefail
-          # Separate from the CLI-style smoke above: this keeps the documented
-          # compose fallback valid for operators/manual quick-start usage.
+          # Separate from the customer local setup journey: this keeps the
+          # documented compose fallback valid for operators/manual quick-start
+          # usage.
           COMPOSE=(docker compose -f nextgen_quickstart/docker-compose.yaml --env-file nextgen_quickstart/.env)
           "${COMPOSE[@]}" up -d --wait
           ready=0
@@ -682,32 +614,11 @@ jobs:
           test -f goreleaser-dist/nextgen-image.tag
           docker load -i goreleaser-dist/nextgen-image.tar
           docker image inspect -f '{{.Os}}/{{.Architecture}}' "$(cat goreleaser-dist/nextgen-image.tag)" | grep -q '^linux/amd64$'
-
-      - name: Start backend stack
-        run: |
-          mkdir -p "$RUNNER_TEMP/nextgen-journey"
-          cp docs/operations/docker-compose.yaml "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml"
-          IMAGE="$(cat goreleaser-dist/nextgen-image.tag)"
-          {
-            echo "NEXTGEN_IMAGE=${IMAGE}"
-            echo "NEXTGEN_PORT=8080"
-          } > "$RUNNER_TEMP/nextgen-journey/.env"
-          docker compose -f "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml" --env-file "$RUNNER_TEMP/nextgen-journey/.env" up -d --wait
-          for _ in $(seq 1 90); do
-            if curl -fsS http://localhost:8080/healthz >/dev/null; then
-              exit 0
-            fi
-            sleep 1
-          done
-          echo "::error::timed out waiting for backend /healthz"
-          docker compose -f "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml" --env-file "$RUNNER_TEMP/nextgen-journey/.env" logs nextgen
-          exit 1
+          echo "ZITADEL_LOCAL_IMAGE=$(cat goreleaser-dist/nextgen-image.tag)" >> "$GITHUB_ENV"
 
       - name: Prepare fresh Next.js app
         id: prepare-app
         env:
-          JOURNEY_BACKEND_URL: http://localhost:8080
-          JOURNEY_CREATE_NEXT_APP_VERSION: 16.2.4
           JOURNEY_REGISTRY_URL: http://127.0.0.1:4873
           JOURNEY_WORK_DIR: ${{ runner.temp }}/zitadel-cli-journey
         run: node apps/cli-journey-e2e/scripts/prepare-next-app.mjs
@@ -735,17 +646,32 @@ jobs:
       - name: Collect diagnostics
         if: failure()
         run: |
-          docker compose -f "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml" --env-file "$RUNNER_TEMP/nextgen-journey/.env" logs > "$RUNNER_TEMP/backend-compose.log" 2>&1 || true
           DIAG_DIR="$RUNNER_TEMP/consumer-journey-diagnostics"
+          APP_DIR="$RUNNER_TEMP/zitadel-cli-journey/myapp"
           mkdir -p "$DIAG_DIR/generated-app"
-          cp "$RUNNER_TEMP/backend-compose.log" "$DIAG_DIR/" 2>/dev/null || true
+          if [ -d "$APP_DIR" ]; then
+            (
+              cd "$APP_DIR"
+              npm_config_registry=http://127.0.0.1:4873 \
+              npm_config_yes=true \
+              npm_config_audit=false \
+              npm_config_fund=false \
+              npx --yes @zitadel/cli@alpha logs --tail 400 --non-interactive --json \
+                > "$DIAG_DIR/logs.json" 2> "$DIAG_DIR/logs.stderr.log"
+            ) || true
+          fi
           cp "$RUNNER_TEMP/next-app.log" "$DIAG_DIR/" 2>/dev/null || true
           cp "$RUNNER_TEMP/verdaccio.log" "$DIAG_DIR/" 2>/dev/null || true
+          cp "$RUNNER_TEMP/zitadel-cli-journey/doctor.json" "$DIAG_DIR/" 2>/dev/null || true
+          cp "$RUNNER_TEMP/zitadel-cli-journey/doctor.stderr.log" "$DIAG_DIR/" 2>/dev/null || true
+          cp "$RUNNER_TEMP/zitadel-cli-journey/start.json" "$DIAG_DIR/" 2>/dev/null || true
+          cp "$RUNNER_TEMP/zitadel-cli-journey/start.stderr.log" "$DIAG_DIR/" 2>/dev/null || true
           cp "$RUNNER_TEMP/zitadel-cli-journey/setup.json" "$DIAG_DIR/" 2>/dev/null || true
           cp "$RUNNER_TEMP/zitadel-cli-journey/setup.stderr.log" "$DIAG_DIR/" 2>/dev/null || true
           cp "$RUNNER_TEMP/zitadel-cli-journey/metadata.json" "$DIAG_DIR/" 2>/dev/null || true
-          cp "$RUNNER_TEMP/zitadel-cli-journey/myapp/package.json" "$DIAG_DIR/generated-app/" 2>/dev/null || true
-          cp "$RUNNER_TEMP/zitadel-cli-journey/myapp/package-lock.json" "$DIAG_DIR/generated-app/" 2>/dev/null || true
+          cp "$APP_DIR/.zitadel/local/runtime.json" "$DIAG_DIR/runtime.json" 2>/dev/null || true
+          cp "$APP_DIR/package.json" "$DIAG_DIR/generated-app/" 2>/dev/null || true
+          cp "$APP_DIR/package-lock.json" "$DIAG_DIR/generated-app/" 2>/dev/null || true
 
       - name: Upload consumer journey diagnostics
         if: failure()
@@ -763,7 +689,15 @@ jobs:
         if: always()
         run: |
           if [ -n "${NEXT_APP_PID:-}" ]; then kill "$NEXT_APP_PID" 2>/dev/null || true; fi
-          if [ -n "${VERDACCIO_PID:-}" ]; then kill "$VERDACCIO_PID" 2>/dev/null || true; fi
-          if [ -f "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml" ]; then
-            docker compose -f "$RUNNER_TEMP/nextgen-journey/docker-compose.yaml" --env-file "$RUNNER_TEMP/nextgen-journey/.env" down -v
+          APP_DIR="$RUNNER_TEMP/zitadel-cli-journey/myapp"
+          if [ -d "$APP_DIR" ]; then
+            (
+              cd "$APP_DIR"
+              npm_config_registry=http://127.0.0.1:4873 \
+              npm_config_yes=true \
+              npm_config_audit=false \
+              npm_config_fund=false \
+              npx --yes @zitadel/cli@alpha reset --force --non-interactive --json
+            ) || true
           fi
+          if [ -n "${VERDACCIO_PID:-}" ]; then kill "$VERDACCIO_PID" 2>/dev/null || true; fi

AGENTS.md

@@ -137,13 +137,13 @@ The local reproduction command for the fresh-app consumer journey gate is:
 corepack pnpm run journey
 ```
 
-This runner requires Docker for Verdaccio. By default it starts the backend from
-source with embedded Postgres, ensures the Playwright Chromium browsers are
-installed, builds and packs local npm packages with pnpm, creates a temporary
-Next.js app outside the repo, runs CLI setup through npm, starts the generated
-app on `localhost`, and runs Playwright with one worker. Use
-`-- --backend image --image <docker-tag>` to run the backend through the local
-compose profile for image parity.
+This runner requires Docker for Verdaccio and the CLI-managed local runtime. By
+default it builds a local runtime image, ensures the Playwright Chromium
+browsers are installed, builds and packs local npm packages with pnpm, creates
+an empty app directory outside the repo, runs `npx @zitadel/cli@alpha doctor`,
+`start`, and `setup --framework next --server local`, starts the generated app
+on `localhost`, and runs Playwright with one worker. Use
+`-- --image <docker-tag>` to reuse an existing local runtime image.
 
 In CI the dedicated `node-e2e` job (in `.github/workflows/ci.yml`) gates merges
 on the checked-in demo integrations. The separate `consumer-journey-e2e` job is
@@ -170,7 +170,7 @@ upward**. When deciding where a new test belongs:
 
 The consumer journey suite is the exception to the checked-in demo ownership
 rule: it belongs in `apps/cli-journey-e2e/` and must exercise a freshly
-generated app because it protects the real CLI onboarding path.
+generated app because it protects the customer local setup path.
 
 A new test belongs at e2e level only when the boundary it covers is
 exclusively the framework integration (middleware, cookie origin, full

README.md

@@ -137,16 +137,17 @@ Use `corepack pnpm --silent run cli -- ... --json` when a script needs
 parseable CLI stdout. Plain `pnpm run` prints its own script prelude before
 the command output.
 
-Fresh-app consumer journey check:
+Customer local setup journey check:
 
 ```sh
 corepack pnpm run journey
 ```
 
 This opt-in check ensures the Playwright Chromium browsers are installed, builds
-the local npm packages, publishes them to a temporary Verdaccio registry, starts
-a source backend with embedded Postgres, scaffolds a new Next.js app outside the
-repo, and verifies registration/login journeys against the generated app.
+the local npm packages, publishes them to a temporary Verdaccio registry, runs
+`npx @zitadel/cli@alpha doctor`, `start`, and
+`setup --framework next --server local` in an empty app directory, starts the
+generated app, and verifies registration/login journeys.
 
 ## CI
 
@@ -158,13 +159,15 @@ Pull requests and pushes to `main` run:
 - npm package dry-run/pack checks.
 - A non-publishing GoReleaser snapshot.
 - `consumer-journey-e2e`, which downloads the current workflow's GoReleaser
-  snapshot image and npm package tarballs, installs them through a temporary
-  npm registry into a fresh Next.js app, and runs the Playwright user journey.
+  snapshot image and npm package tarballs, installs the CLI through a temporary
+  npm registry, runs the customer local setup commands in a fresh app directory,
+  and runs the Playwright user journey against the generated app.
 
 CI uploads short-lived workflow artifacts for review: GoReleaser snapshot output
 and npm package tarballs. On consumer journey failures it also uploads focused
-diagnostics such as Playwright traces, setup JSON, package lock metadata, and
-service logs. These artifacts expire after 7 days and are not release artifacts.
+diagnostics such as Playwright traces, doctor/start/setup JSON, package lock
+metadata, local runtime logs, and service logs. These artifacts expire after 7
+days and are not release artifacts.
 
 ## Build & release
 

apps/cli-journey-e2e/AGENTS.md

@@ -5,8 +5,10 @@ These instructions apply to `apps/cli-journey-e2e/**`. Defer to the root
 
 ## Purpose
 
-This project protects the real consumer onboarding journey. Tests must exercise
-a freshly generated Next.js app, not the checked-in demo apps.
+This project protects the customer local setup journey. Tests must exercise a
+fresh app directory that runs the CLI local runtime path (`doctor`, `start`,
+`setup --server local`) before starting the generated Next.js app. It must not
+test the checked-in demo apps.
 
 ## Maintenance Rules
 
@@ -17,6 +19,9 @@ a freshly generated Next.js app, not the checked-in demo apps.
   protocols.
 - CI must install Zitadel packages from current workflow tarballs through the
   temporary Verdaccio registry, not from public npm.
+- CI must run `npx @zitadel/cli@alpha doctor`, `start`, and
+  `setup --framework next --server local` from the fresh app directory with
+  `--non-interactive --json`.
 - Pack and upload only the public packages:
   `@zitadel/cli`, `@zitadel/api`, `@zitadel/components`,
   `@zitadel/sdk-core`, `@zitadel/sdk-next`, `@zitadel/sdk-nuxt`,