@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

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

@@ -0,0 +1,35 @@
+import type { RunnerImageName } from "../runner";
+import type { Config } from "../types/config";
+import type { ReleaseMethod } from "../types/release";
+/**
+ * what a release method contributes to the release jobs. The job shape
+ * (stage, rules, gates, token) is identical across methods and stays in
+ * the backends; a method only supplies the tooling image and its
+ * entrypoint script.
+ */
+export type ReleaseMethodDefinition = {
+    /**
+     * the catladder job image carrying the release tooling
+     */
+    image: RunnerImageName;
+    /**
+     * the entrypoint script baked into the image (on PATH), used as the
+     * job script. Every entrypoint must run the security-audit gate
+     * before releasing.
+     */
+    script: string;
+    /**
+     * optional MR/PR check script (on the same image): generates an
+     * informational check job in merge-request pipelines (e.g. the
+     * changeset check reporting what merging would release)
+     */
+    checkScript?: string;
+    /**
+     * variables injected into the FORCE release jobs only, letting the
+     * method's script implement force semantics (e.g. changesets: release
+     * a patch bump even without pending changesets)
+     */
+    forceReleaseVariables?: Record<string, string>;
+};
+export declare const RELEASE_METHODS: Record<ReleaseMethod, ReleaseMethodDefinition>;
+export declare const getReleaseMethod: (config: Config) => ReleaseMethodDefinition;

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReleaseMethod = exports.RELEASE_METHODS = void 0;
+exports.RELEASE_METHODS = {
+    "semantic-release": {
+        image: "semantic-release",
+        script: "semanticRelease",
+    },
+    changesets: {
+        image: "changesets",
+        script: "changesetsRelease",
+        checkScript: "changesetCheck",
+        forceReleaseVariables: { CATLADDER_FORCE_RELEASE: "true" },
+    },
+};
+const getReleaseMethod = (config) => { var _a, _b; return exports.RELEASE_METHODS[(_b = (_a = config.releases) === null || _a === void 0 ? void 0 : _a.method) !== null && _b !== void 0 ? _b : "semantic-release"]; };
+exports.getReleaseMethod = getReleaseMethod;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/release/index.ts"],"names":[],"mappings":";;;AAmCa,QAAA,eAAe,GAAmD;IAC7E,kBAAkB,EAAE;QAClB,KAAK,EAAE,kBAAkB;QACzB,MAAM,EAAE,iBAAiB;KAC1B;IACD,UAAU,EAAE;QACV,KAAK,EAAE,YAAY;QACnB,MAAM,EAAE,mBAAmB;QAC3B,WAAW,EAAE,gBAAgB;QAC7B,qBAAqB,EAAE,EAAE,uBAAuB,EAAE,MAAM,EAAE;KAC3D;CACF,CAAC;AAEK,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAA2B,EAAE,eAC1E,OAAA,uBAAe,CAAC,MAAA,MAAA,MAAM,CAAC,QAAQ,0CAAE,MAAM,mCAAI,kBAAkB,CAAC,CAAA,EAAA,CAAC;AADpD,QAAA,gBAAgB,oBACoC"}

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

