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

package/dist/bundles/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/bundles/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/bundles/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
 

package/dist/cli/src/adapters/baseContext.d.ts

@@ -6,21 +6,21 @@ import type { VaultManager } from "../vault/VaultManager";
  * Subclasses only implement the adapter-specific resolution logic.
  */
 export declare abstract class BaseContext<TInputs extends InputsSchema> implements CommandContext<TInputs> {
-  protected readonly command: CommandDef<TInputs>;
-  private cache;
-  constructor(command: CommandDef<TInputs>);
-  abstract readonly interactive: boolean;
-  abstract log(message: string): void;
-  abstract confirm(message: string): Promise<boolean>;
-  private readonly vaultManagerGetter;
-  getVaultManager(): Promise<VaultManager>;
-  /**
-   * Resolve a single input value. Called once per input (result is cached).
-   * Implementations check pre-supplied values, prompt interactively, use defaults, or throw.
-   */
-  protected abstract resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
-  get<K extends keyof TInputs & string>(name: K): Promise<OptionalInput<TInputs[K]>>;
-  promptDirect<P extends InputDef>(spec: P & {
-    name: string;
-  }): Promise<InputResultType<P>>;
-}
+    protected readonly command: CommandDef<TInputs>;
+    private cache;
+    constructor(command: CommandDef<TInputs>);
+    abstract readonly interactive: boolean;
+    abstract log(message: string): void;
+    abstract confirm(message: string): Promise<boolean>;
+    private readonly vaultManagerGetter;
+    getVaultManager(): Promise<VaultManager>;
+    /**
+     * Resolve a single input value. Called once per input (result is cached).
+     * Implementations check pre-supplied values, prompt interactively, use defaults, or throw.
+     */
+    protected abstract resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
+    get<K extends keyof TInputs & string>(name: K): Promise<OptionalInput<TInputs[K]>>;
+    promptDirect<P extends InputDef>(spec: P & {
+        name: string;
+    }): Promise<InputResultType<P>>;
+}

package/dist/cli/src/adapters/baseContext.js

@@ -1,8 +1,5 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseContext = void 0;
 const vaultManagerAccess_1 = require("./vaultManagerAccess");
 /**
@@ -11,35 +8,38 @@ const vaultManagerAccess_1 = require("./vaultManagerAccess");
  * Subclasses only implement the adapter-specific resolution logic.
  */
 class BaseContext {
-  constructor(command) {
-    this.command = command;
-    this.cache = new Map();
-    this.vaultManagerGetter = (0, vaultManagerAccess_1.createVaultManagerGetter)(() => this);
-  }
-  getVaultManager() {
-    return this.vaultManagerGetter();
-  }
-  get(name) {
-    if (!this.cache.has(name)) {
-      const spec = this.command.inputs[name];
-      if (!spec) {
-        return Promise.reject(new Error(`Input "${name}" is not declared in command "${this.command.name}"`));
-      }
-      // For optional inputs (required: false), catch MissingInputError
-      // and return undefined instead of prompting
-      if (spec.required === false) {
-        this.cache.set(name, this.resolveInput(name, spec).catch(err => {
-          if ((err === null || err === void 0 ? void 0 : err.name) === "MissingInputError") return undefined;
-          throw err;
-        }));
-      } else {
-        this.cache.set(name, this.resolveInput(name, spec));
-      }
+    constructor(command) {
+        this.command = command;
+        this.cache = new Map();
+        this.vaultManagerGetter = (0, vaultManagerAccess_1.createVaultManagerGetter)(() => this);
+    }
+    getVaultManager() {
+        return this.vaultManagerGetter();
+    }
+    get(name) {
+        if (!this.cache.has(name)) {
+            const spec = this.command.inputs[name];
+            if (!spec) {
+                return Promise.reject(new Error(`Input "${name}" is not declared in command "${this.command.name}"`));
+            }
+            // For optional inputs (required: false), catch MissingInputError
+            // and return undefined instead of prompting
+            if (spec.required === false) {
+                this.cache.set(name, this.resolveInput(name, spec).catch((err) => {
+                    if ((err === null || err === void 0 ? void 0 : err.name) === "MissingInputError")
+                        return undefined;
+                    throw err;
+                }));
+            }
+            else {
+                this.cache.set(name, this.resolveInput(name, spec));
+            }
+        }
+        return this.cache.get(name);
+    }
+    async promptDirect(spec) {
+        return this.resolveInput(spec.name, spec);
     }
-    return this.cache.get(name);
-  }
-  async promptDirect(spec) {
-    return this.resolveInput(spec.name, spec);
-  }
 }
-exports.BaseContext = BaseContext;
+exports.BaseContext = BaseContext;
+//# sourceMappingURL=baseContext.js.map

package/dist/cli/src/adapters/nonInteractive.d.ts

@@ -5,5 +5,5 @@ import type { SecretsMode } from "../vault";
  * goes to stderr, any required interaction fails with a clear error.
  */
 export declare function createNonInteractiveIO(options?: {
-  vaultMode?: SecretsMode;
-}): IO;
+    vaultMode?: SecretsMode;
+}): IO;

