hexpass 1.0.0 → 1.0.2

package/README.md

@@ -21,15 +21,20 @@ npx hexpass
 ```
 hexpass [length]
 hexpass --bytes <n>
+hexpass --count <n>
+hexpass --env <NAME>
+hexpass --json
 hexpass --help
 hexpass --version
-hexpass --copy
 ```
 
 - Default: `hexpass` outputs a 32-character hex string.
 - `hexpass 64` outputs a 64-character string.
-- `hexpass 33` supports odd lengths (generates extra byte and truncates).
-- `hexpass --bytes 16` uses 16 random bytes (32 characters of hex).
+- `hexpass 33` supports odd lengths (generates the necessary extra byte and truncates to the requested number of hex characters).
+- `hexpass --bytes 16` uses 16 random bytes (32 hex characters).
+- `hexpass 32 --count 5` generates 5 secrets, each on its own line.
+- `hexpass 48 --env JWT_SECRET` outputs `JWT_SECRET=<secret>` format.
+- `hexpass 32 --json` outputs a JSON object with `length`, `bytes`, and `hex` fields (single secret only).
 
 ## Options
 
@@ -37,30 +42,64 @@ hexpass --copy
 | --- | --- |
 | `length` | Desired hex string length (default 32, max 1024) |
 | `--bytes <n>` | Generate from n bytes (output has n×2 characters) |
-| `--copy`, `-c` | Copy the generated hex string to the clipboard |
+| `--count <n>`, `-n` | Generate n secrets (default 1, max 100) |
+| `--env <NAME>`, `-e` | Output as `NAME=secret` instead of raw secret (only valid for single secret) |
+| `--json`, `-j` | Output as JSON object (single secret only; incompatible with `--env` and `--copy`) |
+| `--copy`, `-c` | Copy the generated hex string to the clipboard (single secret only) |
 | `--help`, `-h` | Show usage information |
 | `--version`, `-v` | Show version number |
 
+### Notes on compatibility
+
+- `--json` is only supported for single-secret output (`--count` must be 1).
+- `--env` and `--json` are incompatible — use one or the other depending on whether you want an assignment string or structured data.
+- `--copy` works only for single-secret output and is incompatible with `--json`.
+
 ## Examples
 
 ```
-# Quickly generate a secret
-hexpass 64
+# Quickly generate a secret (default 32 chars)
+hexpass
 
-# Populate .env
-JWT_SECRET=$(hexpass 48)
+# Generate a longer secret
+hexpass 64
 
-# Create API key
+# Use explicit byte count (generates n * 2 hex chars)
 hexpass --bytes 32 > api-key.txt
 
-# Generate and copy instantly
+# Generate and copy a secret (single secret)
 hexpass 48 --copy
+
+# Generate multiple secrets in one go
+hexpass 32 --count 5
+
+# Output as environment variable format
+hexpass 48 --env JWT_SECRET
+# Output: JWT_SECRET=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f
+
+# Output as JSON for automation (single secret)
+hexpass 32 --json
+# Output: {"length":32,"bytes":16,"hex":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"}
 ```
 
 ## Security
 
 `hexpass` always uses `crypto.randomBytes()` from Node.js for cryptographically strong randomness. No weak sources like `Math.random()` are used.
 
+## Testing
+
+The repository includes a small CLI test script used during development. You can exercise common invocations with:
+
+```
+npm test
+```
+
+This runs several `hexpass` variants to validate behavior (lengths, bytes, `--count`, `--env`, and `--json`).
+
+## Version
+
+This README reflects the changes introduced in version 1.0.1 (modular refactor and new CLI options).
+
 ## License
 
 MIT

package/bin/hexpass.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { run } = require("../src/cli");
+
+run(process.argv.slice(2), process.stdout, process.stderr, process.exit);

package/index.js

@@ -1,201 +1,7 @@
-#!/usr/bin/env node
+const { run } = require("./src/cli");
 
