xzipit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),  
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] – Initial development
+
+### Added
+
+- CLI tool `xzipit` for creating ZIP archives
+- Support for packing:
+  - current directory (default)
+  - custom source directory via `--src`
+- Output archive naming:
+  - automatic name from source directory
+  - custom name via `--out`
+  - optional version suffix via `--version`
+  - timestamp suffix when file already exists
+- `.zipignore` support with `.gitignore`-compatible syntax
+- Interactive conflict resolution when output ZIP already exists:
+  - overwrite
+  - cancel
+  - add timestamp suffix
+- CI-friendly mode with `--yes` (no interactive prompts)
+- Compression options:
+  - compression level (`--level`, 0–9)
+  - compression algorithm (`deflate`, `store`)
+- Bounded concurrency for file streaming via `--concurrency`
+  - prevents `EMFILE: too many open files`
+- Live progress UI:
+  - list of archived files
+  - per-file progress
+  - total archive progress
+  - ETA and compression speed
+- Cross-platform support (Linux, macOS, Windows)
+
+### Internal
+
+- Modular architecture (`lib/` + thin CLI)
+- Sequential / bounded-parallel streaming to avoid file descriptor exhaustion
+- Unit tests for core logic:
+  - archive naming
+  - `.zipignore` handling
+  - ZIP creation correctness
+
+---
+
+[0.1.0]: https://github.com/yourname/xzipit

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Ivaskiv
+
+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