package/dist/cli/src/adapters/nonInteractive.js

@@ -1,8 +1,5 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNonInteractiveIO = void 0;
 const types_1 = require("../core/types");
 const vaultManagerAccess_1 = require("./vaultManagerAccess");
@@ -11,22 +8,23 @@ const vaultManagerAccess_1 = require("./vaultManagerAccess");
  * goes to stderr, any required interaction fails with a clear error.
  */
 function createNonInteractiveIO(options = {}) {
-  const io = {
-    interactive: false,
-    getVaultManager: (0, vaultManagerAccess_1.createVaultManagerGetter)(() => io, {
-      mode: options.vaultMode
-    }),
-    log(message) {
-      // stderr: stdout may be evaluated (direnv)
-      console.error(message);
-    },
-    async confirm(message) {
-      throw new types_1.NonInteractiveError(`confirmation ("${message}")`);
-    },
-    async promptDirect(spec) {
-      throw new types_1.NonInteractiveError(`input "${spec.name}"`);
-    }
-  };
-  return io;
+    const io = {
+        interactive: false,
+        getVaultManager: (0, vaultManagerAccess_1.createVaultManagerGetter)(() => io, {
+            mode: options.vaultMode,
+        }),
+        log(message) {
+            // stderr: stdout may be evaluated (direnv)
+            console.error(message);
+        },
+        async confirm(message) {
+            throw new types_1.NonInteractiveError(`confirmation ("${message}")`);
+        },
+        async promptDirect(spec) {
+            throw new types_1.NonInteractiveError(`input "${spec.name}"`);
+        },
+    };
+    return io;
 }
-exports.createNonInteractiveIO = createNonInteractiveIO;
+exports.createNonInteractiveIO = createNonInteractiveIO;
+//# sourceMappingURL=nonInteractive.js.map

package/dist/cli/src/adapters/programmatic.d.ts

@@ -1,19 +1,19 @@
 import type { CommandDef, IO, InputDef, InputResultType, InputsSchema } from "../core/types";
 import { BaseContext } from "./baseContext";
 export interface ProgrammaticOptions {
-  /** Pre-supplied values keyed by input name */
-  inputs?: Record<string, unknown>;
-  /** Called on every log message. Defaults to no-op. */
-  onLog?: (message: string) => void;
+    /** Pre-supplied values keyed by input name */
+    inputs?: Record<string, unknown>;
+    /** Called on every log message. Defaults to no-op. */
+    onLog?: (message: string) => void;
 }
 declare class ProgrammaticContext<TInputs extends InputsSchema> extends BaseContext<TInputs> {
-  private inputs;
-  private onLog?;
-  readonly interactive = false;
-  constructor(command: CommandDef<TInputs>, options: ProgrammaticOptions);
-  log(message: string): void;
-  confirm(): Promise<boolean>;
-  protected resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
+    private inputs;
+    private onLog?;
+    readonly interactive = false;
+    constructor(command: CommandDef<TInputs>, options: ProgrammaticOptions);
+    log(message: string): void;
+    confirm(): Promise<boolean>;
+    protected resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
 }
 /**
  * Create a CommandContext that resolves inputs from pre-supplied values.
@@ -24,4 +24,4 @@ export declare function createProgrammaticContext<TInputs extends InputsSchema>(
  * Create a bare IO instance for helper functions that only need log + promptDirect.
  */
 export declare function createProgrammaticIO(options?: ProgrammaticOptions): IO;
-export {};
+export {};

package/dist/cli/src/adapters/programmatic.js