-const crypto = require("crypto");
-const { spawnSync } = require("child_process");
-const { version } = require("./package.json");
-
-const DEFAULT_LENGTH = 32;
-const MAX_LENGTH = 1024;
-const MAX_BYTES = MAX_LENGTH / 2;
-
-const args = process.argv.slice(2);
-
-const parsed = parseArgs(args);
-
-if (parsed.action === "help") {
-  printHelp();
-  process.exit(0);
-}
-
-if (parsed.action === "version") {
-  console.log(version);
-  process.exit(0);
-}
-
-if (parsed.bytes != null && parsed.lengthValue != null) {
-  exitWithError("Provide either a length or --bytes, not both.");
-}
-
-let charLength;
-
-if (parsed.bytes != null) {
-  const byteLength = parseByteLength(parsed.bytes);
-  if (byteLength * 2 > MAX_LENGTH) {
-    exitWithError(
-      `Byte length exceeds maximum of ${MAX_BYTES} bytes (${MAX_LENGTH} characters).`
-    );
-  }
-  charLength = byteLength * 2;
-} else if (parsed.lengthValue != null) {
-  const length = parseCharacterLength(parsed.lengthValue);
-  if (length > MAX_LENGTH) {
-    exitWithError(`Length exceeds maximum of ${MAX_LENGTH} characters.`);
-  }
-  charLength = length;
-} else {
-  charLength = DEFAULT_LENGTH;
+if (require.main === module) {
+  run(process.argv.slice(2), process.stdout, process.stderr, process.exit);
 }
 
-const password = generateHex(charLength);
-process.stdout.write(`${password}\n`);
-
-if (parsed.copy) {
-  try {
-    copyToClipboard(password);
-  } catch (error) {
-    exitWithError(error.message || "Failed to copy to clipboard.");
-  }
-}
-
-function parseArgs(argv) {
-  let lengthValue = null;
-  let bytes = null;
-  let copy = false;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-
-    if (arg === "--help" || arg === "-h") {
-      return { action: "help" };
-    }
-
-    if (arg === "--version" || arg === "-v") {
-      return { action: "version" };
-    }
-
-    if (arg === "--bytes") {
-      if (bytes != null) {
-        exitWithError("The --bytes option can only be specified once.");
-      }
-      const next = argv[i + 1];
-      if (!next) {
-        exitWithError("Missing value for --bytes.");
-      }
-      bytes = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--copy" || arg === "-c") {
-      copy = true;
-      continue;
-    }
-
-    if (arg.startsWith("--")) {
-      exitWithError(`Unknown option: ${arg}`);
-    }
-
-    if (lengthValue != null) {
-      exitWithError("Multiple length values provided.");
-    }
-
-    lengthValue = arg;
-  }
-
-  return { action: "generate", lengthValue, bytes, copy };
-}
-
-function parseCharacterLength(value) {
-  const num = Number(value);
-  if (!Number.isFinite(num) || !Number.isInteger(num)) {
-    exitWithError(`Invalid length: '${value}'. Must be a positive integer.`);
-  }
-  if (num <= 0) {
-    exitWithError("Length must be a positive integer.");
-  }
-  return num;
-}
-
-function parseByteLength(value) {
-  const num = Number(value);
-  if (!Number.isFinite(num) || !Number.isInteger(num)) {
-    exitWithError(
-      `Invalid byte length: '${value}'. Must be a positive integer.`
-    );
-  }
-  if (num <= 0) {
-    exitWithError("Byte length must be a positive integer.");
-  }
-  return num;
-}
-
-function generateHex(charLength) {
-  const bytesNeeded = Math.ceil(charLength / 2);
-  const hex = crypto.randomBytes(bytesNeeded).toString("hex");
-  return hex.slice(0, charLength);
-}
-
-function printHelp() {
-  console.log(
-    `hexpass - Generate cryptographically secure hex passwords\n\n` +
-      `Usage:\n` +
-      `  hexpass [length]        Generate hex string with specified length (default: ${DEFAULT_LENGTH})\n` +
-      `  hexpass --bytes <n>     Generate from n random bytes (output has n*2 characters)\n\n` +
-      `Options:\n` +
-      `  -h, --help             Show this help message\n` +
-      `  -v, --version          Show version number\n` +
-      `  -c, --copy             Copy the generated hex string to clipboard\n` +
-      `  --bytes <n>            Specify length in bytes instead of characters\n\n` +
-      `Examples:\n` +
-      `  hexpass               # 32-character hex string\n` +
-      `  hexpass 64            # 64-character hex string\n` +
-      `  hexpass --bytes 32    # 64-character hex string (32 bytes)\n` +
-      `  hexpass 48 --copy     # Generate 48 chars and copy to clipboard\n\n` +
-      `Limits:\n` +
-      `  Maximum output length is ${MAX_LENGTH} characters (${MAX_BYTES} bytes).\n\n` +
-      `Security:\n` +
-      `  All passwords are generated using Node.js crypto.randomBytes()`
-  );
-}
-
-function exitWithError(message) {
-  console.error(`Error: ${message}`);
-  process.exit(1);
-}
-
-function copyToClipboard(text) {
-  const platform = process.platform;
-
-  if (platform === "darwin") {
-    runClipboardCommand("pbcopy", text);
-    return;
-  }
-
-  if (platform === "win32") {
-    runClipboardCommand("clip", text);
-    return;
-  }
-
-  const linuxCommands = [
-    ["xclip", ["-selection", "clipboard"]],
-    ["xsel", ["--clipboard", "--input"]],
-  ];
-
-  for (const [cmd, args] of linuxCommands) {
-    const result = spawnSync(cmd, args, { input: text, encoding: "utf8" });
-    if (!result.error && result.status === 0) {
-      return;
-    }
-  }
-
-  throw new Error(
-    "Clipboard copy not supported on this system. Install xclip or xsel."
-  );
-}
-
-function runClipboardCommand(command, input) {
-  const result = spawnSync(command, [], { input, encoding: "utf8" });
-  if (result.error || result.status !== 0) {
-    throw new Error(`Failed to copy to clipboard using ${command}.`);
-  }
-}
+module.exports = { run };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "hexpass",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Generate cryptographically secure hexadecimal passwords and secrets",
   "main": "index.js",
   "bin": {
-    "hexpass": "./index.js"
+    "hexpass": "bin/hexpass.js"
   },
   "scripts": {
-    "test": "node index.js && node index.js 64 && node index.js --bytes 16"
+    "test": "node test.js"
   },
   "keywords": [
     "password",
@@ -19,12 +19,22 @@
     "jwt",
     "api-key"
   ],
