@catladder/cli 0.0.0-next-e9e5af68 → 0.0.0-next-1c65899f

package/dist/pipeline/src/variables/VariableValueContainingReferences.js

@@ -1,63 +1,69 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.createVariableValueContainingReferencesFromString = exports.VariableValueContainingReferences = exports.VariableReference = exports.UnresolvableReference = void 0;
 const BashExpression_1 = require("../bash/BashExpression");
 const bashEscape_1 = require("../bash/bashEscape");
 class UnresolvableReference {
-  constructor(reference) {
-    this.reference = reference;
-  }
-  toString() {
-    return `Unresolvable reference: ${this.reference.toString()}`;
-  }
+    constructor(reference) {
+        this.reference = reference;
+    }
+    toString() {
+        return `Unresolvable reference: ${this.reference.toString()}`;
+    }
 }
 exports.UnresolvableReference = UnresolvableReference;
 class VariableReference {
-  constructor(componentName, variableName) {
-    this.componentName = componentName;
-    this.variableName = variableName;
-  }
-  toString() {
-    return `\${${this.componentName}:${this.variableName}}`;
-  }
+    constructor(componentName, variableName) {
+        this.componentName = componentName;
+        this.variableName = variableName;
+    }
+    toString() {
+        return `\${${this.componentName}:${this.variableName}}`;
+    }
 }
 exports.VariableReference = VariableReference;
 class VariableValueContainingReferences {
-  constructor(parts) {
-    this.parts = (Array.isArray(parts) ? parts : [parts]).flatMap(part => part instanceof VariableValueContainingReferences ? part.parts : part === "" ? [] : [part]);
-  }
-  toString(options = {
-    quotes: false
-  }) {
-    return this.parts.map(part => {
-      if (typeof part === "string") {
-        return (0, bashEscape_1.escapeString)(part, options);
-      } else if (part instanceof BashExpression_1.BashExpression) {
-        return (0, bashEscape_1.escapeBashExpression)(part, options);
-      } else {
-        return part.toString();
-      }
-    }).join("");
-  }
+    constructor(parts) {
+        this.parts = (Array.isArray(parts) ? parts : [parts]).flatMap((part) => part instanceof VariableValueContainingReferences
+            ? part.parts
+            : part === ""
+                ? []
+                : [part]);
+    }
+    toString(options = {
+        quotes: false,
+    }) {
+        return this.parts
+            .map((part) => {
+            if (typeof part === "string") {
+                return (0, bashEscape_1.escapeString)(part, options);
+            }
+            else if (part instanceof BashExpression_1.BashExpression) {
+                return (0, bashEscape_1.escapeBashExpression)(part, options);
+            }
+            else {
+                return part.toString();
+            }
+        })
+            .join("");
+    }
 }
 exports.VariableValueContainingReferences = VariableValueContainingReferences;
 // regex to resolve references in catladder variables
 // those expressions have the pattern ${componentName:variableName}
 const REGEX = /\$\{(([^:}]+):)?([^}]+)}/gm;
 const createVariableValueContainingReferencesFromString = (value, options) => {
-  const parts = [];
-  let match;
-  let lastIndex = 0;
-  while ((match = REGEX.exec(value)) !== null) {
-    const [fullMatch, _, otherComponentName, variableName] = match;
-    parts.push(value.slice(lastIndex, match.index));
-    parts.push(new VariableReference(otherComponentName || options.componentName, variableName));
-    lastIndex = REGEX.lastIndex;
-  }
-  parts.push(value.slice(lastIndex));
-  return new VariableValueContainingReferences(parts);
+    const parts = [];
+    let match;
+    let lastIndex = 0;
+    while ((match = REGEX.exec(value)) !== null) {
+        const [fullMatch, _, otherComponentName, variableName] = match;
+        parts.push(value.slice(lastIndex, match.index));
+        parts.push(new VariableReference(otherComponentName || options.componentName, variableName));
+        lastIndex = REGEX.lastIndex;
+    }
+    parts.push(value.slice(lastIndex));
+    return new VariableValueContainingReferences(parts);
 };
-exports.createVariableValueContainingReferencesFromString = createVariableValueContainingReferencesFromString;
+exports.createVariableValueContainingReferencesFromString = createVariableValueContainingReferencesFromString;
+//# sourceMappingURL=VariableValueContainingReferences.js.map

