zembil

Zembil - Offline Package & Docs Cache

Zembil (Amharic for "stash" or "store") is an offline package and documentation cache system designed for developers in areas with unreliable internet connectivity and frequent power outages.

The Problem

Developers in regions with poor internet infrastructure face:

• Hours of failed npm install attempts
• Inability to access documentation during outages
• Wasted development time due to connectivity issues
• Difficulty learning new packages without internet access

Why Zembil vs npm/pip/maven?

❌ What npm/pip/maven can't do:

• Offline installs fail - Even with npm cache, you need internet to resolve dependencies
• No documentation caching - Docs are online-only, inaccessible during outages
• No queue system - Can't plan ahead and download later
• Single manager focus - Each tool only handles its own ecosystem
• No progress tracking - Can't pause/resume downloads manually

✅ What Zembil adds:

• True offline installs - Install packages completely offline once cached
• Documentation included - Full docs cached with packages for offline access
• Queue system - Queue 50+ packages when you have 5 minutes of good internet, download later
• Multi-manager unified cache - One tool for npm, pip, maven packages
• Manual pause/resume - Control downloads with progress tracking
• Team sharing - Share cache directories across devices/teams

🎯 When to use Zembil:

• ✅ Unreliable/poor internet connection
• ✅ Need to work offline frequently
• ✅ Want offline documentation access
• ✅ Use multiple package managers (npm + pip + maven)
• ✅ Team collaboration with shared cache
• ✅ Air-gapped or bandwidth-limited environments

🚀 When npm/pip/maven is fine:

• ✅ Stable internet connection
• ✅ Only need packages (not docs)
• ✅ Single package manager
• ✅ No need for offline workflow

The Solution

Zembil allows developers to:

• Queue packages they need during good connectivity periods
• Download and cache packages with full documentation
• Install instantly from local cache when offline
• Access documentation with zero latency
• Automatic interruption tracking - progress saved automatically, resume anytime
• Sync across devices when connectivity returns

Features

• 🚀 Multi-package manager support: npm, pip, Maven, and more
• 📚 Full documentation caching: API docs, examples, tutorials
• ⏸️ Pause/Resume downloads: Manual control with progress tracking
• 📊 Real-time progress: See download progress with visual indicators
• ❌ Cancel downloads: Cancel specific packages or all pending downloads
• 🧹 Cache management: Clean specific packages or entire cache
• 🔄 Smart sync: Only download what's changed
• 💾 Efficient storage: Compressed, deduplicated cache
• 🎯 IDE integration: Works with VS Code, IntelliJ, etc.
• 🌐 Offline-first: Designed for unreliable connections
• ⚡ Power outage resilient: Graceful handling of interruptions

Quick Start

CLI Usage

# Install Zembil
npm install -g zembil

# Initialize cache directory
zembil init

# Initialize with custom cache directory (optional)
zembil --cache-dir ./my-cache init

# Queue packages for download
zembil queue add react -v 18.2.0
zembil queue add express -v 4.18.0
zembil queue add lodash -v 4.17.21

# Download queued packages (when you have good internet)
zembil sync
# ⬇️  react@18.2.0: [████████░░░░░░░░░░░░] 45% (2.3MB / 5.1MB)

# If interrupted (network loss, Ctrl+C), progress is automatically saved!
# Check status anytime:
zembil queue list
# ⏸️ react@18.2.0 (npm) - interrupted
#    Progress: [████████░░░░░░░░░░░░] 45% (2.3MB / 5.1MB) (interrupted, will resume)

# Resume when ready (just run sync again, or use resume command)
zembil queue resume  # Optional: marks interrupted items for retry
zembil sync          # Continues from where it left off

# Cancel downloads if needed
zembil queue cancel react           # Cancel specific package
zembil queue cancel-all             # Cancel all pending downloads

# Manage cache
zembil cache clean react            # Remove all versions of a package
zembil cache clean --all            # Remove all cached packages
zembil cache cleanup                # Clean orphaned files

# Install from cache (works offline!)
zembil install react express lodash

Programmatic Usage

import { Zembil } from 'zembil';

// Initialize Zembil
const zembil = new Zembil('./cache');
await zembil.initialize();

// Queue packages
await zembil.queue.add('react', '18.2.0', 'npm', 10);
await zembil.queue.add('express', '4.18.0', 'npm', 8);

// Download packages (progress tracked automatically)
await zembil.sync();

// If interrupted (network error, Ctrl+C), progress is automatically saved!
// Check status to see what was interrupted
const status = await zembil.queue.getStatus();
const items = await zembil.queue.list();
items.forEach(item => {
  if (item.progress) {
    console.log(`${item.packageName}: ${item.progress.percentage}% (interrupted, will resume)`);
  }
});

// Resume interrupted downloads (optional - sync will also retry them)
await zembil.queue.resume();
await zembil.sync(); // Continues from where it left off

// Install from cache
await zembil.install('react', './node_modules');

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Good Internet │    │   Local Cache   │    │  Offline Usage  │
│                 │    │                 │    │                 │
│ • Queue packages│───▶│ • Package files │───▶│ • Instant install│
│ • Download docs │    │ • Documentation │    │ • Fast docs     │
│ • Sync metadata │    │ • Examples       │    │ • No latency    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Documentation

• 📖 Developer Guide - Complete guide for using Zembil as a library
• 🔧 API Reference - Complete API documentation
• 🏗️ Architecture - System design and components
• 🧪 Testing Guide - How to test Zembil applications
• 📚 Basic Usage - CLI usage examples
• 💻 Programmatic Usage - Library usage examples

Installation

As a CLI Tool

npm install -g zembil

As a Library

npm install zembil

License

MIT License - Built for the global developer community