ism-wifi 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,10 +2,14 @@
 
 ## 1.0.0 (2026-07-26)
 
-- Initial release
-- Interactive setup wizard
+- Interactive setup wizard with hidden password input
 - Connectivity monitoring with configurable interval
 - Automatic login to IIT ISM Dhanbad captive portal
-- Exponential backoff retry logic
-- CLI commands: setup, config, login, reset, version, help
+- Exponential backoff retry logic (1s → 2s → 4s → 8s → 16s → 30s)
+- Graceful Ctrl+C shutdown
+- Colorized terminal output with timestamps
 - Cross-platform support (Windows, Linux, macOS)
+- CLI commands: `setup`, `config`, `login`, `reset`, `change-interval`, `version`, `help`
+- 22 unit tests using Node.js built-in test framework
+- Zero browser automation dependencies
+- Published on npm

package/README.md

@@ -1,66 +1,463 @@
-# ism-wifi
+<p align="center">
+  <h1 align="center">ism-wifi</h1>
+  <p align="center">Auto-login to the IIT ISM Dhanbad captive Wi-Fi portal</p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/ism-wifi"><img src="https://img.shields.io/npm/v/ism-wifi" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/ism-wifi"><img src="https://img.shields.io/npm/l/ism-wifi" alt="license"></a>
+    <a href="https://www.npmjs.com/package/ism-wifi"><img src="https://img.shields.io/node/v/ism-wifi" alt="node version"></a>
+    <a href="https://www.npmjs.com/package/ism-wifi"><img src="https://img.shields.io/npm/dm/ism-wifi" alt="downloads"></a>
+  </p>
+</p>
 
