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

package/package.json

@@ -53,18 +53,19 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-next-95928577",
+  "version": "0.0.0-next-e7541a00",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",
     "test": "yarn run lint",
-    "build": "yarn build:compile && yarn build:bundle",
+    "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",
     "build:bundle": "./scripts/bundle",
     "build:compile": "yarn tsc && yarn tsc-alias",
-    "build:watch": "yarn tsc -w"
+    "dev:own-catenv": "cd ../ && node cli/bin/catenv-dev",
+    "build:watch": "tsc-watch --onSuccess \"yarn dev:own-catenv\""
   },
   "bin": {
-    "catci": "./bin/catci",
     "catenv": "./bin/catenv",
     "catladder": "./bin/catladder"
   },
@@ -74,42 +75,46 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-syntax-typescript": "^7.28.6",
     "@gitbeaker/rest": "^39.28.0",
+    "@inquirer/prompts": "^8.4.3",
     "@kubernetes/client-node": "^0.16.2",
     "@tsconfig/node14": "^1.0.1",
-    "@types/common-tags": "^1.8.0",
+    "@types/common-tags": "^1.8.4",
     "@types/fs-extra": "^5.0.4",
-    "@types/lodash": "^4.14.185",
+    "@types/lodash-es": "^4.17.12",
     "@types/memoizee": "^0.4.2",
-    "@types/node-fetch": "^2.1.4",
-    "@types/request": "^2.48.1",
+    "@types/node-fetch": "^2.6.11",
+    "@types/request": "^2.48.12",
     "@types/tmp": "^0.2.3",
     "@types/update-notifier": "^2.5.0",
-    "@types/vorpal": "^1.12.0",
     "@types/websocket": "^0.0.40",
-    "@types/yargs": "^13.0.0",
+    "@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",
-    "common-tags": "^1.8.0",
+    "commander": "^14.0.3",
+    "common-tags": "^1.8.2",
     "connection-string-parser": "^1.0.4",
-    "dayjs": "^1.10.4",
+    "date-fns": "^3.6.0",
     "fs-extra": "^7.0.1",
-    "gitlab": "^4.4.1",
-    "lodash": "^4.17.21",
-    "memoizee": "^0.4.14",
+    "lodash-es": "^4.18.1",
+    "memoizee": "^0.4.17",
     "node-fetch": "^2.3.0",
     "open": "^8.4.0",
-    "prettier": "^3.3.2",
+    "prettier": "^3.3.3",
     "tmp-promise": "^2.0.2",
-    "ts-results-es": "^4.1.0-alpha.1",
-    "tsc-alias": "^1.8.10",
+    "ts-results-es": "^4.2.0",
+    "tsc-alias": "^1.8.16",
+    "tsc-watch": "^7.2.0",
     "typescript": "^5.4.5",
-    "vorpal": "^1.12.0",
-    "yaml": "^2.4.5"
+    "yaml": "^2.5.0"
   },
   "dependencies": {
-    "tsx": "^4.16.2"
+    "tsx": "^4.21.0"
   },
   "stableVersion": "0.0.0"
 }

package/scripts/bundle

@@ -1,6 +1,4 @@
 #!/bin/bash
-ncc build dist/cli/src/catenv.js -o dist/bundles/catenv -e 'tsx/cjs/api' $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
+ncc build dist/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 -e 'tsx/cjs/api' $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
-
-ncc build dist/cli/src/catci.js -o dist/bundles/catci -e 'tsx/cjs/api' $( ((SHOULD_MINIFY == 1)) && printf %s '-m')
+ncc build dist/cli/src/cli.js -o dist/bundles/cli $( ((SHOULD_MINIFY == 1)) && printf %s '-m')

package/src/adapters/baseContext.ts

