@catladder/cli 0.0.0-next-80fd0ab4 → 0.0.0-next-ebc933f2

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

@@ -0,0 +1,82 @@
+---
+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" },  // build types: node | rails | base
+      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom
+      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`).
+
+## 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.
+
+## Related skills
+
+- `catladder-secrets` — env vars and secret management
+- `catladder-pipelines` — how the generated pipelines work, debugging CI
+- `catladder-cli` — non-interactive CLI usage and command reference

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

@@ -0,0 +1,72 @@
+---
+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).
+
+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. With `jobImages: "repo"`, image
+definitions are materialized into `.catladder-generated/images/` and
+built in the project's own registry (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.
+
+## Caching
+
+Cache configuration is generated per build type; node builds cache
+`node_modules` and the yarn cache. GitLab uses mutable caches with
+fallback keys (review branches fall back to the dev cache); GitHub uses
+immutable lockfile-keyed caches where only the build job writes.
+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 via catci.
+
+## 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-secrets` — env vars and secret management
+- `catladder-cli` — non-interactive CLI usage and command reference

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

@@ -0,0 +1,74 @@
+---
+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 or rotated, 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".
+---
+
+# 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:
+
+```sh
+yarn catladder project config-secrets
+```
+
+This opens all env vars as YAML in `$EDITOR` (use e.g.
+`EDITOR="code --wait"`); on save, catladder upserts the changed values
+into the secrets vault. **An agent cannot drive this interactive
+editor** — when a new secret *value* is needed, add the name to
+`vars.secret`, regenerate, and ask the user to run
+`project config-secrets` themselves.
+
+## 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-pipelines` — how the generated pipelines work
+- `catladder-cli` — non-interactive CLI usage and command reference