@reliverse/rempts 1.6.0

package/bin/core-impl/launcher/launcher-mod.js

@@ -0,0 +1,364 @@
+import { reliArgParser } from "@reliverse/reliarg";
+import { relinka } from "@reliverse/relinka";
+import fs from "fs-extra";
+import process from "node:process";
+import path from "pathe";
+const isDebugMode = process.argv.includes("--debug");
+function debugLog(...args) {
+  if (isDebugMode) {
+    relinka("info", "[DEBUG]", ...args);
+  }
+}
+export function defineCommand(options) {
+  return {
+    meta: options.meta,
+    args: options.args || {},
+    run: options.run,
+    subCommands: options.subCommands
+  };
+}
+export async function showUsage(command, parserOptions = {}) {
+  relinka("info", `${command.meta.name} v${command.meta.version || ""}`);
+  if (command.meta.description) {
+    relinka("info", command.meta.description);
+  }
+  const fileCmds = parserOptions.fileBasedCmds;
+  if (fileCmds?.enable) {
+    const usageLine = `Usage: ${command.meta.name} <subCommand> [options]`;
+    relinka("info", usageLine);
+    try {
+      const commandsDir = path.resolve(fileCmds.cmdsRootPath);
+      const items = await fs.readdir(commandsDir, { withFileTypes: true });
+      const subCommandNames = [];
+      for (const dirent of items) {
+        if (dirent.isDirectory() || dirent.isFile()) {
+          const name = dirent.name.replace(/\.[jt]s$/, "");
+          try {
+            const importPath = path.join(
+              commandsDir,
+              dirent.isDirectory() ? `${name}/index.js` : `${name}.js`
+            );
+            const imported = await import(path.resolve(importPath));
+            if (imported.default && !imported.default.meta?.hidden) {
+              subCommandNames.push(name);
+            }
+          } catch (_err) {
+            debugLog(`Skipping file ${dirent.name}:`, _err);
+          }
+        }
+      }
+      if (subCommandNames.length > 0) {
+        relinka("info", "\nAvailable file-based subCommands:");
+        subCommandNames.forEach((sc) => relinka("info", `  ${sc}`));
+      }
+    } catch (_err) {
+      relinka(
+        "info",
+        `
+(No file-based subcommands found in ${fileCmds.cmdsRootPath}.)`
+      );
+      debugLog("Error reading file-based commands:", _err);
+    }
+  } else {
+    const subCommandNames = [];
+    if (command.subCommands) {
+      for (const [name, spec] of Object.entries(command.subCommands)) {
+        try {
+          const cmd = await loadSubCommand(spec);
+          if (!cmd?.meta?.hidden) {
+            const aliasDisplay = cmd.meta.aliases ? ` (aliases: ${cmd.meta.aliases.join(", ")})` : "";
+            subCommandNames.push(`${name}${aliasDisplay}`);
+          }
+        } catch (_err) {
+          debugLog(`Error loading subcommand ${name}:`, _err);
+        }
+      }
+    }
+    let usageLine = `Usage: ${command.meta.name}`;
+    if (subCommandNames.length > 0) {
+      usageLine += " <subCommand> [options]";
+    } else {
+      usageLine += ` [options] ${renderPositional(command.args)}`;
+    }
+    relinka("info", usageLine);
+    if (subCommandNames.length > 0) {
+      relinka("info", "\nAvailable subCommands:");
+      subCommandNames.forEach((sc) => relinka("info", `  ${sc}`));
+    }
+  }
+  relinka("info", "\nOptions:");
+  relinka("info", "  -h, --help       Show help");
+  relinka("info", "  -v, --version    Show version");
+  relinka("info", "  --debug          Enable debug mode");
+  for (const [key, def] of Object.entries(command.args || {})) {
+    if (def.type === "positional") {
+      relinka(
+        "info",
+        `  <${key}> : ${def.description || ""} ${def.required ? "(required)" : ""}`
+      );
+    } else {
+      relinka(
+        "info",
+        `  --${key} : ${def.description || ""} (type=${def.type})${def.required ? " (required)" : ""}${def.default !== void 0 ? ` [default: ${def.default}]` : ""}`
+      );
+    }
+  }
+}
+export async function runMain(command, parserOptions = {}) {
+  if (!parserOptions.fileBasedCmds && (!command.subCommands || Object.keys(command.subCommands).length === 0)) {
+    parserOptions.fileBasedCmds = {
+      enable: true,
+      cmdsRootPath: "src/cli/args"
+      // default path
+    };
+  }
+  const argv = process.argv.slice(2);
+  const autoExit = parserOptions.autoExit !== false;
+  if (checkHelp(argv)) {
+    await showUsage(command, parserOptions);
+    if (autoExit) process.exit(0);
+    return;
+  }
+  if (checkVersion(argv)) {
+    relinka("info", `${command.meta.name} v${command.meta.version || ""}`);
+    if (autoExit) process.exit(0);
+    return;
+  }
+  const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
+  if (fileBasedEnabled && argv.length > 0) {
+    const subName = argv.shift();
+    try {
+      await runFileBasedSubCmd(
+        subName,
+        parserOptions.fileBasedCmds,
+        parserOptions
+      );
+      if (autoExit) process.exit(0);
+      return;
+    } catch (err) {
+      relinka("error", "Error loading file-based subcommand:", err.message);
+      if (autoExit) process.exit(1);
+      throw err;
+    }
+  }
+  if (!fileBasedEnabled && command.subCommands && argv.length > 0) {
+    const maybeSub = argv[0];
+    let subSpec;
+    for (const [key, spec] of Object.entries(command.subCommands)) {
+      if (key === maybeSub) {
+        subSpec = spec;
+        break;
+      }
+      try {
+        const cmd = await loadSubCommand(spec);
+        if (cmd.meta.aliases?.includes(maybeSub)) {
+          subSpec = spec;
+          break;
+        }
+      } catch (_err) {
+        debugLog(`Error checking alias for subcommand ${key}:`, _err);
+      }
+    }
+    if (subSpec) {
+      argv.shift();
+      try {
+        await runSubCommand(subSpec, parserOptions);
+        if (autoExit) process.exit(0);
+        return;
+      } catch (err) {
+        relinka("error", "Error running subcommand:", err.message);
+        if (autoExit) process.exit(1);
+        throw err;
+      }
+    }
+  }
+  await runCommandWithArgs(command, argv, parserOptions);
+}
+function checkHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+function checkVersion(argv) {
+  return argv.includes("--version") || argv.includes("-v");
+}
+async function loadSubCommand(spec) {
+  if (typeof spec === "string") {
+    const mod = await import(spec);
+    if (!mod.default) {
+      throw new Error(`Subcommand module "${spec}" has no default export`);
+    }
+    return mod.default;
+  }
+  const imported = await spec();
+  if ("default" in imported && imported.default) {
+    return imported.default;
+  }
+  if (imported) {
+    return imported;
+  }
+  throw new Error("Subcommand import did not return a valid command");
+}
+async function runFileBasedSubCmd(subName, fileCmdOpts, parserOptions) {
+  const subPathDir = path.join(fileCmdOpts.cmdsRootPath, subName);
+  let importPath;
+  const possibleFiles = [
+    path.join(subPathDir, "index.js"),
+    path.join(subPathDir, "index.ts"),
+    path.join(subPathDir, `${subName}-mod.js`),
+    path.join(subPathDir, `${subName}-mod.ts`),
+    path.join(fileCmdOpts.cmdsRootPath, `${subName}.js`),
+    path.join(fileCmdOpts.cmdsRootPath, `${subName}.ts`),
+    path.join(fileCmdOpts.cmdsRootPath, `arg-${subName}.js`),
+    path.join(fileCmdOpts.cmdsRootPath, `arg-${subName}.ts`)
+  ];
+  const dirExists = await fs.pathExists(subPathDir);
+  let isDirCommand = false;
+  if (dirExists) {
+    const stats = await fs.stat(subPathDir);
+    isDirCommand = stats.isDirectory();
+  }
+  if (isDirCommand) {
+    for (const pattern of possibleFiles.slice(0, 4)) {
+      if (await fs.pathExists(pattern)) {
+        importPath = pattern;
+        break;
+      }
+    }
+    if (!importPath) {
+      throw new Error(
+        `No valid command file found in directory "${subName}". Expected one of: index.{js,ts} or ${subName}-mod.{js,ts}`
+      );
+    }
+  } else {
+    for (const pattern of possibleFiles.slice(4)) {
+      if (await fs.pathExists(pattern)) {
+        importPath = pattern;
+        break;
+      }
+    }
+    if (!importPath) {
+      throw new Error(
+        `No valid command file found for "${subName}". Expected one of: ${subName}.{js,ts} or arg-${subName}.{js,ts}`
+      );
+    }
+  }
+  const imported = await import(path.resolve(importPath));
+  const subCommand = imported.default;
+  if (!subCommand) {
+    throw new Error(
+      `File-based subcommand "${subName}" has no default export or is invalid.`
+    );
+  }
+  const argvRemaining = process.argv.slice(2);
+  await runCommandWithArgs(subCommand, argvRemaining, parserOptions);
+}
+async function runSubCommand(spec, parserOptions) {
+  const subCommand = await loadSubCommand(spec);
+  const argvRemaining = process.argv.slice(2);
+  await runCommandWithArgs(subCommand, argvRemaining, parserOptions);
+}
+async function runCommandWithArgs(command, argv, parserOptions) {
+  const autoExit = parserOptions.autoExit !== false;
+  const booleanKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "boolean"
+  );
+  const defaultMap = {};
+  for (const [argKey, def] of Object.entries(command.args || {})) {
+    if (def.default !== void 0) {
+      defaultMap[argKey] = def.default;
+    }
+  }
+  const mergedParserOptions = {
+    ...parserOptions,
+    boolean: [...parserOptions.boolean || [], ...booleanKeys],
+    defaults: { ...defaultMap, ...parserOptions.defaults || {} }
+  };
+  const parsed = reliArgParser(argv, mergedParserOptions);
+  debugLog("Parsed arguments:", parsed);
+  const finalArgs = {};
+  const positionalKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "positional"
+  );
+  const leftoverPositionals = [...parsed._ || []];
+  for (let i = 0; i < positionalKeys.length; i++) {
+    const key = positionalKeys[i];
+    const def = command.args?.[key];
+    const val = leftoverPositionals[i];
+    if (val == null && def.required) {
+      relinka("error", `Missing required positional argument: <${key}>`);
+      await showUsage(command, parserOptions);
+      if (autoExit) process.exit(1);
+      else throw new Error(`Missing required positional argument: <${key}>`);
+    }
+    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+  }
+  const otherKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type !== "positional"
+  );
+  for (const key of otherKeys) {
+    const def = command.args?.[key];
+    let rawVal = parsed[key];
+    if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
+      rawVal = [rawVal];
+    }
+    if (rawVal == null && def.required) {
+      relinka("error", `Missing required argument: --${key}`);
+      await showUsage(command, parserOptions);
+      if (autoExit) process.exit(1);
+      else throw new Error(`Missing required argument: --${key}`);
+    }
+    try {
+      finalArgs[key] = castArgValue(def, rawVal, key);
+    } catch (err) {
+      relinka("error", String(err));
+      if (autoExit) process.exit(1);
+      else throw err;
+    }
+  }
+  const ctx = {
+    args: finalArgs,
+    raw: argv
+  };
+  try {
+    await command.run(ctx);
+  } catch (err) {
+    relinka("error", `Error while executing command:
+${String(err)}`);
+    if (autoExit) process.exit(1);
+    else throw err;
+  }
+}
+function castArgValue(def, rawVal, argName) {
+  if (rawVal == null) {
+    return def.default ?? void 0;
+  }
+  switch (def.type) {
+    case "boolean":
+      if (typeof rawVal === "string") {
+        const lower = rawVal.toLowerCase();
+        if (lower === "true") return true;
+        if (lower === "false") return false;
+      }
+      return Boolean(rawVal);
+    case "string":
+      return typeof rawVal === "string" ? rawVal : String(rawVal);
+    case "number": {
+      const n = Number(rawVal);
+      if (Number.isNaN(n)) {
+        throw new Error(`Invalid number provided for --${argName}: ${rawVal}`);
+      }
+      return n;
+    }
+    case "positional":
+      return String(rawVal);
+    case "array":
+      return Array.isArray(rawVal) ? rawVal : [String(rawVal)];
+    default:
+      return rawVal;
+  }
+}
+function renderPositional(args) {
+  const positionalKeys = Object.keys(args || {}).filter(
+    (k) => args[k].type === "positional"
+  );
+  return positionalKeys.map((k) => `<${k}>`).join(" ");
+}

