@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/includes/envrc

@@ -1,5 +1,5 @@
 # adjust this file to your needs
-# find a current recommended version here: https://git.panter.ch/panter/catladder2/-/blob/master/includes/envrc
+# find a current recommended version here: https://github.com/panter/catladder/blob/main/apps/cli/includes/envrc
 
 # if catladder is available, invoke that
 if hash catladder 2>/dev/null; then

package/package.json

@@ -2,13 +2,13 @@
   "name": "@catladder/cli",
   "description": "Panter cli tool for cloud CI/CD and DevOps",
   "author": "Marco Wettstein <maw@panter.ch>",
-  "homepage": "https://catladder.git.panter.biz/catladder/docs",
-  "bugs": "https://git.panter.ch/catladder/catladder/issues",
-  "readme": "https://git.panter.ch/catladder/catladder/-/blob/main/cli/README.md",
+  "homepage": "https://panter.github.io/catladder/docs",
+  "bugs": "https://github.com/panter/catladder/issues",
+  "readme": "https://github.com/panter/catladder/blob/main/apps/cli/README.md",
   "repository": {
     "type": "git",
-    "url": "git+https://git.panter.ch/catladder/catladder.git",
-    "directory": "cli"
+    "url": "git+https://github.com/panter/catladder.git",
+    "directory": "apps/cli"
   },
   "keywords": [
     "GitLab",
@@ -53,35 +53,39 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-main-8dbb6c76",
+  "version": "0.0.0-main-a6b45abe",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",
-    "test": "yarn run lint",
-    "build": "yarn build:compile && yarn build:inline-variables && yarn build:bundle",
-    "build:inline-variables": "yarn babel --keep-file-extension --extensions \".ts,.js\" --config-file ./babel-inline.json dist --out-dir dist",
+    "test": "pnpm run lint",
+    "build": "pnpm run build:compile && pnpm run build:bundle && pnpm run build:copy-images && pnpm run build:skill-cli-reference && pnpm run build:copy-skills",
     "build:bundle": "./scripts/bundle",
-    "build:compile": "yarn tsc && yarn tsc-alias",
-    "dev:own-catenv": "cd ../ && node cli/bin/catenv-dev",
-    "build:watch": "tsc-watch --onSuccess \"yarn dev:own-catenv\""
+    "build:copy-images": "rm -rf dist/runner-images dist/bundles/runner-images && cp -R ../../runner-images dist/runner-images && cp -R ../../runner-images dist/bundles/runner-images",
+    "build:copy-skills": "rm -rf dist/skills dist/bundles/skills && cp -R ../../skills dist/skills && cp -R ../../skills dist/bundles/skills",
+    "build:skill-cli-reference": "tsx src/scripts/generateCliSkillReference.ts",
+    "build:compile": "tsc && tsc-alias",
+    "dev:own-catenv": "cd ../../ && node apps/cli/bin/catenv-dev",
+    "build:watch": "tsc-watch --onSuccess \"pnpm run dev:own-catenv\""
   },
   "bin": {
     "catenv": "./bin/catenv",
     "catladder": "./bin/catladder"
   },
-  "types": "dist/cli/src/index.d.ts",
-  "main": "dist/cli/src/index.js",
+  "types": "dist/apps/cli/src/index.d.ts",
+  "main": "dist/apps/cli/src/index.js",
   "engines": {
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.29.0",
-    "@babel/plugin-syntax-typescript": "^7.28.6",
+    "@catladder/bash": "workspace:*",
+    "@catladder/pipeline": "workspace:*",
+    "@changesets/parse": "^0.4.3",
+    "@gitbeaker/core": "^39.28.0",
     "@gitbeaker/rest": "^39.28.0",
     "@inquirer/prompts": "^8.4.3",
     "@kubernetes/client-node": "^0.16.2",
     "@tsconfig/node14": "^1.0.1",
+    "@types/child-process-promise": "^2.2.6",
     "@types/common-tags": "^1.8.4",
     "@types/fs-extra": "^5.0.4",
     "@types/lodash-es": "^4.17.12",
@@ -92,7 +96,6 @@
     "@types/update-notifier": "^2.5.0",
     "@types/websocket": "^0.0.40",
     "@types/yargs": "^17.0.33",
-    "babel-plugin-transform-inline-environment-variables": "^0.4.4",
     "child-process-promise": "^2.2.1",
     "clipboardy": "^2.0.0",
     "command-exists-promise": "^2.0.2",
@@ -101,20 +104,23 @@
     "connection-string-parser": "^1.0.4",
     "date-fns": "^3.6.0",
     "fs-extra": "^7.0.1",
+    "jiti": "^2.7.0",
     "lodash-es": "^4.18.1",
     "memoizee": "^0.4.17",
     "node-fetch": "^2.3.0",
     "open": "^8.4.0",
+    "path-equal": "1.2.5",
     "prettier": "^3.3.3",
+    "slugify": "^1.6.6",
     "tmp-promise": "^2.0.2",
     "ts-results-es": "^4.2.0",
     "tsc-alias": "^1.8.16",
     "tsc-watch": "^7.2.0",
     "typescript": "^5.4.5",
-    "yaml": "^2.5.0"
+    "yaml": "^2.5.0",
+    "zod": "^4.4.3"
   },
   "dependencies": {
     "tsx": "^4.21.0"
-  },
-  "stableVersion": "0.0.0"
+  }
 }

