@catladder/cli 0.0.0-fix-materialize-binary-image-files-37469f1f → 0.0.0-fix-github-artifact-symlinks-3a2c1c28

package/dist/skills/catladder-builds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catladder-builds
-description: Configuring how a component is built in a catladder project — the `build` config in catladder.ts (build types node / rails / meteor / custom, build & start commands, artifacts, caching, lint/test/audit jobs, the Docker image, project-declared job images, and shared workspace builds). Use when adding or changing a component's build, choosing a build type, wiring a Dockerfile/nginx image, declaring a custom CI job image (`images` config), tuning the build/test/lint jobs, or setting up a monorepo workspace build. Triggers on "build config", "buildCommand", "build type", "Dockerfile", "docker image", "job image", "jobImage", "custom image", "project image", "rails build", "monorepo build", "artifacts".
+description: Configuring how a component is built in a catladder project — the `build` config in catladder.ts (build types node / rails / meteor / custom, build & start commands, artifacts, caching, lint/test/audit jobs, the Docker image, project-declared job images, and shared workspace builds). Use when adding or changing a component's build, choosing a build type, wiring a Dockerfile/nginx image, declaring a custom CI job image (`images` config), tuning the build/test/lint jobs, adding e2e tests against the build (`postBuildTests`), or setting up a monorepo workspace build. Triggers on "build config", "postBuildTests", "post-build test", "e2e", "playwright", "buildCommand", "build type", "Dockerfile", "docker image", "job image", "jobImage", "custom image", "project image", "rails build", "monorepo build", "artifacts".
 ---
 
 # Component builds with catladder
@@ -66,6 +66,10 @@ type: `build: { from: "web" }` (see workspace builds below).
   won't run).
 - `lint` / `test` / `audit` — customize (`{ command, jobImage, … }`) or
   set to `false` to disable that job.
+- `postBuildTests` — named tests against the **build output** (e.g. an
+  e2e suite against the production build with a Postgres service). Each
+  entry becomes a job in the `post-build` stage between build and deploy
+  and blocks the deploy when it fails (see below).
 - `artifactsPaths` / `artifactsExcludePaths` — extra build artifacts
   (`dist` and `.next` are always included).
 - `cache` — build caching (see the `catladder-pipelines` skill for the
@@ -74,15 +78,63 @@ type: `build: { from: "web" }` (see workspace builds below).
   runner tags, build-only env vars, and extra runner variables. A
   `jobImage` is a concrete image url or `{ image: "<name>" }`
   referencing a project image (see below).
+- `reuseMainBranchImage` — in release pipelines, stage/prod copy the
+  image the main branch (`dev`) built for the released commit instead of
+  rebuilding it (falls back to a build). Only for images that don't
+  depend on the env, e.g. Rails via Cloud Native Buildpacks.
 - `docker` — the image build strategy: a built-in
   (`{ type: "nginx" | "node" | "meteor" }`) or
   `{ type: "custom" }` (expects a `Dockerfile`).
 
+## Post-build tests (e2e against the build)
+
+`lint`/`test` run against the sources, in parallel with the build. Tests
+that need the built app go into `postBuildTests`:
+
+```ts
+build: {
+  type: "node",
+  postBuildTests: {
+    e2e: {
+      command: "pnpm test:e2e",                  // runs in the build dir
+      jobImage: "mcr.microsoft.com/playwright:v1.56.0-noble",
+      services: [{ name: "postgres:17", alias: "postgres",
+                   variables: { POSTGRES_PASSWORD: "postgres" } }],
+      vars: { DATABASE_URL: "postgres://postgres:postgres@postgres:5432/postgres" },
+      artifacts: { paths: ["apps/web/playwright-report"] }, // repo-root relative
+    },
+  },
+}
+```
+
+- The job (`🔬 e2e`, stage `post-build <env>`) downloads the build
+  artifacts (`.next`, `dist`, `artifactsPaths`), installs dependencies
+  for node builds, then runs `command`. The command starts the app
+  itself, e.g. playwright `webServer: { command: "pnpm start" }`.
+  Builds without artifacts (`rails`, `buildCommand: false`) just run
+  it after the build.
+- It is a quality gate: the env's deploy waits for it; on github it is
+  part of the `catladder ✅` required check. `allowFailure: true` makes
+  it report-only.
+- It gets the build vars plus `vars`, **not** the deployed env's
+  runtime vars/secrets — use services instead of the real database.
+- Artifacts are uploaded also when the job fails.
+- Not run in tagged releases. Disable one per env:
+  `env: { dev: { build: { postBuildTests: { e2e: false } } } }`.
+- Names must not clash with other jobs of the component (e.g. `test`,
+  `lint`) — generation fails with a clear error.
+- Workspace builds: on `builds.<ws>` they block the deploys of all
+  components in the workspace; on `build: { from: "<ws>", postBuildTests }`
+  only that component's deploy.
+- To test the **deployed** env instead (smoke tests on dev / review
+  apps), use the component's `verify` (post-deploy, does not block the
+  deploy). The same suite can serve both, with `BASE_URL` as the switch.
+
 ## Project images (custom CI job images)
 
 When a job needs a toolchain catladder doesn't ship (Java, Playwright,
 …), declare a Docker image at the top level under `images` and reference