package/bin/core-impl/msg-fmt/colors.d.ts

@@ -0,0 +1,30 @@
+import type { ColorName, OutputColor, StandardColor } from "../../core-types.js";
+/**
+ * Maps complex colors (gradients, bright, background) to standard terminal colors.
+ * Used by ora spinners and other terminal utilities that only support basic colors.
+ *
+ * Handles:
+ * - Gradient colors -> solid colors (e.g., retroGradient -> cyan)
+ * - Bright colors -> base colors (e.g., redBright -> red)
+ * - Background colors -> foreground colors (e.g., bgRed -> red)
+ * - Special colors -> undefined (reset, inverse, dim, none)
+ *
+ * @param color The complex color to convert
+ * @returns A standard terminal color or undefined for special colors
+ */
+export declare function toBaseColor(color?: ColorName): StandardColor | undefined;
+/**
+ * Maps any color type to a standard solid color for consistent display.
+ * Similar to toBaseColor but always returns a color (never undefined).
+ *
+ * Handles:
+ * - Gradient colors -> solid colors (e.g., retroGradient -> cyan)
+ * - Bright colors -> base colors (e.g., redBright -> red)
+ * - Background colors -> foreground colors (e.g., bgRed -> red)
+ * - Special colors (reset, inverse, none) -> dim
+ * - Undefined -> dim
+ *
+ * @param color The color to convert
+ * @returns A standard terminal color, defaulting to "dim" for special cases
+ */
+export declare function toSolidColor(color?: ColorName): OutputColor;