package/dist/pipeline/src/variables/resolveAllReferences.d.ts

@@ -1,3 +1,3 @@
 import type { VariableValue } from "./VariableValue";
 import type { VariableValueContainingReferences } from "./VariableValueContainingReferences";
-export declare const resolveAllReferences: (values: Record<string, VariableValueContainingReferences>, getEnvVars: (componentName: string) => Promise<Record<string, VariableValue | null | undefined>>) => Promise<Record<string, VariableValueContainingReferences>>;
+export declare const resolveAllReferences: (values: Record<string, VariableValueContainingReferences>, getEnvVars: (componentName: string) => Promise<Record<string, VariableValue | null | undefined>>) => Promise<Record<string, VariableValueContainingReferences>>;

package/dist/pipeline/src/variables/resolveAllReferences.js

@@ -1,24 +1,25 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAllReferences = void 0;
 const VariableValueContainingReferences_1 = require("./VariableValueContainingReferences");
 const resolveAllReferencesOnce_1 = require("./resolveAllReferencesOnce");
 const resolveAllReferences = async (values, getEnvVars) => {
-  // replace until there aren't any references left
-  let result = values;
-  let i = 0;
-  while (Object.values(result).some(value => value.parts.some(part => part instanceof VariableValueContainingReferences_1.VariableReference))) {
-    const replaced = await (0, resolveAllReferencesOnce_1.resolveAllReferencesOnce)(result, getEnvVars);
-    result = replaced;
-    i++;
-    if (i > 1000) {
-      const unresolved = Object.entries(result).filter(([key, value]) => value.parts.some(part => part instanceof VariableValueContainingReferences_1.VariableReference));
-      throw new Error("Infinite loop detected in these variables: " + unresolved.map(([key, value]) => `${key} (last reference: ${value.parts.find(part => part instanceof VariableValueContainingReferences_1.VariableReference)})`).join(", "));
+    // replace until there aren't any references left
+    let result = values;
+    let i = 0;
+    while (Object.values(result).some((value) => value.parts.some((part) => part instanceof VariableValueContainingReferences_1.VariableReference))) {
+        const replaced = await (0, resolveAllReferencesOnce_1.resolveAllReferencesOnce)(result, getEnvVars);
+        result = replaced;
+        i++;
+        if (i > 1000) {
+            const unresolved = Object.entries(result).filter(([key, value]) => value.parts.some((part) => part instanceof VariableValueContainingReferences_1.VariableReference));
+            throw new Error("Infinite loop detected in these variables: " +
+                unresolved
+                    .map(([key, value]) => `${key} (last reference: ${value.parts.find((part) => part instanceof VariableValueContainingReferences_1.VariableReference)})`)
+                    .join(", "));
+        }
     }
-  }
-  return result;
+    return result;
 };
-exports.resolveAllReferences = resolveAllReferences;
+exports.resolveAllReferences = resolveAllReferences;
+//# sourceMappingURL=resolveAllReferences.js.map

package/dist/pipeline/src/variables/resolveAllReferencesOnce.d.ts

@@ -1,5 +1,5 @@
 import type { VariableValue } from "./VariableValue";
 import type { VariableValueContainingReferences } from "./VariableValueContainingReferences";
 export declare const resolveAllReferencesOnce: (values: Record<string, VariableValueContainingReferences>, getEnvVars: (componentName: string) => Promise<Record<string, VariableValue | undefined | null>>) => Promise<{
-  [k: string]: VariableValueContainingReferences;
-}>;
+    [k: string]: VariableValueContainingReferences;
+}>;

package/dist/pipeline/src/variables/resolveAllReferencesOnce.js

