@catladder/cli 5.4.1 → 5.6.0

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