package/bin/core-impl/msg-fmt/colors.js

@@ -0,0 +1,42 @@
+const GRADIENT_COLOR_MAP = {
+  retroGradient: "cyan",
+  viceGradient: "green",
+  gradientGradient: "blue",
+  rainbowGradient: "blue",
+  cristalGradient: "blue",
+  mindGradient: "blue",
+  passionGradient: "blue"
+};
+const SPECIAL_COLORS = ["reset", "inverse", "none"];
+function stripBrightModifier(color) {
+  return color.replace("Bright", "");
+}
+function stripBgModifier(color) {
+  return color.replace("bg", "").toLowerCase();
+}
+function stripColorModifiers(color) {
+  if (color.includes("Bright")) {
+    return stripBrightModifier(color);
+  }
+  if (color.startsWith("bg")) {
+    return stripBgModifier(color);
+  }
+  return color;
+}
+export function toBaseColor(color) {
+  if (!color || color === "dim" || SPECIAL_COLORS.includes(color)) {
+    return void 0;
+  }
+  if (color in GRADIENT_COLOR_MAP) {
+    return GRADIENT_COLOR_MAP[color];
+  }
+  if (color.includes("Bright") || color.startsWith("bg")) {
+    const baseColor = stripColorModifiers(color);
+    return baseColor;
+  }
+  return color;
+}
+export function toSolidColor(color) {
+  const baseColor = toBaseColor(color);
+  return baseColor ?? "dim";
+}