-it in any `jobImage` field (build, `test.jobImage`, custom/pages deploy,
+it in any `jobImage` field (build, `test.jobImage`, `postBuildTests`, custom/pages deploy,
 verify):
 
 ```ts

package/dist/skills/catladder-builds/references/build-types.md

@@ -12,6 +12,7 @@ generated pipeline files.
 | `startCommand` | `string` | runtime start command |
 | `postInstall` | `string \| string[]` | runs after the package-manager install (node family) |
 | `lint` / `test` / `audit` | `false \| TestJobCustom` | customize or disable the job |
+| `postBuildTests` | `Record<string, PostBuildTestConfig \| false>` | named tests against the build output in the `post-build` stage; block the deploy |
 | `artifactsPaths` | `string[]` | extra artifacts (`dist`, `.next` always included) |
 | `artifactsExcludePaths` | `string[]` | artifact excludes |
 | `artifactsReports` | `{ junit?: string[] }` | CI test report paths |
@@ -20,12 +21,20 @@ generated pipeline files.
 | `runnerVariables` | `Record<string,string>` | extra runner vars (also for `services:`) |
 | `jobTags` | `string[]` | runner tags |
 | `jobImage` | `JobImageConfig` | CI image for the build: a concrete image or `{ image: "<name>" }` referencing a project image |
+| `reuseMainBranchImage` | `boolean \| { releaseFiles?: string[] }` | release envs (stage/prod) copy the main branch (`dev`) image of the released commit instead of rebuilding; falls back to a build. Only for env-independent images; not for `google-cloudrun`. `true` = `{ releaseFiles: ["CHANGELOG.md"] }` |
 | `docker` | see below | the deployable image strategy |
 
 `TestJobCustom` (for `lint`/`test`/`audit`): `command`, `jobImage`,
 `artifactsReports`, `artifacts`, `runnerVariables`, `allowFailure`
 (`allowFailure` defaults to `true` for `audit`).
 
+`PostBuildTestConfig` (for `postBuildTests` entries): `TestJobCustom` with
+a required `command`, plus `services?: Services` (gitlab shape, reachable
+by alias) and `vars?: Record<string,string>`. The job gets the build
+artifacts, the build vars and `vars` (not the deployed env's runtime
+vars), installs dependencies for node builds, and uploads `artifacts`
+also on failure.
+
 `audit` additionally takes `level`: `"info" | "low" | "moderate" | "high" |
 "critical"` (default `"critical"`) — the lowest severity that fails the job,
 translated to the package manager's own flag (`pnpm audit --audit-level`,
@@ -80,5 +89,5 @@ defaulted `buildCommand: "yarn build-storybook --quiet -o ./dist"`.
 Top-level `builds: Record<string, WorkspaceBuildConfig>`. Only
 `type: "node"` is supported.
 
-- Node workspace build: `dir?`, `buildCommand?` (default `<pm> build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "<pm> lint" }`), `test?` (default `{ command: "<pm> test" }`), `audit?`, `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?` (`<pm>` = `yarn`/`pnpm` per detection).
-- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache? }` — the per-component overrides layer on top of the shared build.
+- Node workspace build: `dir?`, `buildCommand?` (default `<pm> build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "<pm> lint" }`), `test?` (default `{ command: "<pm> test" }`), `audit?`, `postBuildTests?` (block the deploys of all its components), `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?` (`<pm>` = `yarn`/`pnpm` per detection).
+- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache?, postBuildTests? }` — the per-component overrides layer on top of the shared build.

package/dist/skills/catladder-config/SKILL.md

@@ -33,20 +33,23 @@ const config = {
   appName: "my-app",
   customerName: "pan",
   pipelines: { gitlab: true, github: true }, // which CI systems to generate
-  environments: {              // optional: project-wide env declarations/tuning
+  environments: {
+    // optional: project-wide env declarations/tuning
     review: { autoStop: "3 days" },
+    stage: false, // the project has no stage env (any component)
     next: { type: "dev", on: { branch: "next" } }, // extra branch-tracking env
   },
   components: {
     www: {
-      dir: "frontend",          // working directory of this component
-      vars: { public: {}, secret: [] },  // env vars (see catladder-secrets skill)
-      build: { type: "node" },  // node | rails | meteor | custom — see catladder-builds
+      dir: "frontend", // working directory of this component
+      vars: { public: {}, secret: [] }, // env vars (see catladder-secrets skill)
+      build: { type: "node" }, // node | rails | meteor | custom — see catladder-builds
       deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
-      env: {                    // enable/customize per environment
+      env: {
+        // enable/customize per environment
         review: {},
         dev: {},
-        stage: false,           // false disables the env for this component
+        stage: false, // false disables the env for this component only
         prod: {},
       },
     },
@@ -68,9 +71,17 @@ Key concepts:
   per-component `env.<name>` entries only carry component-local
   overrides (vars, deploy settings, host, autoStop) or `false` to opt
   the component out. In `environments`:
+  - `<name>: false` — disables the env for the whole project: no
+    component has it, so no setup contexts (`catladder project setup`),
+    secrets, pipeline jobs/workflows or catenv for it. This is how to
+    say "this project has no stage": `environments: { stage: false }`
+    (not `on: false`). `local` cannot be disabled; inheriting from a
+    disabled env is an error.
   - `on` — when the env deploys: `"mainBranch"`, `"mr"`,
     `"taggedRelease"`, `{ branch: "next" }` (a stable env deploying on
-    pushes to that branch), or `false` (in no pipeline). `on: "mr"`
+    pushes to that branch), or `false` (never deployed by a pipeline —
+    the env still exists for setup, secrets and catenv; use
+    `environments.<name>: false` to remove it). `on: "mr"`
     makes an env a review app (one instance per MR/PR, torn down on
     close). Defaults from the env type.
   - `autoStop` — how long a stoppable environment stays up after its

package/dist/skills/catladder-pipelines/SKILL.md

@@ -11,12 +11,12 @@ generated YAML.
 
 ## Triggers and environments
 
-| Trigger | Runs on | Deploys to (default) |
-|---|---|---|
-| `mainBranch` | push to the main branch | `dev` |
-| `mr` | merge/pull requests | `review` (one app per MR/PR) |
-| `taggedRelease` | git tags | `stage`, `prod` |
-| `{ branch: "<name>" }` | push to that branch | envs declaring it via `on` |
+| Trigger                | Runs on                 | Deploys to (default)         |
+| ---------------------- | ----------------------- | ---------------------------- |
+| `mainBranch`           | push to the main branch | `dev`                        |
+| `mr`                   | merge/pull requests     | `review` (one app per MR/PR) |
+| `taggedRelease`        | git tags                | `stage`, `prod`              |
+| `{ branch: "<name>" }` | push to that branch     | envs declaring it via `on`   |
 
 The trigger of each env is its `on` in the top-level `environments`
 config (project-wide — components cannot diverge), defaulting from the
@@ -25,6 +25,9 @@ own pipeline (gitlab: rules on `$CI_COMMIT_BRANCH`; github: a
 `catladder-branch-<name>.yml` workflow) and deploys as one stable,
 branch-tracking environment — unlike review apps, it is not
 per-instance and is stopped via the manual stop job/workflow.
+`on: false` keeps an env out of every pipeline but the env still exists
+(setup, secrets, catenv); `environments: { <name>: false }` removes it
+entirely.
 
 Generated layout:
 
@@ -34,39 +37,40 @@ Generated layout:
   "generated by catladder" header; others are unmanaged). Manual
   actions are per-kind `workflow_dispatch` workflows, visually grouped
   by their emoji prefix in the Actions sidebar: `🚀 catladder create