-  "author": "",
+  "author": "Tejaswan Kalluri",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tejaswankalluri/hexpass.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tejaswankalluri/hexpass/issues"
+  },
+  "homepage": "https://github.com/tejaswankalluri/hexpass#readme",
   "engines": {
     "node": ">=14.0.0"
   },
   "files": [
+    "bin/",
+    "src/",
     "index.js",
     "LICENSE",
     "README.md"

package/src/args.js

@@ -0,0 +1,153 @@
+const DEFAULT_LENGTH = 32;
+const MAX_LENGTH = 1024;
+const MAX_BYTES = MAX_LENGTH / 2;
+const MAX_COUNT = 100;
+
+function parseArgs(argv) {
+  let lengthValue = null;
+  let bytes = null;
+  let copy = false;
+  let count = 1;
+  let envName = null;
+  let json = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "--help" || arg === "-h") {
+      return { action: "help" };
+    }
+
+    if (arg === "--version" || arg === "-v") {
+      return { action: "version" };
+    }
+
+    if (arg === "--bytes") {
+      if (bytes != null) {
+        throw new Error("The --bytes option can only be specified once.");
+      }
+      const next = argv[i + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error("Missing value for --bytes.");
+      }
+      bytes = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--copy" || arg === "-c") {
+      copy = true;
+      continue;
+    }
+
+    if (arg === "--count" || arg === "-n") {
+      if (count !== 1) {
+        throw new Error("The --count option can only be specified once.");
+      }
+      const next = argv[i + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error("Missing value for --count.");
+      }
+      const parsedCount = parseCount(next);
+      count = parsedCount;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--env" || arg === "-e") {
+      if (envName != null) {
+        throw new Error("The --env option can only be specified once.");
+      }
+      const next = argv[i + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error("Missing value for --env.");
+      }
+      envName = parseEnvName(next);
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--json" || arg === "-j") {
+      json = true;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (lengthValue != null) {
+      throw new Error("Multiple length values provided.");
+    }
+
+    lengthValue = arg;
+  }
+
+  return { action: "generate", lengthValue, bytes, copy, count, envName, json };
+}
+
+function parseCharacterLength(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || !Number.isInteger(num)) {
+    throw new Error(`Invalid length: '${value}'. Must be a positive integer.`);
+  }
+  if (num <= 0) {
+    throw new Error("Length must be a positive integer.");
+  }
+  return num;
+}
+
+function parseByteLength(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || !Number.isInteger(num)) {
+    throw new Error(
+      `Invalid byte length: '${value}'. Must be a positive integer.`
+    );
+  }
+  if (num <= 0) {
+    throw new Error("Byte length must be a positive integer.");
+  }
+  return num;
+}
+
+function parseCount(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || !Number.isInteger(num)) {
+    throw new Error(
+      `Invalid count: '${value}'. Must be a positive integer.`
+    );
+  }
+  if (num <= 0) {
+    throw new Error("Count must be a positive integer.");
+  }
+  if (num > MAX_COUNT) {
+    throw new Error(`Count exceeds maximum of ${MAX_COUNT}.`);
+  }
+  return num;
+}
+
+function parseEnvName(value) {
+  if (!value || value.trim() === "") {
+    throw new Error("Environment variable name cannot be empty.");
+  }
+  if (value.includes(" ")) {
+    throw new Error("Environment variable name cannot contain spaces.");
+  }
+  return value;
+}
+
+module.exports = {
+  DEFAULT_LENGTH,
+  MAX_LENGTH,
+  MAX_BYTES,
+  MAX_COUNT,
+  parseArgs,
+  parseCharacterLength,
+  parseByteLength,
+  parseCount,
+  parseEnvName
+};

