@oppira/cli 0.1.0

package/src/index.js

@@ -0,0 +1,108 @@
+// Program definition + dispatch. Assembles the command tree from the command
+// modules and routes `oppira <group> <command> ...` (or a top-level command
+// like `ask`) to the right handler, with generated help and error rendering.
+
+import {
+  parseArgs, makeContext, collectBooleanFlags,
+  renderProgramHelp, renderGroupHelp, renderCommandHelp,
+} from './framework.js';
+import { resolveProfileName } from './config.js';
+import { renderError } from './output.js';
+
+import authGroup from './commands/auth.js';
+import configGroup from './commands/config.js';
+import competitorsGroup from './commands/competitors.js';
+import discoverGroup from './commands/discover.js';
+import scrapeGroup from './commands/scrape.js';
+import insightsGroup from './commands/insights.js';
+import alertsGroup from './commands/alerts.js';
+import battlecardGroup from './commands/battlecard.js';
+import playbookGroup from './commands/playbook.js';
+import studioGroup from './commands/studio.js';
+import artifactGroup from './commands/artifact.js';
+import adminGroup from './commands/admin.js';
+import { askCommand } from './commands/ask.js';
+
+export function buildProgram() {
+  return {
+    name: 'oppira',
+    version: '0.1.0',
+    description: 'Terminal control for Oppira — competitor intelligence, playbook, studio & ops.',
+    groups: {
+      auth: authGroup,
+      config: configGroup,
+      competitors: competitorsGroup,
+      comp: competitorsGroup, // alias
+      discover: discoverGroup,
+      scrape: scrapeGroup,
+      insights: insightsGroup,
+      alerts: alertsGroup,
+      battlecard: battlecardGroup,
+      playbook: playbookGroup,
+      studio: studioGroup,
+      artifact: artifactGroup,
+      admin: adminGroup,
+    },
+    topLevel: {
+      ask: askCommand,
+    },
+  };
+}
+
+export async function main(argv) {
+  const program = buildProgram();
+  const tokens = argv;
+
+  if (tokens.length === 0 || tokens[0] === '--help' || tokens[0] === '-h') {
+    console.log(renderProgramHelp(program));
+    return;
+  }
+  if (tokens[0] === '--version' || tokens[0] === '-v') {
+    console.log(program.version);
+    return;
+  }
+
+  const first = tokens[0];
+  let cmd, cmdPath, rest;
+
+  if (program.groups[first]) {
+    const group = program.groups[first];
+    const sub = tokens[1];
+    if (!sub || sub === '--help' || sub === '-h') {
+      console.log(renderGroupHelp(program, first, group));
+      return;
+    }
+    cmd = group.commands[sub];
+    if (!cmd) {
+      renderError(new Error(`Unknown command: ${first} ${sub}`));
+      console.log('\n' + renderGroupHelp(program, first, group));
+      return;
+    }
+    cmdPath = `${first} ${sub}`;
+    rest = tokens.slice(2);
+  } else if (program.topLevel[first]) {
+    cmd = program.topLevel[first];
+    cmdPath = first;
+    rest = tokens.slice(1);
+  } else {
+    renderError(new Error(`Unknown command: ${first}`));
+    console.log('\n' + renderProgramHelp(program));
+    return;
+  }
+
+  const { positionals, flags } = parseArgs(rest, collectBooleanFlags(cmd));
+  if (flags.help) {
+    console.log(renderCommandHelp(program, cmdPath, cmd));
+    return;
+  }
+
+  const ctx = makeContext({ positionals, flags });
+  ctx.profileName = resolveProfileName(flags);
+  ctx.program = program;
+
+  try {
+    await cmd.handler(ctx);
+  } catch (err) {
+    renderError(err);
+  }
+}

package/src/local.js

