mindvest-atlas 0.1.6 → 0.2.0

package/README.md

@@ -27,6 +27,7 @@ atlas login
 atlas tools
 atlas stock-quote --symbol SPY
 atlas options-chain --symbol SPY --expiration 2026-06-20
+atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call --from 2026-07-06 --to 2026-07-10
 atlas alerts --symbol SPY --name greek_exposure --save-charts ./charts
 atlas flow stream --symbol NVDA
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindvest-atlas",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Atlas CLI — OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -12,6 +12,7 @@ import { whoamiCommand } from './commands/whoami.js';
 import { toolsCommand } from './commands/tools.js';
 import { alertsCommand } from './commands/alerts.js';
 import { flowCommand } from './commands/flow.js';
+import { historicalContractCommand } from './commands/historical.js';
 import { callCommand } from './commands/call.js';
 
 export async function main(rawArgs) {
@@ -46,6 +47,10 @@ export async function main(rawArgs) {
       case 'tools': return await toolsCommand(withoutCommand(args));
       case 'alerts': return await alertsCommand(withoutCommand(args));
       case 'flow': return await flowCommand(withoutCommand(args));
+      // Friendly front end over Historical-Contract-Greeks (short flags + a table).
+      case 'historical-contract':
+      case 'hist-contract':
+        return await historicalContractCommand(withoutCommand(args));
       default:
         // Treat the first positional as a tool slug (e.g. stock-quote).
         return await callCommand(cmd, withoutCommand(args));

package/src/commands/historical.js

@@ -0,0 +1,157 @@
+// `atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call
+//                            --from 2026-07-08 --to 2026-07-10`
+//
+// Day-by-day price + greeks for ONE option contract. This is a friendly front end over
+// the `Historical-Contract-Greeks` tool: short flags (--expiry / --from / --to), a
+// side shorthand (--call / --put), per-flag "you forgot this one" errors, and a table
+// instead of raw JSON. The generic caller still works (`atlas historical-contract-greeks
+// --from-date …`); this exists because five required params deserve better ergonomics.
+import { API } from '../config.js';
+import { requestJson, ApiError, AuthError } from '../api/client.js';
+import { formatContractHistory } from '../util/format.js';
+import { color, println, eprintln } from '../util/ui.js';
+
+const TOOL = 'Historical-Contract-Greeks';
+
+// Flags the user might reach for → the server's parameter name.
+const ALIASES = {
+  symbol: ['symbol', 'ticker'],
+  expiration: ['expiry', 'expiration', 'exp'],
+  strike: ['strike'],
+  side: ['side', 'right'],
+  from_date: ['from', 'from-date', 'start'],
+  to_date: ['to', 'to-date', 'end'],
+};
+
+// A bare `--flag` parses to `true`; that is not a value, so don't accept it.
+function pick(flags, names) {
+  for (const n of names) {
+    const v = flags[n];
+    if (v !== undefined && v !== true && v !== '') return v;
+  }
+  return undefined;
+}
+
+export function printHistoricalHelp() {
+  const c = color;
+  println(`${c.bold('atlas historical-contract')} — day-by-day price and greeks for one option contract`);
+  println();
+  println(c.bold('USAGE'));
+  println('  atlas historical-contract --symbol <TICKER> --expiry <YYYY-MM-DD> \\');
+  println('                           --strike <PRICE> --side <call|put> \\');
+  println('                           --from <YYYY-MM-DD> [--to <YYYY-MM-DD>]');
+  println();
+  println(c.bold('REQUIRED'));
+  println('  --symbol, --ticker <T>     Underlying ticker (e.g. NVDA)');
+  println('  --expiry, --expiration <D> The contract\'s expiration date, YYYY-MM-DD');
+  println('  --strike <PRICE>           The contract\'s strike (e.g. 205)');
+  println('  --side <call|put>          Which side (or use --call / --put)');
+  println('  --from, --start <D>        First day to report, YYYY-MM-DD');
+  println();
+  println(c.bold('OPTIONAL'));
+  println('  --to, --end <D>            Last day to report (default: same as --from)');
+  println('  --no-greeks                Prices only — skip the greeks (faster)');
+  println('  --json                     Raw JSON instead of the table');
+  println();
+  println(c.bold('NOTES'));
+  println(c.dim('  The daily price is the MID of the last bid/ask before the 4pm close.'));
+  println(c.dim('  Greeks are calculated, not reported: no data provider publishes greeks for'));
+  println(c.dim('  past dates, so implied volatility is solved from that day\'s closing mid.'));
+  println(c.dim('  Open interest is not available for past dates at all.'));
+  println(c.dim('  One contract per call, up to 90 trading days.'));
+  println();
+  println(c.dim('Example:'));
+  println(c.dim('  atlas historical-contract --symbol NVDA --expiry 2026-07-13 \\'));
+  println(c.dim('                           --strike 205 --side call --from 2026-07-06 --to 2026-07-10'));
+}
+
+// Pure: flags -> request body, or the reason it can't be built. Kept separate from the
+// command so the flag mapping is unit-testable without a network round trip.
+// Returns { body } | { missing: [...] } | { error }.
+export function buildHistoricalBody(args) {
+  const flags = args.flags || {};
+  const positionals = args._ || [];
+
+  // `atlas historical-contract NVDA …` — allow the ticker as a bare positional too.
+  const symbol = pick(flags, ALIASES.symbol) ?? positionals[0];
+  const expiration = pick(flags, ALIASES.expiration);
+  const strike = pick(flags, ALIASES.strike);
+  const from = pick(flags, ALIASES.from_date);
+  const to = pick(flags, ALIASES.to_date);
+
+  let side = pick(flags, ALIASES.side);
+  if (side === undefined && flags.call === true) side = 'call';
+  if (side === undefined && flags.put === true) side = 'put';
+
+  // Five required params — name the ones actually missing. A bare "missing parameter"
+  // would send the user back to --help every time.
+  const missing = [];
+  if (!symbol) missing.push('--symbol <TICKER>');
+  if (!expiration) missing.push('--expiry <YYYY-MM-DD>');
+  if (strike === undefined) missing.push('--strike <PRICE>');
+  if (!side) missing.push('--side <call|put>');
+  if (!from) missing.push('--from <YYYY-MM-DD>');
+  if (missing.length) return { missing };
+
+  const sideStr = String(side).toLowerCase();
+  const sideNorm = sideStr.startsWith('c') ? 'call' : sideStr.startsWith('p') ? 'put' : null;
+  if (!sideNorm) return { error: `--side must be call or put (got "${side}")` };
+
+  const strikeNum = Number(strike);
+  if (!Number.isFinite(strikeNum) || strikeNum <= 0) {
+    return { error: `--strike must be a positive number (got "${strike}")` };
+  }
+
+  const body = {
+    symbol: String(symbol).toUpperCase(),
+    expiration: String(expiration),
+    strike: strikeNum,
+    side: sideNorm,
+    from_date: String(from),
+  };
+  if (to) body.to_date = String(to);
+  // `--no-greeks` parses to flags.greeks === false (the --no- convention).
+  if (flags.greeks === false || flags['include-greeks'] === false) body.include_greeks = false;
+  return { body };
+}
+
+export async function historicalContractCommand(args) {
+  const flags = args.flags;
+  if (flags.help || flags.h) { printHistoricalHelp(); return 0; }
+
+  const built = buildHistoricalBody(args);
+  if (built.missing) {
+    eprintln(color.red('Missing required flag(s): ') + built.missing.join('  '));
+    eprintln(color.dim('Example: atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call --from 2026-07-08 --to 2026-07-10'));
+    eprintln(color.dim('See: atlas historical-contract --help'));
+    return 1;
+  }
+  if (built.error) { eprintln(color.red(built.error)); return 1; }
+  const body = built.body;
+
+  let data;
+  try {
+    data = await requestJson(API.tool(TOOL), { method: 'POST', body });
+  } catch (err) {
+    if (err instanceof AuthError) { eprintln(color.red(err.message)); return 1; }
+    if (err instanceof ApiError) {
+      eprintln(color.red(`Error (${err.status || '?'}): ${err.message}`));
+      return 1;
+    }
+    eprintln(color.red('Request failed: ') + err.message);
+    return 1;
+  }
+
+  // The tools API returns 200 with an { error } body on bad input.
+  if (data && typeof data === 'object' && typeof data.error === 'string') {
+    eprintln(color.red('Error: ') + data.error);
+    return 1;
+  }
+
+  if (flags.json || flags.raw) {
+    println(JSON.stringify(data, null, 2));
+    return 0;
+  }
+  for (const line of formatContractHistory(data)) println(line);
+  return 0;
+}

package/src/config.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import os from 'node:os';
 
-export const VERSION = '0.1.6';
+export const VERSION = '0.2.0';
 export const DEFAULT_BASE_URL = 'https://atlasmcp.finmanagerai.com';
 export const DEFAULT_SCOPE = 'atlas broker';
 export const CLIENT_NAME = 'Atlas CLI';

package/src/util/format.js

@@ -69,3 +69,64 @@ export function formatTrade(t) {
   const oc = t.open_close ? color.dim(t.open_close === 'open' ? 'O' : 'C') : '';
   return `${time} ${ticker} ${cp} ${strike} ${exp}  ${side} ${size} ${price}  ${prem}  ${type} ${tag} ${oc}`.replace(/\s+$/, '');
 }
+
+// ── historical-contract: one row per trading day ─────────────────────────────
+// Fixed-width so the columns line up; padding is applied BEFORE color codes so the
+// escape sequences don't count toward the width.
+function cell(v, dp, w) {
+  if (v === null || v === undefined || Number.isNaN(Number(v))) return '—'.padStart(w);
+  return Number(v).toFixed(dp).padStart(w);
+}
+
+function ivCell(v, w) {
+  if (v === null || v === undefined || Number.isNaN(Number(v))) return '—'.padStart(w);
+  return (Number(v) * 100).toFixed(1).concat('%').padStart(w);
+}
+
+export function formatContractHistory(d) {
+  const c = color;
+  const out = [];
+  const days = Array.isArray(d.days) ? d.days : [];
+
+  out.push(
+    c.bold(d.option_symbol || '?') +
+    c.dim(`   ${d.symbol} ${num(d.strike)} ${d.side} · expires ${d.expiration}`)
+  );
+  out.push(c.dim(
+    `${d.from_date} → ${d.to_date}   ${days.length} trading day${days.length === 1 ? '' : 's'}` +
+    '   price = mid of the last bid/ask before the close'
+  ));
+  out.push('');
+
+  // Only show greek columns when the response actually carries them (--no-greeks).
+  const hasGreeks = days.some((r) => r.delta !== null && r.delta !== undefined);
+  const head =
+    'DATE'.padEnd(12) + 'DTE'.padStart(4) + 'BID'.padStart(9) + 'ASK'.padStart(9) +
+    'MID'.padStart(9) + 'SPOT'.padStart(10) +
+    (hasGreeks ? 'IV'.padStart(8) + 'DELTA'.padStart(9) + 'GAMMA'.padStart(9) + 'THETA'.padStart(9) : '');
+  out.push(c.dim(head));
+
+  for (const r of days) {
+    let row =
+      String(r.date || '').padEnd(12) +
+      String(r.dte ?? '—').padStart(4) +
+      cell(r.bid, 2, 9) + cell(r.ask, 2, 9) +
+      c.bold(cell(r.mid, 2, 9).replace(/^(\s*)/, '$1')) +
+      cell(r.underlying_price, 2, 10);
+    if (hasGreeks) {
+      row += ivCell(r.iv, 8) + cell(r.delta, 3, 9) + cell(r.gamma, 3, 9) + cell(r.theta, 3, 9);
+    }
+    out.push(row);
+    if (r.greeks_error) out.push(c.dim(`  ↳ no greeks: ${r.greeks_error}`));
+  }
+
+  // Never let a missing day pass silently — a holiday and a never-quoted strike look
+  // identical in a table that just skips rows.
+  if (Array.isArray(d.skipped) && d.skipped.length) {
+    out.push('');
+    for (const s of d.skipped) out.push(c.dim(`skipped ${s.date}: ${s.reason}`));
+  }
+  if (d.truncated) out.push(c.yellow(String(d.truncated)));
+  if (d.note) { out.push(''); out.push(c.dim(d.note)); }
+  return out;
+}

package/src/util/help.js

@@ -22,6 +22,11 @@ export function printRootHelp() {
   println('  <tool> --param value [--out <dir>]                 Call a tool — pass params as flags');
   println('  <tool> --a.b value                                 Nested value via a dotted flag');
   println();
+  println(c.bold('MARKET HISTORY'));
+  println('  historical-contract --symbol NVDA --expiry 2026-07-13             Day-by-day price + greeks');
+  println('        --strike 205 --side call --from 2026-07-06 [--to 2026-07-10]  for ONE option contract');
+  println('        [--no-greeks] [--json]');
+  println();
   println(c.bold('STREAMS'));
   println('  alerts [--symbol SPY] [--name greek_exposure]      Live alert feed (SSE)');
   println('         [--save-charts <dir>] [--no-chart] [--json]');
@@ -42,6 +47,7 @@ export function printRootHelp() {
   println(c.dim('  atlas tools'));
   println(c.dim('  atlas stock-quote --symbol SPY'));
   println(c.dim('  atlas options-chain --symbol SPY --expiration 2026-06-20'));
+  println(c.dim('  atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call --from 2026-07-06 --to 2026-07-10'));
   println(c.dim('  atlas update-alert --alert-id <id> --updates.is-active true   # nested via a dotted flag'));
   println(c.dim('  atlas create-task --name "Close SPY 3:55" --instruction "Close my SPY position" --schedule-times 15:55'));
   println(c.dim('  atlas run-task --task-id <id>'));