package/src/cli.js

@@ -0,0 +1,103 @@
+const {
+  DEFAULT_LENGTH,
+  MAX_LENGTH,
+  MAX_BYTES,
+  parseArgs,
+  parseCharacterLength,
+  parseByteLength
+} = require("./args");
+const { generateSecrets, bytesUsed } = require("./generator");
+const { formatPlain, formatJson, copyToClipboard } = require("./output");
+const { getHelp } = require("./help");
+const { version } = require("../package.json");
+
+function run(argv, stdout, stderr, exit) {
+  try {
+    const parsed = parseArgs(argv);
+
+    if (parsed.action === "help") {
+      stdout.write(getHelp() + "\n");
+      exit(0);
+      return;
+    }
+
+    if (parsed.action === "version") {
+      stdout.write(version + "\n");
+      exit(0);
+      return;
+    }
+
+    if (parsed.bytes != null && parsed.lengthValue != null) {
+      throw new Error("Provide either a length or --bytes, not both.");
+    }
+
+    if (parsed.count > 1 && parsed.envName != null) {
+      throw new Error("The --env option is only supported for single secret generation (count=1).");
+    }
+
+    if (parsed.count > 1 && parsed.copy) {
+      throw new Error("Copy is only supported for single secret.");
+    }
+
+    if (parsed.json && parsed.count > 1) {
+      throw new Error("JSON mode is only supported for single secret generation (count=1).");
+    }
+
+    if (parsed.json && parsed.envName != null) {
+      throw new Error("JSON mode is not compatible with --env. Use JSON output directly for structured data.");
+    }
+
+    if (parsed.json && parsed.copy) {
+      throw new Error("JSON mode is not compatible with --copy. Use JSON output for automation.");
+    }
+
+    let charLength;
+    let cachedByteLength = null;
+
+    if (parsed.bytes != null) {
+      cachedByteLength = parseByteLength(parsed.bytes);
+      if (cachedByteLength * 2 > MAX_LENGTH) {
+        throw new Error(
+          `Byte length exceeds maximum of ${MAX_BYTES} bytes (${MAX_LENGTH} characters).`
+        );
+      }
+      charLength = cachedByteLength * 2;
+    } else if (parsed.lengthValue != null) {
+      const length = parseCharacterLength(parsed.lengthValue);
+      if (length > MAX_LENGTH) {
+        throw new Error(`Length exceeds maximum of ${MAX_LENGTH} characters.`);
+      }
+      charLength = length;
+    } else {
+      charLength = DEFAULT_LENGTH;
+    }
+
+    const secrets = generateSecrets(charLength, parsed.count);
+
+    if (parsed.json) {
+      const bytes = bytesUsed(charLength, cachedByteLength);
+      const jsonOutput = formatJson(secrets[0], charLength, bytes);
+      stdout.write(jsonOutput + "\n");
+    } else {
+      const output = formatPlain(secrets, parsed.envName);
+      stdout.write(output + "\n");
+
+      if (parsed.copy) {
+        try {
+          copyToClipboard(secrets[0]);
+        } catch (error) {
+          throw new Error(error.message || "Failed to copy to clipboard.");
+        }
+      }
+    }
+
+    exit(0);
+  } catch (error) {
+    stderr.write(`Error: ${error.message}\n`);
+    exit(1);
+  }
+}
+
+module.exports = {
+  run
+};

package/src/generator.js

