@bcts/lifehash-cli 1.0.0-alpha.17

package/LICENSE

@@ -0,0 +1,48 @@
+Copyright © 2025 Blockchain Commons, LLC
+Copyright © 2025-2026 Leonardo Amoroso Custodio
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+Subject to the terms and conditions of this license, each copyright holder and
+contributor hereby grants to those receiving rights under this license a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except for failure to satisfy the conditions of this license) patent license to
+make, have made, use, offer to sell, sell, import, and otherwise transfer this
+software, where such license applies only to those patent claims, already
+acquired or hereafter acquired, licensable by such copyright holder or
+contributor that are necessarily infringed by:
+
+    (a) their Contribution(s) (the licensed copyrights of copyright holders and
+    non-copyrightable additions of contributors, in source or binary form)
+    alone; or
+
+    (b) combination of their Contribution(s) with the work of authorship to
+    which such Contribution(s) was added by such copyright holder or
+    contributor, if, at the time the Contribution is added, such addition causes
+    such combination to be necessarily infringed. The patent license shall not
+    apply to any other combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright
+holder or contributor is granted under this license, whether expressly, by
+implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,109 @@
+# Blockchain Commons LifeHash CLI (TypeScript)
+
+> Disclaimer: This package is under active development and APIs may change.
+
+## Introduction
+
+`@bcts/lifehash-cli` is a command line tool for generating [LifeHash](https://github.com/BlockchainCommons/bc-lifehash) images as PNG files. LifeHash is a beautiful method of hash visualization based on Conway's Game of Life.
+
+Features:
+- Generate LifeHash PNG images from any input string
+- Support for all 5 LifeHash versions (version1, version2, detailed, fiducial, grayscaleFiducial)
+- Configurable module (pixel) size for image scaling
+- Automatic random input generation if none provided
+- Cross-platform (Node.js/Bun)
+
+## Installation
+
+```bash
+# Install globally
+bun add -g @bcts/lifehash-cli
+
+# Or run directly with bunx
+bunx @bcts/lifehash-cli --help
+```
+
+## Usage
+
+### Generate a LifeHash
+
+```bash
+# Generate a version2 (default), 32x32 pixel LifeHash from the string "Hello"
+lifehash Hello
+
+# Output: Hello.png
+```
+
+### Specify Version
+
+```bash
+# Generate a version1 LifeHash (deprecated HSB colors)
+lifehash -v version1 Hello
+
+# Generate a detailed (64x64) LifeHash
+lifehash -v detailed Hello
+
+# Generate a fiducial LifeHash (for machine vision)
+lifehash -v fiducial Hello
+
+# Generate a grayscale fiducial LifeHash
+lifehash -v grayscaleFiducial Hello
+```
+
+### Module Size (Scaling)
+
+```bash
+# Generate a 256x256 image (32x32 with module size 8)
+lifehash -m 8 Hello
+
+# Generate a 512x512 detailed image (64x64 with module size 8)
+lifehash -v detailed -m 8 Hello
+```
+
+### Output Path
+
+```bash
+# Save to a specific directory
+lifehash -p ./output Hello
+
+# Output: ./output/Hello.png
+```
+
+### Random Input
+
+```bash
+# Generate with a random input of the form "XXX-XXX"
+lifehash
+
+# Output: ABC-DEF.png (random letters)
+```
+
+## Command Line Reference
+
+```
+Usage: lifehash [options] [input]
+
+Arguments:
+  input                    Input string to hash (default: random XXX-XXX)
+
+Options:
+  -v, --version <version>  LifeHash version: version1, version2, detailed, fiducial, grayscaleFiducial (default: "version2")
+  -m, --module <size>      Size of each module ("pixel") (default: 1)
+  -p, --path <path>        Output directory path (default: current directory)
+  -h, --help               Display help
+  -V, --version            Display version number
+```
+
+## LifeHash Versions
+
+| Version | Size | Description |
+|---------|------|-------------|
+| `version1` | 32x32 | Original version using HSB color space (deprecated) |
+| `version2` | 32x32 | Default version using CMYK-safe colors |
+| `detailed` | 64x64 | Higher resolution version |
+| `fiducial` | 64x64 | Optimized for machine vision applications |
+| `grayscaleFiducial` | 64x64 | Grayscale version for machine vision |
+
+## C++ Reference Implementation
+
+This TypeScript implementation is based on [bc-lifehash-cli](https://github.com/BlockchainCommons/bc-lifehash-cli).

package/dist/index.cjs

@@ -0,0 +1,317 @@
+let fs = require("fs");
+let pngjs = require("pngjs");
+let commander = require("commander");
+let _bcts_lifehash = require("@bcts/lifehash");
+
+//#region src/png-writer.ts
+/**
+* PNG writer for LifeHash images.
+*
+* Ported from bc-lifehash-cli C++ implementation (png-writer.hpp).
+* Uses pngjs instead of libpng.
+*
+* @module
+*/
+/**
+* Writes a LifeHash image to a PNG file.
+*
+* Port of `write_image()` from lifehash.cpp lines 174-186 and
+* PNGWriter class from png-writer.hpp.
+*
+* @param image - The LifeHash image to write
+* @param filename - The output filename
+* @category PNG Encoding
+*
+* @example
+* ```typescript
+* import { makeFromUtf8 } from "@bcts/lifehash";
+*
+* const image = makeFromUtf8("Hello");
+* writeImage(image, "Hello.png");
+* ```
+*/
+function writeImage(image, filename) {
+	const png = new pngjs.PNG({
+		width: image.width,
+		height: image.height,
+		colorType: 2,
+		bitDepth: 8,
+		inputColorType: 2,
+		inputHasAlpha: false
+	});
+	for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
+		const srcOffset = (y * image.width + x) * 3;
+		const dstOffset = (y * image.width + x) * 4;
+		png.data[dstOffset] = image.colors[srcOffset];
+		png.data[dstOffset + 1] = image.colors[srcOffset + 1];
+		png.data[dstOffset + 2] = image.colors[srcOffset + 2];
+		png.data[dstOffset + 3] = 255;
+	}
+	(0, fs.writeFileSync)(filename, pngjs.PNG.sync.write(png));
+}
+/**
+* Generates a PNG buffer from a LifeHash image without writing to disk.
+*
+* @param image - The LifeHash image to encode
+* @returns A Buffer containing the PNG data
+* @category PNG Encoding
+*
+* @example
+* ```typescript
+* import { makeFromUtf8 } from "@bcts/lifehash";
+*
+* const image = makeFromUtf8("Hello");
+* const pngBuffer = generatePNG(image);
+* ```
+*/
+function generatePNG(image) {
+	const png = new pngjs.PNG({
+		width: image.width,
+		height: image.height,
+		colorType: 2,
+		bitDepth: 8,
+		inputColorType: 2,
+		inputHasAlpha: false
+	});
+	for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
+		const srcOffset = (y * image.width + x) * 3;
+		const dstOffset = (y * image.width + x) * 4;
+		png.data[dstOffset] = image.colors[srcOffset];
+		png.data[dstOffset + 1] = image.colors[srcOffset + 1];
+		png.data[dstOffset + 2] = image.colors[srcOffset + 2];
+		png.data[dstOffset + 3] = 255;
+	}
+	return pngjs.PNG.sync.write(png);
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Utility functions for the LifeHash CLI.
+*
+* Ported from bc-lifehash-cli C++ implementation.
+*
+* @module
+*/
+/**
+* Appends a path component to a path, handling trailing slashes correctly.
+*
+* Port of `appending_path_component()` from lifehash.cpp lines 18-24.
+*
+* @param path - The base path
+* @param component - The component to append
+* @returns The combined path
+* @category Utilities
+*
+* @example
+* ```typescript
+* appendingPathComponent("", "file.png") // => "file.png"
+* appendingPathComponent("/tmp/", "file.png") // => "/tmp/file.png"
+* appendingPathComponent("/tmp", "file.png") // => "/tmp/file.png"
+* ```
+*/
+function appendingPathComponent(path, component) {
+	if (path === "") return component;
+	if (path.endsWith("/")) return `${path}${component}`;
+	return `${path}/${component}`;
+}
+/**
+* Selects a random element from an array.
+*
+* Port of `random_element()` template from lifehash.cpp lines 38-50.
+*
+* @param array - The array to select from
+* @returns A random element from the array
+* @category Utilities
+*
+* @example
+* ```typescript
+* randomElement(["A", "B", "C"]) // => "A" or "B" or "C"
+* ```
+*/
+function randomElement(array) {
+	return array[Math.floor(Math.random() * array.length)];
+}
+/**
+* Generates a random input string in "XXX-XXX" format where X is a random uppercase letter.
+*
+* Port of `make_random_input()` from lifehash.cpp lines 52-57.
+*
+* @returns A random string in "XXX-XXX" format
+* @category Utilities
+*
+* @example
+* ```typescript
+* makeRandomInput() // => "ABC-DEF" (random letters)
+* ```
+*/
+function makeRandomInput() {
+	const letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("");
+	const letter = () => randomElement(letters);
+	const cluster = () => `${letter()}${letter()}${letter()}`;
+	return `${cluster()}-${cluster()}`;
+}
+
+//#endregion
+//#region src/main.ts
+/**
+* LifeHash CLI - Command line tool for generating LifeHash PNG images.
+*
+* Ported from bc-lifehash-cli C++ implementation (lifehash.cpp).
+*
+* @module
+*/
+/**
+* Parses a version string to the Version enum.
+*
+* Port of version parsing logic from lifehash.cpp lines 130-145.
+*
+* @param versionString - The version string from CLI
+* @returns The corresponding Version enum value
+* @throws Error if the version string is invalid
+* @category CLI
+*
+* @example
+* ```typescript
+* parseVersion("version2") // => Version.version2
+* parseVersion("detailed") // => Version.detailed
+* parseVersion("invalid") // throws Error
+* ```
+*/
+function parseVersion(versionString) {
+	switch (versionString) {
+		case "version1": return _bcts_lifehash.Version.version1;
+		case "version2": return _bcts_lifehash.Version.version2;
+		case "detailed": return _bcts_lifehash.Version.detailed;
+		case "fiducial": return _bcts_lifehash.Version.fiducial;
+		case "grayscaleFiducial": return _bcts_lifehash.Version.grayscale_fiducial;
+		default: throw new Error("Invalid version.");
+	}
+}
+/**
+* Main execution function that generates a LifeHash image.
+*
+* Port of `run()` from lifehash.cpp lines 188-192.
+*
+* @param input - Input string to hash (or empty for random)
+* @param options - CLI options
+* @category CLI
+*
+* @example
+* ```typescript
+* run("Hello", { version: "version2", module: "1", path: "." });
+* // Generates Hello.png in current directory
+* ```
+*/
+function run(input, options) {
+	const version = parseVersion(options.version);
+	const moduleSize = parseInt(options.module, 10);
+	if (moduleSize < 1 || isNaN(moduleSize)) throw new Error("Illegal value.");
+	const actualInput = input !== "" ? input : makeRandomInput();
+	const outputFilename = `${actualInput}.png`;
+	const outputFile = appendingPathComponent(options.path, outputFilename);
+	writeImage((0, _bcts_lifehash.makeFromUtf8)(actualInput, version, moduleSize), outputFile);
+}
+/**
+* CLI entry point.
+*
+* Port of `main()` from lifehash.cpp lines 194-206.
+*
+* @category CLI
+*/
+function main() {
+	const program = new commander.Command();
+	program.name("lifehash").description("Generate LifeHash PNG images from input strings").argument("[input]", "Input string to hash (default: random XXX-XXX)").option("-v, --version <version>", "LifeHash version: version1, version2, detailed, fiducial, grayscaleFiducial", "version2").option("-m, --module <size>", "Size of each module (\"pixel\")", "1").option("-p, --path <path>", "Output directory path", "").action((input, options) => {
+		try {
+			run(input ?? "", options);
+		} catch (error) {
+			if (error instanceof Error) {
+				console.log(`\u{1F928} ${error.message}`);
+				console.log();
+				program.help();
+			}
+			process.exit(1);
+		}
+	});
+	program.parse();
+}
+if (typeof process !== "undefined" && typeof process.argv[1] === "string" && (process.argv[1].endsWith("/main.mjs") || process.argv[1].endsWith("/main.js") || process.argv[1].includes("lifehash-cli"))) main();
+
+//#endregion
+//#region src/index.ts
+/**
+* @bcts/lifehash-cli - Command line tool for generating LifeHash PNG images.
+*
+* This package provides both a CLI tool and a programmatic API for generating
+* LifeHash visual hash images as PNG files.
+*
+* @packageDocumentation
+* @module @bcts/lifehash-cli
+*
+* @example CLI Usage
+* ```bash
+* # Generate a LifeHash from a string
+* lifehash Hello
+*
+* # Generate with specific version and module size
+* lifehash -v detailed -m 8 Hello
+*
+* # Generate with random input
+* lifehash
+* ```
+*
+* @example Programmatic Usage
+* ```typescript
+* import { generateLifeHash } from "@bcts/lifehash-cli";
+* import { writeFileSync } from "fs";
+*
+* // Generate a PNG buffer
+* const pngBuffer = generateLifeHash("Hello", {
+*   version: "version2",
+*   moduleSize: 1,
+* });
+*
+* // Write to file
+* writeFileSync("Hello.png", pngBuffer);
+* ```
+*/
+/**
+* Generates a LifeHash PNG buffer from an input string.
+*
+* This is the main programmatic API for generating LifeHash images.
+*
+* @param input - The input string to hash
+* @param options - Generation options
+* @returns A Buffer containing the PNG data
+* @category Image Generation
+*
+* @example
+* ```typescript
+* import { generateLifeHash } from "@bcts/lifehash-cli";
+* import { writeFileSync } from "fs";
+*
+* const pngBuffer = generateLifeHash("Hello", {
+*   version: "version2",
+*   moduleSize: 1,
+* });
+*
+* writeFileSync("Hello.png", pngBuffer);
+* ```
+*/
+function generateLifeHash(input, options = {}) {
+	const { version = "version2", moduleSize = 1 } = options;
+	return generatePNG((0, _bcts_lifehash.makeFromUtf8)(input, parseVersion(version), moduleSize));
+}
+
+//#endregion
+exports.Version = _bcts_lifehash.Version;
+exports.appendingPathComponent = appendingPathComponent;
+exports.generateLifeHash = generateLifeHash;
+exports.generatePNG = generatePNG;
+exports.makeFromUtf8 = _bcts_lifehash.makeFromUtf8;
+exports.makeRandomInput = makeRandomInput;
+exports.parseVersion = parseVersion;
+exports.randomElement = randomElement;
+exports.run = run;
+exports.writeImage = writeImage;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["PNG","Version","Command"],"sources":["../src/png-writer.ts","../src/utils.ts","../src/main.ts","../src/index.ts"],"sourcesContent":["/**\n * PNG writer for LifeHash images.\n *\n * Ported from bc-lifehash-cli C++ implementation (png-writer.hpp).\n * Uses pngjs instead of libpng.\n *\n * @module\n */\n\nimport { writeFileSync } from \"fs\";\nimport { PNG } from \"pngjs\";\nimport type { Image } from \"@bcts/lifehash\";\n\n/**\n * Writes a LifeHash image to a PNG file.\n *\n * Port of `write_image()` from lifehash.cpp lines 174-186 and\n * PNGWriter class from png-writer.hpp.\n *\n * @param image - The LifeHash image to write\n * @param filename - The output filename\n * @category PNG Encoding\n *\n * @example\n * ```typescript\n * import { makeFromUtf8 } from \"@bcts/lifehash\";\n *\n * const image = makeFromUtf8(\"Hello\");\n * writeImage(image, \"Hello.png\");\n * ```\n */\nexport function writeImage(image: Image, filename: string): void {\n  const png = new PNG({\n    width: image.width,\n    height: image.height,\n    colorType: 2, // RGB\n    bitDepth: 8,\n    inputColorType: 2,\n    inputHasAlpha: false,\n  });\n\n  // Copy RGB data from image to PNG\n  // PNG expects RGBA, so we need to add alpha channel\n  for (let y = 0; y < image.height; y++) {\n    for (let x = 0; x < image.width; x++) {\n      const srcOffset = (y * image.width + x) * 3;\n      const dstOffset = (y * image.width + x) * 4;\n\n      // Copy RGB from source\n      png.data[dstOffset] = image.colors[srcOffset]; // R\n      png.data[dstOffset + 1] = image.colors[srcOffset + 1]; // G\n      png.data[dstOffset + 2] = image.colors[srcOffset + 2]; // B\n      png.data[dstOffset + 3] = 255; // A (fully opaque)\n    }\n  }\n\n  // Write to file\n  const buffer = PNG.sync.write(png);\n  writeFileSync(filename, buffer);\n}\n\n/**\n * Generates a PNG buffer from a LifeHash image without writing to disk.\n *\n * @param image - The LifeHash image to encode\n * @returns A Buffer containing the PNG data\n * @category PNG Encoding\n *\n * @example\n * ```typescript\n * import { makeFromUtf8 } from \"@bcts/lifehash\";\n *\n * const image = makeFromUtf8(\"Hello\");\n * const pngBuffer = generatePNG(image);\n * ```\n */\nexport function generatePNG(image: Image): Buffer {\n  const png = new PNG({\n    width: image.width,\n    height: image.height,\n    colorType: 2,\n    bitDepth: 8,\n    inputColorType: 2,\n    inputHasAlpha: false,\n  });\n\n  // Copy RGB data from image to PNG\n  for (let y = 0; y < image.height; y++) {\n    for (let x = 0; x < image.width; x++) {\n      const srcOffset = (y * image.width + x) * 3;\n      const dstOffset = (y * image.width + x) * 4;\n\n      png.data[dstOffset] = image.colors[srcOffset];\n      png.data[dstOffset + 1] = image.colors[srcOffset + 1];\n      png.data[dstOffset + 2] = image.colors[srcOffset + 2];\n      png.data[dstOffset + 3] = 255;\n    }\n  }\n\n  return PNG.sync.write(png);\n}\n","/**\n * Utility functions for the LifeHash CLI.\n *\n * Ported from bc-lifehash-cli C++ implementation.\n *\n * @module\n */\n\n/**\n * Appends a path component to a path, handling trailing slashes correctly.\n *\n * Port of `appending_path_component()` from lifehash.cpp lines 18-24.\n *\n * @param path - The base path\n * @param component - The component to append\n * @returns The combined path\n * @category Utilities\n *\n * @example\n * ```typescript\n * appendingPathComponent(\"\", \"file.png\") // => \"file.png\"\n * appendingPathComponent(\"/tmp/\", \"file.png\") // => \"/tmp/file.png\"\n * appendingPathComponent(\"/tmp\", \"file.png\") // => \"/tmp/file.png\"\n * ```\n */\nexport function appendingPathComponent(path: string, component: string): string {\n  if (path === \"\") {\n    return component;\n  }\n  if (path.endsWith(\"/\")) {\n    return `${path}${component}`;\n  }\n  return `${path}/${component}`;\n}\n\n/**\n * Selects a random element from an array.\n *\n * Port of `random_element()` template from lifehash.cpp lines 38-50.\n *\n * @param array - The array to select from\n * @returns A random element from the array\n * @category Utilities\n *\n * @example\n * ```typescript\n * randomElement([\"A\", \"B\", \"C\"]) // => \"A\" or \"B\" or \"C\"\n * ```\n */\nexport function randomElement<T>(array: T[]): T {\n  const index = Math.floor(Math.random() * array.length);\n  return array[index];\n}\n\n/**\n * Generates a random input string in \"XXX-XXX\" format where X is a random uppercase letter.\n *\n * Port of `make_random_input()` from lifehash.cpp lines 52-57.\n *\n * @returns A random string in \"XXX-XXX\" format\n * @category Utilities\n *\n * @example\n * ```typescript\n * makeRandomInput() // => \"ABC-DEF\" (random letters)\n * ```\n */\nexport function makeRandomInput(): string {\n  const letters = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\".split(\"\");\n\n  const letter = (): string => randomElement(letters);\n  const cluster = (): string => `${letter()}${letter()}${letter()}`;\n\n  return `${cluster()}-${cluster()}`;\n}\n","/**\n * LifeHash CLI - Command line tool for generating LifeHash PNG images.\n *\n * Ported from bc-lifehash-cli C++ implementation (lifehash.cpp).\n *\n * @module\n */\n\nimport { Command } from \"commander\";\nimport { makeFromUtf8, Version } from \"@bcts/lifehash\";\nimport { writeImage } from \"./png-writer\";\nimport { appendingPathComponent, makeRandomInput } from \"./utils\";\n\n/**\n * CLI options interface.\n *\n * Port of Parameters struct from lifehash.cpp lines 86-91.\n *\n * @category CLI\n */\nexport interface CliOptions {\n  /** LifeHash version to generate */\n  version: string;\n  /** Size of each module (\"pixel\") */\n  module: string;\n  /** Output directory path */\n  path: string;\n}\n\n/**\n * Parses a version string to the Version enum.\n *\n * Port of version parsing logic from lifehash.cpp lines 130-145.\n *\n * @param versionString - The version string from CLI\n * @returns The corresponding Version enum value\n * @throws Error if the version string is invalid\n * @category CLI\n *\n * @example\n * ```typescript\n * parseVersion(\"version2\") // => Version.version2\n * parseVersion(\"detailed\") // => Version.detailed\n * parseVersion(\"invalid\") // throws Error\n * ```\n */\nexport function parseVersion(versionString: string): Version {\n  switch (versionString) {\n    case \"version1\":\n      return Version.version1;\n    case \"version2\":\n      return Version.version2;\n    case \"detailed\":\n      return Version.detailed;\n    case \"fiducial\":\n      return Version.fiducial;\n    case \"grayscaleFiducial\":\n      return Version.grayscale_fiducial;\n    default:\n      throw new Error(\"Invalid version.\");\n  }\n}\n\n/**\n * Main execution function that generates a LifeHash image.\n *\n * Port of `run()` from lifehash.cpp lines 188-192.\n *\n * @param input - Input string to hash (or empty for random)\n * @param options - CLI options\n * @category CLI\n *\n * @example\n * ```typescript\n * run(\"Hello\", { version: \"version2\", module: \"1\", path: \".\" });\n * // Generates Hello.png in current directory\n * ```\n */\nexport function run(input: string, options: CliOptions): void {\n  // Parse parameters (matching Parameters constructor from C++)\n  const version = parseVersion(options.version);\n  const moduleSize = parseInt(options.module, 10);\n\n  if (moduleSize < 1 || isNaN(moduleSize)) {\n    throw new Error(\"Illegal value.\");\n  }\n\n  // Use random input if none provided\n  const actualInput = input !== \"\" ? input : makeRandomInput();\n\n  // Generate output filename\n  const outputFilename = `${actualInput}.png`;\n  const outputFile = appendingPathComponent(options.path, outputFilename);\n\n  // Generate LifeHash image\n  const image = makeFromUtf8(actualInput, version, moduleSize);\n\n  // Write to PNG file\n  writeImage(image, outputFile);\n}\n\n/**\n * CLI entry point.\n *\n * Port of `main()` from lifehash.cpp lines 194-206.\n *\n * @category CLI\n */\nexport function main(): void {\n  const program = new Command();\n\n  program\n    .name(\"lifehash\")\n    .description(\"Generate LifeHash PNG images from input strings\")\n    .argument(\"[input]\", \"Input string to hash (default: random XXX-XXX)\")\n    .option(\n      \"-v, --version <version>\",\n      \"LifeHash version: version1, version2, detailed, fiducial, grayscaleFiducial\",\n      \"version2\",\n    )\n    .option(\"-m, --module <size>\", 'Size of each module (\"pixel\")', \"1\")\n    .option(\"-p, --path <path>\", \"Output directory path\", \"\")\n    .action((input: string | undefined, options: CliOptions) => {\n      try {\n        run(input ?? \"\", options);\n      } catch (error) {\n        if (error instanceof Error) {\n          console.log(`\\u{1F928} ${error.message}`);\n          console.log();\n          program.help();\n        }\n        process.exit(1);\n      }\n    });\n\n  program.parse();\n}\n\n// Run CLI when executed directly (not when imported as a module)\n// Check if this file is the main entry point\nconst isMainModule =\n  typeof process !== \"undefined\" &&\n  typeof process.argv[1] === \"string\" &&\n  (process.argv[1].endsWith(\"/main.mjs\") ||\n    process.argv[1].endsWith(\"/main.js\") ||\n    process.argv[1].includes(\"lifehash-cli\"));\n\nif (isMainModule) {\n  main();\n}\n","/**\n * @bcts/lifehash-cli - Command line tool for generating LifeHash PNG images.\n *\n * This package provides both a CLI tool and a programmatic API for generating\n * LifeHash visual hash images as PNG files.\n *\n * @packageDocumentation\n * @module @bcts/lifehash-cli\n *\n * @example CLI Usage\n * ```bash\n * # Generate a LifeHash from a string\n * lifehash Hello\n *\n * # Generate with specific version and module size\n * lifehash -v detailed -m 8 Hello\n *\n * # Generate with random input\n * lifehash\n * ```\n *\n * @example Programmatic Usage\n * ```typescript\n * import { generateLifeHash } from \"@bcts/lifehash-cli\";\n * import { writeFileSync } from \"fs\";\n *\n * // Generate a PNG buffer\n * const pngBuffer = generateLifeHash(\"Hello\", {\n *   version: \"version2\",\n *   moduleSize: 1,\n * });\n *\n * // Write to file\n * writeFileSync(\"Hello.png\", pngBuffer);\n * ```\n */\n\nimport { generatePNG, writeImage } from \"./png-writer\";\nimport { parseVersion, run, type CliOptions } from \"./main\";\nimport { makeFromUtf8, Version, type Image } from \"@bcts/lifehash\";\n\n// PNG encoding exports\nexport { writeImage, generatePNG };\n\n// Utility exports\nexport { appendingPathComponent, randomElement, makeRandomInput } from \"./utils\";\n\n// CLI exports\nexport { parseVersion, run, type CliOptions };\n\n// Re-export @bcts/lifehash types for convenience\nexport { Version, type Image };\n\n// Re-export makeFromUtf8 for programmatic usage\nexport { makeFromUtf8 };\n\n/**\n * Options for generating a LifeHash image.\n *\n * @category Image Generation\n */\nexport interface GenerateOptions {\n  /**\n   * LifeHash version to generate.\n   * @default \"version2\"\n   */\n  version?: \"version1\" | \"version2\" | \"detailed\" | \"fiducial\" | \"grayscaleFiducial\";\n  /**\n   * Size of each module (\"pixel\").\n   * @default 1\n   */\n  moduleSize?: number;\n}\n\n/**\n * Generates a LifeHash PNG buffer from an input string.\n *\n * This is the main programmatic API for generating LifeHash images.\n *\n * @param input - The input string to hash\n * @param options - Generation options\n * @returns A Buffer containing the PNG data\n * @category Image Generation\n *\n * @example\n * ```typescript\n * import { generateLifeHash } from \"@bcts/lifehash-cli\";\n * import { writeFileSync } from \"fs\";\n *\n * const pngBuffer = generateLifeHash(\"Hello\", {\n *   version: \"version2\",\n *   moduleSize: 1,\n * });\n *\n * writeFileSync(\"Hello.png\", pngBuffer);\n * ```\n */\nexport function generateLifeHash(input: string, options: GenerateOptions = {}): Buffer {\n  const { version = \"version2\", moduleSize = 1 } = options;\n\n  const versionEnum = parseVersion(version);\n  const image = makeFromUtf8(input, versionEnum, moduleSize);\n  return generatePNG(image);\n}\n"],"mappings":"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"}