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

package/dist/bundles/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/bundles/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/bundles/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

package/dist/bundles/skills/catladder-cli/references/commands.md

@@ -0,0 +1,309 @@
+# catladder CLI command reference
+
+<!-- rendered from the command definitions by
+     apps/cli/src/scripts/generateCliSkillReference.ts — do not edit -->
+
+All commands run non-interactively as `yarn catladder <command> ...`
+(`pnpm catladder ...` in pnpm projects); see SKILL.md for how to
+pass inputs.
+
+## `catladder cloudsql restore-db`
+
+restore a db from one source to another target
+
+- `--source <value>`: Source instance (connection string or 'local')?
+- `--source-local-port <value>`: Local Port for source? (default: 5432)
+- `--source-username <value>`: Source Username? (default: "postgres")
+- `--source-password <value>`: Source Password?
+- `--source-db-name <value>`: Source DB name?
+- `--target <value>`: Target INSTANCE (connection string or 'local')?
+- `--target-local-port <value>`: Local Port for target? (default: 5432)
+- `--target-username <value>`: Target Username? (default: "postgres")
+- `--target-password <value>`: Target Password?
+- `--target-db-name <value>`: Target DB name?
+
+## `catladder fun dadjoke`
+
+something for jonas.
+
+## `catladder fun starwars`
+
+Long time ago... in a galaxy far far away...
+
+## `catladder k8s current-context`
+
+show current kubernetes context
+
+## `catladder k8s get-shell [namespace]`
+
+get a shell to a pod in the environment
+
+- `namespace` (positional): kubernetes namespace
+- `--pod-name <value>`: Which pod?
+
+## `catladder k8s list-namespaces`
+
+list all namespaces
+
+## `catladder k8s list-pods [namespace]`
+
+list all pods of namespace
+
+- `namespace` (positional): kubernetes namespace
+
+## `catladder k8s list-secrets [namespace]`
+
+show secrets
+
+- `namespace` (positional): kubernetes namespace
+
+## `catladder k8s port-forward [namespace]`
+
+start port-forwarding
+
+- `namespace` (positional): kubernetes namespace
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port:
+- `--remote-port <value>`: Remote port:
+
+## `catladder k8s stop-portforward [name]`
+
+stop a running port forward
+
+- `name` (positional): port forward name
+
+## `catladder k8s trigger-cronjob [namespace]`
+
+trigger cronjob
+
+- `namespace` (positional): kubernetes namespace
+- `--job-name <value>`: Which cronjob?
+
+## `catladder project ci job-log`
+
+Show a job's log
+
+- `--job-name <value>`: Which job?
+
+## `catladder project ci job-open`
+
+Open a Job
+
+- `--job-name <value>`: Which job?
+
+## `catladder project cloudsql proxy [envComponent]`
+
+proxy to cloud sql db
+
+- `envComponent` (positional): environment:component
+- `--local-port <value>`: Local port: (default: 54320)
+
+## `catladder project cloudsql restore-db`
+
+restores a project db from one source to another target
+
+- `--source <value>`: Source instance?
+- `--target <value>`: target env?
+- `--confirm-instance <value>`: confirm:
+
+## `catladder project config-secrets [envComponent]`
+
+setup/update secrets in the vault via your editor
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only edit these secrets (comma-separated keys)
+
+## `catladder project doctor [component]`
+
+Checks for drift between the config and the provisioned infrastructure (read-only): service accounts, IAM roles, gitlab tokens, github secrets, store entries.
+
+- `component` (positional): component name
+
+## `catladder project env-vars [envComponent]`
+
+list env vars
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s delete [envComponent]`
+
+deletes a environment of a project (it deletes the namespace)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s delete-pods [envComponent]`
+
+delete / restart pods
+
+- `envComponent` (positional): environment:component
+- `--selected-pod-names <value>`: Which pods to delete / restart ?
+
+## `catladder project k8s get-shell [envComponent]`
+
+get a shell to a pod in the environment
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project k8s list-pods [envComponent]`
+
+list pods of local project
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s namespace [envComponent]`
+
+show namespace of local project
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s pause [envComponent]`
+
+halts all running pods (scales to 0)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s trigger-cronjob [envComponent]`
+
+trigger cronjob
+
+- `envComponent` (positional): environment:component
+- `--job-name <value>`: Which cronjob?
+
+## `catladder project logs open [envComponent]`
+
+open logs for a component (Google Cloud Logging)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project mongo destroy-member [envComponent]`
+
+DESTROY a member of a replicaset in order to reinitialize it
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project mongo get-shell [envComponent]`
+
+get a shell to a mongodb in the environment
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project mongo port-forward [envComponent]`
+
+port forward to a mongodb
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port: (default: 30000)
+
+## `catladder project open env [envComponent]`
+
+open the live environment
+
+- `envComponent` (positional): environment:component
+
+## `catladder project open git`
+
+open the repo on gitlab / github in your browser
+
+## `catladder project port-forward [envComponent]`
+
+start port-forwarding
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port:
+- `--remote-port <value>`: Remote port:
+- `--mr <value>`: Which mr
+
+## `catladder project renew-token`
+
+Configures the project access token for semantic release.
+
+## `catladder project secrets-clear-backups`
+
+clears all backups
+
+- `--keep <value>`: How many backups should we keep? (default: 1)
+
+## `catladder project secrets-list [envComponent]`
+
+lists the declared secrets of a scope with their set/unset status (values only with --reveal)
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--reveal`: also print the secret values (default: false)
+- `--check`: exit with an error when any secret is unset (for CI/agents) (default: false)
+
+## `catladder project secrets-pull [envComponent]`
+
+prints the current secrets of a scope as yaml (unset ones as a placeholder) — edit and feed to secrets-push
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--out <value>`: write the yaml to this file instead of stdout
+
+## `catladder project secrets-push [envComponent]`
+
+writes secrets from a yaml document (secrets-pull format, --file or stdin) to the vault; may be partial
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only write these secrets (comma-separated keys)
+- `--file <value>`: yaml file to push (component → env → key: value); stdin when omitted
+
+## `catladder project secrets-set [envComponent] [key]`
+
+sets one secret — in one env (dev:web), one env everywhere (dev:), or all envs of a component (:web); value via --value, --value-file or stdin
+
+- `envComponent` (positional): scope: env:component, env:, or :component
+- `key` (positional): which secret?
+- `--value <value>`: the secret value (prefer --value-file or stdin over shell history)
+- `--value-file <value>`: read the secret value from this file
+
+## `catladder project secrets-sync-github [repo] [env]`
+
+copies all secrets from the vault to github repo secrets (same names), for the github pipeline
+
+- `repo` (positional): github repository (owner/name)
+- `env` (positional): only sync these environments (comma-separated, e.g. review,dev) — github allows at most 100 repo secrets
+
+## `catladder project security-evaluate`
+
+evaluate project's security audit document
+
+## `catladder project setup [component]`
+
+Initializes all environments and creates required resources, service accounts, etc.
+
+- `component` (positional): component name
+
+## `catladder project worktime`
+
+show the total worktime that you spent on a project
+
+## `catladder security audit ci-job [path] [token] [mainBranch] [projectId] [userId]`
+
+Evaluates security audit document. Creates MR with template if missing.
+
+- `path` (positional): path to project root
+- `token` (positional): GitLab token (api scope)
+- `mainBranch` (positional): main branch name
+- `projectId` (positional): GitLab project ID
+- `userId` (positional): GitLab user ID (assignee)
+
+## `catladder security audit create [token] [mainBranch] [projectId] [userId]`
+
+Creates a MR with the latest security audit template document
+
+- `token` (positional): GitLab token (api scope)
+- `mainBranch` (positional): main branch name
+- `projectId` (positional): GitLab project ID
+- `userId` (positional): GitLab user ID (assignee)
+
+## `catladder security audit evaluate [path]`
+
+Evaluates security audit document in given path
+
+- `path` (positional): path to project root