unbound-cli 0.5.0 → 0.6.0

package/src/commands/chat.js

@@ -0,0 +1,531 @@
+/**
+ * `unbound chat` — interactive session or one-shot wrapper around
+ * POST /api/v1/query_builder/chat/. Conversation history lives in memory
+ * only; nothing is written to disk. In one-shot mode (-m), `--json` writes
+ * the response to stdout and `-o <path>` writes it to a file.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline/promises');
+
+const api = require('../api');
+const output = require('../output');
+const { ensureLoggedIn } = require('../auth');
+const chart = require('../chartRender');
+const { sanitizeForTerminal } = chart;
+
+const ENDPOINT = '/api/v1/query_builder/chat/';
+const HISTORY_CAP = 20;
+const RECENT_RESULTS_CAP = 5;
+const MAX_MESSAGE_LEN = 4000;
+const MAX_TURN_CONTENT_LEN = 8000;
+const ALLOWED_ROLES = new Set(['user', 'assistant']);
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => useColor ? `\x1b[2m${s}\x1b[0m` : s;
+const bold = (s) => useColor ? `\x1b[1m${s}\x1b[0m` : s;
+const cyan = (s) => useColor ? `\x1b[36m${s}\x1b[0m` : s;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+// Expand a leading `~/` to the user's home directory. Does NOT expand `~user/`
+// (uncommon, not worth parsing). Returns an absolute path.
+function expandPath(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return path.resolve(p);
+}
+
+// Write `data` to `target` without following symlinks and without overwriting
+// an existing file. Creates the file with mode 0o600 so org analytics don't
+// leak on multi-user hosts. Returns the resolved absolute path on success.
+function safeWriteFile(target, data) {
+  if (target === undefined || target === null || target === '') {
+    throw new Error('Output path is empty.');
+  }
+  if (typeof target !== 'string') {
+    throw new Error('Output path must be a string.');
+  }
+  if (target.includes('\0')) {
+    throw new Error('Output path contains an invalid character (NUL).');
+  }
+  const resolved = expandPath(target);
+  try {
+    const stat = fs.lstatSync(resolved);
+    if (stat.isDirectory()) {
+      throw new Error(`Refusing to write: '${resolved}' is a directory.`);
+    }
+    throw new Error(`Refusing to overwrite existing file: '${resolved}'. Choose a new path or remove it first.`);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const fd = fs.openSync(
+    resolved,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    fs.writeFileSync(fd, data);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return resolved;
+}
+
+function buildBody(message, history, recent) {
+  return {
+    message,
+    conversation_history: history.slice(-HISTORY_CAP),
+    recent_results: recent.slice(-RECENT_RESULTS_CAP),
+  };
+}
+
+function pushRecent(recent, query, result) {
+  recent.push({
+    query,
+    view_spec: result.view_spec,
+    result_summary: {
+      row_count: result.row_count,
+      chart_type: result.chart_meta?.chart_type,
+    },
+  });
+  while (recent.length > RECENT_RESULTS_CAP) recent.shift();
+}
+
+function pushHistory(history, turn) {
+  history.push(turn);
+  while (history.length > HISTORY_CAP) history.shift();
+}
+
+// Turn text/field from a backend response is untrusted — normalize it before
+// pushing into conversation_history (which we echo on the wire next turn and
+// may print inside /json). Reject unknown roles to prevent a hostile backend
+// from injecting fake `system` turns that amplify prompt-injection attacks.
+function normalizeAssistantTurn(turn) {
+  if (!turn || typeof turn !== 'object') return null;
+  const role = typeof turn.role === 'string' ? turn.role.toLowerCase() : '';
+  if (!ALLOWED_ROLES.has(role)) return null;
+  const content = typeof turn.content === 'string' ? turn.content.slice(0, MAX_TURN_CONTENT_LEN) : '';
+  const timestamp = typeof turn.timestamp === 'string' ? turn.timestamp : nowIso();
+  return { role, content, timestamp };
+}
+
+// Map an error from a chat-endpoint call into a human-readable hint. Keep
+// backend-supplied strings out of the shell line so copy-pastes stay safe.
+function friendlyChatError(err) {
+  if (err?.statusCode === 401) return 'Not authenticated. Run `unbound login` and try again.';
+  if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound whoami` to check yours.';
+  if (err?.statusCode === 429) return 'Rate limited. Please wait a moment and try again.';
+  return sanitizeForTerminal(err?.message || 'Request failed.');
+}
+
+function renderSuggestionsForHuman(suggestions) {
+  if (!suggestions?.length) return;
+  console.log('');
+  output.info('Suggested follow-ups (rerun `unbound chat -m "<your question>"` with one of these):');
+  suggestions.forEach((s, i) => {
+    const label = sanitizeForTerminal(s.label || `Suggestion ${i + 1}`);
+    const query = sanitizeForTerminal(s.query || '');
+    const desc = sanitizeForTerminal(s.description || '');
+    console.log(`  ${i + 1}. ${bold(label)}`);
+    if (query) console.log(`     ${query}`);
+    if (desc) console.log(`     ${dim(desc)}`);
+  });
+}
+
+/**
+ * Print the assistant message + (if a chart) a one-line summary and a chart
+ * body. Suggestions are NOT printed here — caller decides (REPL picker vs
+ * one-shot numbered list).
+ */
+function renderResponse(resp) {
+  const intent = resp?.intent;
+  const message = sanitizeForTerminal(resp?.message || '');
+
+  if (intent === 'invalid') {
+    output.error(message || 'The request could not be processed.');
+    return;
+  }
+
+  if (intent === 'conversational' || !resp.result) {
+    if (message) console.log(cyan('\u25cf ') + message);
+    return;
+  }
+
+  if (message) console.log(cyan('\u25cf ') + message);
+  const result = resp.result;
+  const summary = sanitizeForTerminal(chart.summarizeChart(result.chart_meta, result.row_count));
+  console.log(dim('  ' + summary));
+
+  const { columns, rows } = chart.reconstructRows(result.chart_option, result.chart_meta);
+  if (!rows.length) {
+    console.log(dim('  (no rows to render)'));
+    return;
+  }
+
+  console.log('');
+  const cap = chart.MAX_RENDER_ROWS;
+  const renderRows = rows.slice(0, cap);
+  const chartType = result.chart_meta?.chart_type;
+  const cols = process.stdout.columns || 80;
+  const tableCols = columns.map((k) => ({ key: k, header: k }));
+
+  if (cols < 40) {
+    output.table(renderRows, tableCols);
+  } else if (chartType === 'bar' && columns.length >= 2) {
+    const xKey = columns[0];
+    const yKeys = columns.slice(1);
+    const body = yKeys.length === 1
+      ? chart.renderBarChart(renderRows, xKey, yKeys[0])
+      : chart.renderGroupedBarChart(renderRows, xKey, yKeys);
+    if (body) console.log(body); else output.table(renderRows, tableCols);
+  } else if (chartType === 'line' && columns.length >= 2) {
+    const yKey = columns[1];
+    const series = renderRows.map((r) => Number(r[yKey] ?? 0));
+    const spark = chart.renderSparkline(series);
+    if (spark) console.log(spark);
+    output.table(renderRows, tableCols);
+  } else {
+    output.table(renderRows, tableCols);
+  }
+
+  if (rows.length > cap) {
+    console.log(dim(`  \u2026 ${rows.length - cap} more row${rows.length - cap === 1 ? '' : 's'} hidden. Use --json or -o for full data.`));
+  }
+}
+
+async function runOneShot({ message, json, outputPath }) {
+  const body = buildBody(message, [], []);
+
+  if (json || outputPath) {
+    let resp;
+    try {
+      resp = await api.post(ENDPOINT, { body });
+    } catch (err) {
+      output.error(friendlyChatError(err));
+      process.exitCode = 1;
+      return;
+    }
+    const serialized = JSON.stringify(resp, null, 2) + '\n';
+    // Write to stdout first (when requested) so a downstream `-o` write failure
+    // doesn't eat the response when both flags are combined.
+    if (json) {
+      process.stdout.write(serialized);
+    }
+    if (outputPath) {
+      try {
+        const resolved = safeWriteFile(outputPath, serialized);
+        output.success(`Wrote ${resolved}`);
+      } catch (err) {
+        output.error(sanitizeForTerminal(err.message));
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (resp?.intent === 'invalid') process.exitCode = 1;
+    return;
+  }
+
+  const spin = output.spinner('Thinking...');
+  let resp;
+  try {
+    resp = await api.post(ENDPOINT, { body });
+    spin.stop();
+  } catch (err) {
+    spin.fail(friendlyChatError(err));
+    process.exitCode = 1;
+    return;
+  }
+
+  renderResponse(resp);
+  renderSuggestionsForHuman(resp?.suggestions);
+  if (resp?.intent === 'invalid') process.exitCode = 1;
+}
+
+function printBanner() {
+  console.log(bold('unbound chat') + dim('  — ask questions about your usage data'));
+  console.log(dim('Type a question, or /help for commands. /exit (or Ctrl+C) to quit.'));
+  console.log('');
+}
+
+function printReplHelp() {
+  const lines = [
+    '  /help              show this help',
+    '  /json              print the last result as JSON to stdout',
+    '  /export <path>     write the last result to a new JSON file',
+    '                     (refuses to overwrite; supports ~/ expansion; mode 0600)',
+    '  /clear             reset the conversation in memory',
+    '  /exit              quit (Ctrl+C also works)',
+  ];
+  console.log(lines.join('\n'));
+}
+
+function handleSlash(line, state) {
+  const trimmed = line.trim();
+  const spaceIdx = trimmed.search(/\s/);
+  const cmd = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+  const argStr = spaceIdx === -1 ? '' : trimmed.slice(spaceIdx + 1).trim();
+  switch (cmd) {
+    case '/exit':
+    case '/quit':
+      return 'exit';
+    case '/help':
+      printReplHelp();
+      return 'continue';
+    case '/clear':
+      state.history.length = 0;
+      state.recent.length = 0;
+      state.lastResult = null;
+      output.success('Conversation cleared.');
+      return 'continue';
+    case '/json':
+      if (state.lastResult) console.log(JSON.stringify(state.lastResult, null, 2));
+      else console.log(dim('(no result yet)'));
+      return 'continue';
+    case '/export': {
+      if (!state.lastResult) { output.error('No result to export yet. Ask a question first.'); return 'continue'; }
+      if (!argStr) { output.error('Usage: /export <path>'); return 'continue'; }
+      try {
+        const resolved = safeWriteFile(argStr, JSON.stringify(state.lastResult, null, 2) + '\n');
+        output.success(`Wrote ${resolved}`);
+      } catch (err) {
+        output.error(sanitizeForTerminal(err.message));
+      }
+      return 'continue';
+    }
+    default:
+      output.warn(`Unknown command: ${sanitizeForTerminal(cmd)}. Type /help for the list.`);
+      return 'continue';
+  }
+}
+
+async function runRepl({ noSuggestions }) {
+  const state = { history: [], recent: [], lastResult: null };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  const setClosed = () => { closed = true; };
+  rl.on('SIGINT', () => { closed = true; rl.close(); });
+  rl.on('close', setClosed);
+
+  printBanner();
+  let pending = null;
+
+  while (!closed) {
+    let msg;
+    if (pending) {
+      msg = pending;
+      pending = null;
+      console.log(`${bold('chat>')} ${dim('(picked) ') + sanitizeForTerminal(msg)}`);
+    } else {
+      try {
+        msg = await rl.question(`${bold('chat>')} `);
+      } catch {
+        break;
+      }
+    }
+    if (closed) break;
+    msg = (msg || '').trim();
+    if (!msg) continue;
+    if (msg.length > MAX_MESSAGE_LEN) {
+      output.warn(`Message truncated to ${MAX_MESSAGE_LEN} characters.`);
+      msg = msg.slice(0, MAX_MESSAGE_LEN);
+    }
+
+    if (msg.startsWith('/')) {
+      const action = handleSlash(msg, state);
+      if (action === 'exit') break;
+      continue;
+    }
+
+    // Build the request body BEFORE pushing the current turn into history —
+    // otherwise `message` and the last entry of `conversation_history` would
+    // both contain the same user text, making the backend process it twice.
+    const body = buildBody(msg, state.history, state.recent);
+
+    const spin = output.spinner('Thinking...');
+    let resp;
+    try {
+      resp = await api.post(ENDPOINT, { body });
+      spin.stop();
+    } catch (err) {
+      spin.fail(friendlyChatError(err));
+      if (err?.statusCode === 401 || err?.statusCode === 403) break;
+      continue;
+    }
+
+    // Record the user turn only after a successful round-trip so history stays
+    // consistent with the server view.
+    pushHistory(state.history, { role: 'user', content: msg, timestamp: nowIso() });
+
+    const assistantTurn = normalizeAssistantTurn(resp?.turn);
+    if (assistantTurn) pushHistory(state.history, assistantTurn);
+    if (resp?.result) {
+      pushRecent(state.recent, msg, resp.result);
+      state.lastResult = resp.result;
+    }
+
+    renderResponse(resp);
+
+    const suggestions = Array.isArray(resp?.suggestions) ? resp.suggestions : [];
+    if (suggestions.length && !noSuggestions && process.stdin.isTTY && process.stdout.isTTY) {
+      const pickOptions = [
+        ...suggestions.map((s, i) => ({
+          label: sanitizeForTerminal(s.label || `Suggestion ${i + 1}`)
+            + (s.description ? ' ' + dim('— ' + sanitizeForTerminal(s.description)) : ''),
+          value: sanitizeForTerminal(s.query || ''),
+        })).filter((o) => o.value),
+        { label: dim('(type your own)'), value: null },
+        { label: dim('(exit)'), value: '__exit__' },
+      ];
+      let pick;
+      try {
+        rl.pause();
+        pick = await output.select('Follow up?', pickOptions);
+      } catch {
+        pick = null;
+      } finally {
+        rl.resume();
+      }
+      if (pick === '__exit__') break;
+      if (pick) pending = pick;
+    } else if (suggestions.length && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+      renderSuggestionsForHuman(suggestions);
+    }
+  }
+
+  rl.close();
+  console.log('');
+}
+
+function register(program) {
+  program
+    .command('chat')
+    .description('Chat with your usage data. Opens an interactive session by default; use -m for one-shot.')
+    .option('-m, --message <text>', 'Ask a single question and exit (no interactive session).')
+    .option('--json', 'Write the raw JSON response to stdout. Use with -m.')
+    .option('-o, --output <path>', 'Write the raw JSON response to a file. Refuses to overwrite. Use with -m.')
+    .option('--no-suggestions', 'Skip the follow-up picker after each turn (interactive session only).')
+    .addHelpText('after', `
+EXAMPLES
+  Start an interactive session:
+    $ unbound chat
+
+  Ask a single question and render a chart in the terminal:
+    $ unbound chat -m "show cost by provider for the last 30 days"
+
+  Write the raw JSON response to stdout (pipe to jq, a script, or another tool):
+    $ unbound chat -m "cost by provider last 30 days" --json
+    $ unbound chat -m "cost by provider last 30 days" --json | jq '.intent'
+    $ unbound chat -m "cost by provider last 30 days" --json | jq '.result.chart_option'
+
+  Write the raw JSON response to a file:
+    $ unbound chat -m "cost by provider last 30 days" -o cost.json
+
+  Combine --json and -o to pipe and archive at the same time:
+    $ unbound chat -m "cost by provider last 30 days" --json -o cost.json | jq '.intent'
+
+OUTPUT FORMAT (--json and -o)
+  { message, intent, result?, suggestions?, turn }
+
+  intent: "sql_visualise" | "conversational" | "invalid"
+    sql_visualise  — a chart was generated; 'result' is populated.
+    conversational — the model wants clarification; pick a suggestions[i].query and re-run.
+    invalid        — the prompt could not be answered; exit code is 1.
+
+  result (only when intent == "sql_visualise"):
+    columns      string[]             left-to-right column names
+    row_count    number               total rows in the answer
+    chart_meta   { chart_type, x, y } chart_type is one of:
+                                        "bar" | "line" | "donut" | "pie"
+                                      | "kpi" | "scatter" | "table"
+    chart_option ECharts config with the data embedded.
+
+  suggestions (may be present with any intent):
+    [{ label, query, description }]
+    Each entry's 'query' is the exact text for a follow-up '-m "<query>"' call.
+
+  turn: { role, content, timestamp } — the assistant's turn record.
+
+DATA EXTRACTION (rows are embedded in chart_option; no separate rows field)
+  bar, line        chart_option.xAxis.data         (category labels, ordered)
+                   chart_option.series[i].data     (values, parallel to xAxis.data)
+  donut, pie       chart_option.series[0].data     ([{name, value}, ...])
+  scatter          chart_option.series[0].data     ([[x, y], ...])
+                   or chart_option.dataset.source
+  table            chart_option.dataset.source     (first row is the header)
+  kpi              chart_option.series[0].data[0]  (a single number; no axes)
+
+EXIT CODES
+  0  success
+  1  intent=="invalid", auth/role/network failure, or a write error
+
+INTERACTIVE SESSION
+  $ unbound chat                             start the session
+  $ unbound chat --no-suggestions            skip the follow-up picker
+
+  Commands (type inside the session):
+    /help              show these commands
+    /json              print the last result as JSON
+    /export <path>     write the last result to a file (refuses to overwrite;
+                       supports ~/ expansion; file mode is 0600)
+    /clear             reset the conversation in memory
+    /exit              quit (Ctrl+C also works)
+
+NOTES
+  * Requires Admin or Manager role in your organization. Run 'unbound whoami' to check.
+  * Conversation history is held in memory only; nothing is ever written to disk.
+  * Each -m invocation sends no history; keep each prompt self-contained.
+  * -o writes a new file with mode 0600 and refuses to overwrite existing files.
+`)
+    .action(async (opts) => {
+      try {
+        await ensureLoggedIn();
+      } catch (err) {
+        if (!err.displayed) output.error(sanitizeForTerminal(err.message));
+        process.exitCode = 1;
+        return;
+      }
+
+      const oneShotFlagsGiven = opts.message !== undefined || !!opts.json || !!opts.output;
+      if (oneShotFlagsGiven) {
+        const trimmed = typeof opts.message === 'string' ? opts.message.trim() : '';
+        if (!trimmed) {
+          output.error('`-m/--message` requires a non-empty message. For interactive chat, run `unbound chat` with no flags.');
+          process.exitCode = 1;
+          return;
+        }
+        if (trimmed.length > MAX_MESSAGE_LEN) {
+          output.error(`Message too long (max ${MAX_MESSAGE_LEN} characters).`);
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          await runOneShot({ message: trimmed, json: !!opts.json, outputPath: opts.output });
+        } catch (err) {
+          output.error(friendlyChatError(err));
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      try {
+        await runRepl({ noSuggestions: opts.suggestions === false });
+      } catch (err) {
+        output.error(friendlyChatError(err));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = {
+  register,
+  // Exposed for unit tests:
+  _internals: { safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError },
+};

package/src/commands/onboard.js

@@ -27,6 +27,8 @@ function register(program) {
     .requiredOption('--api-key <key>', 'User API key (for tool setup and login)')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery', DEFAULT_DOMAIN)
+    .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
+    .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
 Runs the full onboarding flow for an end user:
   1. Logs in with --api-key and stores credentials.
@@ -54,7 +56,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing tool bundle');
-        const ok = await runSetupAllBundle(apiKey);
+        const ok = await runSetupAllBundle(apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;
 
@@ -87,7 +89,8 @@ Examples:
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery', DEFAULT_DOMAIN)
-    .addOption(new Option('--url <url>', 'Override backend URL for setup scripts').hideHelp())
+    .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
+    .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
 Runs the full MDM onboarding flow for device enrollment:
   1. Installs the MDM tool bundle: ${MDM_ALL_TOOLS.join(', ')}.
@@ -108,7 +111,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing MDM tool bundle');
-        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { url: opts.url });
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;