-  release`, `▶️ catladder deploy` (manual-gated deploys), `🛑 catladder
-  stop`, `↩️ catladder rollback` — when all of a kind's tasks target one
+release`, `▶️ catladder deploy` (manual-gated deploys), `🛑 catladder
+stop`, `↩️ catladder rollback` — when all of a kind's tasks target one
   env the name carries it (e.g. `▶️ catladder deploy prod`); otherwise
   pick the task from the workflow's dropdown. Review apps are stopped
   automatically when their pull request closes (`🛑 catladder stop
-  review app`); the same workflow can be dispatched with a PR number to
+review app`); the same workflow can be dispatched with a PR number to
   tear one down while the pull request is still open (gitlab runs these as manual jobs inside the pipeline
   instead).
 
-Stages: setup → test → build → deploy → verify (post-deploy checks),
-plus stop jobs for review-app teardown.
+Stages: setup → test → build → post-build (`postBuildTests` against
+the build output, block the deploy) → deploy → verify (post-deploy
+checks), plus stop jobs for review-app teardown.
 
 ## Superseded pipelines are cancelled
 
 Pushing a new commit cancels the pipeline of the previous one, so the
 runners are not busy with results nobody will read.
 
-| Pipeline | On a new commit |
-|---|---|
-| `mr` | cancelled |
-| `mainBranch` (dev) | cancelled, except a release already running |
-| `taggedRelease` | **runs through** — never cancelled |
-| agent runs (`trigger`) | **runs through** — never cancelled |
+| Pipeline               | On a new commit                             |
+| ---------------------- | ------------------------------------------- |
+| `mr`                   | cancelled                                   |
+| `mainBranch` (dev)     | cancelled, except a release already running |
+| `taggedRelease`        | **runs through** — never cancelled          |
+| agent runs (`trigger`) | **runs through** — never cancelled          |
 
 - **GitHub**: the generated MR workflow sets `concurrency` with
   `cancel-in-progress: true`.
 - **GitLab**: generated `workflow:auto_cancel:on_new_commit:
