@catladder/cli 0.0.0-next-b3e567e8 → 0.0.0-next-dccc0a36

package/dist/packages/pipeline/src/customImages/projectImages.d.ts

@@ -0,0 +1,67 @@
+import type { GitlabJobImage } from "../types/gitlab-types";
+/**
+ * a docker image declared by the project (`config.images`): built
+ * automatically in the pipeline, content-hashed into the project's own
+ * registry and rebuilt only when its inputs change.
+ */
+type ProjectImageCommon = {
+    /**
+     * the docker build context, relative to the repository root.
+     *
+     * Defaults to `dir` for a directory-based image, and to the
+     * repository root (`.`) for an inline `dockerfile`.
+     *
+     * NOTE: the context itself is not hashed — only the Dockerfile (or
+     * `dir`), `buildArgs` and `hashExtraPaths` are. List files that are
+     * `COPY`ed from a wider context in `hashExtraPaths` if changing them
+     * should rebuild the image.
+     */
+    context?: string;
+    /**
+     * extra files that influence the image content — they become part of
+     * the content hash and the change detection
+     */
+    hashExtraPaths?: string[];
+    /**
+     * docker `--build-arg` values passed to the image build, part of the
+     * content hash
+     */
+    buildArgs?: Record<string, string>;
+};
+/**
+ * where the image definition comes from: a directory in the repository
+ * containing a `Dockerfile`, or an inline Dockerfile written straight
+ * into the config (materialized into the generated files)
+ */
+export type ProjectImageConfig = ProjectImageCommon & ({
+    /**
+     * directory containing the `Dockerfile`, relative to the
+     * repository root. Also the default build context.
+     */
+    dir: string;
+    dockerfile?: never;
+} | {
+    /**
+     * the Dockerfile content, as one string or as lines. Written to
+     * `.catladder-generated/images/project/<name>/Dockerfile`; the
+     * build context defaults to the repository root.
+     */
+    dockerfile: string | string[];
+    dir?: never;
+});
+/**
+ * a reference to a project-declared job image (`config.images`), usable
+ * in every `jobImage` field. The pipeline backends resolve it to the
+ * concrete content-hashed image url in the project registry.
+ */
+export type ProjectImageRef = {
+    /** the key of the image in `config.images` */
+    image: string;
+};
+export declare const isProjectImageRef: (value: unknown) => value is ProjectImageRef;
+/**
+ * everything a `jobImage` config field accepts: a concrete image (url
+ * or gitlab image object) or a reference to a project-declared image
+ */
+export type JobImageConfig = GitlabJobImage | ProjectImageRef;
+export {};

package/dist/packages/pipeline/src/customImages/projectImages.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProjectImageRef = void 0;
+const isProjectImageRef = (value) => typeof value === "object" &&
+    value !== null &&
+    "image" in value &&
+    typeof value.image === "string";
+exports.isProjectImageRef = isProjectImageRef;
+//# sourceMappingURL=projectImages.js.map

package/dist/packages/pipeline/src/customImages/projectImages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectImages.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/customImages/projectImages.ts"],"names":[],"mappings":";;;AAoEO,MAAM,iBAAiB,GAAG,CAAC,KAAc,EAA4B,EAAE,CAC5E,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAO,IAAI,KAAK;IAChB,OAAQ,KAAyB,CAAC,KAAK,KAAK,QAAQ,CAAC;AAJ1C,QAAA,iBAAiB,qBAIyB"}

package/dist/packages/pipeline/src/deploy/types/custom.d.ts

@@ -1,5 +1,5 @@
 import type { WithCacheConfig } from "../../build";
-import type { GitlabJobImage } from "../../types";
+import type { JobImageConfig } from "../../customImages/projectImages";
 import type { DeployConfigBase } from "./base";
 export type DeployConfigCustom = {
     /**
@@ -31,7 +31,7 @@ export type DeployConfigCustom = {
     /**
      * image to use
      */
-    jobImage?: GitlabJobImage;
+    jobImage?: JobImageConfig;
     /**
      * job artifact paths the deploy produces (relative to the repo root)
      */

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

@@ -15,17 +15,17 @@ export type DeployConfigType = DeployConfig["type"];
 export type DeployConfigGeneric<T extends DeployConfigType> = Extract<DeployConfig, {
     type: T;
 }>;
-export declare const isOfDeployType: <T extends ("custom" | "kubernetes" | "dockerTag" | "google-cloudrun" | "npmPackage" | "pages")[]>(t: DeployConfig | false | null | undefined, ...types: T) => t is Extract<DeployConfigCustom, {
+export declare const isOfDeployType: <T extends ("custom" | "kubernetes" | "pages" | "google-cloudrun" | "dockerTag" | "npmPackage")[]>(t: DeployConfig | false | null | undefined, ...types: T) => t is Extract<DeployConfigKubernetes, {
     type: T[number];
-}> | Extract<DeployConfigDockerTag, {
+}> | Extract<DeployConfigCustom, {
     type: T[number];
 }> | Extract<DeployConfigCloudRun, {
     type: T[number];
-}> | Extract<DeployConfigKubernetes, {
+}> | Extract<DeployConfigDockerTag, {
     type: T[number];
 }> | Extract<DeployConfigNpmPackage, {
     type: T[number];
 }> | Extract<DeployConfigPages, {
     type: T[number];
 }>;
-export declare const getDeployConfigType: (t: DeployConfig | false | null | undefined) => "custom" | "kubernetes" | "dockerTag" | "google-cloudrun" | "npmPackage" | "pages";
+export declare const getDeployConfigType: (t: DeployConfig | false | null | undefined) => "custom" | "kubernetes" | "pages" | "google-cloudrun" | "dockerTag" | "npmPackage";

package/dist/packages/pipeline/src/deploy/types/pages.d.ts

@@ -1,5 +1,5 @@
 import type { WithCacheConfig } from "../../build";
-import type { GitlabJobImage } from "../../types";
+import type { JobImageConfig } from "../../customImages/projectImages";
 import type { DeployConfigBase } from "./base";
 export type DeployConfigPages = {
     /**
@@ -39,5 +39,5 @@ export type DeployConfigPages = {
     /**
      * image to use
      */
-    jobImage?: GitlabJobImage;
+    jobImage?: JobImageConfig;
 } & DeployConfigBase & WithCacheConfig;

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