@cmdwuzntfnd/bitecli 0.1.20

package/template/src/libs/i18n.ts

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import path from "node:path";
+import { appState, createError } from "#meta";
+import type { LanguageStrings } from "#types";
+
+function normalizeLocaleString(
+  localeString: string | undefined | null,
+): string | null {
+  if (!localeString || typeof localeString !== "string") return null;
+  let cleaned = localeString.split(".")[0];
+  cleaned = cleaned.replace(/_/g, "-");
+  return cleaned;
+}
+
+const localeMap: Record<string, string> = {
+  "en-US": "English (United States)",
+}; // Add more here
+const supportedLocales = Object.keys(localeMap);
+const supportedLocaleSet = new Set(supportedLocales);
+
+const SPACE = "                   ";
+export function generateLocaleList(): string {
+  return Object.entries(localeMap)
+    .map(([code, name]) => `${SPACE}${code} — ${name}`)
+    .join("\n");
+}
+
+export function isValidLocale(locale: string): boolean {
+  return supportedLocaleSet.has(locale);
+}
+
+const languageToLocaleMap = new Map<string, string>();
+function findBestSupportedLocale(
+  localeString: string | undefined | null,
+): string | null {
+  const normalized = normalizeLocaleString(localeString);
+  if (!normalized) {
+    return null;
+  }
+
+  try {
+    const parsedInput = new Intl.Locale(normalized);
+
+    if (parsedInput.region) {
+      const exactTag = `${parsedInput.language}-${parsedInput.region}`;
+      if (supportedLocaleSet.has(exactTag)) {
+        return exactTag;
+      }
+    }
+    const language = normalized.split("-")[0];
+    if (languageToLocaleMap.size === 0) {
+      for (const locale of supportedLocales) {
+        const langPart = locale.split("-")[0];
+        if (!languageToLocaleMap.has(langPart)) {
+          languageToLocaleMap.set(langPart, locale);
+        }
+      }
+    }
+    return languageToLocaleMap.get(language) || null;
+  } catch {
+    return null;
+  }
+}
+
+function getUserLocale(): string | null {
+  const localePath = path.join(appState.STATE_DIR, "locale.json");
+  try {
+    const data = fs.readFileSync(localePath, "utf-8");
+    const { locale } = JSON.parse(data) as { locale: string };
+
+    if (isValidLocale(locale)) {
+      return locale;
+    }
+  } catch {}
+  return null;
+}
+
+export function getLocale(): string {
+  const userSetLocale = getUserLocale();
+  if (userSetLocale) {
+    return userSetLocale;
+  }
+
+  const potentialLocaleSources: (string | undefined)[] = [
+    process.env.LC_ALL,
+    process.env.LC_MESSAGES,
+    process.env.LANG,
+    process.env.LANGUAGE,
+    Intl.DateTimeFormat().resolvedOptions().locale,
+  ];
+
+  const localeCandidates = potentialLocaleSources
+    .filter((s): s is string => !!s)
+    .flatMap((source) => source.split(/[:\s]+/));
+
+  const foundLocale = localeCandidates
+    .map(findBestSupportedLocale)
+    .find((l): l is string => !!l);
+
+  return foundLocale ?? "en-US";
+}
+
+async function loadLocaleFile(
+  locale: string,
+): Promise<Partial<LanguageStrings> | null> {
+  try {
+    const module = (await import(`#i18nj/${locale}`, {
+      with: { type: "json" },
+    })) as { default: Partial<LanguageStrings> };
+    return module.default;
+  } catch {
+    return null;
+  }
+}
+
+async function loadStrings(locale = "en-US"): Promise<LanguageStrings> {
+  const englishStrings = (await loadLocaleFile(
+    "en-US",
+  )) as LanguageStrings | null;
+  if (!englishStrings) {
+    throw createError(
+      "English language file (en-US.json) could not be loaded.",
+      { code: "LANGUAGE_LOAD_FAILED" },
+    );
+  }
+
+  if (locale === "en-US") {
+    return englishStrings;
+  }
+
+  const localeStrings = await loadLocaleFile(locale);
+  return localeStrings
+    ? ({ ...englishStrings, ...localeStrings } as LanguageStrings)
+    : englishStrings;
+}
+
+const currentLocale = getLocale();
+export const strings = await loadStrings(currentLocale);

