@catladder/cli 5.5.0 → 5.6.0

package/dist/bundles/cli/index.js

@@ -9679,6 +9679,97 @@ exports.makeAggregateCheckJob = makeAggregateCheckJob;
 
 /***/ }),
 
+/***/ 75125:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.createArtifactDownloadSteps = exports.createArtifactUploadSteps = exports.artifactArchiveFile = void 0;
+/**
+ * Artifacts are handed between github jobs as ONE tar archive instead
+ * of letting upload-artifact walk the paths itself.
+ *
+ * upload-artifact does not preserve symlinks (it uploads the target's
+ * content) nor file modes, and it strips the paths' common ancestor.
+ * Gitlab artifacts keep all of that, and builds rely on it: next.js
+ * with turbopack writes `.next/node_modules/<pkg>-<hash>` as relative
+ * symlinks into the pnpm virtual store. Copied as plain directories,
+ * node resolves the package's own dependencies from the wrong place
+ * and the app crashes with ERR_MODULE_NOT_FOUND at runtime. tar keeps
+ * symlinks, modes and the paths relative to the repo root (github's
+ * own docs recommend it for exactly this).
+ *
+ * The archive is not hidden (upload-artifact skips hidden files) and
+ * lives in the workspace, the one path run steps and actions agree on
+ * inside job containers too.
+ */
+const artifactArchiveFile = (jobId) => `catladder-artifacts-${jobId}.tar`;
+exports.artifactArchiveFile = artifactArchiveFile;
+const createArtifactUploadSteps = (jobId, paths, condition) => {
+    const archive = (0, exports.artifactArchiveFile)(jobId);
+    const ifCondition = condition ? { if: condition } : {};
+    return [
+        {
+            name: "Archive artifacts",
+            ...ifCondition,
+            run: [
+                "shopt -s nullglob globstar",
+                "paths=()",
+                // unquoted on purpose: artifact paths may be globs. Non-matching
+                // globs vanish (nullglob), missing literal paths are skipped —
+                // gitlab only warns about both, so do we
+                `for path in ${paths.join(" ")}; do`,
+                '  if [ -e "$path" ] || [ -L "$path" ]; then paths+=("$path"); else echo "::warning::artifact path not found: $path"; fi',
+                "done",
+                "if [ ${#paths[@]} -eq 0 ]; then",
+                // an empty archive keeps downstream downloads from failing.
+                // Written by hand: busybox tar (alpine job images) refuses to
+                // create one, and zero blocks are what an empty tar is
+                `  head -c 10240 /dev/zero > ${archive}`,
+                "else",
+                `  tar -cf ${archive} -- "\${paths[@]}"`,
+                "fi",
+            ].join("\n"),
+            shell: "bash",
+        },
+        {
+            name: "Upload artifacts",
+            ...ifCondition,
+            uses: "actions/upload-artifact@v4",
+            with: {
+                name: jobId,
+                path: archive,
+                "if-no-files-found": "error",
+            },
+        },
+    ];
+};
+exports.createArtifactUploadSteps = createArtifactUploadSteps;
+const createArtifactDownloadSteps = (providerIds) => providerIds.length === 0
+    ? []
+    : [
+        ...providerIds.map((id) => ({
+            name: `Download artifacts from ${id}`,
+            uses: "actions/download-artifact@v4",
+            with: { name: id },
+        })),
+        {
+            name: "Extract artifacts",
+            run: providerIds
+                .flatMap((id) => [
+                `tar -xf ${(0, exports.artifactArchiveFile)(id)}`,
+                `rm ${(0, exports.artifactArchiveFile)(id)}`,
+            ])
+                .join("\n"),
+            shell: "bash",
+        },
+    ];
+exports.createArtifactDownloadSteps = createArtifactDownloadSteps;
+//# sourceMappingURL=artifactArchive.js.map
+
+/***/ }),
+
 /***/ 17300:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -9748,6 +9839,7 @@ const utils_1 = __nccwpck_require__(49401);
 const gitlab_1 = __nccwpck_require__(86962);
 const scriptFunctions_1 = __nccwpck_require__(85873);
 const ciVariables_1 = __nccwpck_require__(17300);
