# 9Router Manager

Manajemen 9Router AI gateway lokal — scan model, update combo, monitor provider.

**Cross-platform**: Windows, Linux, macOS supported.

**Tests: 88/88 pass · Node ≥18**

## Fitur

- ✅ Scan semua model dari provider aktif
- ✅ Concurrent testing (configurable, default 1 worker — raise NINEROUTER_MAX_WORKERS env var untuk scan paralel)
- ✅ Auto-retry pada HTTP 429 (rate limit)
- ✅ Progress bar real-time
- ✅ Audit log untuk tracking perubahan (verify_token disanitasi, ditulis async)
- ✅ Setup auto-scan via scheduler interaktif (confirm + auto-exec, atau print-only mode)

## Struktur

```
9router-manager/
├── bin/
│   └── 9router-manager.js  # Executable shim
├── src/
│   ├── cli.js              # CLI entry + commander setup
│   ├── env.js              # .env loader + path/token helpers
│   ├── scan.js             # API + concurrent scan logic
│   ├── combo.js            # SQLite combo management
│   ├── metadata.js         # Model pattern matching + sort keys
│   └── results.js          # Read & print audit JSON
├── tests/
│   ├── audit-shape.test.js
│   ├── cli.test.js
│   ├── combo.test.js
│   ├── env.test.js
│   ├── metadata.test.js
│   ├── paths.test.js
│   ├── results.test.js
│   └── scan.test.js
├── bat/                    # Windows batch scripts
│   ├── run-scan.bat
│   ├── check-results.bat
│   └── setup-scheduler.bat
├── sh/                     # Unix shell scripts
│   ├── run-scan.sh
│   ├── check-results.sh
│   ├── setup-scheduler.sh
│   └── setup-scheduler-macos.sh
├── metadata.json           # Model patterns + release dates
├── package.json            # Node.js package config
├── .env                    # Konfigurasi lokal (password, path)
└── .env.template           # Template dokumentasi
```

## Setup

### 1. Konfigurasi

Gunakan perintah bawaan CLI untuk mengatur konfigurasi global (disimpan di `~/.9router/.env`):

```bash
9router-manager config
```

Aplikasi akan meminta Anda untuk memasukkan:
- `NINEROUTER_PASSWORD` (password dashboard 9Router)
- `NINEROUTER_BASE_URL` (biarkan default jika menggunakan `localhost:20128`)

*(Jika Anda ingin konfigurasi per-folder, Anda masih bisa meng-copy `.env.template` ke `.env` di folder tersebut).*

### 2. Setup Auto-Scan (Opsional)

**Cara cepat (via CLI):**
```bash
9router-manager setup       # Tanyakan konfirmasi, lalu jalankan script
9router-manager setup -y    # Skip konfirmasi (untuk script/CI)
```

**Cara manual (langsung ke script):**
```bash
# Windows (as Administrator)
bat\setup-scheduler.bat

# Linux (cron)
./sh/setup-scheduler.sh

# macOS (launchd)
./sh/setup-scheduler-macos.sh
```

## Usage

### CLI (Recommended)

After installation, simply type:
```bash
9router-manager
```

Akan muncul menu interaktif:
```
╔═══════════════════════════════════════════════════╗
║           9Router Manager v0.0.1                     ║
╠═══════════════════════════════════════════════════╣
║  AI Gateway Local - Model Scanner                 ║
╚═══════════════════════════════════════════════════╝

  [1] Run Model Scan
  [2] List Combos
  [3] Show Last Scan Results
  [4] Test Single Model
  [5] Setup Auto-Scan Scheduler
  [6] Configure Settings
  ────────────────────────────────────────────────────────────
  [v] Version Info    [h] Show Help    [q] Quit

  Pilihan (nomor/v/h/q):
```

Atau gunakan command line mode:
```bash
9router-manager scan                              # Run scan
9router-manager list                              # List combos
9router-manager list --details                    # List combos + models in each
9router-manager results                           # Check results
9router-manager test <model>                      # Test single model
9router-manager setup                             # Setup scheduler (interaktif)
9router-manager setup -y                          # Setup scheduler (skip prompt)
9router-manager config                            # Configure global settings (interaktif)
9router-manager version                           # Version info
9router-manager help                              # Show help
```

### Installation

Install globally via npm (recommended for development):

```bash
npm link
```

Setelah itu perintah `9router-manager` bisa dipanggil dari direktori manapun (entry-point dari `package.json`).

### Shell Scripts (Fallback)

Jika CLI belum diinstall, bisa pakai shell scripts:

**Linux/macOS:**
```bash
./sh/run-scan.sh
./sh/check-results.sh
./sh/setup-scheduler.sh
```

**Windows:**
```bash
bat\run-scan.bat
bat\check-results.bat
bat\setup-scheduler.bat
```

### Direct Node

```bash
node src/cli.js scan
node src/cli.js results
node src/cli.js test minimax/MiniMax-M2.7
```

### Commit

```bash
git add .
git commit -m "feat: add new feature"
```

Format: `type: short description`

## Konfigurasi