@@ -1,20 +1,23 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAllReferencesOnce = void 0;
 const VariableValueContainingReferences_1 = require("./VariableValueContainingReferences");
 const resolveReferencesOnce_1 = require("./resolveReferencesOnce");
 const resolveAllReferencesOnce = async (values, getEnvVars) => {
-  const allReferences = Object.values(values).flatMap(value => value === null || value === void 0 ? void 0 : value.parts.filter(part => part instanceof VariableValueContainingReferences_1.VariableReference));
-  const allComponentsUnique = Array.from(new Set(allReferences.map(reference => reference.componentName)));
-  const allEnvVarsInComponents = Object.fromEntries(await Promise.all(allComponentsUnique.map(async componentName => [componentName, await getEnvVars(componentName)])));
-  return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, value !== null && value !== undefined ? (0, resolveReferencesOnce_1.resolveReferencesOnce)(value, ({
-    componentName,
-    variableName
-  }) => {
-    return allEnvVarsInComponents[componentName][variableName];
-  }) : value]));
+    const allReferences = Object.values(values).flatMap((value) => value === null || value === void 0 ? void 0 : value.parts.filter((part) => part instanceof VariableValueContainingReferences_1.VariableReference));
+    const allComponentsUnique = Array.from(new Set(allReferences.map((reference) => reference.componentName)));
+    const allEnvVarsInComponents = Object.fromEntries(await Promise.all(allComponentsUnique.map(async (componentName) => [
+        componentName,
+        await getEnvVars(componentName),
+    ])));
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [
+        key,
+        value !== null && value !== undefined
+            ? (0, resolveReferencesOnce_1.resolveReferencesOnce)(value, ({ componentName, variableName }) => {
+                return allEnvVarsInComponents[componentName][variableName];
+            })
+            : value,
+    ]));
 };
-exports.resolveAllReferencesOnce = resolveAllReferencesOnce;
+exports.resolveAllReferencesOnce = resolveAllReferencesOnce;
+//# sourceMappingURL=resolveAllReferencesOnce.js.map

package/dist/pipeline/src/variables/resolveReferencesOnce.d.ts

@@ -1,8 +1,8 @@
 import type { VariableValue } from "./VariableValue";
 import { VariableValueContainingReferences } from "./VariableValueContainingReferences";
 type Resolver = (args: {
-  componentName: string;
-  variableName: string;
+    componentName: string;
+    variableName: string;
 }) => VariableValue | null | undefined;
 export declare const resolveReferencesOnce: (value: VariableValueContainingReferences, resolver: Resolver) => VariableValueContainingReferences;
-export {};
+export {};

package/dist/pipeline/src/variables/resolveReferencesOnce.js

@@ -1,22 +1,21 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveReferencesOnce = void 0;
 const VariableValueContainingReferences_1 = require("./VariableValueContainingReferences");
 const resolveReferencesOnce = (value, resolver) => {
-  const replacedParts = value.parts.map(part => {
-    if (part instanceof VariableValueContainingReferences_1.VariableReference) {
-      const result = resolver({
-        componentName: part.componentName,
-        variableName: part.variableName
-      });
-      return result !== null && result !== void 0 ? result : new VariableValueContainingReferences_1.UnresolvableReference(part);
-    } else {
-      return part;
-    }
-  });
-  return new VariableValueContainingReferences_1.VariableValueContainingReferences(replacedParts);
+    const replacedParts = value.parts.map((part) => {
+        if (part instanceof VariableValueContainingReferences_1.VariableReference) {
+            const result = resolver({
+                componentName: part.componentName,
+                variableName: part.variableName,
+            });
+            return result !== null && result !== void 0 ? result : new VariableValueContainingReferences_1.UnresolvableReference(part);
+        }
+        else {
+            return part;
+        }
+    });
+    return new VariableValueContainingReferences_1.VariableValueContainingReferences(replacedParts);
 };
-exports.resolveReferencesOnce = resolveReferencesOnce;
+exports.resolveReferencesOnce = resolveReferencesOnce;
+//# sourceMappingURL=resolveReferencesOnce.js.map

package/dist/pipeline/src/verify/createVerifyJobs.d.ts

@@ -1,4 +1,4 @@
 import type { ComponentContext } from "../types/context";
 import type { CatladderJob } from "../types/jobs";
 export declare const VERIFY_JOB_NAME = "\uD83D\uDD0D verify";
-export declare const createVerifyJobs: (context: ComponentContext) => Promise<CatladderJob[]>;
+export declare const createVerifyJobs: (context: ComponentContext) => Promise<CatladderJob[]>;

package/dist/pipeline/src/verify/createVerifyJobs.js