package/scripts/bundle

@@ -1,4 +1,8 @@
 #!/bin/bash
-ncc build dist/cli/src/catenv.js -o dist/bundles/catenv $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
+ncc build dist/apps/cli/src/catenv.js -o dist/bundles/catenv $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
 
-ncc build dist/cli/src/cli.js -o dist/bundles/cli $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
+ncc build dist/apps/cli/src/cli.js -o dist/bundles/cli $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
+
+# catci: minimal CI companion, materialized into .catladder-generated by
+# pipeline generation (always minified — it is committed to consumer repos)
+ncc build dist/apps/cli/src/catci.js -o dist/bundles/catci -m --no-source-map-register

package/src/adapters/baseContext.ts

@@ -6,6 +6,8 @@ import type {
   InputsSchema,
   OptionalInput,
 } from "../core/types";
+import type { VaultManager } from "../vault/VaultManager";
+import { createVaultManagerGetter } from "./vaultManagerAccess";
 
 /**
  * Base class for CommandContext implementations.
@@ -19,9 +21,17 @@ export abstract class BaseContext<TInputs extends InputsSchema>
 
   constructor(protected readonly command: CommandDef<TInputs>) {}
 
+  abstract readonly interactive: boolean;
+
   abstract log(message: string): void;
   abstract confirm(message: string): Promise<boolean>;
 
+  private readonly vaultManagerGetter = createVaultManagerGetter(() => this);
+
+  getVaultManager(): Promise<VaultManager> {
+    return this.vaultManagerGetter();
+  }
+
   /**
    * Resolve a single input value. Called once per input (result is cached).
    * Implementations check pre-supplied values, prompt interactively, use defaults, or throw.

package/src/adapters/nonInteractive.ts

@@ -0,0 +1,30 @@
+import type { IO } from "../core/types";
+import { NonInteractiveError } from "../core/types";
+import type { SecretsMode } from "../vault";
+import { createVaultManagerGetter } from "./vaultManagerAccess";
+
+/**
+ * the context of non-interactive runs (catenv via direnv): logging
+ * goes to stderr, any required interaction fails with a clear error.
+ */
+export function createNonInteractiveIO(
+  options: { vaultMode?: SecretsMode } = {},
+): IO {
+  const io: IO = {
+    interactive: false,
+    getVaultManager: createVaultManagerGetter(() => io, {
+      mode: options.vaultMode,
+    }),
+    log(message: string): void {
+      // stderr: stdout may be evaluated (direnv)
+      console.error(message);
+    },
+    async confirm(message: string): Promise<boolean> {
+      throw new NonInteractiveError(`confirmation ("${message}")`);
+    },
+    async promptDirect(spec): Promise<never> {
+      throw new NonInteractiveError(`input "${spec.name}"`);
+    },
+  };
+  return io;
+}

package/src/adapters/programmatic.ts

@@ -7,6 +7,7 @@ import type {
 } from "../core/types";
 import { MissingInputError } from "../core/types";
 import { BaseContext } from "./baseContext";