| Variable | Default | Deskripsi |
|----------|---------|-----------|
| `NINEROUTER_PASSWORD` | (required) | Password dashboard 9Router |
| `NINEROUTER_BASE_URL` | `http://localhost:20128` | URL 9Router gateway |
| `NINEROUTER_DB_PATH` | OS-specific | Path SQLite DB |
| `NINEROUTER_AUDIT_PATH` | OS-specific | Audit log output |
| `NINEROUTER_TIMEOUT` | `8` | Timeout per model (detik) |
| `NINEROUTER_MAX_WORKERS` | `1` | Concurrent workers |
| `NINEROUTER_RETRY_429_MAX` | `2` | Max retry pada rate limit |
| `NINEROUTER_RETRY_429_DELAY` | `3.0` | Delay antar retry (detik) |
| `NINEROUTER_SLEEP` | `0.05` | Delay antar test (detik) |
| `NINEROUTER_PROMPT` | `1+1=?` | Prompt dikirim ke setiap model |
| `NINEROUTER_ENV_FILE` | (unset) | Override default .env search path |

## Managed Combo

Target combo **tidak dikonfigurasi** — scanner mendeteksinya otomatis dari `/v1/models` × tabel `combos` SQLite.

- 0 combo cocok: scanner berhenti dengan error.
- Tepat 1 combo cocok: combo itu yang di-update.
- Lebih dari 1 cocok: scanner berhenti dengan error (target ambigu).

Managed combo berisi semua model dari semua provider yang berhasil response saat di-test.

- Menambah model baru yang mulai response
- Menghapus model yang tidak lagi response (timeout, 400, 402, 404, 429, error)
- Skip provider yang statusnya `active=false` di SQLite 9Router

## Commit Types

| Type | Usage |
|------|-------|
| `feat` | Fitur baru |
| `fix` | Bug fix |
| `docs` | Dokumentasi |
| `style` | Formatting, typo |
| `refactor` | Refactoring |
| `perf` | Performa |
| `test` | Unit test |
| `build` | Build system |
| `ci` | CI/CD |
| `chore` | Config, dependency |
| `revert` | Revert commit |

## Quick Start

```bash
# 1. Install dependencies
npm install

# 2. Setup configuration
node src/cli.js config
# (You will be prompted to enter your 9Router password)

# 3. Run scan
npm run scan
# atau
node src/cli.js scan

# 4. Check results
npm run results
# atau
node src/cli.js results

# 5. Run tests
npm test
```

## Sub-commands

- `scan` — Run daily combo model scan
- `list` — List combos in database (use `--details` to show models)
- `results` / `check` / `status` — Show last scan results
- `test <model>` — Test a single model
- `setup` — Setup auto-scan scheduler (interactive; `-y` to skip prompt)
- `config` — Configure global settings (interactive)
- `version` — Show version info
- `help` — Show help

## Per-Phase Test Scripts

```bash
npm run env:test         # 8 tests
npm run cli:test         # 6 tests
npm run paths:test       # 14 tests
npm run metadata:test    # 22 tests
npm run combo:test       # 9 tests
npm run scan:test        # 16 tests
npm run results:test     # 8 tests
npm run audit-shape:test # 10 tests
npm test                 # 88 tests total
```

## Key Files

| File | Platform | Description |
|------|----------|-------------|
| `bin/9router-manager.js` | All | Executable shim (`#!/usr/bin/env node`) |
| `src/cli.js` | All | CLI entry + commander setup + interactive menu |
| `src/scan.js` | All | API + concurrent scan logic |
| `src/combo.js` | All | SQLite combo management (async) |
| `src/env.js` | All | .env loader + path helpers |
| `src/metadata.js` | All | Model pattern matching + sort keys |
| `src/results.js` | All | Audit JSON reader/summarizer |
| `package.json` | All | Node.js package config |
| `sh/run-scan.sh` | Linux/macOS | Run scan (fallback) |
| `sh/check-results.sh` | Linux/macOS | Check results (fallback) |
| `bat/run-scan.bat` | Windows | Run scan (fallback) |

## OS-Specific Paths

Default paths untuk setiap OS (jika `NINEROUTER_DB_PATH` / `NINEROUTER_AUDIT_PATH` tidak diset):

| OS | DB Path | Audit Path |
|----|---------|------------|
| Windows | `~/AppData/Roaming/9router/db/data.sqlite` | `%USERPROFILE%\AppData\Local\hermes\scripts\9router_daily_combo_model_scan_last.json` |
| Linux | `~/.9router/db/data.sqlite` (fallback: `~/.config/9router/`, `~/.local/share/9router/`, `snap`) | `~/.local/share/9router/audit/9router_daily_combo_model_scan_last.json` |
| macOS | `~/.9router/db/data.sqlite` (fallback: `~/.config/9router/`, `~/.local/share/9router/`) | `~/Library/Logs/9router-scan.log` |

## Project Status

- [x] All rewrite phases complete
- [x] 88/88 tests pass (`npm test`)
- [x] `npm run lint` passes
- [x] No `AIO` references in the tree
- [x] Combo-agnostic audit file paths
- [x] Async audit write + sanitized verify_token
- [x] Multi-platform CI (Linux, macOS, Windows × Node 18/20/22)
- [x] `node bin/9router-manager.js` works end-to-end
- [x] Interactive menu with letter shortcuts (q/h/v)
- [x] `setup` command with confirm + auto-exec + non-TTY fallback

## Open Questions

- **TypeScript?** Plain JS for now. Can be added later via `tsc --check` without a full rewrite.
- **Cookie store?** In-memory `Map` (single-session scan). Browser-equivalent `tough-cookie` is overkill for a one-shot CLI run.
- **Concurrency model?** Promise-based fan-out (capped by `NINEROUTER_MAX_WORKERS`). Watch SQLite write contention at the end of long runs.
- **Schema for `metadata.json`?** Ported as-is. Normalize later if it pays off.

## Commit

```bash
git add .
git commit -m "feat: add new feature"
```

Format: `type: short description`