package/bin/core-impl/msg-fmt/logger.d.ts

@@ -0,0 +1,17 @@
+import type { AllKinds, StreamOptions } from "../../core-types.js";
+/**
+ * Logs messages with configurable styling and formatting.
+ * Doesn't support streaming functionality.
+ */
+export declare function relinkaByRemptsDeprecated(kind: AllKinds, title: string, content?: string, hint?: string): void;
+/**
+ * Asynchronous version of relinka that supports streaming functionality.
+ * Use this when you want animated text output with optional spinner.
+ *
+ * Streaming is controlled by the streamOpts parameter:
+ * - Use { useSpinner: true } for spinner animation
+ * - Use { delay: number } for character-by-character streaming
+ * - Content and hint are optional regardless of streaming
+ */
+export declare const relinkaAsyncByRemptsDeprecated: (kind: AllKinds, title: string, content?: string, hint?: string, streamOpts?: StreamOptions) => Promise<void>;
+export declare const throwError: (error: unknown) => never;

package/bin/core-impl/msg-fmt/logger.js

@@ -0,0 +1,106 @@
+import {
+  streamText,
+  streamTextWithSpinner
+} from "../utils/stream-text.js";
+import { toSolidColor } from "./colors.js";
+import { msg } from "./messages.js";
+const verboseLogging = false;
+const MESSAGE_CONFIGS = {
+  log: {
+    type: "M_INFO",
+    titleColor: "retroGradient",
+    titleTypography: "bold"
+  },
+  info: {
+    type: "M_INFO",
+    titleColor: "retroGradient",
+    titleTypography: "bold"
+  },
+  success: {
+    type: "M_INFO",
+    titleColor: "viceGradient",
+    titleTypography: "bold"
+  },
+  warn: {
+    type: "M_ERROR",
+    titleColor: "yellowBright",
+    titleTypography: "bold"
+  },
+  error: {
+    type: "M_ERROR",
+    titleColor: "yellowBright",
+    titleTypography: "bold"
+  }
+};
+export function relinkaByRemptsDeprecated(kind, title, content, hint) {
+  const isVerbose = kind.endsWith("-verbose");
+  const baseKind = isVerbose ? kind.replace("-verbose", "") : kind;
+  if (isVerbose && !verboseLogging) {
+    return;
+  }
+  const config = MESSAGE_CONFIGS[baseKind];
+  msg({
+    ...config,
+    title: isVerbose ? `[debug] ${title}` : title,
+    content: content ?? "",
+    contentColor: "dim",
+    contentTypography: "italic",
+    hint: hint ?? ""
+  });
+}
+export const relinkaAsyncByRemptsDeprecated = async (kind, title, content, hint, streamOpts) => {
+  const isVerbose = kind.endsWith("-verbose");
+  const baseKind = isVerbose ? kind.replace("-verbose", "") : kind;
+  if (isVerbose && !verboseLogging) {
+    return;
+  }
+  const config = MESSAGE_CONFIGS[baseKind];
+  if (!streamOpts) {
+    msg({
+      ...config,
+      title: isVerbose ? `[debug] ${title}` : title,
+      content: content ?? "",
+      contentColor: "dim",
+      contentTypography: "italic",
+      hint: hint ?? ""
+    });
+    return;
+  }
+  const titleText = isVerbose ? `[debug] ${title}` : title;
+  if (streamOpts.useSpinner) {
+    await streamTextWithSpinner({
+      text: titleText,
+      color: toSolidColor(config.titleColor),
+      delay: streamOpts.delay,
+      spinnerFrames: streamOpts.spinnerFrames,
+      spinnerDelay: streamOpts.spinnerDelay
+    });
+  } else {
+    await streamText({
+      text: titleText,
+      color: toSolidColor(config.titleColor),
+      delay: streamOpts.delay
+    });
+  }
+  if (content) {
+    await streamText({
+      text: content,
+      color: toSolidColor(config.contentColor) ?? "dim",
+      delay: streamOpts.delay
+    });
+  }
+  if (hint) {
+    await streamText({
+      text: hint,
+      color: "dim",
+      delay: streamOpts.delay
+    });
+  }
+};
+export const throwError = (error) => {
+  msg({
+    type: "M_ERROR",
+    title: error instanceof Error ? `\u{1F914} Failed to set up the project: ${error.message}` : "\u{1F914} An unknown error occurred."
+  });
+  process.exit(1);
+};

