@catladder/cli 3.48.0 → 4.0.0

package/src/apps/cli/commands/project/setup/setupCloudRun.ts

@@ -5,7 +5,7 @@ import {
   isOfDeployType,
 } from "@catladder/pipeline";
 
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../../../../../core/types";
 import { upsertGcloudArtifactsRegistry } from "../../../../../gcloud/artifactsRegistry";
 import { getCloudRunDomainSuffix } from "../../../../../gcloud/cloudRun/getCloudRunDomainSuffix";
 import { enableGCloudServices } from "../../../../../gcloud/enableServices";
@@ -13,7 +13,7 @@ import { upsertGcloudServiceAccountAndSaveSecret } from "../../../../../gcloud/s
 import { upsertAllVariables } from "../../../../../utils/gitlab";
 
 export const setupCloudRun = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
 ) => {
   if (!isOfDeployType(context.deploy?.config, "google-cloudrun")) {

package/src/apps/cli/commands/project/setup/setupContext.ts

@@ -1,15 +1,12 @@
 import type { ComponentContext } from "@catladder/pipeline";
 import { isOfDeployType } from "@catladder/pipeline";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../../../../../core/types";
 import { setupCloudRun } from "./setupCloudRun";
 
 import { setupKubernetes } from "./setupKubernetes";
 import { logSection } from "./logSection";
 
-export const setupContext = async (
-  instance: CommandInstance,
-  context: ComponentContext,
-) => {
+export const setupContext = async (instance: IO, context: ComponentContext) => {
   await logSection(
     instance,
     "setting up " + context.env + ":" + context.name,

package/src/apps/cli/commands/project/setup/setupKubernetes.ts

@@ -3,7 +3,7 @@ import {
   getFullKubernetesClusterName,
   isOfDeployType,
 } from "@catladder/pipeline";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../../../../../core/types";
 import { exec } from "child-process-promise";
 import { connectToCluster } from "../../../../../utils/cluster";
 import {
@@ -14,7 +14,7 @@ import {
 import ensureNamespace from "../utils/ensureNamespace";
 
 export const setupKubernetes = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
 ) => {
   const deployConfig = context.deploy?.config;

package/src/apps/cli/commands/project/setup/setupTopic.ts

@@ -1,9 +1,9 @@
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../../../../../core/types";
 import { doGitlabRequest, getProjectInfo } from "../../../../../utils/gitlab";
 
 const catladderTopic = "catladder";
 
-export const setupTopic = async (instance: CommandInstance) => {
+export const setupTopic = async (instance: IO) => {
   const { id: projectId } = await getProjectInfo(instance);
 
   const { topics } = await doGitlabRequest(instance, `projects/${projectId}`);

package/src/apps/cli/commands/project/utils/ensureCluster.ts

@@ -10,7 +10,19 @@ import {
   connectToCluster,
   getCurrentConnectedClusterName,
 } from "../../../../../utils/cluster";
-export default async function (envComponent: string) {
+import type { IO } from "../../../../../core/types";
+
+/**
+ * Ensures the user is connected to the correct Kubernetes cluster for the given envComponent.
+ * If already connected, does nothing. If not, prompts for confirmation to switch (in interactive mode).
+ *
+ * Accepts an IO instance for logging and prompting.
+ * Also works with Vorpal's CommandInstance via .call(this, envComponent) for backward compatibility.
+ */
+export async function ensureCluster(
+  io: IO,
+  envComponent: string,
+): Promise<void> {
   const { env, componentName } = parseChoice(envComponent);
   const context = await getPipelineContextByChoice(env, componentName);
   if (!isOfDeployType(context.deploy?.config, "kubernetes")) {
@@ -20,21 +32,16 @@ export default async function (envComponent: string) {
   const connectedClusterName = await getCurrentConnectedClusterName();
 
   if (cluster !== connectedClusterName) {
-    this.log(
-      `you are currently connected to cluster '${connectedClusterName}'`,
+    io.log(`you are currently connected to cluster '${connectedClusterName}'`);
+    io.log(`but the project requires cluster '${cluster}'`);
+    const shouldContinue = await io.confirm(
+      `Do you want to connect to '${cluster}'?`,
     );
-    this.log(`but the project requires cluster '${cluster}'`);
-    const { shouldContinue } = await this.prompt({
-      type: "confirm",
-      name: "shouldContinue",
-      default: true,
-      message: `Do you want to connect to '${cluster}'?`,
-    });
     if (!shouldContinue) {
-      this.log("abort");
+      io.log("abort");
     } else {
       await connectToCluster(cluster);
-      this.log(`connected to cluster '${cluster}'`);
+      io.log(`connected to cluster '${cluster}'`);
     }
   }
 }

package/src/apps/cli/utils/getGoogleAuthUserNumber.ts

@@ -1,3 +1,4 @@
+import type { IO } from "../../../core/types";
 import {
   getPreference,
   hasPreference,
@@ -5,16 +6,16 @@ import {
 } from "../../../utils/preferences";
 
 const KEY = "googleAuthUserNumber";
-export const getGoogleAuthUserNumber = async function () {
+export const getGoogleAuthUserNumber = async (io: IO) => {
   if (!(await hasPreference(KEY))) {
-    this.log(
+    io.log(
       "Please type in your google auth user number (0 if you have only one google account or maybe 1 if you have multiple)",
     );
 
-    const { authUserNumber } = await this.prompt({
+    const authUserNumber = await io.promptDirect({
       type: "number",
       name: "authUserNumber",
-      default: "0",
+      default: 0,
       message: "Auth user ",
     });
     await setPreference(KEY, authUserNumber);

package/src/catenv.ts

@@ -1,24 +1,30 @@
+import { Command } from "commander";
 import catenv from "./apps/catenv/catenv";
-
 import { parseChoice } from "./config/parseChoice";
+import packageInfos from "./packageInfos";
 
-const args = process.argv.slice(2);
+const program = new Command();
 
-const helpFlags = ["--help", "-h", "help"];
-if (args.some((arg) => helpFlags.includes(arg))) {
-  const docLink =
-    "https://git.panter.ch/catladder/catladder/-/blob/main/docs/1_VARS.md";
-  console.log(
-    `\nUsage: catenv [env|env:component] [-v|--verbose]\n\nEnv variable and catenv documentation:\n${docLink}`,
+program
+  .name("catenv")
+  .description("Environment variable and pipeline generation via direnv")
+  .version(packageInfos.version)
+  .argument("[envComponent]", "env or env:component")
+  .option("-v, --verbose", "verbose output")
+  .option("-p, --print-variables", "print variables")
+  .action(
+    (
+      envComponent: string | undefined,
+      opts: { verbose?: boolean; printVariables?: boolean },
+    ) => {
+      catenv(envComponent ? parseChoice(envComponent) : null, {
+        verbose: opts.verbose ?? false,
+        printVariables: opts.printVariables ?? false,
+      }).then(() => {
+        // we have to exit manually, because we have some file watches
+        process.exit();
+      });
+    },
   );
-  process.exit(0);
-}
-
-const verbose = args.some((arg) => arg === "-v" || arg === "--verbose");
-// choise arg is deprecated and will be removed in the future
-const choiceArg = args.find((arg) => arg !== "-v" && arg !== "--verbose");
 
-catenv(choiceArg ? parseChoice(choiceArg) : null, { verbose }).then(() => {
-  // we have to exit manually, because we have some file watches
-  process.exit();
-});
+program.parse();

package/src/cli.ts

@@ -1,3 +1,214 @@
-import cli from "./apps/cli/cli";
+import { Command } from "commander";
+import packageInfos from "./packageInfos";
+import { stopAllPortForwards } from "./utils/portForwards";
+import { createTerminalContext } from "./adapters/terminal";
+import type { CommandDef } from "./core/types";
+import {
+  getCompletions,
+  generateZshCompletionScript,
+  installCompletions,
+  uninstallCompletions,
+} from "./completion";
 
-cli();
+// Import all commands
+import * as commands from "./commands";
+
+const program = new Command();
+
+program
+  .name("catladder")
+  .description("Panter CLI tool for cloud CI/CD and DevOps")
+  .version(packageInfos.version)
+  .option("-y, --yes", "skip all confirmation prompts");
+
+// Collect all command defs for completion
+const allCommandDefs: CommandDef[] = [];
+
+// Cache for intermediate subcommand groups (e.g., "project", "project cloudsql")
+const subcommandCache = new Map<string, Command>();
+
+/**
+ * Get or create a chain of nested subcommands.
+ * E.g., for ["project", "cloudsql"], ensures program.command("project").command("cloudsql") exists.
+ */
+function getOrCreateParent(parts: string[]): Command {
+  if (parts.length === 0) return program;
+
+  const key = parts.join(" ");
+  if (subcommandCache.has(key)) return subcommandCache.get(key)!;
+
+  const parent = getOrCreateParent(parts.slice(0, -1));
+  const cmd = parent.command(parts[parts.length - 1]);
+  subcommandCache.set(key, cmd);
+  return cmd;
+}
+
+/**
+ * Register a CommandDef with Commander.js.
+ * - Command name can contain spaces for nesting (e.g., "project cloudsql proxy")
+ * - Inputs with `positional: true` become Commander positional args
+ * - Other inputs become optional --flags
+ * - --inputs accepts JSON for programmatic use
+ */
+function registerCommand(def: CommandDef): void {
+  allCommandDefs.push(def);
+
+  // Separate positional inputs from flag inputs
+  const positionalInputs: [string, (typeof def.inputs)[string]][] = [];
+  const flagInputs: [string, (typeof def.inputs)[string]][] = [];
+
+  for (const [name, inputDef] of Object.entries(def.inputs)) {
+    if (inputDef.positional) {
+      positionalInputs.push([name, inputDef]);
+    } else {
+      flagInputs.push([name, inputDef]);
+    }
+  }
+
+  // Split name into parent groups + leaf command
+  const nameParts = def.name.split(" ");
+  const parentParts = nameParts.slice(0, -1);
+  const leafName = nameParts[nameParts.length - 1];
+
+  // Build leaf command string with positional args
+  let cmdStr = leafName;
+  for (const [name] of positionalInputs) {
+    cmdStr += ` [${name}]`;
+  }
+
+  const parent = getOrCreateParent(parentParts);
+  const cmd = parent.command(cmdStr).description(def.description);
+
+  // Add --flag for each non-positional input
+  for (const [name, inputDef] of flagInputs) {
+    const flagName = name.replace(/([A-Z])/g, "-$1").toLowerCase();
+    const desc = inputDef.message.replace(/\s*🤔\s*$/, "").trim();
+    if (inputDef.type === "boolean") {
+      cmd.option(`--${flagName}`, desc);
+      cmd.option(`--no-${flagName}`, `negate: ${desc}`);
+    } else {
+      cmd.option(`--${flagName} <value>`, desc);
+    }
+  }
+
+  // Add --inputs for JSON input
+  cmd.option("--inputs <json>", "JSON object with input values");
+
+  cmd.action(async (...rawArgs: any[]) => {
+    // Commander passes positional args first, then options object, then the Command
+    const opts = rawArgs[rawArgs.length - 2];
+
+    // Parse positional args into cliOptions
+    const cliOptions: Record<string, unknown> = {};
+    positionalInputs.forEach(([name], i) => {
+      if (rawArgs[i] !== undefined) {
+        cliOptions[name] = rawArgs[i];
+      }
+    });
+
+    // Parse CLI flag overrides
+    for (const [name, inputDef] of flagInputs) {
+      const flagName = name.replace(/([A-Z])/g, "-$1").toLowerCase();
+      const camelName = flagName.replace(/-([a-z])/g, (_, c) =>
+        c.toUpperCase(),
+      );
+      if (opts[camelName] !== undefined) {
+        let value = opts[camelName];
+        if (inputDef.type === "number" && typeof value === "string") {
+          value = Number(value);
+        }
+        cliOptions[name] = value;
+      }
+    }
+
+    // Parse --inputs JSON
+    let jsonInputs: Record<string, unknown> = {};
+    if (opts.inputs) {
+      try {
+        jsonInputs = JSON.parse(opts.inputs);
+      } catch {
+        console.error("Error: --inputs must be valid JSON");
+        process.exit(1);
+      }
+    }
+
+    const ctx = createTerminalContext(def, {
+      cliOptions,
+      jsonInputs,
+      yes: program.opts().yes,
+    });
+
+    try {
+      await def.execute(ctx);
+    } catch (err: any) {
+      if (err.name === "MissingInputError") {
+        console.error(`\n${err.message}\n`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  });
+}
+
+// Register all commands
+for (const cmd of Object.values(commands)) {
+  if (cmd && typeof cmd === "object" && "name" in cmd && "execute" in cmd) {
+    registerCommand(cmd as CommandDef);
+  }
+}
+
+// Hidden __complete command for shell completion
+program
+  .command("__complete", { hidden: true })
+  .argument("[words]", "words typed so far")
+  .argument("[cursor]", "word at cursor")
+  .action(async (wordsStr: string | undefined, cursor: string | undefined) => {
+    const words = wordsStr ? wordsStr.split(" ").filter(Boolean) : [];
+    const cursorWord = cursor ?? "";
+    try {
+      const completions = await getCompletions(
+        allCommandDefs,
+        words,
+        cursorWord,
+      );
+      for (const c of completions) {
+        console.log(c);
+      }
+    } catch {
+      // Silently fail -- completion should never break the shell
+    }
+    process.exit(0);
+  });
+
+// completion commands
+const completionCmd = program
+  .command("completion")
+  .description("shell completion setup");
+
+completionCmd
+  .command("zsh")
+  .description("output zsh completion script")
+  .action(() => {
+    console.log(generateZshCompletionScript());
+  });
+
+completionCmd
+  .command("install")
+  .description("install shell completions into your .zshrc")
+  .action(async () => {
+    await installCompletions();
+  });
+
+completionCmd
+  .command("uninstall")
+  .description("remove shell completions from your .zshrc")
+  .action(async () => {
+    await uninstallCompletions();
+  });
+
+// Cleanup on exit
+process.on("exit", () => {
+  stopAllPortForwards();
+});
+
+program.parse();

package/src/commands/cloudSQL/commandRestoreDb.ts

@@ -0,0 +1,105 @@
+import { defineCommand } from "../../core/defineCommand";
+import { spawnCopyDb } from "../../gcloud/cloudSql/copyDb";
+import type { CloudSqlBackgroundProxy } from "../../gcloud/cloudSql/startProxy";
+import { startCloudSqlProxyInBackground } from "../../gcloud/cloudSql/startProxy";
+
+export const commandRestoreDb = defineCommand({
+  name: "cloudsql restore-db",
+  description: "restore a db from one source to another target",
+  group: "cloudSQL",
+  inputs: {
+    source: {
+      type: "string",
+      message: "Source instance (connection string or 'local')? 🤔 ",
+    },
+    sourceLocalPort: {
+      type: "number",
+      message: "Local Port for source? 🤔 ",
+      default: 5432,
+    },
+    sourceUsername: {
+      type: "string",
+      message: "Source Username? 🤔 ",
+      default: "postgres",
+    },
+    sourcePassword: { type: "string", message: "Source Password? 🤔 " },
+    sourceDbName: { type: "string", message: "Source DB name? 🤔 " },
+    target: {
+      type: "string",
+      message: "Target INSTANCE (connection string or 'local')? 🤔  ",
+    },
+    targetLocalPort: {
+      type: "number",
+      message: "Local Port for target? 🤔 ",
+      default: 5432,
+    },
+    targetUsername: {
+      type: "string",
+      message: "Target Username? 🤔 ",
+      default: "postgres",
+    },
+    targetPassword: { type: "string", message: "Target Password? 🤔 " },
+    targetDbName: { type: "string", message: "Target DB name? 🤔 " },
+  },
+  execute: async (ctx) => {
+    const source = await ctx.get("source");
+
+    let sourceProxy: CloudSqlBackgroundProxy;
+    let targetProxy: CloudSqlBackgroundProxy;
+    let sourcePort: number;
+    let targetPort: number;
+
+    if (source === "local") {
+      sourcePort = await ctx.get("sourceLocalPort");
+    } else {
+      sourcePort = 54399;
+      sourceProxy = await startCloudSqlProxyInBackground({
+        instanceName: source,
+        localPort: sourcePort,
+      });
+    }
+
+    const sourceUsername = await ctx.get("sourceUsername");
+    const sourcePassword = await ctx.get("sourcePassword");
+    const sourceDbName = await ctx.get("sourceDbName");
+
+    const target = await ctx.get("target");
+
+    if (target === "local") {
+      targetPort = await ctx.get("targetLocalPort");
+    } else {
+      targetPort = 54499;
+      targetProxy = await startCloudSqlProxyInBackground({
+        instanceName: target,
+        localPort: targetPort,
+      });
+    }
+
+    const targetUsername = await ctx.get("targetUsername");
+    const targetPassword = await ctx.get("targetPassword");
+    const targetDbName = await ctx.get("targetDbName");
+
+    const shouldContinue = await ctx.confirm(
+      `This will drop ${target}/${targetDbName} and replace it with ${source}/${sourceDbName}. Continue? 🤔 `,
+    );
+    if (!shouldContinue) {
+      return;
+    }
+
+    try {
+      await spawnCopyDb({
+        targetPassword,
+        targetPort,
+        targetUsername,
+        sourceUsername,
+        sourcePassword,
+        sourcePort,
+        sourceDbName,
+        targetDbName,
+      });
+    } finally {
+      sourceProxy?.stop();
+      targetProxy?.stop();
+    }
+  },
+});

package/src/commands/fun/commandDadjoke.ts

@@ -0,0 +1,18 @@
+import fetch from "node-fetch";
+import { defineCommand } from "../../core/defineCommand";
+
+export const commandDadjoke = defineCommand({
+  name: "fun dadjoke",
+  description: "something for jonas.",
+  group: "fun",
+  inputs: {},
+  execute: async (ctx) => {
+    const result = await fetch("https://icanhazdadjoke.com/", {
+      headers: { Accept: "text/plain" },
+    });
+    const text = await result.text();
+    ctx.log("");
+    ctx.log(text);
+    ctx.log("");
+  },
+});

package/src/commands/fun/commandStarwars.ts

@@ -0,0 +1,14 @@
+import { spawn } from "child-process-promise";
+import { defineCommand } from "../../core/defineCommand";
+
+export const commandStarwars = defineCommand({
+  name: "fun starwars",
+  description: "Long time ago... in a galaxy far far away...",
+  group: "fun",
+  inputs: {},
+  execute: async () => {
+    await spawn("nc", ["towel.blinkenlights.nl", "23"], {
+      stdio: ["pipe", "inherit", "pipe"],
+    });
+  },
+});

package/src/commands/general/commandKubeCurrentContext.ts

@@ -0,0 +1,12 @@
+import { defineCommand } from "../../core/defineCommand";
+import { getCurrentContext } from "../../utils/cluster";
+
+export const commandKubeCurrentContext = defineCommand({
+  name: "kube current-context",
+  description: "show current kubernetes context",
+  group: "general",
+  inputs: {},
+  execute: async (ctx) => {
+    ctx.log(await getCurrentContext());
+  },
+});

package/src/commands/general/commandKubeGetShell.ts

@@ -0,0 +1,32 @@
+import { defineCommand } from "../../core/defineCommand";
+import { getk8sApi } from "../../k8sApi";
+
+import { getShell } from "../../utils/shell";
+
+export const commandKubeGetShell = defineCommand({
+  name: "kube get-shell",
+  description: "get a shell to a pod in the environment",
+  group: "general",
+  inputs: {
+    namespace: {
+      type: "string",
+      message: "kubernetes namespace",
+      positional: true,
+    },
+    podName: {
+      type: "string",
+      message: "Which pod? 🤔",
+      choices: async (ctx) => {
+        const namespace = await ctx.get("namespace");
+        const k8sApi = getk8sApi();
+        const res = await k8sApi.listNamespacedPod(namespace);
+        return res.body.items.map((i: any) => i.metadata.name);
+      },
+    },
+  },
+  execute: async (ctx) => {
+    const namespace = await ctx.get("namespace");
+    const podName = await ctx.get("podName");
+    await getShell(namespace, podName);
+  },
+});

package/src/commands/general/commandKubeListNamespaces.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from "../../core/defineCommand";
+import { getk8sApi } from "../../k8sApi";
+
+export const commandKubeListNamespaces = defineCommand({
+  name: "kube list-namespaces",
+  description: "list all namespaces",
+  group: "general",
+  inputs: {},
+  execute: async (ctx) => {
+    const k8sApi = getk8sApi();
+    const res = await k8sApi.listNamespace();
+    const namespaces = res.body.items.map((n: any) => n.metadata.name);
+    ctx.log(namespaces.join("\n"));
+  },
+});

package/src/commands/general/commandKubeListPods.ts

@@ -0,0 +1,21 @@
+import { defineCommand } from "../../core/defineCommand";
+import { getk8sApi } from "../../k8sApi";
+
+export const commandKubeListPods = defineCommand({
+  name: "kube list-pods",
+  description: "list all pods of namespace",
+  group: "general",
+  inputs: {
+    namespace: {
+      type: "string",
+      message: "kubernetes namespace",
+      positional: true,
+    },
+  },
+  execute: async (ctx) => {
+    const namespace = await ctx.get("namespace");
+    const k8sApi = getk8sApi();
+    const res = await k8sApi.listNamespacedPod(namespace);
+    ctx.log(res.body.items.map((n: any) => n.metadata.name).join("\n"));
+  },
+});

package/src/commands/general/commandKubeListSecrets.ts

@@ -0,0 +1,21 @@
+import { defineCommand } from "../../core/defineCommand";
+import { getk8sApi } from "../../k8sApi";
+
+export const commandKubeListSecrets = defineCommand({
+  name: "kube list-secrets",
+  description: "show secrets",
+  group: "general",
+  inputs: {
+    namespace: {
+      type: "string",
+      message: "kubernetes namespace",
+      positional: true,
+    },
+  },
+  execute: async (ctx) => {
+    const namespace = await ctx.get("namespace");
+    const k8sApi = getk8sApi();
+    const res = await k8sApi.listNamespacedSecret(namespace);
+    ctx.log(res.body.items.map((n: any) => n.metadata.name).join("\n"));
+  },
+});