@@ -1,72 +1,67 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.createProgrammaticIO = exports.createProgrammaticContext = void 0;
 const types_1 = require("../core/types");
 const baseContext_1 = require("./baseContext");
 const vaultManagerAccess_1 = require("./vaultManagerAccess");
 class ProgrammaticContext extends baseContext_1.BaseContext {
-  constructor(command, options) {
-    var _a;
-    super(command);
-    this.interactive = false;
-    this.inputs = (_a = options.inputs) !== null && _a !== void 0 ? _a : {};
-    this.onLog = options.onLog;
-  }
-  log(message) {
-    var _a;
-    (_a = this.onLog) === null || _a === void 0 ? void 0 : _a.call(this, message);
-  }
-  async confirm() {
-    return true; // programmatic mode always confirms
-  }
-  async resolveInput(name, spec) {
-    if (name in this.inputs && this.inputs[name] !== undefined) {
-      return this.inputs[name];
+    constructor(command, options) {
+        var _a;
+        super(command);
+        this.interactive = false;
+        this.inputs = (_a = options.inputs) !== null && _a !== void 0 ? _a : {};
+        this.onLog = options.onLog;
     }
-    if ("default" in spec && spec.default !== undefined) {
-      return spec.default;
+    log(message) {
+        var _a;
+        (_a = this.onLog) === null || _a === void 0 ? void 0 : _a.call(this, message);
+    }
+    async confirm() {
+        return true; // programmatic mode always confirms
+    }
+    async resolveInput(name, spec) {
+        if (name in this.inputs && this.inputs[name] !== undefined) {
+            return this.inputs[name];
+        }
+        if ("default" in spec && spec.default !== undefined) {
+            return spec.default;
+        }
+        throw new types_1.MissingInputError(name, spec.message);
     }
-    throw new types_1.MissingInputError(name, spec.message);
-  }
 }
 /**
  * Create a CommandContext that resolves inputs from pre-supplied values.
  * Used for non-interactive CLI mode and programmatic invocation.
  */
 function createProgrammaticContext(command, options = {}) {
-  return new ProgrammaticContext(command, options);
+    return new ProgrammaticContext(command, options);
 }
 exports.createProgrammaticContext = createProgrammaticContext;
 /**
  * Create a bare IO instance for helper functions that only need log + promptDirect.
  */
 function createProgrammaticIO(options = {}) {
-  const {
-    inputs = {},
-    onLog
-  } = options;
-  const io = {
-    interactive: false,
-    getVaultManager: (0, vaultManagerAccess_1.createVaultManagerGetter)(() => io),
-    log(message) {
-      onLog === null || onLog === void 0 ? void 0 : onLog(message);
-    },
-    async confirm() {
-      return true;
-    },
-    async promptDirect(spec) {
-      if (spec.name in inputs && inputs[spec.name] !== undefined) {
-        return inputs[spec.name];
-      }
-      if ("default" in spec && spec.default !== undefined) {
-        return spec.default;
-      }
-      throw new types_1.MissingInputError(spec.name, spec.message);
-    }
-  };
-  return io;
+    const { inputs = {}, onLog } = options;
+    const io = {
+        interactive: false,
+        getVaultManager: (0, vaultManagerAccess_1.createVaultManagerGetter)(() => io),
+        log(message) {
+            onLog === null || onLog === void 0 ? void 0 : onLog(message);
+        },
+        async confirm() {
+            return true;
+        },
+        async promptDirect(spec) {
+            if (spec.name in inputs && inputs[spec.name] !== undefined) {
+                return inputs[spec.name];
+            }
+            if ("default" in spec && spec.default !== undefined) {
+                return spec.default;
+            }
+            throw new types_1.MissingInputError(spec.name, spec.message);
+        },
+    };
+    return io;
 }
-exports.createProgrammaticIO = createProgrammaticIO;
+exports.createProgrammaticIO = createProgrammaticIO;
+//# sourceMappingURL=programmatic.js.map

package/dist/cli/src/adapters/terminal.d.ts

@@ -1,22 +1,22 @@
 import type { CommandDef, IO, InputDef, InputResultType, InputsSchema } from "../core/types";
 import { BaseContext } from "./baseContext";
 export interface TerminalOptions {
-  /** Pre-supplied values from CLI flags/positional args, keyed by input name */
-  cliOptions?: Record<string, unknown>;
-  /** Pre-supplied values from --inputs JSON flag */
-  jsonInputs?: Record<string, unknown>;
-  /** Whether interactive prompts are allowed (default: auto-detect from TTY) */
-  interactive?: boolean;
-  /** If true, all confirm() calls return true without prompting (--yes flag) */
-  yes?: boolean;
+    /** Pre-supplied values from CLI flags/positional args, keyed by input name */
+    cliOptions?: Record<string, unknown>;
+    /** Pre-supplied values from --inputs JSON flag */
+    jsonInputs?: Record<string, unknown>;
+    /** Whether interactive prompts are allowed (default: auto-detect from TTY) */
+    interactive?: boolean;
+    /** If true, all confirm() calls return true without prompting (--yes flag) */
+    yes?: boolean;
 }
 declare class TerminalContext<TInputs extends InputsSchema> extends BaseContext<TInputs> {
-  private options;
-  constructor(command: CommandDef<TInputs>, options: TerminalOptions);
-  get interactive(): boolean;
-  log(message: string): void;
-  confirm(message: string): Promise<boolean>;
-  protected resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
+    private options;
+    constructor(command: CommandDef<TInputs>, options: TerminalOptions);
+    get interactive(): boolean;
+    log(message: string): void;
+    confirm(message: string): Promise<boolean>;
+    protected resolveInput<P extends InputDef>(name: string, spec: P): Promise<InputResultType<P>>;
 }
 /**
  * Create a CommandContext for terminal usage.
@@ -26,4 +26,4 @@ export declare function createTerminalContext<TInputs extends InputsSchema>(comm
  * Create a bare IO instance for terminal helper functions.
  */
 export declare function createTerminalIO(options?: TerminalOptions): IO;
-export {};
+export {};