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

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

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

@@ -0,0 +1,125 @@
+---
+name: catladder-config
+description: Working with catladder, the framework that generates this repository's CI/CD pipelines (GitLab CI and/or GitHub Actions) from catladder.ts. Use when editing catladder.ts, adding or changing components, builds, deploys, environments or env vars, or when a change to generated pipeline files (.catladder-generated/, .gitlab-ci.yml, .github/workflows/) seems needed. Triggers on "catladder", "catladder.ts", "add a component", "change the pipeline", "deploy config".
+---
+
+# Working with catladder
+
+catladder generates this repository's CI/CD pipelines, deployments and
+environment files from the TypeScript config `catladder.ts` at the repo
+root. It is installed per project (`@catladder/cli`) — always use the
+locally installed version (`yarn catenv`, `yarn catladder`).
+
+## Golden rules
+
+1. **Never hand-edit generated files.** Everything under
+   `.catladder-generated/`, the generated parts of `.gitlab-ci.yml`, and
+   catladder-generated workflows under `.github/workflows/` are
+   overwritten on every regeneration (they carry a "generated by
+   catladder" header). To change them, change `catladder.ts` and
+   regenerate.
+2. **Regenerate after every `catladder.ts` change** by running
+   `yarn catenv`. With direnv set up, re-entering the project directory
+   does this automatically.
+3. **Commit the regenerated files together with the config change.**
+   Generated files are checked in; CI includes them directly.
+
+## Structure of catladder.ts
+
+```ts
+import type { Config } from "@catladder/cli";
+
+const config = {
+  appName: "my-app",
+  customerName: "pan",
+  pipelines: { gitlab: true, github: true }, // which CI systems to generate
+  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
+      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
+      env: {                    // enable/customize per environment
+        review: {},
+        dev: {},
+        stage: false,           // false disables the env for this component
+        prod: {},
+      },
+    },
+  },
+} satisfies Config;
+
+export default config;
+```
+
+Key concepts:
+
+- **Components** are the sub-apps/services of the project (frontend,
+  api, ...). Each has a build config and a deploy config.
+- **Environments**: `dev` (deployed on push to the main branch),
+  `review` (per merge/pull request), `stage` and `prod` (deployed on
+  tagged releases), `local` (only for local development via catenv).
+  Per-env overrides live under `env.<name>` and can override vars,
+  deploy settings, and more.
+- **Pipelines**: `pipelines: { gitlab: true, github: true }` selects
+  which CI systems get generated files. Options objects instead of
+  `true` allow per-pipeline settings (e.g. `runnerVariables`).
+- **Package manager**: yarn and pnpm are supported and autodetected
+  (from the `packageManager` field in package.json or the lockfile;
+  yarn is the fallback). `packageManager: "pnpm" | "yarn"` at the top
+  level overrides the detection. In pnpm projects, run the CLIs as
+  `pnpm catenv` / `pnpm catladder`.
+
+## Common tasks
+
+- **Add a component**: add an entry under `components`, run
+  `yarn catenv`, commit config + generated files.
+- **Change resources / deployment settings**: edit the component's
+  `deploy` (or per-env override), regenerate.
+- **Inspect the resulting pipeline**: read the generated files (e.g.
+  `.catladder-generated/gitlab/`, `.github/workflows/`) — but never
+  edit them.
+
+## Escape hatches — last resort, and a signal to file an issue
+
+catladder has two escape hatches for things it doesn't (yet) support
+natively:
+
+- **`customJobs`** (per component) — hand-written CI job specs injected
+  into the pipeline.
+- **transform `hooks`** (top-level `hooks`) —
+  `transformFileBeforeWrite` / `transformYamlBeforeWrite` rewrite the
+  generated files just before they're written to disk.
+
+Both work, but they are **fragile by design**: they depend on the exact
+shape of catladder's generated output, so a catladder upgrade can break
+them silently, and they sit outside everything the rest of the config
+gives you (rules, caching, images, per-env logic, snapshots). Prefer a
+first-class config option whenever one exists — check the `build`,
+`deploy`, `releases`, and env/vars surfaces (and the sibling skills)
+first.
+
+**When you do reach for one, treat it as a missing-feature signal.** If
+a dev needs `customJobs` or a transform hook, it almost always means
+catladder is missing a capability that other projects will need too.
+**Open an issue at
+https://github.com/panter/catladder/issues** describing the use
+case (what you're trying to achieve and why the existing config can't
+express it) so it can be generalized into a supported feature — and,
+where possible, offer to help the dev write that issue. The goal is for
+escape hatches to shrink over time, not accumulate.
+
+## Related skills
+
+- `catladder-builds` — the component `build` config (build types, Docker)
+- `catladder-deploys` — the component `deploy` config (k8s, Cloud Run, …)
+- `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
+- `catladder-pipelines` — how the generated pipelines work, debugging CI
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving a project between GitLab CI
+  and GitHub Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets
+- `catladder-migrate-package-manager` — switching a project between
+  yarn and pnpm

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

@@ -0,0 +1,146 @@
+---
+name: catladder-deploys
+description: Configuring how a component is deployed in a catladder project — the `deploy` config in catladder.ts (deploy types kubernetes / google-cloudrun / npmPackage / pages / dockerTag / custom, manual vs auto deploy, resources, autoscaling, health checks, CloudSQL/MongoDB, Cloud Run services/jobs/worker pools, cron jobs). Use when adding or changing a component's deploy, choosing a deploy target, setting resources/replicas/autoscaling, wiring a database, adding cron/scheduled jobs, publishing a component as an npm package, publishing a site on gitlab pages, or making a deploy manual. Triggers on "deploy config", "deploy type", "kubernetes", "cloud run", "cloudrun", "autoscale", "resources", "replicas", "cloudsql", "mongodb", "cronjob", "manual deploy", "npm package", "npm publish", "publish to npm", "gitlab pages", "static site", "docs site", "site preview".
+---
+
+# Component deploys with catladder
+
+Each component in `catladder.ts` has a `deploy` config that catladder
+turns into the deploy (and stop) CI jobs and the cloud resources. Change
+the deploy in `catladder.ts` and regenerate (`yarn catenv`) — never
+hand-edit generated files (see the `catladder-config` skill). Cloud
+resources themselves are provisioned separately with
+`yarn catladder project setup` (see the `catladder-cli` skill).
+
+```ts
+components: {
+  api: {
+    dir: "backend",
+    build: { /* see catladder-builds */ },
+    deploy: {
+      type: "kubernetes",         // kubernetes | google-cloudrun | npmPackage | pages | dockerTag | custom
+      cluster: { type: "gcloud", name: "…", projectId: "…", region: "…" },
+      values: { application: { replicas: 2 } },
+    },
+  },
+}
+```
+
+## Deploy types
+
+| Type | Deploys to | Requires |
+|---|---|---|
+| `kubernetes` | a GKE cluster via Helm | `cluster` |
+| `google-cloudrun` | Google Cloud Run | `projectId`, `region` |
+| `npmPackage` | publishes the component to an npm registry | nothing — see below |
+| `pages` | publishes a static site on gitlab pages | `script` — see below |
+| `dockerTag` | tags an image (no runtime) | `tag` — rarely used, not generally recommended |
+| `custom` | your own script | `requiresDocker`, `script` |
+
+## Manual vs automatic deploys
+
+`when: "manual" | "auto"` controls whether the deploy job runs
+automatically. **Default: `prod` is `manual`, every other environment
+is `auto`.** Set per component or per environment (`env.<name>.deploy`).
+
+`waitFor: ["otherComponent"]` (experimental) makes a deploy wait for
+another component to deploy first.
+
+## Kubernetes essentials
+
+`cluster` is required: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+Everything app-level lives under `values`:
+
+- `application` — `replicas`, `autoscale` (`minReplicas`/`maxReplicas`/`metrics`),
+  `resources` (cpu/memory limits & requests), `healthRoute`,
+  `startupProbe`/`readinessProbe`/`livenessProbe`, `command`,
+  `redirects`, `worker` (a separate background deployment). Set
+  `application: false` for a component with no long-running deployment.
+- `cloudsql` — attach an (unmanaged) CloudSQL Postgres instance.
+- `mongodb` — a Bitnami MongoDB (`standalone` or `replicaset`).
+- `jobs` — Helm post-install/upgrade jobs; `cronjobs` — scheduled jobs.
+
+## Cloud Run essentials
+
+`projectId` and `region` are required. Then:
+
+- `service` — the main service (`minInstances`, `maxInstances`, `cpu`,
+  `memory`, `timeout`, `allowUnauthenticated`, `ingress`, `healthCheck`,
+  …). `service: false` disables it (job-only deployments).
+- `additionalServices`, `jobs`, `workerPools` — extra services, run-to-
+  completion jobs, and always-on background worker pools.
+- `cloudSql` — attach an (unmanaged) CloudSQL instance; choose the
+  connection-string format (`prisma` default, `rails`, `jdbc`).
+- `execute` — run a script/job/HTTP call at a deploy lifecycle point
+  (`preDeploy`/`postDeploy`/`preStop`/`postStop`) or on a `schedule`.
+  Prefer this over the deprecated `when`/`schedule` fields on `jobs`.
+
+## npm packages
+
+`type: "npmPackage"` publishes the component to an npm registry instead
+of deploying a service — "deploy" means `npm publish`. Version and
+dist-tag derive from the pipeline trigger:
+
+- tagged release (`prod` env): the tag's version (`v5.1.2` → `5.1.2`)
+  under dist-tag `latest`
+- main branch (`dev`) and merge requests (`review`): an installable
+  canary `0.0.0-<branch-slug>-<sha>`; branches named `next`/`beta` get
+  their own dist-tag, everything else publishes under `canary`
+
+Options (all optional): `access` (`"public"` default), `registry`
+(npmjs.org default), `distTag` (overrides the derivation).
+
+```ts
+lib: {
+  dir: "lib",
+  env: { stage: false },   // npm has no staging — publish latest directly
+  build: { type: "node" },
+  deploy: { type: "npmPackage" },
+},
+```
+
+Authentication uses the `NPM_TOKEN` secret (set it like any other
+catladder secret, see `catladder-secrets`). Disable the stage
+environment as shown — a tagged release then publishes `latest`
+directly from the auto-deploying prod env.
+
+## GitLab pages sites
+
+`type: "pages"` publishes a static site (docs, storybook, coverage
+report) on gitlab pages: the deploy job runs your build `script` and
+publishes `publishDir` (default `"public"`). Review environments
+automatically publish under an `mr-<iid>` path prefix — every merge
+request gets its own site preview (the prefix is exposed to the build
+as `$PAGES_PREFIX`). The gitlab environment url points at the
+published site. GitLab-only for now.
+
+```ts
+docs: {
+  dir: "docs",
+  env: { stage: false, prod: false },  // pages exist on main + MRs
+  build: false,
+  deploy: {
+    type: "pages",
+    requiresInstall: true,
+    script: ["yarn workspace docs build"],
+  },
+},
+```
+
+Pages deploys default to `allowFailure: true` (a broken site publish
+should not block the pipeline). `allowFailure` is also available on
+every other deploy type, and custom deploys can now declare
+`artifactsPaths` for output they produce.
+
+## Full option reference
+
+See [references/deploy-types.md](references/deploy-types.md) for every
+deploy type's options, required fields, and defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the matching `build` config
+- `catladder-pipelines` — how deploy jobs, environments and review apps work
+- `catladder-cli` — `project setup` (provision cloud resources) and `project doctor`
+- `catladder-secrets` — env vars available at runtime

package/dist/skills/catladder-deploys/references/deploy-types.md

@@ -0,0 +1,83 @@
+# catladder deploy config reference
+
+Full options for `components.<name>.deploy` (and per-env
+`env.<name>.deploy`). Fix deploy problems in `catladder.ts` and
+regenerate — never edit generated files. Provision the underlying cloud
+resources with `yarn catladder project setup`; detect drift with
+`yarn catladder project doctor`.
+
+## Shared base (all deploy types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `when` | `"manual" \| "auto"` | prod → `manual`, other envs → `auto` |
+| `waitFor` | `string[]` | EXPERIMENTAL; wait for other components first |
+| `jobTags` | `string[]` | runner tags |
+| `jobVars` | `EnvVars` | env vars only in the deploy job |
+| `runnerVariables` | `Record<string,string>` | extra runner vars |
+
+(Cloud Run defines its own `execute`; otherwise the base applies to all.)
+
+## `kubernetes`
+
+- `cluster` — **required**: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+- `debug?: boolean` — pass `--debug` to Helm.
+- `additionalHelmArgs?: string[]`.
+- `chartName?: string` — custom chart location (not recommended).
+- `values?` — app configuration (unknown props allowed, forwarded to the chart):
+  - `application?: false | { command?, enabled? (default true), redirects?, hostAliases?, replicas?, autoscale?: { minReplicas, maxReplicas, metrics[] }, updateStrategy?, resources?: { limits/requests: { cpu, memory } }, healthRoute?, startupProbe? / readinessProbe? / livenessProbe? (httpGet shape), worker?, jobDefaults? }`.
+  - `cloudsql?: { type: "unmanaged", enabled, instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName? }`.
+  - `mongodb?: { enabled?, dbName?, persistence?, resources?, tolerations? } & ({ architecture: "standalone" } | { architecture: "replicaset", replicaCount? (default 2) })`.
+  - `mailhog?: { enabled }` — dev mail catcher (injects `MAIL_URL`).
+  - `jobs?: Record<string, false | { command, hook? }>` — Helm hook jobs (default hook `post-install,post-upgrade`).
+  - `cronjobs?: Record<string, false | { schedule, command, concurrencyPolicy?, timeZone? }>`.
+  - `secretsFromOtherComponent?: { [envVar]: string }` — load secrets from another component in the same cluster.
+  - `mapServiceUrlToEnv?: { [envVar]: string }` — map another service's internal endpoint to an env var.
+
+## `google-cloudrun`
+
+- `projectId` — **required**.
+- `region` — **required** (`Gcloudregion` enum, e.g. `europe-west6`).
+- `service?: boolean | DeployConfigCloudRunService` (default enabled):
+  - `command?`, `args?`, `image?`, `minInstances?` (0), `maxInstances?` (100), `cpu?` (1|2|4|6|8), `memory?` (512MB), `timeout?` (5min), `noCpuThrottling?`, `allowUnauthenticated?` (true), `ingress?` (`all` | `internal` | `internal-and-cloud-load-balancing`, default `all`), `executionEnvironment?` (`gen1`|`gen2`), `http2?`, `gpu?`/`gpuType?`, `sessionAffinity?`, `healthCheck?` (`true` or `{ startupProbe, livenessProbe }`), plus cloud-storage volumes and VPC network config.
+- `additionalServices?: Record<string, service | false | null>`.
+- `jobs?: Record<string, DeployConfigCloudRunJob | false | null>` — `{ command, args?, image?, cpu?, memory? (512Mi), timeout? (10min), parallelism? (1), maxRetries? (0) }`. The per-job `when`/`schedule`/`waitForCompletion` fields are **deprecated** — use `execute`.
+- `workerPools?: Record<string, DeployConfigCloudRunWorkerPool | false | null>` — always-on background work, no endpoint, no autoscaling: `{ command, instances? (1), cpu?, memory?, image?, args?, gpu?/gpuType? }`.
+- `cloudSql?: DeployConfigCloudRunCloudSql | false` — `{ type: "unmanaged", instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName?, deleteDatabaseOnStop?, dbConnectionStringFormat? ("prisma" default | "rails" | "jdbc"), dbConnectionStringVariablesMode? ("embedded" default | "legacy"), dbAdditionalQueryParams? }`. Injects `DB_*` vars plus `DATABASE_URL`/`DATABASE_JDBC_URL`; in the default `"embedded"` mode the connection strings contain the component's final values (referenceable from other components, `vars.public` overrides of `DB_*` flow in). To share another component's database: `dbBaseName: "<owner>"` + `DB_PASSWORD: "${<owner>:DB_PASSWORD}"` in `vars.public`.
+- `execute?: Record<string, DeployConfigCloudRunExecute | null>` — run a script / job / HTTP call at a lifecycle point (`when`: `preDeploy` | `postDeploy` | `preStop` | `postStop`) or on a `schedule`.
+- `debug?: boolean`.
+- Service name and url: the service deploys as `<customerName>-<appName>-<env>[-<reviewSlug>]-<componentName>`, and `ROOT_URL`/`ROOT_URL_INTERNAL` are cloud run's deterministic url `https://<service>-<projectNumber>.<region>.run.app`. That url only exists while its first dns label stays within 63 characters, so catladder **shortens the component part** of the service name when it would not fit — otherwise cloud run would serve a legacy url with a random identifier and the generated hostname would never resolve. Review environments carry a runtime slug on top, for which 8 characters are reserved, so a name can fit `dev`/`prod` and still be shortened for `review`. Generation fails instead of shortening when two components would end up with the same name, or when customerName/appName/env/project number already leave no room.
+
+## `npmPackage`
+
+- `type: "npmPackage"` — **required**. Publishes the component as an npm package: the deploy job stamps the derived version into `package.json` and runs `npm publish` (via catci).
+- `access?: "public" | "restricted"` — npm access level, default `"public"`.
+- `registry?: string` — registry url, default `https://registry.npmjs.org/`.
+- `distTag?: string` — overrides the derived dist-tag.
+- Version/dist-tag derivation: tagged release (`prod`) → tag version under `latest`; branch/MR → `0.0.0-<branch-slug>-<sha>` under `canary` (branches `next`/`beta` publish under their own dist-tag).
+- Auth: the `NPM_TOKEN` secret (managed like any catladder secret), or — on github — **trusted publishing** with no stored token: register the package's trusted publisher on npmjs.com with the repo and the publishing **workflow filename** (`catladder-release.yml` for tagged releases). npm allows one trusted publisher per package, so canary publishes from the main/review workflows still need `NPM_TOKEN`. A set token always wins over OIDC.
+- Disable staging on the component (`env: { stage: false }`) so tagged releases publish directly.
+
+## `pages`
+
+- `type: "pages"` — **required**. Publishes a static site on gitlab pages or github pages. On github the repo's Pages source must be set to "GitHub Actions" once; per-merge-request previews are gitlab-only (github serves one site per repository).
+- `script: string[]` — **required**; produces the site.
+- `publishDir?: string` — output directory relative to the repo root, default `"public"`.
+- `requiresInstall?: boolean` — run the package-manager install (yarn/pnpm) first (`requiresYarnInstall` is a deprecated alias).
+- `jobImage?: GitlabJobImage`; also accepts `cache`.
+- Review envs publish under an `mr-<iid>` path prefix (parallel deployments → MR previews; exposed as `$PAGES_PREFIX`); other envs publish at the root. The environment url is the published pages url.
+- Defaults to `allowFailure: true`.
+
+## `dockerTag`
+
+- `type: "dockerTag"`, `tag: string` — **required**. Adds a custom tag on the image repo to deploy it. Only used in one project historically; not generally recommended (runtime env vars must be coordinated manually).
+
+## `custom`
+
+- `type: "custom"` — **required**.
+- `requiresDocker: boolean` — **required**; whether the deploy needs a built Docker image.
+- `script: string[]` — **required**; the deploy script.
+- `requiresInstall?: boolean` — whether the script needs the package-manager install (`requiresYarnInstall` is a deprecated alias).
+- `stopScript?: string[]` — script to stop/tear down the environment.
+- `jobImage?: GitlabJobImage`.
+- Also accepts `cache` (via `WithCacheConfig`).