gen-random-cli 0.0.0-stage → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gen-random-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# gen-random-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate cryptographically secure random hexadecimal values locally from your terminal. After installation, the command works offline: it makes no network requests and includes no tracking or telemetry. It prints both the 128-bit and 256-bit formats by default.
+
+## Security and privacy
+
+Random bytes are generated locally with Node.js `crypto.randomBytes()`, which Node documents as providing cryptographically strong pseudorandom data ([Node.js crypto documentation](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback)). After installation, the generator works offline: it makes no network requests and includes no tracking, telemetry, analytics, or third-party runtime dependencies.
+
+Generated values are printed to the terminal and are not written to files by the CLI. The settings file stores only the prefix. The source is small and available for inspection under the MIT license.
+
+## Requirements
+
+- Node.js 22 or newer
+
+## Install
+
+```sh
+npm install --global gen-random-cli
+```
+
+This installs the commands `gen-random-cli`, `gen-random`, and `genran` locally on your system. To run a command through npm without a global install, use the explicit package option:
+
+```sh
+npx --package gen-random-cli genran --help
+```
+
+`npx genran` asks npm for the separate package named `genran`, not for a binary in `gen-random-cli`. A standalone `genran` package alias must be published separately before that exact invocation can work.
+
+
+## Usage
+
+Print both values:
+
+```sh
+gen-random
+```
+
+Print one format only with `--bits`:
+
+```sh
+gen-random --bits 128
+gen-random --bits 256
+```
+
+Override the prefix for one run with `--prefix`:
+
+```sh
+gen-random --prefix dev_
+gen-random --bits 256 --prefix "service key_"
+```
+
+The default prefix is `sk_`. A command-line prefix does not change the saved setting.
+
+Open the interactive settings menu to change the saved prefix:
+
+```sh
+gen-random settings
+```
+
+Type printable ASCII characters to add to the prefix, use Backspace to remove characters, press Enter to save, or Esc to cancel. Settings are stored in `~/.config/gen-random-cli/settings.json`.
+
+Show all options:
+
+```sh
+gen-random --help
+```
+
+## Output formats
+
+The total character count includes the prefix. With the default `sk_` prefix, the output is:
+
+```text
+128 bits (32 chars): sk_<29 lowercase hex characters>
+256 bits (64 chars): sk_<61 lowercase hex characters>
+```
+
+The prefix is fixed text and adds no randomness. With `sk_`, the random portions contain 116 and 244 bits respectively. If a custom prefix is too long to fit, the output grows to retain at least 112 random bits for the 128-bit format and 128 random bits for the 256-bit format.
+
+## License
+
+MIT

