@catladder/cli 5.1.3 → 5.3.0

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

@@ -13,6 +13,24 @@ 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];
+/**
+ * a pipeline that runs on pushes to one specific branch (in addition to
+ * the built-in triggers). Declared by an env via its `on` config.
+ */
+export type BranchPipelineTrigger = {
+    branch: string;
+};
+/**
+ * everything a pipeline (and therefore an env's jobs) can run on
+ */
+export type EnvPipelineTrigger = PipelineTrigger | BranchPipelineTrigger;
+/**
+ * the `on` config of an env: a trigger, or `false` for an env that is
+ * not part of any pipeline (like `local`)
+ */
+export type EnvOnConfig = EnvPipelineTrigger | false;
+export declare const isBranchTrigger: (trigger: EnvPipelineTrigger) => trigger is BranchPipelineTrigger;
+export declare const envTriggerEquals: (a: EnvOnConfig | undefined, b: EnvPipelineTrigger) => boolean;
 /**
  * all env types with their trigger.
  * Each env type has a default env with the same name which is always included
@@ -34,16 +52,10 @@ export declare const ENV_TYPES: {
         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 declare const DEFAULT_ENV_TYPES: ("stage" | "prod" | "local" | "review" | "dev")[];
 export type EnvType = keyof typeof ENV_TYPES;
-export declare const isKnowEnvType: (env: string) => env is "stage" | "prod" | "local" | "dev" | "review";
+export declare const isKnowEnvType: (env: string) => env is "stage" | "prod" | "local" | "review" | "dev";
 export type EnvVars = {
     /**
      * public env vars (means: they are checked in the repo).
@@ -120,7 +132,100 @@ export type EnvConfig<E extends EnvType = EnvType> = {
      * host that is used. If not set, a "canonical" url is created
      */
     host?: string;
+    /**
+     * per-component override of the environment's autoStop (see
+     * {@link EnvironmentConfig.autoStop} — each component has its own
+     * gitlab environment, so the duration may differ per component)
+     */
+    autoStop?: string | false;
 } & PartialDeep<DefaultEnvConfig>;
