@catladder/cli 0.0.0-next-b3e567e8 → 0.0.0-next-78f04d3f

package/dist/packages/pipeline/src/index.d.ts

@@ -3,6 +3,8 @@ export * from "./backends";
 export * from "./types";
 export * from "./rules";
 export * from "./runner";
+export * from "./customImages/projectImages";
+export * from "./customImages/jobImagesPlan";
 export * from "./config";
 export * from "./store";
 export * from "./context";

package/dist/packages/pipeline/src/index.js

@@ -19,6 +19,8 @@ __exportStar(require("./backends"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./rules"), exports);
 __exportStar(require("./runner"), exports);
+__exportStar(require("./customImages/projectImages"), exports);
+__exportStar(require("./customImages/jobImagesPlan"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./store"), exports);
 __exportStar(require("./context"), exports);

package/dist/packages/pipeline/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/pipeline/src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,4CAA0B;AAC1B,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,qDAAmC;AACnC,sDAAoC;AACpC,kDAAgC;AAChC,2CAAyB;AACzB,gDAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/pipeline/src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,+DAA6C;AAC7C,+DAA6C;AAC7C,2CAAyB;AACzB,0CAAwB;AACxB,4CAA0B;AAC1B,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,qDAAmC;AACnC,sDAAoC;AACpC,kDAAgC;AAChC,2CAAyB;AACzB,gDAA8B"}

package/dist/packages/pipeline/src/types/config.d.ts

@@ -9,6 +9,7 @@ import type { Hooks } from "./hooks";
 import type { ReleaseConfig } from "./release";
 import type { CatladderStore } from "../store";
 import type { AgentSkillsConfig } from "../agentSkills/types";
+import type { ProjectImageConfig } from "../customImages/projectImages";
 import type { VerifyConfig } from "../verify/types";
 export declare const ALL_PIPELINE_TRIGGERS: readonly ["mainBranch", "mr", "taggedRelease"];
 export type PipelineTrigger = (typeof ALL_PIPELINE_TRIGGERS)[number];
@@ -294,6 +295,13 @@ export type Config<C extends ConfigProps = never> = {
      */
     domainCanonical?: string;
     agents?: Record<string, AgentConfig>;
+    /**
+     * docker images declared by the project, built automatically in the
+     * pipeline: content-hashed into the project's own registry and only
+     * rebuilt when their inputs change. Reference them in any `jobImage`
+     * field via `{ image: "<key>" }`.
+     */
+    images?: Record<string, ProjectImageConfig>;
     builds?: Record<string, WorkspaceBuildConfig>;
     /**
      * components (sub apps)

package/dist/packages/pipeline/src/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAca,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAGX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEX;;;;GAIG;AACI,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAE,EAAE,CAC/D,MAAM,CAAC,OAAO,CAAC,iBAAS,CAAC;KACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,CAAC,CAAC,QAAuC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC7D;KACA,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAY,CAAC,CAAC;AALnB,QAAA,oBAAoB,wBAKD;AAEnB,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAea,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAGX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEX;;;;GAIG;AACI,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAE,EAAE,CAC/D,MAAM,CAAC,OAAO,CAAC,iBAAS,CAAC;KACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,CAAC,CAAC,QAAuC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC7D;KACA,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAY,CAAC,CAAC;AALnB,QAAA,oBAAoB,wBAKD;AAEnB,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB"}

package/dist/packages/pipeline/src/types/github-types.d.ts

@@ -38,6 +38,7 @@ export type GithubJob = {
     permissions?: Record<string, string>;
     if?: string;
     "continue-on-error"?: boolean;
+    outputs?: Record<string, string>;
     steps: GithubStep[];
 };
 export type GithubWorkflow = {

package/dist/packages/pipeline/src/types/jobs.d.ts

@@ -1,5 +1,6 @@
 import type { UnspecifiedEnvVars } from "..";
 import type { CatladderImageRef } from "../runner";
+import type { ProjectImageRef } from "../customImages/projectImages";
 import type { CacheConfig } from "../build/types";
 import type { Artifacts, GitlabJobCache, GitlabJobDef, GitlabJobImage, GitlabRule } from "./gitlab-types";
 export type CatladderJobCache = GitlabJobCache & {
@@ -186,7 +187,7 @@ export type GitlabJobFields = {
      * catladder-provided job image (resolved by the backend to an image
      * built in the repository's own registry)
      */
-    image?: GitlabJobImage | CatladderImageRef;
+    image?: GitlabJobImage | CatladderImageRef | ProjectImageRef;
     /**
      * whether failures are allowed
      */

package/dist/packages/pipeline/src/types/jobs.js.map

@@ -1 +1 @@
-{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/jobs.ts"],"names":[],"mappings":";;;AAGA,8DAA2D;AAsB9C,QAAA,WAAW,GAAG;IACzB,OAAO;IACP,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,MAAM;CACE,CAAC;AAWE,QAAA,YAAY,GAAG;IAC1B,OAAO;IACP,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,YAAY;CACJ,CAAC;AA6NX;;;;;;;GAOG;AACH,4JAA4J;AAC5J,MAAa,YAAY;IACvB,YAAY,IAAyB;QACnC,uDAAuD;QACvD,2DAA2D;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAA,iCAAe,EAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,CAAC,IAAI,CACT,GAAkD;QAElD,OAAO,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;CACF;AAZD,oCAYC"}
+{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/jobs.ts"],"names":[],"mappings":";;;AAIA,8DAA2D;AAsB9C,QAAA,WAAW,GAAG;IACzB,OAAO;IACP,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,MAAM;CACE,CAAC;AAWE,QAAA,YAAY,GAAG;IAC1B,OAAO;IACP,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,YAAY;CACJ,CAAC;AA6NX;;;;;;;GAOG;AACH,4JAA4J;AAC5J,MAAa,YAAY;IACvB,YAAY,IAAyB;QACnC,uDAAuD;QACvD,2DAA2D;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAA,iCAAe,EAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,CAAC,IAAI,CACT,GAAkD;QAElD,OAAO,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;CACF;AAZD,oCAYC"}

package/dist/packages/pipeline/src/types/release.d.ts

@@ -14,7 +14,13 @@ export type ReleaseMethod = "semantic-release" | "changesets";
 export type ReleaseConfig = {
     /**
      * Whether to release automatically or manually on main branch.
-     * Defaults to "manuel"
+     * - "manual" (default): the pipeline offers a `create release`
+     *   button that can be clicked at any time — the release then runs
+     *   automatically as soon as every other job of the pipeline
+     *   succeeded (clicking after a green pipeline releases right away).
+     *   A `force create release` button releases immediately, ignoring
+     *   the pipeline state.
+     * - "auto": every main-branch pipeline releases at the end.
      */
     when?: "manual" | "auto";
     /**

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

@@ -1,6 +1,6 @@
 ---
 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, and shared workspace builds). Use when adding or changing a component's build, choosing a build type, wiring a Dockerfile/nginx image, tuning the build/test/lint jobs, or setting up a monorepo workspace build. Triggers on "build config", "buildCommand", "build type", "Dockerfile", "docker image", "rails build", "monorepo build", "artifacts".
+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
@@ -71,11 +71,58 @@ type: `build: { from: "web" }` (see workspace builds below).
 - `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.
+  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

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

@@ -19,7 +19,7 @@ generated pipeline files.
 | `jobVars` | `EnvVars` | env vars only in build jobs |
 | `runnerVariables` | `Record<string,string>` | extra runner vars (also for `services:`) |
 | `jobTags` | `string[]` | runner tags |
-| `jobImage` | `GitlabJobImage` | custom CI image for the build |
+| `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`,
@@ -48,7 +48,7 @@ generated pipeline files.
 
 ### `custom`
 - `type: "custom"` — **required**.
-- `jobImage: GitlabJobImage` — **required** CI image.
+- `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.

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

@@ -29,13 +29,23 @@ plus stop jobs for review-app teardown.
 
 ## Job images and catci
 
-Jobs run in catladder-provided images. Their definitions are
-materialized into `.catladder-generated/images/` and built in the
-project's own registry (content-hashed, rebuilt only on change).
+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; node builds cache

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

@@ -23,12 +23,23 @@ are generated, never hand-edited.
 ## `when` — who triggers the release
 
 - **`manual`** (default) — the `create release` job on the main branch
-  is manual; someone runs it to cut a release.
+  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 the `create-release` dispatch task 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 manual **`⚠️ force create release`** job as an
-escape hatch. With `method: "changesets"` it has an extra meaning: it
+escape hatch: it releases **immediately**, ignoring the state of the
+pipeline. With `method: "changesets"` it 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.