@@ -0,0 +1,68 @@
+import type {
+  CommandContext,
+  CommandDef,
+  InputDef,
+  InputResultType,
+  InputsSchema,
+  OptionalInput,
+} from "../core/types";
+
+/**
+ * Base class for CommandContext implementations.
+ * Handles caching, the `get()` method, and `promptDirect` delegation.
+ * Subclasses only implement the adapter-specific resolution logic.
+ */
+export abstract class BaseContext<TInputs extends InputsSchema>
+  implements CommandContext<TInputs>
+{
+  private cache = new Map<string, Promise<any>>();
+
+  constructor(protected readonly command: CommandDef<TInputs>) {}
+
+  abstract log(message: string): void;
+  abstract confirm(message: string): Promise<boolean>;
+
+  /**
+   * 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]>> {
+    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?.name === "MissingInputError") return undefined;
+            throw err;
+          }),
+        );
+      } else {
+        this.cache.set(name, this.resolveInput(name, spec));
+      }
+    }
+    return this.cache.get(name)!;
+  }
+
+  async promptDirect<P extends InputDef>(
+    spec: P & { name: string },
+  ): Promise<InputResultType<P>> {
+    return this.resolveInput(spec.name, spec);
+  }
+}

package/src/adapters/programmatic.ts

@@ -0,0 +1,88 @@
+import type {
+  CommandDef,
+  IO,
+  InputDef,
+  InputResultType,
+  InputsSchema,
+} from "../core/types";
+import { MissingInputError } 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;
+}
+
+class ProgrammaticContext<
+  TInputs extends InputsSchema,
+> extends BaseContext<TInputs> {
+  private inputs: Record<string, unknown>;
+  private onLog?: (message: string) => void;
+
+  constructor(command: CommandDef<TInputs>, options: ProgrammaticOptions) {
+    super(command);
+    this.inputs = options.inputs ?? {};
+    this.onLog = options.onLog;
+  }
+
+  log(message: string): void {
+    this.onLog?.(message);
+  }
+
+  async confirm(): Promise<boolean> {
+    return true; // programmatic mode always confirms
+  }
+
+  protected async resolveInput<P extends InputDef>(
+    name: string,
+    spec: P,
+  ): Promise<InputResultType<P>> {
+    if (name in this.inputs && this.inputs[name] !== undefined) {
+      return this.inputs[name] as InputResultType<P>;
+    }
+    if ("default" in spec && spec.default !== undefined) {
+      return spec.default as InputResultType<P>;
+    }
+    throw new MissingInputError(name, spec.message);
+  }
+}
+
+/**
+ * Create a CommandContext that resolves inputs from pre-supplied values.
+ * Used for non-interactive CLI mode and programmatic invocation.
+ */
+export function createProgrammaticContext<TInputs extends InputsSchema>(
+  command: CommandDef<TInputs>,
+  options: ProgrammaticOptions = {},
+): ProgrammaticContext<TInputs> {
+  return new ProgrammaticContext(command, options);
+}
+
+/**
+ * Create a bare IO instance for helper functions that only need log + promptDirect.
+ */
+export function createProgrammaticIO(options: ProgrammaticOptions = {}): IO {
+  const { inputs = {}, onLog } = options;
+
+  return {
+    log(message: string): void {
+      onLog?.(message);
+    },
+    async confirm(): Promise<boolean> {
+      return true;
+    },
+    async promptDirect<P extends InputDef>(
+      spec: P & { name: string },
+    ): Promise<InputResultType<P>> {
+      if (spec.name in inputs && inputs[spec.name] !== undefined) {
+        return inputs[spec.name] as InputResultType<P>;
+      }
+      if ("default" in spec && spec.default !== undefined) {
+        return spec.default as InputResultType<P>;
+      }
+      throw new MissingInputError(spec.name, spec.message);
+    },
+  };
+}

package/src/adapters/terminal.ts

@@ -0,0 +1,207 @@
+import type {
+  CommandDef,
+  IO,
+  InputDef,
+  InputResultType,
+  InputsSchema,
+  PromptChoice,
+} from "../core/types";
+import { MissingInputError } from "../core/types";
+import { BaseContext } from "./baseContext";
+
+/**
+ * Resolve choices from a choices function.
+ */
+async function resolveChoices(
+  choices: (ctx: any) => PromptChoice[] | Promise<PromptChoice[]>,
+  ctx: any,
+): Promise<{ name: string; value: string }[]> {
+  const raw = await choices(ctx);
+  return raw.map((c) => (typeof c === "string" ? { name: c, value: c } : c));
+}
+
+/**
+ * Prompt the user interactively using @inquirer/prompts.
+ * The UI is determined by the value type + presence of choices.
+ */
+async function promptInteractive<P extends InputDef>(
+  spec: P & { name: string },
+  ctx: any,
+): Promise<InputResultType<P>> {
+  const inquirer = await import("@inquirer/prompts");
+
+  switch (spec.type) {
+    case "string": {
+      if (spec.choices) {
+        const choices = await resolveChoices(spec.choices, ctx);
+        return inquirer.select({
+          message: spec.message,
+          choices,
+        }) as Promise<InputResultType<P>>;
+      }
+      return inquirer.input({
+        message: spec.message,
+        default: spec.default,
+      }) as Promise<InputResultType<P>>;
+    }
+    case "string[]": {
+      if (spec.choices) {
+        const choices = await resolveChoices(spec.choices, ctx);
+        return inquirer.checkbox({
+          message: spec.message,
+          choices,
+        }) as Promise<InputResultType<P>>;
+      }
+      const raw = await inquirer.input({ message: spec.message });
+      return (
+        raw ? raw.split(",").map((s: string) => s.trim()) : []
+      ) as InputResultType<P>;
+    }
+    case "number":
+      return inquirer.number({
+        message: spec.message,
+        default: spec.default,
+      }) as Promise<InputResultType<P>>;
+    case "boolean":
+      return inquirer.confirm({
+        message: spec.message,
+        default: spec.default,
+      }) as Promise<InputResultType<P>>;
+    default:
+      throw new Error(`Unsupported input type: ${(spec as InputDef).type}`);
+  }
+}
+
+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;
+}
+
+class TerminalContext<
+  TInputs extends InputsSchema,
+> extends BaseContext<TInputs> {
+  constructor(
+    command: CommandDef<TInputs>,
+    private options: TerminalOptions,
+  ) {
+    super(command);
+  }
+
+  log(message: string): void {
+    console.log(message);
+  }
+
+  async confirm(message: string): Promise<boolean> {
+    if (this.options.yes) return true;
+    const isInteractive =
+      this.options.interactive ?? process.stdin.isTTY === true;
+    if (!isInteractive) return true;
+    const inquirer = await import("@inquirer/prompts");
+    return inquirer.confirm({ message });
+  }
+
+  protected async resolveInput<P extends InputDef>(
+    name: string,
+    spec: P,
+  ): Promise<InputResultType<P>> {
+    const { cliOptions = {}, jsonInputs = {}, interactive } = this.options;
+    const isInteractive = interactive ?? process.stdin.isTTY === true;
+
+    // Helper: validate a pre-supplied value against choices if they exist
+    const validateAgainstChoices = async (value: unknown): Promise<void> => {
+      if (!("choices" in spec) || !spec.choices) return;
+      const choices = await resolveChoices(spec.choices, this);
+      const validValues = choices.map((c) => c.value);
+      if (Array.isArray(value)) {
+        const invalid = (value as string[]).filter(
+          (v) => !validValues.includes(v),
+        );
+        if (invalid.length > 0) {
+          throw new Error(
+            `Invalid value(s) for "${name}": ${invalid.join(", ")}. Valid choices: ${validValues.join(", ")}`,
+          );
+        }
+      } else if (!validValues.includes(value as string)) {
+        throw new Error(
+          `Invalid value for "${name}": "${value}". Valid choices: ${validValues.join(", ")}`,
+        );
+      }
+    };
+
+    // 1. CLI flag or positional arg
+    if (name in cliOptions && cliOptions[name] !== undefined) {
+      await validateAgainstChoices(cliOptions[name]);
+      return cliOptions[name] as InputResultType<P>;
+    }
+
+    // 2. JSON inputs
+    if (name in jsonInputs && jsonInputs[name] !== undefined) {
+      await validateAgainstChoices(jsonInputs[name]);
+      return jsonInputs[name] as InputResultType<P>;
+    }
+
+    // 3. Default (check before prompting, so optional inputs with defaults don't prompt)
+    if ("default" in spec && spec.default !== undefined) {
+      return spec.default as InputResultType<P>;
+    }
+
+    // 4. Optional inputs: don't prompt, throw so baseContext returns undefined
+    if (spec.required === false) {
+      throw new MissingInputError(name, spec.message);
+    }
+
+    // 5. Interactive prompt
+    if (isInteractive) {
+      return promptInteractive({ ...spec, name }, this);
+    }
+
+    // 6. Throw
+    throw new MissingInputError(name, spec.message);
+  }
+}
+
+/**
+ * Create a CommandContext for terminal usage.
+ */
+export function createTerminalContext<TInputs extends InputsSchema>(
+  command: CommandDef<TInputs>,
+  options: TerminalOptions = {},
+): TerminalContext<TInputs> {
+  return new TerminalContext(command, options);
+}
+
+/**
+ * Create a bare IO instance for terminal helper functions.
+ */
+export function createTerminalIO(options: TerminalOptions = {}): IO {
+  return {
+    log(message: string): void {
+      console.log(message);
+    },
+    async confirm(message: string): Promise<boolean> {
+      if (options.yes) return true;
+      const isInteractive = options.interactive ?? process.stdin.isTTY === true;
+      if (!isInteractive) return true;
+      const inquirer = await import("@inquirer/prompts");
+      return inquirer.confirm({ message });
+    },
+    async promptDirect<P extends InputDef>(
+      spec: P & { name: string },
+    ): Promise<InputResultType<P>> {
+      const isInteractive = options.interactive ?? process.stdin.isTTY === true;
+      if (isInteractive) {
+        return promptInteractive(spec, null);
+      }
+      if ("default" in spec && spec.default !== undefined) {
+        return spec.default as InputResultType<P>;
+      }
+      throw new MissingInputError(spec.name, spec.message);
+    },
+  };
+}