+import { createVaultManagerGetter } from "./vaultManagerAccess";
 
 export interface ProgrammaticOptions {
   /** Pre-supplied values keyed by input name */
@@ -21,6 +22,8 @@ class ProgrammaticContext<
   private inputs: Record<string, unknown>;
   private onLog?: (message: string) => void;
 
+  readonly interactive = false;
+
   constructor(command: CommandDef<TInputs>, options: ProgrammaticOptions) {
     super(command);
     this.inputs = options.inputs ?? {};
@@ -66,7 +69,9 @@ export function createProgrammaticContext<TInputs extends InputsSchema>(
 export function createProgrammaticIO(options: ProgrammaticOptions = {}): IO {
   const { inputs = {}, onLog } = options;
 
-  return {
+  const io: IO = {
+    interactive: false,
+    getVaultManager: createVaultManagerGetter(() => io),
     log(message: string): void {
       onLog?.(message);
     },
@@ -85,4 +90,5 @@ export function createProgrammaticIO(options: ProgrammaticOptions = {}): IO {
       throw new MissingInputError(spec.name, spec.message);
     },
   };
+  return io;
 }

package/src/adapters/terminal.ts

@@ -7,7 +7,9 @@ import type {
   PromptChoice,
 } from "../core/types";
 import { MissingInputError } from "../core/types";
+import type { SecretsMode } from "../vault";
 import { BaseContext } from "./baseContext";
+import { createVaultManagerGetter } from "./vaultManagerAccess";
 
 /**
  * Resolve choices from a choices function.
@@ -81,6 +83,13 @@ export interface TerminalOptions {
   interactive?: boolean;
   /** If true, all confirm() calls return true without prompting (--yes flag) */
   yes?: boolean;
+  /**
+   * log to stderr instead of stdout (catenv: stdout may be evaluated
+   * by direnv or piped, so only data belongs there)
+   */
+  logToStderr?: boolean;
+  /** how to interact with the secrets vault (--vault-mode) */
+  vaultMode?: SecretsMode;
 }
 
 class TerminalContext<
@@ -93,6 +102,10 @@ class TerminalContext<
     super(command);
   }
 
+  get interactive(): boolean {
+    return this.options.interactive ?? process.stdin.isTTY === true;
+  }
+
   log(message: string): void {
     console.log(message);
   }
@@ -180,9 +193,17 @@ export function createTerminalContext<TInputs extends InputsSchema>(
  * Create a bare IO instance for terminal helper functions.
  */
 export function createTerminalIO(options: TerminalOptions = {}): IO {
-  return {
+  const io: IO = {
+    interactive: options.interactive ?? process.stdin.isTTY === true,
+    getVaultManager: createVaultManagerGetter(() => io, {
+      mode: options.vaultMode,
+    }),
     log(message: string): void {
-      console.log(message);
+      if (options.logToStderr) {
+        console.error(message);
+      } else {
+        console.log(message);
+      }
     },
     async confirm(message: string): Promise<boolean> {
       if (options.yes) return true;
@@ -204,4 +225,5 @@ export function createTerminalIO(options: TerminalOptions = {}): IO {
       throw new MissingInputError(spec.name, spec.message);
     },
   };
+  return io;
 }

package/src/adapters/vaultManagerAccess.ts

@@ -0,0 +1,25 @@
+import { getProjectConfig } from "../config/getProjectConfig";
+import type { IO } from "../core/types";
+import type { VaultManagerOptions } from "../vault/VaultManager";
+import { VaultManager } from "../vault/VaultManager";
+
+/**
+ * lazily creates the vault manager of a context (once per context),
+ * loading the project config on first use
+ */
+export const createVaultManagerGetter = (
+  io: () => IO,
+  options: Omit<VaultManagerOptions, "io"> = {},
+): (() => Promise<VaultManager>) => {
+  let managerPromise: Promise<VaultManager> | undefined;
+  return () =>
+    (managerPromise ??= (async () => {
+      const config = await getProjectConfig();
+      if (!config) {
+        throw new Error(
+          "no catladder config found — the secrets vault needs a project config",
+        );
+      }
+      return new VaultManager(config, { ...options, io: io() });
+    })());
+};

package/src/apps/catenv/catenv.ts

@@ -8,10 +8,19 @@ import {
   createCatenvContext,
   generatePipelineFiles,
 } from "@catladder/pipeline";
+import type { SecretsMode } from "../../vault";
+import { createNonInteractiveIO } from "../../adapters/nonInteractive";
+import { createTerminalIO } from "../../adapters/terminal";
 
 type Options = {
   verbose?: boolean;
   printVariables?: boolean;
+  vaultMode?: SecretsMode;
+  /**
+   * whether prompting is allowed (token setup, vault unlock). Callers
+   * pass the TTY detection result; direnv/turbo/CI runs come out false.
+   */
+  interactive?: boolean;
 };
 export default async (choice?: Choice, options?: Options) => {
   const config = await getProjectConfig();
@@ -19,13 +28,22 @@ export default async (choice?: Choice, options?: Options) => {
     return;
   }
 
-  const context = createCatenvContext(config);
+  const io = options?.interactive
+    ? // logs still go to stderr: even on a TTY, stdout is reserved for
+      // data (--print-variables) and may be piped
+      createTerminalIO({
+        interactive: true,
+        logToStderr: true,
+        vaultMode: options?.vaultMode,
+      })
+    : createNonInteractiveIO({ vaultMode: options?.vaultMode });
+  const context = { ...createCatenvContext(config), io };
   if (options?.verbose) {
     printVerboseBanner();
   }
 
   await Promise.all([
-    generatePipelineFiles(context, config.pipelineType ?? "gitlab"),
+    generatePipelineFiles(context),
     writeDotEnvFiles(context, choice),
 
     writeDTsFiles(context, choice),

package/src/apps/catenv/printVariables.ts

@@ -1,4 +1,6 @@
-import type { CatenvContext, Config } from "@catladder/pipeline";
+import type { Config } from "@catladder/pipeline";
+import type { IO } from "../../core/types";
+import type { CatenvCliContext } from "./types";
 import { getEnvVarsResolved } from "../../config/getProjectConfig";
 import type { Choice } from "./types";
 import {
@@ -7,21 +9,25 @@ import {
   sanitizeEnvVarName,
 } from "./utils";
 
-const getAllVariablesToPrint = async (config: Config, choice?: Choice) => {
+const getAllVariablesToPrint = async (
+  io: IO,
+  config: Config,
+  choice?: Choice,
+) => {
   const { env, currentComponent } = await getCurrentComponentAndEnvFromChoice(
     config,
     choice,
   );
 
   if (currentComponent) {
-    return await getEnvVarsResolved(null, env, currentComponent);
+    return await getEnvVarsResolved(io, env, currentComponent);
   } else {
     // when in a monorep and not in a subapp, merge all env vars.
     // this is not 100% correct, but better than not exporting any vars at all
     // so we also add prefixed variants
     return await Object.keys(config.components).reduce(
       async (acc, componentName) => {
-        const subappvars = await getEnvVarsResolved(null, env, componentName);
+        const subappvars = await getEnvVarsResolved(io, env, componentName);
         delete subappvars["_ALL_ENV_VAR_KEYS"];
         return {
           ...(await acc),
@@ -41,10 +47,14 @@ const getAllVariablesToPrint = async (config: Config, choice?: Choice) => {
 };
 
 export const printVariables = async (
-  context: CatenvContext,
+  context: CatenvCliContext,
   choice?: Choice,
 ) => {
-  const variables = await getAllVariablesToPrint(context.config, choice);
+  const variables = await getAllVariablesToPrint(
+    context.io,
+    context.config,
+    choice,
+  );
 
   console.log(makeExportKeyValuestring(variables));
 };

package/src/apps/catenv/types.ts

@@ -1,3 +1,12 @@
+import type { CatenvContext } from "@catladder/pipeline";
+import type { IO } from "../../core/types";
+
+/**
+ * the pipeline's catenv context extended with the cli io context
+ * (non-interactive when run via direnv)
+ */
+export type CatenvCliContext = CatenvContext & { io: IO };
+
 import type { VariableValue } from "@catladder/pipeline";
 
 export type Choice = {

package/src/apps/catenv/writeDotEnvFiles.ts

@@ -7,10 +7,10 @@ import {
   getCurrentComponentAndEnvFromChoice,
   makeKeyValueString,
 } from "./utils";
-import type { CatenvContext } from "@catladder/pipeline";
+import type { CatenvCliContext } from "./types";
 
 export const writeDotEnvFiles = async (
-  context: CatenvContext,
+  context: CatenvCliContext,
   choice?: Choice,
 ) => {
   const { env, currentComponent } = await getCurrentComponentAndEnvFromChoice(
@@ -32,7 +32,7 @@ export const writeDotEnvFiles = async (
   const gitRoot = await getGitRoot();
 
   for (const componentName of componentsToActuallyWriteDotEnvNow) {
-    const variables = await getEnvVarsResolved(null, env, componentName);
+    const variables = await getEnvVarsResolved(context.io, env, componentName);
     delete variables["_ALL_ENV_VAR_KEYS"];
     const componentDir = getComponentFullPath(
       gitRoot,

package/src/apps/cli/commands/project/doctor/DoctorReport.ts

@@ -0,0 +1,72 @@
+import type { IO } from "../../../../../core/types";
+
+type Finding = {
+  section: string;
+  message: string;
+  remediation?: string;
+};
+
+/**
+ * collects the results of all doctor checks: each check logs
+ * immediately (progressive output like `project setup`) and problems
+ * are repeated in the final summary together with the command that
+ * heals them. The report itself never mutates anything — doctor
+ * diagnoses, setup heals.
+ */
+export class DoctorReport {
+  private passed = 0;
+  private readonly warnings: Finding[] = [];
+  private readonly problems: Finding[] = [];
+  private currentSection = "";
+
+  constructor(private readonly io: IO) {}
+
+  section(title: string) {
+    this.currentSection = title;
+    this.io.log("");
+    this.io.log("🩺 " + title);
+  }
+
+  ok(message: string) {
+    this.passed++;
+    this.io.log("  ✅ " + message);
+  }
+
+  warn(message: string, remediation?: string) {
+    this.warnings.push({ section: this.currentSection, message, remediation });
+    this.io.log("  ⚠️ " + message);
+    if (remediation) this.io.log("     ↳ " + remediation);
+  }
+
+  fail(message: string, remediation?: string) {
+    this.problems.push({ section: this.currentSection, message, remediation });
+    this.io.log("  ❌ " + message);
+    if (remediation) this.io.log("     ↳ " + remediation);
+  }
+
+  get hasProblems(): boolean {
+    return this.problems.length > 0;
+  }
+
+  summarize() {
+    const { io } = this;
+    io.log("");
+    io.log(
+      "==================================================================================",
+    );
+    io.log(
+      `🩺 doctor summary: ${this.passed} checks passed, ` +
+        `${this.warnings.length} warnings, ${this.problems.length} problems`,
+    );
+    if (!this.hasProblems) {
+      io.log("");
+      io.log("everything looks healthy 😻");
+      return;
+    }
+    io.log("");
+    for (const { section, message, remediation } of this.problems) {
+      io.log(`❌ [${section}] ${message}`);
+      if (remediation) io.log(`   ↳ ${remediation}`);
+    }
+  }
+}

package/src/apps/cli/commands/project/doctor/GcloudProjectInspector.ts

@@ -0,0 +1,77 @@
+import { exec } from "child-process-promise";
+import { CATLADDER_REGISTRY_NAME } from "../../../../../gcloud/artifactsRegistry";
+
+type IamBinding = { role: string; members?: string[] };
+
+/**
+ * read-only gcloud queries for the doctor, cached per project: checking
+ * many component/env contexts of the same gcloud project costs one
+ * `get-iam-policy` / `services list` call, not one per context
+ */
+export class GcloudProjectInspector {
+  private readonly iamBindings = new Map<string, Promise<IamBinding[]>>();
+  private readonly enabledServices = new Map<string, Promise<Set<string>>>();
+
+  async isAuthenticated(): Promise<boolean> {
+    try {
+      await exec("gcloud auth print-access-token");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private getIamBindings(projectId: string): Promise<IamBinding[]> {
+    if (!this.iamBindings.has(projectId)) {
+      this.iamBindings.set(
+        projectId,
+        exec(`gcloud projects get-iam-policy ${projectId} --format=json`).then(
+          (result) => JSON.parse(result.stdout).bindings ?? [],
+        ),
+      );
+    }
+    return this.iamBindings.get(projectId)!;
+  }
+
+  /** all roles bound to the given member (e.g. "serviceAccount:<email>") */
+  async getRolesOfMember(projectId: string, member: string): Promise<string[]> {
+    const bindings = await this.getIamBindings(projectId);
+    return bindings
+      .filter((binding) => binding.members?.includes(member))
+      .map((binding) => binding.role);
+  }
+
+  getEnabledServices(projectId: string): Promise<Set<string>> {
+    if (!this.enabledServices.has(projectId)) {
+      this.enabledServices.set(
+        projectId,
+        exec(
+          `gcloud services list --enabled --project=${projectId} --format="value(config.name)"`,
+        ).then(
+          (result) =>
+            new Set(
+              result.stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean),
+            ),
+        ),
+      );
+    }
+    return this.enabledServices.get(projectId)!;
+  }
+
+  async hasArtifactsRegistry(
+    projectId: string,
+    region: string,
+  ): Promise<boolean> {
+    try {
+      await exec(
+        `gcloud artifacts repositories describe ${CATLADDER_REGISTRY_NAME} --project="${projectId}" --location=${region}`,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}