@catladder/cli 5.4.1 → 5.5.0

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/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

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

@@ -11,12 +11,12 @@ generated YAML.
 
 ## Triggers and environments
 
-| 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` |
+| 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
@@ -25,6 +25,9 @@ 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.
+`on: false` keeps an env out of every pipeline but the env still exists
+(setup, secrets, catenv); `environments: { <name>: false }` removes it
+entirely.
 
 Generated layout:
 
@@ -34,12 +37,12 @@ Generated layout:
   "generated by catladder" header; others are unmanaged). Manual
   actions are per-kind `workflow_dispatch` workflows, visually grouped
   by their emoji prefix in the Actions sidebar: `🚀 catladder create
-  release`, `▶️ catladder deploy` (manual-gated deploys), `🛑 catladder
-  stop`, `↩️ catladder rollback` — when all of a kind's tasks target one
+release`, `▶️ catladder deploy` (manual-gated deploys), `🛑 catladder
+stop`, `↩️ catladder rollback` — when all of a kind's tasks target one
   env the name carries it (e.g. `▶️ catladder deploy prod`); otherwise
   pick the task from the workflow's dropdown. Review apps are stopped
   automatically when their pull request closes (`🛑 catladder stop
-  review app`); the same workflow can be dispatched with a PR number to
+review app`); the same workflow can be dispatched with a PR number to
   tear one down while the pull request is still open (gitlab runs these as manual jobs inside the pipeline
   instead).
 
@@ -51,22 +54,22 @@ plus stop jobs for review-app teardown.
 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 |
+| 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
+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
+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`
@@ -74,7 +77,7 @@ 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
+started keeps _itself_ alive — under gitlab's own default
 (`conservative`, which catladder overrides) it would shield the whole
 pipeline from cancellation.