package/src/apps/catenv/catenv.ts

@@ -1,22 +1,36 @@
 import { getProjectConfig } from "../../config/getProjectConfig";
 import { printVariables } from "./printVariables";
 import type { Choice } from "./types";
+import { printVerboseBanner } from "./verboseBanner";
 import { writeDotEnvFiles } from "./writeDotEnvFiles";
 import { writeDTsFiles } from "./writeEnvDTs";
-import { generatePipelineFiles } from "@catladder/pipeline";
+import {
+  createCatenvContext,
+  generatePipelineFiles,
+} from "@catladder/pipeline";
 
-export default async (choice?: Choice) => {
+type Options = {
+  verbose?: boolean;
+  printVariables?: boolean;
+};
+export default async (choice?: Choice, options?: Options) => {
   const config = await getProjectConfig();
   if (!config) {
     return;
   }
 
-  await Promise.all([
-    generatePipelineFiles(config, config.pipelineType ?? "gitlab", "local"),
-    writeDotEnvFiles(config, choice),
+  const context = createCatenvContext(config);
+  if (options?.verbose) {
+    printVerboseBanner();
+  }
 
-    writeDTsFiles(config, choice),
+  await Promise.all([
+    generatePipelineFiles(context, config.pipelineType ?? "gitlab"),
+    writeDotEnvFiles(context, choice),
 
-    printVariables(config, choice),
+    writeDTsFiles(context, choice),
+    options?.printVariables
+      ? printVariables(context, choice)
+      : Promise.resolve(),
   ]);
 };

package/src/apps/catenv/printVariables.ts

@@ -1,4 +1,4 @@
-import type { Config } from "@catladder/pipeline";
+import type { CatenvContext, Config } from "@catladder/pipeline";
 import { getEnvVarsResolved } from "../../config/getProjectConfig";
 import type { Choice } from "./types";
 import {
@@ -14,10 +14,6 @@ const getAllVariablesToPrint = async (config: Config, choice?: Choice) => {
   );
 
   if (currentComponent) {
-    // don't print vars if dotenv is enabled
-    if (config.components[currentComponent].dotEnv ?? true) {
-      return {};
-    }
     return await getEnvVarsResolved(null, env, currentComponent);
   } else {
     // when in a monorep and not in a subapp, merge all env vars.
@@ -25,10 +21,6 @@ const getAllVariablesToPrint = async (config: Config, choice?: Choice) => {
     // so we also add prefixed variants
     return await Object.keys(config.components).reduce(
       async (acc, componentName) => {
-        // don't print vars if dotenv is enabled
-        if (config.components[componentName].dotEnv ?? true) {
-          return await acc;
-        }
         const subappvars = await getEnvVarsResolved(null, env, componentName);
         delete subappvars["_ALL_ENV_VAR_KEYS"];
         return {
@@ -48,11 +40,17 @@ const getAllVariablesToPrint = async (config: Config, choice?: Choice) => {
   }
 };
 
-export const printVariables = async (config: Config, choice?: Choice) => {
-  const variables = await getAllVariablesToPrint(config, choice);
+export const printVariables = async (
+  context: CatenvContext,
+  choice?: Choice,
+) => {
+  const variables = await getAllVariablesToPrint(context.config, choice);
 
   console.log(makeExportKeyValuestring(variables));
 };
 
 const makeExportKeyValuestring = (variables: Record<string, string>) =>
-  makeKeyValueString(variables, "export ");
+  makeKeyValueString(variables, {
+    keyPrefix: "export ",
+    escapeOptions: { quoteMode: "always" },
+  });

package/src/apps/catenv/utils.ts

@@ -1,4 +1,4 @@
-import type { Config } from "@catladder/pipeline";
+import type { Config, EscapeForDotEnvOptions } from "@catladder/pipeline";
 import { join } from "path";
 import { getGitRoot } from "../../utils/projects";
 import type { Choice } from "./types";
@@ -32,13 +32,22 @@ export const getCurrentComponentAndEnvFromChoice = async (
   };
 };
 
+export type MakeKeyValueStringOptions = {
+  keyPrefix?: string;
+  escapeOptions?: EscapeForDotEnvOptions;
+};
 export const makeKeyValueString = (
   variables: Record<string, string>,
-  keyPrefix = "",
+  { keyPrefix, escapeOptions }: MakeKeyValueStringOptions = {
+    keyPrefix: "",
+  },
 ) =>
   Object.entries(variables)
     // quotes are important, otherwise line breaks don't work properly
-    .map(([key, value]) => `${keyPrefix}${key}=${escapeForDotEnv(value)}`)
+    .map(
+      ([key, value]) =>
+        `${keyPrefix}${key}=${escapeForDotEnv(value, escapeOptions)}`,
+    )
     .join("\n");
 
 export const sanitizeEnvVarName = (name: string) =>

package/src/apps/catenv/verboseBanner.ts

@@ -0,0 +1,33 @@
+import {
+  getEnvironment,
+  getProjectConfig,
+} from "../../config/getProjectConfig";
+
+export const printVerboseBanner = async () => {
+  const config = await getProjectConfig();
+  if (!config) {
+    return;
+  }
+
+  const allCompontsWithPorts = await Promise.all(
+    Object.keys(config.components).map(async (componentName) => {
+      const environment = await getEnvironment("local", componentName);
+      const port = environment.envVars.PORT;
+      if (!port) {
+        return null;
+      }
+      return `${componentName}: http://localhost:${port}`;
+    }),
+  ).then((lines) => lines.filter(Boolean));
+
+  const lines = [
+    "catenv",
+    "-------",
+    "running on:",
+    "",
+    ...allCompontsWithPorts,
+  ];
+  for (const line of lines) {
+    console.log(line);
+  }
+};

package/src/apps/catenv/writeDotEnvFiles.ts

@@ -1,4 +1,3 @@
-import { writeGeneratedFile, type Config } from "@catladder/pipeline";
 import { join } from "path";
 import { getEnvVarsResolved } from "../../config/getProjectConfig";
 import { getGitRoot } from "../../utils/projects";
@@ -8,14 +7,20 @@ import {
   getCurrentComponentAndEnvFromChoice,
   makeKeyValueString,
 } from "./utils";
+import type { CatenvContext } from "@catladder/pipeline";
 
-export const writeDotEnvFiles = async (config: Config, choice?: Choice) => {
+export const writeDotEnvFiles = async (
+  context: CatenvContext,
+  choice?: Choice,
+) => {
   const { env, currentComponent } = await getCurrentComponentAndEnvFromChoice(
-    config,
+    context.config,
     choice,
   );
 
-  const componentsWithEnabledDotEnvWrite = Object.entries(config.components)
+  const componentsWithEnabledDotEnvWrite = Object.entries(
+    context.config.components,
+  )
     .filter(([, component]) => component?.dotEnv ?? true) // when set to true or "local"
     .map(([componentName]) => componentName);
 
@@ -29,11 +34,19 @@ export const writeDotEnvFiles = async (config: Config, choice?: Choice) => {
   for (const componentName of componentsToActuallyWriteDotEnvNow) {
     const variables = await getEnvVarsResolved(null, env, componentName);
     delete variables["_ALL_ENV_VAR_KEYS"];
-    const componentDir = getComponentFullPath(gitRoot, config, componentName);
+    const componentDir = getComponentFullPath(
+      gitRoot,
+      context.config,
+      componentName,
+    );
     const filePath = join(componentDir, ".env");
 
-    await writeGeneratedFile(filePath, makeKeyValueString(variables), {
-      commentChar: "#",
-    });
+    await context.fileWriter.writeGeneratedFile(
+      filePath,
+      makeKeyValueString(variables),
+      {
+        commentChar: "#",
+      },
+    );
   }
 };