neozip-cli 0.70.0-alpha

package/README.md

@@ -0,0 +1,504 @@
+# NeoZip CLI
+
+> Full-featured command-line ZIP application with blockchain integration and advanced compression
+
+[![npm version](https://img.shields.io/npm/v/neozip-cli?label=alpha&color=orange)](https://www.npmjs.com/package/neozip-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org/)
+
+## ⚠️ Alpha Release Notice
+
+**This is an alpha release (v0.70.0-alpha).** This software is in early development and may contain bugs, incomplete features, or breaking changes. Use at your own risk.
+
+- **API Stability**: Command-line interface may change in future releases
+- **Testing**: Please test thoroughly and report any issues
+- **Feedback**: We welcome feedback and bug reports via [GitHub Issues](https://github.com/NeoWareInc/neozip-support/issues) or email [support@neozip.io](mailto:support@neozip.io)
+
+## Overview
+
+NeoZip CLI is a modern, full-featured ZIP utility that provides:
+
+- **Standard ZIP Compatibility**: ~99% compatible with InfoZip utilities
+- **Blockchain Integration**: Tokenize archives and verify integrity on-chain
+- **Advanced Compression**: Zstd, Deflate, and Store compression methods
+- **Encryption Support**: PKZIP encryption
+- **Cross-Platform**: Works on macOS, Linux, and Windows
+
+## Features
+
+### Core Functionality
+- ✅ Create, extract, and list ZIP archives
+- ✅ Standard ZIP format compatibility
+- ✅ ZIP64 support for large files (>4GB)
+- ✅ Archive comments and file comments
+- ✅ Recursive directory processing
+- ✅ Pattern-based file inclusion/exclusion
+- ✅ Stdin filename input
+
+### Compression
+- **Zstd**: Modern, fast compression (default)
+- **Deflate**: Standard ZIP compression (maximum compatibility)
+- **Store**: No compression (fastest, for already-compressed files)
+- Compression levels: 0-9 (0=store, 9=best compression)
+
+### Encryption
+- **PKZIP**: Legacy encryption (maximum compatibility)
+- Password-protected archives
+- InfoZip-compatible encrypted archives
+
+### Blockchain Features
+- **Tokenization**: Create on-chain tokens for archives
+- **OpenTimestamp**: Bitcoin blockchain timestamping
+- **Integrity Verification**: Verify archive integrity on-chain
+- **Network Support**: Base Sepolia, Base Mainnet, Arbitrum, and more
+
+### Advanced Features
+- Symbolic link handling
+- Hard link detection and deduplication
+- File permission preservation
+- Progress reporting
+- Archive integrity testing
+- Update and freshen modes
+- Move files into archive
+- Delete files from archive
+
+## Installation
+
+### Prerequisites
+
+- Node.js 16.0.0 or higher
+- npm or yarn package manager
+
+### Install from npm (Alpha Release)
+
+```bash
+npm install -g neozip-cli@alpha
+```
+
+After installation, the following commands will be available:
+- `neozip` - Create and manage ZIP archives
+- `neounzip` - Extract files from ZIP archives
+- `neolist` - List contents of ZIP archives
+
+### Verify Installation
+
+```bash
+neozip --version
+neounzip --version
+neolist --version
+```
+
+## Quick Start
+
+### Basic Usage
+
+```bash
+# Create a ZIP archive
+neozip archive.nzip file1.txt file2.txt folder/
+
+# Create archive with recursive directory inclusion
+neozip -r archive.nzip ./project/
+
+# Create tokenized archive (blockchain integration)
+neozip -b tokenized.nzip file1.txt file2.txt
+
+# Extract files from archive
+neounzip archive.nzip extracted/
+
+# Extract and verify tokenized archive
+neounzip -t tokenized.nzip
+
+# Test the archive file
+neounzip -t archive.nzip
+
+# List archive contents
+neolist archive.nzip
+
+# List with detailed information
+neolist -v archive.nzip
+```
+
+### Compression Examples
+
+```bash
+# Compress with default settings (Zstd)
+neozip output.nzip ./src/
+
+# Compress with maximum compression
+neozip -9 output.nzip ./src/
+
+# Compress with deflate (maximum compatibility)
+neozip --compression deflate output.nzip ./src/
+
+# Store files without compression (fastest)
+neozip -0 output.nzip ./src/
+```
+
+### Encryption Examples
+
+```bash
+# Create encrypted archive (will prompt for password)
+neozip -e secure.nzip file.txt
+
+# Create encrypted archive with password
+neozip -e -P "mypassword" secure.nzip file.txt
+
+# Extract encrypted archive
+neounzip -P "mypassword" secure.nzip extracted/
+```
+
+### Blockchain Examples
+
+```bash
+# Tokenize archive on Base Sepolia (default)
+neozip -b tokenized.nzip file.txt
+
+# Tokenize with OpenTimestamp proof
+neozip -ots timestamped.nzip file.txt
+
+# Extract and verify blockchain integrity
+neounzip tokenized.nzip extracted/
+```
+
+## Commands
+
+### `neozip` - Create and Manage Archives
+
+Create, update, and manage ZIP archives.
+
+**Basic Syntax:**
+```bash
+neozip [options] <archive> [files...]
+```
+
+**Common Options:**
+- `-r, --recurse` - Include subdirectories recursively
+- `-0` to `-9` - Compression level (0=store, 9=best)
+- `-x, --exclude <pattern>` - Exclude files matching pattern
+- `-i, --include <pattern>` - Include only matching files
+- `-e, --encrypt` - Encrypt files (will prompt for password)
+- `-P, --password <pwd>` - Encrypt with password
+- `-b, --blockchain` - Enable blockchain tokenization
+- `-ots, --opentimestamp` - Enable OpenTimestamp proof
+- `-T, --test-integrity` - Test archive after creation
+- `-v, --verbose` - Enable verbose output
+- `-q, --quiet` - Suppress output
+
+**Configuration Commands:**
+```bash
+neozip init      # Interactive wallet setup wizard
+neozip config     # Show current configuration
+```
+
+**Examples:**
+```bash
+# Compress directory recursively
+neozip -r archive.nzip ./project/
+
+# Compress with exclusions
+neozip -x "*.log" -x "*.tmp" archive.nzip ./src/
+
+# Compress from stdin
+find . -name "*.txt" | neozip -@ archive.nzip
+
+# Update existing archive
+neozip -u archive.nzip ./src/
+
+# Move files into archive
+neozip -m archive.nzip ./temp/
+```
+
+### `neounzip` - Extract Archives
+
+Extract files from ZIP archives.
+
+**Basic Syntax:**
+```bash
+neounzip [options] <archive> [output]
+```
+
+**Common Options:**
+- `-d, --exdir <dir>` - Extract to specific directory
+- `-o, --overwrite` - Overwrite files without prompting
+- `-t, --test` - Test archive integrity
+- `-l, --list` - List contents without extracting
+- `-P, --password <pwd>` - Password for encrypted archives
+- `-x, --exclude <pattern>` - Exclude files from extraction
+- `-i, --include <pattern>` - Include only matching files
+- `-j, --junk-paths` - Extract files without directory structure
+- `-v, --verbose` - Enable verbose output
+- `-q, --quiet` - Suppress output
+
+**Examples:**
+```bash
+# Extract to current directory
+neounzip archive.nzip
+
+# Extract to specific directory
+neounzip archive.nzip ./extracted/
+
+# Test archive integrity
+neounzip -t archive.nzip
+
+# Extract with exclusions
+neounzip -x "*.log" archive.nzip extracted/
+
+# Extract encrypted archive
+neounzip --password "mypassword" secure.nzip extracted/
+```
+
+### `neolist` - List Archive Contents
+
+List and inspect ZIP archive contents.
+
+**Basic Syntax:**
+```bash
+neolist [options] <archive>
+```
+
+**Common Options:**
+- `-v, --verbose` - Detailed listing
+- `-s, --short` - Short format
+- `-j, --json` - Output as JSON
+- `-u, --unix` - Unix-style listing
+- `-b, --basic` - Basic listing
+- `-1` - Filenames only
+- `-2` - Filenames with header/totals
+
+**Examples:**
+```bash
+# Basic listing
+neolist archive.nzip
+
+# Verbose listing
+neolist -v archive.nzip
+
+# JSON output
+neolist -j archive.nzip
+
+# Filenames only
+neolist -1 archive.nzip
+```
+
+## Configuration
+
+### Wallet Setup (for Blockchain Features)
+
+To use blockchain features, you need to configure a wallet:
+
+```bash
+# Interactive setup wizard
+neozip init
+```
+
+This will guide you through:
+1. Creating or importing a wallet
+2. Selecting a blockchain network
+3. Saving configuration to `~/.neozip/wallet.json`
+
+### Environment Variables
+
+You can also configure via environment variables:
+
+```bash
+export NEOZIP_WALLET_PASSKEY="your-wallet-key"
+export NEOZIP_NETWORK="base-sepolia"  # or base-mainnet, arbitrum-sepolia, etc.
+```
+
+### Configuration File
+
+Configuration is stored in `~/.neozip/wallet.json`:
+
+```json
+{
+  "walletKey": "0x...",
+  "network": "base-sepolia",
+  "rpcUrl": "https://..."
+}
+```
+
+## Advanced Examples
+
+### Common Workflows
+
+```bash
+# Create archive
+neozip project.nzip src/ docs/ README.md
+
+# List contents
+neolist project.nzip
+
+# Extract files
+neounzip project.nzip extracted/
+
+# Test integrity
+neounzip -t project.nzip
+```
+
+### Compression Options
+
+```bash
+# Maximum compression
+neozip -9 archive.nzip large-folder/
+
+# Fast compression
+neozip -1 archive.nzip large-folder/
+
+# Store only (no compression)
+neozip -0 archive.nzip already-compressed-files/
+```
+
+### File Selection
+
+```bash
+# Include only JavaScript files
+neozip -i "*.js" code.nzip ./src/
+
+# Exclude log files
+neozip -x "*.log" -x "*.tmp" clean.nzip ./project/
+
+# Recursive with exclusions
+neozip -r -x "node_modules" -x "*.log" project.nzip ./
+```
+
+### Encryption
+
+```bash
+# Create encrypted archive
+neozip -e -P "secure-password" secret.nzip sensitive-files/
+
+# Extract encrypted archive
+neounzip -P "secure-password" secret.nzip decrypted/
+```
+
+### Blockchain Features
+
+```bash
+# Tokenize archive
+neozip -b tokenized.nzip important-file.txt
+
+# Tokenize with OpenTimestamp
+neozip -ots timestamped.nzip document.pdf
+
+# Extract and verify
+neounzip tokenized.nzip verified/
+```
+
+### Advanced Operations
+
+```bash
+# Update existing archive
+neozip -u archive.nzip ./updated-files/
+
+# Move files into archive
+neozip -m archive.nzip ./temp-files/
+
+# Delete files from archive
+neozip -d archive.nzip old-file.txt
+
+# Preserve file permissions
+neozip -X archive.nzip ./files/
+
+# Handle symbolic links
+neozip -y archive.nzip ./symlinks/
+```
+
+## Requirements
+
+- **Node.js**: 16.0.0 or higher
+- **Platform**: macOS, Linux, or Windows
+- **Disk Space**: ~1MB for installation, additional space for archives
+
+## Documentation
+
+The following documentation is included with this package:
+
+- **[README.md](README.md)** - This file, containing installation, usage, and examples
+- **[WHY_NEOZIP.md](WHY_NEOZIP.md)** - Introduction to NeoZip and its blockchain integration
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
+- **[DOCUMENTATION.md](DOCUMENTATION.md)** - Complete documentation index and reference
+
+## Troubleshooting
+
+### Installation Issues
+
+**Command not found after installation:**
+```bash
+# Verify npm global bin path is in your PATH
+npm config get prefix
+
+# Add to PATH if needed (example for macOS/Linux)
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+**Permission errors:**
+```bash
+# Use sudo (not recommended) or fix npm permissions
+sudo npm install -g neozip-cli@alpha
+
+# Better: Fix npm permissions
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### Runtime Issues
+
+**Archive integrity errors:**
+```bash
+# Test archive integrity
+neounzip -t archive.nzip
+
+# Recreate archive if corrupted
+neozip new-archive.nzip original-files/
+```
+
+**Blockchain errors:**
+```bash
+# Check wallet configuration
+neozip config
+
+# Reconfigure wallet
+neozip init
+```
+
+**Encryption errors:**
+```bash
+# Verify password is correct
+neounzip -P "your-password" archive.nzip
+
+# Try different encryption method
+neozip --pkzip-encrypt -P "password" archive.nzip files/
+```
+
+## Contributing
+
+We welcome feedback and contributions! Since this is an alpha release, we're actively seeking input:
+
+1. **Report Issues**: Use [GitHub Issues](https://github.com/NeoWareInc/neozip-support/issues) or email [support@neozip.io](mailto:support@neozip.io)
+2. **Suggest Features**: Share your ideas and use cases
+3. **Test and Provide Feedback**: Help us improve by testing and reporting your experience
+
+**Important**: This is an alpha release. API and behavior may change. Please test thoroughly.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **GitHub Issues**: [Report bugs or request features](https://github.com/NeoWareInc/neozip-support/issues) (public issue tracker)
+- **Email Support**: [support@neozip.io](mailto:support@neozip.io)
+- **Documentation**: See [DOCUMENTATION.md](DOCUMENTATION.md) for detailed guides
+
+## Acknowledgments
+
+- Built with [NeoZipKit] - coming soon
+- Compatible with InfoZip utilities
+- Follows ZIP format specification (APPNOTE.TXT)
+
+---
+
+**Version**: 0.70.0-alpha  
+**Status**: Alpha Release  
+**Last Updated**: 2025