🧙 LANES-ENGINE — Terminal-Native Distributed Execution Engine (v1.2.0)

lanes-engine is a CLI-based, high-throughput, 15-lane parallel mail delivery engine. It splits massive recipient queues into 15 independent workers, executing jobs in concurrent batches of 20 with dynamic load balancing, checkpoint-based pauses, live CLI dashboard metrics, and non-interactive failure retry via resend --failed-only.

🎨 Visual Console Aesthetic

    ✦  ·  ✧  ·  ✦  ·  ✧  ·  ✦
   ╔══════════════════════════════════════════════════════════════╗
   ║  ██╗      █████╗ ███╗   ██╗███████╗███████╗                 ║
   ║  ██║     ██╔══██╗████╗  ██║██╔════╝██╔════╝                 ║
   ║  ██║     ███████║██╔██╗ ██║█████╗  ███████╗                 ║
   ║  ██║     ██╔══██║██║╚██╗██║██╔══╝  ╚════██║                 ║
   ║  ███████╗██║  ██║██║ ╚████║███████╗███████║                 ║
   ║  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝                 ║
   ╚══════════════════════════════════════════════════════════════╝
       "We route the mail through chaos"
    ✧  ·  ✦  ·  ✧  ·  ✦  ·  ✧

• 24-bit gradient banner (cyan → magenta, line-by-line)
• Typewriter banner animation on cold start
• Braille spinner during session load + connection pre-warm
• Hooded wizard ASCII mascot drawn at start of every command
• Per-lane live status glyphs (◐ sending, ● done, ○ idle)
• Confetti burst when the campaign finishes

🚀 Core Features

1. 15 Parallel Sending Lanes: Distributes lists equally using a deterministic round-robin queue.
2. File-Driven Input: Zero database requirements. Just drop email.txt and senders.csv.
3. Live Dashboard Metrics: Gradient progress bar, per-lane glyphs, processing speed, failure count.
4. Auto-Retry (resend --failed-only): After any run, the engine writes lanes-session.json (template + recipients). Re-run failed emails non-interactively with one command.
5. Fast Cold Start: Backend connection pre-warmed in parallel with file parsing; heavy CSS inliner is lazy-loaded only when HTML mode is enabled.
6. No Web Bloat: Strictly a CLI engine built for speed and integration into external services.

📁 Input Format Requirements

1. email.txt

Place this in your working directory. Use Subject: as the first line header. Supports template rendering via {{placeholder}}:

Subject: Welcome {{name}} to Scholarly!

Hello {{name}},

Your journey through the lanes begins now.

— MQ Team

2. senders.csv

Contains the recipient email list and fields for templating:

email,name
[email protected],Alex
[email protected],Sara
[email protected],John

⚙️ CLI Installation & Commands

Install globally via npm:

npm install -g lanes-engine

1. Initialize Templates

Create initial email.txt and senders.csv mock templates in your current directory:

lanes-engine init

2. Run Campaign Processing

Parse the local templates and start the 15 parallel workers:

lanes-engine send

3. Check Latest Summary

Read the final log report from the latest run:

lanes-engine status

4. Open Detailed Performance Breakdown

Displays per-lane success/error counts and detailed failure stream error messages:

lanes-engine report

5. Auto-Resend Failed Emails (Non-Interactive)

Re-runs only the recipients that failed in the most recent session, using the saved lanes-session.json. No prompts, no interactive recycle loop:

lanes-engine resend --failed-only

You can chain --no-banner to skip the startup animation in CI/scripted environments:

lanes-engine resend --failed-only --no-banner

🧠 Code Architecture

The project structure is organized cleanly for packaging and extensibility:

lanes-engine/
 ├── bin/
 │    └── cli.js           # CLI routing and command arguments
 ├── core/
 │    ├── engine.js        # Main core workflow orchestrator
 │    ├── lanes.js         # Gmail/API parallel lane workers (batch size 20) + prewarm
 │    ├── queue.js         # Round-robin job partitioning builder
 │    ├── parser.js        # CSV & placeholder template parses
 │    ├── reporter.js      # Save campaign logs + session state
 │    ├── resend.js        # Non-interactive resend of failed recipients
 │    └── retry.js         # Console failure prompt & queue recycling
 ├── ui/
 │    ├── cli-progress.js  # Live dashboard with gradient progress bar
 │    └── cli-theme.js     # Colors, gradient banner, mascot, animations

📄 License

MIT © Lanes Wizard