+const artifactArchive_1 = __nccwpck_require__(75125);
 /**
  * runner variables that only make sense on gitlab runners and must not
  * leak into github jobs (docker-in-docker daemon config, kubernetes
@@ -9958,7 +10050,7 @@ const getReferencedSecretsEnv = (script, kinds) => Object.fromEntries([...script
     .filter((name) => !ciVariables_1.GITHUB_INJECTED_WORKFLOW_ENV_NAMES.has(name))
     .map((name) => [name, vaultValueExpression(name, kinds)]));
 const makeGithubJob = (context, job, allJobs, uploadProviderIds, images, scripts, secretKinds = new Map()) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const id = (0, exports.githubJobId)(context, job.name);
     const isComponent = context.type === "component";
     const createsJobEnv = !!job.environment &&
@@ -10103,13 +10195,7 @@ const makeGithubJob = (context, job, allJobs, uploadProviderIds, images, scripts
                 ? []
                 : [{ name: "Checkout", uses: "actions/checkout@v4" }]),
             ...createCacheSteps(context, job),
-            ...needs
-                .filter((n) => n.artifacts)
-                .map((n) => ({
-                name: `Download artifacts from ${n.id}`,
-                uses: "actions/download-artifact@v4",
-                with: { name: n.id },
-            })),
+            ...(0, artifactArchive_1.createArtifactDownloadSteps)(needs.filter((n) => n.artifacts).map((n) => n.id)),
             {
                 name: job.name,
                 id: "main",
@@ -10130,27 +10216,15 @@ const makeGithubJob = (context, job, allJobs, uploadProviderIds, images, scripts
                     },
                 ]
                 : []),
-            ...(pagesPublishDir
-                ? []
-                : uploadProviderIds.has(id) || artifactPaths.length > 0
-                    ? artifactPaths.length > 0
-                        ? [
-                            {
-                                name: "Upload artifacts",
-                                uses: "actions/upload-artifact@v4",
-                                with: {
-                                    name: id,
-                                    path: artifactPaths.join("\n"),
-                                    "if-no-files-found": "warn",
-                                    // gitlab artifacts include everything; upload-artifact
-                                    // silently drops hidden files by default — which is
-                                    // exactly where next.js builds live (.next)
-                                    "include-hidden-files": true,
-                                },
-                            },
-                        ]
-                        : []
-                    : []),
+            ...(!pagesPublishDir && artifactPaths.length > 0
+                ? (0, artifactArchive_1.createArtifactUploadSteps)(id, artifactPaths, 
+                // gitlab's `artifacts.when`: steps only run on success by default
+                ((_k = job.artifacts) === null || _k === void 0 ? void 0 : _k.when) === "always"
+                    ? "always()"
+                    : ((_l = job.artifacts) === null || _l === void 0 ? void 0 : _l.when) === "on_failure"
+                        ? "failure()"
+                        : undefined)
+                : []),
         ],
     };
     return [id, githubJob];
@@ -10843,7 +10917,6 @@ class GitlabBackend {
         return [mainInclude, ...componentIncludes];
     }
     async createPipeline(config, images) {
-        const stages = (0, getPipelineStages_1.getPipelineStages)(config);
         // 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
@@ -10862,6 +10935,9 @@ class GitlabBackend {
             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);
+        const stages = (0, getPipelineStages_1.getPipelineStages)(config, new Set(allJobsPerTrigger
+            .map(({ gitlabJob }) => gitlabJob.stage)
+            .filter((stage) => typeof stage === "string")));
         // 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
@@ -11516,14 +11592,23 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getPipelineStages = void 0;
 const config_1 = __nccwpck_require__(11646);
 const jobs_1 = __nccwpck_require__(98521);
+/**
+ * stages that only appear in the pipeline when a job uses them, so that
+ * projects not using the feature keep their generated files unchanged
+ */
+const OPTIONAL_STAGES = ["post-build"];
 /**
  * while technically not required, we group different envs in its own stage
  * each job from `createJobs` that is defined as `envMode: "stagePerEnv"` will have `deploy dev`, etc. instead of just `deploy`
  * this is just so that it looks nicer in gitlab and makes running mutliple manual tasks more easy to use
+ *
+ * `usedStages` are the stages of all generated jobs; optional stages are
+ * dropped when none of them is used.
  */