package/template/src/libs/meta.ts

@@ -0,0 +1,399 @@
+import fs from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import type {
+  NumConstraints,
+  StrConstraints,
+  HelpSection,
+  GenericHelpSection,
+  CommandConstructor,
+} from "#types";
+
+function findProjectRoot(startDir: string): string {
+  let currentDir = startDir;
+  while (true) {
+    const packageJsonPath = path.join(currentDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) return currentDir;
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      throw new Error("Could not find project root.");
+    }
+    currentDir = parentDir;
+  }
+}
+
+const FILENAME = fileURLToPath(import.meta.url);
+const DIRNAME = path.dirname(FILENAME);
+export const PROJECT_ROOT = findProjectRoot(DIRNAME);
+
+const packageJsonPath = path.join(PROJECT_ROOT, "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath).toString());
+
+export const FILES_TO_KEEP = ["defaultvals.js", "locale.json"];
+export const P_NAME = packageJson.name;
+export const P_VERSION = packageJson.version;
+export const P_AUTHOR = packageJson.author;
+export const P_CONTACT_URL = packageJson.url;
+
+const home = homedir();
+export function getStateDirPath() {
+  switch (process.platform) {
+    case "win32": {
+      const appDataPath = process.env.APPDATA;
+      if (appDataPath) {
+        return path.join(appDataPath, P_NAME);
+      }
+      return path.join(home, "AppData", "Roaming", P_NAME);
+    }
+    case "linux": {
+      const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+      if (xdgConfigHome) {
+        return path.join(xdgConfigHome, P_NAME);
+      }
+      return path.join(home, ".config", P_NAME);
+    }
+    case "darwin": {
+      return path.join(home, "Library", "Application Support", P_NAME);
+    }
+    default:
+      console.warn(
+        `Unsupported OS: ${process.platform}. The application may not behave appropriately regarding state storage.`,
+      );
+      return path.join(home, `.${P_NAME}`);
+  }
+}
+
+export const stateDirPath = getStateDirPath();
+
+export const appState = {
+  P_NAME: P_NAME,
+  P_VERSION: P_VERSION,
+  HOME_DIR: homedir(),
+  STATE_DIR: stateDirPath,
+  DEBUG_MODE: false,
+};
+export const setDebug = (): boolean => (appState.DEBUG_MODE = true);
+
+interface CreateErrorOptions {
+  cause?: unknown;
+  code?: string;
+  immediateExitCode?: boolean;
+}
+
+export interface NodeError extends Error {
+  code?: string;
+}
+
+export function isNodeError(error: unknown): error is NodeError {
+  return error instanceof Error;
+}
+
+export function isTypeError(error: unknown): error is TypeError {
+  return error instanceof TypeError;
+}
+
+export function isEnoentError(
+  error: unknown,
+): error is NodeError & { code: "ENOENT" } {
+  return isNodeError(error) && error.code === "ENOENT";
+}
+
+export function isEexistError(
+  error: unknown,
+): error is NodeError & { code: "EEXIST" } {
+  return isNodeError(error) && error.code === "EEXIST";
+}
+
+export function exitOne(): void {
+  if (process.env.NODE_ENV !== "test") {
+    process.exitCode = 1;
+  }
+}
+
+export function createError(
+  message: string,
+  options: CreateErrorOptions = {},
+): Error {
+  const { cause, code, immediateExitCode = true } = options;
+  const newError = new Error(message, { cause });
+
+  if (code) {
+    (newError as NodeError).code = code;
+  } else if (isNodeError(cause) && cause.code) {
+    (newError as NodeError).code = cause.code;
+  }
+
+  if (process.env.NODE_ENV !== "test" && immediateExitCode) {
+    process.exitCode = 1;
+  }
+
+  return newError;
+}
+
+export const V = {
+  num:
+    (
+      constraints: NumConstraints,
+      errorMsg: string,
+      errorCode: string,
+      errorPlaceholder = "{{ .Value }}",
+      secondaryCheck?: { fn: (v: number) => boolean },
+      secondaryErrorMsg?: string,
+      secondaryErrorCode?: string,
+      secondaryErrorPlaceholder?: string,
+    ) =>
+    (val: unknown) => {
+      if (
+        typeof val !== "number" ||
+        (!constraints.allowNaN && Number.isNaN(val))
+      ) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (constraints.integer && !Number.isInteger(val)) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (constraints.isFloat && Number.isInteger(val)) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (constraints.min !== undefined && val < constraints.min) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (constraints.max !== undefined && val > constraints.max) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (
+        constraints.minExclusive !== undefined &&
+        val <= constraints.minExclusive
+      ) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (
+        constraints.maxExclusive !== undefined &&
+        val >= constraints.maxExclusive
+      ) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (
+        secondaryCheck &&
+        secondaryErrorMsg &&
+        secondaryErrorCode &&
+        secondaryErrorPlaceholder &&
+        !secondaryCheck.fn(val)
+      ) {
+        throw createError(
+          secondaryErrorMsg.replace(secondaryErrorPlaceholder, String(val)),
+          { code: secondaryErrorCode },
+        );
+      }
+    },
+
+  str:
+    (
+      constraints: StrConstraints,
+      errorMsg: string,
+      errorCode: string,
+      errorPlaceholder = "{{ .Value }}",
+      secondaryCheck?: { fn: (v: string) => boolean },
+      secondaryErrorMsg?: string,
+      secondaryErrorCode?: string,
+      secondaryErrorPlaceholder?: string,
+    ) =>
+    (val: unknown) => {
+      if (typeof val !== "string") {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (constraints.notEmpty && val.trim() === "") {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+      if (
+        secondaryCheck &&
+        secondaryErrorMsg &&
+        secondaryErrorCode &&
+        secondaryErrorPlaceholder &&
+        !secondaryCheck.fn(val)
+      ) {
+        throw createError(
+          secondaryErrorMsg.replace(secondaryErrorPlaceholder, String(val)),
+          { code: secondaryErrorCode },
+        );
+      }
+    },
+  bool:
+    (
+      constraints: { strictTrueFalse?: boolean } = {},
+      errorMsg: string,
+      errorCode: string,
+      errorPlaceholder = "{{ .Value }}",
+    ) =>
+    (val: unknown) => {
+      const isBoolean = typeof val === "boolean";
+      const isStrict = constraints.strictTrueFalse;
+
+      if (isStrict && !isBoolean) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+
+      if (!isStrict && typeof val !== "boolean" && val !== 0 && val !== 1) {
+        throw createError(errorMsg.replace(errorPlaceholder, String(val)), {
+          code: errorCode,
+        });
+      }
+    },
+  getValueFromArray:
+    <T>(
+      errorMsg: string,
+      errorCode: string,
+      errorPlaceholder = "{{ .optionValue }}",
+    ) =>
+    (optionValue: unknown): T => {
+      if (!Array.isArray(optionValue) || optionValue.length < 2) {
+        throw createError(
+          errorMsg.replace(errorPlaceholder, String(optionValue)),
+          { code: errorCode },
+        );
+      }
+      return optionValue[1] as T;
+    },
+  getDelaySeconds: (seconds: unknown): number => {
+    if (typeof seconds !== "number" && typeof seconds !== "string") {
+      throw new TypeError("Delay must be a number or string");
+    }
+    return Math.round(parseFloat(String(seconds)) * 1000);
+  },
+};
+
+function simpleTemplate(str: string, data: Record<string, string>): string {
+  if (!data) return str;
+  return str.replace(/\{\{\s*\.(.*?)\s*\}\}/g, (_, key) => data[key] ?? "");
+}
+
+export function generateHelpText(
+  helpSection: HelpSection,
+  optionsConfig: CommandConstructor["options"],
+  replacements: Record<string, string> = {},
+): string {
+  const lines: string[] = [];
+
+  lines.push(helpSection.usage);
+  lines.push(`\n${helpSection.description}`);
+
+  if (helpSection.flags && optionsConfig) {
+    lines.push("\nOptions:");
+
+    const flagLines = Object.entries(optionsConfig).map(
+      ([longName, config]) => {
+        const parts: string[] = [];
+        if (config.short) {
+          parts.push(`-${config.short},`);
+        }
+        parts.push(`--${longName}`);
+        if (config.type === "string") {
+          parts.push("<value>");
+        }
+
+        const flagPart = `  ${parts.join(" ")}`;
+        const description = helpSection.flags?.[longName] ?? "";
+
+        return { flagPart, description };
+      },
+    );
+
+    const longestFlagPart = Math.max(
+      ...flagLines.map((f) => f.flagPart.length),
+    );
+    const padding = 2;
+
+    flagLines.forEach(({ flagPart, description }) => {
+      const requiredPadding = longestFlagPart - flagPart.length + padding;
+      lines.push(`${flagPart}${" ".repeat(requiredPadding)}${description}`);
+    });
+  }
+
+  if (helpSection.footer) {
+    lines.push(`\n${helpSection.footer}`);
+  }
+
+  const rawText = lines.join("\n");
+  return simpleTemplate(rawText, replacements);
+}
+
+export function generateGenericHelpText(
+  helpSection: GenericHelpSection,
+): string {
+  const lines: string[] = [];
+
+  const commandParts = Object.keys(helpSection.commandDescriptions).map(
+    (cmd) => `  ${cmd}`,
+  );
+  const flagParts = Object.keys(helpSection.flags).map((flag) => `  --${flag}`);
+  const allLeftParts = [...commandParts, ...flagParts];
+
+  const longestPart = Math.max(...allLeftParts.map((p) => p.length));
+  const padding = 4;
+
+  lines.push(helpSection.header);
+  lines.push(`\n${helpSection.usage}`);
+
+  lines.push(`\n${helpSection.commandHeader}`);
+  Object.entries(helpSection.commandDescriptions).forEach(([cmd, desc]) => {
+    const cmdPart = `  ${cmd}`;
+    const requiredPadding = longestPart - cmdPart.length + padding;
+    lines.push(`${cmdPart}${" ".repeat(requiredPadding)}${desc}`);
+  });
+
+  lines.push(`\n${helpSection.footer}`);
+
+  lines.push(`\n${helpSection.globalOptionsHeader}`);
+  Object.entries(helpSection.flags).forEach(([flag, desc]) => {
+    const flagPart = `  --${flag}`;
+    const requiredPadding = longestPart - flagPart.length + padding;
+    lines.push(`${flagPart}${" ".repeat(requiredPadding)}${desc}`);
+  });
+
+  return lines.join("\n");
+}
+
+const isInteractive = process.stdout.isTTY;
+const noop = (text: string): string => text;
+export const red = isInteractive
+  ? (text: string) => `\x1b[31m${text}\x1b[0m`
+  : noop;
+export const yellow = isInteractive
+  ? (text: string) => `\x1b[33m${text}\x1b[0m`
+  : noop;
+export const yellowBright = isInteractive
+  ? (text: string) => `\x1b[93m${text}\x1b[0m`
+  : noop;
+export const blue = isInteractive
+  ? (text: string) => `\x1b[34m${text}\x1b[0m`
+  : noop;
+
+// Maps command aliases to their module filenames in src/commands/
+export const commandConfig: Record<string, string> = {
+  help: "helpcommand",
+  cfg: "configcommand",
+  co: "cocommand",
+  hello: "hellocommand",
+};

package/template/src/libs/types/types.ts

@@ -0,0 +1,59 @@
+import type { parseArgs } from "node:util";
+// Import the JSON type definition for the default language (en-US)
+import type enUS from "#i18nj/en-US";
+
+// Base interface for all command classes
+export interface Command {
+  execute(argv: string[]): Promise<number | void>;
+}
+
+// Type for dynamically imported command modules
+export type CommandModule = {
+  default: new () => Command;
+};
+
+// Defines the bash completion type for positional arguments (for the `co` command)
+export type PositionalCompletion = "file" | "directory" | "none";
+
+// Describes the static properties required on a command class constructor
+export interface CommandConstructor {
+  new (): Command;
+  // Configuration for node:util.parseArgs
+  options: NonNullable<Parameters<typeof parseArgs>[0]>["options"];
+  allowPositionals?: boolean;
+  positionalCompletion?: PositionalCompletion;
+}
+
+// Constraints for numeric and string arguments
+export type NumConstraints = {
+  min?: number;
+  max?: number;
+  minExclusive?: number;
+  maxExclusive?: number;
+  integer?: boolean;
+  isFloat?: boolean;
+  allowNaN?: boolean;
+};
+export type StrConstraints = { notEmpty?: boolean };
+
+// Structure for help text sections used by generateHelpText
+export interface HelpSection {
+  usage: string;
+  description: string;
+  flags?: Record<string, string>;
+  footer?: string;
+}
+
+// Structure for the main `help` command's text
+export interface GenericHelpSection {
+  header: string;
+  usage: string;
+  commandHeader: string;
+  commandDescriptions: Record<string, string>;
+  footer: string;
+  globalOptionsHeader: string;
+  flags: Record<string, string>;
+}
+
+// Type definition for the i18n JSON file structure
+export type LanguageStrings = typeof enUS;

package/template/src/templatevals.ts

@@ -0,0 +1,2 @@
+// An example of a customizable string value.
+export const GREETING = "Hello";

package/template/tests/commands.test.js

@@ -0,0 +1,19 @@
+// when in doubt, just throw the misc stuff here
+import assert from "node:assert/strict";
+import { suite, test } from "node:test";
+import * as utils from "#testutils";
+
+suite("basic sanity checks", () => {
+  test("Command classes", async (t) => {
+    await t.test("HelpCommand shows generic help", async () => {
+      process.env.LC_ALL = "en_US.UTF-8";
+      process.env.LANG = "en_US.UTF-8";
+      const { default: HelpCommand } = await import("#commands/helpcommand");
+      const output = await utils.withCapturedConsole(async () => {
+        const command = new HelpCommand();
+        await command.execute(["help"]);
+      });
+      assert.match(output, /A tool for/);
+    });
+  });
+});

package/template/tests/testutils.js

@@ -0,0 +1,13 @@
+export async function withCapturedConsole(fn) {
+  const originalLog = console.log;
+  let output = "";
+  console.log = (...args) => {
+    output += args.join(" ") + "\n";
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = originalLog;
+  }
+  return output;
+}

package/template/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "baseUrl": "./src",
+    "paths": {
+      "#app": ["./bitecli.ts"],
+      "#defaultvals": ["./defaultvals.ts"],
+      "#templatevals": ["./templatevals.ts"],
+      "#meta": ["./libs/meta.ts"],
+      "#i18n": ["./libs/i18n.ts"],
+      "#commands/*": ["./commands/*.ts"],
+      "#i18nj/*": ["../data/i18n/*.json"],
+      "#types": ["./libs/types/types.ts"]
+    },
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "tests"]
+}