@catladder/cli 3.48.0 → 4.0.0

package/src/core/runner.ts

@@ -0,0 +1,31 @@
+import type { CommandDef, InputsSchema } from "./types";
+import { createProgrammaticContext } from "../adapters/programmatic";
+
+/**
+ * Run a command programmatically.
+ * This is the main entry point for calling commands from code.
+ *
+ * @example
+ * ```ts
+ * import { commandPortForward } from "./commands/project/portForward";
+ * import { runCommand } from "./core/runner";
+ *
+ * await runCommand(commandPortForward, {
+ *   inputs: { envComponent: "dev:web", podName: "web-abc", localPort: 3000, remotePort: 3000 },
+ * });
+ * ```
+ */
+export async function runCommand<TInputs extends InputsSchema>(
+  command: CommandDef<TInputs>,
+  options: {
+    inputs?: Record<string, unknown>;
+    onLog?: (message: string) => void;
+  } = {},
+): Promise<void> {
+  const ctx = createProgrammaticContext(command, {
+    inputs: options.inputs,
+    onLog: options.onLog,
+  });
+
+  await command.execute(ctx);
+}

package/src/core/types.ts

@@ -0,0 +1,142 @@
+// ─── Input Definitions ───────────────────────────────────────────────
+
+export type PromptChoice = string | { name: string; value: string };
+
+/**
+ * Function that returns choices for an input.
+ * Receives the command context so it can resolve other inputs first.
+ */
+export type ChoicesFn<TCtx = any> = (
+  ctx: TCtx,
+) => PromptChoice[] | Promise<PromptChoice[]>;
+
+export type StringInputDef = {
+  type: "string";
+  message: string;
+  default?: string;
+  positional?: boolean;
+  required?: boolean;
+  /** If provided, renders as a list selection in interactive mode */
+  choices?: ChoicesFn;
+};
+
+export type StringArrayInputDef = {
+  type: "string[]";
+  message: string;
+  positional?: boolean;
+  required?: boolean;
+  /** If provided, renders as checkboxes in interactive mode */
+  choices?: ChoicesFn;
+};
+
+export type NumberInputDef = {
+  type: "number";
+  message: string;
+  default?: number;
+  positional?: boolean;
+  required?: boolean;
+};
+
+export type BooleanInputDef = {
+  type: "boolean";
+  message: string;
+  default?: boolean;
+  positional?: boolean;
+  required?: boolean;
+};
+
+export type InputDef =
+  | StringInputDef
+  | StringArrayInputDef
+  | NumberInputDef
+  | BooleanInputDef;
+
+/** Map an InputDef to its resolved TypeScript value type */
+export type InputResultType<P extends InputDef> = P extends { type: "string" }
+  ? string
+  : P extends { type: "string[]" }
+    ? string[]
+    : P extends { type: "number" }
+      ? number
+      : P extends { type: "boolean" }
+        ? boolean
+        : never;
+
+// ─── Inputs Schema ──────────────────────────────────────────────────
+
+export type InputsSchema = Record<string, InputDef>;
+
+// ─── IO Interface (for helpers) ──────────────────────────────────────
+
+/**
+ * Base IO interface for helper functions that need to log or prompt.
+ * Helpers use `promptDirect` for ad-hoc prompts (confirmations, sub-selections)
+ * that are NOT part of a command's declared input schema.
+ */
+export interface IO {
+  log(message: string): void;
+  /**
+   * Ask for confirmation. Returns true/false.
+   * Skipped (returns true) when --yes is active.
+   * Throws or returns false on decline, depending on the adapter.
+   */
+  confirm(message: string): Promise<boolean>;
+  promptDirect<P extends InputDef>(
+    spec: P & { name: string },
+  ): Promise<InputResultType<P>>;
+}
+
+// ─── Command Context ─────────────────────────────────────────────────
+
+/**
+ * Runtime context passed to command execute functions.
+ * Extends IO so it can be passed to helpers that only need log + promptDirect.
+ *
+ * - `get(name)`: consume a declared input by name (type-safe).
+ *   Returns the value if already provided (positional arg, CLI flag, JSON),
+ *   or prompts for it interactively, or throws if non-interactive.
+ * - `log(message)`: output a message.
+ * - `promptDirect(spec)`: ad-hoc prompt for helpers (not type-checked against schema).
+ */
+export interface CommandContext<TInputs extends InputsSchema> extends IO {
+  /**
+   * Consume a declared input by name.
+   * - Compile error if `name` is not in TInputs
+   * - Return type matches the input's type (string, number, boolean, string[])
+   * - If `required: false`, returns `undefined` when not provided (no prompt)
+   * - Otherwise: pre-supplied value > choices function + interactive prompt > default > throw
+   */
+  get<K extends keyof TInputs & string>(
+    name: K,
+  ): Promise<OptionalInput<TInputs[K]>>;
+}
+
+/** If the input has `required: false`, the result can be undefined */
+export type OptionalInput<T extends InputDef> = T extends { required: false }
+  ? InputResultType<T> | undefined
+  : InputResultType<T>;
+
+// ─── Command Definition ──────────────────────────────────────────────
+
+export interface CommandDef<TInputs extends InputsSchema = InputsSchema> {
+  name: string;
+  description: string;
+  group?: string;
+  inputs: TInputs;
+  execute: (ctx: CommandContext<TInputs>) => Promise<void>;
+}
+
+// ─── Errors ──────────────────────────────────────────────────────────
+
+export class MissingInputError extends Error {
+  constructor(
+    public readonly inputName: string,
+    public readonly promptMessage: string,
+  ) {
+    super(
+      `Missing required input: "${inputName}" (${promptMessage}). ` +
+        `Provide it via --${inputName}=<value> or --inputs='{"${inputName}": ...}'`,
+    );
+    this.name = "MissingInputError";
+  }
+}

