unbound-cli 0.5.0 → 0.6.0

package/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/LOCAL_DEV.md

@@ -43,6 +43,51 @@ node src/index.js config reset-url
 node src/index.js config reset-frontend-url
 ```
 
+## Point setup scripts to a local backend / frontend
+
+The `setup`, `setup mdm`, `onboard`, and `onboard-mdm` commands invoke Python setup scripts from the `setup` repo. Those scripts:
+
+- Ping `https://backend.getunbound.ai/api/v1/setup/complete/` when a tool is configured (override with `--backend-url`).
+- Use the frontend URL for the browser-auth callback if `--api-key` is not already stored (override with `--frontend-url`, passed through to the scripts as `--domain`).
+
+Both flags are hidden from `--help` (dev-only) and work on every setup-invoking command:
+
+```bash
+# Single tool — override backend only, or both
+node src/index.js setup cursor --backend-url http://localhost:8000
+node src/index.js setup cursor --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+node src/index.js setup claude-code --gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Default bundle
+node src/index.js setup --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# With --api-key, the CLI verifies the key against its own base URL before running the setup scripts,
+# so you must ALSO set UNBOUND_API_URL (or `config set-url`) or auth will hit prod and fail with 401.
+UNBOUND_API_URL=http://localhost:8000 node src/index.js setup --all --api-key <key> --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Multiple explicit tools
+node src/index.js setup cursor claude-code-gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Interactive mode (select tools, then apply overrides to all selected)
+node src/index.js setup --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# MDM (requires sudo; MDM scripts ignore --frontend-url since they don't use browser auth)
+sudo node src/index.js setup mdm --admin-api-key <ADMIN_KEY> --all --backend-url http://localhost:8000
+
+# Onboarding (combined setup + discover)
+node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> \
+    --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+sudo node src/index.js onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> \
+    --backend-url http://localhost:8000
+```
+
+When omitted, scripts default to `https://backend.getunbound.ai` and the stored frontend URL (or `https://gateway.getunbound.ai`).
+
+Notes:
+- `--backend-url` / `--frontend-url` only affect the setup scripts. They do not change the CLI's own API calls (use `config set-url` / `UNBOUND_API_URL` / `config set-frontend-url` / `UNBOUND_FRONTEND_URL` for that).
+- `onboard` and `onboard-mdm` also take a visible `--domain <url>` flag — that one is for the **discovery** backend (a separate repo), not the setup scripts' frontend. The two flags don't conflict.
+- MDM setup scripts (`setup mdm`, `onboard-mdm`) don't do browser auth, so `--frontend-url` is a no-op there; only `--backend-url` is meaningful.
+
 ## Verify config
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node src/index.js",
     "lint": "eslint src/",
-    "test": "node --test test/"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "unbound",

package/src/chartRender.js