@@ -1,8 +1,5 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.createVerifyJobs = exports.VERIFY_JOB_NAME = void 0;
 const createArtifactsConfig_1 = require("../build/base/createArtifactsConfig");
 const cache_1 = require("../build/node/cache");
@@ -12,55 +9,65 @@ const deploy_1 = require("../deploy");
 const runner_1 = require("../runner");
 const utils_1 = require("../utils");
 exports.VERIFY_JOB_NAME = "🔍 verify";
-const createVerifyJobs = async context => {
-  var _a, _b, _c, _d, _e, _f, _g;
-  const verifyConfig = context.componentConfig.verify;
-  if (!verifyConfig) {
-    return [];
-  }
-  const deployConfig = (_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config;
-  if (!deployConfig) {
-    // nothing is deployed, so there is nothing to verify
-    return [];
-  }
-  const isNodeBuild = context.build.type !== "disabled" && context.build.buildType === "node";
-  const [yarnInstall, nodeCache] = isNodeBuild ? await Promise.all([(0, yarn_1.getYarnInstall)(context), (0, cache_1.getNodeCache)(context, "pull")]) : [null, null];
-  const setupScript = (_d = (_c = (_b = deploy_1.DEPLOY_TYPES[deployConfig.type]).verifyJobSetupScript) === null || _c === void 0 ? void 0 : _c.call(_b, context)) !== null && _d !== void 0 ? _d : [];
-  return [{
-    name: exports.VERIFY_JOB_NAME,
-    stage: "verify",
-    envMode: "stagePerEnv",
-    requires: [
-    // wait for this component's own deploy
-    {
-      capability: "deployment",
-      artifacts: false
-    },
-    // ...and for the deploys of the components listed in waitFor
-    ...((_e = verifyConfig.waitFor) !== null && _e !== void 0 ? _e : []).map(componentName => ({
-      capability: "deployment",
-      from: {
-        component: componentName
-      },
-      artifacts: false,
-      strict: true
-    }))],
-    image: (_f = verifyConfig.jobImage) !== null && _f !== void 0 ? _f : (0, runner_1.getRunnerImage)("jobs-testing-chrome"),
-    // neutral cache declarations — each backend lowers them itself
-    // (gitlab strips the github-only hint keys, github builds cache
-    // restore steps). Pre-lowering via createJobCacheFromCacheConfigs
-    // would leak the hints into the gitlab yaml, which rejects them.
-    caches: nodeCache !== null && nodeCache !== void 0 ? nodeCache : undefined,
-    variables: {
-      ...context.environment.envVars
-    },
-    runnerVariables: {
-      ...constants_1.NODE_RUNNER_BUILD_VARIABLES,
-      ...((_g = verifyConfig.runnerVariables) !== null && _g !== void 0 ? _g : {})
-    },
-    script: [...setupScript, ...(yarnInstall ? (0, yarn_1.ensureNodeVersion)(context) : []), `cd ${context.build.dir}`, ...(yarnInstall !== null && yarnInstall !== void 0 ? yarnInstall : []), ...(0, utils_1.ensureArray)(verifyConfig.command)],
-    allow_failure: verifyConfig.allowFailure,
-    ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, verifyConfig.artifactsReports, verifyConfig.artifacts)
-  }];
+const createVerifyJobs = async (context) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const verifyConfig = context.componentConfig.verify;
+    if (!verifyConfig) {
+        return [];
+    }
+    const deployConfig = (_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config;
+    if (!deployConfig) {
+        // nothing is deployed, so there is nothing to verify
+        return [];
+    }
+    const isNodeBuild = context.build.type !== "disabled" && context.build.buildType === "node";
+    const [yarnInstall, nodeCache] = isNodeBuild
+        ? await Promise.all([
+            (0, yarn_1.getYarnInstall)(context),
+            (0, cache_1.getNodeCache)(context, "pull"),
+        ])
+        : [null, null];
+    const setupScript = (_d = (_c = (_b = deploy_1.DEPLOY_TYPES[deployConfig.type]).verifyJobSetupScript) === null || _c === void 0 ? void 0 : _c.call(_b, context)) !== null && _d !== void 0 ? _d : [];
+    return [
+        {
+            name: exports.VERIFY_JOB_NAME,
+            stage: "verify",
+            envMode: "stagePerEnv",
+            requires: [
+                // wait for this component's own deploy
+                { capability: "deployment", artifacts: false },
+                // ...and for the deploys of the components listed in waitFor
+                ...((_e = verifyConfig.waitFor) !== null && _e !== void 0 ? _e : []).map((componentName) => ({
+                    capability: "deployment",
+                    from: { component: componentName },
+                    artifacts: false,
+                    strict: true,
+                })),
+            ],
+            image: (_f = verifyConfig.jobImage) !== null && _f !== void 0 ? _f : (0, runner_1.getRunnerImage)("jobs-testing-chrome"),
+            // neutral cache declarations — each backend lowers them itself
+            // (gitlab strips the github-only hint keys, github builds cache
+            // restore steps). Pre-lowering via createJobCacheFromCacheConfigs
+            // would leak the hints into the gitlab yaml, which rejects them.
+            caches: nodeCache !== null && nodeCache !== void 0 ? nodeCache : undefined,
+            variables: {
+                ...context.environment.envVars,
+            },
+            runnerVariables: {
+                ...constants_1.NODE_RUNNER_BUILD_VARIABLES,
+                ...((_g = verifyConfig.runnerVariables) !== null && _g !== void 0 ? _g : {}),
+            },
+            script: [
+                ...setupScript,
+                ...(yarnInstall ? (0, yarn_1.ensureNodeVersion)(context) : []),
+                `cd ${context.build.dir}`,
+                ...(yarnInstall !== null && yarnInstall !== void 0 ? yarnInstall : []),
+                ...(0, utils_1.ensureArray)(verifyConfig.command),
+            ],
+            allow_failure: verifyConfig.allowFailure,
+            ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, verifyConfig.artifactsReports, verifyConfig.artifacts),
+        },
+    ];
 };