-Auto-login to the IIT ISM Dhanbad captive Wi-Fi portal.
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Commands](#cli-commands)
+- [Configuration](#configuration)
+- [How It Works](#how-it-works)
+- [Project Architecture](#project-architecture)
+- [Project Structure](#project-structure)
+- [Exponential Backoff](#exponential-backoff)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
 
 ## Installation
 
+**Prerequisites:** [Node.js](https://nodejs.org) 20+ and npm.
+
 ```bash
 npm install -g ism-wifi
 ```
 
-## Usage
+Verify it's installed:
+
+```bash
+ism-wifi --version
+```
+
+---
+
+## Quick Start
+
+Run the tool:
 
 ```bash
 ism-wifi
 ```
 
-On first run you will be prompted for your credentials. The configuration is saved automatically. The tool monitors your internet connectivity and re-authenticates when the connection drops.
+On first execution, you'll be guided through setup:
+
+```
+======================================
+       ISM WiFi Auto Login
+======================================
+
+No configuration found.
+
+Let's configure ISM WiFi.
+
+Username: 24je0758
+Password: ********
+Connectivity check interval [30]:
+
+Configuration saved.
+
+Starting monitoring...
+
+[15:31:11] ✓ Internet OK
+```
+
+The tool runs in the terminal until you press **Ctrl+C**.
+
+---
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `ism-wifi` | Start monitoring |
-| `ism-wifi setup` | Re-run configuration setup |
+| `ism-wifi` | Start monitoring (runs setup first if no config) |
+| `ism-wifi setup` | Re-run interactive configuration |
 | `ism-wifi config` | Display current configuration |
-| `ism-wifi login` | Single login attempt |
+| `ism-wifi login` | Perform a single login attempt and exit |
 | `ism-wifi reset` | Delete saved configuration |
 | `ism-wifi change-interval` | Change the connectivity check interval |
-| `ism-wifi version` | Print version |
-| `ism-wifi help` | Display usage |
+| `ism-wifi version` | Print package version |
+| `ism-wifi help` | Display usage information |
+
+### `ism-wifi`
+
+Starts the monitoring loop. Checks internet connectivity every N seconds. If the connection drops, it attempts to log in to the captive portal automatically.
+
+If no configuration exists, the interactive setup wizard runs first.
+
+### `ism-wifi setup`
+
+Re-runs the interactive configuration wizard. Useful if your credentials change or you want to reconfigure the tool.
+
+```
+Username:
+Password:
+Connectivity check interval [30]:
+```
+
+### `ism-wifi config`
+
+Displays your current saved configuration. The password is masked for security.
+
+```
+Username : 24je0758
+
+Interval : 30 seconds
+
+SSL Verify : false
+
+Password : 2********
+```
+
+### `ism-wifi login`
+
+Performs a single login attempt and exits. Useful for testing or scripting.
+
+### `ism-wifi reset`
+
+Deletes the saved configuration. Asks for confirmation first.
+
+```
+? Are you sure you want to delete the saved configuration? (y/N)
+```
+
+### `ism-wifi change-interval`
+
+Change the check interval interactively without re-entering credentials.
+
+```
+New check interval in seconds (current: 30):
+```
+
+---
 
 ## Configuration
 
-Stored automatically at:
+Configuration is stored automatically in your home directory. **No manual file editing required.**
+
+| OS | Config path |
+|----|------------|
+| Windows | `C:\Users\<username>\.ism-wifi\config.json` |
+| Linux | `~/.ism-wifi/config.json` |
+| macOS | `~/.ism-wifi/config.json` |
 
-- **Windows:** `C:\Users\<username>\.ism-wifi\config.json`
-- **Linux/macOS:** `~/.ism-wifi/config.json`
+Example `config.json`:
+
+```json
+{
+  "username": "24je0758",
+  "password": "...",
+  "checkInterval": 30,
+  "verifySSL": false
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `username` | string | — | Your IIT ISM network credential username |
+| `password` | string | — | Your network password (stored in plain text) |
+| `checkInterval` | number | `30` | Seconds between connectivity checks (max 30) |
+| `verifySSL` | boolean | `false` | Whether to verify the portal SSL certificate |
+
+---
 
 ## How It Works
 
-1. Every N seconds (default 30), the tool checks internet connectivity via `clients3.google.com/generate_204`
-2. If connectivity is lost, it posts your credentials to the ISM captive portal
-3. After a 3-second pause, it verifies the connection was restored
-4. If login fails, it retries with exponential backoff (1s, 2s, 4s, 8s, 16s, 30s)
+### High-Level Flow
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Config exists?}
+    B -->|No| C[Run setup wizard]
+    C --> D[Save config]
+    B -->|Yes| D
+    D --> E[Start monitoring loop]
+    E --> F[Check internet]
+    F --> G{Internet OK?}
+    G -->|Yes| H[Sleep N seconds]
+    H --> E
+    G -->|No| I[Attempt login]
+    I --> J[Verify after 3s]
+    J --> K{Access granted?}
+    K -->|Yes| H
+    K -->|No| L[Wait with backoff]
+    L --> I
+```
+
+### Login Retry Flow
+
+```mermaid
+flowchart LR
+    A[Login failed] --> B[Wait 1s]
+    B --> C[Retry login]
+    C --> D{Success?}
+    D -->|No| E[Wait 2s]
+    E --> F[Retry login]
+    F --> G{Success?}
+    G -->|No| H[Wait 4s]
+    H --> I[Retry login]
+    I --> J{Success?}
+    J -->|No| K[Wait 8s]
+    K --> L[Retry login]
+    L --> M{Success?}
+    M -->|No| N[Wait 16s]
+    N --> O[Retry login]
+    O --> P{Success?}
+    P -->|No| Q[Wait 30s]
+    Q --> R[Retry login]
+    R --> S{Success?}
+    S -->|No| T[Give up until next cycle]
+    D -->|Yes| U[✓ Internet restored]
+    G -->|Yes| U
+    J -->|Yes| U
+    M -->|Yes| U
+    P -->|Yes| U
+    S -->|Yes| U
+```
+
+### Connectivity Check
+
+Every `checkInterval` seconds, the tool sends a `GET` request to:
+
+```
+https://clients3.google.com/generate_204
+```
+
+- **HTTP 204** → Internet is available ✓
+- **Anything else** (timeout, redirect, DNS failure, SSL error, connection refused) → Internet unavailable ✗
+
+The request has a **10-second timeout**. If no response is received within that time, connectivity is assumed lost.
+
+### Login
+
+When connectivity is lost, the tool sends a `POST` request to the captive portal:
+
+```
+POST https://netaccess.iitism.ac.in:6082/?url=
+
+Content-Type: application/x-www-form-urlencoded
+
+username=<username>&password=<password>
+```
+
+After the login request, it **waits 3 seconds**, then performs another connectivity check. Only when `HTTP 204` is received is the login considered successful.
+
+---
+
+## Project Architecture
+
+```mermaid
+flowchart TD
+    CLI[cli.js] --> CONFIG[config.js]
+    CLI --> MONITOR[monitor.js]
+    CLI --> LOGIN[login.js]
+    MONITOR --> CONN[connectivity.js]
+    MONITOR --> LOGIN
+    LOGIN --> CONN
+    CONFIG --> UTILS[utils.js]
+    LOGGER[logger.js] --> UTILS
+    MONITOR --> LOGGER
+    CLI --> LOGGER
+
+    subgraph Entry
+        BIN[bin/ism-wifi.js] --> CLI
+    end
+
+    subgraph Core
+        CONFIG
+        CONN
+        LOGIN
+        MONITOR
+    end
+
+    subgraph Shared
+        UTILS
+        LOGGER
+        CONST[constants.js]
+    end
+
+    CLI --> CONST
+    CONFIG --> CONST
+    CONN --> CONST
+    LOGIN --> CONST
+    MONITOR --> CONST
+```
+
+| Module | Responsibility |
+|--------|---------------|
+| `bin/ism-wifi.js` | Entry point — calls `src/index.js` |
+| `src/cli.js` | Commander setup, command routing |
+| `src/config.js` | Load, save, delete config; interactive setup |
+| `src/connectivity.js` | HTTP 204 check via native `fetch` |
+| `src/login.js` | POST credentials to portal, verify |
+| `src/monitor.js` | Main monitoring loop, retry logic |
+| `src/logger.js` | Colored terminal output |
+| `src/utils.js` | sleep, path helpers, formatting |
+| `src/constants.js` | URLs, delays, messages |
+
+---
+
+## Project Structure
+
+```
+ism-wifi/
+├── bin/
+│   └── ism-wifi.js          # CLI entry point
+├── src/
+│   ├── cli.js               # Command definitions and routing
+│   ├── config.js             # Configuration management
+│   ├── connectivity.js       # Internet connectivity checking
+│   ├── login.js              # Captive portal login
+│   ├── monitor.js            # Monitoring loop
+│   ├── logger.js             # Colored terminal output
+│   ├── utils.js              # Shared utilities
+│   ├── constants.js          # Shared constants
+│   └── index.js              # Public API
+├── test/
+│   ├── cli.test.js           # CLI command tests
+│   ├── config.test.js        # Config roundtrip tests
+│   ├── connectivity.test.js  # Connectivity check tests
+│   ├── login.test.js         # Login module tests
+│   └── utils.test.js         # Utility function tests
+├── package.json
+├── CHANGELOG.md
+├── LICENSE
+├── README.md
+└── .gitignore
+```
+
+---
+
+## Exponential Backoff
+
+When a login attempt fails, the tool retries with increasing delays:
+
+```
+Attempt 1  → wait 1 second
+Attempt 2  → wait 2 seconds
+Attempt 3  → wait 4 seconds
+Attempt 4  → wait 8 seconds
+Attempt 5  → wait 16 seconds
+Attempt 6+ → wait 30 seconds (capped)
+```
+
+This prevents hammering the portal while still recovering quickly from transient failures. If all retries fail, the tool returns to the main monitoring loop and tries again on the next interval.
+
+---
 
 ## Troubleshooting
 
-**Login keeps failing:** Run `ism-wifi setup` to re-enter your credentials.
+### Login keeps failing
+
+Run `ism-wifi setup` to re-enter your credentials. Ensure your username and password match what you use on the IIT ISM network portal.
+
+### SSL / certificate errors
+
+The tool disables SSL certificate verification for the captive portal by default (`verifySSL: false`). This is because the portal often uses self-signed certificates. You can enable verification by editing `~/.ism-wifi/config.json` and setting `"verifySSL": true`.
+
+### Network not detected
 
-**SSL errors:** The tool disables SSL verification by default for the captive portal endpoint.
+The tool checks connectivity by requesting `https://clients3.google.com/generate_204`. If this URL is blocked or redirected by your network (other than the captive portal), the tool may incorrectly report no internet. You can test this URL manually in your browser.
+
+### "No configuration found" after setup
+
+Ensure the config file was saved correctly. Check `~/.ism-wifi/config.json` exists and contains valid JSON.
+
+### Permission denied (Linux/macOS)
+
+If you installed globally with `npm install -g`, you might need `sudo` on some systems:
+
+```bash
+sudo npm install -g ism-wifi
+```
+
+Alternatively, [configure npm for global installs without sudo](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
+
+---
 
 ## FAQ
 
-**Q: Does this run in the background?**  
-A: No, it runs in the terminal until you press Ctrl+C.
+**Q: Does this run in the background?**
+A: No. It runs in the terminal and stays active until you press **Ctrl+C**.
 
-**Q: Is my password stored securely?**  
-A: It is stored in plain text in your home directory. Use OS-level disk encryption for security.
+**Q: Is my password stored securely?**
+A: It is stored in plain text in `~/.ism-wifi/config.json`. Use OS-level disk encryption (BitLocker, FileVault, LUKS) to protect your home directory.
+
+**Q: Does it work on macOS?**
+A: Yes. The tool is tested on Windows, Linux, and macOS.
+
+**Q: Can I change the check interval without re-entering my password?**
+A: Yes. Use `ism-wifi change-interval` to update just the interval.
+
+**Q: What happens if the internet goes down while I'm away?**
+A: The tool automatically detects the outage, logs in when connectivity is partially restored, and resumes monitoring.
+
+**Q: How do I stop the tool?**
+A: Press **Ctrl+C**. You'll see:
+
+```
+Stopping ISM WiFi...
+
+Goodbye!
+```
+
+**Q: Do I need to run this on startup?**
+A: Not required. Run it manually when you need it, or set it up as a startup command in your terminal profile.
+
+---
 
 ## Contributing
 
-Contributions welcome. Please open an issue or PR.
+Contributions are welcome!
+
+### Setup
+
+```bash
+git clone <your-fork>
+cd ism-wifi
+npm install
+```
+
+### Running tests
+
+```bash
+npm test
+```
+
+Tests use Node's built-in `node:test` framework — no external test runner needed.
+
+### Guidelines
+
+- ES Modules only (`import`/`export`)
+- Async/await throughout
+- JSDoc comments on all exported functions
+- Small focused functions
+- No global mutable state
+- Cross-platform compatible
+- Run `npm test` before submitting
+
+### Pull requests
+
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes
+4. Run tests
+5. Submit a PR with a clear description
+
+---
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "ism-wifi",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Auto-login to IIT ISM Dhanbad captive Wi-Fi portal",
   "type": "module",
   "bin": {
-    "ism-wifi": "./bin/ism-wifi.js"
+    "ism-wifi": "bin/ism-wifi.js"
   },
   "files": [
     "bin/",
@@ -18,7 +18,12 @@
     "test": "node --test",
     "start": "node bin/ism-wifi.js"
   },
-  "keywords": ["iit-ism", "wifi", "captive-portal", "cli"],
+  "keywords": [
+    "iit-ism",
+    "wifi",
+    "captive-portal",
+    "cli"
+  ],
   "license": "MIT",
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",