@catladder/cli 5.4.1 → 5.6.0

package/dist/packages/pipeline/src/postBuildTest/createPostBuildTestJobs.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertUniquePostBuildTestNames = exports.createPostBuildTestJobs = exports.postBuildTestJobName = exports.POST_BUILD_TEST_STAGE = void 0;
+const createArtifactsConfig_1 = require("../build/base/createArtifactsConfig");
+const cache_1 = require("../build/node/cache");
+const constants_1 = require("../build/node/constants");
+const packageManagerInstall_1 = require("../build/node/packageManagerInstall");
+const types_1 = require("../build/types");
+const runner_1 = require("../runner");
+const jobs_1 = require("../types/jobs");
+const utils_1 = require("../utils");
+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

package/dist/packages/pipeline/src/postBuildTest/createPostBuildTestJobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPostBuildTestJobs.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/postBuildTest/createPostBuildTestJobs.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./createPostBuildTestJobs";

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

@@ -0,0 +1,19 @@
+"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(require("./types"), exports);
+__exportStar(require("./createPostBuildTestJobs"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/postBuildTest/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,4DAA0C"}

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

@@ -0,0 +1,61 @@
+import type { TestJobCustom } from "../build/types";
+import type { Services } from "../types/gitlab-ci-yml";
+/**
+ * a test job that runs after the build, against the build output, and
+ * blocks the deploy when it fails (e.g. an e2e suite against the
+ * production build with a database service)
+ */
+export type PostBuildTestConfig = TestJobCustom & {
+    /**
+     * command(s) to run, in the build directory (component dir, or the
+     * workspace dir for workspace builds). The build artifacts (e.g.
+     * `dist`, `.next`) are already in place and dependencies are
+     * installed for node builds.
+     *
+     * The command is responsible for starting the app if it needs one,
+     * e.g. via playwright's `webServer` option running `next start`.
+     */
+    command: string | string[];
+    /**
+     * services the job needs, e.g. a database:
+     *
+     * ```ts
+     * services: [{
+     *   name: "postgres:17",
+     *   alias: "postgres",
+     *   variables: { POSTGRES_PASSWORD: "postgres" },
+     * }]
+     * ```
+     *
+     * The service is reachable by its alias as hostname. On github,
+     * `command` and `entrypoint` of a service are not supported.
+     */
+    services?: Services;
+    /**
+     * variables for this job, e.g. `DATABASE_URL` pointing to a service
+     * or `BASE_URL` for the test runner.
+     *
+     * The job gets the build vars of the component (like the build and
+     * test jobs), but not the runtime vars and secrets of the deployed
+     * environment: post-build tests run before the deploy, also for
+     * merge requests, and should use their own services.
+     */
+    vars?: Record<string, string>;
+};
+/**
+ * named post-build tests: each entry becomes its own job in the
+ * `post-build` stage. Set an entry to `false` to disable it (e.g. in an
+ * env-specific override).
+ */
+export type PostBuildTestsConfig = Record<string, PostBuildTestConfig | false>;
+export type WithPostBuildTests = {
+    /**
+     * tests that run after the build against the build output, in the
+     * `post-build` stage between build and deploy. A failing post-build
+     * test blocks the deploy.
+     *
+     * Each entry becomes its own job, e.g. `{ e2e: { command: "pnpm test:e2e" } }`.
+     * Post-build tests don't run in tagged-release pipelines (like lint and test).
+     */
+    postBuildTests?: PostBuildTestsConfig;
+};

package/dist/packages/pipeline/src/postBuildTest/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/postBuildTest/types.ts"],"names":[],"mappings":""}

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

@@ -170,7 +170,10 @@ export type EnvironmentConfig = {
      * `{ branch: "next" }` deploys the env on pushes to that branch —
      * one stable environment tracking a long-lived branch.
      *
-     * `false` removes the env from all pipelines.
+     * `false` keeps the env but never deploys it from a pipeline (like
+     * `local`): it still exists for `catladder project setup`, secrets and
+     * catenv. To remove an env from the project entirely, disable it
+     * instead: `environments: { stage: false }`.
      */
     on?: EnvOnConfig;
     /**
@@ -220,6 +223,18 @@ export type EnvironmentConfig = {
  * Inheriting from `local` is not possible, chains are followed, cycles
  * are an error.
  */
+/**
+ * the top-level `environments` config: per env either its project-wide
+ * declaration/tuning, or `false` to disable the env for the whole
+ * project (all components, setup, secrets, pipelines, catenv).
+ */
+export type EnvironmentsConfig = Record<string, EnvironmentConfig | false>;
+/**
+ * the project-wide config of `env` (undefined when not declared or
+ * disabled)
+ */
+export declare const getEnvironmentConfig: (environments: EnvironmentsConfig | undefined, env: string) => EnvironmentConfig | undefined;
+export declare const isEnvironmentDisabled: (environments: EnvironmentsConfig | undefined, env: string) => boolean;
 export type EnvironmentInheritConfig = string | {
     /** env whose per-component config overrides are inherited */
     config?: string;
@@ -430,8 +445,11 @@ export type Config<C extends ConfigProps = never> = {
      * - declare an extra env (every component deploys to it unless it
      *   opts out with `env.<name>: false`):
      *   `environments: { next: { type: "dev", on: { branch: "next" } } }`
+     * - disable an env for the whole project (no setup, secrets, jobs or
+     *   catenv for any component): `environments: { stage: false }`.
+     *   A single component opts out with `env.<name>: false` instead.
      */
-    environments?: Record<string, EnvironmentConfig>;
+    environments?: EnvironmentsConfig;
     /**
      * components (sub apps)
      */

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isKnowEnvType = exports.DEFAULT_ENV_TYPES = exports.DEFAULT_ENVS = exports.ENV_TYPES = exports.envTriggerEquals = exports.isBranchTrigger = exports.ALL_PIPELINE_TRIGGERS = void 0;
+exports.isEnvironmentDisabled = exports.getEnvironmentConfig = exports.isKnowEnvType = exports.DEFAULT_ENV_TYPES = exports.DEFAULT_ENVS = exports.ENV_TYPES = exports.envTriggerEquals = exports.isBranchTrigger = exports.ALL_PIPELINE_TRIGGERS = void 0;
 exports.ALL_PIPELINE_TRIGGERS = [
     "mainBranch",
     "mr",
@@ -43,4 +43,12 @@ const isKnowEnvType = (env) => {
     return env in exports.ENV_TYPES;
 };
 exports.isKnowEnvType = isKnowEnvType;
+/**
+ * the project-wide config of `env` (undefined when not declared or
+ * disabled)
+ */
+const getEnvironmentConfig = (environments, env) => (environments === null || environments === void 0 ? void 0 : environments[env]) || undefined;
+exports.getEnvironmentConfig = getEnvironmentConfig;
+const isEnvironmentDisabled = (environments, env) => (environments === null || environments === void 0 ? void 0 : environments[env]) === false;
+exports.isEnvironmentDisabled = isEnvironmentDisabled;
 //# sourceMappingURL=config.js.map

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":";;;AAea,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAoBJ,MAAM,eAAe,GAAG,CAC7B,OAA2B,EACO,EAAE,CACpC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAI,OAAO,CAAC;AAH5D,QAAA,eAAe,mBAG6C;AAElE,MAAM,gBAAgB,GAAG,CAC9B,CAA0B,EAC1B,CAAqB,EACZ,EAAE;IACX,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,IAAA,uBAAe,EAAC,CAAC,CAAC;QAAE,OAAO,IAAA,uBAAe,EAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC,CAAC;AAPW,QAAA,gBAAgB,oBAO3B;AAEF;;;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;AAEE,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;AAoBJ,MAAM,eAAe,GAAG,CAC7B,OAA2B,EACO,EAAE,CACpC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAI,OAAO,CAAC;AAH5D,QAAA,eAAe,mBAG6C;AAElE,MAAM,gBAAgB,GAAG,CAC9B,CAA0B,EAC1B,CAAqB,EACZ,EAAE;IACX,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,IAAA,uBAAe,EAAC,CAAC,CAAC;QAAE,OAAO,IAAA,uBAAe,EAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC,CAAC;AAPW,QAAA,gBAAgB,oBAO3B;AAEF;;;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;AAEE,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;AAmMF;;;GAGG;AACI,MAAM,oBAAoB,GAAG,CAClC,YAA4C,EAC5C,GAAW,EACoB,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,KAAI,SAAS,CAAC;AAHxD,QAAA,oBAAoB,wBAGoC;AAE9D,MAAM,qBAAqB,GAAG,CACnC,YAA4C,EAC5C,GAAW,EACF,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,MAAK,KAAK,CAAC;AAH/B,QAAA,qBAAqB,yBAGU"}

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

@@ -16,7 +16,7 @@ export type CatladderJobCache = GitlabJobCache & {
     cacheId?: string;
     redundantOnExactHitOf?: string;
 };
-export declare const BASE_STAGES: readonly ["setup", "test", "build", "deploy", "verify", "agents", "rollback", "stop"];
+export declare const BASE_STAGES: readonly ["setup", "test", "build", "post-build", "deploy", "verify", "agents", "rollback", "stop"];
 export type BaseStage = (typeof BASE_STAGES)[number];
 export type CatladderJobNeed = string | {
     job: string;
@@ -130,7 +130,7 @@ export type CatladderJobCore<S = BaseStage> = {
     /**
      * the capabilities this job provides to other jobs.
      * If not set, it is derived from the stage:
-     * build -> "build", test -> "qualityGate", deploy -> "deployment"
+     * build -> "build", test and post-build -> "qualityGate", deploy -> "deployment"
      */
     provides?: CapabilityName[];
     /**

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

@@ -6,6 +6,7 @@ exports.BASE_STAGES = [
     "setup",
     "test",
     "build",
+    "post-build",
     "deploy",
     "verify",
     "agents",

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":";;;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;AAuOX;;;;;;;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,YAAY;IACZ,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;AAuOX;;;;;;;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, 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/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.

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

@@ -33,20 +33,23 @@ const config = {
   appName: "my-app",
   customerName: "pan",
   pipelines: { gitlab: true, github: true }, // which CI systems to generate
-  environments: {              // optional: project-wide env declarations/tuning
+  environments: {
+    // optional: project-wide env declarations/tuning
     review: { autoStop: "3 days" },
+    stage: false, // the project has no stage env (any component)
     next: { type: "dev", on: { branch: "next" } }, // extra branch-tracking env
   },
   components: {
     www: {
-      dir: "frontend",          // working directory of this component
-      vars: { public: {}, secret: [] },  // env vars (see catladder-secrets skill)
-      build: { type: "node" },  // node | rails | meteor | custom — see catladder-builds
+      dir: "frontend", // working directory of this component
+      vars: { public: {}, secret: [] }, // env vars (see catladder-secrets skill)
+      build: { type: "node" }, // node | rails | meteor | custom — see catladder-builds
       deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
-      env: {                    // enable/customize per environment
+      env: {
+        // enable/customize per environment
         review: {},
         dev: {},
-        stage: false,           // false disables the env for this component
+        stage: false, // false disables the env for this component only
         prod: {},
       },
     },
@@ -68,9 +71,17 @@ Key concepts:
   per-component `env.<name>` entries only carry component-local
   overrides (vars, deploy settings, host, autoStop) or `false` to opt
   the component out. In `environments`:
+  - `<name>: false` — disables the env for the whole project: no
+    component has it, so no setup contexts (`catladder project setup`),
+    secrets, pipeline jobs/workflows or catenv for it. This is how to
+    say "this project has no stage": `environments: { stage: false }`
+    (not `on: false`). `local` cannot be disabled; inheriting from a
+    disabled env is an error.
   - `on` — when the env deploys: `"mainBranch"`, `"mr"`,
     `"taggedRelease"`, `{ branch: "next" }` (a stable env deploying on
-    pushes to that branch), or `false` (in no pipeline). `on: "mr"`
+    pushes to that branch), or `false` (never deployed by a pipeline —
+    the env still exists for setup, secrets and catenv; use
+    `environments.<name>: false` to remove it). `on: "mr"`
     makes an env a review app (one instance per MR/PR, torn down on
     close). Defaults from the env type.
   - `autoStop` — how long a stoppable environment stays up after its