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

package/dist/runner-images/kubernetes/scripts/kubernetesCreateSecret

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -e
+
+# The credentials come from DOCKER_REGISTRY_USER / DOCKER_REGISTRY_PASSWORD,
+# which the deploy job resolves per CI backend (gitlab: CI_REGISTRY_USER +
+# CI_REGISTRY_PASSWORD, github: the actor + workflow token) — the raw
+# gitlab names used to be hardcoded here, which left the secret without
+# credentials on the github backend.
+#
+# Both of those are job-scoped and expire with the pipeline: the initial
+# pull works, but a pod rescheduled later can no longer re-pull. Projects
+# that need durable pulls declare long-lived registry credentials as
+# secrets named CI_DEPLOY_USER / CI_DEPLOY_PASSWORD, which win here.
+#
+# --docker-email is deliberately gone: it is optional for a
+# docker-registry secret and its only source was $GITLAB_USER_EMAIL.
+echo "KUBE_NAMESPACE: '$KUBE_NAMESPACE', KUBE_DOCKER_IMAGE_PULL_SECRET: '$KUBE_DOCKER_IMAGE_PULL_SECRET'"
+kubectl create secret -n "$KUBE_NAMESPACE" \
+    docker-registry $KUBE_DOCKER_IMAGE_PULL_SECRET \
+    --docker-server="$DOCKER_REGISTRY" \
+    --docker-username="${CI_DEPLOY_USER:-$DOCKER_REGISTRY_USER}" \
+    --docker-password="${CI_DEPLOY_PASSWORD:-$DOCKER_REGISTRY_PASSWORD}" \
+    -o yaml --dry-run | kubectl replace -n "$KUBE_NAMESPACE" --force -f -

package/dist/runner-images/kubernetes/scripts/kubernetesDelete

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+echo "Delete $RELEASE_NAME"
+helm uninstall "$RELEASE_NAME" --namespace "$KUBE_NAMESPACE"

package/dist/runner-images/kubernetes/scripts/kubernetesDeploy

@@ -0,0 +1,57 @@
+#!/bin/bash
+set -e
+
+echo "Deploy to kubernetes"
+echo "Release: $RELEASE_NAME"
+echo "URL (canonical): $HOSTNAME_INTERNAL"
+
+# this bash-brainfuck simply splits $helmArgs by newline to an array...
+readarray -t helmArgsArray <<<"$HELM_ARGS"
+
+#Log the time until selfdestruct in case of review environment
+if [[ ${ENV_SHORT} == "review" ]]; then echo "NOTE - This deployment will stop itself after 2 weeks"; fi
+
+if [[ ${ENV_SHORT} == "review" ]]; then
+    # auto rollback
+    set +e # disable fail job on error
+    helmStatus=$(helm status --namespace $KUBE_NAMESPACE $RELEASE_NAME 2>/dev/null | awk -F': ' -v key="STATUS" '$1==key {print $2}')
+    helmRevision=$(helm status --namespace $KUBE_NAMESPACE $RELEASE_NAME 2>/dev/null | awk -F': ' -v key="REVISION" '$1==key {print $2}')
+    if [ "$helmStatus" = "failed" ] || [ "$helmStatus" = "pending-install" ] || [ "$helmStatus" = "pending-upgrade" ]; then
+        # rollback
+        echo "helm deployment is pending or failed, rollback (only on review)..."
+        if [ "$helmRevision" = "1" ]; then
+            helm uninstall "$RELEASE_NAME" --namespace "$KUBE_NAMESPACE"
+        else
+            helm rollback "$RELEASE_NAME" --namespace "$KUBE_NAMESPACE"
+        fi
+
+    fi
+    set -e # reenable
+
+fi
+
+echo "doing helm upgrade"
+helm upgrade --install "$RELEASE_NAME" "$HELM_GITLAB_CHART_NAME" \
+    --timeout="30m0s" \
+    --set global.appName="$KUBE_APP_NAME" \
+    --set global.appPrefix="$KUBE_APP_NAME_PREFIX" \
+    --set global.ENV_SHORT="$ENV_SHORT" \
+    --set global.BUILD_ID="$BUILD_INFO_ID" \
+    --set image.repository="$CI_REGISTRY_IMAGE" \
+    --set image.pullSecret="$KUBE_DOCKER_IMAGE_PULL_SECRET" \
+    --set image.name="$DOCKER_IMAGE_NAME" \
+    --set image.tag="$DOCKER_IMAGE_TAG" \
+    --set image.pullPolicy=IfNotPresent \
+    --set application.hostCanonical="$HOSTNAME_INTERNAL" \
+    --set mongodb.fullnameOverride=$KUBE_APP_NAME-mongodb \
+    --set mailhog.fullnameOverride=$KUBE_APP_NAME-mailhog \
+    --set gitlab.visualReviewEnabled="$GITLAB_VISUAL_REVIEW_ENABLED" \
+    --set gitlab.app="$CI_PROJECT_PATH_SLUG" \
+    --set gitlab.projectPath="$CI_PROJECT_PATH" \
+    --set gitlab.mergeRequestId="$CI_MERGE_REQUEST_IID" \
+    --set gitlab.projectId="$CI_PROJECT_ID" \
+    --set gitlab.env="$CI_ENVIRONMENT_SLUG" \
+    --set namespace="$KUBE_NAMESPACE" \
+    --namespace="$KUBE_NAMESPACE" \
+    ${helmArgsArray[@]} \
+    --values __all_values.yml

