@bcts/lifehash-cli 1.0.0-alpha.17

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["Version","makeFromUtf8"],"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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"}

package/dist/main.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { Version, makeFromUtf8 } from "@bcts/lifehash";
+import { writeFileSync } from "fs";
+import { PNG } from "pngjs";
+
+//#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 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;
+	}
+	writeFileSync(filename, 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 Version.version1;
+		case "version2": return Version.version2;
+		case "detailed": return Version.detailed;
+		case "fiducial": return Version.fiducial;
+		case "grayscaleFiducial": return 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(makeFromUtf8(actualInput, version, moduleSize), outputFile);
+}
+/**
+* CLI entry point.
+*
+* Port of `main()` from lifehash.cpp lines 194-206.
+*
+* @category CLI
+*/
+function main() {
+	const program = new 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
+export { main, parseVersion, run };
+//# sourceMappingURL=main.mjs.map

package/dist/main.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.mjs","names":[],"sources":["../src/png-writer.ts","../src/utils.ts","../src/main.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"],"mappings":"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"}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@bcts/lifehash-cli",
+  "version": "1.0.0-alpha.17",
+  "type": "module",
+  "description": "A command-line tool for generating LifeHash visual hash images as PNG files.",
+  "license": "BSD-2-Clause-Patent",
+  "contributors": [
+    {
+      "name": "Leonardo Custodio",
+      "email": "leonardo.custodio@parity.io",
+      "url": "https://github.com/leonardocustodio"
+    },
+    {
+      "name": "Karim Jedda",
+      "email": "karim@parity.io",
+      "url": "https://github.com/KarimJedda"
+    }
+  ],
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardocustodio/bcts.git",
+    "directory": "tools/lifehash-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/leonardocustodio/bcts/issues"
+  },
+  "bin": {
+    "lifehash": "./dist/main.mjs"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "lifehash",
+    "visual-hash",
+    "hash-visualization",
+    "png",
+    "image",
+    "cli",
+    "blockchain-commons",
+    "game-of-life",
+    "cellular-automata",
+    "fiducial"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bcts/lifehash": "workspace:*",
+    "commander": "^14.0.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "workspace:*",
+    "@bcts/tsconfig": "workspace:*",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.10",
+    "@types/pngjs": "^6.0.5",
+    "eslint": "^9.39.2",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.20.1",
+    "typedoc": "^0.28.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * @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);
+ * ```
+ */
+
+import { generatePNG, writeImage } from "./png-writer";
+import { parseVersion, run, type CliOptions } from "./main";
+import { makeFromUtf8, Version, type Image } from "@bcts/lifehash";
+
+// PNG encoding exports
+export { writeImage, generatePNG };
+
+// Utility exports
+export { appendingPathComponent, randomElement, makeRandomInput } from "./utils";
+
+// CLI exports
+export { parseVersion, run, type CliOptions };
+
+// Re-export @bcts/lifehash types for convenience
+export { Version, type Image };
+
+// Re-export makeFromUtf8 for programmatic usage
+export { makeFromUtf8 };
+
+/**
+ * Options for generating a LifeHash image.
+ *
+ * @category Image Generation
+ */
+export interface GenerateOptions {
+  /**
+   * LifeHash version to generate.
+   * @default "version2"
+   */
+  version?: "version1" | "version2" | "detailed" | "fiducial" | "grayscaleFiducial";
+  /**
+   * Size of each module ("pixel").
+   * @default 1
+   */
+  moduleSize?: number;
+}
+
+/**
+ * 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);
+ * ```
+ */
+export function generateLifeHash(input: string, options: GenerateOptions = {}): Buffer {
+  const { version = "version2", moduleSize = 1 } = options;
+
+  const versionEnum = parseVersion(version);
+  const image = makeFromUtf8(input, versionEnum, moduleSize);
+  return generatePNG(image);
+}

package/src/main.ts

@@ -0,0 +1,150 @@
+/**
+ * LifeHash CLI - Command line tool for generating LifeHash PNG images.
+ *
+ * Ported from bc-lifehash-cli C++ implementation (lifehash.cpp).
+ *
+ * @module
+ */
+
+import { Command } from "commander";
+import { makeFromUtf8, Version } from "@bcts/lifehash";
+import { writeImage } from "./png-writer";
+import { appendingPathComponent, makeRandomInput } from "./utils";
+
+/**
+ * CLI options interface.
+ *
+ * Port of Parameters struct from lifehash.cpp lines 86-91.
+ *
+ * @category CLI
+ */
+export interface CliOptions {
+  /** LifeHash version to generate */
+  version: string;
+  /** Size of each module ("pixel") */
+  module: string;
+  /** Output directory path */
+  path: string;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function parseVersion(versionString: string): Version {
+  switch (versionString) {
+    case "version1":
+      return Version.version1;
+    case "version2":
+      return Version.version2;
+    case "detailed":
+      return Version.detailed;
+    case "fiducial":
+      return Version.fiducial;
+    case "grayscaleFiducial":
+      return 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
+ * ```
+ */
+export function run(input: string, options: CliOptions): void {
+  // Parse parameters (matching Parameters constructor from C++)
+  const version = parseVersion(options.version);
+  const moduleSize = parseInt(options.module, 10);
+
+  if (moduleSize < 1 || isNaN(moduleSize)) {
+    throw new Error("Illegal value.");
+  }
+
+  // Use random input if none provided
+  const actualInput = input !== "" ? input : makeRandomInput();
+
+  // Generate output filename
+  const outputFilename = `${actualInput}.png`;
+  const outputFile = appendingPathComponent(options.path, outputFilename);
+
+  // Generate LifeHash image
+  const image = makeFromUtf8(actualInput, version, moduleSize);
+
+  // Write to PNG file
+  writeImage(image, outputFile);
+}
+
+/**
+ * CLI entry point.
+ *
+ * Port of `main()` from lifehash.cpp lines 194-206.
+ *
+ * @category CLI
+ */
+export function main(): void {
+  const program = new 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: string | undefined, options: CliOptions) => {
+      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();
+}
+
+// Run CLI when executed directly (not when imported as a module)
+// Check if this file is the main entry point
+const isMainModule =
+  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"));
+
+if (isMainModule) {
+  main();
+}