ispbills-icli 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# iCli — IspBills AI Terminal
+
+**iCli** is a command-line interface for [IspBills](https://github.com/lupael/IspBills) that brings your iCopilot AI network engineer to any terminal.
+
+Ask it anything your NOC team would ask:
+
+```bash
+icli "is vlan 82 in use across my network?"
+icli "show all ONUs on olt#1"
+icli "which customer is using IP 10.10.1.50?"
+icli "check high optical signal on main OLT"
+```
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- A running IspBills instance
+- An operator account (group admin, operator, or NOC user)
+
+---
+
+## Quick start (npx — no install)
+
+```bash
+npx ispbills-icli
+```
+
+On first run iCli will ask for your instance URL, email, and password. Credentials are saved to `~/.config/ispbills-icli/config.json` (mode 600 — readable only by you).
+
+---
+
+## Permanent install
+
+```bash
+npm install -g ispbills-icli
+icli
+```
+
+---
+
+## Usage
+
+### Interactive REPL
+
+```
+$ icli
+
+  iCli — IspBills AI terminal
+  Connected to: https://app.myisp.com
+
+  Type your question. Press Ctrl+C or type "exit" to quit.
+
+iCli › is vlan 82 free on all devices?
+
+  › 🧭 Assigning 3 sub-agents…
+  › ✅ [1/3] nas#1: FREE
+  › ✅ [2/3] nas#2: FREE
+  › ✅ [3/3] olt#1: FREE
+
+VLAN 82 is free across all 3 reachable devices in your fleet.
+
+iCli › exit
+```
+
+### Single-shot query
+
+```bash
+icli "check uptime on all routers"
+icli "show customers with overdue invoices"
+icli "what is the RX power on olt#1?"
+```
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `icli` | Start interactive REPL |
+| `icli "question"` | Single question, then exit |
+| `icli login` | Re-authenticate (or switch instance) |
+| `icli whoami` | Show current login info |
+| `icli --help` | Show help |
+
+---
+
+## What iCli can do
+
+iCli connects to the same AI engine as the in-browser terminal:
+
+- **Fleet-wide checks** — asks about all devices at once with parallel sub-agents  
+- **Live device data** — reads VLAN tables, ONU lists, optical power, ARP, PPPoE sessions  
+- **Customer lookup** — find customers by name, IP, MAC, username, or invoice  
+- **Config audits** — review running config and get concrete suggestions  
+- **Web search** — looks up vendor CLI docs when it needs to  
+- **Streaming output** — answers stream token-by-token with a live thinking indicator  
+
+---
+
+## API endpoints (for integrators)
+
+iCli uses two endpoints added to your IspBills instance:
+
+| Method | URL | Description |
+|---|---|---|
+| `POST` | `/api/v1/auth/login` | Get Bearer token (`username` + `password`) |
+| `POST` | `/api/v1/ai/chat` | Non-streaming JSON response |
+| `POST` | `/api/v1/ai/chat/stream` | SSE stream (`delta` / `reason_delta` / `status_delta` / `done` events) |
+
+**Authentication:** `Authorization: Bearer <token>` on all `/api/v1/ai/*` requests.
+
+**Request body:**
+```json
+{
+  "messages": [
+    { "role": "user", "content": "is vlan 82 in use?" }
+  ],
+  "context": {
+    "vendor": "auto",
+    "connected": false
+  }
+}
+```
+
+**SSE events:**
+```
+data: {"delta": "VLAN 82 is..."}        ← streaming answer tokens
+data: {"reason_delta": "checking..."}   ← AI reasoning (dim, italic)
+data: {"status_delta": "✅ [1/3]..."}   ← sub-agent progress
+data: {"done": true, "result": {...}}   ← final result object
+```
+
+---
+
+## Configuration
+
+Config is stored at `~/.config/ispbills-icli/config.json`:
+
+```json
+{
+  "url": "https://app.myisp.com",
+  "token": "...",
+  "refresh_token": "...",
+  "user": { "id": 1, "name": "Admin", "email": "admin@myisp.com", "role": "group_admin" }
+}
+```
+
+Tokens refresh automatically when they expire.
+
+---
+
+## License
+
+MIT — © IspBills

package/bin/icli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import * as readline from 'readline/promises';
+import { stdin as input, stdout as output, argv, exit } from 'process';
+import chalk from 'chalk';
+import { loadConfig, configPath } from '../src/config.js';
+import { loginFlow } from '../src/auth.js';
+import { streamChat } from '../src/chat.js';
+
+// ─── Parse args ─────────────────────────────────────────────────────────────
+const args = argv.slice(2);
+const cmd  = args[0] ?? '';
+
+// ─── Help ────────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log(`
+${chalk.bold.cyan('iCli')} — IspBills AI network engineer in your terminal
+${chalk.dim('Powered by iCopilot · github.com/lupael/IspBills')}
+
+${chalk.bold('Usage:')}
+  ${chalk.cyan('icli')}                     Interactive chat (REPL)
+  ${chalk.cyan('icli')} ${chalk.yellow('"your question"')}    Single-shot query, then exit
+  ${chalk.cyan('icli login')}               Authenticate (or re-authenticate)
+  ${chalk.cyan('icli whoami')}              Show current login info
+  ${chalk.cyan('icli --help')}              Show this help
+
+${chalk.bold('Examples:')}
+  ${chalk.dim('$')} icli "is vlan 82 in use?"
+  ${chalk.dim('$')} icli "show all ONUs on olt#1"
+  ${chalk.dim('$')} icli "which customer is using IP 192.168.1.50?"
+  ${chalk.dim('$')} icli                        ${chalk.dim('# start interactive REPL')}
+
+${chalk.bold('Config stored at:')}
+  ${chalk.dim(configPath())}
+`);
+}
+
+// ─── Ensure authenticated ────────────────────────────────────────────────────
+async function ensureAuth() {
+  let cfg = loadConfig();
+  if (!cfg) {
+    console.log(chalk.yellow('No saved login found. Let\'s set up iCli.\n'));
+    cfg = await loginFlow();
+    console.log(chalk.green(`\n✓ Logged in as ${cfg.user?.name ?? cfg.user?.email} (${cfg.user?.role ?? 'operator'})`));
+    console.log(chalk.dim(`  Connected to: ${cfg.url}\n`));
+  }
+  return cfg;
+}
+
+// ─── Single-shot query ───────────────────────────────────────────────────────
+async function singleShot(cfg, question) {
+  const messages = [{ role: 'user', content: question }];
+  try {
+    await streamChat(cfg, messages);
+  } catch (e) {
+    console.error(chalk.red('\n✖ ' + e.message));
+    exit(1);
+  }
+}
+
+// ─── Interactive REPL ────────────────────────────────────────────────────────
+async function interactiveRepl(cfg) {
+  const history = [];
+  const rl = readline.createInterface({
+    input, output,
+    prompt: chalk.cyan('iCli') + chalk.dim(' › '),
+  });
+
+  console.log(
+    chalk.bold.cyan('\n  iCli') + chalk.dim(' — IspBills AI terminal\n') +
+    chalk.dim(`  Connected to: ${cfg.url}`) + '\n' +
+    chalk.dim('  Type your question. Press Ctrl+C or type "exit" to quit.\n')
+  );
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const q = line.trim();
+    if (!q) { rl.prompt(); return; }
+    if (q === 'exit' || q === 'quit') { rl.close(); return; }
+    if (q === 'clear') { console.clear(); rl.prompt(); return; }
+    if (q === 'history') {
+      history.forEach((m, i) => {
+        if (m.role === 'user') console.log(chalk.dim(`  ${i}: `) + m.content.slice(0, 80));
+      });
+      rl.prompt();
+      return;
+    }
+
+    rl.pause();
+    history.push({ role: 'user', content: q });
+
+    try {
+      const answer = await streamChat(cfg, [...history]);
+      if (answer) history.push({ role: 'assistant', content: answer });
+    } catch (e) {
+      console.error(chalk.red('\n✖ ' + e.message + '\n'));
+    }
+
+    rl.resume();
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    console.log(chalk.dim('\n  Goodbye.\n'));
+    exit(0);
+  });
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+async function main() {
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    printHelp(); return;
+  }
+
+  if (cmd === 'login') {
+    const cfg = await loginFlow();
+    console.log(chalk.green(`\n✓ Logged in as ${cfg.user?.name ?? cfg.user?.email} (${cfg.user?.role})`));
+    console.log(chalk.dim(`  Config saved to: ${configPath()}\n`));
+    return;
+  }
+
+  if (cmd === 'whoami') {
+    const cfg = loadConfig();
+    if (!cfg) { console.log(chalk.yellow('Not logged in. Run `icli login`.')); return; }
+    console.log(`\n${chalk.bold('URL:')}   ${cfg.url}`);
+    console.log(`${chalk.bold('Name:')}  ${cfg.user?.name ?? '—'}`);
+    console.log(`${chalk.bold('Email:')} ${cfg.user?.email ?? '—'}`);
+    console.log(`${chalk.bold('Role:')}  ${cfg.user?.role ?? '—'}\n`);
+    return;
+  }
+
+  const cfg = await ensureAuth();
+
+  // Single-shot: icli "question here"
+  if (cmd && !cmd.startsWith('-')) {
+    await singleShot(cfg, args.join(' '));
+    return;
+  }
+
+  // Interactive REPL
+  await interactiveRepl(cfg);
+}
+
+main().catch(e => { console.error(chalk.red('✖ ' + e.message)); exit(1); });

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ispbills-icli",
+  "version": "1.0.0",
+  "description": "iCli — IspBills AI network engineer in your terminal",
+  "keywords": ["ispbills", "network", "isp", "ai", "cli", "noc"],
+  "license": "MIT",
+  "bin": {
+    "icli": "./bin/icli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0"
+  }
+}

package/src/auth.js

@@ -0,0 +1,55 @@
+import * as readline from 'readline/promises';
+import { stdin as input, stdout as output } from 'process';
+import { saveConfig } from './config.js';
+
+export async function loginFlow(existingUrl = '') {
+  const rl = readline.createInterface({ input, output });
+
+  console.log('\n🔌 iCli — IspBills AI terminal\n');
+
+  let url = existingUrl;
+  if (!url) {
+    url = (await rl.question('IspBills instance URL (e.g. https://app.myisp.com): ')).trim();
+  }
+  url = url.replace(/\/$/, '');
+
+  const email    = (await rl.question('Email: ')).trim();
+  const password = await rl.question('Password: ');
+
+  rl.close();
+
+  const res = await fetch(`${url}/api/v1/auth/login`, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+    body:    JSON.stringify({ username: email, password }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.message || `Login failed (HTTP ${res.status})`);
+  }
+
+  const data = await res.json();
+  const cfg = {
+    url,
+    token:         data.token,
+    refresh_token: data.refresh_token,
+    user:          data.user,
+  };
+  saveConfig(cfg);
+  return cfg;
+}
+
+export async function refreshToken(cfg) {
+  const res = await fetch(`${cfg.url}/api/v1/auth/refresh`, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+    body:    JSON.stringify({ refresh_token: cfg.refresh_token }),
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  cfg.token         = data.token;
+  cfg.refresh_token = data.refresh_token;
+  saveConfig(cfg);
+  return cfg;
+}

package/src/chat.js

@@ -0,0 +1,181 @@
+import chalk from 'chalk';
+import { refreshToken } from './auth.js';
+
+const SPINNER_FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+
+/**
+ * Stream a single chat turn to stdout.
+ *
+ * @param {object}   cfg       - { url, token, refresh_token, user }
+ * @param {Array}    messages  - [{ role, content }]
+ * @param {object}   [context] - optional device context
+ * @param {object}   [opts]    - { thinking: bool }
+ * @returns {string} The final answer text
+ */
+export async function streamChat(cfg, messages, context = {}, opts = {}) {
+  const showThinking = opts.thinking !== false;
+
+  const body = JSON.stringify({ messages, context });
+
+  let res = await fetch(`${cfg.url}/api/v1/ai/chat/stream`, {
+    method:  'POST',
+    headers: {
+      'Content-Type':  'application/json',
+      'Accept':        'text/event-stream',
+      'Authorization': `Bearer ${cfg.token}`,
+    },
+    body,
+  });
+
+  // Token expired — try refresh once
+  if (res.status === 401 && cfg.refresh_token) {
+    const updated = await refreshToken(cfg);
+    if (!updated) throw new Error('Session expired. Run `icli login` to re-authenticate.');
+    Object.assign(cfg, updated);
+    res = await fetch(`${cfg.url}/api/v1/ai/chat/stream`, {
+      method:  'POST',
+      headers: {
+        'Content-Type':  'application/json',
+        'Accept':        'text/event-stream',
+        'Authorization': `Bearer ${cfg.token}`,
+      },
+      body,
+    });
+  }
+
+  if (!res.ok) {
+    const txt = await res.text().catch(() => '');
+    throw new Error(`AI request failed (HTTP ${res.status}): ${txt.slice(0, 200)}`);
+  }
+
+  // ── Render state ────────────────────────────────────────────────────────
+  let spinTimer    = null;
+  let spinIdx      = 0;
+  let thinkingLine = false;
+  let reasonBuf    = '';
+  let statusBuf    = '';
+  let answerBuf    = '';
+  let lastWasNewline = true;
+
+  function clearSpinner() {
+    if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
+    if (thinkingLine) {
+      process.stdout.write('\r\x1b[K');   // clear the thinking line
+      thinkingLine = false;
+    }
+  }
+
+  function startSpinner() {
+    if (!showThinking) return;
+    thinkingLine = true;
+    spinTimer = setInterval(() => {
+      const f = SPINNER_FRAMES[spinIdx++ % SPINNER_FRAMES.length];
+      process.stdout.write(`\r${chalk.blue(f)} ${chalk.dim('Thinking…')}`);
+    }, 80);
+  }
+
+  function printStatus(line) {
+    clearSpinner();
+    process.stdout.write(chalk.magenta('  › ') + chalk.dim(line) + '\n');
+    lastWasNewline = true;
+    if (showThinking) startSpinner();
+  }
+
+  function printReasoning(delta) {
+    // Reasoning streams as a running line; collapse to a single dim block.
+    reasonBuf += delta;
+  }
+
+  function flushReasoning() {
+    if (!reasonBuf) return;
+    clearSpinner();
+    const lines = reasonBuf.trim().split('\n');
+    process.stdout.write(chalk.dim('  ┆ ' + lines.join('\n  ┆ ')) + '\n');
+    reasonBuf = '';
+    lastWasNewline = true;
+  }
+
+  function parseStreamText(raw) {
+    const m = raw.match(/"text"\s*:\s*"((?:[^"\\]|\\.)*)$/);
+    if (!m) return raw.trimStart().startsWith('{') ? null : raw;
+    return m[1]
+      .replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+      .replace(/\\r/g, '').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+
+  // ── SSE reader ───────────────────────────────────────────────────────────
+  if (showThinking) startSpinner();
+
+  const decoder = new TextDecoder();
+  let sseBuffer = '';
+  let finalResult = null;
+  let rawAnswer  = '';
+
+  for await (const chunk of res.body) {
+    sseBuffer += decoder.decode(chunk, { stream: true });
+    const lines = sseBuffer.split('\n');
+    sseBuffer = lines.pop();          // keep incomplete line in buffer
+
+    for (const line of lines) {
+      const trimmed = line.replace(/\r$/, '');
+      if (!trimmed.startsWith('data: ')) continue;
+      let ev;
+      try { ev = JSON.parse(trimmed.slice(6)); } catch { continue; }
+
+      if (ev.status_delta !== undefined) {
+        printStatus(ev.status_delta);
+
+      } else if (ev.reason_delta !== undefined) {
+        printReasoning(ev.reason_delta);
+
+      } else if (ev.delta !== undefined) {
+        rawAnswer += ev.delta;
+        const txt = parseStreamText(rawAnswer);
+        if (txt !== null) answerBuf = txt;
+
+      } else if (ev.done) {
+        finalResult = ev.result;
+      }
+    }
+  }
+
+  // ── Final render ─────────────────────────────────────────────────────────
+  clearSpinner();
+  flushReasoning();
+
+  const reply   = finalResult?.reply  ?? {};
+  const replyType = reply.type ?? 'message';
+
+  if (replyType === 'message') {
+    const text = reply.text || answerBuf || '(no response)';
+    if (!lastWasNewline) process.stdout.write('\n');
+    process.stdout.write('\n' + chalk.white(text) + '\n\n');
+    return text;
+
+  } else if (replyType === 'plan') {
+    process.stdout.write('\n');
+    process.stdout.write(chalk.bold.cyan('📋 Plan: ') + chalk.cyan(reply.summary || '') + '\n');
+    (reply.steps || []).forEach((step, i) => {
+      const risk = step.risk === 'high' ? chalk.red(' ⚠ high') : '';
+      process.stdout.write(
+        `  ${chalk.dim(String(i + 1) + '.')} ${chalk.yellow(step.cmd || '')}${risk}\n`
+      );
+      if (step.purpose) process.stdout.write(chalk.dim(`     ${step.purpose}\n`));
+    });
+    process.stdout.write('\n');
+    return reply.summary || '';
+
+  } else if (replyType === 'connect') {
+    const dev = reply.device ?? {};
+    process.stdout.write('\n');
+    process.stdout.write(
+      chalk.bold.green('🔌 Connect: ') +
+      chalk.green(`${dev.kind ?? '?'}#${dev.id ?? '?'} ${dev.name ?? ''} (${dev.host ?? ''})`) + '\n'
+    );
+    if (reply.note) process.stdout.write(chalk.dim('   ' + reply.note) + '\n');
+    process.stdout.write('\n');
+    return reply.note || '';
+  }
+
+  return answerBuf;
+}

package/src/config.js

@@ -0,0 +1,23 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_DIR  = join(homedir(), '.config', 'ispbills-icli');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+export function configPath() {
+  return CONFIG_FILE;
+}