@@ -0,0 +1,284 @@
+/**
+ * Render ECharts-style chart specs as ASCII for the terminal, and reconstruct
+ * tabular rows from a chart_option payload (the backend never returns rows
+ * separately — they live inside chart_option as xAxis.data + series[].data,
+ * series[].data of {name,value}, or dataset.source).
+ *
+ * Pure functions so they can be unit-tested without TTY mocking.
+ */
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = {
+  cyan: (s) => useColor ? `\x1b[36m${s}\x1b[0m` : s,
+  green: (s) => useColor ? `\x1b[32m${s}\x1b[0m` : s,
+  yellow: (s) => useColor ? `\x1b[33m${s}\x1b[0m` : s,
+  red: (s) => useColor ? `\x1b[31m${s}\x1b[0m` : s,
+  dim: (s) => useColor ? `\x1b[2m${s}\x1b[0m` : s,
+  bold: (s) => useColor ? `\x1b[1m${s}\x1b[0m` : s,
+};
+const SERIES_COLORS = [c.cyan, c.green, c.yellow, c.red];
+const MAX_RENDER_ROWS = 20;
+// Upper bound on how many data points we'll materialize from a chart_option,
+// regardless of what the backend returns. Guards against OOM from pathological
+// or hostile payloads. MAX_RENDER_ROWS is a subset of this for display only.
+const MAX_RECONSTRUCT_ROWS = 10000;
+
+// Strip terminal control sequences and C0/C1 control characters from backend-
+// sourced strings before printing. Prevents a hostile/compromised backend from
+// hijacking the user's terminal via ANSI CSI, OSC (title, clipboard, hyperlinks),
+// DCS, APC, or PM sequences. Callers should pipe every backend-origin string
+// through this before echoing.
+function sanitizeForTerminal(value) {
+  if (value === null || value === undefined) return '';
+  let s = typeof value === 'string' ? value : String(value);
+  // Strip OSC (\x1b]...\x07 or \x1b]...\x1b\\), DCS/APC/PM/SOS (\x1bP|X|_|^...\x1b\\).
+  s = s.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+  s = s.replace(/\x1b[PX_^][^\x1b]*\x1b\\/g, '');
+  // Strip CSI and other ESC-prefixed sequences.
+  s = s.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  s = s.replace(/\x1b[@-Z\\-_]/g, '');
+  // Strip 8-bit C1 control bytes (\x80-\x9f) — in 8-bit terminals \x9b means
+  // CSI, \x9d means OSC, \x90 means DCS, etc. Modern UTF-8 terminals mostly
+  // ignore these, but strip them so the sanitizer's guarantee is complete.
+  s = s.replace(/[\x80-\x9f]/g, '');
+  // Strip remaining C0 control chars except tab (\t); drop backspace, CR, LF,
+  // vertical tab, form feed, and the rest. Newlines in assistant messages are
+  // converted to spaces to preserve flow without breaking line-based layout.
+  s = s.replace(/[\r\n]+/g, ' ');
+  s = s.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+  return s;
+}
+
+function asArray(x) {
+  if (x === undefined || x === null) return [];
+  return Array.isArray(x) ? x : [x];
+}
+
+function pickXAxisData(chart_option) {
+  const axes = asArray(chart_option?.xAxis);
+  for (const a of axes) {
+    if (Array.isArray(a?.data)) return a.data;
+  }
+  return null;
+}
+
+function formatNumber(v) {
+  if (typeof v !== 'number' || !isFinite(v)) return String(v ?? '');
+  if (Number.isInteger(v)) return v.toLocaleString('en-US');
+  return v.toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+/**
+ * Reconstruct {columns, rows} from a chart_option + chart_meta.
+ * Defensive — returns {columns: [], rows: []} if nothing usable.
+ */
+function reconstructRows(chart_option, chart_meta) {
+  if (!chart_option || typeof chart_option !== 'object') {
+    return { columns: [], rows: [] };
+  }
+
+  const sanitizeLabel = (v) => {
+    if (typeof v === 'number' || typeof v === 'boolean') return v;
+    return sanitizeForTerminal(v);
+  };
+
+  // 1) dataset.source — preferred when present
+  const source = chart_option.dataset?.source;
+  if (Array.isArray(source) && source.length > 0) {
+    const cappedSource = source.slice(0, MAX_RECONSTRUCT_ROWS + 1);
+    if (Array.isArray(cappedSource[0])) {
+      const [header, ...body] = cappedSource;
+      const columns = header.map((h) => sanitizeForTerminal(String(h)));
+      const rows = body.map((r) => Object.fromEntries(columns.map((k, i) => [k, sanitizeLabel(r[i])])));
+      return { columns, rows };
+    }
+    if (typeof cappedSource[0] === 'object' && cappedSource[0] !== null) {
+      const columns = Object.keys(cappedSource[0]).map((k) => sanitizeForTerminal(k));
+      // Object-shape has no header row so re-cap to MAX_RECONSTRUCT_ROWS.
+      const rows = cappedSource.slice(0, MAX_RECONSTRUCT_ROWS)
+        .map((r) => Object.fromEntries(columns.map((k) => [k, sanitizeLabel(r[k])])));
+      return { columns, rows };
+    }
+  }
+
+  const series = asArray(chart_option.series).filter(Boolean);
+  const xData = pickXAxisData(chart_option);
+  const xKey = sanitizeForTerminal(chart_meta?.x || 'category');
+  const yKeys = asArray(chart_meta?.y).map((y) => sanitizeForTerminal(String(y)));
+
+  // 2) Pie / donut — series[0].data is [{name, value}, ...]
+  const pieSeries = series.find((s) => Array.isArray(s.data) && s.data.length > 0
+    && typeof s.data[0] === 'object' && s.data[0] !== null
+    && 'value' in s.data[0]);
+  if (pieSeries && !xData) {
+    const valueKey = yKeys[0] || 'value';
+    const nameKey = xKey || 'name';
+    const columns = [nameKey, valueKey];
+    const cappedPie = pieSeries.data.slice(0, MAX_RECONSTRUCT_ROWS);
+    const rows = cappedPie.map((d) => ({
+      [nameKey]: sanitizeLabel(d.name ?? ''),
+      [valueKey]: d.value,
+    }));
+    return { columns, rows };
+  }
+
+  // 3) Cartesian — xAxis.data + parallel series[i].data arrays
+  if (xData && series.length > 0) {
+    const seriesNames = series.map((s, i) => sanitizeForTerminal(s.name || yKeys[i] || `series_${i + 1}`));
+    const columns = [xKey, ...seriesNames];
+    const cappedX = xData.slice(0, MAX_RECONSTRUCT_ROWS);
+    const rows = cappedX.map((label, i) => {
+      const row = { [xKey]: sanitizeLabel(label) };
+      series.forEach((s, j) => {
+        const v = Array.isArray(s.data) ? s.data[i] : undefined;
+        row[seriesNames[j]] = (v && typeof v === 'object' && 'value' in v) ? v.value : v;
+      });
+      return row;
+    });
+    return { columns, rows };
+  }
+
+  // 4) KPI / single number — series[0].data[0]
+  const flat = series.find((s) => Array.isArray(s.data) && s.data.length === 1
+    && (typeof s.data[0] === 'number' || typeof s.data[0] === 'string'));
+  if (flat) {
+    const valueKey = yKeys[0] || sanitizeForTerminal(flat.name || 'value');
+    return { columns: [valueKey], rows: [{ [valueKey]: sanitizeLabel(flat.data[0]) }] };
+  }
+
+  return { columns: [], rows: [] };
+}
+
+/**
+ * One-line summary, e.g. "Bar chart, x=provider, y=cost, 4 rows".
+ */
+function summarizeChart(chart_meta, row_count) {
+  const t = chart_meta?.chart_type ? String(chart_meta.chart_type) : 'unknown';
+  const cap = t.charAt(0).toUpperCase() + t.slice(1);
+  const parts = [`${cap} chart`];
+  if (chart_meta?.x) parts.push(`x=${chart_meta.x}`);
+  const ys = asArray(chart_meta?.y);
+  if (ys.length) parts.push(`y=${ys.join('+')}`);
+  if (typeof row_count === 'number') parts.push(`${row_count} row${row_count === 1 ? '' : 's'}`);
+  return parts.join(', ');
+}
+
+/**
+ * Render an ASCII bar chart for the given rows. Single-series only (use
+ * renderGroupedBarChart for multi-series). Returns the rendered string;
+ * caller decides where to print.
+ *
+ * @param {Array<object>} rows
+ * @param {string} xKey
+ * @param {string} yKey
+ * @param {{width?: number, color?: (s:string)=>string}} [opts]
+ */
+function renderBarChart(rows, xKey, yKey, opts = {}) {
+  if (!rows?.length) return '';
+  const width = clampWidth(opts.width);
+  const color = opts.color || c.cyan;
+
+  const labels = rows.map((r) => String(r[xKey] ?? ''));
+  const values = rows.map((r) => Number(r[yKey] ?? 0));
+  const max = Math.max(...values.map((v) => isFinite(v) ? Math.abs(v) : 0));
+
+  const labelWidth = Math.min(24, Math.max(...labels.map((l) => l.length), 1));
+  const truncatedLabels = labels.map((l) => l.length > labelWidth ? l.slice(0, labelWidth - 1) + '\u2026' : l);
+  const valueStrs = values.map(formatNumber);
+  const valueWidth = Math.max(...valueStrs.map((s) => s.length), 1);
+  // Line layout: "  " + label(W) + "  " + bar + "  " + value(W) = 6 padding chars + label + bar + value.
+  const barArea = Math.max(4, width - labelWidth - valueWidth - 6);
+
+  const lines = [];
+  for (let i = 0; i < rows.length; i++) {
+    const v = values[i];
+    const len = max > 0 && isFinite(v) ? Math.max(1, Math.round(Math.abs(v) / max * barArea)) : 0;
+    const bar = '\u2588'.repeat(len);
+    lines.push(
+      `  ${c.dim(truncatedLabels[i].padEnd(labelWidth))}  ${color(bar)}${' '.repeat(barArea - len)}  ${c.bold(valueStrs[i])}`
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render a multi-series grouped bar chart by stacking series under each label.
+ */
+function renderGroupedBarChart(rows, xKey, yKeys, opts = {}) {
+  if (!rows?.length || !yKeys?.length) return '';
+  if (yKeys.length === 1) return renderBarChart(rows, xKey, yKeys[0], opts);
+
+  const width = clampWidth(opts.width);
+  const labels = rows.map((r) => String(r[xKey] ?? ''));
+  const labelWidth = Math.min(24, Math.max(...labels.map((l) => l.length), 1));
+  const allValues = rows.flatMap((r) => yKeys.map((k) => Number(r[k] ?? 0)));
+  const max = Math.max(...allValues.map((v) => isFinite(v) ? Math.abs(v) : 0));
+
+  // Build per-series strings to compute valueWidth uniformly.
+  const valueWidth = Math.max(
+    ...rows.flatMap((r) => yKeys.map((k) => formatNumber(Number(r[k] ?? 0)).length)),
+    1
+  );
+  const seriesLabelWidth = Math.max(...yKeys.map((k) => k.length), 1);
+  // Per-series line: "    " + seriesLabel(W) + "  " + bar + "  " + value(W) = 8 padding chars + label + bar + value.
+  const barArea = Math.max(4, width - seriesLabelWidth - valueWidth - 8);
+
+  const legend = '  ' + c.dim('Legend: ') + yKeys.map((k, i) => SERIES_COLORS[i % SERIES_COLORS.length]('\u2588') + ' ' + k).join('  ');
+  const blocks = [legend];
+  for (let i = 0; i < rows.length; i++) {
+    const truncated = labels[i].length > labelWidth ? labels[i].slice(0, labelWidth - 1) + '\u2026' : labels[i];
+    blocks.push('  ' + c.bold(truncated));
+    for (let j = 0; j < yKeys.length; j++) {
+      const v = Number(rows[i][yKeys[j]] ?? 0);
+      const len = max > 0 && isFinite(v) ? Math.max(1, Math.round(Math.abs(v) / max * barArea)) : 0;
+      const color = SERIES_COLORS[j % SERIES_COLORS.length];
+      blocks.push(
+        `    ${c.dim(yKeys[j].padEnd(seriesLabelWidth))}  ${color('\u2588'.repeat(len))}${' '.repeat(barArea - len)}  ${c.bold(formatNumber(v).padStart(valueWidth))}`
+      );
+    }
+  }
+  return blocks.join('\n');
+}
+
+/**
+ * One-line braille sparkline for a numeric series.
+ */
+function renderSparkline(values, opts = {}) {
+  const nums = values.filter((v) => typeof v === 'number' && isFinite(v));
+  if (nums.length < 2) return '';
+  const width = Math.min(opts.width || clampWidth(), nums.length);
+  const min = Math.min(...nums);
+  const max = Math.max(...nums);
+  const span = max - min || 1;
+  // Sample/bucket if more values than width.
+  const buckets = [];
+  for (let i = 0; i < width; i++) {
+    const start = Math.floor(i * nums.length / width);
+    const end = Math.max(start + 1, Math.floor((i + 1) * nums.length / width));
+    const slice = nums.slice(start, end);
+    buckets.push(slice.reduce((a, b) => a + b, 0) / slice.length);
+  }
+  const chars = ['\u2581', '\u2582', '\u2583', '\u2584', '\u2585', '\u2586', '\u2587', '\u2588'];
+  const rendered = buckets.map((v) => {
+    const idx = Math.round((v - min) / span * (chars.length - 1));
+    return chars[Math.max(0, Math.min(chars.length - 1, idx))];
+  }).join('');
+  return `  ${c.dim(formatNumber(min))} ${c.cyan(rendered)} ${c.dim(formatNumber(max))}`;
+}
+
+function clampWidth(w) {
+  const cols = w ?? process.stdout.columns ?? 80;
+  return Math.max(40, Math.min(cols, 120));
+}
+
+module.exports = {
+  reconstructRows,
+  renderBarChart,
+  renderGroupedBarChart,
+  renderSparkline,
+  summarizeChart,
+  formatNumber,
+  sanitizeForTerminal,
+  MAX_RENDER_ROWS,
+  MAX_RECONSTRUCT_ROWS,
+};