-function getPipelineStages(config) {
+function getPipelineStages(config, usedStages = new Set()) {
     const allEnvs = (0, config_1.getAllEnvsInAllComponents)(config).filter((e) => e !== "local");
-    const stages = jobs_1.BASE_STAGES.reduce((acc, baseStage) => [
+    const isUsed = (baseStage) => [...usedStages].some((stage) => stage === baseStage || stage.startsWith(`${baseStage} `));
+    const stages = jobs_1.BASE_STAGES.filter((baseStage) => !OPTIONAL_STAGES.includes(baseStage) || isUsed(baseStage)).reduce((acc, baseStage) => [
         ...acc,
         baseStage,
         ...allEnvs.map((e) => `${baseStage} ${e}`),
@@ -15607,14 +15692,20 @@ class DeployJob extends jobs_1.CatladderJob {
                     : []),
             ];
         // we don't want to deploy when there is a broken test
-        const qualityGateRequirement = {
-            capability: "qualityGate",
-            artifacts: false,
-            // use test from workspace build
-            from: (0, context_1.componentContextHasWorkspaceBuild)(context)
-                ? { workspace: context.build.workspaceName }
-                : undefined,
-        };
+        const qualityGateRequirements = [
+            // the component's own gates (e.g. post-build tests, custom test jobs)
+            { capability: "qualityGate", artifacts: false },
+            // ...and the gates of the workspace build it is built in
+            ...((0, context_1.componentContextHasWorkspaceBuild)(context)
+                ? [
+                    {
+                        capability: "qualityGate",
+                        artifacts: false,
+                        from: { workspace: context.build.workspaceName },
+                    },
+                ]
+                : []),
+        ];
         super({
             name: exports.DEPLOY_JOB_NAME,
             script: jobDefinition.script,
@@ -15631,7 +15722,7 @@ class DeployJob extends jobs_1.CatladderJob {
                 ...waitForRequirements,
                 // if the build is disabled, we don't need to wait for it
                 ...(context.build.type !== "disabled"
-                    ? [...buildRequirements, qualityGateRequirement]
+                    ? [...buildRequirements, ...qualityGateRequirements]
                     : []),
             ],
             gate: whenDeploy,
@@ -18407,6 +18498,7 @@ __exportStar(__nccwpck_require__(15707), exports);
 __exportStar(__nccwpck_require__(45492), exports);
 __exportStar(__nccwpck_require__(3659), exports);
 __exportStar(__nccwpck_require__(50713), exports);
+__exportStar(__nccwpck_require__(28458), exports);
 __exportStar(__nccwpck_require__(26041), exports);
 __exportStar(__nccwpck_require__(47663), exports);
 __exportStar(__nccwpck_require__(91804), exports);
@@ -19004,6 +19096,7 @@ exports.createJobsForComponentContext = void 0;
 const build_1 = __nccwpck_require__(45492);
 const deploy_1 = __nccwpck_require__(3659);
 const jobs_1 = __nccwpck_require__(98521);
+const createPostBuildTestJobs_1 = __nccwpck_require__(61844);
 const createVerifyJobs_1 = __nccwpck_require__(66900);
 const injectDefaultVarsInCustomJobs = (context, jobs) => jobs.map(({ variables, ...job }) => {
     var _a;
@@ -19023,17 +19116,26 @@ const getCustomJobs = (context) => {
     return injectDefaultVarsInCustomJobs(context, rawJobs);
 };
 const createJobsForComponentContext = async (context) => {
-    const [buildJobs, deployJobs, verifyJobs] = await Promise.all([
+    const [buildJobs, postBuildTestJobs, deployJobs, verifyJobs] = await Promise.all([
         context.build.type !== "disabled"
             ? build_1.BUILD_TYPES[context.build.buildType].jobs(context)
             : [],
+        (0, createPostBuildTestJobs_1.createPostBuildTestJobs)(context),
         context.componentConfig.deploy !== false
             ? deploy_1.DEPLOY_TYPES[context.componentConfig.deploy.type].jobs(context)
             : [],
         (0, createVerifyJobs_1.createVerifyJobs)(context),
     ]);
     const customJobs = getCustomJobs(context);
-    return [...buildJobs, ...deployJobs, ...verifyJobs, ...customJobs];
+    const otherJobs = [...buildJobs, ...deployJobs, ...verifyJobs, ...customJobs];
+    (0, createPostBuildTestJobs_1.assertUniquePostBuildTestNames)(context, postBuildTestJobs, otherJobs);
+    return [
+        ...buildJobs,
+        ...postBuildTestJobs,
+        ...deployJobs,
+        ...verifyJobs,
+        ...customJobs,
+    ];
 };
 exports.createJobsForComponentContext = createJobsForComponentContext;
 //# sourceMappingURL=createJobsForComponent.js.map
@@ -19048,9 +19150,14 @@ exports.createJobsForComponentContext = createJobsForComponentContext;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.createJobsForWorkspace = void 0;
 const build_1 = __nccwpck_require__(45492);
+const createPostBuildTestJobs_1 = __nccwpck_require__(61844);
 const createJobsForWorkspace = async (context) => {
-    const buildJobs = await build_1.WORKSPACE_BUILD_TYPES[context.build.buildType].jobs(context);
-    return buildJobs;
+    const [buildJobs, postBuildTestJobs] = await Promise.all([
+        build_1.WORKSPACE_BUILD_TYPES[context.build.buildType].jobs(context),
+        (0, createPostBuildTestJobs_1.createPostBuildTestJobs)(context),
+    ]);
+    (0, createPostBuildTestJobs_1.assertUniquePostBuildTestNames)(context, postBuildTestJobs, buildJobs);
+    return [...buildJobs, ...postBuildTestJobs];
 };
 exports.createJobsForWorkspace = createJobsForWorkspace;
 //# sourceMappingURL=createJobsForWorkspace.js.map
@@ -19519,6 +19626,7 @@ exports.resolveRequirements = void 0;
 const DEFAULT_STAGE_CAPABILITIES = {
     build: "build",
     test: "qualityGate",
+    "post-build": "qualityGate",
     deploy: "deployment",
 };
 /**
@@ -19660,6 +19768,216 @@ exports.getWorkspaceDependencies = getWorkspaceDependencies;
 
 /***/ }),
 
+/***/ 61844:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.assertUniquePostBuildTestNames = exports.createPostBuildTestJobs = exports.postBuildTestJobName = exports.POST_BUILD_TEST_STAGE = void 0;
+const createArtifactsConfig_1 = __nccwpck_require__(14149);
+const cache_1 = __nccwpck_require__(74559);
+const constants_1 = __nccwpck_require__(5576);
+const packageManagerInstall_1 = __nccwpck_require__(28419);
+const types_1 = __nccwpck_require__(35249);
+const runner_1 = __nccwpck_require__(92146);
+const jobs_1 = __nccwpck_require__(98521);
+const utils_1 = __nccwpck_require__(49401);
+exports.POST_BUILD_TEST_STAGE = "post-build";
+const postBuildTestJobName = (name) => `🔬 ${name}`;
+exports.postBuildTestJobName = postBuildTestJobName;
+const getPostBuildTestsConfig = (context) => {
+    if (context.type === "workspace") {
+        return context.build.config.postBuildTests;
+    }
+    if (context.build.type === "disabled") {
+        return undefined;
+    }
+    return context.build.config.postBuildTests;
+};
+/**
+ * whether the build output is a node project, so the job has to install
+ * the dependencies before running the tests
+ */
+const isNodeBuild = (context) => {
+    if (context.type === "workspace") {
+        return true; // workspace builds are node builds
+    }
+    if (context.build.type === "fromWorkspace") {
+        return true;
+    }
+    if (context.build.type === "standalone") {
+        return (0, types_1.isOfBuildType)(context.build.config, "node", "node-static", "storybook", "meteor");
+    }
+    return false;
+};
+const hasBuildCommand = (buildCommand) => buildCommand !== null && buildCommand !== false;
+/**
+ * whether the build creates an app build job with artifacts. Rails builds
+ * and builds with `buildCommand: false` only build the docker image.
+ */
+const hasBuildArtifacts = (context) => {
+    if (context.type === "workspace") {
+        return hasBuildCommand(context.build.config.buildCommand);
+    }
+    if (context.build.type === "fromWorkspace") {
+        return hasBuildCommand(context.build.workspaceBuildConfig.buildCommand);
+    }
+    if (context.build.type === "standalone") {
+        return (!(0, types_1.isOfBuildType)(context.build.config, "rails") &&
+            hasBuildCommand(context.build.config.buildCommand));
+    }
+    return false;
+};
+const getDefaultImage = (context) => {
+    if (context.type === "component" &&
+        context.build.type === "standalone" &&
+        (0, types_1.isOfBuildType)(context.build.config, "custom")) {
+        // custom builds bring their own toolchain image
+        return context.build.config.jobImage;
+    }
+    return (0, runner_1.getRunnerImage)("jobs-default");
+};
+/**
+ * jobs for `postBuildTests`: they run after the build in the `post-build`
+ * stage, against the build artifacts, and act as quality gates, so a
+ * failing post-build test blocks the deploy.
+ */
+const createPostBuildTestJobs = async (context) => {
+    var _a;
+    // like lint and test: tagged releases deploy what was already tested
+    if (context.trigger === "taggedRelease") {
+        return [];
+    }
+    const tests = Object.entries((_a = getPostBuildTestsConfig(context)) !== null && _a !== void 0 ? _a : {}).filter((entry) => entry[1] !== false);
+    if (tests.length === 0) {
+        return [];
+    }
+    const nodeBuild = isNodeBuild(context);
+    const [packageManagerInstall, nodeCache] = nodeBuild
+        ? await Promise.all([
+            (0, packageManagerInstall_1.getPackageManagerInstall)(context),
+            // pull-only: the build job is the designated cache writer
+            (0, cache_1.getNodeCache)(context, "pull"),
+        ])
+        : [null, null];
+    // components built in a workspace test the workspace build output
+    const from = context.type === "component" && context.build.type === "fromWorkspace"
+        ? { workspace: context.build.workspaceName }
+        : undefined;
+    const buildRequirement = hasBuildArtifacts(context)
+        ? { capability: "buildArtifacts", artifacts: true, strict: true, from }
+        : // no build artifacts (e.g. rails): run after the build (docker image)
+            { capability: "build", artifacts: false, from };
+    return tests.map(([name, test]) => {
+        var _a, _b, _c;
+        const artifactsConfig = (0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, test.artifactsReports, test.artifacts);
+        return new jobs_1.CatladderJob({
+            name: (0, exports.postBuildTestJobName)(name),
+            stage: exports.POST_BUILD_TEST_STAGE,
+            envMode: "stagePerEnv",
+            provides: ["qualityGate"],
+            needs: [],
+            requires: [buildRequirement],
+            image: (_a = test.jobImage) !== null && _a !== void 0 ? _a : getDefaultImage(context),
+            services: test.services,
+            // neutral cache declarations, lowered by each backend
+            caches: nodeCache !== null && nodeCache !== void 0 ? nodeCache : undefined,
+            variables: {
+                APP_PATH: context.build.dir,
+                ...(context.type === "component"
+                    ? context.environment.jobOnlyVars.build.envVars
+                    : {}),
+                ...((_b = test.vars) !== null && _b !== void 0 ? _b : {}),
+            },
+            runnerVariables: {
+                ...(nodeBuild ? constants_1.NODE_RUNNER_BUILD_VARIABLES : {}),
+                ...((_c = test.runnerVariables) !== null && _c !== void 0 ? _c : {}),
+            },
+            script: [
+                ...(nodeBuild ? (0, packageManagerInstall_1.ensureNodeVersion)(context) : []),
+                `cd ${context.build.dir}`,
+                ...(packageManagerInstall !== null && packageManagerInstall !== void 0 ? packageManagerInstall : []),
+                ...(0, utils_1.ensureArray)(test.command),
+            ],
+            allow_failure: test.allowFailure,
+            // reports and screenshots are most needed when the tests fail
+            ...(artifactsConfig
+                ? {
+                    artifacts: {
+                        when: "always",
+                        ...artifactsConfig.artifacts,
+                    },
+                }
+                : {}),
+        });
+    });
+};
+exports.createPostBuildTestJobs = createPostBuildTestJobs;
+const jobIdOf = (jobName) => jobName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/**
+ * post-build test names are chosen by the user. Github job ids drop the
+ * emoji of the job name, so e.g. a post-build test named `test` would
+ * clash with the `🧪 test` job.
+ */
+const assertUniquePostBuildTestNames = (context, postBuildTestJobs, otherJobs) => {
+    const seenIds = new Set(otherJobs.map((job) => jobIdOf(job.name)));
+    // also catches two post-build tests that only differ in case or
+    // punctuation (e.g. `e2e` and `E2E`)
+    const clash = postBuildTestJobs.find((job) => {
+        const id = jobIdOf(job.name);
+        const isClash = seenIds.has(id);
+        seenIds.add(id);
+        return isClash;
+    });
+    if (clash) {
+        throw new Error(`${context.name}: post-build test '${clash.name}' clashes with another job of the same name, please rename it in postBuildTests`);
+    }
+};
+exports.assertUniquePostBuildTestNames = assertUniquePostBuildTestNames;
+//# sourceMappingURL=createPostBuildTestJobs.js.map
+
+/***/ }),
+
+/***/ 28458:
+/***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
+
+"use strict";
+
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+__exportStar(__nccwpck_require__(92967), exports);
+__exportStar(__nccwpck_require__(61844), exports);
+//# sourceMappingURL=index.js.map
+
+/***/ }),
+
+/***/ 92967:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+//# sourceMappingURL=types.js.map
+
+/***/ }),
+
 /***/ 26041:
 /***/ ((__unused_webpack_module, exports) => {
 
@@ -19993,6 +20311,7 @@ exports.BASE_STAGES = [
     "setup",
     "test",
     "build",
+    "post-build",
     "deploy",
     "verify",
     "agents",

package/dist/bundles/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, 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".
+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, adding e2e tests against the build (`postBuildTests`), or setting up a monorepo workspace build. Triggers on "build config", "postBuildTests", "post-build test", "e2e", "playwright", "buildCommand", "build type", "Dockerfile", "docker image", "job image", "jobImage", "custom image", "project image", "rails build", "monorepo build", "artifacts".
 ---
 
 # Component builds with catladder
@@ -66,6 +66,10 @@ type: `build: { from: "web" }` (see workspace builds below).
   won't run).
 - `lint` / `test` / `audit` — customize (`{ command, jobImage, … }`) or
   set to `false` to disable that job.
+- `postBuildTests` — named tests against the **build output** (e.g. an
+  e2e suite against the production build with a Postgres service). Each
+  entry becomes a job in the `post-build` stage between build and deploy
+  and blocks the deploy when it fails (see below).
 - `artifactsPaths` / `artifactsExcludePaths` — extra build artifacts
   (`dist` and `.next` are always included).
 - `cache` — build caching (see the `catladder-pipelines` skill for the
@@ -82,11 +86,55 @@ type: `build: { from: "web" }` (see workspace builds below).
   (`{ type: "nginx" | "node" | "meteor" }`) or
   `{ type: "custom" }` (expects a `Dockerfile`).
 
+## Post-build tests (e2e against the build)
+
+`lint`/`test` run against the sources, in parallel with the build. Tests
+that need the built app go into `postBuildTests`:
+
+```ts
+build: {
+  type: "node",
+  postBuildTests: {
+    e2e: {
+      command: "pnpm test:e2e",                  // runs in the build dir
+      jobImage: "mcr.microsoft.com/playwright:v1.56.0-noble",
+      services: [{ name: "postgres:17", alias: "postgres",
+                   variables: { POSTGRES_PASSWORD: "postgres" } }],
+      vars: { DATABASE_URL: "postgres://postgres:postgres@postgres:5432/postgres" },
+      artifacts: { paths: ["apps/web/playwright-report"] }, // repo-root relative
+    },
+  },
+}
+```
+
+- The job (`🔬 e2e`, stage `post-build <env>`) downloads the build
+  artifacts (`.next`, `dist`, `artifactsPaths`), installs dependencies
+  for node builds, then runs `command`. The command starts the app
+  itself, e.g. playwright `webServer: { command: "pnpm start" }`.
+  Builds without artifacts (`rails`, `buildCommand: false`) just run
+  it after the build.
+- It is a quality gate: the env's deploy waits for it; on github it is
+  part of the `catladder ✅` required check. `allowFailure: true` makes
+  it report-only.
+- It gets the build vars plus `vars`, **not** the deployed env's
+  runtime vars/secrets — use services instead of the real database.
+- Artifacts are uploaded also when the job fails.
+- Not run in tagged releases. Disable one per env:
+  `env: { dev: { build: { postBuildTests: { e2e: false } } } }`.
+- Names must not clash with other jobs of the component (e.g. `test`,
+  `lint`) — generation fails with a clear error.
+- Workspace builds: on `builds.<ws>` they block the deploys of all
+  components in the workspace; on `build: { from: "<ws>", postBuildTests }`
+  only that component's deploy.
+- To test the **deployed** env instead (smoke tests on dev / review
+  apps), use the component's `verify` (post-deploy, does not block the
+  deploy). The same suite can serve both, with `BASE_URL` as the switch.
+
 ## 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,
+it in any `jobImage` field (build, `test.jobImage`, `postBuildTests`, custom/pages deploy,
 verify):
 
 ```ts

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

@@ -12,6 +12,7 @@ generated pipeline files.
 | `startCommand` | `string` | runtime start command |
 | `postInstall` | `string \| string[]` | runs after the package-manager install (node family) |
 | `lint` / `test` / `audit` | `false \| TestJobCustom` | customize or disable the job |
+| `postBuildTests` | `Record<string, PostBuildTestConfig \| false>` | named tests against the build output in the `post-build` stage; block the deploy |
 | `artifactsPaths` | `string[]` | extra artifacts (`dist`, `.next` always included) |
 | `artifactsExcludePaths` | `string[]` | artifact excludes |
 | `artifactsReports` | `{ junit?: string[] }` | CI test report paths |
@@ -27,6 +28,13 @@ generated pipeline files.
 `artifactsReports`, `artifacts`, `runnerVariables`, `allowFailure`
 (`allowFailure` defaults to `true` for `audit`).
 
+`PostBuildTestConfig` (for `postBuildTests` entries): `TestJobCustom` with
+a required `command`, plus `services?: Services` (gitlab shape, reachable
+by alias) and `vars?: Record<string,string>`. The job gets the build
+artifacts, the build vars and `vars` (not the deployed env's runtime
+vars), installs dependencies for node builds, and uploads `artifacts`
+also on failure.
+
 `audit` additionally takes `level`: `"info" | "low" | "moderate" | "high" |
 "critical"` (default `"critical"`) — the lowest severity that fails the job,
 translated to the package manager's own flag (`pnpm audit --audit-level`,
@@ -81,5 +89,5 @@ defaulted `buildCommand: "yarn build-storybook --quiet -o ./dist"`.
 Top-level `builds: Record<string, WorkspaceBuildConfig>`. Only
 `type: "node"` is supported.
 
-- Node workspace build: `dir?`, `buildCommand?` (default `<pm> build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "<pm> lint" }`), `test?` (default `{ command: "<pm> test" }`), `audit?`, `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?` (`<pm>` = `yarn`/`pnpm` per detection).
-- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache? }` — the per-component overrides layer on top of the shared build.
+- Node workspace build: `dir?`, `buildCommand?` (default `<pm> build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "<pm> lint" }`), `test?` (default `{ command: "<pm> test" }`), `audit?`, `postBuildTests?` (block the deploys of all its components), `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?` (`<pm>` = `yarn`/`pnpm` per detection).
+- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache?, postBuildTests? }` — the per-component overrides layer on top of the shared build.