@@ -0,0 +1,28 @@
+const crypto = require("crypto");
+
+function generateSecrets(charLength, count) {
+  const secrets = [];
+  for (let i = 0; i < count; i += 1) {
+    const secret = generateHex(charLength);
+    secrets.push(secret);
+  }
+  return secrets;
+}
+
+function generateHex(charLength) {
+  const bytesNeeded = Math.ceil(charLength / 2);
+  const hex = crypto.randomBytes(bytesNeeded).toString("hex");
+  return hex.slice(0, charLength);
+}
+
+function bytesUsed(charLength, inputBytes) {
+  if (inputBytes != null) {
+    return inputBytes;
+  }
+  return Math.ceil(charLength / 2);
+}
+
+module.exports = {
+  generateSecrets,
+  bytesUsed
+};

package/src/help.js

@@ -0,0 +1,38 @@
+const { DEFAULT_LENGTH, MAX_LENGTH, MAX_BYTES, MAX_COUNT } = require("./args");
+
+function getHelp() {
+  return (
+    `hexpass - Generate cryptographically secure hex passwords\n\n` +
+    `Usage:\n` +
+    `  hexpass [length]        Generate hex string with specified length (default: ${DEFAULT_LENGTH})\n` +
+    `  hexpass --bytes <n>     Generate from n random bytes (output has n*2 characters)\n` +
+    `  hexpass --count <n>     Generate n secrets (default: 1, max: ${MAX_COUNT})\n` +
+    `  hexpass --env <NAME>    Output as NAME=secret instead of raw secret\n` +
+    `  hexpass --json          Output as JSON object (single secret only)\n\n` +
+    `Options:\n` +
+    `  -h, --help             Show this help message\n` +
+    `  -v, --version          Show version number\n` +
+    `  -c, --copy             Copy the generated hex string to clipboard (single secret only)\n` +
+    `  -n, --count <n>        Generate n secrets (default: 1, max: ${MAX_COUNT})\n` +
+    `  -e, --env <NAME>       Output as NAME=secret (single secret only)\n` +
+    `  -j, --json             Output as JSON object (single secret only, incompatible with --env and --copy)\n` +
+    `  --bytes <n>            Specify length in bytes instead of characters\n\n` +
+    `Examples:\n` +
+    `  hexpass               # 32-character hex string\n` +
+    `  hexpass 64            # 64-character hex string\n` +
+    `  hexpass --bytes 32    # 64-character hex string (32 bytes)\n` +
+    `  hexpass 48 --copy     # Generate 48 chars and copy to clipboard\n` +
+    `  hexpass 32 --count 5  # Generate 5 secrets, each 32 characters\n` +
+    `  hexpass 48 --env JWT_SECRET  # Output as JWT_SECRET=<secret>\n` +
+    `  hexpass 32 --json     # Output as JSON with length, bytes, and hex fields\n\n` +
+    `Limits:\n` +
+    `  Maximum output length is ${MAX_LENGTH} characters (${MAX_BYTES} bytes).\n` +
+    `  Maximum count is ${MAX_COUNT} secrets.\n\n` +
+    `Security:\n` +
+    `  All passwords are generated using Node.js crypto.randomBytes()`
+  );
+}
+
+module.exports = {
+  getHelp
+};

package/src/output.js

@@ -0,0 +1,62 @@
+const { spawnSync } = require("child_process");
+
+function formatPlain(secrets, envName) {
+  const output = secrets.map(secret => {
+    if (envName != null) {
+      return `${envName}=${secret}`;
+    }
+    return secret;
+  }).join("\n");
+  return output;
+}
+
+function formatJson(secret, charLength, bytesValue) {
+  return JSON.stringify({
+    length: charLength,
+    bytes: bytesValue,
+    hex: secret
+  });
+}
+
+function copyToClipboard(text) {
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    runClipboardCommand("pbcopy", text);
+    return;
+  }
+
+  if (platform === "win32") {
+    runClipboardCommand("clip", text);
+    return;
+  }
+
+  const linuxCommands = [
+    ["xclip", ["-selection", "clipboard"]],
+    ["xsel", ["--clipboard", "--input"]],
+  ];
+
+  for (const [cmd, args] of linuxCommands) {
+    const result = spawnSync(cmd, args, { input: text, encoding: "utf8" });
+    if (!result.error && result.status === 0) {
+      return;
+    }
+  }
+
+  throw new Error(
+    "Clipboard copy not supported on this system. Install xclip or xsel."
+  );
+}
+
+function runClipboardCommand(command, input) {
+  const result = spawnSync(command, [], { input, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    throw new Error(`Failed to copy to clipboard using ${command}.`);
+  }
+}
+
+module.exports = {
+  formatPlain,
+  formatJson,
+  copyToClipboard
+};