@@ -0,0 +1,13 @@
+import type { GitlabRule } from "../types";
+export declare const RULE_CONDITION_MAIN_BRANCH = "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
+export declare const RULE_CONDITION_RELEASE_COMMIT = "$CI_COMMIT_MESSAGE =~ /^chore\\(release\\).*/";
+export declare const RULE_CONDITION_NOT_RELEASE_COMMIT = "$CI_COMMIT_MESSAGE !~ /^chore\\(release\\).*/";
+export declare const RULE_CONDITION_NOT_RELEASE_COMMIT_ON_PUSH = "($CI_COMMIT_MESSAGE !~ /^chore\\(release\\).*/ || $CI_PIPELINE_SOURCE != \"push\")";
+export declare const RULE_IS_MAIN_BRANCH: GitlabRule;
+export declare const RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT: GitlabRule;
+export declare const RULE_NEVER_ON_RELEASE_COMMIT: GitlabRule;
+export declare const RULE_NEVER_ON_AGENT_TRIGGER: GitlabRule;
+export declare const RULE_NEVER_ON_SCHEDULE: GitlabRule;
+export declare const RULE_IS_MERGE_REQUEST: GitlabRule;
+export declare const RULE_IS_TAGGED_RELEASE: GitlabRule;
+export declare const RULE_CONDITION_HOTFIX_BRANCH = "$CI_COMMIT_BRANCH =~ /^[0-9]+.([0-9]+|x).x$/";

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_CONDITION_HOTFIX_BRANCH = exports.RULE_IS_TAGGED_RELEASE = exports.RULE_IS_MERGE_REQUEST = exports.RULE_NEVER_ON_SCHEDULE = exports.RULE_NEVER_ON_AGENT_TRIGGER = exports.RULE_NEVER_ON_RELEASE_COMMIT = exports.RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT = exports.RULE_IS_MAIN_BRANCH = exports.RULE_CONDITION_NOT_RELEASE_COMMIT_ON_PUSH = exports.RULE_CONDITION_NOT_RELEASE_COMMIT = exports.RULE_CONDITION_RELEASE_COMMIT = exports.RULE_CONDITION_MAIN_BRANCH = void 0;
+exports.RULE_CONDITION_MAIN_BRANCH = "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
+exports.RULE_CONDITION_RELEASE_COMMIT = "$CI_COMMIT_MESSAGE =~ /^chore\\(release\\).*/";
+exports.RULE_CONDITION_NOT_RELEASE_COMMIT = "$CI_COMMIT_MESSAGE !~ /^chore\\(release\\).*/";
+// NOT(release_commit AND push) — skip release commits on push, but allow
+// manually triggered (web/API) pipelines even on release commits.
+exports.RULE_CONDITION_NOT_RELEASE_COMMIT_ON_PUSH = '($CI_COMMIT_MESSAGE !~ /^chore\\(release\\).*/ || $CI_PIPELINE_SOURCE != "push")';
+exports.RULE_IS_MAIN_BRANCH = {
+    if: exports.RULE_CONDITION_MAIN_BRANCH,
+};
+exports.RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT = {
+    if: exports.RULE_CONDITION_MAIN_BRANCH +
+        " && " +
+        exports.RULE_CONDITION_NOT_RELEASE_COMMIT_ON_PUSH,
+};
+exports.RULE_NEVER_ON_RELEASE_COMMIT = {
+    if: exports.RULE_CONDITION_RELEASE_COMMIT,
+    when: "never",
+};
+// currently, we consider all triggered pipelines as agent triggers
+exports.RULE_NEVER_ON_AGENT_TRIGGER = {
+    if: '$CI_PIPELINE_SOURCE  == "trigger"',
+    when: "never",
+};
+exports.RULE_NEVER_ON_SCHEDULE = {
+    if: '$CI_PIPELINE_SOURCE  == "schedule"',
+    when: "never",
+};
+exports.RULE_IS_MERGE_REQUEST = {
+    if: "$CI_MERGE_REQUEST_ID",
+};
+exports.RULE_IS_TAGGED_RELEASE = {
+    if: "$CI_COMMIT_TAG",
+};
+exports.RULE_CONDITION_HOTFIX_BRANCH = "$CI_COMMIT_BRANCH =~ /^[0-9]+.([0-9]+|x).x$/";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/rules/index.ts"],"names":[],"mappings":";;;AACa,QAAA,0BAA0B,GACrC,yCAAyC,CAAC;AAE/B,QAAA,6BAA6B,GACxC,+CAA+C,CAAC;AAErC,QAAA,iCAAiC,GAC5C,+CAA+C,CAAC;AAElD,yEAAyE;AACzE,kEAAkE;AACrD,QAAA,yCAAyC,GACpD,kFAAkF,CAAC;AAExE,QAAA,mBAAmB,GAAe;IAC7C,EAAE,EAAE,kCAA0B;CAC/B,CAAC;AACW,QAAA,0CAA0C,GAAe;IACpE,EAAE,EACA,kCAA0B;QAC1B,MAAM;QACN,iDAAyC;CAC5C,CAAC;AACW,QAAA,4BAA4B,GAAe;IACtD,EAAE,EAAE,qCAA6B;IACjC,IAAI,EAAE,OAAO;CACd,CAAC;AACF,mEAAmE;AACtD,QAAA,2BAA2B,GAAe;IACrD,EAAE,EAAE,mCAAmC;IACvC,IAAI,EAAE,OAAO;CACd,CAAC;AAEW,QAAA,sBAAsB,GAAe;IAChD,EAAE,EAAE,oCAAoC;IACxC,IAAI,EAAE,OAAO;CACd,CAAC;AAEW,QAAA,qBAAqB,GAAe;IAC/C,EAAE,EAAE,sBAAsB;CAC3B,CAAC;AAEW,QAAA,sBAAsB,GAAe;IAChD,EAAE,EAAE,gBAAgB;CACrB,CAAC;AAEW,QAAA,4BAA4B,GACvC,8CAA8C,CAAC"}

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

