@danielarndt0/brutils-cli 1.1.0

package/dist/cli.js

@@ -0,0 +1,3346 @@
+#!/usr/bin/env node
+
+// src/cli/create-program.ts
+import { Command } from "commander";
+
+// src/services/zip/resolve-zip-output.ts
+import path from "path";
+function resolveZipOutputPath(sourcePath, explicitOut) {
+  if (explicitOut) {
+    return explicitOut;
+  }
+  const normalizedSource = path.resolve(sourcePath);
+  const parsed = path.parse(normalizedSource);
+  if (path.basename(normalizedSource) === ".") {
+    const cwd = process.cwd();
+    return path.join(cwd, `${path.basename(cwd)}.zip`);
+  }
+  if (parsed.ext) {
+    return path.join(parsed.dir, `${parsed.name}.zip`);
+  }
+  return path.join(parsed.dir, `${parsed.base}.zip`);
+}
+
+// src/services/zip/collect-zip-inputs.ts
+import fs from "fs";
+import path2 from "path";
+import fg from "fast-glob";
+
+// src/core/errors/brutils.error.ts
+var BRUtilsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BRUtilsError";
+  }
+};
+
+// src/services/zip/collect-zip-inputs.ts
+function normalizeEntryName(value) {
+  return value.replace(/\\/g, "/");
+}
+function isDirectory(sourcePath) {
+  return fs.statSync(sourcePath).isDirectory();
+}
+function isFile(sourcePath) {
+  return fs.statSync(sourcePath).isFile();
+}
+function collectZipInputs(sourcePath, outputPath, options = {}) {
+  const resolvedSource = path2.resolve(sourcePath);
+  if (!fs.existsSync(resolvedSource)) {
+    throw new BRUtilsError(`Source path does not exist: ${sourcePath}`);
+  }
+  if (isFile(resolvedSource)) {
+    return [
+      {
+        type: "file",
+        sourcePath: resolvedSource,
+        entryName: path2.basename(resolvedSource)
+      }
+    ];
+  }
+  if (!isDirectory(resolvedSource)) {
+    throw new BRUtilsError(`Unsupported source type: ${sourcePath}`);
+  }
+  const excludePatterns = options.exclude ?? [];
+  const outputAbsolutePath = path2.resolve(outputPath);
+  const rootEntryName = path2.basename(resolvedSource);
+  const entries = fg.sync(["**/*", "**/.*"], {
+    cwd: resolvedSource,
+    onlyFiles: false,
+    onlyDirectories: false,
+    dot: true,
+    followSymbolicLinks: options.followSymlinks ?? false,
+    unique: true,
+    ignore: excludePatterns,
+    markDirectories: true
+  });
+  if (entries.length === 0) {
+    return options.contentsOnly ? [] : [
+      {
+        type: "directory",
+        sourcePath: resolvedSource,
+        entryName: `${rootEntryName}/`
+      }
+    ];
+  }
+  return entries.map((entry) => {
+    const cleanedEntry = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    const absoluteEntryPath = path2.join(resolvedSource, cleanedEntry);
+    if (path2.resolve(absoluteEntryPath) === outputAbsolutePath) {
+      return null;
+    }
+    const relativeEntryName = options.contentsOnly ? cleanedEntry : path2.join(rootEntryName, cleanedEntry);
+    const entryType = entry.endsWith("/") ? "directory" : "file";
+    return {
+      type: entryType,
+      sourcePath: absoluteEntryPath,
+      entryName: normalizeEntryName(
+        entryType === "directory" ? `${relativeEntryName}/` : relativeEntryName
+      )
+    };
+  }).filter((entry) => entry !== null);
+}
+
+// src/services/zip/create-zip.ts
+import fs2 from "fs";
+import path3 from "path";
+import archiver from "archiver";
+function resolveCompressionLevel(level) {
+  const resolvedLevel = level ?? 9;
+  if (!Number.isInteger(resolvedLevel) || resolvedLevel < 0 || resolvedLevel > 9) {
+    throw new BRUtilsError(
+      "Compression level must be an integer between 0 and 9."
+    );
+  }
+  return resolvedLevel;
+}
+function getSourceType(sourcePath) {
+  return fs2.statSync(sourcePath).isDirectory() ? "directory" : "file";
+}
+function ensureOutputCanBeWritten(outputPath, force = false) {
+  if (fs2.existsSync(outputPath) && !force) {
+    throw new BRUtilsError(
+      `Output file already exists: ${outputPath}. Use --force to overwrite it.`
+    );
+  }
+  fs2.mkdirSync(path3.dirname(outputPath), { recursive: true });
+}
+function createZipExecutionPlan(sourcePath, positionalOut, options = {}) {
+  if (positionalOut && options.out) {
+    throw new BRUtilsError("Use either positional [out] or --out, not both.");
+  }
+  const resolvedOutputPath = path3.resolve(
+    resolveZipOutputPath(sourcePath, positionalOut ?? options.out)
+  );
+  return {
+    sourcePath: path3.resolve(sourcePath),
+    outputPath: resolvedOutputPath,
+    sourceType: getSourceType(path3.resolve(sourcePath)),
+    exclude: options.exclude ?? [],
+    contentsOnly: options.contentsOnly ?? false,
+    level: resolveCompressionLevel(options.level),
+    followSymlinks: options.followSymlinks ?? false,
+    store: options.store ?? false
+  };
+}
+async function createZip(sourcePath, positionalOut, options = {}) {
+  const plan = createZipExecutionPlan(sourcePath, positionalOut, options);
+  if (options.dryRun) {
+    return plan;
+  }
+  ensureOutputCanBeWritten(plan.outputPath, options.force);
+  const outputStream = fs2.createWriteStream(plan.outputPath);
+  const archive = archiver("zip", {
+    zlib: { level: plan.store ? 0 : plan.level },
+    store: plan.store
+  });
+  await new Promise((resolve, reject) => {
+    outputStream.on("close", () => resolve());
+    archive.on("error", (error) => reject(error));
+    archive.pipe(outputStream);
+    const inputs = collectZipInputs(plan.sourcePath, plan.outputPath, options);
+    for (const input of inputs) {
+      if (options.verbose && !options.quiet) {
+        console.log(`[zip] adding ${input.entryName}`);
+      }
+      if (input.type === "directory") {
+        archive.append("", { name: input.entryName });
+      } else {
+        archive.file(input.sourcePath, { name: input.entryName });
+      }
+    }
+    archive.finalize().catch(reject);
+  });
+  return plan;
+}
+
+// src/services/zip/list-zip.ts
+import path5 from "path";
+
+// src/services/archive/zip-archive.ts
+import fs3 from "fs";
+import path4 from "path";
+import { Writable } from "stream";
+import { pipeline } from "stream/promises";
+import yauzl from "yauzl";
+
+// src/core/utils/glob.ts
+import * as minimatchModule from "minimatch";
+function resolveMinimatch() {
+  const moduleValue = minimatchModule;
+  if (typeof moduleValue.minimatch === "function") {
+    return moduleValue.minimatch;
+  }
+  if (typeof moduleValue.default === "function") {
+    return moduleValue.default;
+  }
+  if (typeof moduleValue === "function") {
+    return moduleValue;
+  }
+  throw new Error("Could not resolve minimatch implementation.");
+}
+var minimatch = resolveMinimatch();
+function matchesGlob(input, pattern) {
+  return minimatch(input, pattern, { dot: true });
+}
+
+// src/services/archive/zip-archive.ts
+function normalizeEntryPath(entryPath) {
+  return entryPath.replace(/\\/g, "/");
+}
+function ensureZipSourceIsValid(sourcePath) {
+  if (!fs3.existsSync(sourcePath)) {
+    throw new BRUtilsError(`Zip file does not exist: ${sourcePath}`);
+  }
+  if (!fs3.statSync(sourcePath).isFile()) {
+    throw new BRUtilsError(`Source is not a file: ${sourcePath}`);
+  }
+  if (path4.extname(sourcePath).toLowerCase() !== ".zip") {
+    throw new BRUtilsError("Only .zip files are supported.");
+  }
+}
+function openZipFile(sourcePath) {
+  ensureZipSourceIsValid(sourcePath);
+  return new Promise((resolve, reject) => {
+    yauzl.open(
+      sourcePath,
+      {
+        lazyEntries: true,
+        decodeStrings: true,
+        validateEntrySizes: true
+      },
+      (error, zipFile) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        if (!zipFile) {
+          reject(new BRUtilsError("Could not open zip file."));
+          return;
+        }
+        resolve(zipFile);
+      }
+    );
+  });
+}
+function shouldIncludeEntry(entryPath, match) {
+  if (!match) {
+    return true;
+  }
+  return matchesGlob(normalizeEntryPath(entryPath), match);
+}
+async function listZipArchiveEntries(sourcePath, options = {}) {
+  const zipFile = await openZipFile(sourcePath);
+  return new Promise((resolve, reject) => {
+    const entries = [];
+    zipFile.on("entry", (entry) => {
+      const entryPath = normalizeEntryPath(entry.fileName);
+      if (shouldIncludeEntry(entryPath, options.match)) {
+        entries.push({
+          path: entryPath,
+          type: entryPath.endsWith("/") ? "directory" : "file",
+          compressedSize: entry.compressedSize,
+          uncompressedSize: entry.uncompressedSize
+        });
+      }
+      zipFile.readEntry();
+    });
+    zipFile.once("end", () => {
+      zipFile.close();
+      resolve(entries);
+    });
+    zipFile.once("error", (error) => {
+      zipFile.close();
+      reject(error);
+    });
+    zipFile.readEntry();
+  });
+}
+async function drainEntryStream(zipFile, entry) {
+  await new Promise((resolve, reject) => {
+    zipFile.openReadStream(entry, async (error, stream) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      if (!stream) {
+        reject(
+          new BRUtilsError(`Could not read archive entry: ${entry.fileName}`)
+        );
+        return;
+      }
+      try {
+        await pipeline(
+          stream,
+          new Writable({
+            write(_chunk, _encoding, callback) {
+              callback();
+            }
+          })
+        );
+        resolve();
+      } catch (streamError) {
+        reject(streamError);
+      }
+    });
+  });
+}
+async function testZipArchive(sourcePath, options = {}) {
+  const zipFile = await openZipFile(sourcePath);
+  let testedEntries = 0;
+  return new Promise((resolve, reject) => {
+    zipFile.on("entry", (entry) => {
+      const entryPath = normalizeEntryPath(entry.fileName);
+      void (async () => {
+        try {
+          if (!shouldIncludeEntry(entryPath, options.match) || entryPath.endsWith("/")) {
+            zipFile.readEntry();
+            return;
+          }
+          await drainEntryStream(zipFile, entry);
+          testedEntries += 1;
+          zipFile.readEntry();
+        } catch (error) {
+          zipFile.close();
+          reject(error);
+        }
+      })();
+    });
+    zipFile.once("end", () => {
+      zipFile.close();
+      resolve({
+        sourcePath: path4.resolve(sourcePath),
+        testedEntries,
+        ok: true
+      });
+    });
+    zipFile.once("error", (error) => {
+      zipFile.close();
+      reject(error);
+    });
+    zipFile.readEntry();
+  });
+}
+
+// src/services/zip/list-zip.ts
+async function listZip(sourcePath, match) {
+  return listZipArchiveEntries(
+    path5.resolve(sourcePath),
+    match ? { match } : {}
+  );
+}
+
+// src/services/zip/test-zip.ts
+import path6 from "path";
+async function testZip(sourcePath, match) {
+  return testZipArchive(path6.resolve(sourcePath), match ? { match } : {});
+}
+
+// src/services/unzip/resolve-unzip-output.ts
+import path7 from "path";
+function resolveUnzipOutputPath(sourcePath, explicitOut) {
+  if (explicitOut) {
+    return explicitOut;
+  }
+  const resolvedSource = path7.resolve(sourcePath);
+  const parsed = path7.parse(resolvedSource);
+  return path7.join(parsed.dir, parsed.name);
+}
+
+// src/services/unzip/extract-zip.ts
+import fs4 from "fs";
+import path8 from "path";
+import { pipeline as pipeline2 } from "stream/promises";
+import yauzl2 from "yauzl";
+function ensureOutputCanBeExtracted(outputDir, force = false) {
+  if (fs4.existsSync(outputDir) && !force) {
+    throw new BRUtilsError(
+      `Output directory already exists: ${outputDir}. Use --force to overwrite it.`
+    );
+  }
+  if (fs4.existsSync(outputDir) && force) {
+    fs4.rmSync(outputDir, { recursive: true, force: true });
+  }
+  fs4.mkdirSync(outputDir, { recursive: true });
+}
+function normalizeEntryPath2(entryPath) {
+  return entryPath.replace(/\\/g, "/");
+}
+function shouldIncludeEntry2(entryPath, match) {
+  if (!match) {
+    return true;
+  }
+  return matchesGlob(normalizeEntryPath2(entryPath), match);
+}
+function resolveTargetRelativePath(entryPath, flat) {
+  if (!flat) {
+    return normalizeEntryPath2(entryPath);
+  }
+  return path8.posix.basename(normalizeEntryPath2(entryPath));
+}
+function resolveSafeDestination(outputDir, relativePath) {
+  const destination = path8.resolve(outputDir, relativePath);
+  const resolvedOutputDir = path8.resolve(outputDir);
+  const outputPrefix = `${resolvedOutputDir}${path8.sep}`;
+  if (destination !== resolvedOutputDir && !destination.startsWith(outputPrefix)) {
+    throw new BRUtilsError(`Unsafe zip entry path detected: ${relativePath}`);
+  }
+  return destination;
+}
+function openZipFile2(sourcePath) {
+  ensureZipSourceIsValid(sourcePath);
+  return new Promise((resolve, reject) => {
+    yauzl2.open(
+      sourcePath,
+      {
+        lazyEntries: true,
+        decodeStrings: true,
+        validateEntrySizes: true
+      },
+      (error, zipFile) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        if (!zipFile) {
+          reject(new BRUtilsError("Could not open zip file."));
+          return;
+        }
+        resolve(zipFile);
+      }
+    );
+  });
+}
+function createUnzipExecutionPlan(sourcePath, positionalOut, options = {}) {
+  if (positionalOut && options.out) {
+    throw new BRUtilsError("Use either positional [out] or --out, not both.");
+  }
+  const resolvedSourcePath = path8.resolve(sourcePath);
+  const resolvedOutputDir = path8.resolve(
+    resolveUnzipOutputPath(sourcePath, positionalOut ?? options.out)
+  );
+  return {
+    sourcePath: resolvedSourcePath,
+    outputDir: resolvedOutputDir,
+    flat: options.flat ?? false,
+    ...options.match ? { match: options.match } : {}
+  };
+}
+async function extractZipFile(sourcePath, positionalOut, options = {}) {
+  const plan = createUnzipExecutionPlan(sourcePath, positionalOut, options);
+  ensureZipSourceIsValid(plan.sourcePath);
+  if (options.dryRun) {
+    return plan;
+  }
+  ensureOutputCanBeExtracted(plan.outputDir, options.force);
+  if (options.verbose && !options.quiet) {
+    console.log(`[unzip] extracting ${plan.sourcePath} -> ${plan.outputDir}`);
+  }
+  const zipFile = await openZipFile2(plan.sourcePath);
+  const flatTargets = /* @__PURE__ */ new Set();
+  await new Promise((resolve, reject) => {
+    zipFile.on("entry", (entry) => {
+      const entryPath = normalizeEntryPath2(entry.fileName);
+      void (async () => {
+        try {
+          if (!shouldIncludeEntry2(entryPath, options.match)) {
+            zipFile.readEntry();
+            return;
+          }
+          const isDirectory2 = entryPath.endsWith("/");
+          const targetRelativePath = resolveTargetRelativePath(
+            entryPath,
+            options.flat ?? false
+          );
+          if (!targetRelativePath) {
+            zipFile.readEntry();
+            return;
+          }
+          if ((options.flat ?? false) && flatTargets.has(targetRelativePath) && !isDirectory2) {
+            throw new BRUtilsError(
+              `Flat extraction would overwrite a file more than once: ${targetRelativePath}`
+            );
+          }
+          if ((options.flat ?? false) && !isDirectory2) {
+            flatTargets.add(targetRelativePath);
+          }
+          const destinationPath = resolveSafeDestination(
+            plan.outputDir,
+            targetRelativePath
+          );
+          if (options.verbose && !options.quiet) {
+            console.log(`[unzip] extracting ${entryPath}`);
+          }
+          if (isDirectory2) {
+            if (!(options.flat ?? false)) {
+              fs4.mkdirSync(destinationPath, { recursive: true });
+            }
+            zipFile.readEntry();
+            return;
+          }
+          fs4.mkdirSync(path8.dirname(destinationPath), { recursive: true });
+          await new Promise((entryResolve, entryReject) => {
+            zipFile.openReadStream(entry, async (error, stream) => {
+              if (error) {
+                entryReject(error);
+                return;
+              }
+              if (!stream) {
+                entryReject(
+                  new BRUtilsError(
+                    `Could not read archive entry: ${entry.fileName}`
+                  )
+                );
+                return;
+              }
+              try {
+                await pipeline2(stream, fs4.createWriteStream(destinationPath));
+                entryResolve();
+              } catch (streamError) {
+                entryReject(streamError);
+              }
+            });
+          });
+          zipFile.readEntry();
+        } catch (error) {
+          zipFile.close();
+          reject(error);
+        }
+      })();
+    });
+    zipFile.once("end", () => {
+      zipFile.close();
+      resolve();
+    });
+    zipFile.once("error", (error) => {
+      zipFile.close();
+      reject(error);
+    });
+    zipFile.readEntry();
+  });
+  return plan;
+}
+
+// src/services/unzip/list-unzip.ts
+import path9 from "path";
+async function listUnzip(sourcePath, match) {
+  return listZipArchiveEntries(
+    path9.resolve(sourcePath),
+    match ? { match } : {}
+  );
+}
+
+// src/services/unzip/test-unzip.ts
+import path10 from "path";
+async function testUnzip(sourcePath, match) {
+  return testZipArchive(path10.resolve(sourcePath), match ? { match } : {});
+}
+
+// src/cli/ui/theme.ts
+var colorsEnabled = process.stdout.isTTY && !process.argv.includes("--no-color") && process.env.NO_COLOR === void 0;
+function paint(code, value) {
+  if (!colorsEnabled) {
+    return value;
+  }
+  return `\x1B[${code}m${value}\x1B[0m`;
+}
+var theme = {
+  muted: (value) => paint(90, value),
+  red: (value) => paint(31, value),
+  green: (value) => paint(32, value),
+  yellow: (value) => paint(33, value),
+  blue: (value) => paint(34, value),
+  magenta: (value) => paint(35, value),
+  cyan: (value) => paint(36, value),
+  bold: (value) => paint(1, value),
+  section: (value) => paint(36, paint(1, value)),
+  command: (value) => paint(36, value),
+  flag: (value) => paint(33, value),
+  value: (value) => paint(32, value),
+  errorLabel: (value) => paint(31, paint(1, value)),
+  successLabel: (value) => paint(32, paint(1, value))
+};
+
+// src/cli/shared/help.ts
+function examples(lines) {
+  return `
+${theme.section("Examples")}
+${lines.map((line) => `  ${theme.command(line)}`).join("\n")}
+`;
+}
+function rootFooter() {
+  return `
+${theme.section("Quick start")}
+  ${theme.command("brutils <command> --help")}
+  ${theme.command("brutils <command> <action> --help")}
+
+${theme.section("Examples")}
+  ${theme.command("brutils cpf generate --formatted")}
+  ${theme.command('brutils str slug --text "Hello Cool World"')}
+  ${theme.command("brutils json format --file ./config.json --sort-keys")}
+  ${theme.command("brutils hash sha256 --text hello")}
+  ${theme.command("brutils id token --length 24 --charset base64url")}
+  ${theme.command("brutils date diff --from 2024-01-01T00:00:00Z --to 2024-01-03T00:00:00Z --unit days")}
+  ${theme.command("brutils random-number int --min 1 --max 60 --count 6 --unique --sorted")}
+  ${theme.command("brutils zip create ./folder --out ./backup.zip --force")}
+
+${theme.section("Tips")}
+  ${theme.muted("The official interface is the brutils command.")}
+  ${theme.muted("Use --no-color if you want plain output.")}
+  ${theme.muted("Use module-specific --help to see focused examples.")}
+`;
+}
+
+// src/cli/shared/parsers.ts
+import { InvalidArgumentError } from "commander";
+
+// src/cli/shared/constants.ts
+var BRAZILIAN_STATES = [
+  "AC",
+  "AL",
+  "AM",
+  "AP",
+  "BA",
+  "CE",
+  "DF",
+  "ES",
+  "GO",
+  "MA",
+  "MG",
+  "MS",
+  "MT",
+  "PA",
+  "PB",
+  "PE",
+  "PI",
+  "PR",
+  "RJ",
+  "RN",
+  "RO",
+  "RR",
+  "RS",
+  "SC",
+  "SE",
+  "SP",
+  "TO"
+];
+var CARD_BRANDS = ["visa", "mastercard", "amex", "elo"];
+var RANDOM_OUTPUT_FORMATS = ["plain", "json", "csv"];
+var STRING_CASE_STYLES = [
+  "camel",
+  "snake",
+  "kebab",
+  "pascal",
+  "constant",
+  "title"
+];
+var STRING_CODEC_MODES = ["encode", "decode"];
+var STRING_PAD_SIDES = ["left", "right", "both"];
+var CHARSET_NAMES = [
+  "alnum",
+  "alpha",
+  "numeric",
+  "hex",
+  "base64url",
+  "lower",
+  "upper"
+];
+var DATE_DIFF_UNITS = ["seconds", "minutes", "hours", "days"];
+
+// src/cli/shared/parsers.ts
+function parseInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw new InvalidArgumentError(`Expected an integer, received "${value}".`);
+  }
+  return parsed;
+}
+function parsePositiveInteger(value) {
+  const parsed = parseInteger(value);
+  if (parsed < 1) {
+    throw new InvalidArgumentError(
+      `Expected a positive integer, received "${value}".`
+    );
+  }
+  return parsed;
+}
+function parseNumber(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new InvalidArgumentError(
+      `Expected a numeric value, received "${value}".`
+    );
+  }
+  return parsed;
+}
+function parseState(value) {
+  const normalized = value.toUpperCase();
+  if (!BRAZILIAN_STATES.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid state "${value}". Use one of: ${BRAZILIAN_STATES.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseCardBrand(value) {
+  const normalized = value.toLowerCase();
+  if (!CARD_BRANDS.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid brand "${value}". Use one of: ${CARD_BRANDS.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseRandomFormat(value) {
+  const normalized = value.toLowerCase();
+  if (!RANDOM_OUTPUT_FORMATS.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid output format "${value}". Use one of: ${RANDOM_OUTPUT_FORMATS.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseStringCaseStyle(value) {
+  const normalized = value.toLowerCase();
+  if (!STRING_CASE_STYLES.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid string case style "${value}". Use one of: ${STRING_CASE_STYLES.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseStringCodecMode(value) {
+  const normalized = value.toLowerCase();
+  if (!STRING_CODEC_MODES.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid codec mode "${value}". Use one of: ${STRING_CODEC_MODES.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseStringPadSide(value) {
+  const normalized = value.toLowerCase();
+  if (!STRING_PAD_SIDES.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid pad side "${value}". Use one of: ${STRING_PAD_SIDES.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseCharsetName(value) {
+  const normalized = value.toLowerCase();
+  if (!CHARSET_NAMES.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid charset "${value}". Use one of: ${CHARSET_NAMES.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+function parseDateDiffUnit(value) {
+  const normalized = value.toLowerCase();
+  if (!DATE_DIFF_UNITS.includes(normalized)) {
+    throw new InvalidArgumentError(
+      `Invalid diff unit "${value}". Use one of: ${DATE_DIFF_UNITS.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+
+// src/cli/ui/output.ts
+function configureProgramUi(program) {
+  program.configureOutput({
+    writeErr: (str) => process.stderr.write(str),
+    outputError: (str, write) => {
+      write(theme.red(str));
+    }
+  });
+  program.configureHelp({
+    subcommandTerm: (cmd) => theme.command(cmd.name()),
+    optionTerm: (option) => theme.flag(option.flags)
+  });
+}
+function printValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    console.log(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.every(
+      (item) => typeof item === "string" || typeof item === "number"
+    )) {
+      console.log(value.join("\n"));
+      return;
+    }
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+function printRandomValues(values, format) {
+  if (format === "json") {
+    console.log(JSON.stringify(values, null, 2));
+    return;
+  }
+  if (format === "csv") {
+    console.log(values.join(","));
+    return;
+  }
+  console.log(values.join("\n"));
+}
+function handleCliError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`${theme.errorLabel("error")} ${message}`);
+  process.exit(1);
+}
+
+// src/cli/commands/register-archive.ts
+function registerArchiveCommands(program) {
+  const zip = program.command("zip").description("Create zip archives and inspect them.").addHelpText(
+    "after",
+    examples([
+      "brutils zip create ./folder",
+      "brutils zip create ./folder ./backup.zip",
+      "brutils zip create ./folder --out ./backup.zip --force",
+      "brutils zip create ./folder --contents-only --exclude node_modules --exclude dist",
+      'brutils zip list ./backup.zip --match "**/*.txt"',
+      "brutils zip test ./backup.zip"
+    ])
+  );
+  zip.command("create").alias("run").argument("<source>", "File or folder to archive.").argument("[out]", "Optional output .zip file path.").description("Create a zip archive from a source path.").option("-o, --out <path>", "Explicit output file path.").option(
+    "-l, --level <number>",
+    "Compression level from 0 to 9.",
+    parseInteger
+  ).option(
+    "-x, --exclude <glob...>",
+    "Glob patterns to exclude when zipping folder contents."
+  ).option(
+    "--contents-only",
+    "Zip only the folder contents instead of the folder root."
+  ).option("-f, --force", "Overwrite output if it already exists.").option(
+    "--dry-run",
+    "Print the execution plan without writing the archive."
+  ).option("-v, --verbose", "Show verbose archive creation logs.").option("-q, --quiet", "Suppress non-error output.").option(
+    "--follow-symlinks",
+    "Follow symbolic links while collecting inputs."
+  ).option("--store", "Store files without compression.").action(
+    async (source, out, options) => {
+      const plan = await createZip(source, out, options);
+      if (!options.quiet) {
+        printValue(plan);
+      }
+    }
+  );
+  zip.command("list").argument("<source>", "Existing .zip file to inspect.").description("List archive contents without extracting.").option("--match <pattern>", "Filter which archive entries are included.").option("-q, --quiet", "Suppress non-error output.").action(
+    async (source, options) => {
+      const result = await listZip(source, options.match);
+      if (!options.quiet) {
+        printValue(result);
+      }
+    }
+  );
+  zip.command("test").argument("<source>", "Existing .zip file to validate.").description("Test archive readability without extracting files.").option("--match <pattern>", "Filter which archive entries are included.").option("-q, --quiet", "Suppress non-error output.").action(
+    async (source, options) => {
+      const result = await testZip(source, options.match);
+      if (!options.quiet) {
+        printValue(result);
+      }
+    }
+  );
+  const unzip = program.command("unzip").description("Extract zip archives and inspect them.").addHelpText(
+    "after",
+    examples([
+      "brutils unzip extract ./backup.zip",
+      "brutils unzip extract ./backup.zip ./output",
+      "brutils unzip extract ./backup.zip --out ./output --force",
+      'brutils unzip extract ./backup.zip --flat --match "**/*.txt"',
+      "brutils unzip list ./backup.zip",
+      "brutils unzip test ./backup.zip"
+    ])
+  );
+  unzip.command("extract").alias("run").argument("<source>", "Existing .zip file to extract.").argument("[out]", "Optional destination directory.").description("Extract a zip archive.").option("-o, --out <path>", "Explicit output directory.").option(
+    "-f, --force",
+    "Overwrite the target directory if it already exists."
+  ).option("--dry-run", "Print the extraction plan without writing files.").option("-v, --verbose", "Show verbose extraction logs.").option("-q, --quiet", "Suppress non-error output.").option("--flat", "Extract files without preserving nested folders.").option("--match <pattern>", "Filter which archive entries are extracted.").action(
+    async (source, out, options) => {
+      const plan = await extractZipFile(source, out, options);
+      if (!options.quiet) {
+        printValue(plan);
+      }
+    }
+  );
+  unzip.command("list").argument("<source>", "Existing .zip file to inspect.").description("List archive contents without extracting.").option("--match <pattern>", "Filter which archive entries are included.").option("-q, --quiet", "Suppress non-error output.").action(
+    async (source, options) => {
+      const result = await listUnzip(source, options.match);
+      if (!options.quiet) {
+        printValue(result);
+      }
+    }
+  );
+  unzip.command("test").argument("<source>", "Existing .zip file to validate.").description("Test archive readability without extracting files.").option("--match <pattern>", "Filter which archive entries are included.").option("-q, --quiet", "Suppress non-error output.").action(
+    async (source, options) => {
+      const result = await testUnzip(source, options.match);
+      if (!options.quiet) {
+        printValue(result);
+      }
+    }
+  );
+}
+
+// src/core/utils/digits.ts
+function onlyDigits(value) {
+  return value.replace(/\D/g, "");
+}
+function allDigitsEqual(value) {
+  return /^(\d)\1+$/.test(value);
+}
+
+// src/services/cep/cep.shared.ts
+var CEP_STATE_LEADING_DIGIT_MAP = {
+  AC: [6],
+  AL: [5],
+  AM: [6],
+  AP: [6],
+  BA: [4],
+  CE: [6],
+  DF: [7],
+  ES: [2],
+  GO: [7],
+  MA: [6],
+  MG: [3],
+  MS: [7],
+  MT: [7],
+  PA: [6],
+  PB: [5],
+  PE: [5],
+  PI: [6],
+  PR: [8],
+  RJ: [2],
+  RN: [5],
+  RO: [7],
+  RR: [6],
+  RS: [9],
+  SC: [8],
+  SE: [4],
+  SP: [0, 1],
+  TO: [7]
+};
+function normalizeCEP(value) {
+  return onlyDigits(value);
+}
+function stripCEP(value) {
+  return normalizeCEP(value);
+}
+function ensureCEPLength(value) {
+  const digits = normalizeCEP(value);
+  if (digits.length !== 8)
+    throw new BRUtilsError("CEP must contain exactly 8 digits.");
+  return digits;
+}
+function resolveCEPLeadingDigits(state) {
+  return state ? CEP_STATE_LEADING_DIGIT_MAP[state] : void 0;
+}
+
+// src/core/utils/format.ts
+function formatCPF(value) {
+  return value.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
+}
+function formatCNPJ(value) {
+  return value.replace(/(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})/, "$1.$2.$3/$4-$5");
+}
+function formatCEP(value) {
+  return value.replace(/(\d{5})(\d{3})/, "$1-$2");
+}
+
+// src/services/cep/cep.formatter.ts
+function formatCEPValue(value) {
+  return formatCEP(ensureCEPLength(value));
+}
+
+// src/core/utils/mask.ts
+function applyDigitMask(value, pattern) {
+  let index = 0;
+  let result = "";
+  for (const token of pattern) {
+    if (token === "*") {
+      if (value[index] === void 0)
+        throw new BRUtilsError(
+          "Mask pattern consumes more digits than the input provides."
+        );
+      result += "*";
+      index += 1;
+      continue;
+    }
+    if (token === "#" || /\d/.test(token)) {
+      const digit = value[index];
+      if (digit === void 0)
+        throw new BRUtilsError(
+          "Mask pattern consumes more digits than the input provides."
+        );
+      result += digit;
+      index += 1;
+      continue;
+    }
+    result += token;
+  }
+  if (index != value.length)
+    throw new BRUtilsError(
+      `Mask pattern consumed ${index} digits, but the input has ${value.length}.`
+    );
+  return result;
+}
+
+// src/services/cep/cep.masker.ts
+var DEFAULT_CEP_MASK_PATTERN = "*****-###";
+function maskCEP(value, options = {}) {
+  return applyDigitMask(
+    ensureCEPLength(value),
+    options.pattern ?? DEFAULT_CEP_MASK_PATTERN
+  );
+}
+
+// src/core/utils/random.ts
+function randomDigit() {
+  return Math.floor(Math.random() * 10);
+}
+function randomDigits(length) {
+  return Array.from({ length }, () => randomDigit());
+}
+
+// src/services/cep/cep.generator.ts
+function generateCEP(options = {}) {
+  const stateLeadingDigits = resolveCEPLeadingDigits(options.state);
+  const firstDigit = stateLeadingDigits ? stateLeadingDigits[Math.floor(Math.random() * stateLeadingDigits.length)] : randomDigit();
+  const digits = [firstDigit, ...randomDigits(7)].join("");
+  return options.formatted ? formatCEP(digits) : digits;
+}
+function generateCEPBatch(options) {
+  const count = options.count;
+  if (!Number.isInteger(count) || count <= 0)
+    throw new BRUtilsError("Count must be a positive integer.");
+  return Array.from(
+    { length: count },
+    () => generateCEP({ formatted: options.formatted, state: options.state })
+  );
+}
+
+// src/services/cep/cep.validator.ts
+function validateCEP(value, options = {}) {
+  const digits = normalizeCEP(value);
+  const hasValidLength = digits.length === 8;
+  const passesStrictRules = !options.strict || !allDigitsEqual(digits);
+  return {
+    isValid: hasValidLength && passesStrictRules,
+    value: digits,
+    formatted: hasValidLength ? formatCEP(digits) : void 0
+  };
+}
+
+// src/services/cnpj/cnpj.shared.ts
+function normalizeCNPJ(value) {
+  return onlyDigits(value);
+}
+function stripCNPJ(value) {
+  return normalizeCNPJ(value);
+}
+function ensureCNPJLength(value) {
+  const digits = normalizeCNPJ(value);
+  if (digits.length !== 14)
+    throw new BRUtilsError("CNPJ must contain exactly 14 digits.");
+  return digits;
+}
+function normalizeCNPJBranch(value) {
+  const branch = normalizeCNPJ(value ?? "0001");
+  if (!/^\d{1,4}$/.test(branch))
+    throw new BRUtilsError("Branch must contain between 1 and 4 digits.");
+  return branch.padStart(4, "0");
+}
+function calculateCNPJCheckDigit(digits) {
+  const weights = digits.length === 12 ? [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2] : [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * weights[index],
+    0
+  );
+  const remainder = sum % 11;
+  return remainder < 2 ? 0 : 11 - remainder;
+}
+function resolveCNPJBranch(value) {
+  const digits = normalizeCNPJ(value);
+  return digits.length < 12 ? void 0 : digits.slice(8, 12);
+}
+
+// src/services/cnpj/cnpj.formatter.ts
+function formatCNPJValue(value) {
+  return formatCNPJ(ensureCNPJLength(value));
+}
+
+// src/services/cnpj/cnpj.masker.ts
+var DEFAULT_CNPJ_MASK_PATTERN = "**.***.***/****-##";
+function maskCNPJ(value, options = {}) {
+  return applyDigitMask(
+    ensureCNPJLength(value),
+    options.pattern ?? DEFAULT_CNPJ_MASK_PATTERN
+  );
+}
+
+// src/services/cnpj/cnpj.generator.ts
+function generateCNPJ(options = {}) {
+  const rootDigits = randomDigits(8);
+  const branchDigits = normalizeCNPJBranch(options.branch).split("").map(Number);
+  const baseDigits = [...rootDigits, ...branchDigits];
+  const firstCheckDigit = calculateCNPJCheckDigit(baseDigits);
+  const secondCheckDigit = calculateCNPJCheckDigit([
+    ...baseDigits,
+    firstCheckDigit
+  ]);
+  const cnpj = [...baseDigits, firstCheckDigit, secondCheckDigit].join("");
+  return options.formatted ? formatCNPJ(cnpj) : cnpj;
+}
+function generateCNPJBatch(options) {
+  const count = options.count;
+  if (!Number.isInteger(count) || count <= 0)
+    throw new BRUtilsError("Count must be a positive integer.");
+  if (!options.unique)
+    return Array.from(
+      { length: count },
+      () => generateCNPJ({ formatted: options.formatted, branch: options.branch })
+    );
+  const seen = /* @__PURE__ */ new Set();
+  const values = [];
+  while (values.length < count) {
+    const value = generateCNPJ({
+      formatted: options.formatted,
+      branch: options.branch
+    });
+    if (!seen.has(value)) {
+      seen.add(value);
+      values.push(value);
+    }
+  }
+  return values;
+}
+
+// src/services/cnpj/cnpj.validator.ts
+function validateCNPJ(value, options = {}) {
+  const digits = normalizeCNPJ(value);
+  if (digits.length !== 14) return { isValid: false, value: digits };
+  if (options.strict && allDigitsEqual(digits))
+    return {
+      isValid: false,
+      value: digits,
+      formatted: formatCNPJ(digits),
+      branch: resolveCNPJBranch(digits)
+    };
+  const baseDigits = digits.slice(0, 12).split("").map(Number);
+  const firstCheckDigit = calculateCNPJCheckDigit(baseDigits);
+  const secondCheckDigit = calculateCNPJCheckDigit([
+    ...baseDigits,
+    firstCheckDigit
+  ]);
+  const expectedCNPJ = [...baseDigits, firstCheckDigit, secondCheckDigit].join(
+    ""
+  );
+  return {
+    isValid: digits === expectedCNPJ,
+    value: digits,
+    formatted: formatCNPJ(digits),
+    branch: resolveCNPJBranch(digits)
+  };
+}
+
+// src/services/cpf/cpf.shared.ts
+var CPF_STATE_REGION_MAP = {
+  AC: 2,
+  AL: 4,
+  AM: 2,
+  AP: 2,
+  BA: 5,
+  CE: 3,
+  DF: 1,
+  ES: 7,
+  GO: 1,
+  MA: 3,
+  MG: 6,
+  MS: 1,
+  MT: 1,
+  PA: 2,
+  PB: 4,
+  PE: 4,
+  PI: 3,
+  PR: 9,
+  RJ: 7,
+  RN: 4,
+  RO: 2,
+  RR: 2,
+  RS: 0,
+  SC: 9,
+  SE: 5,
+  SP: 8,
+  TO: 1
+};
+var REGION_TO_STATE = {
+  0: "RS",
+  1: "DF",
+  2: "AC",
+  3: "CE",
+  4: "AL",
+  5: "BA",
+  6: "MG",
+  7: "RJ",
+  8: "SP",
+  9: "PR"
+};
+function normalizeCPF(value) {
+  return onlyDigits(value);
+}
+function stripCPF(value) {
+  return normalizeCPF(value);
+}
+function ensureCPFLength(value) {
+  const digits = normalizeCPF(value);
+  if (digits.length !== 11)
+    throw new BRUtilsError("CPF must contain exactly 11 digits.");
+  return digits;
+}
+function calculateCPFCheckDigit(digits) {
+  const factorStart = digits.length + 1;
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * (factorStart - index),
+    0
+  );
+  const remainder = sum * 10 % 11;
+  return remainder === 10 ? 0 : remainder;
+}
+function resolveCPFRegionDigit(state) {
+  return state ? CPF_STATE_REGION_MAP[state] : void 0;
+}
+function resolveCPFStateFromDigits(value) {
+  const digits = normalizeCPF(value);
+  if (digits.length < 9) return void 0;
+  return REGION_TO_STATE[Number(digits[8])];
+}
+
+// src/services/cpf/cpf.formatter.ts
+function formatCPFValue(value) {
+  return formatCPF(ensureCPFLength(value));
+}
+
+// src/services/cpf/cpf.masker.ts
+var DEFAULT_CPF_MASK_PATTERN = "***.***.***-##";
+function maskCPF(value, options = {}) {
+  return applyDigitMask(
+    ensureCPFLength(value),
+    options.pattern ?? DEFAULT_CPF_MASK_PATTERN
+  );
+}
+
+// src/services/cpf/cpf.generator.ts
+function generateCPF(options = {}) {
+  const firstEightDigits = randomDigits(8);
+  const regionDigit = resolveCPFRegionDigit(options.state) ?? randomDigit();
+  const baseDigits = [...firstEightDigits, regionDigit];
+  const firstCheckDigit = calculateCPFCheckDigit(baseDigits);
+  const secondCheckDigit = calculateCPFCheckDigit([
+    ...baseDigits,
+    firstCheckDigit
+  ]);
+  const cpf = [...baseDigits, firstCheckDigit, secondCheckDigit].join("");
+  return options.formatted ? formatCPF(cpf) : cpf;
+}
+function generateCPFBatch(options) {
+  const count = options.count;
+  if (!Number.isInteger(count) || count <= 0)
+    throw new BRUtilsError("Count must be a positive integer.");
+  if (!options.unique)
+    return Array.from(
+      { length: count },
+      () => generateCPF({ formatted: options.formatted, state: options.state })
+    );
+  const seen = /* @__PURE__ */ new Set();
+  const values = [];
+  while (values.length < count) {
+    const value = generateCPF({
+      formatted: options.formatted,
+      state: options.state
+    });
+    if (!seen.has(value)) {
+      seen.add(value);
+      values.push(value);
+    }
+  }
+  return values;
+}
+
+// src/services/cpf/cpf.validator.ts
+function validateCPF(value, options = {}) {
+  const digits = normalizeCPF(value);
+  if (digits.length !== 11) return { isValid: false, value: digits };
+  if (options.strict && allDigitsEqual(digits))
+    return { isValid: false, value: digits, formatted: formatCPF(digits) };
+  const baseDigits = digits.slice(0, 9).split("").map(Number);
+  const firstCheckDigit = calculateCPFCheckDigit(baseDigits);
+  const secondCheckDigit = calculateCPFCheckDigit([
+    ...baseDigits,
+    firstCheckDigit
+  ]);
+  const expectedCPF = [...baseDigits, firstCheckDigit, secondCheckDigit].join(
+    ""
+  );
+  return {
+    isValid: digits === expectedCPF,
+    value: digits,
+    formatted: formatCPF(digits),
+    state: resolveCPFStateFromDigits(digits)
+  };
+}
+
+// src/services/credit-card/credit-card.constants.ts
+var CREDIT_CARD_BRAND_PREFIXES = {
+  visa: ["4"],
+  mastercard: ["51", "52", "53", "54", "55"],
+  amex: ["34", "37"],
+  elo: [
+    "401178",
+    "401179",
+    "431274",
+    "438935",
+    "451416",
+    "457393",
+    "457631",
+    "457632",
+    "504175",
+    "627780",
+    "636297",
+    "636368"
+  ]
+};
+var CREDIT_CARD_BRAND_LENGTHS = {
+  visa: [16],
+  mastercard: [16],
+  amex: [15],
+  elo: [16]
+};
+var CREDIT_CARD_BRAND_CVV_LENGTH = {
+  visa: 3,
+  mastercard: 3,
+  amex: 4,
+  elo: 3
+};
+
+// src/services/credit-card/credit-card.detector.ts
+function detectCreditCardBrand(number) {
+  const digits = onlyDigits(number);
+  const brands = Object.keys(CREDIT_CARD_BRAND_PREFIXES);
+  for (const brand of brands) {
+    const prefixes = CREDIT_CARD_BRAND_PREFIXES[brand];
+    const lengths = CREDIT_CARD_BRAND_LENGTHS[brand];
+    const matchesPrefix = prefixes.some((prefix) => digits.startsWith(prefix));
+    const matchesLength = lengths.includes(digits.length);
+    if (matchesPrefix && matchesLength) {
+      return brand;
+    }
+  }
+  return "unknown";
+}
+
+// src/core/utils/array.ts
+function pickRandomItem(items, randomSource = Math.random) {
+  const item = items[Math.floor(randomSource() * items.length)];
+  if (item === void 0) {
+    throw new BRUtilsError("Cannot pick a random item from an empty array.");
+  }
+  return item;
+}
+function getItemAtIndex(items, index) {
+  const item = items[index];
+  if (item === void 0) {
+    throw new BRUtilsError(`Array index out of bounds: ${index}`);
+  }
+  return item;
+}
+function shuffleArray(items, randomSource = Math.random) {
+  const result = [...items];
+  for (let index = result.length - 1; index > 0; index -= 1) {
+    const swapIndex = Math.floor(randomSource() * (index + 1));
+    const currentValue = getItemAtIndex(result, index);
+    const swapValue = getItemAtIndex(result, swapIndex);
+    result[index] = swapValue;
+    result[swapIndex] = currentValue;
+  }
+  return result;
+}
+
+// src/services/credit-card/credit-card.generator.ts
+function generateRandomNumericString(length) {
+  return Array.from({ length }, () => String(randomDigit())).join("");
+}
+function formatCreditCardNumber(value) {
+  return onlyDigits(value).replace(/(\d{4})(?=\d)/g, "$1 ").trim();
+}
+function calculateLuhnCheckDigit(partialNumber) {
+  const digits = partialNumber.split("").map(Number).reverse();
+  const sum = digits.reduce((accumulator, digit, index) => {
+    if (index % 2 === 0) {
+      const doubled = digit * 2;
+      return accumulator + (doubled > 9 ? doubled - 9 : doubled);
+    }
+    return accumulator + digit;
+  }, 0);
+  return (10 - sum % 10) % 10;
+}
+function generateCardNumber(brand) {
+  const prefixes = CREDIT_CARD_BRAND_PREFIXES[brand];
+  const lengths = CREDIT_CARD_BRAND_LENGTHS[brand];
+  const prefix = pickRandomItem(prefixes);
+  const totalLength = pickRandomItem(lengths);
+  const bodyLength = totalLength - prefix.length - 1;
+  const partialNumber = prefix + generateRandomNumericString(bodyLength);
+  const checkDigit = calculateLuhnCheckDigit(partialNumber);
+  return partialNumber + String(checkDigit);
+}
+function generateExpiry(expiryYearsAhead = 5) {
+  const now = /* @__PURE__ */ new Date();
+  const month = String(Math.floor(Math.random() * 12) + 1).padStart(2, "0");
+  const futureYear = now.getFullYear() + Math.floor(Math.random() * Math.max(expiryYearsAhead, 1)) + 1;
+  const yearTwoDigits = String(futureYear).slice(-2);
+  return {
+    expiryMonth: month,
+    expiryYear: yearTwoDigits,
+    expiry: `${month}/${yearTwoDigits}`
+  };
+}
+function generateCVV(brand) {
+  const length = CREDIT_CARD_BRAND_CVV_LENGTH[brand];
+  return generateRandomNumericString(length);
+}
+function generateCreditCard(options = {}) {
+  const brand = options.brand ?? "visa";
+  const rawNumber = generateCardNumber(brand);
+  const number = options.formatted ? formatCreditCardNumber(rawNumber) : rawNumber;
+  const { expiryMonth, expiryYear, expiry } = generateExpiry(
+    options.expiryYearsAhead
+  );
+  const cvv = generateCVV(brand);
+  return {
+    brand,
+    number,
+    expiryMonth,
+    expiryYear,
+    expiry,
+    cvv
+  };
+}
+
+// src/services/credit-card/credit-card.validator.ts
+function isValidLuhn(number) {
+  const digits = onlyDigits(number);
+  let sum = 0;
+  let shouldDouble = false;
+  for (let index = digits.length - 1; index >= 0; index -= 1) {
+    let digit = Number(digits[index]);
+    if (shouldDouble) {
+      digit *= 2;
+      if (digit > 9) {
+        digit -= 9;
+      }
+    }
+    sum += digit;
+    shouldDouble = !shouldDouble;
+  }
+  return sum % 10 === 0;
+}
+function isValidExpiry(expiryMonth, expiryYear, expiry) {
+  let month = expiryMonth;
+  let year = expiryYear;
+  if ((!month || !year) && expiry) {
+    const match = expiry.match(/^(\d{2})\/(\d{2})$/);
+    if (!match) {
+      return false;
+    }
+    month = match[1];
+    year = match[2];
+  }
+  if (!month || !year) {
+    return false;
+  }
+  const monthNumber = Number(month);
+  const yearNumber = Number(year);
+  if (monthNumber < 1 || monthNumber > 12) {
+    return false;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const currentYear = Number(String(now.getFullYear()).slice(-2));
+  const currentMonth = now.getMonth() + 1;
+  if (yearNumber > currentYear) {
+    return true;
+  }
+  if (yearNumber === currentYear && monthNumber >= currentMonth) {
+    return true;
+  }
+  return false;
+}
+function isValidCVV(brand, cvv) {
+  if (!cvv) {
+    return false;
+  }
+  const digits = onlyDigits(cvv);
+  if (brand === "unknown") {
+    return digits.length >= 3 && digits.length <= 4;
+  }
+  const expectedLength = CREDIT_CARD_BRAND_CVV_LENGTH[brand];
+  return digits.length === expectedLength;
+}
+function validateCreditCard(input) {
+  const number = onlyDigits(input.number);
+  const brand = detectCreditCardBrand(number);
+  const numberValid = brand !== "unknown" && CREDIT_CARD_BRAND_LENGTHS[brand].includes(number.length) && isValidLuhn(number);
+  const expiryValid = isValidExpiry(
+    input.expiryMonth,
+    input.expiryYear,
+    input.expiry
+  );
+  const cvvValid = isValidCVV(brand, input.cvv);
+  return {
+    isValid: numberValid && expiryValid && cvvValid,
+    brand,
+    number,
+    numberValid,
+    expiryValid,
+    cvvValid
+  };
+}
+
+// src/cli/commands/register-brazilian.ts
+function registerBrazilianCommands(program) {
+  const cpf = program.command("cpf").description("Generate, validate, format, strip and mask CPF values.").addHelpText(
+    "after",
+    examples([
+      "brutils cpf generate --formatted",
+      "brutils cpf generate --formatted --state SP --count 5 --unique",
+      "brutils cpf validate 52998224725 --strict",
+      "brutils cpf format 52998224725",
+      "brutils cpf strip 529.982.247-25",
+      'brutils cpf mask 52998224725 --mask "***.###.***-##"'
+    ])
+  );
+  cpf.command("generate").description("Generate synthetic valid CPF values.").option("--formatted", "Return generated values with CPF punctuation.").option(
+    "--state <uf>",
+    "Bias the region digit using a Brazilian state code.",
+    parseState
+  ).option(
+    "--count <number>",
+    "Generate multiple CPFs.",
+    parsePositiveInteger,
+    1
+  ).option("--unique", "Avoid duplicates during batch generation.").action(
+    (options) => {
+      const values = options.count > 1 ? generateCPFBatch({
+        formatted: options.formatted,
+        state: options.state,
+        count: options.count,
+        unique: options.unique
+      }) : [
+        generateCPF({
+          formatted: options.formatted,
+          state: options.state
+        })
+      ];
+      printValue(values);
+    }
+  );
+  cpf.command("validate").argument("<value>", "CPF value to validate.").description(
+    "Validate a CPF using size, check digits and optional strict repeated-pattern rejection."
+  ).option("--strict", "Reject repeated patterns such as 11111111111.").action((value, options) => {
+    printValue(validateCPF(value, { strict: options.strict }));
+  });
+  cpf.command("format").argument("<value>", "CPF value to format.").description("Format a CPF as 000.000.000-00.").action((value) => {
+    printValue(formatCPFValue(value));
+  });
+  cpf.command("strip").argument("<value>", "CPF value to normalize to digits only.").description("Remove punctuation and keep digits only.").action((value) => {
+    printValue(stripCPF(value));
+  });
+  cpf.command("mask").argument("<value>", "CPF value to mask.").description("Mask a CPF for safe display.").option(
+    "--mask <pattern>",
+    'Custom mask. Use "*" to hide digits and "#" to reveal them.'
+  ).action((value, options) => {
+    printValue(maskCPF(value, { pattern: options.mask }));
+  });
+  const cnpj = program.command("cnpj").description("Generate, validate, format, strip and mask CNPJ values.").addHelpText(
+    "after",
+    examples([
+      "brutils cnpj generate --formatted",
+      "brutils cnpj generate --branch 12 --count 3 --unique",
+      "brutils cnpj validate 11.444.777/0001-61 --strict",
+      "brutils cnpj format 11444777000161",
+      "brutils cnpj strip 11.444.777/0001-61",
+      'brutils cnpj mask 11444777000161 --mask "##.***.***/****-##"'
+    ])
+  );
+  cnpj.command("generate").description("Generate synthetic valid CNPJ values.").option("--formatted", "Return generated values with CNPJ punctuation.").option(
+    "--branch <number>",
+    "Force a branch identifier. Values are left-padded to 4 digits."
+  ).option(
+    "--count <number>",
+    "Generate multiple CNPJs.",
+    parsePositiveInteger,
+    1
+  ).option("--unique", "Avoid duplicates during batch generation.").action(
+    (options) => {
+      const values = options.count > 1 ? generateCNPJBatch({
+        formatted: options.formatted,
+        branch: options.branch,
+        count: options.count,
+        unique: options.unique
+      }) : [
+        generateCNPJ({
+          formatted: options.formatted,
+          branch: options.branch
+        })
+      ];
+      printValue(values);
+    }
+  );
+  cnpj.command("validate").argument("<value>", "CNPJ value to validate.").description(
+    "Validate a CNPJ using size, check digits and optional strict repeated-pattern rejection."
+  ).option("--strict", "Reject repeated patterns such as 00000000000000.").action((value, options) => {
+    printValue(validateCNPJ(value, { strict: options.strict }));
+  });
+  cnpj.command("format").argument("<value>", "CNPJ value to format.").description("Format a CNPJ as 00.000.000/0000-00.").action((value) => {
+    printValue(formatCNPJValue(value));
+  });
+  cnpj.command("strip").argument("<value>", "CNPJ value to normalize to digits only.").description("Remove punctuation and keep digits only.").action((value) => {
+    printValue(stripCNPJ(value));
+  });
+  cnpj.command("mask").argument("<value>", "CNPJ value to mask.").description("Mask a CNPJ for safe display.").option(
+    "--mask <pattern>",
+    'Custom mask. Use "*" to hide digits and "#" to reveal them.'
+  ).action((value, options) => {
+    printValue(maskCNPJ(value, { pattern: options.mask }));
+  });
+  const cep = program.command("cep").description("Generate, validate, format, strip and mask CEP values.").addHelpText(
+    "after",
+    examples([
+      "brutils cep generate --formatted",
+      "brutils cep generate --state PR --count 5",
+      "brutils cep validate 86010-190 --strict",
+      "brutils cep format 86010190",
+      "brutils cep strip 86010-190",
+      'brutils cep mask 86010190 --mask "###**-***"'
+    ])
+  );
+  cep.command("generate").description("Generate synthetic CEP values for testing.").option("--formatted", "Return generated values with CEP punctuation.").option(
+    "--state <uf>",
+    "Bias the leading digit using a Brazilian state code.",
+    parseState
+  ).option(
+    "--count <number>",
+    "Generate multiple CEP values.",
+    parsePositiveInteger,
+    1
+  ).action(
+    (options) => {
+      const values = options.count > 1 ? generateCEPBatch({
+        formatted: options.formatted,
+        state: options.state,
+        count: options.count
+      }) : [
+        generateCEP({
+          formatted: options.formatted,
+          state: options.state
+        })
+      ];
+      printValue(values);
+    }
+  );
+  cep.command("validate").argument("<value>", "CEP value to validate.").description(
+    "Validate CEP structure and optional strict repeated-pattern rejection."
+  ).option("--strict", "Reject repeated patterns such as 11111111.").action((value, options) => {
+    printValue(validateCEP(value, { strict: options.strict }));
+  });
+  cep.command("format").argument("<value>", "CEP value to format.").description("Format a CEP as 00000-000.").action((value) => {
+    printValue(formatCEPValue(value));
+  });
+  cep.command("strip").argument("<value>", "CEP value to normalize to digits only.").description("Remove punctuation and keep digits only.").action((value) => {
+    printValue(stripCEP(value));
+  });
+  cep.command("mask").argument("<value>", "CEP value to mask.").description("Mask a CEP for safe display.").option(
+    "--mask <pattern>",
+    'Custom mask. Use "*" to hide digits and "#" to reveal them.'
+  ).action((value, options) => {
+    printValue(maskCEP(value, { pattern: options.mask }));
+  });
+  const creditCard = program.command("credit-card").alias("card").description("Generate, validate and detect test credit card data.").addHelpText(
+    "after",
+    examples([
+      "brutils credit-card generate --brand visa --formatted",
+      "brutils credit-card validate --number 4111111111111111 --expiry 12/30 --cvv 123",
+      "brutils credit-card validate --number 4111111111111111 --expiry-month 12 --expiry-year 30 --cvv 123",
+      "brutils credit-card detect 4111111111111111"
+    ])
+  );
+  creditCard.command("generate").description("Generate synthetic card test data.").option("--brand <brand>", "Card brand to generate.", parseCardBrand).option("--formatted", "Return the card number with spaces every 4 digits.").option(
+    "--expiry-years-ahead <number>",
+    "Maximum number of years ahead for generated expiry.",
+    parsePositiveInteger
+  ).action(
+    (options) => {
+      printValue(generateCreditCard(options));
+    }
+  );
+  creditCard.command("validate").description("Validate card number, expiry and CVV.").requiredOption("--number <value>", "Card number to validate.").option("--expiry <value>", "Expiry in MM/YY format.").option("--expiry-month <value>", "Expiry month.").option("--expiry-year <value>", "Expiry year.").requiredOption("--cvv <value>", "CVV to validate.").action(
+    (options) => {
+      printValue(validateCreditCard(options));
+    }
+  );
+  creditCard.command("detect").argument("<number>", "Card number to inspect.").description("Detect the card brand from a card number.").action((number) => {
+    printValue(detectCreditCardBrand(number));
+  });
+}
+
+// src/services/date/date.service.ts
+var DATE_DIFF_FACTORS = {
+  seconds: 1e3,
+  minutes: 60 * 1e3,
+  hours: 60 * 60 * 1e3,
+  days: 24 * 60 * 60 * 1e3
+};
+function ensureValidDate(date, input) {
+  if (Number.isNaN(date.getTime())) {
+    throw new BRUtilsError(`Invalid date value: ${input}`);
+  }
+}
+function parseDate(input) {
+  const date = new Date(input);
+  ensureValidDate(date, input);
+  return date;
+}
+function ensureValidInteger(value, label) {
+  const resolved = value ?? 0;
+  if (!Number.isInteger(resolved)) {
+    throw new BRUtilsError(`${label} must be an integer.`);
+  }
+  return resolved;
+}
+function pad2(value) {
+  return String(value).padStart(2, "0");
+}
+function snapshot(date) {
+  const unixMs = date.getTime();
+  return {
+    iso: date.toISOString(),
+    unix: Math.floor(unixMs / 1e3),
+    unixMs
+  };
+}
+function formatUtcDate(date, pattern) {
+  const replacements = {
+    YYYY: String(date.getUTCFullYear()),
+    MM: pad2(date.getUTCMonth() + 1),
+    DD: pad2(date.getUTCDate()),
+    HH: pad2(date.getUTCHours()),
+    mm: pad2(date.getUTCMinutes()),
+    ss: pad2(date.getUTCSeconds())
+  };
+  return pattern.replace(
+    /YYYY|MM|DD|HH|mm|ss/g,
+    (token) => replacements[token]
+  );
+}
+function adjustDate(date, options, multiplier) {
+  const days = ensureValidInteger(options.days, "Days");
+  const hours = ensureValidInteger(options.hours, "Hours");
+  const minutes = ensureValidInteger(options.minutes, "Minutes");
+  const seconds = ensureValidInteger(options.seconds, "Seconds");
+  const totalMs = days * DATE_DIFF_FACTORS.days + hours * DATE_DIFF_FACTORS.hours + minutes * DATE_DIFF_FACTORS.minutes + seconds * DATE_DIFF_FACTORS.seconds;
+  return new Date(date.getTime() + multiplier * totalMs);
+}
+function ensureTimeZone(value) {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value }).format(/* @__PURE__ */ new Date());
+    return value;
+  } catch {
+    throw new BRUtilsError(`Invalid time zone: ${value}`);
+  }
+}
+function timeZoneParts(date, timeZone) {
+  const formatter = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  return formatter.formatToParts(date).reduce((acc, part) => {
+    if (part.type !== "literal") {
+      acc[part.type] = part.value;
+    }
+    return acc;
+  }, {});
+}
+function currentDateTime() {
+  return snapshot(/* @__PURE__ */ new Date());
+}
+function formatDateValue(value, pattern) {
+  return formatUtcDate(parseDate(value), pattern);
+}
+function parseDateValue(value) {
+  return {
+    input: value,
+    ...snapshot(parseDate(value))
+  };
+}
+function addToDate(value, options) {
+  return adjustDate(parseDate(value), options, 1).toISOString();
+}
+function subtractFromDate(value, options) {
+  return adjustDate(parseDate(value), options, -1).toISOString();
+}
+function diffDates(from, to, unit = "seconds") {
+  const left = parseDate(from);
+  const right = parseDate(to);
+  const factor = DATE_DIFF_FACTORS[unit];
+  const raw = (right.getTime() - left.getTime()) / factor;
+  return {
+    from,
+    to,
+    unit,
+    value: Number(raw.toFixed(6))
+  };
+}
+function convertDateToUnix(value) {
+  return {
+    input: value,
+    sourceUnit: "milliseconds",
+    ...snapshot(parseDate(value))
+  };
+}
+function convertUnixValue(value) {
+  const normalized = String(value).trim();
+  if (!/^-?\d+$/.test(normalized)) {
+    throw new BRUtilsError(`Invalid Unix timestamp value: ${value}`);
+  }
+  const numeric = Number(normalized);
+  const sourceUnit = Math.abs(numeric) >= 1e12 ? "milliseconds" : "seconds";
+  const unixMs = sourceUnit === "seconds" ? numeric * 1e3 : numeric;
+  const date = new Date(unixMs);
+  ensureValidDate(date, normalized);
+  return {
+    input: value,
+    sourceUnit,
+    ...snapshot(date)
+  };
+}
+function convertDateToTimeZone(value, timeZone) {
+  const date = parseDate(value);
+  const normalizedTimeZone = ensureTimeZone(timeZone);
+  const parts = timeZoneParts(date, normalizedTimeZone);
+  return {
+    input: value,
+    timeZone: normalizedTimeZone,
+    formatted: `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}:${parts.second}`,
+    iso: date.toISOString()
+  };
+}
+
+// src/services/hash/hash.service.ts
+import crypto from "crypto";
+import fs5 from "fs";
+function resolveHashSource(options) {
+  if (options.text !== void 0 && options.file !== void 0) {
+    throw new BRUtilsError("Use either --text or --file, not both.");
+  }
+  if (options.text !== void 0) {
+    return {
+      kind: "text",
+      content: Buffer.from(options.text, "utf-8")
+    };
+  }
+  if (options.file !== void 0) {
+    if (!fs5.existsSync(options.file) || !fs5.statSync(options.file).isFile()) {
+      throw new BRUtilsError(`File does not exist: ${options.file}`);
+    }
+    return {
+      kind: "file",
+      content: fs5.readFileSync(options.file)
+    };
+  }
+  throw new BRUtilsError("One of --text or --file is required.");
+}
+function normalizeAlgorithm(value) {
+  const algorithm = value.toLowerCase();
+  if (!crypto.getHashes().includes(algorithm)) {
+    throw new BRUtilsError(`Unsupported hash algorithm: ${value}`);
+  }
+  return algorithm;
+}
+function digestBuffer(buffer, algorithm) {
+  return crypto.createHash(normalizeAlgorithm(algorithm)).update(buffer).digest("hex");
+}
+function normalizeExpectedHash(value) {
+  return value.trim().toLowerCase();
+}
+function computeHash(options, algorithm) {
+  const source = resolveHashSource(options);
+  return digestBuffer(source.content, algorithm);
+}
+function computeMd5(options) {
+  return computeHash(options, "md5");
+}
+function computeSha1(options) {
+  return computeHash(options, "sha1");
+}
+function computeSha256(options) {
+  return computeHash(options, "sha256");
+}
+function computeSha512(options) {
+  return computeHash(options, "sha512");
+}
+function computeHmac(options) {
+  const source = resolveHashSource(options);
+  return crypto.createHmac(normalizeAlgorithm(options.algo), options.key).update(source.content).digest("hex");
+}
+function computeChecksum(options) {
+  return computeHash({ file: options.file }, options.algo ?? "sha256");
+}
+function compareHash(options) {
+  const source = resolveHashSource(options);
+  const algorithm = normalizeAlgorithm(options.algo ?? "sha256");
+  const actual = digestBuffer(source.content, algorithm);
+  const expected = normalizeExpectedHash(options.expected);
+  return {
+    algorithm,
+    actual,
+    expected,
+    matches: actual === expected,
+    source: source.kind
+  };
+}
+
+// src/services/id/id.service.ts
+import crypto2 from "crypto";
+var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var DIGITS = "0123456789";
+var SYMBOLS = "!@#$%^&*()-_=+[]{};:,.?/|~";
+var CHARSET_MAP = {
+  alnum: `${LOWERCASE}${UPPERCASE}${DIGITS}`,
+  alpha: `${LOWERCASE}${UPPERCASE}`,
+  numeric: DIGITS,
+  hex: "0123456789abcdef",
+  base64url: `${LOWERCASE}${UPPERCASE}${DIGITS}-_`,
+  lower: LOWERCASE,
+  upper: UPPERCASE
+};
+function ensurePositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new BRUtilsError(`${label} must be a positive integer.`);
+  }
+}
+function resolveCount(count) {
+  const resolved = count ?? 1;
+  ensurePositiveInteger(resolved, "Count");
+  return resolved;
+}
+function resolveLength(length, fallback) {
+  const resolved = length ?? fallback;
+  ensurePositiveInteger(resolved, "Length");
+  return resolved;
+}
+function charsetByName(name) {
+  return CHARSET_MAP[name];
+}
+function randomCharacter(charset) {
+  return charset[crypto2.randomInt(0, charset.length)];
+}
+function randomString(length, charset) {
+  return Array.from({ length }, () => randomCharacter(charset)).join("");
+}
+function ensureNotEmptyCharset(charset) {
+  if (charset.length === 0) {
+    throw new BRUtilsError(
+      "The selected options produced an empty character set."
+    );
+  }
+}
+function ensureUppercasePresence(value) {
+  if (/[A-Z]/.test(value)) {
+    return value;
+  }
+  const index = crypto2.randomInt(0, value.length);
+  const replacement = randomCharacter(UPPERCASE);
+  return `${value.slice(0, index)}${replacement}${value.slice(index + 1)}`;
+}
+function resolveTokenCharset(charset) {
+  return charsetByName(charset ?? "alnum");
+}
+function resolvePasswordCharset(options) {
+  let charset = options.charset ? charsetByName(options.charset) : `${LOWERCASE}${UPPERCASE}${DIGITS}${SYMBOLS}`;
+  if (options.noNumbers) {
+    charset = charset.replace(/[0-9]/g, "");
+  }
+  if (options.noSymbols) {
+    charset = charset.replace(/[!@#$%^&*()_=+[\]{};:,.?/|~-]/g, "");
+  }
+  if (options.uppercase && !/[A-Z]/.test(charset)) {
+    charset += UPPERCASE;
+  }
+  ensureNotEmptyCharset(charset);
+  return charset;
+}
+function generateUuidValues(options = {}) {
+  const count = resolveCount(options.count);
+  return Array.from({ length: count }, () => crypto2.randomUUID());
+}
+function generateTokenValues(options = {}) {
+  const count = resolveCount(options.count);
+  const length = resolveLength(options.length, 32);
+  const charset = resolveTokenCharset(options.charset);
+  return Array.from({ length: count }, () => randomString(length, charset));
+}
+function generatePasswordValues(options = {}) {
+  const count = resolveCount(options.count);
+  const length = resolveLength(options.length, 16);
+  const charset = resolvePasswordCharset(options);
+  return Array.from({ length: count }, () => {
+    let password = randomString(length, charset);
+    if (options.uppercase) {
+      password = ensureUppercasePresence(password);
+    }
+    return password;
+  });
+}
+
+// src/cli/commands/register-helpers.ts
+function printStringBatch(values) {
+  if (values.length === 1) {
+    printValue(values[0]);
+    return;
+  }
+  printValue(values);
+}
+function registerHelperCommands(program) {
+  const hash = program.command("hash").description("Digest helpers for text, files and HMAC operations.").addHelpText(
+    "after",
+    examples([
+      "brutils hash md5 --text hello",
+      "brutils hash sha256 --file ./README.md",
+      "brutils hash hmac --algo sha256 --key secret --text hello",
+      "brutils hash checksum --file ./dist/cli.js --algo sha512",
+      "brutils hash compare --file ./README.md --algo sha256 --expected <hash>"
+    ])
+  );
+  hash.command("md5").description("Compute an MD5 digest for text or a file.").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action((options) => {
+    printValue(computeMd5(options));
+  });
+  hash.command("sha1").description("Compute a SHA-1 digest for text or a file.").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action((options) => {
+    printValue(computeSha1(options));
+  });
+  hash.command("sha256").description("Compute a SHA-256 digest for text or a file.").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action((options) => {
+    printValue(computeSha256(options));
+  });
+  hash.command("sha512").description("Compute a SHA-512 digest for text or a file.").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action((options) => {
+    printValue(computeSha512(options));
+  });
+  hash.command("hmac").description("Compute an HMAC with a chosen algorithm.").requiredOption("--key <value>", "Secret key for the HMAC.").option("--algo <name>", "Hash algorithm to use.", "sha256").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action(
+    (options) => {
+      printValue(computeHmac(options));
+    }
+  );
+  hash.command("checksum").description("Compute a digest for a file.").requiredOption("--file <path>", "File to hash.").option("--algo <name>", "Hash algorithm to use.", "sha256").action((options) => {
+    printValue(computeChecksum(options));
+  });
+  hash.command("compare").description("Compare a computed hash against an expected value.").requiredOption("--expected <hash>", "Expected hash value.").option("--algo <name>", "Hash algorithm to use.", "sha256").option("--text <value>", "Inline value to hash.").option("--file <path>", "File to hash.").action(
+    (options) => {
+      printValue(compareHash(options));
+    }
+  );
+  const id = program.command("id").description("UUID, token and password generation helpers.").addHelpText(
+    "after",
+    examples([
+      "brutils id uuid",
+      "brutils id uuid --count 3",
+      "brutils id token --length 24 --charset base64url",
+      "brutils id password --length 20 --uppercase",
+      "brutils id password --length 16 --no-symbols --no-numbers"
+    ])
+  );
+  id.command("uuid").description("Generate UUID values.").option(
+    "--count <number>",
+    "How many UUIDs to generate.",
+    parsePositiveInteger,
+    1
+  ).action((options) => {
+    printStringBatch(generateUuidValues(options));
+  });
+  id.command("token").description("Generate random tokens.").option(
+    "--count <number>",
+    "How many tokens to generate.",
+    parsePositiveInteger,
+    1
+  ).option("--length <number>", "Desired token length.", parsePositiveInteger).option(
+    "--charset <name>",
+    "Allowed character preset: alnum, alpha, numeric, hex, base64url, lower or upper.",
+    parseCharsetName
+  ).action(
+    (options) => {
+      printStringBatch(generateTokenValues(options));
+    }
+  );
+  id.command("password").description("Generate strong passwords.").option(
+    "--count <number>",
+    "How many passwords to generate.",
+    parsePositiveInteger,
+    1
+  ).option(
+    "--length <number>",
+    "Desired password length.",
+    parsePositiveInteger
+  ).option(
+    "--charset <name>",
+    "Allowed character preset: alnum, alpha, numeric, hex, base64url, lower or upper.",
+    parseCharsetName
+  ).option("--no-symbols", "Exclude symbols from generated passwords.").option("--no-numbers", "Exclude digits from generated passwords.").option("--uppercase", "Ensure at least one uppercase letter.").action(
+    (options) => {
+      printStringBatch(generatePasswordValues(options));
+    }
+  );
+  const date = program.command("date").description("Date formatting, arithmetic and timezone helpers.").addHelpText(
+    "after",
+    examples([
+      "brutils date now",
+      'brutils date format --date 2024-01-02T03:04:05Z --pattern "YYYY-MM-DD HH:mm:ss"',
+      "brutils date add --date 2024-01-01T00:00:00Z --days 7",
+      "brutils date diff --from 2024-01-01T00:00:00Z --to 2024-01-03T00:00:00Z --unit days",
+      "brutils date unix --date 2024-01-01T00:00:00Z",
+      "brutils date tz --from 2024-01-01T12:00:00Z --to America/Sao_Paulo"
+    ])
+  );
+  date.command("now").description("Print the current date and time.").action(() => {
+    printValue(currentDateTime());
+  });
+  date.command("format").description("Format a date using a token pattern.").requiredOption("--date <value>", "Input date/time value.").requiredOption("--pattern <value>", "Formatting pattern.").action((options) => {
+    printValue(formatDateValue(options.date, options.pattern));
+  });
+  date.command("parse").description("Parse a date string and return normalized metadata.").requiredOption("--date <value>", "Input date/time value.").action((options) => {
+    printValue(parseDateValue(options.date));
+  });
+  date.command("add").description("Add time to a date.").requiredOption("--date <value>", "Input date/time value.").option("--days <number>", "Day delta.", parsePositiveInteger).option("--hours <number>", "Hour delta.", parsePositiveInteger).option("--minutes <number>", "Minute delta.", parsePositiveInteger).option("--seconds <number>", "Second delta.", parsePositiveInteger).action(
+    (options) => {
+      printValue(addToDate(options.date, options));
+    }
+  );
+  date.command("sub").description("Subtract time from a date.").requiredOption("--date <value>", "Input date/time value.").option("--days <number>", "Day delta.", parsePositiveInteger).option("--hours <number>", "Hour delta.", parsePositiveInteger).option("--minutes <number>", "Minute delta.", parsePositiveInteger).option("--seconds <number>", "Second delta.", parsePositiveInteger).action(
+    (options) => {
+      printValue(subtractFromDate(options.date, options));
+    }
+  );
+  date.command("diff").description("Calculate the difference between two dates.").requiredOption("--from <value>", "Source date/time value.").requiredOption("--to <value>", "Target date/time value.").option(
+    "--unit <name>",
+    "Output unit: seconds, minutes, hours or days.",
+    parseDateDiffUnit,
+    "seconds"
+  ).action((options) => {
+    printValue(diffDates(options.from, options.to, options.unit));
+  });
+  date.command("unix").argument("[value]", "Unix seconds or milliseconds to convert to ISO.").description("Convert to or from Unix timestamps.").option("--date <value>", "Date/time value to convert to Unix.").action((value, options) => {
+    if (options.date !== void 0) {
+      printValue(convertDateToUnix(options.date));
+      return;
+    }
+    if (value === void 0) {
+      throw new Error("Provide either a positional unix value or --date.");
+    }
+    printValue(convertUnixValue(value));
+  });
+  date.command("tz").description("Convert a date/time to a target time zone representation.").requiredOption("--from <value>", "Source date/time value.").requiredOption(
+    "--to <value>",
+    "Target IANA time zone, such as America/Sao_Paulo."
+  ).action((options) => {
+    printValue(convertDateToTimeZone(options.from, options.to));
+  });
+}
+
+// src/core/utils/seeded-random.ts
+function createRandomSource(seed) {
+  if (seed === void 0) {
+    return Math.random;
+  }
+  let state = Math.trunc(seed) >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let value = state;
+    value = Math.imul(value ^ value >>> 15, value | 1);
+    value ^= value + Math.imul(value ^ value >>> 7, value | 61);
+    return ((value ^ value >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/services/number-picker/number-picker.service.ts
+function resolveMin(min) {
+  return min ?? Number.MIN_SAFE_INTEGER;
+}
+function resolveMax(max) {
+  return max ?? Number.MAX_SAFE_INTEGER;
+}
+function pickRandomNumber(options = {}) {
+  const min = resolveMin(options.min);
+  const max = resolveMax(options.max);
+  const randomSource = createRandomSource(options.seed);
+  if (!Number.isInteger(min) || !Number.isInteger(max)) {
+    throw new BRUtilsError("Minimum and maximum values must be integers.");
+  }
+  if (min > max) {
+    throw new BRUtilsError(
+      "Minimum value cannot be greater than maximum value."
+    );
+  }
+  return Math.floor(randomSource() * (max - min + 1)) + min;
+}
+
+// src/services/random-number/random-number.generator.ts
+function resolveIntegerMin(min) {
+  return min ?? Number.MIN_SAFE_INTEGER;
+}
+function resolveIntegerMax(max) {
+  return max ?? Number.MAX_SAFE_INTEGER;
+}
+function resolveFloatMin(min) {
+  return min ?? 0;
+}
+function resolveFloatMax(max) {
+  return max ?? 1;
+}
+function randomIntegerBetween(min, max, randomSource) {
+  return Math.floor(randomSource() * (max - min + 1)) + min;
+}
+function randomFloatBetween(min, max, randomSource) {
+  return randomSource() * (max - min) + min;
+}
+function validateRange(min, max, integerOnly = true) {
+  if (integerOnly && (!Number.isInteger(min) || !Number.isInteger(max))) {
+    throw new BRUtilsError("Minimum and maximum values must be integers.");
+  }
+  if (min > max) {
+    throw new BRUtilsError(
+      "Minimum value cannot be greater than maximum value."
+    );
+  }
+}
+function validateCount(count) {
+  if (!Number.isInteger(count) || count < 1) {
+    throw new BRUtilsError("Count must be a positive integer.");
+  }
+}
+function normalizePrecision(precision) {
+  if (precision === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(precision) || precision < 0) {
+    throw new BRUtilsError("Precision must be a non-negative integer.");
+  }
+  return precision;
+}
+function normalizeItems(items) {
+  const normalized = items.map((item) => item.trim()).filter(Boolean);
+  if (normalized.length === 0) {
+    throw new BRUtilsError("At least one item must be provided.");
+  }
+  return normalized;
+}
+function applyFloatPrecision(value, precision) {
+  if (precision === void 0) {
+    return value;
+  }
+  return Number(value.toFixed(precision));
+}
+function generateRandomIntegers(options = {}) {
+  const min = resolveIntegerMin(options.min);
+  const max = resolveIntegerMax(options.max);
+  const count = options.count ?? 1;
+  const unique = options.unique ?? false;
+  const sorted = options.sorted ?? false;
+  const randomSource = createRandomSource(options.seed);
+  validateRange(min, max, true);
+  validateCount(count);
+  const availableNumbers = max - min + 1;
+  if (unique && count > availableNumbers) {
+    throw new BRUtilsError(
+      "Cannot generate more unique numbers than the available range size."
+    );
+  }
+  let result;
+  if (unique) {
+    const pool = Array.from(
+      { length: availableNumbers },
+      (_, index) => min + index
+    );
+    result = shuffleArray(pool, randomSource).slice(0, count);
+  } else {
+    result = Array.from(
+      { length: count },
+      () => randomIntegerBetween(min, max, randomSource)
+    );
+  }
+  if (sorted) {
+    result.sort((a, b) => a - b);
+  }
+  return result;
+}
+function generateRandomFloats(options = {}) {
+  const min = resolveFloatMin(options.min);
+  const max = resolveFloatMax(options.max);
+  const count = options.count ?? 1;
+  const sorted = options.sorted ?? false;
+  const precision = normalizePrecision(options.precision);
+  const randomSource = createRandomSource(options.seed);
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    throw new BRUtilsError(
+      "Minimum and maximum values must be finite numbers."
+    );
+  }
+  validateRange(min, max, false);
+  validateCount(count);
+  const result = Array.from(
+    { length: count },
+    () => applyFloatPrecision(randomFloatBetween(min, max, randomSource), precision)
+  );
+  if (sorted) {
+    result.sort((a, b) => a - b);
+  }
+  return result;
+}
+function pickRandomItems(options) {
+  const items = normalizeItems(options.items);
+  const count = options.count ?? 1;
+  const unique = options.unique ?? false;
+  const randomSource = createRandomSource(options.seed);
+  validateCount(count);
+  if (unique && count > items.length) {
+    throw new BRUtilsError(
+      "Cannot pick more unique items than the available item count."
+    );
+  }
+  if (unique) {
+    return shuffleArray(items, randomSource).slice(0, count);
+  }
+  return Array.from(
+    { length: count },
+    () => pickRandomItem(items, randomSource)
+  );
+}
+function shuffleRandomItems(options) {
+  return shuffleArray(
+    normalizeItems(options.items),
+    createRandomSource(options.seed)
+  );
+}
+function rollDice(options = {}) {
+  const faces = options.faces ?? 6;
+  const count = options.count ?? 1;
+  const randomSource = createRandomSource(options.seed);
+  if (!Number.isInteger(faces) || faces < 2) {
+    throw new BRUtilsError(
+      "Dice faces must be an integer greater than or equal to 2."
+    );
+  }
+  validateCount(count);
+  return Array.from(
+    { length: count },
+    () => randomIntegerBetween(1, faces, randomSource)
+  );
+}
+function flipCoin(options = {}) {
+  const randomSource = createRandomSource(options.seed);
+  return randomSource() < 0.5 ? "heads" : "tails";
+}
+
+// src/cli/shared/io.ts
+import fs6 from "fs";
+
+// src/services/json/json.service.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneJsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeysDeep(item));
+  }
+  if (isPlainObject(value)) {
+    return Object.keys(value).sort((left, right) => left.localeCompare(right)).reduce((accumulator, key) => {
+      accumulator[key] = sortKeysDeep(value[key]);
+      return accumulator;
+    }, {});
+  }
+  return value;
+}
+function formatYamlScalar(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "string") {
+    if (/^[A-Za-z0-9_-]+$/.test(value)) {
+      return value;
+    }
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
+}
+function toYamlLines(value, depth = 0) {
+  const indent = "  ".repeat(depth);
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return [`${indent}[]`];
+    }
+    return value.flatMap((item) => {
+      if (Array.isArray(item) || isPlainObject(item)) {
+        const nested = toYamlLines(item, depth + 1);
+        return [`${indent}-`, ...nested];
+      }
+      return [`${indent}- ${formatYamlScalar(item)}`];
+    });
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return [`${indent}{}`];
+    }
+    return keys.flatMap((key) => {
+      const child = value[key];
+      if (Array.isArray(child) || isPlainObject(child)) {
+        return [`${indent}${key}:`, ...toYamlLines(child, depth + 1)];
+      }
+      return [`${indent}${key}: ${formatYamlScalar(child)}`];
+    });
+  }
+  return [`${indent}${formatYamlScalar(value)}`];
+}
+function parsePath(path11) {
+  const segments = path11.match(/[^.[\]]+/g) ?? [];
+  if (segments.length === 0) {
+    throw new BRUtilsError("JSON path cannot be empty.");
+  }
+  return segments;
+}
+function getContainerForPath(root, segments) {
+  let current = root;
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index)) {
+        return void 0;
+      }
+      current = current[index];
+      continue;
+    }
+    if (isPlainObject(current)) {
+      current = current[segment];
+      continue;
+    }
+    return void 0;
+  }
+  return current;
+}
+function appendDiffPath(basePath, segment) {
+  if (typeof segment === "number") {
+    return `${basePath}[${segment}]`;
+  }
+  return basePath === "$" ? `$.${segment}` : `${basePath}.${segment}`;
+}
+function deepEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function diffValues(left, right, basePath = "$") {
+  if (deepEqual(left, right)) {
+    return [];
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    const result = [];
+    const maxLength = Math.max(left.length, right.length);
+    for (let index = 0; index < maxLength; index += 1) {
+      if (index >= left.length) {
+        result.push({
+          path: appendDiffPath(basePath, index),
+          type: "added",
+          right: right[index]
+        });
+        continue;
+      }
+      if (index >= right.length) {
+        result.push({
+          path: appendDiffPath(basePath, index),
+          type: "removed",
+          left: left[index]
+        });
+        continue;
+      }
+      result.push(
+        ...diffValues(
+          left[index],
+          right[index],
+          appendDiffPath(basePath, index)
+        )
+      );
+    }
+    return result;
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const result = [];
+    const keys = /* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)]);
+    for (const key of Array.from(keys).sort((a, b) => a.localeCompare(b))) {
+      if (!(key in left)) {
+        result.push({
+          path: appendDiffPath(basePath, key),
+          type: "added",
+          right: right[key]
+        });
+        continue;
+      }
+      if (!(key in right)) {
+        result.push({
+          path: appendDiffPath(basePath, key),
+          type: "removed",
+          left: left[key]
+        });
+        continue;
+      }
+      result.push(
+        ...diffValues(left[key], right[key], appendDiffPath(basePath, key))
+      );
+    }
+    return result;
+  }
+  return [
+    {
+      path: basePath,
+      type: "changed",
+      left,
+      right
+    }
+  ];
+}
+function deepMerge(left, right) {
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return cloneJsonValue(right);
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const result = cloneJsonValue(left);
+    for (const [key, value] of Object.entries(right)) {
+      if (key in result) {
+        result[key] = deepMerge(result[key], value);
+      } else {
+        result[key] = cloneJsonValue(value);
+      }
+    }
+    return result;
+  }
+  return cloneJsonValue(right);
+}
+function parseJsonInput(value) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown JSON parse error.";
+    throw new BRUtilsError(message);
+  }
+}
+function validateJsonInput(value) {
+  try {
+    JSON.parse(value);
+    return { isValid: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown JSON parse error.";
+    return { isValid: false, error: message };
+  }
+}
+function formatJsonValue(value, indent = 2, sortKeys = false) {
+  if (!Number.isInteger(indent) || indent < 0) {
+    throw new BRUtilsError("Indent must be a non-negative integer.");
+  }
+  const normalized = sortKeys ? sortKeysDeep(value) : value;
+  return JSON.stringify(normalized, null, indent);
+}
+function minifyJsonValue(value) {
+  return JSON.stringify(value);
+}
+function getJsonPathValue(value, path11) {
+  return getContainerForPath(value, parsePath(path11));
+}
+function setJsonPathValue(value, path11, newValue) {
+  const root = cloneJsonValue(value);
+  const segments = parsePath(path11);
+  let current = root;
+  segments.forEach((segment, index) => {
+    const isLast = index === segments.length - 1;
+    const nextSegment = segments[index + 1];
+    const nextShouldBeArray = nextSegment !== void 0 && /^\d+$/.test(nextSegment);
+    if (Array.isArray(current)) {
+      const currentIndex = Number(segment);
+      if (!Number.isInteger(currentIndex)) {
+        throw new BRUtilsError(`Invalid array index in path: ${segment}`);
+      }
+      if (isLast) {
+        current[currentIndex] = newValue;
+        return;
+      }
+      if (current[currentIndex] === void 0) {
+        current[currentIndex] = nextShouldBeArray ? [] : {};
+      }
+      current = current[currentIndex];
+      return;
+    }
+    if (!isPlainObject(current)) {
+      throw new BRUtilsError(`Cannot set nested path at segment: ${segment}`);
+    }
+    if (isLast) {
+      current[segment] = newValue;
+      return;
+    }
+    if (current[segment] === void 0) {
+      current[segment] = nextShouldBeArray ? [] : {};
+    }
+    current = current[segment];
+  });
+  return root;
+}
+function deleteJsonPathValue(value, path11) {
+  const root = cloneJsonValue(value);
+  const segments = parsePath(path11);
+  const parent = getContainerForPath(root, segments.slice(0, -1));
+  const lastSegment = segments[segments.length - 1];
+  if (Array.isArray(parent)) {
+    const index = Number(lastSegment);
+    if (!Number.isInteger(index)) {
+      throw new BRUtilsError(`Invalid array index in path: ${lastSegment}`);
+    }
+    parent.splice(index, 1);
+    return root;
+  }
+  if (isPlainObject(parent)) {
+    delete parent[lastSegment];
+    return root;
+  }
+  if (segments.length === 1 && isPlainObject(root)) {
+    delete root[lastSegment];
+    return root;
+  }
+  throw new BRUtilsError(`Path not found: ${path11}`);
+}
+function diffJsonValues(left, right) {
+  const changes = diffValues(left, right);
+  return {
+    isEqual: changes.length === 0,
+    changes
+  };
+}
+function mergeJsonValues(values) {
+  if (values.length < 2) {
+    throw new BRUtilsError("Merge requires at least two JSON sources.");
+  }
+  return values.slice(1).reduce((accumulator, current) => {
+    return deepMerge(accumulator, current);
+  }, cloneJsonValue(values[0]));
+}
+function convertJsonToYaml(value) {
+  return toYamlLines(value).join("\n");
+}
+
+// src/cli/shared/io.ts
+function readTextSource(options) {
+  if (options.text && options.file) {
+    throw new Error("Use either --text or --file, not both.");
+  }
+  if (options.text !== void 0) {
+    return options.text;
+  }
+  if (options.file) {
+    return fs6.readFileSync(options.file, "utf-8");
+  }
+  throw new Error("One of --text or --file is required.");
+}
+function normalizeStringList(value) {
+  if (value === void 0) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+function readSingleJsonSource(options) {
+  if (options.file && options.value) {
+    throw new Error("Use either --file or --value, not both.");
+  }
+  if (options.file) {
+    const raw = fs6.readFileSync(options.file, "utf-8");
+    return {
+      sourcePath: options.file,
+      raw,
+      parsed: parseJsonInput(raw)
+    };
+  }
+  if (options.value !== void 0) {
+    return {
+      raw: options.value,
+      parsed: parseJsonInput(options.value)
+    };
+  }
+  throw new Error("One of --file or --value is required.");
+}
+function readMultipleJsonSources(options) {
+  const fileValues = normalizeStringList(options.file);
+  const inlineValues = normalizeStringList(options.value);
+  if (fileValues.length + inlineValues.length < 2) {
+    throw new Error(
+      "Provide at least two JSON sources via --file and/or --value."
+    );
+  }
+  return [
+    ...fileValues.map((filePath) => {
+      const raw = fs6.readFileSync(filePath, "utf-8");
+      return parseJsonInput(raw);
+    }),
+    ...inlineValues.map((value) => parseJsonInput(value))
+  ];
+}
+function readDiffJsonSource(value) {
+  if (fs6.existsSync(value) && fs6.statSync(value).isFile()) {
+    return parseJsonInput(fs6.readFileSync(value, "utf-8"));
+  }
+  return parseJsonInput(value);
+}
+function writeTextFile(pathValue, content) {
+  fs6.writeFileSync(pathValue, content, "utf-8");
+}
+function readItems(items, file) {
+  if (items && file) {
+    throw new Error("Use either --items or --file, not both.");
+  }
+  if (!items && !file) {
+    throw new Error("One of --items or --file is required.");
+  }
+  if (items) {
+    const parsed2 = items.split(",").map((item) => item.trim()).filter(Boolean);
+    if (parsed2.length === 0) {
+      throw new Error("The --items value did not produce any usable items.");
+    }
+    return parsed2;
+  }
+  const content = fs6.readFileSync(file, "utf-8");
+  const parsed = content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (parsed.length === 0) {
+    throw new Error(
+      "The file passed to --file did not contain any usable items."
+    );
+  }
+  return parsed;
+}
+
+// src/cli/commands/register-random.ts
+function registerRandomCommands(program) {
+  const randomNumber = program.command("random-number").alias("rand").description(
+    "Generate random integers, floats, picks, shuffles, dice rolls and coin flips."
+  ).addHelpText(
+    "after",
+    examples([
+      "brutils random-number int --min 1 --max 100 --count 5 --sorted",
+      "brutils random-number float --min 0 --max 1 --count 3 --precision 4",
+      'brutils random-number pick --items "red,blue,green" --count 2 --unique',
+      "brutils random-number shuffle --file ./items.txt",
+      "brutils random-number dice --faces 20 --count 2",
+      "brutils random-number coin --seed 42"
+    ])
+  );
+  randomNumber.command("int").alias("generate").description("Generate random integers within a range.").option("--min <number>", "Minimum integer value.", parseInteger).option("--max <number>", "Maximum integer value.", parseInteger).option(
+    "--count <number>",
+    "How many values to generate.",
+    parsePositiveInteger,
+    1
+  ).option("--unique", "Avoid duplicates when generating multiple values.").option("--sorted", "Sort the generated values in ascending order.").option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).option(
+    "--format <mode>",
+    "Output mode: plain, json or csv.",
+    parseRandomFormat,
+    "plain"
+  ).action(
+    (options) => {
+      printRandomValues(generateRandomIntegers(options), options.format);
+    }
+  );
+  randomNumber.command("float").description("Generate random floating-point numbers within a range.").option("--min <number>", "Minimum numeric value.", parseNumber).option("--max <number>", "Maximum numeric value.", parseNumber).option(
+    "--count <number>",
+    "How many values to generate.",
+    parsePositiveInteger,
+    1
+  ).option("--sorted", "Sort the generated values in ascending order.").option(
+    "--precision <number>",
+    "Number of decimal places to preserve.",
+    parsePositiveInteger
+  ).option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).option(
+    "--format <mode>",
+    "Output mode: plain, json or csv.",
+    parseRandomFormat,
+    "plain"
+  ).action(
+    (options) => {
+      printRandomValues(generateRandomFloats(options), options.format);
+    }
+  );
+  randomNumber.command("pick").description("Pick one or more items from a list.").option("--items <csv>", "Comma-separated items to pick from.").option(
+    "--file <path>",
+    "Read source items from a text file (one per line)."
+  ).option(
+    "--count <number>",
+    "How many items to pick.",
+    parsePositiveInteger,
+    1
+  ).option("--unique", "Avoid duplicate picks when possible.").option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).option(
+    "--format <mode>",
+    "Output mode: plain, json or csv.",
+    parseRandomFormat,
+    "plain"
+  ).action(
+    (options) => {
+      const values = pickRandomItems({
+        items: readItems(options.items, options.file),
+        count: options.count,
+        ...options.unique !== void 0 ? { unique: options.unique } : {},
+        ...options.seed !== void 0 ? { seed: options.seed } : {}
+      });
+      printRandomValues(values, options.format);
+    }
+  );
+  randomNumber.command("shuffle").description("Shuffle a list of items.").option("--items <csv>", "Comma-separated items to shuffle.").option(
+    "--file <path>",
+    "Read source items from a text file (one per line)."
+  ).option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).option(
+    "--format <mode>",
+    "Output mode: plain, json or csv.",
+    parseRandomFormat,
+    "plain"
+  ).action(
+    (options) => {
+      const values = shuffleRandomItems({
+        items: readItems(options.items, options.file),
+        ...options.seed !== void 0 ? { seed: options.seed } : {}
+      });
+      printRandomValues(values, options.format);
+    }
+  );
+  randomNumber.command("dice").description("Roll one or more dice.").option(
+    "--faces <number>",
+    "Number of faces on the die.",
+    parsePositiveInteger,
+    6
+  ).option(
+    "--count <number>",
+    "How many rolls to generate.",
+    parsePositiveInteger,
+    1
+  ).option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).option(
+    "--format <mode>",
+    "Output mode: plain, json or csv.",
+    parseRandomFormat,
+    "plain"
+  ).action(
+    (options) => {
+      printRandomValues(rollDice(options), options.format);
+    }
+  );
+  randomNumber.command("coin").description("Flip a coin once.").option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).action((options) => {
+    printValue(flipCoin(options));
+  });
+  const numberPicker = program.command("number-picker").alias("pick-number").description("Pick a single random integer within a range.").addHelpText(
+    "after",
+    examples([
+      "brutils number-picker run --min 1 --max 10",
+      "brutils number-picker run --min 100 --max 999 --seed 42"
+    ])
+  );
+  numberPicker.command("run").description("Pick one random integer.").option("--min <number>", "Minimum integer value.", parseInteger).option("--max <number>", "Maximum integer value.", parseInteger).option(
+    "--seed <number>",
+    "Seed used for deterministic output.",
+    parseInteger
+  ).action((options) => {
+    printValue(pickRandomNumber(options));
+  });
+}
+
+// src/services/str/str.service.ts
+function ensureNonNegativeInteger(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new BRUtilsError(`${label} must be a non-negative integer.`);
+  }
+}
+function splitWords(value) {
+  return value.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/[_\-.]+/g, " ").trim().split(/\s+/).filter(Boolean).map((word) => word.toLowerCase());
+}
+function capitalize(word) {
+  if (word.length === 0) {
+    return word;
+  }
+  return word[0].toUpperCase() + word.slice(1).toLowerCase();
+}
+function encodeHtmlEntities(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function decodeHtmlEntities(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+function buildGlobalRegex(pattern) {
+  try {
+    return new RegExp(pattern, "g");
+  } catch {
+    throw new BRUtilsError(`Invalid regex pattern: ${pattern}`);
+  }
+}
+function extractUsingDelimiters(value, query) {
+  const separatorIndex = query.indexOf("|");
+  if (separatorIndex === -1) {
+    throw new BRUtilsError(
+      'Delimiter extraction expects a query in the format "start|end".'
+    );
+  }
+  const startDelimiter = query.slice(0, separatorIndex);
+  const endDelimiter = query.slice(separatorIndex + 1);
+  if (startDelimiter.length === 0 || endDelimiter.length === 0) {
+    throw new BRUtilsError(
+      "Delimiter extraction expects non-empty start and end delimiters."
+    );
+  }
+  const matches = [];
+  let cursor = 0;
+  while (cursor < value.length) {
+    const startIndex = value.indexOf(startDelimiter, cursor);
+    if (startIndex === -1) {
+      break;
+    }
+    const contentStart = startIndex + startDelimiter.length;
+    const endIndex = value.indexOf(endDelimiter, contentStart);
+    if (endIndex === -1) {
+      break;
+    }
+    matches.push(value.slice(contentStart, endIndex));
+    cursor = endIndex + endDelimiter.length;
+  }
+  return matches;
+}
+function slugifyText(value) {
+  return removeAccents(value).toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+}
+function convertStringCase(value, style) {
+  const words = splitWords(value);
+  if (words.length === 0) {
+    return "";
+  }
+  switch (style) {
+    case "camel":
+      return words[0] + words.slice(1).map(capitalize).join("");
+    case "snake":
+      return words.join("_");
+    case "kebab":
+      return words.join("-");
+    case "pascal":
+      return words.map(capitalize).join("");
+    case "constant":
+      return words.join("_").toUpperCase();
+    case "title":
+      return words.map(capitalize).join(" ");
+  }
+}
+function trimText(value) {
+  return value.trim();
+}
+function truncateText(value, options) {
+  ensureNonNegativeInteger(options.max, "Maximum length");
+  if (value.length <= options.max) {
+    return value;
+  }
+  const suffix = options.suffix ?? "";
+  if (suffix.length >= options.max) {
+    return suffix.slice(0, options.max);
+  }
+  return value.slice(0, options.max - suffix.length) + suffix;
+}
+function replaceText(value, options) {
+  if (options.regex) {
+    return value.replace(buildGlobalRegex(options.from), options.with);
+  }
+  return value.replaceAll(options.from, options.with);
+}
+function normalizeText(value) {
+  return value.normalize("NFC");
+}
+function removeAccents(value) {
+  return value.normalize("NFD").replace(/[̀-ͯ]/g, "");
+}
+function padText(value, options) {
+  ensureNonNegativeInteger(options.length, "Target length");
+  const side = options.side ?? "right";
+  if (value.length >= options.length) {
+    return value;
+  }
+  switch (side) {
+    case "left":
+      return value.padStart(options.length);
+    case "right":
+      return value.padEnd(options.length);
+    case "both": {
+      const totalPadding = options.length - value.length;
+      const leftPadding = Math.floor(totalPadding / 2);
+      const rightPadding = totalPadding - leftPadding;
+      return `${" ".repeat(leftPadding)}${value}${" ".repeat(rightPadding)}`;
+    }
+  }
+}
+function extractText(value, query, options = {}) {
+  if (options.regex) {
+    const matches = Array.from(value.matchAll(buildGlobalRegex(query)));
+    return matches.flatMap((match) => {
+      const groups = match.slice(1).filter((group) => group !== void 0);
+      return groups.length > 0 ? groups : [match[0]];
+    });
+  }
+  return extractUsingDelimiters(value, query);
+}
+function transformBase64(value, mode = "encode") {
+  if (mode === "decode") {
+    return Buffer.from(value, "base64").toString("utf-8");
+  }
+  return Buffer.from(value, "utf-8").toString("base64");
+}
+function transformUrlEncoding(value, mode = "encode") {
+  if (mode === "decode") {
+    return decodeURIComponent(value);
+  }
+  return encodeURIComponent(value);
+}
+function transformHtmlEntities(value, mode = "encode") {
+  if (mode === "decode") {
+    return decodeHtmlEntities(value);
+  }
+  return encodeHtmlEntities(value);
+}
+function getLevenshteinDistance(a, b) {
+  a = a.trim();
+  b = b.trim();
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from(
+    { length: n + 1 },
+    () => new Array(m + 1).fill(0)
+  );
+  for (let i = 0; i <= n; i++) dp[i][0] = i;
+  for (let j = 0; j <= m; j++) dp[0][j] = j;
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[n][m];
+}
+
+// src/cli/commands/register-text-data.ts
+function registerTextDataCommands(program) {
+  const str = program.command("str").description("String transformations and encoding helpers.").addHelpText(
+    "after",
+    examples([
+      'brutils str slug --text "Hello Cool World"',
+      'brutils str case --text "my cool variable" --to camel',
+      'brutils str truncate --text "hello world" --max 8 --suffix "..."',
+      'brutils str replace --text "hello 123" --from "\\\\d+" --with "X" --regex',
+      'brutils str extract "\\\\[(.*?)\\\\]" --text "[one] [two]" --regex',
+      'brutils str base64 --text "hello" --mode encode',
+      'brutils str leven "kitten" "sitting"'
+    ])
+  );
+  str.command("slug").description("Convert text to a URL-friendly slug.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").action((options) => {
+    printValue(slugifyText(readTextSource(options)));
+  });
+  str.command("case").description("Convert text between casing styles.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").requiredOption(
+    "--to <style>",
+    "Target style: camel, snake, kebab, pascal, constant or title.",
+    parseStringCaseStyle
+  ).action(
+    (options) => {
+      printValue(convertStringCase(readTextSource(options), options.to));
+    }
+  );
+  str.command("trim").description("Remove surrounding spaces and newlines.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").action((options) => {
+    printValue(trimText(readTextSource(options)));
+  });
+  str.command("truncate").description("Cut text to a maximum length.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").requiredOption("--max <number>", "Maximum length.", parsePositiveInteger).option("--suffix <value>", "Suffix to append after truncation.").action(
+    (options) => {
+      printValue(
+        truncateText(readTextSource(options), {
+          max: options.max,
+          ...options.suffix !== void 0 ? { suffix: options.suffix } : {}
+        })
+      );
+    }
+  );
+  str.command("replace").description("Replace text fragments or regex matches.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").requiredOption("--from <value>", "Text or regex pattern to replace.").requiredOption("--with <value>", "Replacement value.").option("--regex", "Interpret --from as a regex pattern.").action(
+    (options) => {
+      printValue(
+        replaceText(readTextSource(options), {
+          from: options.from,
+          with: options.with,
+          ...options.regex !== void 0 ? { regex: options.regex } : {}
+        })
+      );
+    }
+  );
+  str.command("normalize").description("Normalize text using Unicode NFC.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").action((options) => {
+    printValue(normalizeText(readTextSource(options)));
+  });
+  str.command("remove-accents").description("Remove accents and diacritics from text.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").action((options) => {
+    printValue(removeAccents(readTextSource(options)));
+  });
+  str.command("pad").description("Pad a string with spaces on the left, right or both sides.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").requiredOption(
+    "--length <number>",
+    "Target text length.",
+    parsePositiveInteger
+  ).option(
+    "--side <side>",
+    "Pad direction: left, right or both.",
+    parseStringPadSide,
+    "right"
+  ).action(
+    (options) => {
+      printValue(
+        padText(readTextSource(options), {
+          length: options.length,
+          side: options.side
+        })
+      );
+    }
+  );
+  str.command("extract").argument("<query>", 'Regex pattern or delimiter pair such as "start|end".').description("Extract content by regex or by delimiter pairs.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").option("--regex", "Interpret the query as a regex pattern.").action(
+    (query, options) => {
+      printValue(
+        extractText(readTextSource(options), query, {
+          ...options.regex !== void 0 ? { regex: options.regex } : {}
+        })
+      );
+    }
+  );
+  str.command("base64").description("Encode or decode Base64 values.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").option(
+    "--mode <mode>",
+    "Use encode or decode mode.",
+    parseStringCodecMode,
+    "encode"
+  ).action(
+    (options) => {
+      printValue(transformBase64(readTextSource(options), options.mode));
+    }
+  );
+  str.command("urlencode").description("Encode or decode URL-safe content.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").option(
+    "--mode <mode>",
+    "Use encode or decode mode.",
+    parseStringCodecMode,
+    "encode"
+  ).action(
+    (options) => {
+      printValue(transformUrlEncoding(readTextSource(options), options.mode));
+    }
+  );
+  str.command("html").description("Encode or decode basic HTML entities.").option("--text <value>", "Inline text input.").option("--file <path>", "Read input text from a file.").option(
+    "--mode <mode>",
+    "Use encode or decode mode.",
+    parseStringCodecMode,
+    "encode"
+  ).action(
+    (options) => {
+      printValue(
+        transformHtmlEntities(readTextSource(options), options.mode)
+      );
+    }
+  );
+  str.description("Calculates the Levenshtein distance between two strings").command("leven").argument("<a>").argument("<b>").action((a, b) => {
+    printValue(getLevenshteinDistance(a, b));
+  });
+  const jsonCommand = program.command("json").description("Local JSON formatting, editing and diff helpers.").addHelpText(
+    "after",
+    examples([
+      "brutils json format --file ./config.json --sort-keys",
+      `brutils json validate --value '{"ok":true}'`,
+      "brutils json get --file ./config.json --path server.port",
+      "brutils json set --file ./config.json --path flags.dev --set-value true --in-place",
+      "brutils json diff --left ./a.json --right ./b.json",
+      "brutils json merge --file ./base.json --file ./override.json",
+      `brutils json to-yaml --value '{"name":"brutils"}'`
+    ])
+  );
+  jsonCommand.command("format").description("Pretty-print JSON.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").option(
+    "--indent <number>",
+    "Pretty-print indentation size.",
+    parseInteger,
+    2
+  ).option("--sort-keys", "Sort object keys recursively before printing.").option("--in-place", "Write the formatted content back to the input file.").action(
+    (options) => {
+      const source = readSingleJsonSource(options);
+      const result = formatJsonValue(
+        source.parsed,
+        options.indent,
+        options.sortKeys ?? false
+      );
+      if (options.inPlace) {
+        if (!source.sourcePath) {
+          throw new Error("--in-place requires --file.");
+        }
+        writeTextFile(source.sourcePath, `${result}
+`);
+      }
+      printValue(result);
+    }
+  );
+  jsonCommand.command("minify").description("Minify JSON.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").option("--in-place", "Write the minified content back to the input file.").action((options) => {
+    const source = readSingleJsonSource(options);
+    const result = minifyJsonValue(source.parsed);
+    if (options.inPlace) {
+      if (!source.sourcePath) {
+        throw new Error("--in-place requires --file.");
+      }
+      writeTextFile(source.sourcePath, result);
+    }
+    printValue(result);
+  });
+  jsonCommand.command("validate").description("Validate JSON syntax.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").action((options) => {
+    const source = readSingleJsonSource(options);
+    printValue(validateJsonInput(source.raw));
+  });
+  jsonCommand.command("get").description("Read a path from JSON.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").requiredOption("--path <value>", "JSON path to read.").action((options) => {
+    const source = readSingleJsonSource(options);
+    printValue(getJsonPathValue(source.parsed, options.path));
+  });
+  jsonCommand.command("set").description("Write a path in JSON.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").requiredOption("--path <value>", "JSON path to update.").requiredOption(
+    "--set-value <json>",
+    "New JSON value to write at the path."
+  ).option("--in-place", "Write the updated content back to the input file.").action(
+    (options) => {
+      const source = readSingleJsonSource(options);
+      const updated = setJsonPathValue(
+        source.parsed,
+        options.path,
+        parseJsonInput(options.setValue)
+      );
+      const formatted = formatJsonValue(updated, 2, false);
+      if (options.inPlace) {
+        if (!source.sourcePath) {
+          throw new Error("--in-place requires --file.");
+        }
+        writeTextFile(source.sourcePath, `${formatted}
+`);
+      }
+      printValue(updated);
+    }
+  );
+  jsonCommand.command("delete").description("Remove a path from JSON.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").requiredOption("--path <value>", "JSON path to delete.").option("--in-place", "Write the updated content back to the input file.").action(
+    (options) => {
+      const source = readSingleJsonSource(options);
+      const updated = deleteJsonPathValue(source.parsed, options.path);
+      const formatted = formatJsonValue(updated, 2, false);
+      if (options.inPlace) {
+        if (!source.sourcePath) {
+          throw new Error("--in-place requires --file.");
+        }
+        writeTextFile(source.sourcePath, `${formatted}
+`);
+      }
+      printValue(updated);
+    }
+  );
+  jsonCommand.command("diff").description("Diff two JSON values or files.").requiredOption(
+    "--left <source>",
+    "Left JSON file path or inline JSON value."
+  ).requiredOption(
+    "--right <source>",
+    "Right JSON file path or inline JSON value."
+  ).action((options) => {
+    printValue(
+      diffJsonValues(
+        readDiffJsonSource(options.left),
+        readDiffJsonSource(options.right)
+      )
+    );
+  });
+  jsonCommand.command("merge").description("Merge multiple JSON sources.").option("--file <paths...>", "Read JSON from one or more files.").option("--value <json...>", "Read one or more inline JSON values.").action(
+    (options) => {
+      printValue(mergeJsonValues(readMultipleJsonSources(options)));
+    }
+  );
+  jsonCommand.command("to-yaml").description("Convert JSON to YAML.").option("--file <path>", "Read JSON from a file.").option("--value <json>", "Read JSON inline.").action((options) => {
+    const source = readSingleJsonSource(options);
+    printValue(convertJsonToYaml(source.parsed));
+  });
+}
+
+// src/cli/create-program.ts
+var CLI_VERSION = "1.1.0";
+function buildProgram() {
+  const program = new Command();
+  configureProgramUi(program);
+  program.name("brutils").description("Core Brazilian developer utilities CLI.").version(CLI_VERSION).showHelpAfterError("(use --help for detailed usage)").showSuggestionAfterError(true).addHelpText("after", rootFooter());
+  registerBrazilianCommands(program);
+  registerTextDataCommands(program);
+  registerHelperCommands(program);
+  registerRandomCommands(program);
+  registerArchiveCommands(program);
+  return program;
+}
+
+// src/cli.ts
+buildProgram().parseAsync(process.argv).catch((error) => {
+  handleCliError(error);
+});
+//# sourceMappingURL=cli.js.map