+/**
+ * project-wide declaration and tuning of an environment (the top-level
+ * `environments` config). Environments are a project-wide concept —
+ * every component deploys to a declared env unless it opts out with
+ * `env.<name>: false`. Anything that must be consistent across
+ * components (which envs exist, when they deploy) lives here; the
+ * per-component `env.<name>` entries only override component-local
+ * things (vars, deploy settings, host, autoStop).
+ */
+export type EnvironmentConfig = {
+    /**
+     * the type of env this behaves like (dev, review, stage, prod) —
+     * think of it as a preset: it supplies all defaults (when the env
+     * deploys, autoStop, deploy policy like rollback history and manual
+     * prod deploys) and the env's identity for tooling (the `ENV_TYPE`
+     * env var / `env-type` label). Everything it implies can be
+     * overridden explicitly. Required for envs whose name is not itself
+     * an env type.
+     */
+    type?: EnvType;
+    /**
+     * when this env deploys. Defaults from the env type:
+     * - dev: "mainBranch" (pushes to the default branch)
+     * - review: "mr" (merge requests / pull requests; the env is created
+     *   per MR and torn down when it closes)
+     * - stage / prod: "taggedRelease" (release tags)
+     * - local: false (not part of any pipeline)
+     *
+     * `{ 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.
+     */
+    on?: EnvOnConfig;
+    /**
+     * how long the environment stays up after its last deployment before
+     * gitlab stops it automatically (gitlab `auto_stop_in`, e.g. "3 days").
+     * `false` disables auto-stopping. Defaults from the env type, tunable
+     * project-wide via the top-level `autoStop` durations: review
+     * "1 week", dev "4 weeks", everything else never.
+     *
+     * Only applies to stoppable deployments, and only on gitlab (github
+     * review apps stop when their pull request closes). Components can
+     * override it per env (`env.<name>.autoStop`).
+     *
+     * NOTE: an explicit value here is a literal — setting it on a review
+     * env opts that env out of the pin-label mechanism (the top-level
+     * `autoStop.pinLabel`), which only steers the default review lifetime.
+     */
+    autoStop?: string | false;
+    /**
+     * inherit from another environment (see {@link EnvironmentInheritConfig}):
+     *
+     * `inherit: "dev"` makes this env use dev's per-component config
+     * overrides AND dev's secret values. The object form controls the two
+     * axes separately.
+     */
+    inherit?: EnvironmentInheritConfig;
+};
+/**
+ * what an environment inherits from another environment.
+ *
+ * The string shorthand `inherit: "dev"` means
+ * `{ config: "dev", secrets: "dev" }`.
+ *
+ * - `config`: the named env's per-component overrides (`env.<name>` in
+ *   each component — vars, deploy/build settings, autoStop) are merged
+ *   in below this env's own overrides: component base → inherited env's
+ *   overrides → own overrides. `host` and `type` are never inherited
+ *   (a host must stay unique per env). The env's `type` defaults to the
+ *   inherited env's type.
+ * - `secrets`: this env uses the named env's secret VALUES — all or
+ *   nothing: its jobs reference the other env's secret variables
+ *   (`CL_<OTHERENV>_...`) and it has no secret store of its own, so the
+ *   secrets CLI manages them via the other env and rotating them
+ *   affects both envs. Set to `false` (or omit in the object form) for
+ *   own secrets.
+ *
+ * Inheriting from `local` is not possible, chains are followed, cycles
+ * are an error.
+ */
+export type EnvironmentInheritConfig = string | {
+    /** env whose per-component config overrides are inherited */
+    config?: string;
+    /** env whose secret values are used (all-or-nothing); false = own secrets */
+    secrets?: string | false;
+};
 export type EnvConfigWithComponent = EnvConfig<EnvType> & ComponentConfig;
 export type CustomEnv = EnvConfigWithOverride & {
     type: EnvType;
@@ -134,7 +239,7 @@ export type Env<C extends ConfigProps = never> = {
     stage?: EnvConfigWithOverride<"stage"> | false;
     review?: EnvConfigWithOverride<"review"> | false;
     prod?: EnvConfigWithOverride<"prod"> | false;
-} & Record<C["CustomEnvs"], CustomEnv> & Record<string, any>;
+} & Partial<Record<C["CustomEnvs"], EnvConfigWithOverride | false>> & Record<string, any>;
 export type ComponentConfig<C extends ConfigProps = never> = {
     /**
      * specify environment configurations
@@ -315,6 +420,18 @@ export type Config<C extends ConfigProps = never> = {
      */
     images?: Record<string, ProjectImageConfig>;
     builds?: Record<string, WorkspaceBuildConfig>;
+    /**
+     * project-wide environment declarations and tuning. Environments are
+     * shared across all components, so everything that must be consistent
+     * between them (which envs exist, their type, when they deploy) is
+     * declared here — components only carry per-component overrides.
+     *
+     * - tune a default env: `environments: { review: { autoStop: "3 days" } }`
+     * - declare an extra env (every component deploys to it unless it
+     *   opts out with `env.<name>: false`):
+     *   `environments: { next: { type: "dev", on: { branch: "next" } } }`
+     */
+    environments?: Record<string, EnvironmentConfig>;
     /**
      * components (sub apps)
      */

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

@@ -1,11 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isKnowEnvType = exports.DEFAULT_ENV_TYPES = exports.DEFAULT_ENVS = exports.getEnvTypesByTrigger = exports.ENV_TYPES = exports.ALL_PIPELINE_TRIGGERS = void 0;
+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",
     "taggedRelease",
 ];