package/src/gcloud/cloudRun/openCloudRunDashboards.ts

@@ -1,10 +1,10 @@
 import type { ComponentContext } from "@catladder/pipeline";
 import { isOfDeployType } from "@catladder/pipeline";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../../core/types";
 import { openGoogleCloudDashboard } from "../openDashboard";
 
 export const openGoogleCloudRunDashboard = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
 ) => {
   if (!isOfDeployType(context.deploy?.config, "google-cloudrun")) {

package/src/gcloud/openDashboard.ts

@@ -1,8 +1,8 @@
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../core/types";
 import { getGoogleAuthUserNumber } from "../apps/cli/utils/getGoogleAuthUserNumber";
 import open from "open";
 export const openGoogleCloudDashboard = async (
-  instance: CommandInstance,
+  instance: IO,
   path: string,
   params: Record<string, string>,
 ) => {
@@ -12,7 +12,7 @@ export const openGoogleCloudDashboard = async (
     url.searchParams.set(key, value);
   }
 
-  const googleAuthUserNumber = await getGoogleAuthUserNumber.call(instance);
+  const googleAuthUserNumber = await getGoogleAuthUserNumber(instance);
   url.searchParams.set("authuser", googleAuthUserNumber);
 
   open(url.toString());

package/src/gcloud/serviceAccounts.ts

@@ -2,7 +2,7 @@ import type { ComponentContext } from "@catladder/pipeline";
 
 import { exec } from "child-process-promise";
 import { createHmac } from "crypto";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../core/types";
 import { upsertAllVariables } from "../utils/gitlab";
 
 export const accountExists = async (fullIdentifier: string) => {
@@ -93,7 +93,7 @@ const upsertGcloudServiceAccount = async (
 };
 
 export const upsertGcloudServiceAccountAndSaveSecret = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
   account: ServiceAccount,
   secretName: string,

package/src/kubernetes/openKubernetesDashboards.ts

@@ -1,10 +1,10 @@
 import type { ComponentContext } from "@catladder/pipeline";
 import { isOfDeployType } from "@catladder/pipeline";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../core/types";
 import { openGoogleCloudDashboard } from "../gcloud/openDashboard";
 
 export const openGoogleCloudLogs = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
 ) => {
   const deployConfig = context.deploy?.config;
@@ -30,7 +30,7 @@ export const openGoogleCloudLogs = async (
 };
 
 export const openGoogleCloudKubernetesDashboard = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
 ) => {
   const deployConfig = context.deploy?.config;

package/src/utils/gitlab.ts

@@ -3,36 +3,31 @@ import { has, isObject } from "lodash";
 import memoizee from "memoizee";
 import fetch from "node-fetch";
 import open from "open";
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../core/types";
 import { getPreference, hasPreference, setPreference } from "./preferences";
 import { getGitRemoteHostAndPath } from "../git/gitProjectInformation";
 
 const TOKEN_KEY = "gitlab-personal-access-token";
 
 export const hasGitlabToken = async () => await hasPreference(TOKEN_KEY);
-export const setupGitlabToken = async (vorpal: CommandInstance) => {
-  vorpal.log("");
-  vorpal.log("☝ in order to access the api, we need a personal access token");
-  vorpal.log("Its best to create one specifically for catladder");
-  vorpal.log("Scopes needed: api");
-  vorpal.log("");
-  vorpal.log("☝ we open up the settings page for you!");
-  vorpal.log("");
-  const [{ shouldContinue }, { gitRemoteHost }] = await Promise.all([
-    vorpal.prompt({
-      default: true,
-      message: "Ok",
-      name: "shouldContinue",
-      type: "prompt",
-    }),
+export const setupGitlabToken = async (io: IO) => {
+  io.log("");
+  io.log("☝ in order to access the api, we need a personal access token");
+  io.log("Its best to create one specifically for catladder");
+  io.log("Scopes needed: api");
+  io.log("");
+  io.log("☝ we open up the settings page for you!");
+  io.log("");
+  const [shouldContinue, { gitRemoteHost }] = await Promise.all([
+    io.confirm("Ok"),
     getGitRemoteHostAndPath(),
   ]);
 
   open(`https://${gitRemoteHost}/-/user_settings/personal_access_tokens`);
 
-  vorpal.log("Please type in gitlab's personal access token");
+  io.log("Please type in gitlab's personal access token");
 
-  const { personalToken } = await vorpal.prompt({
+  const personalToken = await io.promptDirect({
     type: "string",
     name: "personalToken",
     default: "",
@@ -42,28 +37,28 @@ export const setupGitlabToken = async (vorpal: CommandInstance) => {
     await setPreference(TOKEN_KEY, personalToken);
   }
 };
-export const getGitlabToken = async (vorpal: CommandInstance | null) => {
+export const getGitlabToken = async (io: IO | null) => {
   if (!(await hasGitlabToken())) {
-    if (!vorpal) {
+    if (!io) {
       console.error(
         "⚠️ gitlab token missing, please run catladder to set it up",
       );
       process.exit(1);
     }
-    await setupGitlabToken(vorpal);
+    await setupGitlabToken(io);
   }
   return getPreference(TOKEN_KEY);
 };
 
 type Method = "GET" | "PUT" | "POST" | "DELETE";
 export const doGitlabRequest = async <T = any>(
-  vorpal: CommandInstance | null,
+  io: IO | null,
   path: string,
   data: any = undefined,
   method: Method = "GET",
 ): Promise<T> => {
   const [rootToken, { gitRemoteHost }] = await Promise.all([
-    getGitlabToken(vorpal),
+    getGitlabToken(io),
     getGitRemoteHostAndPath(),
   ]);
 
@@ -96,11 +91,11 @@ export const doGitlabRequest = async <T = any>(
 };
 
 export const getProjectInfo = async (
-  vorpal: CommandInstance | null,
+  io: IO | null,
 ): Promise<{ id: string; web_url: string }> => {
   const { gitRemotePath } = await getGitRemoteHostAndPath();
   const project = await doGitlabRequest(
-    vorpal,
+    io,
     `projects/${encodeURIComponent(gitRemotePath)}`,
   );
   return project;
@@ -116,10 +111,10 @@ type GitlabVariable = {
 };
 export const getAllVariables = memoizee(
   async (
-    vorpal: CommandInstance | null,
+    io: IO | null,
     n = 5, // how many requests to do in parallel, 5 seems a good value for many projects, ideally we would do one request in parallel per component
   ): Promise<Array<GitlabVariable>> => {
-    const { id } = await getProjectInfo(vorpal);
+    const { id } = await getProjectInfo(io);
 
     let all: Array<GitlabVariable> = [];
     let result: Array<Array<GitlabVariable>> = [];
@@ -129,7 +124,7 @@ export const getAllVariables = memoizee(
       // Create an array of promises for N pages
       const promises = Array.from({ length: n }, (_, i) => {
         return doGitlabRequest(
-          vorpal,
+          io,
           `projects/${id}/variables?per_page=100&page=${page + i}`,
         );
       });
@@ -150,11 +145,8 @@ export const getAllVariables = memoizee(
   { promise: true },
 );
 
-export const getVariableValueByRawName = async (
-  vorpal: CommandInstance,
-  rawName: string,
-) => {
-  const allVariables = await getAllVariables(vorpal);
+export const getVariableValueByRawName = async (io: IO, rawName: string) => {
+  const allVariables = await getAllVariables(io);
   return allVariables.find((v) => v.key === rawName)?.value;
 };
 
@@ -162,7 +154,7 @@ const maskableRegex = new RegExp("^[a-zA-Z0-9_+=/@:.~-]{8,}$"); // SEE https://g
 const isMaskable = (value: string): boolean => maskableRegex.test(value);
 
 const createVariable = async (
-  vorpal: CommandInstance,
+  io: IO,
   projectId: string,
   key: string,
   value: string,
@@ -170,7 +162,7 @@ const createVariable = async (
   environment_scope = "*",
 ) => {
   return await doGitlabRequest(
-    vorpal,
+    io,
     `projects/${projectId}/variables`,
     {
       key,
@@ -183,14 +175,14 @@ const createVariable = async (
 };
 
 const updateVariable = async (
-  vorpal: CommandInstance,
+  io: IO,
   projectId: string,
   key: string,
   value: string,
   masked = true,
 ) => {
   return await doGitlabRequest(
-    vorpal,
+    io,
     `projects/${projectId}/variables/${key}`,
     {
       value,
@@ -200,21 +192,17 @@ const updateVariable = async (
   );
 };
 
-const deleteVariable = async (
-  vorpal: CommandInstance,
-  projectId: string,
-  key: string,
-) => {
+const deleteVariable = async (io: IO, projectId: string, key: string) => {
   return await doGitlabRequest(
-    vorpal,
+    io,
     `projects/${projectId}/variables/${key}`,
     undefined,
     "DELETE",
   );
 };
 
-const getAllCatladderEnvVarsInGitlab = async (vorpal: CommandInstance) => {
-  const allVariables = await getAllVariables(vorpal).then((v) =>
+const getAllCatladderEnvVarsInGitlab = async (io: IO) => {
+  const allVariables = await getAllVariables(io).then((v) =>
     v.reduce<{
       [key: string]: {
         value?: string;
@@ -257,32 +245,32 @@ const getAllCatladderEnvVarsInGitlab = async (vorpal: CommandInstance) => {
 
 const getBackupKey = (fullKey: string, timestamp: number) =>
   `${fullKey}_backup_${timestamp}`;
-export const clearBackups = async (vorpal: CommandInstance, keep: number) => {
-  const existingVariables = await getAllCatladderEnvVarsInGitlab(vorpal);
-  const { id } = await getProjectInfo(vorpal);
+export const clearBackups = async (io: IO, keep: number) => {
+  const existingVariables = await getAllCatladderEnvVarsInGitlab(io);
+  const { id } = await getProjectInfo(io);
   for (const [key, { backups }] of Object.entries(existingVariables)) {
     const backupsSorted = backups.sort((a, b) => b - a);
     //const toKeep = backupsSorted.slice(0, keep);
     const toDelete = backupsSorted.slice(keep);
 
     for (const timestamp of toDelete) {
-      await deleteVariable(vorpal, id, getBackupKey(key, timestamp));
+      await deleteVariable(io, id, getBackupKey(key, timestamp));
     }
   }
 };
 
 export const upsertAllVariables = async (
-  vorpal: CommandInstance,
+  io: IO,
   variables: Record<string, any>,
   env: string,
   componentName: string,
   backup = true,
   masked = true, // FIXME: would be better to have this per variable
 ): Promise<void> => {
-  const { id } = await getProjectInfo(vorpal);
+  const { id } = await getProjectInfo(io);
 
   // we list all existing variables. We also gather backup versions, but its currently unused
-  const existingVariables = await getAllCatladderEnvVarsInGitlab(vorpal);
+  const existingVariables = await getAllCatladderEnvVarsInGitlab(io);
   for (const [key, value] of Object.entries(variables ?? {})) {
     const fullKey = getSecretVarName(env, componentName, key);
     const valueSanitized = isObject(value) ? JSON.stringify(value) : `${value}`;
@@ -292,13 +280,13 @@ export const upsertAllVariables = async (
     const changed = oldValue !== valueSanitized;
     if (changed) {
       if (exists) {
-        vorpal.log(`changed: ${key}`);
+        io.log(`changed: ${key}`);
 
-        await updateVariable(vorpal, id, fullKey, valueSanitized, masked);
+        await updateVariable(io, id, fullKey, valueSanitized, masked);
         // write backup
         if (backup) {
           await createVariable(
-            vorpal,
+            io,
             id,
             getBackupKey(fullKey, new Date().getTime()),
             oldValue,
@@ -307,11 +295,11 @@ export const upsertAllVariables = async (
           );
         }
       } else {
-        vorpal.log(`new    : ${key}`);
-        await createVariable(vorpal, id, fullKey, valueSanitized, masked);
+        io.log(`new    : ${key}`);
+        await createVariable(io, id, fullKey, valueSanitized, masked);
       }
     } else {
-      vorpal.log(`skip   : ${key}`);
+      io.log(`skip   : ${key}`);
     }
   }
   getAllVariables.clear();

package/src/utils/log.ts

@@ -1,4 +1,4 @@
-import type { CommandInstance } from "vorpal";
+import type { IO } from "../core/types";
 
 type AnyMessagesFn = (message?: any, ...optionalParams: any[]) => void;
 type StringMessagesFn = (message?: string, ...optionalParams: string[]) => void;
@@ -21,7 +21,7 @@ type HasSomeKindOfLogMethod = { log: SomeKindOfLogFn };
  * null and undefined will fall back to console.log.
  */
 export type LoggerCmdInstance =
-  | CommandInstance
+  | IO
   | Console
   | HasSomeKindOfLogMethod
   | null

package/bin/catci

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-// tslint:disable-next-line:no-var-requires
-require("../dist/bundles/catci/index.js");

package/bin/catci-dev

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-// tslint:disable-next-line:no-var-requires
-require("../dist/cli/src/catci.js");