@catladder/cli 0.0.0-next-95928577 → 0.0.0-next-e7541a00

package/src/core/defineCommand.ts

@@ -0,0 +1,32 @@
+import type { CommandDef, InputDef } from "./types";
+
+/**
+ * Type-safe builder for command definitions.
+ * Infers TInputs from the definition object so that
+ * `ctx.get("...")` is fully typed.
+ *
+ * @example
+ * ```ts
+ * export const myCommand = defineCommand({
+ *   name: "my-command",
+ *   description: "Does something",
+ *   inputs: {
+ *     envComponent: { type: "string", message: "env:component", positional: true },
+ *     podName: { type: "string", message: "Which pod?", choices: async () => ["a", "b"] },
+ *     mr: { type: "number", message: "Which MR?" },
+ *     confirmed: { type: "boolean", message: "Continue?" },
+ *   },
+ *   execute: async (ctx) => {
+ *     const env = await ctx.get("envComponent");  // string
+ *     const pod = await ctx.get("podName");        // string
+ *     const mr = await ctx.get("mr");              // number
+ *     const ok = await ctx.get("confirmed");       // boolean
+ *   },
+ * });
+ * ```
+ */
+export function defineCommand<const TInputs extends Record<string, InputDef>>(
+  def: CommandDef<TInputs>,
+): CommandDef<TInputs> {
+  return def;
+}

package/src/core/index.ts

@@ -0,0 +1,23 @@
+export type {
+  CommandContext,
+  CommandDef,
+  IO,
+  InputDef,
+  InputResultType,
+  InputsSchema,
+  StringInputDef,
+  StringArrayInputDef,
+  NumberInputDef,
+  BooleanInputDef,
+  PromptChoice,
+  ChoicesFn,
+} from "./types";
+export { MissingInputError } from "./types";
+export { defineCommand } from "./defineCommand";
+export {
+  registerCommand,
+  getCommand,
+  getAllCommands,
+  getCommandsByGroup,
+} from "./registry";
+export { runCommand } from "./runner";

package/src/core/registry.ts

@@ -0,0 +1,22 @@
+import type { CommandDef } from "./types";
+
+const commands: Map<string, CommandDef> = new Map();
+
+export function registerCommand(def: CommandDef): void {
+  if (commands.has(def.name)) {
+    throw new Error(`Command "${def.name}" is already registered`);
+  }
+  commands.set(def.name, def);
+}
+
+export function getCommand(name: string): CommandDef | undefined {
+  return commands.get(name);
+}
+
+export function getAllCommands(): CommandDef[] {
+  return Array.from(commands.values());
+}
+
+export function getCommandsByGroup(group: string): CommandDef[] {
+  return getAllCommands().filter((c) => c.group === group);
+}

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,145 @@
+import type { ComponentContext } from "@catladder/pipeline";
+
+// ─── 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;
+  isAvailable?: (contexts: ComponentContext[]) => boolean;
+  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/cloudSql/copyDb.ts