+const isBranchTrigger = (trigger) => typeof trigger === "object" && trigger !== null && "branch" in trigger;
+exports.isBranchTrigger = isBranchTrigger;
+const envTriggerEquals = (a, b) => {
+    if (a === undefined || a === false)
+        return false;
+    if ((0, exports.isBranchTrigger)(b))
+        return (0, exports.isBranchTrigger)(a) && a.branch === b.branch;
+    return a === b;
+};
+exports.envTriggerEquals = envTriggerEquals;
 /**
  * all env types with their trigger.
  * Each env type has a default env with the same name which is always included
@@ -27,15 +37,6 @@ exports.ENV_TYPES = {
         triggers: [],
     },
 };
-/**
- *
- * @param trigger a trigger
- * @returns array of env types for that trigger. this is also the list of default envs
- */
-const getEnvTypesByTrigger = (trigger) => Object.entries(exports.ENV_TYPES)
-    .filter(([, e]) => e.triggers.includes(trigger))
-    .map(([e]) => e);
-exports.getEnvTypesByTrigger = getEnvTypesByTrigger;
 exports.DEFAULT_ENVS = Object.keys(exports.ENV_TYPES);
 exports.DEFAULT_ENV_TYPES = exports.DEFAULT_ENVS;
 const isKnowEnvType = (env) => {

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;AAGX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEX;;;;GAIG;AACI,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAE,EAAE,CAC/D,MAAM,CAAC,OAAO,CAAC,iBAAS,CAAC;KACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,CAAC,CAAC,QAAuC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC7D;KACA,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAY,CAAC,CAAC;AALnB,QAAA,oBAAoB,wBAKD;AAEnB,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAea,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;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"}

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

@@ -3,7 +3,8 @@ import type { BuildConfigFromWorkspace, BuildConfigStandalone, WorkspaceBuildCon
 import type { PredefinedVariables, SecretEnvVar } from "../context";
 import type { DeployConfig } from "../deploy";
 import type { VariableValue } from "../../../bash/src/index.js";
-import type { ComponentConfig, Config, EnvType, PipelineTrigger } from "./config";
+import type { ComponentConfig, Config, EnvPipelineTrigger, EnvType } from "./config";
+import type { EnvironmentInstance } from "./environmentContext";
 import type { BaseStage, CatladderJob, CatladderJobSpec } from "./jobs";
 import type { PipelineType } from "./pipeline";
 export type UnspecifiedEnvVars = Record<string, VariableValue | undefined | null>;
@@ -29,8 +30,14 @@ export type Environment = {
      * the environment slug without component name.
      */
     slugPrefix: StringOrBashExpression;
+    /**
+     * how the env is instantiated — `instance.type === "review"` is the
+     * way to find out whether this is a review app
+     */
+    instance: EnvironmentInstance;
     /**
      * the review slug, if it is a review app, null otherwise
+     * @deprecated use `instance` — the review variant carries the slug
      */
     reviewSlug: StringOrBashExpression | null;
     /**
@@ -38,6 +45,18 @@ export type Environment = {
      */
     slug: StringOrBashExpression;
     envType: EnvType;
+    /**
+     * the resolved `autoStop` config (component override, then the
+     * project-wide environment config — see {@link EnvironmentConfig.autoStop});
+     * undefined means the env type's default applies
+     */
+    autoStop?: string | false;
+    /**
+     * the env whose secret values this env uses — the env itself unless
+     * it shares another env's secrets via `inherit`. All secret variable
+     * names are built with this env.
+     */
+    secretsEnv: string;
 } & EnvironmentEnvVarPart;
 export type YarnWorkspace = {
     name: string;
@@ -136,7 +155,7 @@ export type ComponentContext<BC extends BuildContextComponent = BuildContextComp
     deploy?: DeployContext | null;
     fullConfig: Config;
     environment: Environment;
-    trigger?: PipelineTrigger;
+    trigger?: EnvPipelineTrigger;
     pipelineType?: PipelineType;
     packageManagerInfo: Promise<PackageManagerInfoComponent>;
     customJobs?: CatladderJobSpec[];
@@ -159,7 +178,7 @@ export type WorkspaceContext = {
     packageManagerInfo: Promise<PackageManagerInfoBase>;
     components: Array<ComponentContext>;
     build: BuildContextWorkspace;
-    trigger: PipelineTrigger;
+    trigger: EnvPipelineTrigger;
     pipelineType: PipelineType;
     env: string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/context.ts"],"names":[],"mappings":";;;AAiNO,MAAM,iCAAiC,GAAG,CAC/C,OAAgD,EACK,EAAE;IACvD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AAC7C,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C;AAEK,MAAM,iCAAiC,GAAG,CAC/C,OAAgD,EACQ,EAAE;IAC1D,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AAChD,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/context.ts"],"names":[],"mappings":";;;AAsOO,MAAM,iCAAiC,GAAG,CAC/C,OAAgD,EACK,EAAE;IACvD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AAC7C,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C;AAEK,MAAM,iCAAiC,GAAG,CAC/C,OAAgD,EACQ,EAAE;IAC1D,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AAChD,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C"}

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

@@ -3,20 +3,49 @@ import type { BuildConfig } from "../build";
 import type { DeployConfig } from "../deploy";
 import type { Config, EnvConfigWithComponent, EnvType } from "./config";
 import type { PipelineType } from "./pipeline";
+/**
+ * how an environment is instantiated:
+ * - "stable": one long-lived instance (dev, stage, prod, branch envs)
+ * - "review": one instance per merge/pull request (`on: "mr"`),
+ *   addressed by the runtime review slug (mr<iid> / pr<number>)
+ */
+export type EnvironmentInstance = {
+    type: "stable";
+} | {
+    type: "review";
+    reviewSlug: StringOrBashExpression;
+};
 export type EnvironmentContext<B extends BuildConfig = BuildConfig, D extends DeployConfig = DeployConfig> = {
     envConfigRaw: EnvConfigWithComponent;
     buildConfigRaw: false | B;
     deployConfigRaw: false | D;
     env: string;
     envType: EnvType;
+    /**
+     * the resolved autoStop config (component override, then project-wide
+     * environment config); undefined means the env type's default applies
+     */
+    autoStop?: string | false;
+    /**
+     * the env whose secret values this env uses — the env itself unless
+     * it shares another env's secrets via `inherit`. All secret variable
+     * names are built with this env.
+     */
+    secretsEnv: string;
     componentName: string;
     fullName: StringOrBashExpression;
     /**
      * the environment slug without component name.
      */
     environmentSlugPrefix: StringOrBashExpression;
+    /**
+     * how the env is instantiated — `instance.type === "review"` is the
+     * way to find out whether this is a review app
+     */
+    instance: EnvironmentInstance;
     /**
      * the review slug, if it is a review app, null otherwise
+     * @deprecated use `instance` — the review variant carries the slug
      */
     reviewSlug: StringOrBashExpression | null;
     /**

package/dist/packages/pipeline/src/types/gitlab-types.d.ts

@@ -4,6 +4,33 @@ export { Retry, Image as GitlabJobImage } from "./gitlab-ci-yml";
 export type Artifacts = GitlabCiArtifacts;
 export type { GitlabJobCache };
 export type GitlabRule = Exclude<Exclude<Rules, null>[number], string | string[]>;
+/**
+ * gitlab's auto-cancel policy for redundant pipelines. Tunes the
+ * project setting "Auto-cancel redundant pipelines" (Settings > CI/CD >
+ * General pipelines) — it does NOT enable it: with the setting off,
+ * nothing is ever cancelled regardless of this.
+ *
+ * needs gitlab >= 16.8 (top-level) / >= 16.10 (per workflow rule).
+ */
+export interface GitlabAutoCancel {
+    /**
+     * - `conservative` (gitlab's default): cancel the whole pipeline, but
+     *   only while no `interruptible: false` job has *started* — a single
+     *   such job then shields every other job from cancellation
+     * - `interruptible`: cancel every `interruptible: true` job, with no
+     *   such veto
+     * - `none`: never auto-cancel
+     */
+    on_new_commit?: "conservative" | "interruptible" | "none";
+    on_job_failure?: "all" | "none";
+}
+/**
+ * a workflow rule may override {@link GitlabAutoCancel} per pipeline
+ * kind — job rules may not.
+ */
+export type GitlabWorkflowRule = GitlabRule & {
+    auto_cancel?: GitlabAutoCancel;
+};
 export type GitlabEnvironment = Omit<Exclude<JobTemplate["environment"], undefined | string>, "deployment_tier">;
 export interface GitlabJobDef extends Pick<JobTemplate, "after_script" | "allow_failure" | "artifacts" | "before_script" | "coverage" | "dependencies" | "environment" | "except" | "hooks" | "image" | "interruptible" | "needs" | "only" | "parallel" | "release" | "resource_group" | "retry" | "rules" | "script" | "services" | "stage" | "tags" | "trigger" | "variables"> {
     stage: JobTemplate["stage"];
@@ -23,8 +50,9 @@ export interface GitlabJobDef extends Pick<JobTemplate, "after_script" | "allow_
 export interface GitlabPipeline extends Pick<JobTemplate, "variables"> {
     image: string;
     workflow?: {
-        rules: GitlabRule[];
         name?: string;
+        auto_cancel?: GitlabAutoCancel;
+        rules: GitlabWorkflowRule[];
         variables?: Record<string, string>;
     };
     stages: string[];

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

@@ -33,6 +33,10 @@ const config = {
   appName: "my-app",
   customerName: "pan",
   pipelines: { gitlab: true, github: true }, // which CI systems to generate
+  environments: {              // optional: project-wide env declarations/tuning
+    review: { autoStop: "3 days" },
+    next: { type: "dev", on: { branch: "next" } }, // extra branch-tracking env
+  },
   components: {
     www: {
       dir: "frontend",          // working directory of this component
@@ -59,8 +63,36 @@ Key concepts:
 - **Environments**: `dev` (deployed on push to the main branch),
   `review` (per merge/pull request), `stage` and `prod` (deployed on
   tagged releases), `local` (only for local development via catenv).
-  Per-env overrides live under `env.<name>` and can override vars,
-  deploy settings, and more.
+  Environments are project-wide: the top-level `environments` config
+  declares and tunes them consistently for all components, while
+  per-component `env.<name>` entries only carry component-local
+  overrides (vars, deploy settings, host, autoStop) or `false` to opt
+  the component out. In `environments`:
+  - `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"`
+    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
+    last deploy before gitlab stops it (e.g. `"3 days"`; `false`
+    disables). Defaults: review `"1 week"`, dev `"4 weeks"`, others
+    never. GitLab only — github review apps stop when their PR closes.
+    Components can override it per env (`env.<name>.autoStop`).
+  - Extra envs are declared with any name plus a `type` — the env type
+    acts as a preset: it supplies all defaults (trigger, autoStop,
+    deploy policy) and the env's identity for tooling (`ENV_TYPE`),
+    everything overridable. Every component deploys to a declared env
+    unless it opts out:
+    `environments: { next: { type: "dev", on: { branch: "next" } } }`.
+  - `inherit` — make an env inherit from another env:
+    `inherit: "dev"` gives it dev's per-component config overrides
+    (merged below its own; `host` and `type` never inherit, the env
+    type is implied from the inherited env) AND dev's secret values —
+    all-or-nothing: its jobs reference dev's `CL_DEV_*` variables and
+    it has no secret store of its own (manage secrets via dev; rotating
+    affects both). The object form separates the axes:
+    `inherit: { config: "dev" }` inherits config only,
+    `inherit: { config: "dev", secrets: "dev" }` both.
 - **Pipelines**: `pipelines: { gitlab: true, github: true }` selects
   which CI systems get generated files. Options objects instead of
   `true` allow per-pipeline settings (e.g. `runnerVariables`,

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

@@ -78,6 +78,11 @@ Everything app-level lives under `values`:
   completion jobs, and always-on background worker pools.
 - `cloudSql` — attach an (unmanaged) CloudSQL instance; choose the
   connection-string format (`prisma` default, `rails`, `jdbc`).
+  `deleteDatabaseOnStop` controls whether the database is dropped when
+  the environment stops (default: true for review envs, false else).
+- `revisionsToKeep` — how many inactive revisions (the rollback
+  history) the post-deploy cleanup keeps; older revisions and their
+  images are deleted. Default: 5 on prod envs, 0 everywhere else.
 - `execute` — run a script/job/HTTP call at a deploy lifecycle point
   (`preDeploy`/`postDeploy`/`preStop`/`postStop`) or on a `schedule`.
   Prefer this over the deprecated `when`/`schedule` fields on `jobs`.

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

@@ -11,11 +11,20 @@ generated YAML.
 
 ## Triggers and environments
 
-| Trigger | Runs on | Deploys to |
+| Trigger | Runs on | Deploys to (default) |
 |---|---|---|
 | `mainBranch` | push to the main branch | `dev` |
 | `mr` | merge/pull requests | `review` (one app per MR/PR) |
 | `taggedRelease` | git tags | `stage`, `prod` |
+| `{ branch: "<name>" }` | push to that branch | envs declaring it via `on` |
+
+The trigger of each env is its `on` in the top-level `environments`
+config (project-wide — components cannot diverge), defaulting from the
+env type as in the table. An env with `on: { branch: "next" }` gets its
+own pipeline (gitlab: rules on `$CI_COMMIT_BRANCH`; github: a
+`catladder-branch-<name>.yml` workflow) and deploys as one stable,
+branch-tracking environment — unlike review apps, it is not
+per-instance and is stopped via the manual stop job/workflow.
 
 Generated layout:
 
@@ -37,6 +46,38 @@ Generated layout:
 Stages: setup → test → build → deploy → verify (post-deploy checks),
 plus stop jobs for review-app teardown.
 
+## Superseded pipelines are cancelled
+
+Pushing a new commit cancels the pipeline of the previous one, so the
+runners are not busy with results nobody will read.
+
+| Pipeline | On a new commit |
+|---|---|
+| `mr` | cancelled |
+| `mainBranch` (dev) | cancelled, except a release already running |
+| `taggedRelease` | **runs through** — never cancelled |
+| agent runs (`trigger`) | **runs through** — never cancelled |
+
+- **GitHub**: the generated MR workflow sets `concurrency` with
+  `cancel-in-progress: true`.
+- **GitLab**: generated `workflow:auto_cancel:on_new_commit:
+  interruptible`, with per-rule `none` for tags and agent runs. Every
+  job carries an explicit `interruptible`, jobs that must finish
+  (release jobs, agent jobs) carry `interruptible: false`.
+
+**GitLab requires the project setting too.** The generated YAML only
+tunes *how* redundant pipelines are cancelled — it does not switch the
+feature on. If old pipelines keep running, check **Settings > CI/CD >
+General pipelines > Auto-cancel redundant pipelines**; with that
+checkbox off nothing is ever cancelled. (`catladder project-doctor`
+does not check this.)
+
+**Adding a hand-written GitLab job?** Set `interruptible` explicitly.
+GitLab defaults it to `false`, and a non-interruptible job that has
+started keeps *itself* alive — under gitlab's own default
+(`conservative`, which catladder overrides) it would shield the whole
+pipeline from cancellation.
+
 ## Review-app auto-stop and pinning (GitLab)
 
 GitLab review environments stop automatically after 1 week, dev

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

@@ -38,6 +38,12 @@ files in the repo. All secrets commands accept a **scope**:
 `dev:web` (one env of one component), `dev:` (one env, all
 components), `:web` (all envs of one component), or nothing (everything).
 
+An env that shares another env's secrets (top-level
+`environments.<name>.inherit`, e.g. a `next` branch env inheriting from
+dev) has **no secret store of its own** — its jobs reference the source
+env's variables directly, so it never appears in secrets scopes: manage
+(and rotate) the values via the source env, which affects both.
+
 Check what is declared and what is still unset (never prints values
 unless `--reveal` is passed):