-exports.createVerifyJobs = createVerifyJobs;
+exports.createVerifyJobs = createVerifyJobs;
+//# sourceMappingURL=createVerifyJobs.js.map

package/dist/pipeline/src/verify/index.d.ts

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

package/dist/pipeline/src/verify/index.js

@@ -1,26 +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);
+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
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
-__exportStar(require("./createVerifyJobs"), exports);
+__exportStar(require("./createVerifyJobs"), exports);
+//# sourceMappingURL=index.js.map

package/dist/pipeline/src/verify/types.d.ts

@@ -3,14 +3,14 @@ import type { TestJobCustom } from "../build/types";
  * post-deploy verification job configuration
  */
 export type VerifyConfig = TestJobCustom & {
-  /**
-   * command(s) to run against the deployed environment (e.g. `yarn e2e`).
-   * Runs in the component's directory.
-   */
-  command: string | string[];
-  /**
-   * names of other components whose deploy must finish before this verify job runs
-   * (in addition to this component's own deploy, which is always awaited)
-   */
-  waitFor?: string[];
-};
+    /**
+     * command(s) to run against the deployed environment (e.g. `yarn e2e`).
+     * Runs in the component's directory.
+     */
+    command: string | string[];
+    /**
+     * names of other components whose deploy must finish before this verify job runs
+     * (in addition to this component's own deploy, which is always awaited)
+     */
+    waitFor?: string[];
+};

package/dist/pipeline/src/verify/types.js

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

package/dist/skills/catladder-cli/references/commands.md

@@ -107,9 +107,10 @@ restores a project db from one source to another target
 
 ## `catladder project config-secrets [envComponent]`
 
-setup/update secrets stored in pass
+setup/update secrets in the vault via your editor
 
-- `envComponent` (positional): environment:component
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only edit these secrets (comma-separated keys)
 
 ## `catladder project doctor [component]`
 
@@ -226,6 +227,40 @@ clears all backups
 
 - `--keep <value>`: How many backups should we keep? (default: 1)
 