package/dist/runner-images/kubernetes/scripts/kubernetesRollback

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+echo "Rolling back $RELEASE_NAME"
+helm rollback "$RELEASE_NAME" --namespace "$KUBE_NAMESPACE"

package/dist/runner-images/npm-publish/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:lts-alpine
+
+RUN apk add --no-cache bash git
+
+# npm trusted publishing (OIDC) needs npm >= 11.5.1; the npm bundled
+# with the node image is not guaranteed to be new enough, so pin the
+# major explicitly. Without it npm silently falls back to token auth.
+RUN npm install -g npm@11
+
+# no publish logic baked in: it lives in catci, which pipeline
+# generation materializes into the repository checkout
+# (.catladder-generated/catci)

package/dist/runner-images/semantic-release/Dockerfile

@@ -0,0 +1,30 @@
+# job images are addressed by a content hash of this directory — the
+# build must be reproducible, so every dependency is pinned exactly.
+# node:24 satisfies the newer plugins' engine requirements
+# (@semantic-release/git and @semantic-release/changelog need node >=24.15).
+FROM node:24-alpine
+
+RUN apk add --no-cache bash git git-lfs
+
+# add semantic release
+# NOTE: pin every dependency exactly. These are the semantic-release@25 line
+# (all ESM — v25 loads plugins via dynamic import, so changelog@7/git@11 are
+# fine). Every plugin declares `semantic-release` as a peer dependency, so a
+# plugin major that outpaces the semantic-release major fails the release job
+# with "plugins configuration is invalid" — bump them together. Upstream
+# @semantic-release/git replaces the old panter fork; see
+# scripts/semanticRelease for why the commit message is hardcoded.
+RUN yarn global add \
+    semantic-release@25.0.8 \
+    @semantic-release/commit-analyzer@13.0.1 \
+    @semantic-release/release-notes-generator@14.1.1 \
+    @semantic-release/git@11.0.0 \
+    @semantic-release/changelog@7.0.0 \
+    @semantic-release/gitlab@13.3.3 \
+    @semantic-release/exec@7.1.0
+
+RUN mkdir -p /scripts
+COPY ./scripts/* /scripts/
+RUN chmod +x /scripts/*
+
+ENV PATH="/scripts:${PATH}"

package/dist/runner-images/semantic-release/scripts/semanticRelease

@@ -0,0 +1,133 @@
+#!/bin/bash
+set -e
+
+# 0. check and evalaute security audit or create MR with security audit template (and exit 1)
+# 1. create "@semantic-release/changelog"
+# 2. commit it to git (and push)
+# 3. optional: update package.json
+
+# better branches settings: https://github.com/semantic-release/semantic-release/issues/1581
+
+if [ "$GITHUB_ACTIONS" = "true" ]; then
+  # github container jobs: the workspace volume is owned by the host
+  # runner user while this step runs as the container user, and the
+  # safe.directory entry actions/checkout writes goes to a temporary
+  # HOME that is gone by now — git would refuse the repo ("dubious
+  # ownership", surfacing as ENOGITREPO from semantic-release)
+  git config --global --add safe.directory "$(pwd)"
+fi
+
+echo "doing security audit check"
+CATCI=".catladder-generated/catci/index.js"
+if [ -f "$CATCI" ]; then
+  # catci is materialized by pipeline generation — always the exact
+  # catladder version that generated this pipeline
+  if [ "$GITHUB_ACTIONS" = "true" ]; then
+    # github: gate only — the MR remediation is gitlab-specific
+    node "$CATCI" security-audit check ./
+  else
+    node "$CATCI" security-audit ci-job ./ "$GL_TOKEN" "$CI_DEFAULT_BRANCH" "$CI_PROJECT_ID" "$GITLAB_USER_ID"
+  fi
+elif command -v catladder > /dev/null 2>&1; then
+  # repos generated by old catladder versions (no materialized catci):
+  # the central image still bakes the cli in
+  catladder security audit ci-job ./ "$GL_TOKEN" "$CI_DEFAULT_BRANCH" "$CI_PROJECT_ID" "$GITLAB_USER_ID"
+else
+  echo "neither $CATCI nor the catladder cli found — regenerate the pipeline with a current catladder version (catenv)"
+  exit 1
+fi
+
+echo "doing semantic release"
+
+if [ "$GITHUB_ACTIONS" = "true" ]; then
+  # the gitlab publish plugin would fail on github; skip it (the tag
+  # and changelog commit still happen, only the gitlab release entry
+  # is gitlab-specific)
+  PUBLISH_PLUGIN=""
+else
+  # no gitlabUrl: the plugin derives it from the CI-provided variables
+  # of the running instance. It used to be hardcoded to panter's gitlab,
+  # which broke the release on every other instance.
+  PUBLISH_PLUGIN=',
+    "@semantic-release/gitlab"'
+fi
+
+if [ ! -e .releaserc ]; then
+  cat >.releaserc <<EOF
+{
+  "plugins": [
+      [
+      "@semantic-release/commit-analyzer",
+      {
+        preset: "angular",
+        releaseRules: [
+          { breaking: true, release: "major" },
+          { revert: true, release: "patch" },
+
+          { type: "feat", release: "minor" },
+          { type: "docs", release: "patch" },
+          { type: "fix", release: "patch" },
+          { type: "perf", release: "patch" },
+          # always fall back to a patch release
+          {
+            header: "**",
+            release: "patch",
+          },
+        ],
+      },
+    ],
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    # message prefix hardcoded to "release" on purpose. Ideally this would be
+    # "chore(\${branch.type})", but upstream @semantic-release/git passes the
+    # branch *name* (not the object) into the template, so \${branch.type} is
+    # never available (see https://github.com/semantic-release/git/pull/213,
+    # open/ignored since 2020 — the README documents branch.type but the code
+    # never wired it up; the old panter fork existed only to patch this). On the
+    # default branch branch.type is always "release", and the pipeline
+    # loop-prevention rule keys on the literal "chore(release)" prefix, so keep
+    # this literal. Don't "fix" it back to \${branch.type}.
+    ["@semantic-release/git", {
+      "message": "chore(release): \${nextRelease.version}\n\n\${nextRelease.notes}"
+    }]${PUBLISH_PLUGIN}
+    ],
+  "branches": [
+    "+([0-9])?(.{+([0-9]),x}).x",
+    "master",
+    "main",
+    "next",
+    "next-major",
+    {
+      "name": "beta",
+      "prerelease": true
+    },
+    {
+      "name": "alpha",
+      "prerelease": true
+    }
+  ],
+}
+EOF
+fi
+
+if [ "$GITHUB_ACTIONS" = "true" ]; then
+  TAGS_BEFORE=$(git tag --list 'v[0-9]*')
+fi
+
+semantic-release
+
+# tags pushed with the default GITHUB_TOKEN don't trigger `on: push:
+# tags` workflows (github's recursion guard) — dispatch the
+# taggedRelease workflow explicitly for a tag semantic-release created
+if [ "$GITHUB_ACTIONS" = "true" ] && [ -f "$CATCI" ]; then
+  if [ -z "$TAGS_BEFORE" ]; then
+    NEW_TAG=$(git tag --list 'v[0-9]*' | tail -n1)
+  else
+    NEW_TAG=$(git tag --list 'v[0-9]*' | grep -Fxv -f <(printf '%s\n' "$TAGS_BEFORE") | tail -n1 || true)
+  fi
+  if [ -n "$NEW_TAG" ]; then
+    node "$CATCI" release dispatch-tagged-workflow "$NEW_TAG"
+  else
+    echo "no new release tag created — skipping taggedRelease dispatch"
+  fi
+fi

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

@@ -0,0 +1,154 @@
+---
+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".
+---
+
+# Component builds with catladder
+
+Each component in `catladder.ts` has a `build` config that catladder
+turns into the setup/lint/test/build CI jobs and the deployable Docker
+image. Change the build in `catladder.ts` and regenerate
+(`yarn catenv`) — never hand-edit generated pipeline files (see the
+`catladder-config` skill).
+
+```ts
+components: {
+  www: {
+    dir: "frontend",
+    build: {
+      type: "node",           // node | rails | meteor | custom (+ deprecated node-static/storybook)
+      buildCommand: "yarn build",
+      startCommand: "yarn start",
+    },
+    deploy: { /* see catladder-deploys */ },
+  },
+}
+```
+
+Set `build: false` to disable building for a component (e.g. a
+deploy-only or docker-tag component).
+
+Node-family builds work with **yarn or pnpm**: catladder autodetects the
+package manager (from the `packageManager` field in package.json or the
+lockfile) and generates the matching install commands, caches and
+default build/lint/test commands. Override with `packageManager:
+"pnpm" | "yarn"` at the top level of `catladder.ts` if needed. The
+`meteor` build type is yarn-only.
+
+pnpm gotchas: dependency build scripts must be approved in
+pnpm-workspace.yaml (`allowBuilds` map since pnpm 11,
+`onlyBuiltDependencies` list on pnpm 10); pnpm runs the root
+`prepare` script even during the production install in the docker
+build — guard husky with `"prepare": "husky || true"`; `pnpm run`
+prints a banner to stdout, so use `pnpm --silent run` in piped
+commands.
+
+## Build types
+
+| Type | Use for | Notes |
+|---|---|---|
+| `node` | Node/JS apps (Next.js, Vite, plain node) | default `<pm> build` + `<pm> start` (yarn or pnpm, autodetected); `docker` selects the runtime image |
+| `rails` | Ruby on Rails apps | Cloud Native Buildpacks when there is no `Dockerfile`; Postgres test DB |
+| `meteor` | Meteor apps | starts `node main.js` |
+| `custom` | anything else | you provide the `jobImage` and `docker` config (both required) |
+| `node-static`, `storybook` | *deprecated* | use `type: "node"` + `docker: { type: "nginx" }` |
+
+A component can also **reuse a shared workspace build** instead of a
+type: `build: { from: "web" }` (see workspace builds below).
+
+## Common options (all standalone build types)
+
+- `buildCommand` — the build step (`string | string[] | null | false`;
+  `false`/`null` skips building).
+- `startCommand` — how the app is started at runtime.
+- `postInstall` — commands run after the package-manager install (node
+  family; needed e.g. for Yarn PnP where `package.json` postinstall
+  won't run).
+- `lint` / `test` / `audit` — customize (`{ command, jobImage, … }`) or
+  set to `false` to disable that job.
+- `artifactsPaths` / `artifactsExcludePaths` — extra build artifacts
+  (`dist` and `.next` are always included).
+- `cache` — build caching (see the `catladder-pipelines` skill for the
+  caching model).
+- `jobImage`, `jobTags`, `jobVars`, `runnerVariables` — the CI image,
+  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).
+- `docker` — the image build strategy: a built-in
+  (`{ type: "nginx" | "node" | "meteor" }`) or
+  `{ type: "custom" }` (expects a `Dockerfile`).
+
+## 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,
+verify):
+
+```ts
+images: {
+  // (a) a directory in the repo (default context = the dir)
+  "java-build": {
+    dir: "docker/java-build",                 // contains the Dockerfile
+    buildArgs: { MAVEN_VERSION: "3.9.9" },    // optional, part of the content hash
+    hashExtraPaths: ["shared/settings.xml"],  // optional extra hashed+watched files
+  },
+  // (b) inline (default context = repo root); materialized into
+  // .catladder-generated/images/project/<name>/Dockerfile
+  "db-tools": {
+    dockerfile: ["FROM alpine:3.21", "RUN apk add --no-cache postgresql17-client"],
+  },
+},
+components: {
+  api: {
+    build: { type: "custom", jobImage: { image: "java-build" }, docker: { type: "custom" } },
+  },
+}
+```
+
+`dir` and `dockerfile` are mutually exclusive. `context` overrides the
+build context (relative to the repo root) — needed when the image
+`COPY`s files from outside its `dir`.
+
+Catladder generates a `🐳 image <name>` job (setup stage) that builds
+the image content-hashed into the project registry
+(`…/job-images/<name>:<hash>`) and skips when it already exists — works
+on GitLab and GitHub.
+
+**The build context is not hashed** (it can be the whole repo) — only
+the Dockerfile / `dir`, `buildArgs` and `hashExtraPaths` are. Files
+pulled in via `COPY` that should trigger a rebuild belong in
+`hashExtraPaths`.
+
+Generation (`yarn catenv`) fails fast on an undeclared image name, a
+missing `dir`, or a `dir` without a `Dockerfile`.
+
+## Workspace builds (monorepos)
+
+For a shared build across several components, declare it once at the top
+level under `builds` and reference it from each component:
+
+```ts
+builds: {
+  web: { type: "node", dir: "packages/web", buildCommand: "yarn build" },
+},
+components: {
+  www: { dir: "packages/web", build: { from: "web" }, deploy: { /* … */ } },
+}
+```
+
+Only `type: "node"` workspace builds exist today.
+
+## Full option reference
+
+See [references/build-types.md](references/build-types.md) for every
+build type's options, the `docker` sub-config, and the exact defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-deploys` — the matching `deploy` config
+- `catladder-pipelines` — how build jobs, caching and job images work
+- `catladder-secrets` — env vars available at build time
+- `catladder-migrate-package-manager` — migrating a project from yarn
+  to pnpm (or back)

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

