@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/dist/skills/catladder-migrate-release-method/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: catladder-migrate-release-method
+description: Migrating a catladder project from one release method to another — semantic-release (conventional commits) ↔ changesets (`.changeset/*.md` files) — including backfilling changesets for everything merged since the last release tag so the changelog and the version bump stay correct. Use when switching `releases.method`, adopting changesets in a project that has been releasing with semantic-release, or going back. Triggers on "switch to changesets", "migrate to changesets", "adopt changesets", "use changesets instead", "back to semantic-release", "change the release method", "backfill changesets".
+---
+
+# Migrating the release method
+
+catladder projects release either with **semantic-release** (version
+derived from conventional commit messages) or with **changesets**
+(version derived from `.changeset/*.md` files that developers write
+deliberately). The method is one field in `catladder.ts`:
+
+```ts
+releases: {
+  when: "manual",
+  method: "changesets", // "semantic-release" (default) | "changesets"
+}
+```
+
+Flipping that field is **not** the whole migration. Read
+`catladder-releases` first if you are unsure how either method works.
+
+## Why a config flip is not enough
+
+The two methods disagree about where "what changed since the last
+release" lives:
+
+| | semantic-release | changesets |
+|---|---|---|
+| source of the bump | commit messages since the last `v*` tag | pending `.changeset/*.md` |
+| changelog text | generated from those commits | the changeset summaries |
+
+Everything up to and including the **last `v*` tag** is already written
+into `CHANGELOG.md` — that part is settled and must not be touched.
+But everything merged **after** that tag is exactly what semantic-release
+would have released next, and after the switch the release job can no
+longer see it. Without a backfill:
+
+- those changes silently disappear from the changelog, and
+- the next version is likely too small (a `feat:` merged since the tag
+  releases as a patch, or nothing releases at all).
+
+So the migration is: **backfill changesets for the commits since the
+last release tag, then flip the config, in one merge request.**
+
+## Step 1 — establish the range
+
+Work on a branch (never directly on the main branch).
+
+```bash
+git fetch --tags
+git describe --tags --abbrev=0 --match "v[0-9]*"
+```
+
+That is the same tag the release job uses. Then list the candidates:
+
+```bash
+git log <tag>..HEAD --no-merges --pretty=format:"%h %s"
+```
+
+Cases:
+
+- **No `v*` tag at all** — the project has never released. There is
+  nothing to backfill; the first changesets release will be `1.0.0`
+  regardless of the bump levels. Skip to step 5.
+- **The tag is the current HEAD** — nothing merged since the release,
+  nothing to backfill. Skip to step 5.
+
+## Step 2 — drop what is not user-facing
+
+From that list, remove:
+
+- `chore(release): X.Y.Z` commits (semantic-release's own commits)
+- pure `chore:` / `ci:` / `build:` / `test:` / internal-refactor commits
+- documentation-only changes, unless the docs *are* the product
+
+Keep everything a user of this app would notice. When a commit message
+is too vague to judge, look at the diff (`git show <sha> --stat`) before
+deciding — do not guess from the subject line alone.
+
+## Step 3 — group the remaining commits
+
+A changeset is **one user-facing change**, not one commit. Several
+commits that built the same feature belong in one changeset; one commit
+that shipped two unrelated things belongs in two.
+
+**Decide yourself** when the remaining set is small (roughly ≤ 5
+commits) and the grouping is obvious — then show the user the resulting
+changesets and let them correct.
+
+**Ask the user first** when there are many commits, or when the grouping
+is genuinely ambiguous. Ask once, with a concrete proposal attached
+rather than an open question — for example:
+
+- the proposed grouping as a list ("these 4 commits → one changeset
+  *Export endpoint*"), asking whether to merge or split any of them
+- the commits you could not classify: user-facing or internal?
+- any change they consider **breaking** — that alone decides whether the
+  next release is a major
+
+Do not ask about things you can answer from the diff.
+
+## Step 4 — pick the bump level per changeset
+
+- **major** — breaking change (`feat!:`/`fix!:`, or a `BREAKING CHANGE:`
+  footer, or anything that forces consumers to adapt)
+- **minor** — a new feature (`feat:`)
+- **patch** — fixes, performance, reverts, and anything else user-facing
+
+Only the **highest** pending bump decides the next version, but write
+the honest level on each changeset anyway: the changelog groups by it.
+Note that `0.x` versions get no special treatment — a minor bump on
+`v0.3.1` produces `0.4.0`.
+
+## Step 5 — write the changeset files
+
+One file per changeset, `.changeset/<kebab-case-slug>.md`:
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+- The package name in the frontmatter is **ignored** (catladder versions
+  from git tags, not from package.json) — use the project's `appName`
+  for readability.
+- Write the summary for someone reading the changelog, not the commit
+  log: what changed and why it matters, not `refactor foo helper`.
+- Reference the MR/PR or issue when it helps the reader.
+
+Also add `.changeset/README.md` so the next developer knows what the
+folder is:
+
+````md
+# Changesets
+
+This repo releases with catladder's `changesets` release method: every
+user-facing change merges together with a changeset file in this
+directory. The release job consumes all pending changesets — the highest
+bump (applied to the last `v*` tag) becomes the new version, the
+summaries become the changelog entries.
+
+Write one by hand (`.changeset/<descriptive-name>.md`):
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+Bump levels: `major` (breaking), `minor` (feature), `patch` (fix).
+The package name in the frontmatter is ignored — only the bump counts.
+`yarn changeset` also works if you prefer the interactive prompt.
+
+No pending changesets on the main branch means the release job is a
+no-op.
+````
+
+## Step 6 — flip the config and regenerate
+
+```ts
+releases: {
+  when: "manual",       // unchanged — `when` is independent of `method`
+  method: "changesets",
+}
+```
+
+```bash
+yarn catenv
+```
+
+Commit the regenerated files (`.catladder-generated/`, `.gitlab-ci.yml`,
+`.github/workflows/catladder-*`) together with the config change and the
+changesets — see the `catladder-config` skill.
+
+## Step 7 — verify before merging
+
+- State the expected outcome explicitly: *last tag `vX.Y.Z` + highest
+  pending bump = next release `vA.B.C`*. If that is not what the user
+  expects, the bump levels are wrong.
+- The merge request now runs the **`🦋 changeset check`** job. It should
+  report the pending changesets and that same version. A yellow check
+  only means "this MR adds no changeset" — for the migration MR itself
+  that is not the case, so expect it green.
+- Do **not** hand-write `CHANGELOG.md`. The release job prepends the new
+  section; anything you write by hand there gets duplicated.
+- Leave any `.releaserc` / `release.config.js` alone if the project has
+  one — it becomes inert, and deleting it is a separate cleanup.
+
+## Step 8 — hand over to the team
+
+After merging, tell the user what changes for everyone:
+
+- every user-facing MR now needs a `.changeset/*.md` file; the
+  `🦋 changeset check` job warns (without blocking) when one is missing
+- commit messages no longer decide the version — conventional commits
+  are still nice, but purely cosmetic now
+- if something was merged without a changeset and must ship anyway, the
+  **force release** escape hatch releases a patch (GitLab:
+  `⚠️ force create release`, GitHub: the *force* checkbox of the
+  `🚀 catladder create release` workflow)
+
+## The other direction: changesets → semantic-release
+
+Same shape, mirrored, with one loss to flag up front:
+
+1. **Pending changesets are not converted.** Their summaries would
+   simply vanish from the changelog. Either cut one last changesets
+   release first (draining `.changeset/`), or fold each summary into the
+   changelog by hand before removing the files. Tell the user which one
+   you are doing.
+2. Commits since the last tag must carry conventional messages for
+   semantic-release to see them — history cannot be rewritten after the
+   fact, so accept that the first semantic-release version may
+   under-report. Say so rather than silently releasing a patch.
+3. Set `method: "semantic-release"` (or drop the field — it is the
+   default), run `yarn catenv`, commit the regenerated files.
+4. Delete `.changeset/` including its `README.md`.
+5. From then on the version comes from commit messages again, and the
+   `🦋 changeset check` job disappears from MR pipelines.
+
+## Related skills
+
+- `catladder-releases` — how both methods work, the release jobs and the
+  security-audit gate
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-migrate-ci-backend` — migrating between GitLab CI and
+  GitHub Actions
+- `catladder-migrate-package-manager` — migrating between yarn and pnpm

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

@@ -0,0 +1,101 @@
+---
+name: catladder-pipelines
+description: Understanding and debugging the CI/CD pipelines catladder generates (GitLab CI and GitHub Actions) — pipeline triggers, stages, environments, caching, job images, releases, and infrastructure drift. Use when investigating failing CI jobs, when asked why/when a job runs, when changing caching or job behavior, or when deployments misbehave. Triggers on "pipeline", "CI job", "gitlab-ci", "workflow", "deploy failed", "cache", "release".
+---
+
+# How catladder pipelines work
+
+All pipeline files are generated from `catladder.ts` — fix pipeline
+problems in the config (see `catladder-config` skill), never in the
+generated YAML.
+
+## Triggers and environments
+
+| Trigger | Runs on | Deploys to |
+|---|---|---|
+| `mainBranch` | push to the main branch | `dev` |
+| `mr` | merge/pull requests | `review` (one app per MR/PR) |
+| `taggedRelease` | git tags | `stage`, `prod` |
+
+Generated layout:
+
+- **GitLab**: `.gitlab-ci.yml` includes generated files from
+  `.catladder-generated/gitlab/` (one per trigger).
+- **GitHub**: workflows in `.github/workflows/` (generated ones carry a
+  "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
+  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
+  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.
+
+## Job images and catci
+
+Jobs run in catladder-provided images (`🐳 catladder image <name>` build
+jobs). Their definitions are materialized into
+`.catladder-generated/images/` and built in the project's own registry
+under `catladder/` (content-hashed, rebuilt only on change).
+`.catladder-generated/catci/` holds a small bundled CI companion used by
+generated jobs (e.g. the release security audit) — all generated, never
+edit.
+
+Projects can declare their own job images under `images` in
+`catladder.ts` (`🐳 image <name>` build jobs, pushed to `job-images/` in
+the registry) and reference them in any `jobImage` field via
+`{ image: "<name>" }` — see the `catladder-builds` skill. A declared
+Dockerfile directory is used in place; an inline `dockerfile` is
+materialized into `.catladder-generated/images/project/<name>/`. Either
+way the build job is skipped when the content hash already exists in
+the registry.
+
+## Caching
+
+Cache configuration is generated per build type. **yarn** node builds
+cache `node_modules` and the `.yarn` zip cache; GitLab uses mutable
+caches with fallback keys (review branches fall back to the dev cache),
+GitHub immutable lockfile-keyed caches where only the build job writes.
+**pnpm** builds cache nothing: measured on a 3800-package monorepo,
+moving the store or node_modules through a CI cache costs more than
+pnpm's from-registry install.
+Caching behavior is changed via the build config in `catladder.ts`,
+not in the YAML.
+
+## Releases
+
+With `releases` configured, tagged releases are created by a release
+job (method: `semantic-release` or `changesets`). The release job also
+runs a dependency security audit that gates the release. See the
+`catladder-releases` skill for the full flow.
+
+## Debugging CI
+
+Useful CLI commands (see the `catladder-cli` skill for invocation):
+
+- `yarn catladder project ci job-log` / `project ci job-open` — fetch
+  or open a CI job
+- `yarn catladder project doctor` — detect drift between `catladder.ts`
+  and the actually provisioned infrastructure (missing IAM roles, stale
+  secrets, ...). Run this when a deploy/teardown fails with permission
+  errors even though the config looks right; fix findings with
+  `yarn catladder project setup [component]`.
+- `yarn catladder project logs open`, `project k8s list-pods`,
+  `project k8s get-shell` — inspect the running deployments
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — build jobs and Docker images
+- `catladder-deploys` — deploy jobs, environments and review apps
+- `catladder-releases` — the `taggedRelease` flow and security-audit gate
+- `catladder-secrets` — env vars and secret management
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions (running both in parallel, then cutting over)

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

@@ -0,0 +1,134 @@
+---
+name: catladder-releases
+description: How releases work in a catladder project — the `releases` config in catladder.ts (manual vs automatic releasing, and the release method: semantic-release from conventional commits, or changesets from `.changeset/*.md` files), the version/tag/changelog flow, and the security-audit gate that every release must pass. Use when enabling or changing releases, deciding between semantic-release and changesets, writing changesets, cutting or debugging a release, or when a release job fails on the security audit. Triggers on "release", "releases config", "semantic-release", "changesets", "changeset", "version bump", "tag a release", "security audit", "release failed".
+---
+
+# Releases with catladder
+
+A release is what produces a `vX.Y.Z` git tag (with a changelog), which
+in turn triggers the `taggedRelease` pipeline that deploys to `stage`
+and `prod` (see the `catladder-pipelines` skill). Enable it in
+`catladder.ts`:
+
+```ts
+releases: {
+  when: "auto",              // "manual" (default) | "auto"
+  method: "semantic-release", // "semantic-release" (default) | "changesets"
+}
+```
+
+Change `catladder.ts` and regenerate (`yarn catenv`) — the release jobs
+are generated, never hand-edited.
+
+## `when` — who triggers the release
+
+- **`manual`** (default) — the `create release` job on the main branch
+  can be clicked **at any time**, even while the pipeline is still
+  running: it queues the release, which then runs automatically as soon
+  as every other job of the pipeline succeeded (and is skipped if the
+  pipeline fails). Clicking after a green pipeline releases right away.
+  - On GitLab the button is a quick no-op job; the actual release runs
+    in the automatic `🚀 release once pipeline succeeds` job (skipped
+    when the button was never clicked — never run it by hand).
+  - On GitHub, releasing is the **`🚀 catladder create release`**
+    workflow (Actions sidebar → Run workflow): it releases immediately
+    when the main workflow for HEAD is green, queues the release when
+    it is still running (the `🛠️ catladder release on green` workflow then
+    picks it up on completion), and fails when the run concluded red.
+- **`auto`** — the release job runs automatically on every main-branch
+  pipeline (it still no-ops when there is nothing to release).
+
+There is always also a **force release** escape hatch that releases
+**immediately**, ignoring the state of the pipeline: on GitLab the
+manual `⚠️ force create release` job, on GitHub the *force* checkbox of
+the `🚀 catladder create release` workflow. With `method: "changesets"`
+forcing has an extra meaning: it releases **even when no changesets are
+pending** (patch bump with a generic changelog entry) — the recovery
+path when a change was merged without a changeset and must ship now.
+
+On GitHub, other manual tasks are split into per-kind dispatch
+workflows the same way (`▶️ catladder deploy`, `⏹️ catladder stop`,
+`↩️ catladder rollback`), each with a dropdown of its tasks.
+
+## `method` — how the version is decided
+
+### `semantic-release` (default)
+The version is derived automatically from **conventional commit
+messages** since the last release (`fix:` → patch, `feat:` → minor,
+`BREAKING CHANGE` → major). Nothing to declare by hand — just write
+conventional commits.
+
+### `changesets`
+Developers declare changes intentionally as **`.changeset/*.md` files**
+(the official changesets format: a bump type + a human-written summary).
+The release job consumes all pending changesets, takes the highest bump,
+computes the next version from the last `v*` git tag, writes the
+changelog, commits `chore(release): <version>`, and pushes the tag. An
+empty `.changeset/` folder means there is nothing to release.
+
+Add a changeset by creating `.changeset/<name>.md`:
+
+```md
+---
+"my-app": minor
+---
+
+Add the new export endpoint.
+```
+
+**When you (an agent) make a user-facing change in a changesets
+project, add a changeset file in the same MR** — bump level `major`
+(breaking) / `minor` (feature) / `patch` (fix), and a one-to-two
+sentence summary written for the changelog reader. Docs/chore-only
+changes need none. The package name in the frontmatter is ignored
+(versions come from git tags); only the bump counts.
+
+### The changeset check (MR/PR pipelines)
+
+Changesets projects get a **`🦋 changeset check`** job in every
+merge-request pipeline. It reports what merging would do — the
+changesets this MR adds, everything pending, and the version the next
+release would get (with a changelog preview) — and **warns without
+blocking** (`allow_failure`) when the MR adds no changeset:
+
+- **GitLab**: report in the job log and as an exposed artifact
+  (`changeset-report.md`) in the MR widget. If the project makes
+  `GL_TOKEN` available to MR pipelines it also maintains a sticky MR
+  comment (opt-in — an api-scope token in MR pipelines is a security
+  trade-off).
+- **GitHub**: maintains a sticky PR comment via the workflow token; the
+  job stays green and reports a warning annotation (github has no
+  yellow job state, and a red job would read like a real failure).
+
+A yellow changeset-check job on an MR is a prompt to ask: is this
+change user-facing? If yes, add a changeset; if not, ignore it.
+
+## The security-audit gate
+
+**Both methods gate on a dependency security audit before releasing.**
+The release entrypoint runs the audit first; only if it passes does it
+create the version, changelog and tag. On GitLab, if the audit document
+is missing or invalid the job opens a merge request with a security-audit
+template and **fails** — resolve that MR, then re-run the release. See
+the `security` commands in the `catladder-cli` reference.
+
+## Debugging a failed release
+
+- Fails immediately on the audit → handle the security-audit gate above.
+- `changesets` released nothing → no `.changeset/*.md` files were
+  pending. To ship anyway, force the release (patch bump) — gitlab:
+  `⚠️ force create release` job, github: force checkbox — or merge an
+  MR adding a changeset describing the accumulated work.
+- Wrong version bump → check commit types (semantic-release) or the bump
+  levels in the changeset files (changesets).
+- Inspect the job with `yarn catladder project ci job-log` (see the
+  `catladder-cli` skill).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
+- `catladder-cli` — `project ci` and `security` commands
+- `catladder-migrate-release-method` — switching an existing project
+  between semantic-release and changesets (incl. backfilling changesets
+  for everything merged since the last release tag)

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

@@ -0,0 +1,111 @@
+---
+name: catladder-secrets
+description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set, rotated or checked, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets", "secrets-set", "secrets-list", "rotate a secret", "set a secret".
+---
+
+# Env vars and secrets with catladder
+
+Environment variables are declared per component in `catladder.ts`;
+secret *values* are never checked into the repo.
+
+## Declaring variables
+
+```ts
+components: {
+  app: {
+    vars: {
+      // names of secret vars — values are stored in the secrets vault, not in git
+      secret: ["API_KEY"],
+      public: {
+        MY_VAR: "some value",
+        // reference other vars, including from other components:
+        GRAPHQL_ENDPOINT: "${api:ROOT_URL}/graphql",
+      },
+    },
+  },
+}
+```
+
+Predefined per component/env: `ROOT_URL`, `HOSTNAME`, `PORT` (plus
+deploy-type specific ones). All vars are available at build time and at
+runtime. After changing declarations, regenerate with `yarn catenv` and
+commit.
+
+## Setting secret values
+
+Secret values are managed through the catladder CLI — never by editing
+files in the repo. All secrets commands accept a **scope**:
+`dev:web` (one env of one component), `dev:` (one env, all
+components), `:web` (all envs of one component), or nothing (everything).
+
+Check what is declared and what is still unset (never prints values
+unless `--reveal` is passed):
+
+```sh
+yarn catladder project secrets-list
+yarn catladder project secrets-list --check   # non-zero exit when something is unset
+```
+
+Set a single secret (the usual case — also for rotating one value
+across all envs via the `:component` scope):
+
+```sh
+echo -n "the-value" | yarn catladder project secrets-set dev:web API_KEY
+yarn catladder project secrets-set :web API_KEY --value-file /path/to/value
+```
+
+Prefer stdin or `--value-file` over `--value` so values stay out of
+shell history. **Never pass a real secret value you found in the
+conversation without the user having provided it for this purpose.**
+
+Bulk-edit several secrets as a YAML document
+(`component → env → key: value`):
+
+```sh
+yarn catladder project secrets-pull dev: --out /tmp/secrets.yml   # unset ones appear as "🚨 FILL ME"
+# edit the file, then:
+yarn catladder project secrets-push dev: --file /tmp/secrets.yml  # partial docs are fine
+```
+
+`secrets-push` skips placeholder/empty values, rejects undeclared
+keys, and may be partial — only the provided keys are written. Both
+support `--key KEY1,KEY2` to narrow further. Delete the temp file
+afterwards; never commit it.
+
+Humans may instead use the interactive editor flow
+(`project config-secrets`, opens `$EDITOR`); as an agent, use the
+commands above.
+
+All of these write to the secrets vault (the source of truth) and
+automatically mirror to the enabled CI backends — which vault is
+configured makes no difference to the commands.
+
+## GitHub pipelines
+
+GitHub Actions cannot read the vault at runtime; secrets are mirrored
+into GitHub *environment* secrets (one GitHub environment per catladder
+env). Sync them with:
+
+```sh
+yarn catladder project secrets-sync-github
+```
+
+Run this after adding/changing secrets when a github pipeline is
+enabled.
+
+## Local development
+
+`catenv` generates the local env (`.env` files / exported vars via
+direnv) for the `local` environment. If a var is missing locally,
+check its declaration in `catladder.ts` and re-run `yarn catenv` before
+suspecting anything else.
+
+## Related skills
+
+- `catladder-config` — general catladder.ts structure and regeneration
+- `catladder-builds` — build-time vars (`jobVars`) and build config
+- `catladder-deploys` — runtime deploy config
+- `catladder-pipelines` — how the generated pipelines work
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between CI backends (the vault
+  is what blocks decommissioning the old one)