@@ -0,0 +1,123 @@
+# xzipit 🎤📦
+
+![npm](https://img.shields.io/npm/v/xzipit)
+![node](https://img.shields.io/node/v/xzipit)
+![license](https://img.shields.io/npm/l/xzipit)
+![tests](https://github.com/romaniv1024/xzipit/actions/workflows/test.yml/badge.svg)
+
+**xzipit** is a fast and flexible Node.js CLI tool for archiving projects into ZIP files.
+It supports `.zipignore` (gitignore-style rules), live progress display, CI-friendly mode,
+and safe concurrent file streaming.
+
+> The name is partially inspired by a famous American rapper 😄
+
+---
+
+## ✨ Features
+
+- 📦 Zip folders into ZIP archives
+- 🧾 `.zipignore` support (same syntax as `.gitignore`)
+- 📊 Live progress:
+  - overall archive progress
+  - current file progress
+  - ETA and speed
+- 🧠 Smart defaults if options are omitted
+- 🧩 Interactive handling when output ZIP already exists
+- ⚙️ Control over:
+  - compression level
+  - compression algorithm (`deflate` / `store`)
+  - concurrency (prevents `EMFILE`)
+
+---
+
+## 📥 Installation
+
+```bash
+npm install -g xzipit
+```
+
+or locally:
+
+```bash
+npm install xzipit
+```
+
+---
+
+## 🚀 Usage
+
+```bash
+xzipit [options]
+```
+
+### Examples
+
+```bash
+# Pack current directory
+xzipit
+
+# Pack a specific folder
+xzipit --src ./project
+
+# Add version suffix
+xzipit --src ./project --version 1.2.3
+# => project-1.2.3.zip
+
+# Custom output name
+xzipit --src ./project --out my-archive
+
+# No compression
+xzipit --algo store
+
+# Faster packing (bounded concurrency)
+xzipit --concurrency 8
+
+# CI mode: overwrite without prompt
+xzipit --yes
+```
+
+---
+
+## ⚙️ Options
+
+| Option | Description | Default |
+|------|------------|---------|
+| `-s, --src <dir>` | Source directory | current directory |
+| `-o, --out <name>` | Output ZIP name (without `.zip`) | source folder name |
+| `-v, --version <ver>` | Version suffix (`-1.2.3`) | — |
+| `-l, --level <0-9>` | Compression level | `9` |
+| `-a, --algo <type>` | `deflate` or `store` | `deflate` |
+| `-c, --concurrency <n>` | Number of files processed in parallel | `1` |
+| `-y, --yes` | CI mode: overwrite existing zip without prompt | — |
+| `-h, --help` | Show help | — |
+
+### Concurrency recommendations
+
+`--concurrency` controls how many files are streamed in parallel.
+
+- `1` — safest (lowest RAM/FD usage, avoids `EMFILE`)
+- `4–8` — usually optimal on most machines
+- `16+` — may hit OS file descriptor limits (`EMFILE`) on some systems and can reduce I/O efficiency
+
+---
+
+## 📄 .zipignore
+
+If a `.zipignore` file exists in the source directory, it will be used to exclude files  
+using the same syntax as `.gitignore`.
+
+### Example
+
+```gitignore
+node_modules/
+dist/
+.env
+*.log
+**/*.tmp
+```
+
+---
+
+## 📜 License
+
+MIT

package/README.uk.md

@@ -0,0 +1,87 @@
+# xzipit 🎤📦 (Українська версія)
+
+![npm](https://img.shields.io/npm/v/xzipit)
+![node](https://img.shields.io/node/v/xzipit)
+![license](https://img.shields.io/npm/l/xzipit)
+![tests](https://github.com/romaniv1024/xzipit/actions/workflows/test.yml/badge.svg)
+
+Це українська версія документації.  
+Основна (англійська) версія знаходиться у `README.md`.
+
+**xzipit** — це швидкий і гнучкий інструмент Node.js CLI для архівування проектів у ZIP-файли.
+Він підтримує `.zipignore` (правила у стилі gitignore), відображення прогресу в режимі реального часу, режим, сумісний із CI,
+та безпечну одночасну передачу файлів.
+
+---
+
+## ✨ Можливості
+
+- 📦 Архівування папок у ZIP
+- 🧾 Підтримка `.zipignore` (синтаксис як `.gitignore`)
+- 📊 Live-прогрес:
+  - загальний прогрес архіву
+  - прогрес поточного файлу
+  - ETA та швидкість
+- 🧠 Розумні дефолти
+- 🧩 Інтерактивна обробка конфліктів імен
+- ⚙️ Контроль рівня стиснення, алгоритму та паралельності
+
+---
+
+## 📥 Встановлення
+
+```bash
+npm install -g xzipit
+```
+
+або локально:
+
+```bash
+npm install xzipit
+```
+
+---
+
+## 🚀 Використання
+
+```bash
+xzipit [options]
+```
+
+### Приклади
+
+```bash
+xzipit
+xzipit --src ./project
+xzipit --version 1.2.3
+xzipit --algo store
+xzipit --concurrency 8
+xzipit --yes
+```
+
+---
+
+## ⚙️ Опції
+
+| Опція | Опис | За замовчуванням |
+|-----|------|------------------|
+| `-s, --src <dir>` | Папка для архівування | поточна |
+| `-o, --out <name>` | Назва ZIP | назва папки |
+| `-v, --version <ver>` | Версія | — |
+| `-l, --level <0-9>` | Рівень стиснення | `9` |
+| `-a, --algo <type>` | `deflate` або `store` | `deflate` |
+| `-c, --concurrency <n>` | Паралельність | `1` |
+| `-y, --yes` | CI-режим (без запитань) | — |
+| `-h, --help` | Довідка | — |
+
+---
+
+## 📄 .zipignore
+
+Файл `.zipignore` дозволяє виключати файли за синтаксисом `.gitignore`.
+
+---
+
+## 📜 Ліцензія
+
+MIT

package/bin/xzipit.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import logUpdate from "log-update";
+import chalk from "chalk";
+
+import {
+	buildZipName,
+	createIgnoreMatcher,
+	listFiles,
+	createZip,
+	formatBytes,
+	formatTime
+} from "../lib/index.js";
+
+function bar(pct, width = 36) {
+	const p = Math.max(0, Math.min(1, pct));
+	const filled = Math.round(p * width);
+	return "█".repeat(filled) + "░".repeat(Math.max(0, width - filled));
+}
+
+async function fileExists(p) {
+	try {
+		await fsp.access(p, fs.constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const program = new Command();
+
+program
+	.name("xzipit")
+	.usage("[options]")
+	.description("Pack a folder into a ZIP archive with .zipignore support and live progress UI")
+	.option("-s, --src <dir>", "Source folder to pack (default: current folder)")
+	.option("-o, --out <name>", "Output zip base name without .zip (default: source folder name)")
+	.option("-v, --version <ver>", "Version to append to archive name (e.g. -1.2.3)")
+	.option("-l, --level <0-9>", "Compression level (0..9, default: 9)", "9")
+	.option("-a, --algo <deflate|store>", "Compression algorithm: deflate (default) or store", "deflate")
+	.option(
+		"-c, --concurrency <n>",
+		"Number of files processed in parallel (default: 1). Recommended: 1 safest; 4-8 usually optimal; 16+ may hit OS file descriptor limits (EMFILE).",
+		"1"
+	)
+	.option("-y, --yes", "CI mode: overwrite existing zip without prompt", false)
+	.helpOption("-h, --help", "Display help for command")
+	.addHelpText(
+		"after",
+		`
+Examples:
+  xzipit
+  xzipit --src ./project
+  xzipit --src ./project --version 1.2.3
+  xzipit --out my-archive --algo store
+  xzipit --concurrency 8
+  xzipit --yes
+`
+	);
+
+program.parse(process.argv);
+const opts = program.opts();
+
+async function main() {
+	const srcDir = path.resolve(opts.src ?? ".");
+	const srcBase = path.basename(srcDir);
+	const baseName = (opts.out ?? srcBase).replace(/\.zip$/i, "");
+	const version = opts.version ? String(opts.version) : "";
+
+	const algo = String(opts.algo || "deflate").toLowerCase() === "store" ? "store" : "deflate";
+	let level = Number(opts.level ?? 9);
+	if (!Number.isFinite(level) || level < 0 || level > 9) level = 9;
+
+	let concurrency = Number(opts.concurrency ?? 1);
+	if (!Number.isFinite(concurrency) || concurrency < 1) concurrency = 1;
+
+	const yes = Boolean(opts.yes);
+
+	const ig = await createIgnoreMatcher(srcDir);
+	const relFiles = await listFiles({ srcDir, ig });
+
+	if (relFiles.length === 0) {
+		console.error("No files to archive (after applying .zipignore).");
+		process.exit(1);
+	}
+
+	// output name
+	let outZip = path.resolve(buildZipName(baseName, version, ""));
+
+	if (await fileExists(outZip)) {
+		if (!yes) {
+			const { action } = await inquirer.prompt([
+				{
+					type: "list",
+					name: "action",
+					message: `ZIP file already exists:\n${outZip}\nChoose an action:`,
+					choices: [
+						{ name: "Overwrite (Y)", value: "Y" },
+						{ name: "Cancel (N)", value: "N" },
+						{ name: "Add timestamp suffix (M)", value: "M" }
+					],
+					default: 1
+				}
+			]);
+
+			if (action === "N") process.exit(0);
+			if (action === "M") {
+				outZip = path.resolve(buildZipName(baseName, version, Date.now()));
+			}
+		}
+		// yes=true => overwrite silently
+	}
+
+	// progress UI state
+	const doneList = [];
+	const doneListMax = 12;
+
+	let totalBytes = 0;
+	let processedBytes = 0;
+
+	let currentRel = null;
+	let currentRead = 0;
+	let currentSize = 0;
+
+	let speedBytesPerSec = 0;
+	let etaMs = Infinity;
+
+	const render = () => {
+		const overallPct = totalBytes > 0 ? processedBytes / totalBytes : 0;
+		const filePct = currentSize > 0 ? currentRead / currentSize : 0;
+
+		const lines = [];
+		lines.push(chalk.dim("Archived files:"));
+		if (doneList.length === 0) lines.push(chalk.dim("  (none yet)"));
+		for (const f of doneList.slice(-doneListMax)) lines.push(chalk.dim("  ✓ ") + f);
+
+		lines.push("");
+		lines.push(
+			chalk.bold("Current file: ") +
+			(currentRel
+				? `${currentRel} (${formatBytes(currentRead)} / ${formatBytes(currentSize)})`
+				: "—")
+		);
+		lines.push(`${bar(filePct)}  ${(filePct * 100).toFixed(1)}%`);
+
+		lines.push("");
+		lines.push(chalk.bold("Total progress: ") + `${formatBytes(processedBytes)} / ${formatBytes(totalBytes)}`);
+		lines.push(
+			`${bar(overallPct)}  ${(overallPct * 100).toFixed(1)}%   ` +
+			chalk.dim(`ETA: ${formatTime(etaMs)} | Speed: ${formatBytes(speedBytesPerSec)}/s`)
+		);
+
+		logUpdate(lines.join("\n"));
+	};
+
+	const timer = setInterval(render, 80);
+
+	const result = await createZip({
+		srcDir,
+		outZip,
+		algo,
+		level,
+		concurrency,
+		relFiles,
+		onOverallProgress: (e) => {
+			totalBytes = e.totalBytes;
+			processedBytes = e.processedBytes;
+			speedBytesPerSec = e.speedBytesPerSec;
+			etaMs = e.etaMs;
+		},
+		onFileProgress: (e) => {
+			currentRel = e.rel;
+			currentRead = e.currentRead;
+			currentSize = e.size;
+		},
+		onFileDone: (e) => {
+			doneList.push(e.rel);
+			if (doneList.length > doneListMax * 3) doneList.splice(0, doneList.length - doneListMax * 3);
+		}
+	});
+
+	clearInterval(timer);
+	render();
+	logUpdate.done();
+
+	console.log(`\nDone: ${outZip}`);
+	console.log(`Files: ${result.fileCount}, Total: ${formatBytes(result.totalBytes)}`);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/lib/files.js

@@ -0,0 +1,19 @@
+import fg from "fast-glob";
+import path from "path";
+
+export function normalizeToPosix(p) {
+	return p.split(path.sep).join("/");
+}
+
+export async function listFiles({ srcDir, ig }) {
+	const all = await fg(["**/*"], {
+		cwd: srcDir,
+		dot: true,
+		onlyFiles: true,
+		followSymbolicLinks: false
+	});
+
+	if (!ig) return all;
+
+	return all.filter((rel) => !ig.ignores(normalizeToPosix(rel)));
+}

package/lib/ignore.js

@@ -0,0 +1,19 @@
+import fsp from "fs/promises";
+import path from "path";
+import ignore from "ignore";
+
+export async function readZipIgnoreFile(srcDir) {
+	const p = path.join(srcDir, ".zipignore");
+	try {
+		return await fsp.readFile(p, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+export async function createIgnoreMatcher(srcDir) {
+	const igText = await readZipIgnoreFile(srcDir);
+	const ig = ignore();
+	if (igText.trim()) ig.add(igText);
+	return ig;
+}

package/lib/index.js

@@ -0,0 +1,5 @@
+export { buildZipName } from "./naming.js";
+export { createIgnoreMatcher, readZipIgnoreFile } from "./ignore.js";
+export { listFiles, normalizeToPosix } from "./files.js";
+export { createZip } from "./zip.js";
+export { formatBytes, formatTime } from "./progress.js";

package/lib/naming.js

@@ -0,0 +1,6 @@
+export function buildZipName(baseName, version = "", msSuffix = "") {
+	let name = baseName;
+	if (version) name += `-${version}`;
+	if (msSuffix) name += `_${msSuffix}`;
+	return `${name}.zip`;
+}

package/lib/progress.js

@@ -0,0 +1,18 @@
+export function formatBytes(bytes) {
+	const units = ["B", "KB", "MB", "GB", "TB"];
+	let i = 0;
+	let n = bytes;
+	while (n >= 1024 && i < units.length - 1) {
+		n /= 1024;
+		i++;
+	}
+	return `${n.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+export function formatTime(ms) {
+	if (!isFinite(ms) || ms < 0) return "—";
+	const s = Math.ceil(ms / 1000);
+	const m = Math.floor(s / 60);
+	const r = s % 60;
+	return m > 0 ? `${m}m ${r}s` : `${r}s`;
+}

package/lib/zip.js

@@ -0,0 +1,153 @@
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import archiver from "archiver";
+import { normalizeToPosix } from "./files.js";
+
+/**
+ * @typedef {Object} ZipFileMeta
+ * @property {string} rel
+ * @property {string} abs
+ * @property {number} size
+ * @property {Date} mtime
+ */
+
+async function statFiles(srcDir, relFiles) {
+	/** @type {ZipFileMeta[]} */
+	const metas = [];
+	let total = 0;
+
+	for (const rel of relFiles) {
+		const abs = path.join(srcDir, rel);
+		const st = await fsp.stat(abs);
+		if (!st.isFile()) continue;
+		total += st.size;
+		metas.push({ rel, abs, size: st.size, mtime: st.mtime });
+	}
+
+	return { metas, totalBytes: total };
+}
+
+function clampInt(n, min, max, fallback) {
+	const v = Number(n);
+	if (!Number.isFinite(v)) return fallback;
+	const i = Math.trunc(v);
+	return Math.max(min, Math.min(max, i));
+}
+
+/**
+ * Create ZIP archive with bounded concurrency (prevents EMFILE).
+ *
+ * @param {Object} params
+ * @param {string} params.srcDir
+ * @param {string} params.outZip
+ * @param {"deflate"|"store"} params.algo
+ * @param {number} params.level
+ * @param {number} [params.concurrency] number of files streamed in parallel (default: 1)
+ * @param {string[]} params.relFiles
+ * @param {(e: {type:"overall", processedBytes:number, totalBytes:number, speedBytesPerSec:number, etaMs:number})=>void} [params.onOverallProgress]
+ * @param {(e: {type:"file", rel:string, currentRead:number, size:number})=>void} [params.onFileProgress]
+ * @param {(e: {type:"fileDone", rel:string})=>void} [params.onFileDone]
+ */
+export async function createZip({
+	srcDir,
+	outZip,
+	algo = "deflate",
+	level = 9,
+	concurrency = 1,
+	relFiles,
+	onOverallProgress,
+	onFileProgress,
+	onFileDone
+}) {
+	const { metas, totalBytes } = await statFiles(srcDir, relFiles);
+
+	if (metas.length === 0) {
+		throw new Error("No files to archive.");
+	}
+
+	// ✅ bounded concurrency (1..64)
+	const conc = clampInt(concurrency, 1, 64, 1);
+
+	const zipOptions = algo === "store" ? { store: true } : { zlib: { level } };
+
+	await fsp.mkdir(path.dirname(outZip), { recursive: true });
+
+	const output = fs.createWriteStream(outZip);
+	const archive = archiver("zip", zipOptions);
+
+	archive.on("warning", () => { });
+	archive.on("error", (err) => {
+		throw err;
+	});
+
+	archive.pipe(output);
+
+	const start = Date.now();
+	let processedBytes = 0;
+
+	const timer = setInterval(() => {
+		const elapsed = Date.now() - start;
+		const speedBytesPerSec = (processedBytes / Math.max(1, elapsed)) * 1000;
+		const remaining = totalBytes - processedBytes;
+		const etaMs = speedBytesPerSec > 0 ? (remaining / speedBytesPerSec) * 1000 : Infinity;
+
+		onOverallProgress?.({
+			type: "overall",
+			processedBytes,
+			totalBytes,
+			speedBytesPerSec,
+			etaMs
+		});
+	}, 120);
+
+	let idx = 0;
+
+	// Один "таск" архівує один файл: відкрив stream, підписався на data, append, дочекався end
+	async function archiveOne(f) {
+		let currentRead = 0;
+		const stream = fs.createReadStream(f.abs);
+
+		stream.on("data", (chunk) => {
+			currentRead += chunk.length;
+			processedBytes += chunk.length;
+			onFileProgress?.({
+				type: "file",
+				rel: f.rel,
+				currentRead,
+				size: f.size
+			});
+		});
+
+		archive.append(stream, { name: normalizeToPosix(f.rel), date: f.mtime });
+
+		await new Promise((resolve, reject) => {
+			stream.on("end", resolve);
+			stream.on("error", reject);
+		});
+
+		onFileDone?.({ type: "fileDone", rel: f.rel });
+	}
+
+	// ✅ Worker pool
+	const workers = Array.from({ length: conc }, async () => {
+		while (true) {
+			const my = idx++;
+			if (my >= metas.length) return;
+			await archiveOne(metas[my]);
+		}
+	});
+
+	await Promise.all(workers);
+
+	await archive.finalize();
+
+	await new Promise((resolve, reject) => {
+		output.on("close", resolve);
+		output.on("error", reject);
+	});
+
+	clearInterval(timer);
+
+	return { totalBytes, fileCount: metas.length };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "xzipit",
+	"version": "0.1.0",
+	"description": "CLI utility to zip projects with .zipignore support and live progress",
+	"keywords": [
+		"zip",
+		"archiver",
+		"cli",
+		"compression",
+		"zipignore",
+		"nodejs",
+		"npm",
+		"project-archiver",
+		"ci",
+		"build-tools"
+	],
+	"author": "Roman Ivaskiv",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"xzipit": "bin/xzipit.js"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"README.md",
+		"README.uk.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node --test",
+		"prepublishOnly": "npm test"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"adm-zip": "^0.5.16",
+		"archiver": "^6.0.2",
+		"chalk": "^5.3.0",
+		"commander": "^11.1.0",
+		"fast-glob": "^3.3.2",
+		"ignore": "^5.3.1",
+		"inquirer": "^9.2.12",
+		"log-update": "^6.0.0"
+	}
+}