@@ -30,27 +30,33 @@ const createCopyDbScript = ({
   const targetPSQL = (command: string) =>
     `PGPASSWORD=${targetPassword} psql -p ${targetPort} --host=localhost --user=${targetUsername} -q ${command}`;
 
+  // URL-encode credentials to handle special characters like @, :, /, etc.
+  const encodedSourceUsername = encodeURIComponent(sourceUsername);
+  const encodedSourcePassword = encodeURIComponent(sourcePassword);
+
   const copyDBScript = `
       set -e
-     
-    
-
-      dumptmp=$(mktemp /tmp/dump.XXXXXX)
 
-      echo "Dumping file to $dumptmp"
-      pg_dump --dbname=postgres://${sourceUsername}:${sourcePassword}@localhost:${sourcePort}/${sourceDbName} --no-owner --no-privileges > $dumptmp
-      echo "dump done"
       ${targetPSQL(
         `-c 'drop database "${targetDbName}" WITH (FORCE)' 1> /dev/null || true`,
       )}
       ${targetPSQL(`-c 'create database "${targetDbName}"' 1> /dev/null`)}
-          echo "Restoring dump..."
-      ${targetPSQL(`"${targetDbName}" < $dumptmp 1> /dev/null`)}
-  
+      echo "Estimating database size..."
+      DB_SIZE=$(PGPASSWORD=${encodedSourcePassword} psql --dbname=postgres://${encodedSourceUsername}:${encodedSourcePassword}@localhost:${sourcePort}/${sourceDbName} -t -A -c "SELECT pg_database_size('${sourceDbName}')")
+      # pg_database_size includes indexes, TOAST, and free space — pg_dump output is roughly 40% of that
+      ESTIMATED_DUMP_SIZE=$((DB_SIZE * 40 / 100))
+      echo "Estimated dump size: $((ESTIMATED_DUMP_SIZE / 1024 / 1024)) MB (~40% of $((DB_SIZE / 1024 / 1024)) MB database size)"
+
+      PROGRESS=""
+      if command -v pv &> /dev/null; then
+        PROGRESS="pv -s $ESTIMATED_DUMP_SIZE |"
+      else
+        echo "(install 'pv' for progress info)"
+      fi
+
+      echo "Dumping and restoring via pipe..."
+      eval "pg_dump --dbname=postgres://${encodedSourceUsername}:${encodedSourcePassword}@localhost:${sourcePort}/${sourceDbName} --no-owner --no-privileges | $PROGRESS ${targetPSQL(`"${targetDbName}" 1> /dev/null`)}"
 
-      echo "Clean up..."
-      set +e
-      rm $dumptmp
       echo "\n🐱 Done!"
       `;
   return copyDBScript;

package/src/gcloud/cloudSql/parseConnectionString.ts

@@ -0,0 +1,28 @@
+import {
+  ConnectionStringParser,
+  type IConnectionStringParameters,
+} from "connection-string-parser";
+
+/**
+ * Parses a PostgreSQL connection string.
+ * Accepts both postgres:// and postgresql:// schemes and normalizes to postgresql://
+ *
+ * @param connectionString - The connection string to parse (e.g., "postgresql://user:pass@localhost:5432/dbname")
+ * @returns Parsed connection string parameters
+ */
+export function parseConnectionString(
+  connectionString: string,
+): IConnectionStringParameters {
+  const parser = new ConnectionStringParser({
+    scheme: "postgresql",
+    hosts: [],
+  });
+
+  // Normalize postgres:// to postgresql:// (the official IANA scheme)
+  const normalizedConnectionString = connectionString.replace(
+    /^postgres:\/\//,
+    "postgresql://",
+  );
+
+  return parser.parse(normalizedConnectionString);
+}

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) => {
@@ -69,7 +69,7 @@ const upsertGcloudServiceAccount = async (
   const memberName = `serviceAccount:${fullIdentifier}`;
   for (const role of roles) {
     await exec(
-      `gcloud projects add-iam-policy-binding ${projectId} --member=${memberName} --role=${role} `,
+      `gcloud projects add-iam-policy-binding ${projectId} --member=${memberName} --role=${role} --condition=None`,
     );
   }
 
@@ -93,7 +93,7 @@ const upsertGcloudServiceAccount = async (
 };
 
 export const upsertGcloudServiceAccountAndSaveSecret = async (
-  instance: CommandInstance,
+  instance: IO,
   context: ComponentContext,
   account: ServiceAccount,
   secretName: string,

package/src/git/getGetMainBranch.ts

@@ -0,0 +1,5 @@
+import { exec } from "child-process-promise";
+export const getMainBranch = async () => {
+  const { stdout } = await exec("git rev-parse --abbrev-ref HEAD");
+  return stdout.trim();
+};

package/src/git/gitConfig.ts

@@ -0,0 +1,32 @@
+import { exec } from "child-process-promise";
+
+export type GitLocationScope = "global" | "local" | "system" | "worktree";
+export type GitConfigOptions = {
+  location?: GitLocationScope;
+  comment?: string;
+};
+
+const argsJoin = (args: (string | undefined)[]): string =>
+  args.filter(Boolean).join(" ");
+
+export async function gitConfigGet(
+  key: string,
+  { location }: Pick<GitConfigOptions, "location"> = {},
+) {
+  const { stdout } = await exec(
+    `git config --get ${argsJoin([location ? `--${location}` : undefined])} ${key}`,
+  );
+  return stdout.trim();
+}
+
+export const gitConfigSet = (
+  key: string,
+  value: string,
+  { location, comment }: GitConfigOptions = {},
+) =>
+  exec(
+    `git config --set ${argsJoin([
+      location ? `--${location}` : undefined,
+      comment ? `--comment=${comment}` : undefined,
+    ])} ${key} ${value}`,
+  );

package/src/git/gitProjectInformation.ts

@@ -0,0 +1,40 @@
+import { gitConfigGet } from "./gitConfig";
+import { exec } from "child-process-promise";
+
+/**
+ * Find the absolute path of the current git project root.
+ */
+export const getProjectRootPath = async (): Promise<string> => {
+  const { stdout } = await exec(`git rev-parse --show-toplevel`);
+  return stdout.trim();
+};
+
+/**
+ * Get the git remote hostname and project path from the git config.
+ */
+export const getGitRemoteHostAndPath = async (): Promise<{
+  gitRemoteHost: string;
+  gitRemotePath: string;
+}> => {
+  const remoteUrl = await gitConfigGet("remote.origin.url");
+  const remoteReg = /(https:\/\/|git@)([^:/]+)[:/]([^.]*)(\.git)?/;
+  const match = remoteUrl.match(remoteReg) ?? [];
+  const [, , gitRemoteHost, gitRemotePath] = match;
+  if (!gitRemoteHost?.length || !gitRemotePath?.length) {
+    throw new Error(
+      `Failed to parse git remote hostname and path from git configs remote.origin.url! ${remoteUrl}`,
+    );
+  }
+  return { gitRemoteHost, gitRemotePath };
+};
+
+export const gitProjectInformation = async () => {
+  const [{ gitRemoteHost, gitRemotePath }, projectRootPath] = await Promise.all(
+    [getGitRemoteHostAndPath(), getProjectRootPath()],
+  );
+  return {
+    gitRemoteHost,
+    gitRemotePath,
+    projectRootPath,
+  };
+};

package/src/git/index.ts

@@ -0,0 +1,3 @@
+export * from "./gitConfig";
+export * from "./gitProjectInformation";
+export * from "./getGetMainBranch";

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/packageInfos.ts

@@ -4,7 +4,6 @@
 // this will point to the root package.json
 
 const path = require.main?.path + "/../package.json";
-// eslint-disable-next-line @typescript-eslint/no-var-requires
 const ownPkg = require(path);
 
 export default ownPkg;

package/src/utils/files.ts

@@ -1,7 +1,6 @@
-import fs from "fs-extra";
+import { readFile as fsExtraReadFile } from "fs-extra";
 
-const readFile = async (file: string) =>
-  fs.readFile(file, { encoding: "utf-8" });
+const readFile = (file: string) => fsExtraReadFile(file, { encoding: "utf-8" });
 
 export const readFileOrError = async (filePath: string) => {
   try {