package/bin/core-impl/msg-fmt/mapping.d.ts

@@ -0,0 +1,3 @@
+import type { ColorName, TypographyName } from "../../core-types.js";
+export declare const colorMap: Record<ColorName, (text: string) => string>;
+export declare const typographyMap: Record<TypographyName, (text: string) => string>;

package/bin/core-impl/msg-fmt/mapping.js

@@ -0,0 +1,49 @@
+import { re } from "@reliverse/relico";
+import gradient, { cristal, mind, passion, retro, vice } from "gradient-string";
+import { rainbow } from "gradient-string";
+export const colorMap = {
+  // @reliverse/relico
+  none: (text) => text,
+  reset: re.reset,
+  bgCyan: re.bgCyan,
+  bgCyanBright: re.bgCyanBright,
+  black: re.black,
+  blue: re.blue,
+  blueBright: re.blueBright,
+  cyan: re.cyan,
+  cyanBright: re.cyanBright,
+  dim: re.dim,
+  gray: re.gray,
+  green: re.green,
+  greenBright: re.greenBright,
+  inverse: (text) => re.bold(re.inverse(text)),
+  magenta: re.magenta,
+  magentaBright: re.magentaBright,
+  red: re.red,
+  redBright: re.redBright,
+  white: re.white,
+  yellow: re.yellow,
+  yellowBright: re.yellowBright,
+  // gradient-string
+  cristalGradient: cristal,
+  gradientGradient: gradient([
+    "red",
+    "yellow",
+    "green",
+    "cyan",
+    "blue",
+    "magenta"
+  ]),
+  mindGradient: mind,
+  passionGradient: passion,
+  rainbowGradient: rainbow,
+  retroGradient: retro,
+  viceGradient: vice
+};
+export const typographyMap = {
+  none: (text) => text,
+  bold: re.bold,
+  italic: re.italic,
+  strikethrough: re.strikethrough,
+  underline: re.underline
+};