@@ -0,0 +1,16 @@
+export type RunnerImageName = "jobs-default" | "jobs-meteor" | "kubernetes" | "docker-build" | "semantic-release" | "changesets" | "npm-publish" | "agent-claude";
+/**
+ * a reference to a catladder-provided job image. The pipeline backend
+ * resolves it to a concrete image url: the image is built in the
+ * repository's own registry from the image definition shipped with
+ * catladder.
+ */
+export type CatladderImageRef = {
+    catladderImage: RunnerImageName;
+};
+export declare const isCatladderImageRef: (value: unknown) => value is CatladderImageRef;
+/**
+ * job creators use this to reference a catladder-provided job image;
+ * the backends resolve it to a concrete image url
+ */
+export declare const getRunnerImage: (imageName: RunnerImageName) => CatladderImageRef;

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunnerImage = exports.isCatladderImageRef = void 0;
+const isCatladderImageRef = (value) => typeof value === "object" &&
+    value !== null &&
+    "catladderImage" in value &&
+    typeof value.catladderImage === "string";
+exports.isCatladderImageRef = isCatladderImageRef;
+/**
+ * job creators use this to reference a catladder-provided job image;
+ * the backends resolve it to a concrete image url
+ */
+const getRunnerImage = (imageName) => ({
+    catladderImage: imageName,
+});
+exports.getRunnerImage = getRunnerImage;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/runner/index.ts"],"names":[],"mappings":";;;AAoBO,MAAM,mBAAmB,GAAG,CACjC,KAAc,EACc,EAAE,CAC9B,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,gBAAgB,IAAI,KAAK;IACzB,OAAQ,KAA2B,CAAC,cAAc,KAAK,QAAQ,CAAC;AANrD,QAAA,mBAAmB,uBAMkC;AAElE;;;GAGG;AACI,MAAM,cAAc,GAAG,CAC5B,SAA0B,EACP,EAAE,CAAC,CAAC;IACvB,cAAc,EAAE,SAAS;CAC1B,CAAC,CAAC;AAJU,QAAA,cAAc,kBAIxB"}

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+export declare const CATLADDER_STORE_DIR = ".catladder-store";
+export declare const CATLADDER_STORE_FILE_NAME = "store.yml";
+export declare const CATLADDER_STORE_FILE = ".catladder-store/store.yml";
+/**
+ * schema of `.catladder-store/store.yml` — non-secret, machine-fetched
+ * values that pipeline generation needs but that are neither part of the
+ * user-authored config nor derivable from it (e.g. gcloud project numbers).
+ *
+ * The store is written by `catladder project setup` and checked into the
+ * repository. Deleting the folder is safe: rerunning project setup
+ * restores it.
+ */
+export declare const catladderStoreSchema: z.ZodObject<{
+    gcloudProjects: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        projectNumber: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CatladderStore = z.infer<typeof catladderStoreSchema>;
+export declare const getCatladderStorePath: (directory: string) => string;
+/**
+ * reads and validates the catladder store. Returns an empty store when the
+ * file does not exist (project setup has not run yet).
+ *
+ * An unreadable or invalid store is treated the same as a missing one
+ * (with a warning): the store only holds machine-fetched values, so the
+ * remedy is always rerunning project setup — not hand-editing the file.
+ */
+export declare const readCatladderStore: (directory?: string) => CatladderStore;
+/**
+ * gcloud project number from the store, or null when it has not been
+ * fetched yet. Use this where a missing number is not itself the problem —
+ * `getGcloudProjectNumber` is the one that reports it.
+ */
+export declare const readGcloudProjectNumber: (config: {
+    store?: CatladderStore;
+}, projectId: string) => string | null;
+/**
+ * gcloud project number from the store — needed to compute deterministic
+ * cloud run urls (`<service>-<projectNumber>.<region>.run.app`) at
+ * generation time.
+ *
+ * Throws with a setup instruction when the value is missing, which makes
+ * catenv fail until `catladder project setup` has stored it.
+ */
+export declare const getGcloudProjectNumber: (config: {
+    store?: CatladderStore;
+}, projectId: string) => string;

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGcloudProjectNumber = exports.readGcloudProjectNumber = exports.readCatladderStore = exports.getCatladderStorePath = exports.catladderStoreSchema = exports.CATLADDER_STORE_FILE = exports.CATLADDER_STORE_FILE_NAME = exports.CATLADDER_STORE_DIR = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const zod_1 = require("zod");
+exports.CATLADDER_STORE_DIR = ".catladder-store";
+exports.CATLADDER_STORE_FILE_NAME = "store.yml";
+exports.CATLADDER_STORE_FILE = `${exports.CATLADDER_STORE_DIR}/${exports.CATLADDER_STORE_FILE_NAME}`;
+/**
+ * schema of `.catladder-store/store.yml` — non-secret, machine-fetched
+ * values that pipeline generation needs but that are neither part of the
+ * user-authored config nor derivable from it (e.g. gcloud project numbers).
+ *
+ * The store is written by `catladder project setup` and checked into the
+ * repository. Deleting the folder is safe: rerunning project setup
+ * restores it.
+ */
+exports.catladderStoreSchema = zod_1.z.object({
+    /**
+     * gcloud project facts, keyed by project id
+     */
+    gcloudProjects: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.object({
+        projectNumber: zod_1.z.string().regex(/^\d+$/),
+    }))
+        .optional(),
+});
+const getCatladderStorePath = (directory) => (0, path_1.join)(directory, exports.CATLADDER_STORE_DIR, exports.CATLADDER_STORE_FILE_NAME);
+exports.getCatladderStorePath = getCatladderStorePath;
+/**
+ * reads and validates the catladder store. Returns an empty store when the
+ * file does not exist (project setup has not run yet).
+ *
+ * An unreadable or invalid store is treated the same as a missing one
+ * (with a warning): the store only holds machine-fetched values, so the
+ * remedy is always rerunning project setup — not hand-editing the file.
+ */
+const readCatladderStore = (directory = process.cwd()) => {
+    var _a;
+    const path = (0, exports.getCatladderStorePath)(directory);
+    if (!(0, fs_1.existsSync)(path)) {
+        return {};
+    }
+    try {
+        return exports.catladderStoreSchema.parse((_a = (0, yaml_1.parse)((0, fs_1.readFileSync)(path, { encoding: "utf-8" }))) !== null && _a !== void 0 ? _a : {});
+    }
+    catch (error) {
+        console.warn(`⚠️ ignoring invalid ${exports.CATLADDER_STORE_FILE} (rerun "catladder project setup" to regenerate it): ${error instanceof Error ? error.message : error}`);
+        return {};
+    }
+};
+exports.readCatladderStore = readCatladderStore;
+/**
+ * gcloud project number from the store, or null when it has not been
+ * fetched yet. Use this where a missing number is not itself the problem —
+ * `getGcloudProjectNumber` is the one that reports it.
+ */
+const readGcloudProjectNumber = (config, projectId) => { var _a, _b, _c, _d; return (_d = (_c = (_b = (_a = config.store) === null || _a === void 0 ? void 0 : _a.gcloudProjects) === null || _b === void 0 ? void 0 : _b[projectId]) === null || _c === void 0 ? void 0 : _c.projectNumber) !== null && _d !== void 0 ? _d : null; };
+exports.readGcloudProjectNumber = readGcloudProjectNumber;
+/**
+ * gcloud project number from the store — needed to compute deterministic
+ * cloud run urls (`<service>-<projectNumber>.<region>.run.app`) at
+ * generation time.
+ *
+ * Throws with a setup instruction when the value is missing, which makes
+ * catenv fail until `catladder project setup` has stored it.
+ */
+const getGcloudProjectNumber = (config, projectId) => {
+    const projectNumber = (0, exports.readGcloudProjectNumber)(config, projectId);
+    if (!projectNumber) {
+        throw new Error(`Missing gcloud project number for project "${projectId}" in ${exports.CATLADDER_STORE_FILE}.\n` +
+            `Run "catladder project setup" to fetch and store it.`);
+    }
+    return projectNumber;
+};
+exports.getGcloudProjectNumber = getGcloudProjectNumber;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/store/index.ts"],"names":[],"mappings":";;;AAAA,2BAA8C;AAC9C,+BAA4B;AAC5B,+BAA6B;AAC7B,6BAAwB;AAEX,QAAA,mBAAmB,GAAG,kBAAkB,CAAC;AACzC,QAAA,yBAAyB,GAAG,WAAW,CAAC;AACxC,QAAA,oBAAoB,GAAG,GAAG,2BAAmB,IAAI,iCAAyB,EAAE,CAAC;AAE1F;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C;;OAEG;IACH,cAAc,EAAE,OAAC;SACd,MAAM,CACL,OAAC,CAAC,MAAM,EAAE,EACV,OAAC,CAAC,MAAM,CAAC;QACP,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;KACzC,CAAC,CACH;SACA,QAAQ,EAAE;CACd,CAAC,CAAC;AAII,MAAM,qBAAqB,GAAG,CAAC,SAAiB,EAAE,EAAE,CACzD,IAAA,WAAI,EAAC,SAAS,EAAE,2BAAmB,EAAE,iCAAyB,CAAC,CAAC;AADrD,QAAA,qBAAqB,yBACgC;AAElE;;;;;;;GAOG;AACI,MAAM,kBAAkB,GAAG,CAChC,YAAoB,OAAO,CAAC,GAAG,EAAE,EACjB,EAAE;;IAClB,MAAM,IAAI,GAAG,IAAA,6BAAqB,EAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,IAAA,eAAU,EAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,4BAAoB,CAAC,KAAK,CAC/B,MAAA,IAAA,YAAK,EAAC,IAAA,iBAAY,EAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,mCAAI,EAAE,CACvD,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CACV,uBAAuB,4BAAoB,wDACzC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAC3C,EAAE,CACH,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC,CAAC;AAnBW,QAAA,kBAAkB,sBAmB7B;AAEF;;;;GAIG;AACI,MAAM,uBAAuB,GAAG,CACrC,MAAkC,EAClC,SAAiB,EACF,EAAE,uBACjB,OAAA,MAAA,MAAA,MAAA,MAAA,MAAM,CAAC,KAAK,0CAAE,cAAc,0CAAG,SAAS,CAAC,0CAAE,aAAa,mCAAI,IAAI,CAAA,EAAA,CAAC;AAJtD,QAAA,uBAAuB,2BAI+B;AAEnE;;;;;;;GAOG;AACI,MAAM,sBAAsB,GAAG,CACpC,MAAkC,EAClC,SAAiB,EACT,EAAE;IACV,MAAM,aAAa,GAAG,IAAA,+BAAuB,EAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjE,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,8CAA8C,SAAS,QAAQ,4BAAoB,KAAK;YACtF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC,CAAC;AAZW,QAAA,sBAAsB,0BAYjC"}

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