+## `catladder project secrets-list [envComponent]`
+
+lists the declared secrets of a scope with their set/unset status (values only with --reveal)
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--reveal`: also print the secret values (default: false)
+- `--check`: exit with an error when any secret is unset (for CI/agents) (default: false)
+
+## `catladder project secrets-pull [envComponent]`
+
+prints the current secrets of a scope as yaml (unset ones as a placeholder) — edit and feed to secrets-push
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--out <value>`: write the yaml to this file instead of stdout
+
+## `catladder project secrets-push [envComponent]`
+
+writes secrets from a yaml document (secrets-pull format, --file or stdin) to the vault; may be partial
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only write these secrets (comma-separated keys)
+- `--file <value>`: yaml file to push (component → env → key: value); stdin when omitted
+
+## `catladder project secrets-set [envComponent] [key]`
+
+sets one secret — in one env (dev:web), one env everywhere (dev:), or all envs of a component (:web); value via --value, --value-file or stdin
+
+- `envComponent` (positional): scope: env:component, env:, or :component
+- `key` (positional): which secret?
+- `--value <value>`: the secret value (prefer --value-file or stdin over shell history)
+- `--value-file <value>`: read the secret value from this file
+
 ## `catladder project secrets-sync-github [repo] [env]`
 
 copies all secrets from the vault to github repo secrets (same names), for the github pipeline

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

@@ -29,12 +29,12 @@ plus stop jobs for review-app teardown.
 
 ## Job images and catci
 
-Jobs run in catladder-provided images. With `jobImages: "repo"`, image
-definitions are materialized into `.catladder-generated/images/` and
-built in the project's own registry (content-hashed, rebuilt only on
-change). `.catladder-generated/catci/` holds a small bundled CI
-companion used by generated jobs (e.g. the release security audit) —
-all generated, never edit.
+Jobs run in catladder-provided images. Their definitions are
+materialized into `.catladder-generated/images/` and built in the
+project's own registry (content-hashed, rebuilt only on change).
+`.catladder-generated/catci/` holds a small bundled CI companion used by
+generated jobs (e.g. the release security audit) — all generated, never
+edit.
 
 ## Caching
 

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

@@ -1,6 +1,6 @@
 ---
 name: catladder-secrets
-description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set or rotated, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets".
+description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set, rotated or checked, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets", "secrets-set", "secrets-list", "rotate a secret", "set a secret".
 ---
 
 # Env vars and secrets with catladder
@@ -34,18 +34,51 @@ commit.
 ## Setting secret values
 
 Secret values are managed through the catladder CLI — never by editing
-files in the repo:
+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).
+
+Check what is declared and what is still unset (never prints values
+unless `--reveal` is passed):
+
+```sh
+yarn catladder project secrets-list
+yarn catladder project secrets-list --check   # non-zero exit when something is unset
+```
+
+Set a single secret (the usual case — also for rotating one value
+across all envs via the `:component` scope):
+
+```sh
+echo -n "the-value" | yarn catladder project secrets-set dev:web API_KEY
+yarn catladder project secrets-set :web API_KEY --value-file /path/to/value
+```
+
+Prefer stdin or `--value-file` over `--value` so values stay out of
+shell history. **Never pass a real secret value you found in the
+conversation without the user having provided it for this purpose.**
+
+Bulk-edit several secrets as a YAML document
+(`component → env → key: value`):
 
 ```sh
-yarn catladder project config-secrets
+yarn catladder project secrets-pull dev: --out /tmp/secrets.yml   # unset ones appear as "🚨 FILL ME"
+# edit the file, then:
+yarn catladder project secrets-push dev: --file /tmp/secrets.yml  # partial docs are fine
 ```
 
-This opens all env vars as YAML in `$EDITOR` (use e.g.
-`EDITOR="code --wait"`); on save, catladder upserts the changed values
-into the secrets vault. **An agent cannot drive this interactive
-editor** — when a new secret *value* is needed, add the name to
-`vars.secret`, regenerate, and ask the user to run
-`project config-secrets` themselves.
+`secrets-push` skips placeholder/empty values, rejects undeclared
+keys, and may be partial — only the provided keys are written. Both
+support `--key KEY1,KEY2` to narrow further. Delete the temp file
+afterwards; never commit it.
+
+Humans may instead use the interactive editor flow
+(`project config-secrets`, opens `$EDITOR`); as an agent, use the
+commands above.
+
+All of these write to the secrets vault (the source of truth) and
+automatically mirror to the enabled CI backends — which vault is
+configured makes no difference to the commands.
 
 ## GitHub pipelines