@@ -0,0 +1,84 @@
+# catladder build config reference
+
+Full options for `components.<name>.build` (and top-level `builds`).
+Fix build problems in `catladder.ts` and regenerate — never edit the
+generated pipeline files.
+
+## Shared base options (all standalone build types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `buildCommand` | `string \| string[] \| null \| false` | build step; `false`/`null` skips it |
+| `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 |
+| `artifactsPaths` | `string[]` | extra artifacts (`dist`, `.next` always included) |
+| `artifactsExcludePaths` | `string[]` | artifact excludes |
+| `artifactsReports` | `{ junit?: string[] }` | CI test report paths |
+| `cache` | `CacheConfig \| CacheConfig[]` | build caching (`jobCache` is deprecated) |
+| `jobVars` | `EnvVars` | env vars only in build jobs |
+| `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 |
+| `docker` | see below | the deployable image strategy |
+
+`TestJobCustom` (for `lint`/`test`/`audit`): `command`, `jobImage`,
+`artifactsReports`, `artifacts`, `runnerVariables`, `allowFailure`
+(`allowFailure` defaults to `true` for `audit`).
+
+`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`,
+`yarn npm audit --severity`, classic `yarn audit --level`). Ignored when
+`command` spells out its own command:
+
+```ts
+audit: { level: "high" },   // fail on high and critical advisories
+```
+
+## Per-type options & defaults
+
+### `node`
+- Works with yarn **and pnpm** — the package manager is autodetected (`packageManager` field / lockfile), overridable via top-level `packageManager: "pnpm" | "yarn"` in `catladder.ts`.
+- `docker?` — built-in node image `{ type: "node", yarnRebuildEnabled?: boolean (default true, yarn berry only), additionsBegin?: string[], additionsEnd?: string[] }`, or a custom docker config.
+- Defaults: `buildCommand: "<pm> build"`, `startCommand: "<pm> start"` (`yarn`/`pnpm` per detection), artifacts `["dist", ".next"]`, excludes `[".next/cache/**/*"]`.
+
+### `rails`
+- `test?.databaseImage?` — test DB container image (Postgres only; default `docker.io/postgres:latest`).
+- `cnbBuilder?` — Cloud Native Buildpacks config, used only when there is **no `Dockerfile`**:
+  - `image?` — builder image. **Actual runtime default `heroku/builder:24`** (the type's JSDoc saying `heroku/buildpacks:20` is stale).
+  - `packVersion?` — pack CLI version. **Actual runtime default `0.36.4`** (JSDoc `0.28.0` is stale).
+  - `packExtraArgs?: string[]` — extra args passed to `pack`.
+  - `buildVars?: Record<string, string | undefined>` — Bundler / Rails asset-precompile vars (`undefined` inherits from the component's env vars).
+
+### `meteor`
+- Yarn-only (meteor's bundler is yarn-based) — a pnpm project cannot use this build type.
+- `installScripts?: boolean` — run `yarn install` inside the source folder in the image (only needed with custom image scripts).
+- `docker?` — meteor built-in or custom. Default `startCommand: "node main.js"`.
+
+### `custom`
+- `type: "custom"` — **required**.
+- `jobImage: JobImageConfig` — **required** CI image (concrete image or `{ image: "<name>" }` project-image ref).
+- `docker: BuildConfigDocker` — **required** image build config.
+- `jobServices?: Services` — services for lint/test/audit/build jobs.
+- `lint?` / `test?` / `audit?: TestJobCustom` — disabled unless set.
+
+### `node-static` / `storybook` — deprecated
+Use `type: "node"` with `docker: { type: "nginx" }` (and
+`startCommand: ""` for a purely static app). `storybook` previously
+defaulted `buildCommand: "yarn build-storybook --quiet -o ./dist"`.
+
+## `docker` sub-config
+
+`BuildConfigDocker` is either:
+
+- **built-in**: `{ type: "nginx" | "node" | "meteor", additionsBegin?: string[], additionsEnd?: string[] }` — `additionsBegin`/`additionsEnd` inject Dockerfile lines before/after the standard steps.
+- **custom**: `{ type: "custom", buildContextLocation?: "root" | "component" (default "root"), dockerfileContent?: string[] }` — expects a `Dockerfile`. `dockerfileContent` is experimental and supports the `$DOCKER_COPY_WORKSPACE_FILES` / `$DOCKER_COPY_AND_INSTALL_APP` placeholders.
+
+## Workspace builds (`builds`)
+
+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.

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

@@ -0,0 +1,56 @@
+---
+name: catladder-cli
+description: How to invoke the catladder CLI non-interactively — command structure, passing inputs via flags or --inputs JSON, skipping prompts, and the full generated command reference. Use when running any `catladder` command (project setup, doctor, secrets, k8s, ci, cloudsql, mongo) or when unsure which catladder command exists for a task. Triggers on "catladder command", "yarn catladder", "project doctor", "project setup", "run catladder".
+---
+
+# Using the catladder CLI
+
+catladder is installed per project — invoke it as `yarn catladder`
+(never a globally installed copy). Every command can run
+non-interactively, which is the mode agents should use.
+
+## Invocation
+
+```sh
+yarn catladder <command...> [args] [flags]
+
+# examples
+yarn catladder project doctor
+yarn catladder project ci job-log
+yarn catladder --help                 # command tree
+yarn catladder project --help         # subcommands of a group
+```
+
+## Passing inputs
+
+Commands declare typed inputs. Any input not provided on the command
+line is prompted for interactively — in a non-interactive context
+(agents!) provide them up front:
+
+- positional inputs: `yarn catladder project k8s list-pods dev:api`
+- flag per input: `--some-input value` (kebab-case of the input name),
+  booleans as `--flag` / `--no-flag`
+- all at once as JSON: `--inputs '{"envComponent": "dev:api"}'`
+- `-y` / `--yes` skips confirmation prompts
+
+A missing required input fails with a message naming the exact flag to
+pass. Environment/component selectors use the `env:component` form
+(e.g. `dev:api`, `review-123:www`).
+
+Some commands are inherently interactive (e.g.
+`project config-secrets` opens `$EDITOR`) — ask the user to run those.
+
+## Command reference
+
+See [references/commands.md](references/commands.md) for all commands
+with their descriptions and inputs (generated from the CLI itself, so
+it matches the installed version).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the component `build` config
+- `catladder-deploys` — the component `deploy` config
+- `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
+- `catladder-pipelines` — pipeline behavior and CI debugging