package/bin/core-impl/msg-fmt/messages.d.ts

@@ -0,0 +1,35 @@
+import type { ColorName, FmtMsgOptions, Symbols } from "../../core-types.js";
+export declare const symbols: Symbols;
+/**
+ * Returns a colored vertical bar symbol. Prevents gradient colors for bars.
+ */
+export declare const bar: ({ borderColor, }?: {
+    borderColor?: ColorName;
+}) => string;
+/**
+ * Main formatter function: builds the final text output based on FmtMsgOptions.
+ */
+export declare function fmt(opts: FmtMsgOptions): {
+    text: string;
+    lineCount: number;
+};
+/**
+ * Logs a formatted message to the console and records how many lines it occupies.
+ */
+export declare function msg(opts: FmtMsgOptions): void;
+/**
+ * Undo the last printed message by deleting its lines from the terminal.
+ * @param count How many messages to undo. Defaults to 1.
+ */
+export declare function msgUndo(count?: number): void;
+/**
+ * Undo all printed messages so far.
+ */
+export declare function msgUndoAll(): void;
+/**
+ * Prints:  "│  <text>"  (two spaces after the bar).
+ * If text is empty, it just prints "│".
+ * If indent is 1, it prints "│ <text>" (one space).
+ * If indent is 2, it prints "│  <text>" (two spaces), etc.
+ */
+export declare function printLineBar(text: string, indent?: number): void;