package/bin/gen-random.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const DEFAULT_SETTINGS = {
+  prefix: 'sk_',
+};
+
+const OUTPUT_SIZES = [
+  { targetBits: 128, totalChars: 32, minRandomHexLength: 28 },
+  { targetBits: 256, totalChars: 64, minRandomHexLength: 32 },
+];
+const settingsPath = path.join(os.homedir(), '.config', 'gen-random-cli', 'settings.json');
+
+function isValidSettings(settings) {
+  return typeof settings?.prefix === 'string'
+    && /^[\x20-\x7E]*$/.test(settings.prefix);
+}
+
+function loadSettings() {
+  try {
+    const saved = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    const settings = {
+      prefix: saved?.prefix ?? DEFAULT_SETTINGS.prefix,
+    };
+    if (!isValidSettings(settings)) {
+      return { ...DEFAULT_SETTINGS };
+    }
+    return settings;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) {
+      return { ...DEFAULT_SETTINGS };
+    }
+    throw error;
+  }
+}
+
+function saveSettings(settings) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${settingsPath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporaryPath, settingsPath);
+}
+
+function drawSettingsMenu(settings, notice = '') {
+  process.stdout.write('\u001b[2J\u001b[H');
+  process.stdout.write('gen-random settings\n');
+  process.stdout.write('Type a printable ASCII prefix   Backspace delete   Enter save   Esc cancel\n\n');
+  process.stdout.write(`Prefix: ${settings.prefix || '(empty)'}\n`);
+  if (notice) process.stdout.write(`\n${notice}\n`);
+}
+
+function runSettingsMenu(settings) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+    throw new Error('Settings require an interactive terminal.');
+  }
+
+  return new Promise((resolve) => {
+    const input = process.stdin;
+    const output = process.stdout;
+    const previousRawMode = input.isRaw;
+    const rl = readline.createInterface({ input, output });
+    readline.emitKeypressEvents(input, rl);
+    input.setRawMode(true);
+    input.resume();
+
+    let notice = '';
+    let finished = false;
+
+    const finish = (result) => {
+      if (finished) return;
+      finished = true;
+      input.removeListener('keypress', onKeypress);
+      input.setRawMode(Boolean(previousRawMode));
+      rl.close();
+      output.write('\u001b[2J\u001b[H');
+      resolve(result);
+    };
+
+    const onKeypress = (character, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        finish(null);
+        return;
+      }
+
+      if (key.name === 'escape') {
+        finish(null);
+        return;
+      }
+      if (key.name === 'backspace' || key.name === 'delete') {
+        settings.prefix = [...settings.prefix].slice(0, -1).join('');
+        notice = '';
+      } else if (key.name === 'return') {
+        if (isValidSettings(settings)) finish(settings);
+        else notice = 'Prefix can contain printable ASCII characters only.';
+        return;
+      } else if (!key.ctrl && !key.meta && typeof character === 'string' && /^[\x20-\x7E]$/.test(character)) {
+        settings.prefix += character;
+        notice = '';
+      }
+
+      drawSettingsMenu(settings, notice);
+    };
+
+    input.on('keypress', onKeypress);
+    drawSettingsMenu(settings);
+  });
+}
+
+function printUsage() {
+  process.stdout.write('gen-random - secure random hexadecimal values\n\n');
+  process.stdout.write('Usage:\n');
+  process.stdout.write('  gen-random [--bits 128|256] [--prefix <text>]\n');
+  process.stdout.write('  gen-random settings\n');
+  process.stdout.write('  gen-random --help\n\n');
+  process.stdout.write('Options:\n');
+  process.stdout.write('  --bits <128|256>   Print only the selected format.\n');
+  process.stdout.write('  --prefix <text>    Override the prefix for this run.\n');
+  process.stdout.write('  settings           Edit and save the default prefix.\n');
+  process.stdout.write('  -h, --help          Show this help.\n');
+  process.stdout.write('  -V, --version       Show the installed version.\n\n');
+  process.stdout.write('With no size option, both formats are printed. The default prefix is sk_.\n');
+}
+
+async function main() {
+  const argumentsList = process.argv.slice(2);
+  if (argumentsList.length === 1 && (argumentsList[0] === '--help' || argumentsList[0] === '-h')) {
+    printUsage();
+    return;
+  }
+  if (argumentsList.length === 1 && (argumentsList[0] === '--version' || argumentsList[0] === '-V')) {
+    const packageJson = require('../package.json');
+    process.stdout.write(`${packageJson.version}\n`);
+    return;
+  }
+  if (argumentsList.length === 1 && argumentsList[0] === 'settings') {
+    const settings = loadSettings();
+    const result = await runSettingsMenu(settings);
+    if (result) {
+      saveSettings(result);
+      process.stdout.write(`Settings saved to ${settingsPath}\n`);
+    }
+    return;
+  }
+
+  let selectedBits = 'both';
+  let bitsWereSelected = false;
+  let prefixOverride;
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === '--bits') {
+      if (bitsWereSelected) throw new Error('Use --bits only once.');
+      const value = argumentsList[index + 1];
+      if (value !== '128' && value !== '256') throw new Error('--bits must be 128 or 256.');
+      selectedBits = value;
+      bitsWereSelected = true;
+      index += 1;
+    } else if (argument === '--prefix') {
+      if (index + 1 >= argumentsList.length) throw new Error(`${argument} requires a value.`);
+      prefixOverride = argumentsList[index + 1];
+      if (!/^[\x20-\x7E]*$/.test(prefixOverride)) {
+        throw new Error('Prefix can contain printable ASCII characters only.');
+      }
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+
+  const settings = loadSettings();
+  if (prefixOverride !== undefined) settings.prefix = prefixOverride;
+  const selectedSizes = selectedBits === '128'
+    ? OUTPUT_SIZES.slice(0, 1)
+    : selectedBits === '256'
+      ? OUTPUT_SIZES.slice(1)
+      : OUTPUT_SIZES;
+
+  for (const { targetBits, totalChars, minRandomHexLength } of selectedSizes) {
+    const randomHexLength = Math.max(totalChars - settings.prefix.length, minRandomHexLength);
+    const randomHex = crypto.randomBytes(Math.ceil(randomHexLength / 2)).toString('hex').slice(0, randomHexLength);
+    const value = `${settings.prefix}${randomHex}`;
+    process.stdout.write(`${targetBits} bits (${value.length} chars): ${value}\n`);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`gen-random: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "gen-random-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "A secure multi-length random password generator for your terminal",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "gen-random-cli": "bin/gen-random.js",
+    "gen-random": "bin/gen-random.js",
+    "genran": "bin/gen-random.js"
+  },
+  "files": [
+    "bin/gen-random.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "password",
+    "generator",
+    "cli",
+    "secure-random"
+  ]
+}