@@ -0,0 +1,16 @@
+export type AgentConfig = {
+    type: "claude";
+    agentUser?: {
+        username: string;
+        userId: string;
+    };
+    reviews?: {
+        /**
+         * usernames that the agent should review merge requests for.
+         * Defaults to agentUser
+         */
+        byUser?: Record<string, {
+            automatic: boolean;
+        }> | "all-automatic";
+    };
+};

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

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

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

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

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

@@ -0,0 +1,338 @@
+import type { BuildConfig } from "../build/types";
+import type { DeployConfig } from "../deploy/types";
+import type { CatladderJobSpec } from "./jobs";
+import type { ComponentContext, PackageManagerType } from "./context";
+import type { PartialDeep } from "./utils";
+import type { PipelineType, WorkspaceBuildConfig } from "..";
+import type { AgentConfig } from "./agent";
+import type { Hooks } from "./hooks";
+import type { ReleaseConfig } from "./release";
+import type { CatladderStore } from "../store";
+import type { AgentSkillsConfig } from "../agentSkills/types";
+import type { ProjectImageConfig } from "../customImages/projectImages";
+import type { VerifyConfig } from "../verify/types";
+export declare const ALL_PIPELINE_TRIGGERS: readonly ["mainBranch", "mr", "taggedRelease"];
+export type PipelineTrigger = (typeof ALL_PIPELINE_TRIGGERS)[number];
+/**
+ * all env types with their trigger.
+ * Each env type has a default env with the same name which is always included
+ */
+export declare const ENV_TYPES: {
+    readonly dev: {
+        readonly triggers: readonly ["mainBranch"];
+    };
+    readonly review: {
+        readonly triggers: readonly ["mr"];
+    };
+    readonly stage: {
+        readonly triggers: readonly ["taggedRelease"];
+    };
+    readonly prod: {
+        readonly triggers: readonly ["taggedRelease"];
+    };
+    readonly local: {
+        readonly triggers: readonly [];
+    };
+};
+/**
+ *
+ * @param trigger a trigger
+ * @returns array of env types for that trigger. this is also the list of default envs
+ */
+export declare const getEnvTypesByTrigger: (trigger: PipelineTrigger) => ("stage" | "prod" | "local" | "dev" | "review")[];
+export declare const DEFAULT_ENVS: string[];
+export declare const DEFAULT_ENV_TYPES: ("stage" | "prod" | "local" | "dev" | "review")[];
+export type EnvType = keyof typeof ENV_TYPES;
+export declare const isKnowEnvType: (env: string) => env is "stage" | "prod" | "local" | "dev" | "review";
+export type EnvVars = {
+    /**
+     * public env vars (means: they are checked in the repo).
+     *
+     * You can reuse env vars in other vars using ${OTHER_VAR}.
+     * You an reuse other public env vars, or secret env vars
+     *
+     * EXAMPLE: A_VAR: "the other var is ${OTHER_VAR}"
+     *
+     * You can reuse vars from other components in the same project using ${componentName:variableName}
+     * EXAMPLE: A_VAR: "the other var is ${api:OTHER_VAR}"
+     */
+    public?: Record<string, any>;
+    /**
+     * env vars whose values live in the vault (managed with catladder/cli).
+     *
+     * Preferred form is a record with the kind per key:
+     * - "secret": sensitive — masked where the platform supports it
+     * - "variable": vault-stored but not sensitive (ids, host suffixes) —
+     *   never masked, so log links stay clickable and environment urls work
+     * - an object for additional per-key config
+     *
+     * EXAMPLE: secret: { API_KEY: "secret", PROJECT_ID: "variable" }
+     *
+     * The plain string[] form (all keys secret) is deprecated.
+     */
+    secret?: string[] | Record<string, SecretVarKind | SecretVarConfig>;
+};
+export type SecretVarKind = "secret" | "variable";
+export type SecretVarConfig = {
+    kind?: SecretVarKind;
+    /** hidden env vars are not shown in config-secrets */
+    hidden?: boolean;
+};
+export type DefaultEnvConfig = {
+    /**
+     * how the app is deployed
+     */
+    deploy: DeployConfig | false;
+    /**
+     * how the app is built and its runtime
+     */
+    build: BuildConfig | false;
+    /**
+     * environment variables
+     */
+    vars?: EnvVars;
+    /**
+     * post-deploy verification: runs a job in the `verify` stage after the deploy,
+     * e.g. an e2e test suite against the freshly deployed environment.
+     *
+     * Runs in all deployed envs by default, disable per env with `verify: false`
+     */
+    verify?: VerifyConfig | false;
+};
+export type DevLocalEnvConfig = {
+    vars?: EnvVars;
+    /**
+     * port that is used. If not set, 3000 is used.
+     * set false to not set a port at all
+     */
+    port?: number | false;
+};
+type AddOverrideFunction<T> = {
+    [K in keyof T]: T[K] | ((defaultValue: T[K]) => T[K]) | (T[K] extends Record<string, unknown> | undefined ? AddOverrideFunction<T[K]> : never);
+};
+type EnvConfigWithOverride<E extends EnvType = EnvType> = AddOverrideFunction<EnvConfig<E>>;
+export type EnvConfig<E extends EnvType = EnvType> = {
+    /**
+     * type of the env (stage, prod, review, dev)
+     */
+    type?: E;
+    /**
+     * host that is used. If not set, a "canonical" url is created
+     */
+    host?: string;
+} & PartialDeep<DefaultEnvConfig>;
+export type EnvConfigWithComponent = EnvConfig<EnvType> & ComponentConfig;
+export type CustomEnv = EnvConfigWithOverride & {
+    type: EnvType;
+};
+export type Env<C extends ConfigProps = never> = {
+    /**
+     * local is a special env that is only used in local development
+     */
+    local?: AddOverrideFunction<DevLocalEnvConfig>;
+    dev?: EnvConfigWithOverride<"dev"> | false;
+    stage?: EnvConfigWithOverride<"stage"> | false;
+    review?: EnvConfigWithOverride<"review"> | false;
+    prod?: EnvConfigWithOverride<"prod"> | false;
+} & Record<C["CustomEnvs"], CustomEnv> & Record<string, any>;
+export type ComponentConfig<C extends ConfigProps = never> = {
+    /**
+     * specify environment configurations
+     */
+    env?: Env<C>;
+    /**
+     * the directory of the component (e.g. where the package.json or similar is located). You can set "." if you only have one app.
+     */
+    dir: string;
+    /**
+     * add custom jobs. Can be an array or a function that receives the context and returns an array of jobs.
+     * For convenience, all env vars are injectd as variables
+     *
+     * customJobs are a last-resort escape hatch. Prefer a first-class
+     * config option whenever one exists.
+     *
+     * Please raise an issue on
+     * https://github.com/panter/catladder/issues
+     * to let us know about why you need to use custom jobs.
+     * This feedback will help us to generalize use cases
+     */
+    customJobs?: CatladderJobSpec[] | ((context: Omit<ComponentContext, "customJobs">) => CatladderJobSpec[]);
+    /**
+     * whether to create a .env
+     *
+     * Be careful, this will overwrite any existing .env file!
+     *
+     * if set to true it will create .env locally and during build.
+     * Be careful: the .env file usually ends up in the build artifacts.
+     * Use this for apps and clients where env does not contain any secrets
+     *
+     *
+     * if set to "local" it will only create .env file locally.
+     * Use this in combination with @dotenvx/dotenvx or node 20 to start apps locally with .env files
+     * During build and runtime, it relies on the env vars set in the environment
+     *
+     * @defaultValue true
+     *
+     */
+    dotEnv?: boolean | "local";
+    /**
+     * whether to create a env.d.ts localy and during build jobs
+     *
+     * @defaultValue true
+     */
+    envDTs?: boolean;
+} & DefaultEnvConfig;
+export type ConfigProps = {
+    CustomEnvs: string;
+};
+/**
+ * per-pipeline-type options
+ */
+export type PipelineOutputOptions = {
+    /**
+     * the git remote that points to this CI system's repository.
+     * Relevant during migrations, where e.g. gitlab is `origin` and
+     * github is a second remote.
+     *
+     * defaults to "origin"
+     */
+    gitRemote?: string;
+    /**
+     * variables applied to every job of THIS pipeline type only —
+     * lowered to gitlab's pipeline-level `variables:` / github's
+     * workflow-level `env:`, so job-level `runnerVariables` take
+     * precedence.
+     *
+     * Useful when the CI systems need different values, e.g. a lower
+     * `TURBO_CONCURRENCY` for github's small hosted runners.
+     */
+    runnerVariables?: Record<string, string>;
+};
+/**
+ * where secret values are stored and edited (the readable source of
+ * truth). CI backends only receive mirrored copies.
+ *
+ * - "gitlab" (default): the gitlab project variables double as the
+ *   secret store (legacy behavior; requires a gitlab project)
+ * - bitwarden: secrets live in bitwarden as one yaml note per
+ *   env/component (`<customer>/<app>/<env>/<component>/secrets.yml`)
+ */
+export type SecretsVaultConfig = "gitlab" | {
+    type: "gitlab";
+} | {
+    type: "bitwarden";
+    /**
+     * the bitwarden collection holding the secret notes
+     * @default "catladder"
+     */
+    collection?: string;
+};
+export type SecretsConfig = {
+    vault?: SecretsVaultConfig;
+};
+export type Config<C extends ConfigProps = never> = {
+    /**
+     * the pipeline type to generate, defaults to gitlab
+     *
+     * @deprecated use `pipelines` instead
+     */
+    pipelineType?: PipelineType;
+    /**
+     * which pipelines to generate. Multiple pipeline types can be enabled
+     * at the same time (e.g. during a step-by-step migration from one CI
+     * system to another); each generates its own set of files.
+     *
+     * Defaults to `{ gitlab: true }` (or the deprecated `pipelineType`).
+     *
+     * @example
+     * pipelines: {
+     *   gitlab: true,
+     * }
+     */
+    pipelines?: {
+        [T in PipelineType]?: boolean | PipelineOutputOptions;
+    };
+    /**
+     * how secrets are stored and shared (see {@link SecretsConfig})
+     */
+    secrets?: SecretsConfig;
+    /**
+     * which package manager the project uses. Usually not needed:
+     * catladder autodetects it from the `packageManager` field in
+     * package.json or the lockfile present (pnpm-lock.yaml / yarn.lock),
+     * falling back to yarn. Set it to override the detection.
+     */
+    packageManager?: PackageManagerType;
+    /**
+     * materialize the agent skills shipped with catladder (usage guides
+     * for AI coding agents like Claude Code) into the repository, so
+     * agents working in the project use knowledge matching the installed
+     * catladder version. The skills are written on every generation into
+     * `catladder-*` directories under the agent skill folders (e.g.
+     * `.claude/skills/`) — that namespace is owned by catladder and must
+     * not be edited manually.
+     *
+     * - `true` / omitted (default): write to `.claude/skills/` only
+     *   (Claude Code is the only agent that consumes these today)
+     * - `false`: opt out (previously generated skills are removed)
+     * - `{ targets: [...] }`: write to the given targets, e.g.
+     *   `["claude-code", "agents"]` to also populate the cross-agent
+     *   `.agents/skills/` directory
+     */
+    agentSkills?: AgentSkillsConfig;
+    /**
+     * name of the customer or group
+     */
+    customerName: string;
+    /**
+     * name of the app / project
+     */
+    appName: string;
+    /**
+     * if a env does not define a host, it will generate a canonical one (e.g. for review, dev and stage).
+     * This prop specifies the domain that is used for these urls.
+     *
+     */
+    domainCanonical?: string;
+    agents?: Record<string, AgentConfig>;
+    /**
+     * docker images declared by the project, built automatically in the
+     * pipeline: content-hashed into the project's own registry and only
+     * rebuilt when their inputs change. Reference them in any `jobImage`
+     * field via `{ image: "<key>" }`.
+     */
+    images?: Record<string, ProjectImageConfig>;
+    builds?: Record<string, WorkspaceBuildConfig>;
+    /**
+     * components (sub apps)
+     */
+    components: Record<string, ComponentConfig<C>>;
+    /**
+     * additional meta data (only for organisational purposes)
+     */
+    meta?: {
+        labels?: Record<string, string>;
+    };
+    /**
+     * additional vars only for the runner in all jobs.
+     */
+    runnerVariables?: Record<string, string>;
+    /**
+     * hook into catladder generation
+     */
+    hooks?: Hooks;
+    /**
+     * configure tagged releases
+     */
+    releases?: ReleaseConfig;
+    /**
+     * contents of `.catladder-store/store.yml` — non-secret, machine-fetched
+     * values written by `catladder project setup` (e.g. gcloud project
+     * numbers).
+     *
+     * Attached automatically when the config is read from disk; do not set
+     * this manually in catladder.ts.
+     */
+    store?: CatladderStore;
+};
+export {};