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

package/dist/bundles/catenv/index.js

@@ -2321,7 +2321,7 @@ class GithubBackend {
         await (0, promises_1.rm)(scriptFiles_1.GITHUB_SCRIPTS_FOLDER, { recursive: true, force: true });
     }
     async createFiles(config) {
-        const images = this.createImagesPlan();
+        const images = this.createImagesPlan(config);
         const scripts = new scriptFiles_1.GithubScriptFiles();
         const workflows = await this.createWorkflows(config, images, scripts);
         return [
@@ -2336,13 +2336,13 @@ class GithubBackend {
             ...(0, shippedCatci_1.getCatciGeneratedFiles)(),
         ];
     }
-    createImagesPlan() {
-        return new jobImagesPlan_1.JobImagesPlan(this.type);
+    createImagesPlan(config) {
+        return new jobImagesPlan_1.JobImagesPlan(this.type, config.images);
     }
     /**
      * all workflows keyed by file name, mainly for testing purposes
      */
-    async createWorkflows(config, images = this.createImagesPlan(), scripts = new scriptFiles_1.GithubScriptFiles()) {
+    async createWorkflows(config, images = this.createImagesPlan(config), scripts = new scriptFiles_1.GithubScriptFiles()) {
         var _a, _b, _c, _d;
         const workflows = {};
         // per-pipeline-type variables (pipelines.github.runnerVariables);
@@ -2463,6 +2463,13 @@ class GithubBackend {
                     manualJobConditions[id] = `inputs.job == '${id}'`;
                     manualDispatchOptions.push(id);
                 }
+                // manual release mode: the workflow that runs a queued release
+                // once the main workflow completed green
+                const releaseOnGreen = (0, githubReleaseJobs_1.getGithubReleaseOnGreenWorkflow)(config, images, TRIGGER_WORKFLOWS.mainBranch.name, workflowEnv);
+                if (releaseOnGreen) {
+                    workflows[`${GENERATED_FILE_PREFIX}release-on-green.yml`] =
+                        releaseOnGreen;
+                }
             }
             if (Object.keys(jobs).length > 0) {
                 workflows[`${GENERATED_FILE_PREFIX}${workflowFileName(trigger)}`] = {
@@ -3007,16 +3014,21 @@ exports.getUploadProviderIds = getUploadProviderIds;
 "use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.getGithubReleaseCheckJobs = exports.getGithubReleaseJobs = void 0;
+exports.getGithubReleaseCheckJobs = exports.getGithubReleaseOnGreenWorkflow = exports.getGithubReleaseJobs = void 0;
 const createGithubJobs_1 = __nccwpck_require__(57877);
 const release_1 = __nccwpck_require__(38904);
-const createReleaseJob = (config, images, needs, extraEnv) => {
+const shippedCatci_1 = __nccwpck_require__(79024);
+const CATCI = `${shippedCatci_1.GENERATED_CATCI_FOLDER}/index.js`;
+const createReleaseJob = (config, images, options = {}) => {
+    var _a;
     const method = (0, release_1.getReleaseMethod)(config);
     const resolved = images.resolveRef({ catladderImage: method.image });
-    const imageNeeds = resolved.need && typeof resolved.need === "object"
+    const imageNeeds = !options.skipImageNeeds &&
+        resolved.need &&
+        typeof resolved.need === "object"
         ? [(0, createGithubJobs_1.githubGlobalJobId)(resolved.need.job)]
         : [];
-    const allNeeds = [...imageNeeds, ...(needs !== null && needs !== void 0 ? needs : [])];
+    const allNeeds = [...imageNeeds, ...((_a = options.needs) !== null && _a !== void 0 ? _a : [])];
     return {
         name: "create release",
         "runs-on": "ubuntu-latest",
@@ -3045,7 +3057,7 @@ const createReleaseJob = (config, images, needs, extraEnv) => {
         ...(allNeeds.length > 0 ? { needs: allNeeds } : {}),
         env: {
             GITHUB_TOKEN: "${{ github.token }}",
-            ...extraEnv,
+            ...options.extraEnv,
         },
         steps: [
             {
@@ -3055,8 +3067,21 @@ const createReleaseJob = (config, images, needs, extraEnv) => {
                 // tags since the last release) to determine the version
                 with: { "fetch-depth": 0 },
             },
+            ...(options.queueCheck
+                ? [
+                    {
+                        name: "check main workflow",
+                        id: "queue",
+                        run: `node ${CATCI} release github-queue-check`,
+                        shell: "bash",
+                    },
+                ]
+                : []),
             {
                 name: "create release",
+                ...(options.queueCheck
+                    ? { if: "steps.queue.outputs.queued != 'true'" }
+                    : {}),
                 run: method.script,
                 shell: "bash",
             },
@@ -3070,7 +3095,10 @@ const createReleaseJob = (config, images, needs, extraEnv) => {
  *   workflow after all other jobs; a force variant goes to the manual
  *   tasks workflow
  * - otherwise (manual, the default): the release job goes to the
- *   manual tasks workflow
+ *   manual tasks workflow. Its queue-check step releases right away on
+ *   a green main run and otherwise queues the release for the
+ *   release-on-green workflow (see getGithubReleaseOnGreenWorkflow) —
+ *   the counterpart of gitlab's queue button + executor pair.
  */
 const getGithubReleaseJobs = (config, mainWorkflowJobIds, images) => {
     var _a;
@@ -3078,28 +3106,89 @@ const getGithubReleaseJobs = (config, mainWorkflowJobIds, images) => {
     if (((_a = config.releases) === null || _a === void 0 ? void 0 : _a.when) === "auto") {
         return {
             main: {
-                "create-release": createReleaseJob(config, images, mainWorkflowJobIds),
+                "create-release": createReleaseJob(config, images, {
+                    needs: mainWorkflowJobIds,
+                }),
             },
             manual: {
-                "force-create-release": createReleaseJob(config, images, undefined, method.forceReleaseVariables),
+                "force-create-release": createReleaseJob(config, images, {
+                    extraEnv: method.forceReleaseVariables,
+                }),
             },
         };
     }
     return {
         main: {},
         manual: {
-            "create-release": createReleaseJob(config, images),
+            "create-release": createReleaseJob(config, images, { queueCheck: true }),
             // an explicit force option wherever the method distinguishes it
             // (e.g. changesets: release a patch bump without changesets)
             ...(method.forceReleaseVariables
                 ? {
-                    "force-create-release": createReleaseJob(config, images, undefined, method.forceReleaseVariables),
+                    "force-create-release": createReleaseJob(config, images, {
+                        extraEnv: method.forceReleaseVariables,
+                    }),
                 }
                 : {}),
         },
     };
 };
 exports.getGithubReleaseJobs = getGithubReleaseJobs;
+/**
+ * the release-on-green workflow (manual release mode only): runs on
+ * every completed main workflow run. A lightweight host job checks the
+ * queue marker (written by the create-release task while the main
+ * workflow was still running) — most runs have nothing queued and end
+ * after that single quick job. When the marker matches the completed
+ * run, the containerized release job creates the release.
+ *
+ * No image-build jobs here: the release image was ensured by the main
+ * workflow run that just completed (same commit, same content-hashed
+ * tag).
+ */
+const getGithubReleaseOnGreenWorkflow = (config, images, mainWorkflowName, workflowEnv) => {
+    var _a;
+    if (((_a = config.releases) === null || _a === void 0 ? void 0 : _a.when) === "auto") {
+        return null;
+    }
+    return {
+        name: "catladder release on green",
+        on: {
+            workflow_run: {
+                workflows: [mainWorkflowName],
+                types: ["completed"],
+            },
+        },
+        env: workflowEnv,
+        jobs: {
+            guard: {
+                name: "check queued release",
+                "runs-on": "ubuntu-latest",
+                // consuming the queue marker is a ref deletion
+                permissions: { contents: "write" },
+                env: { GITHUB_TOKEN: "${{ github.token }}" },
+                outputs: { release: "${{ steps.guard.outputs.release }}" },
+                steps: [
+                    { name: "Checkout", uses: "actions/checkout@v4" },
+                    {
+                        name: "check queued release",
+                        id: "guard",
+                        run: `node ${CATCI} release github-queued-guard "\${{ github.event.workflow_run.head_sha }}" "\${{ github.event.workflow_run.conclusion }}"`,
+                        shell: "bash",
+                    },
+                ],
+            },
+            "create-release": {
+                ...createReleaseJob(config, images, {
+                    needs: ["guard"],
+                    skipImageNeeds: true,
+                }),
+                if: "${{ needs.guard.outputs.release == 'true' }}",
+            },
+        },
+    };
+};
+exports.getGithubReleaseOnGreenWorkflow = getGithubReleaseOnGreenWorkflow;
 /**
  * the informational MR/PR check job of the release method (e.g. the
  * changeset check), added to the mr workflow. continue-on-error keeps
@@ -3294,6 +3383,7 @@ const config_1 = __nccwpck_require__(17860);
 const createAllJobs_1 = __nccwpck_require__(54114);
 const jobImagesPlan_1 = __nccwpck_require__(47864);
 const shippedCatci_1 = __nccwpck_require__(79024);
+const release_1 = __nccwpck_require__(38904);
 const index_1 = __nccwpck_require__(68906);
 const createGitlabJobs_1 = __nccwpck_require__(41509);
 const createGitlabPipeline_1 = __nccwpck_require__(94411);
@@ -3311,7 +3401,7 @@ class GitlabBackend {
         await (0, promises_1.rm)(this.generatedFolder, { force: true, recursive: true });
     }
     async createFiles(config) {
-        const images = this.createImagesPlan();
+        const images = this.createImagesPlan(config);
         const includes = await this.createIncludes(config, images);
         const mainFile = {
             path: ".gitlab-ci.yml",
@@ -3328,15 +3418,15 @@ class GitlabBackend {
             ...(0, shippedCatci_1.getCatciGeneratedFiles)(),
         ];
     }
-    createImagesPlan() {
-        return new jobImagesPlan_1.JobImagesPlan(this.type);
+    createImagesPlan(config) {
+        return new jobImagesPlan_1.JobImagesPlan(this.type, config.images);
     }
     /**
      * the complete pipeline as one object (all includes merged into one),
      * mainly for testing purposes
      */
     async createCompletePipeline(config) {
-        const includes = await this.createIncludes(config, this.createImagesPlan());
+        const includes = await this.createIncludes(config, this.createImagesPlan(config));
         return includes.reduce((acc, { content }) => {
             return {
                 ...acc,
@@ -3380,12 +3470,29 @@ class GitlabBackend {
     }
     async createPipeline(config, images) {
         const stages = (0, getPipelineStages_1.getPipelineStages)(config);
-        // release jobs first: they register their image on the plan, and the
-        // per-trigger job creation below emits the build jobs of all images
-        // registered so far
-        const releaseJobs = (0, gitlabReleaseJobs_1.getGitlabReleaseJobs)(config, images);
+        // register the release image first: the per-trigger job creation
+        // below emits the build jobs of all images registered so far. The
+        // release jobs themselves are created afterwards — they need the
+        // main-branch job list for the queued-release executor's needs.
+        images.resolveRef({ catladderImage: (0, release_1.getReleaseMethod)(config).image });
         // for all triggers create jobs and add base rules
-        const allJobsPerTrigger = await Promise.all(config_1.ALL_PIPELINE_TRIGGERS.map(async (trigger) => await (0, createGitlabJobs_1.createGitlabJobs)(await (0, createAllJobs_1.createAllJobs)({ config, trigger, pipelineType: this.type }), images, getGitlabRulesForTrigger(trigger)))).then((j) => j.flat());
+        const jobsPerTrigger = await Promise.all(config_1.ALL_PIPELINE_TRIGGERS.map(async (trigger) => ({
+            trigger,
+            jobs: await (0, createGitlabJobs_1.createGitlabJobs)(await (0, createAllJobs_1.createAllJobs)({ config, trigger, pipelineType: this.type }), images, getGitlabRulesForTrigger(trigger)),
+        })));
+        const allJobsPerTrigger = jobsPerTrigger.flatMap(({ jobs }) => jobs);
+        // the jobs the queued-release executor waits for: everything that
+        // runs automatically in a main-branch pipeline. Manual jobs (stop,
+        // rollback, gates) are excluded — gitlab skips a job whose needs
+        // include an unplayed manual job.
+        const mainBranchJobNames = [
+            ...new Set(jobsPerTrigger
+                .filter(({ trigger }) => trigger === "mainBranch")
+                .flatMap(({ jobs }) => jobs)
+                .filter(({ gitlabJob }) => !isManualGitlabJob(gitlabJob))
+                .map(({ name }) => name)),
+        ];
+        const releaseJobs = (0, gitlabReleaseJobs_1.getGitlabReleaseJobs)(config, images, mainBranchJobNames);
         const allWorkspaceJobs = allJobsPerTrigger
             .filter((j) => { var _a; return ((_a = j.context) === null || _a === void 0 ? void 0 : _a.type) === "workspace"; }) // sort by componentName in the same order as they appear in the config
             // this is purely for better readability in git diffs when you add new components
@@ -3451,6 +3558,14 @@ class GitlabBackend {
     }
 }
 exports.GitlabBackend = GitlabBackend;
+/**
+ * whether a job can end up waiting for a human in a main-branch
+ * pipeline (catladder expresses manual-ness only through rules)
+ */
+function isManualGitlabJob(job) {
+    var _a;
+    return ((_a = job.rules) !== null && _a !== void 0 ? _a : []).some((rule) => rule.when === "manual");
+}
 function getGitlabRulesForTrigger(trigger) {
     // mainBranch: on push to main branch except it's a release commit
     // mr: on merge request
@@ -3983,91 +4098,179 @@ exports.getPipelineStages = getPipelineStages;
 "use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.getGitlabReleaseJobs = void 0;
+exports.getGitlabReleaseJobs = exports.RELEASE_EXECUTOR_JOB_NAME = exports.RELEASE_BUTTON_JOB_NAME = void 0;
 const rules_1 = __nccwpck_require__(35086);
 const release_1 = __nccwpck_require__(38904);
 const EXPIRED_TOKEN_HELP = "echo '👉 If this job failed with access denied, the project access token might be invald - run `project-renew-token` in catladder CLI to fix.'";
+/**
+ * gitlab rejects jobs with more than 50 `needs:` entries (default
+ * limit). Pipelines beyond that fall back to the legacy manual release
+ * job, which is only playable once all prior stages finished.
+ */
+const GITLAB_MAX_NEEDS = 50;
+exports.RELEASE_BUTTON_JOB_NAME = "create release";
+exports.RELEASE_EXECUTOR_JOB_NAME = "🚀 release once pipeline succeeds";
 const baseReleaseRules = [
     rules_1.RULE_NEVER_ON_RELEASE_COMMIT,
     rules_1.RULE_NEVER_ON_AGENT_TRIGGER,
     rules_1.RULE_NEVER_ON_SCHEDULE,
 ];
-const getGitlabReleaseJobs = (config, images) => {
+// NOTE: with `rules:`, when: manual defaults to allow_failure: false,
+// which turns every unclicked pipeline into status "blocked" — the
+// manual release jobs therefore carry allow_failure: true so pipelines
+// end "passed" when nobody releases
+const manualReleaseRules = [
+    ...baseReleaseRules,
+    {
+        if: rules_1.RULE_CONDITION_MAIN_BRANCH,
+        when: "manual",
+    },
+    {
+        if: rules_1.RULE_CONDITION_HOTFIX_BRANCH,
+        when: "manual",
+    },
+];
+const getGitlabReleaseJobs = (config, images, 
+/**
+ * names of the jobs that run automatically in main-branch pipelines
+ * (manual jobs excluded: a needed-but-unplayed manual job would make
+ * gitlab skip the release executor)
+ */
+mainBranchJobNames) => {
     var _a;
     const method = (0, release_1.getReleaseMethod)(config);
     // NOTE: only the resolved image url is used, not the `need`: release
-    // jobs have no `needs` on purpose — their stage ordering already
-    // guarantees the image build job (setup stage) ran, and adding a
-    // `needs` would switch gitlab to DAG mode, so the release job would no
-    // longer wait for the build/deploy stages.
+    // jobs have no `needs` on the whole pipeline on purpose — where they
+    // must wait for it, the wait is expressed by enumerating the jobs
+    // explicitly (see the executor below).
     const releaseImage = images.resolveRef({
         catladderImage: method.image,
     }).image;
-    return {
-        ["create release"]: {
-            stage: "release",
-            image: releaseImage,
-            script: [method.script],
-            after_script: [EXPIRED_TOKEN_HELP],
-            rules: [
-                ...baseReleaseRules,
-                {
-                    if: rules_1.RULE_CONDITION_MAIN_BRANCH,
-                    when: ((_a = config.releases) === null || _a === void 0 ? void 0 : _a.when) === "auto" ? "on_success" : "manual",
-                },
-                {
-                    if: rules_1.RULE_CONDITION_HOTFIX_BRANCH,
-                    when: "manual",
-                },
-            ],
-        },
+    const releaseJobBase = {
+        stage: "release",
+        image: releaseImage,
+        script: [method.script],
+        after_script: [EXPIRED_TOKEN_HELP],
+    };
+    const forceReleaseJob = {
         ["⚠️ force create release"]: {
-            stage: "release",
-            image: releaseImage,
-            script: [method.script],
-            after_script: [EXPIRED_TOKEN_HELP],
+            ...releaseJobBase,
             needs: [],
+            allow_failure: true,
             // force semantics of the method's script (e.g. changesets:
             // release a patch bump even without pending changesets)
             ...(method.forceReleaseVariables
                 ? { variables: method.forceReleaseVariables }
                 : {}),
+            rules: manualReleaseRules,
+        },
+    };
+    // informational MR check of the release method (e.g. the changeset
+    // check): warns via allow_failure, the report lands in the MR
+    // widget as an exposed artifact
+    const checkJob = method.checkScript
+        ? {
+            ["🦋 changeset check"]: {
+                stage: "test",
+                image: releaseImage,
+                script: [method.checkScript],
+                allow_failure: true,
+                artifacts: {
+                    paths: ["changeset-report.md"],
+                    expose_as: "changeset report",
+                    // the report must survive the warning exit
+                    when: "always",
+                },
+                rules: [
+                    rules_1.RULE_NEVER_ON_AGENT_TRIGGER,
+                    rules_1.RULE_NEVER_ON_SCHEDULE,
+                    rules_1.RULE_IS_MERGE_REQUEST,
+                ],
+            },
+        }
+        : {};
+    if (((_a = config.releases) === null || _a === void 0 ? void 0 : _a.when) === "auto") {
+        return {
+            [exports.RELEASE_BUTTON_JOB_NAME]: {
+                ...releaseJobBase,
+                rules: [
+                    ...baseReleaseRules,
+                    {
+                        if: rules_1.RULE_CONDITION_MAIN_BRANCH,
+                        when: "on_success",
+                    },
+                    {
+                        if: rules_1.RULE_CONDITION_HOTFIX_BRANCH,
+                        when: "manual",
+                        // per-rule: only the unclicked hotfix button must not
+                        // block — a failed automatic release stays loud
+                        allow_failure: true,
+                    },
+                ],
+            },
+            ...forceReleaseJob,
+            ...checkJob,
+        };
+    }
+    const executorNeeds = [
+        { job: exports.RELEASE_BUTTON_JOB_NAME },
+        // optional: hotfix pipelines (and rules-filtered jobs) contain a
+        // different job subset
+        ...mainBranchJobNames.map((name) => ({ job: name, optional: true })),
+    ];
+    if (executorNeeds.length > GITLAB_MAX_NEEDS) {
+        console.warn(`⚠️ the main-branch pipeline has more than ${GITLAB_MAX_NEEDS} jobs — ` +
+            `the "${exports.RELEASE_BUTTON_JOB_NAME}" job falls back to being playable ` +
+            `only once the pipeline finished (gitlab caps needs: at ${GITLAB_MAX_NEEDS})`);
+        return {
+            [exports.RELEASE_BUTTON_JOB_NAME]: {
+                ...releaseJobBase,
+                allow_failure: true,
+                rules: manualReleaseRules,
+            },
+            ...forceReleaseJob,
+            ...checkJob,
+        };
+    }
+    return {
+        // the queue button: playable from the first second of the pipeline.
+        // It only records the intent to release — the executor below does
+        // the actual work once every other job succeeded. Clicking after the
+        // pipeline finished works the same (the executor starts right away).
+        [exports.RELEASE_BUTTON_JOB_NAME]: {
+            stage: "release",
+            image: releaseImage,
+            script: [
+                `echo "release queued — '${exports.RELEASE_EXECUTOR_JOB_NAME}' runs it as soon as every other job in this pipeline succeeded"`,
+            ],
+            needs: [],
+            // allow_failure keeps the unclicked button from blocking the
+            // pipeline AND makes the executor's needs treat it as optional
+            // (skipped executor instead of a forever-waiting pipeline)
+            allow_failure: true,
+            rules: manualReleaseRules,
+        },
+        // the executor: never played manually. Skipped when the button was
+        // not clicked; otherwise starts automatically as soon as the button
+        // and every other (non-manual) job of the pipeline succeeded, and
+        // is skipped when any of them failed.
+        [exports.RELEASE_EXECUTOR_JOB_NAME]: {
+            ...releaseJobBase,
+            needs: executorNeeds,
             rules: [
                 ...baseReleaseRules,
                 {
                     if: rules_1.RULE_CONDITION_MAIN_BRANCH,
-                    when: "manual",
+                    when: "on_success",
                 },
                 {
                     if: rules_1.RULE_CONDITION_HOTFIX_BRANCH,
-                    when: "manual",
+                    when: "on_success",
                 },
             ],
         },
-        // informational MR check of the release method (e.g. the changeset
-        // check): warns via allow_failure, the report lands in the MR
-        // widget as an exposed artifact
-        ...(method.checkScript
-            ? {
-                ["🦋 changeset check"]: {
-                    stage: "test",
-                    image: releaseImage,
-                    script: [method.checkScript],
-                    allow_failure: true,
-                    artifacts: {
-                        paths: ["changeset-report.md"],
-                        expose_as: "changeset report",
-                        // the report must survive the warning exit
-                        when: "always",
-                    },
-                    rules: [
-                        rules_1.RULE_NEVER_ON_AGENT_TRIGGER,
-                        rules_1.RULE_NEVER_ON_SCHEDULE,
-                        rules_1.RULE_IS_MERGE_REQUEST,
-                    ],
-                },
-            }
-            : {}),
+        ...forceReleaseJob,
+        ...checkJob,
     };
 };
 exports.getGitlabReleaseJobs = getGitlabReleaseJobs;
@@ -6981,7 +7184,7 @@ exports.makeSecretEnvVarMapping = makeSecretEnvVarMapping;
 "use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.computeCustomImageHash = void 0;
+exports.computeInlineImageHash = exports.computeCustomImageHash = void 0;
 const crypto_1 = __nccwpck_require__(76982);
 const fs_1 = __nccwpck_require__(79896);
 const path_1 = __nccwpck_require__(16928);
@@ -7002,6 +7205,29 @@ function listFilesRecursive(dir) {
     })
         .sort();
 }
+/**
+ * the parts every image definition hashes on top of its content:
+ * files outside the definition, and the build args
+ */
+function hashExtras(hash, config) {
+    const watchedPaths = [];
+    // Hash extra paths (for files outside the dir)
+    if (config.hashExtraPaths) {
+        // Extra paths are literal file paths (not globs) for simplicity
+        const extraFiles = [...config.hashExtraPaths].sort();
+        for (const file of extraFiles) {
+            hash.update(file);
+            hash.update((0, fs_1.readFileSync)(file));
+        }
+        watchedPaths.push(...config.hashExtraPaths);
+    }
+    // Hash build args (sorted keys for determinism)
+    if (config.buildArgs) {
+        const sorted = Object.entries(config.buildArgs).sort(([a], [b]) => a.localeCompare(b));
+        hash.update(JSON.stringify(sorted));
+    }
+    return watchedPaths;
+}
 function computeCustomImageHash(config) {
     var _a;
     const hash = (0, crypto_1.createHash)("sha256");
@@ -7022,27 +7248,29 @@ function computeCustomImageHash(config) {
         }
         watchedPaths.push(`${extraDir}/**/*`);
     }
-    // Hash extra paths (for files outside the dir)
-    if (config.hashExtraPaths) {
-        // Extra paths are literal file paths (not globs) for simplicity
-        const extraFiles = [...config.hashExtraPaths].sort();
-        for (const file of extraFiles) {
-            hash.update(file);
-            hash.update((0, fs_1.readFileSync)(file));
-        }
-        watchedPaths.push(...config.hashExtraPaths);
-    }
-    // Hash build args (sorted keys for determinism)
-    if (config.buildArgs) {
-        const sorted = Object.entries(config.buildArgs).sort(([a], [b]) => a.localeCompare(b));
-        hash.update(JSON.stringify(sorted));
-    }
+    watchedPaths.push(...hashExtras(hash, config));
     return {
         hash: hash.digest("hex").slice(0, 12),
         watchedPaths,
     };
 }
 exports.computeCustomImageHash = computeCustomImageHash;
+/**
+ * the hash of an image defined by an inline Dockerfile: its content
+ * stands in for the definition dir. The build context is deliberately
+ * NOT hashed (it may be the whole repository) — `hashExtraPaths` is how
+ * context files opt into the hash.
+ */
+function computeInlineImageHash(config) {
+    const hash = (0, crypto_1.createHash)("sha256");
+    hash.update(config.dockerfileContent);
+    const watchedPaths = hashExtras(hash, config);
+    return {
+        hash: hash.digest("hex").slice(0, 12),
+        watchedPaths,
+    };
+}
+exports.computeInlineImageHash = computeInlineImageHash;
 //# sourceMappingURL=hash.js.map
 
 /***/ }),
@@ -7053,7 +7281,7 @@ exports.computeCustomImageHash = computeCustomImageHash;
 "use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.JobImagesPlan = exports.GENERATED_IMAGES_FOLDER = void 0;
+exports.JobImagesPlan = exports.PROJECT_IMAGES_FOLDER = exports.GENERATED_IMAGES_FOLDER = void 0;
 const fs_1 = __nccwpck_require__(79896);
 const path_1 = __nccwpck_require__(16928);
 const ciVariables_1 = __nccwpck_require__(72700);
@@ -7061,6 +7289,7 @@ const docker_1 = __nccwpck_require__(83777);
 const runner_1 = __nccwpck_require__(71065);
 const gitlab_1 = __nccwpck_require__(37393);
 const hash_1 = __nccwpck_require__(34092);
+const projectImages_1 = __nccwpck_require__(55537);
 const shippedImages_1 = __nccwpck_require__(28687);
 exports.GENERATED_IMAGES_FOLDER = ".catladder-generated/images";
 /**
@@ -7068,7 +7297,44 @@ exports.GENERATED_IMAGES_FOLDER = ".catladder-generated/images";
  * catladder image, so building images never depends on one (bootstrap)
  */
 const BUILDER_IMAGE = "docker.io/docker:29.5.1";
-const ensureJobName = (name) => `🐳 job image ${name}`;
+/**
+ * every planned image is consumed the same way: its url, plus an
+ * optional dependency on its build job
+ */
+const toResolvedJobImage = ({ imageRef, jobName, }) => ({
+    image: imageRef,
+    fromRepoRegistry: true,
+    need: {
+        job: jobName,
+        artifacts: false,
+        optional: true,
+        global: true,
+    },
+});
+/**
+ * materializes an image definition directory into the generated files
+ * (used for the definitions catladder ships)
+ */
+const materializeDir = (sourceDir, targetDir) => listFilesRecursive(sourceDir).map((file) => ({
+    path: (0, path_1.join)(targetDir, file),
+    content: (0, fs_1.readFileSync)((0, path_1.join)(sourceDir, file), "utf-8"),
+}));
+// built-in (catladder-shipped) images carry the catladder marker in
+// their job name; project-declared images get the short plain name
+const ensureJobName = (name) => `🐳 catladder image ${name}`;
+const projectEnsureJobName = (name) => `🐳 image ${name}`;
+/**
+ * the config file whose content feeds the project image hashes
+ * (`buildArgs`, `hashExtraPaths`): the gitlab change detection has to
+ * watch it, because a config-only change alters the image tag without
+ * touching the image dir
+ */
+const CONFIG_FILE = "catladder.ts";
+/**
+ * where inline project Dockerfiles are materialized — a subfolder, so a
+ * project image can carry the same name as a shipped one
+ */
+exports.PROJECT_IMAGES_FOLDER = `${exports.GENERATED_IMAGES_FOLDER}/project`;
 /**
  * plans the catladder job images of one backend run: resolves image
  * references, collects the image build jobs, and the image definitions
@@ -7079,33 +7345,30 @@ const ensureJobName = (name) => `🐳 job image ${name}`;
  * Reference-driven: only images actually used by a job are built.
  */
 class JobImagesPlan {
-    constructor(pipelineType) {
+    constructor(pipelineType, projectImages = {}) {
         this.pipelineType = pipelineType;
+        this.projectImages = projectImages;
         this.used = new Map();
+        this.usedProject = new Map();
     }
     /**
      * resolves a job image (marker or concrete) to a concrete image url
      * plus the build job dependency
      */
     resolve(image) {
-        if (!(0, runner_1.isCatladderImageRef)(image)) {
-            return { image };
+        if ((0, runner_1.isCatladderImageRef)(image)) {
+            return this.resolveRef(image);
         }
-        return this.resolveRef(image);
+        if ((0, projectImages_1.isProjectImageRef)(image)) {
+            return this.resolveProjectRef(image);
+        }
+        return { image };
     }
     resolveRef(ref) {
-        const name = ref.catladderImage;
-        const { hash } = this.use(name);
-        return {
-            image: `${this.registryImageRef()}/catladder/${name}:${hash}`,
-            fromRepoRegistry: true,
-            need: {
-                job: ensureJobName(name),
-                artifacts: false,
-                optional: true,
-                global: true,
-            },
-        };
+        return toResolvedJobImage(this.use(ref.catladderImage));
+    }
+    resolveProjectRef(ref) {
+        return toResolvedJobImage(this.useProject(ref.image));
     }
     /**
      * the registry image prefix. On github, container images can't use
@@ -7116,6 +7379,85 @@ class JobImagesPlan {
             ? "ghcr.io/${{ github.repository }}"
             : `${(0, ciVariables_1.getCiVariable)({ pipelineType: this.pipelineType }, "registryImage")}`;
     }
+    useProject(name) {
+        const existing = this.usedProject.get(name);
+        if (existing) {
+            return existing;
+        }
+        const imageConfig = this.projectImages[name];
+        if (!imageConfig) {
+            const declared = Object.keys(this.projectImages);
+            throw new Error(`unknown job image "${name}" — ${declared.length > 0
+                ? `images declared in config.images: ${declared.join(", ")}`
+                : "no images are declared in config.images"}`);
+        }
+        const source = this.planProjectSource(name, imageConfig);
+        const planned = {
+            ...source,
+            jobName: projectEnsureJobName(name),
+            buildArgs: imageConfig.buildArgs,
+            // `job-images/` keeps the project's job images apart from its
+            // deployable component images (registry root) and build caches
+            imageRef: `${this.registryImageRef()}/job-images/${name}:${source.hash}`,
+        };
+        this.usedProject.set(name, planned);
+        return planned;
+    }
+    /**
+     * the source-dependent half of a project image: an inline Dockerfile
+     * is materialized into the generated files and hashed by its content,
+     * a directory is hashed and watched in place
+     */
+    planProjectSource(name, imageConfig) {
+        var _a, _b;
+        if (imageConfig.dockerfile !== undefined) {
+            const content = toDockerfileContent(imageConfig.dockerfile);
+            const dockerfilePath = `${exports.PROJECT_IMAGES_FOLDER}/${name}/Dockerfile`;
+            const { hash, watchedPaths } = (0, hash_1.computeInlineImageHash)({
+                dockerfileContent: content,
+                hashExtraPaths: imageConfig.hashExtraPaths,
+                buildArgs: imageConfig.buildArgs,
+            });
+            return {
+                hash,
+                dockerfilePath,
+                // an inline definition carries no directory of its own — the
+                // repository root is the sensible default context
+                contextDir: (_a = imageConfig.context) !== null && _a !== void 0 ? _a : ".",
+                watchedPaths: [
+                    `${exports.PROJECT_IMAGES_FOLDER}/${name}/**/*`,
+                    ...watchedPaths,
+                    CONFIG_FILE,
+                ],
+                files: [{ path: dockerfilePath, content }],
+            };
+        }
+        const dir = imageConfig.dir;
+        // fail at generation time with the offending image named: an
+        // unreadable dir would otherwise surface as a bare fs ENOENT, and a
+        // missing Dockerfile only as a docker build failure in CI
+        if (!(0, fs_1.existsSync)(dir)) {
+            throw new Error(`job image "${name}": the directory "${dir}" does not exist (config.images.${name}.dir, relative to the repository root)`);
+        }
+        if (!(0, fs_1.existsSync)((0, path_1.join)(dir, "Dockerfile"))) {
+            throw new Error(`job image "${name}": no Dockerfile in "${dir}" (config.images.${name}.dir)`);
+        }
+        const { hash, watchedPaths } = (0, hash_1.computeCustomImageHash)({
+            dir,
+            hashExtraPaths: imageConfig.hashExtraPaths,
+            buildArgs: imageConfig.buildArgs,
+        });
+        return {
+            hash,
+            dockerfilePath: `${dir}/Dockerfile`,
+            contextDir: (_b = imageConfig.context) !== null && _b !== void 0 ? _b : dir,
+            // the dir is committed in the project — watched in place, nothing
+            // is materialized. The config file is watched too: buildArgs /
+            // hashExtraPaths changes alter the tag without touching the dir
+            watchedPaths: [...watchedPaths, CONFIG_FILE],
+            files: [],
+        };
+    }
     use(name) {
         var _a;
         const existing = this.used.get(name);
@@ -7130,27 +7472,43 @@ class JobImagesPlan {
             dir: (0, shippedImages_1.getShippedImageDir)(name),
             extraDirs: dependencies.map((dependency) => (0, shippedImages_1.getShippedImageDir)(dependency)),
         });
-        const entry = { hash };
-        this.used.set(name, entry);
-        return entry;
+        const targetDir = `${exports.GENERATED_IMAGES_FOLDER}/${name}`;
+        const planned = {
+            hash,
+            jobName: ensureJobName(name),
+            imageRef: `${this.registryImageRef()}/catladder/${name}:${hash}`,
+            dockerfilePath: `${targetDir}/Dockerfile`,
+            // the jobs family INCLUDEs sibling images, so it builds from the
+            // images root; the others from their own dir
+            contextDir: shippedImages_1.RUNNER_IMAGE_BUILD_CONTEXT[name] === "root"
+                ? exports.GENERATED_IMAGES_FOLDER
+                : targetDir,
+            watchedPaths: [name, ...dependencies].map((dir) => `${exports.GENERATED_IMAGES_FOLDER}/${dir}/**/*`),
+            // pipelines build from committed, reviewable files (and gitlab's
+            // rules:changes can watch them)
+            files: materializeDir((0, shippedImages_1.getShippedImageDir)(name), targetDir),
+        };
+        this.used.set(name, planned);
+        return planned;
     }
     /**
      * the image build jobs for all used images
      */
     getEnsureJobs() {
-        return [...this.used.entries()].map(([name, { hash }]) => this.createEnsureJob(name, hash));
+        return [...this.used.values(), ...this.usedProject.values()].map((planned) => this.createImageBuildJob(planned));
     }
-    createEnsureJob(name, hash) {
-        var _a;
+    createImageBuildJob({ jobName, imageRef, watchedPaths, dockerfilePath, contextDir, buildArgs, }) {
+        const buildArgFlags = Object.entries(buildArgs !== null && buildArgs !== void 0 ? buildArgs : {})
+            .map(([key, value]) => ` --build-arg '${key}=${value}'`)
+            .join("");
+        const buildCommand = `DOCKER_BUILDKIT=1 docker build -t ${imageRef}${buildArgFlags} -f ${dockerfilePath} ${contextDir}`;
         const ctx = { pipelineType: this.pipelineType };
         const registryUser = (0, ciVariables_1.getCiVariable)(ctx, "registryUser");
         const jobToken = (0, ciVariables_1.getCiVariable)(ctx, "jobToken");
         const registry = (0, ciVariables_1.getCiVariable)(ctx, "registry");
-        const imageRef = `${this.registryImageRef()}/catladder/${name}:${hash}`;
-        const watchedDirs = [name, ...((_a = shippedImages_1.RUNNER_IMAGE_DEPENDENCIES[name]) !== null && _a !== void 0 ? _a : [])];
         const { services, runnerVariables } = (0, docker_1.getDockerJobBaseProps)();
         return {
-            name: ensureJobName(name),
+            name: jobName,
             stage: "setup",
             image: BUILDER_IMAGE,
             services,
@@ -7160,7 +7518,9 @@ class JobImagesPlan {
             // no equivalent and always runs (the existence check is fast)
             rules: [
                 {
-                    changes: watchedDirs.map((dir) => `${exports.GENERATED_IMAGES_FOLDER}/${dir}/**/*`),
+                    // a fresh array per job: the yaml serializer anchors repeated
+                    // objects, and a shared reference would reshuffle anchors
+                    changes: [...watchedPaths],
                 },
             ],
             variables: {},
@@ -7174,31 +7534,33 @@ class JobImagesPlan {
                     `  exit 0`,
                     `fi`,
                 ]),
-                ...(0, gitlab_1.collapseableSection)("docker-build", "Building image")([
-                    `DOCKER_BUILDKIT=1 docker build -t ${imageRef} -f ${exports.GENERATED_IMAGES_FOLDER}/${name}/Dockerfile ${shippedImages_1.RUNNER_IMAGE_BUILD_CONTEXT[name] === "root"
-                        ? exports.GENERATED_IMAGES_FOLDER
-                        : `${exports.GENERATED_IMAGES_FOLDER}/${name}`}`,
-                ]),
+                ...(0, gitlab_1.collapseableSection)("docker-build", "Building image")([buildCommand]),
                 ...(0, gitlab_1.collapseableSection)("docker-push", "Pushing image")([`docker push ${imageRef}`]),
             ],
         };
     }
     /**
-     * the image definitions of all used images, materialized into the
-     * generated files (so pipelines build from committed, reviewable
-     * files and gitlab's rules:changes can watch them)
+     * the image definitions to materialize into the generated files (so
+     * pipelines build from committed, reviewable files and gitlab's
+     * rules:changes can watch them): the definitions catladder ships and
+     * the project's inline Dockerfiles. A project image directory is
+     * already committed and contributes nothing.
      */
     getGeneratedFiles() {
-        return [...this.used.keys()].flatMap((name) => {
-            const dir = (0, shippedImages_1.getShippedImageDir)(name);
-            return listFilesRecursive(dir).map((file) => ({
-                path: (0, path_1.join)(exports.GENERATED_IMAGES_FOLDER, name, file),
-                content: (0, fs_1.readFileSync)((0, path_1.join)(dir, file), "utf-8"),
-            }));
-        });
+        return [...this.used.values(), ...this.usedProject.values()].flatMap(({ files }) => files);
     }
 }
 exports.JobImagesPlan = JobImagesPlan;
+/**
+ * an inline Dockerfile is written as given — as one string, or as lines
+ * joined with newlines (always newline-terminated)
+ */
+const toDockerfileContent = (dockerfile) => {
+    const content = Array.isArray(dockerfile)
+        ? dockerfile.join("\n")
+        : dockerfile;
+    return content.endsWith("\n") ? content : `${content}\n`;
+};
 const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
 const listFilesRecursive = (dir) => (0, fs_1.readdirSync)(dir, { recursive: true, encoding: "utf-8" })
     .filter((entry) => {
@@ -7212,6 +7574,22 @@ const listFilesRecursive = (dir) => (0, fs_1.readdirSync)(dir, { recursive: true
 
 /***/ }),
 
+/***/ 55537:
+/***/ ((__unused_webpack_module, exports) => {
+
+"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
+
+/***/ }),
+
 /***/ 28687:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -9925,6 +10303,8 @@ __exportStar(__nccwpck_require__(68906), exports);
 __exportStar(__nccwpck_require__(23040), exports);
 __exportStar(__nccwpck_require__(35086), exports);
 __exportStar(__nccwpck_require__(71065), exports);
+__exportStar(__nccwpck_require__(55537), exports);
+__exportStar(__nccwpck_require__(47864), exports);
 __exportStar(__nccwpck_require__(80769), exports);
 __exportStar(__nccwpck_require__(7732), exports);
 __exportStar(__nccwpck_require__(66526), exports);