@@ -0,0 +1,99 @@
+// Ops / "local mode". Runs commands against MongoDB + the backend's engine
+// functions directly, instead of over HTTP. This is how the CLI reaches the
+// cron-only generators (battlecard / insights / alerts / summary) and the
+// intelligent scraper without needing new HTTP endpoints — mirroring the
+// existing one-off scripts in ../scripts (dotenv + mongoose.connect + engine).
+//
+// Only usable from a repo checkout with MONGO_URI available; the published
+// customer build never exercises this path.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BACKEND_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+
+// Absolute path to the backend repo root (for spawning ../scripts, etc.).
+export const backendDir = BACKEND_ROOT;
+
+// Dynamic import of a module inside the backend, resolved from the repo root.
+export async function backendImport(relPath) {
+  const abs = path.join(BACKEND_ROOT, relPath);
+  return import(pathToFileUrl(abs));
+}
+
+function pathToFileUrl(abs) {
+  // Cross-platform file URL (Windows paths need this).
+  const url = new URL('file://');
+  url.pathname = abs.replace(/\\/g, '/');
+  // On Windows the drive letter needs a leading slash.
+  return /^[a-zA-Z]:/.test(abs) ? `file:///${abs.replace(/\\/g, '/')}` : url.href;
+}
+
+let connected = false;
+
+export async function connectDb() {
+  if (connected) return;
+  // Local/ops mode drives the backend engines directly — those modules read
+  // secrets (MONGO_URI, RESEND_API_KEY, APIFY_API_KEY, LLM keys) at import time,
+  // so the backend .env must be present. Fail early and clearly if it isn't,
+  // instead of surfacing a downstream client's cryptic "missing API key".
+  const envPath = path.join(BACKEND_ROOT, '.env');
+  if (!fs.existsSync(envPath) && !process.env.MONGO_URI) {
+    throw new Error(
+      `Local/ops mode needs the backend .env (looked in ${BACKEND_ROOT}). Run from a repo checkout with secrets, or use the remote (HTTP) commands instead.`
+    );
+  }
+  const dotenv = await import('dotenv');
+  dotenv.config({ path: envPath });
+  if (!process.env.MONGO_URI) {
+    throw new Error('MONGO_URI not set. Local/ops mode needs the backend .env (run from the repo).');
+  }
+  const mongoose = (await import('mongoose')).default;
+  await mongoose.connect(process.env.MONGO_URI);
+  connected = true;
+  return mongoose;
+}
+
+export async function disconnectDb() {
+  if (!connected) return;
+  const mongoose = (await import('mongoose')).default;
+  await mongoose.disconnect();
+  connected = false;
+}
+
+// Run fn with a live DB connection, always disconnecting afterwards.
+export async function withDb(fn) {
+  await connectDb();
+  try {
+    return await fn();
+  } finally {
+    await disconnectDb();
+  }
+}
+
+// Convenience loaders for the models + engines the CLI drives.
+export async function loadModels() {
+  const [{ User }, { Competitor }] = await Promise.all([
+    backendImport('models/userModel.js'),
+    backendImport('models/competitorModel.js'),
+  ]);
+  return { User, Competitor };
+}
+
+export async function findUserOrThrow(email) {
+  const { User } = await loadModels();
+  const user = await User.findOne({ email });
+  if (!user) throw new Error(`No user found with email ${email}`);
+  return user;
+}
+
+// Resolve competitors for a user by name/handle substring, or all if omitted.
+export async function findCompetitorsForUser(user, nameQuery) {
+  const { Competitor } = await loadModels();
+  const q = { userEmails: user.email };
+  if (nameQuery) q.name = new RegExp(escapeRegex(nameQuery), 'i');
+  return Competitor.find(q);
+}
+
+function escapeRegex(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/output.js

@@ -0,0 +1,74 @@
+// Output helpers. Two modes: human (tables + key/value) and --json (raw JSON
+// for scripts/agents). Errors are rendered with a helpful hint where we have
+// one (quota / plan gates carry a suggestedPlan), and always set exit code 1.
+
+import { ApiError } from './http.js';
+
+export function out(data, ctx) {
+  if (ctx?.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    return;
+  }
+  if (typeof data === 'string') { console.log(data); return; }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function kv(obj, ctx) {
+  if (ctx?.json) { out(obj, ctx); return; }
+  const width = Math.max(...Object.keys(obj).map((k) => k.length)) + 2;
+  for (const [k, v] of Object.entries(obj)) {
+    const val = v === null || v === undefined ? '—' : (typeof v === 'object' ? JSON.stringify(v) : String(v));
+    console.log(`${k.padEnd(width)}${val}`);
+  }
+}
+
+export function table(rows, columns, ctx) {
+  if (ctx?.json) { out(rows, ctx); return; }
+  if (!rows || rows.length === 0) { console.log('(no results)'); return; }
+  const cols = columns || Object.keys(rows[0]).map((k) => ({ key: k, label: k }));
+  const widths = cols.map((c) => {
+    const header = c.label || c.key;
+    const cellMax = Math.max(...rows.map((r) => cellStr(r, c).length));
+    return Math.max(header.length, cellMax);
+  });
+  const header = cols.map((c, i) => (c.label || c.key).padEnd(widths[i])).join('  ');
+  console.log(header);
+  console.log(cols.map((_, i) => '-'.repeat(widths[i])).join('  '));
+  for (const r of rows) {
+    console.log(cols.map((c, i) => cellStr(r, c).padEnd(widths[i])).join('  '));
+  }
+}
+
+function cellStr(row, col) {
+  let v = col.get ? col.get(row) : row[col.key];
+  if (v === null || v === undefined) return '—';
+  if (typeof v === 'object') v = JSON.stringify(v);
+  v = String(v);
+  const max = col.max || 48;
+  return v.length > max ? v.slice(0, max - 1) + '…' : v;
+}
+
+export function renderError(err) {
+  process.exitCode = 1;
+  if (err instanceof ApiError) {
+    console.error(`✗ ${err.message}`);
+    const b = err.body;
+    if (b?.error === 'quota-exceeded') {
+      const parts = [];
+      if (b.scope) parts.push(`scope: ${b.scope}`);
+      if (b.limit !== undefined) parts.push(`limit: ${b.limit}`);
+      if (typeof b.retryAfter === 'number') {
+        const h = Math.ceil(b.retryAfter / 3600);
+        parts.push(h >= 1 ? `retry in ~${h}h` : `retry in ~${Math.ceil(b.retryAfter / 60)}m`);
+      }
+      if (b.suggestedPlan) parts.push(`suggested plan: ${b.suggestedPlan}`);
+      if (parts.length) console.error(`  ${parts.join(' · ')}`);
+    } else if (err.status === 403) {
+      console.error('  (plan gate or permission — check your subscription / account role.)');
+    }
+    return;
+  }
+  console.error(`✗ ${err?.message || String(err)}`);
+}
+
+export function info(msg) { console.error(msg); } // stderr so --json stdout stays clean

package/src/sse.js

@@ -0,0 +1,52 @@
+// SSE client for POST /agent/chat. The backend streams `data: {json}\n\n`
+// frames (types: conversation-id, agent, navigate, text-delta) terminated by a
+// literal `data: [DONE]\n\n`. We parse frames off the byte stream and hand each
+// decoded event to onEvent.
+
+import { getProfile, getCredentials } from './config.js';
+import { ApiError } from './http.js';
+
+function joinUrl(base, pathname) {
+  return `${base.replace(/\/$/, '')}/${pathname.replace(/^\//, '')}`;
+}
+
+export async function streamChat(profileName, { message, conversationId, pageContext }, onEvent) {
+  const profile = getProfile(profileName);
+  const creds = getCredentials(profile.name);
+  const auth = creds.accessToken ? `Bearer ${creds.accessToken}` : (creds.apiKey ? `Bearer ${creds.apiKey}` : null);
+  if (!auth) throw new ApiError('Not logged in. Run: oppira auth login');
+
+  const res = await fetch(joinUrl(profile.apiUrl, '/agent/chat'), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'text/event-stream',
+      Authorization: auth,
+      'X-Oppira-Client': 'oppira-cli',
+    },
+    body: JSON.stringify({ message, conversationId, pageContext }),
+  });
+
+  if (!res.ok) {
+    let body = null;
+    try { body = JSON.parse(await res.text()); } catch { /* non-json error */ }
+    throw new ApiError(body?.message || `Chat failed (${res.status})`, { status: res.status, body });
+  }
+  if (!res.body) throw new ApiError('No response stream from /agent/chat');
+
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for await (const chunk of res.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const frame = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      const dataLine = frame.split('\n').find((l) => l.startsWith('data:'));
+      if (!dataLine) continue;
+      const payload = dataLine.slice(5).trim();
+      if (payload === '[DONE]') return;
+      try { onEvent(JSON.parse(payload)); } catch { /* ignore malformed frame */ }
+    }
+  }
+}