Release 2.0.4 with versioned CLI summary output.

Show version on every run, add --version, and print aligned human-readable stats.

Author: chasoft

README.md

@@ -67,6 +67,9 @@ text-compress ./large-file.txt -s 4000
 # Inline text
 text-compress -t "hello world" -o output.txt
 
+# Show version
+text-compress --version
+
 # Force mode when auto-detect is wrong
 text-compress --compress ./looks-compressed.txt
 text-compress --decompress ./plain.md   # errors if not valid payload
@@ -184,6 +187,12 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/LEARNING.md](docs/LEA
 
 ## Changelog
 
+### v2.0.4 — `text-compress` (2026-07-09)
+
+- Show package version on every run (`text-compress v2.0.4`)
+- Add `-V` / `--version` flag
+- Improve CLI summary: aligned stats, human-readable sizes, clearer split output
+
 ### v2.0.3 — `text-compress` (2026-07-09)
 
 - Use printable ASCII `;TCP2;` split headers so part files stay copyable in text editors (legacy binary `TCP\x02` headers still accepted on read)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "text-compress",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Brotli-compress text or folders to base64/base85 strings for easy sharing",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -1,14 +1,62 @@
 /**
  * @module cli/analytics
  *
- * Post-run statistics printed to stdout after each CLI command.
+ * Post-run summary printed to stdout after each CLI command.
  */
 
-/** Print a key/value analytics block below the main status line. */
-export function printAnalytics(stats: Record<string, string | number>) {
-  console.log("\n--- Analytics ---")
-  for (const [key, value] of Object.entries(stats)) {
-    console.log(`${key}: ${value}`)
+import { getVersion } from "./version.js"
+
+/** Print package version and exit (for `-V` / `--version`). */
+export function printVersion(): void {
+  console.log(`text-compress v${getVersion()}`)
+}
+
+/** Format a byte count for human-readable CLI output. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const units = ["KB", "MB", "GB", "TB"] as const
+  let value = bytes / 1024
+  for (const unit of units) {
+    if (value < 1024) {
+      const digits = value < 10 ? 1 : 0
+      return `${value.toFixed(digits)} ${unit}`
+    }
+    value /= 1024
+  }
+  return `${value.toFixed(1)} TB`
+}
+
+/** Format integers with thousands separators. */
+export function formatCount(value: number): string {
+  return value.toLocaleString("en-US")
+}
+
+export interface RunSummary {
+  title: string
+  outputPaths: string[]
+  stats: Record<string, string | number>
+}
+
+/** Print a versioned, aligned summary block after a successful run. */
+export function printRunSummary(summary: RunSummary): void {
+  console.log(`text-compress v${getVersion()}`)
+  console.log()
+  console.log(summary.title)
+
+  if (summary.outputPaths.length > 1) {
+    for (const path of summary.outputPaths) {
+      console.log(`  ${path}`)
+    }
+  } else if (summary.outputPaths.length === 1) {
+    console.log(`  ${summary.outputPaths[0]}`)
+  }
+
+  if (Object.keys(summary.stats).length === 0) return
+
+  console.log()
+  const width = Math.max(...Object.keys(summary.stats).map((key) => key.length))
+  for (const [key, value] of Object.entries(summary.stats)) {
+    console.log(`  ${key.padEnd(width)}  ${value}`)
   }
 }
 
@@ -19,7 +67,7 @@ export function splitAnalytics(
 ): Record<string, string | number> {
   if (splitChunkSize === undefined) return {}
   return {
-    "Split size (chars)": splitChunkSize,
-    "Output parts": outputParts,
+    "Split limit": `${formatCount(splitChunkSize)} chars / part`,
+    Parts: outputParts,
   }
 }

src/cli/analytics.ts

@@ -7,7 +7,7 @@
 import { compress } from "../../api/text.js"
 import { assertDirectory } from "../../fs/paths.js"
 import { compressFolderToPath } from "../../streaming/folder.js"
-import { printAnalytics, splitAnalytics } from "../analytics.js"
+import { formatBytes, formatCount, printRunSummary, splitAnalytics } from "../analytics.js"
 import { type Args, readInput, resolveEncoding } from "../args.js"
 import { writeCompressedOutput } from "../output.js"
 import { resolveOutputPath } from "../paths.js"
@@ -32,22 +32,23 @@ export async function runCompress(args: Args): Promise<void> {
     const elapsedMs = Number(process.hrtime.bigint() - start) / 1e6
     const ratio = originalBytes === 0 ? 0 : compressedBytes / originalBytes
 
-    console.log(
-      outputPaths.length === 1
-        ? `Compressed folder written to ${outputPaths[0]}`
-        : `Compressed folder written to ${outputPaths.length} files:\n  ${outputPaths.join("\n  ")}`,
-    )
-    printAnalytics({
-      Encoding: `base${encoding}`,
-      Files: fileCount,
-      Directories: dirCount,
-      "Original size (bytes)": originalBytes,
-      "Archive size before compression (bytes)": archiveBytes,
-      [`Compressed size (bytes, base${encoding})`]: compressedBytes,
-      ...splitAnalytics(splitChunkSize, outputPaths.length),
-      "Size ratio (compressed/original)": ratio.toFixed(3),
-      "Space saved": `${((1 - ratio) * 100).toFixed(1)}%`,
-      "Time taken (ms)": elapsedMs.toFixed(3),
+    printRunSummary({
+      title:
+        outputPaths.length === 1
+          ? "Compressed folder"
+          : `Compressed folder → ${outputPaths.length} files`,
+      outputPaths,
+      stats: {
+        Encoding: `base${encoding}`,
+        Files: formatCount(fileCount),
+        Directories: formatCount(dirCount),
+        "Original size": formatBytes(originalBytes),
+        "Archive (pre-Brotli)": formatBytes(archiveBytes),
+        [`Compressed (base${encoding})`]: formatBytes(compressedBytes),
+        ...splitAnalytics(splitChunkSize, outputPaths.length),
+        "Space saved": `${((1 - ratio) * 100).toFixed(1)}%`,
+        Time: `${elapsedMs.toFixed(0)} ms`,
+      },
     })
     return
   }
@@ -68,18 +69,20 @@ export async function runCompress(args: Args): Promise<void> {
   const outputBytes = Buffer.byteLength(result, "utf-8")
   const ratio = inputBytes === 0 ? 0 : outputBytes / inputBytes
 
-  console.log(
-    outputPaths.length === 1
-      ? `Compressed output written to ${outputPath}`
-      : `Compressed output written to ${outputPaths.length} files:\n  ${outputPaths.join("\n  ")}`,
-  )
-  printAnalytics({
-    Encoding: `base${encoding}`,
-    "Original size (bytes)": inputBytes,
-    [`Compressed size (bytes, base${encoding})`]: outputBytes,
-    ...splitAnalytics(splitChunkSize, outputPaths.length),
-    "Size ratio (compressed/original)": ratio.toFixed(3),
-    "Space saved": `${((1 - ratio) * 100).toFixed(1)}%`,
-    "Time taken (ms)": elapsedMs.toFixed(3),
+  printRunSummary({
+    title:
+      outputPaths.length === 1
+        ? "Compressed text"
+        : `Compressed text → ${outputPaths.length} files`,
+    outputPaths,
+    stats: {
+      Encoding: `base${encoding}`,
+      "Original size": formatBytes(inputBytes),
+      [`Compressed (base${encoding})`]: formatBytes(outputBytes),
+      ...splitAnalytics(splitChunkSize, outputPaths.length),
+      "Size ratio": ratio.toFixed(3),
+      "Space saved": `${((1 - ratio) * 100).toFixed(1)}%`,
+      Time: `${elapsedMs.toFixed(0)} ms`,
+    },
   })
 }

src/cli/commands/compress.ts

@@ -8,7 +8,7 @@ import { writeFileSync } from "node:fs"
 import { unpackDirectory } from "../../archive/unpack.js"
 import { decompressPayload, TAG_FOLDER, TAG_TEXT } from "../../payload/tags.js"
 import { readSplitInput } from "../../split/parts.js"
-import { printAnalytics } from "../analytics.js"
+import { formatBytes, formatCount, printRunSummary } from "../analytics.js"
 import { type Args, readInput, resolveEncoding, resolveEncodingOptional } from "../args.js"
 import { resolveDetectedEncoding } from "../detect.js"
 import { resolveOutputPath } from "../paths.js"
@@ -47,15 +47,18 @@ export function runDecompress(args: Args): void {
     const outputPath = resolveOutputPath(args, "decompressed.de", ".de")
     const { files, dirs, bytes } = unpackDirectory(data, outputPath)
 
-    console.log(`Decompressed folder recreated at ${outputPath}`)
-    printAnalytics({
-      Encoding: `base${encoding}`,
-      [`Compressed size (bytes, base${encoding})`]: inputBytes,
-      ...(partPaths ? { "Input parts": partPaths.length } : {}),
-      "Files restored": files,
-      "Directories restored": dirs,
-      "Decompressed size (bytes)": bytes,
-      "Time taken (ms)": elapsedMs.toFixed(3),
+    printRunSummary({
+      title: "Decompressed folder",
+      outputPaths: [outputPath],
+      stats: {
+        Encoding: `base${encoding}`,
+        [`Compressed (base${encoding})`]: formatBytes(inputBytes),
+        ...(partPaths ? { "Input parts": partPaths.length } : {}),
+        "Files restored": formatCount(files),
+        "Directories restored": formatCount(dirs),
+        "Restored size": formatBytes(bytes),
+        Time: `${elapsedMs.toFixed(0)} ms`,
+      },
     })
     return
   }
@@ -70,13 +73,16 @@ export function runDecompress(args: Args): void {
   const outputBytes = Buffer.byteLength(result, "utf-8")
   const ratio = inputBytes === 0 ? 0 : outputBytes / inputBytes
 
-  console.log(`Decompressed output written to ${outputPath}`)
-  printAnalytics({
-    Encoding: `base${encoding}`,
-    [`Compressed size (bytes, base${encoding})`]: inputBytes,
-    ...(partPaths ? { "Input parts": partPaths.length } : {}),
-    "Decompressed size (bytes)": outputBytes,
-    "Expansion ratio (decompressed/compressed)": ratio.toFixed(3),
-    "Time taken (ms)": elapsedMs.toFixed(3),
+  printRunSummary({
+    title: "Decompressed text",
+    outputPaths: [outputPath],
+    stats: {
+      Encoding: `base${encoding}`,
+      [`Compressed (base${encoding})`]: formatBytes(inputBytes),
+      ...(partPaths ? { "Input parts": partPaths.length } : {}),
+      "Restored size": formatBytes(outputBytes),
+      "Expansion ratio": ratio.toFixed(3),
+      Time: `${elapsedMs.toFixed(0)} ms`,
+    },
   })
 }

src/cli/commands/decompress.ts

@@ -5,6 +5,7 @@
  */
 
 import { readSplitInput } from "../split/parts.js"
+import { printVersion } from "./analytics.js"
 import { type Args, parseArgs, resolveEncodingOptional, resolveInputArgs } from "./args.js"
 import { runCompress } from "./commands/compress.js"
 import { runDecompress } from "./commands/decompress.js"
@@ -15,6 +16,10 @@ function wantsHelp(argv: string[]): boolean {
   return argv.length === 0 || argv.includes("-h") || argv.includes("--help")
 }
 
+function wantsVersion(argv: string[]): boolean {
+  return argv.includes("-V") || argv.includes("--version")
+}
+
 /** Strip an optional legacy leading compress/decompress command. */
 function normalizeArgv(argv: string[]): { argv: string[]; forcedMode?: Args["mode"] } {
   const [first, ...rest] = argv
@@ -52,6 +57,11 @@ export function main() {
     process.exit(argv.length === 0 ? 1 : 0)
   }
 
+  if (wantsVersion(argv)) {
+    printVersion()
+    process.exit(0)
+  }
+
   const legacy = normalizeArgv(argv)
   argv = legacy.argv
   const args = parseArgs(argv)

src/cli/main.ts

@@ -40,6 +40,7 @@ Options:
                                  preserves text verbatim (e.g. a code block)
   -p, --password <string>  Password-protect on compress, or unlock on decompress
   -h, --help               Show this usage guide
+  -V, --version            Show package version
 
 Split output (decompress):
   Pass any one sibling file. All files sharing the same basename prefix

src/cli/usage.ts

@@ -0,0 +1,20 @@
+/**
+ * @module cli/version
+ *
+ * Package version read from package.json at runtime.
+ */
+
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+let cachedVersion: string | undefined
+
+/** Return the published `text-compress` version string. */
+export function getVersion(): string {
+  if (cachedVersion) return cachedVersion
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..")
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8")) as { version: string }
+  cachedVersion = pkg.version
+  return cachedVersion
+}