-  interruptible`, with per-rule `none` for tags and agent runs. Every
+interruptible`, with per-rule `none` for tags and agent runs. Every
   job carries an explicit `interruptible`, jobs that must finish
   (release jobs, agent jobs) carry `interruptible: false`.
 
 **GitLab requires the project setting too.** The generated YAML only
-tunes *how* redundant pipelines are cancelled — it does not switch the
+tunes _how_ redundant pipelines are cancelled — it does not switch the
 feature on. If old pipelines keep running, check **Settings > CI/CD >
 General pipelines > Auto-cancel redundant pipelines**; with that
 checkbox off nothing is ever cancelled. (`catladder project-doctor`
@@ -74,7 +78,7 @@ does not check this.)
 
 **Adding a hand-written GitLab job?** Set `interruptible` explicitly.
 GitLab defaults it to `false`, and a non-interruptible job that has
-started keeps *itself* alive — under gitlab's own default
+started keeps _itself_ alive — under gitlab's own default
 (`conservative`, which catladder overrides) it would shield the whole
 pipeline from cancellation.
 
@@ -148,6 +152,21 @@ pipelines: { github: { repository: "AcmeCorp/Nautilus" } },
 `yarn catladder project doctor` reports a mixed-case repository whose
 generated workflows still carry the expression.
 
+### Artifacts between jobs (GitHub)
+
+A job's `artifacts.paths` are handed to the jobs that need them as one
+tar archive (`catladder-artifacts-<job-id>.tar`): an "Archive
+artifacts" step tars them after the job, `upload-artifact` uploads the
+archive under the job id, and the consumers get a matching "Extract
+artifacts" step after `download-artifact`. The tar keeps symlinks, file
+modes and repo-relative paths, as GitLab artifacts do. Plain
+`upload-artifact` loses them, which breaks Next.js/Turbopack builds in
+pnpm workspaces: `.next/node_modules/<pkg>-<hash>` are symlinks into
+the pnpm store, and as copied directories they fail at runtime with
+`ERR_MODULE_NOT_FOUND`. If a deployed app shows that error, check that
+the committed workflows contain the archive steps and regenerate if
+they don't.
+
 ## Caching
 
 Cache configuration is generated per build type. **yarn** node builds