@catladder/cli 5.2.0 → 5.3.0

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

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):