@desk2quant/cli 1.1.0

package/README.md

@@ -0,0 +1,66 @@
+# Desk2Quant Quant Agent CLI
+
+A terminal-based quant learning, problem-solving, interview and project assistant backed by Desk2Quant.
+
+## Requirements
+
+- Node.js 20+
+- A paid Desk2Quant purchase using the email you sign in with
+
+## Install
+
+Once the package is published:
+
+```bash
+npm install -g @desk2quant/cli
+```
+
+For development from this repository:
+
+```bash
+cd cli
+npm link
+```
+
+## Sign in
+
+```bash
+d2q login you@example.com
+```
+
+Desk2Quant emails the existing My Access magic link. Paste the complete link into the terminal. The CLI exchanges it for a signed Quant Agent session. Model, Razorpay, Supabase and email-service secrets always remain server-side.
+
+## Main commands
+
+```bash
+d2q learn "Ito's lemma"
+d2q solve "derive E[S_T^2] under GBM"
+d2q practice "conditional probability"
+d2q interview "quant research"
+d2q project "Heston calibration"
+d2q progress
+```
+
+## Adaptive assessment
+
+```bash
+d2q assess probability
+d2q submit <assessment-id> "your answer"
+d2q skills
+```
+
+`theta` is a bounded latent ability estimate updated from graded assessments. It is not a percentage or percentile.
+
+## Private Desk2Quant retrieval
+
+When the signed-in buyer has a Razorpay-verified entitlement to an indexed Desk2Quant product, relevant excerpts from that product can be retrieved server-side and used as grounding. The CLI cannot query the private corpus directly and no paid-book text is bundled with this package.
+
+## Local credentials
+
+The CLI stores only the signed Desk2Quant agent session in `~/.desk2quant/config.json`, created with owner-only permissions where supported. Run:
+
+```bash
+d2q logout
+```
+
+to remove it.

package/d2q.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import {
+  COMMANDS,
+  HELP,
+  exchangeMagicLink,
+  formatProgress,
+  formatSkills,
+  formatTerminalMath,
+  getProgress,
+  getSkills,
+  loadConfig,
+  logout,
+  requestLogin,
+  runCommand,
+  startAssessment,
+  submitAssessment
+} from './engine.mjs';
+
+const VERSION = '1.1.0';
+
+function hasFlag(args, flag) { return args.includes(flag); }
+function withoutFlags(args) { return args.filter(a => !a.startsWith('--')); }
+function print(value, json = false) {
+  if (json) return console.log(JSON.stringify(value, null, 2));
+  if (typeof value === 'string') return console.log(formatTerminalMath(value));
+  if (value?.content) {
+    console.log(formatTerminalMath(value.content));
+    if (value.meta?.remainingToday !== undefined) console.log(`\n[${value.meta.remainingToday} requests remaining today]`);
+    return;
+  }
+  console.log(value);
+}
+
+async function login(email, rl, json = false) {
+  await requestLogin(email);
+  if (!json) {
+    console.log('A Desk2Quant sign-in link has been requested.');
+    console.log('Open your email, copy the complete "My Access" sign-in URL, and paste it below.');
+  }
+  const link = (await rl.question('Magic link > ')).trim();
+  const result = await exchangeMagicLink(link);
+  if (json) return print({ success: true, email: result.config.email, tier: result.tier, expiresAt: result.expiresAt, progress: result.progress }, true);
+  console.log(`Signed in as ${result.config.email} (${result.tier}).`);
+  if (result.progress) console.log('\n' + formatProgress(result.progress));
+}
+
+async function execute(command, rest, rl, json = false) {
+  if (command === 'help') return console.log(HELP);
+  if (command === 'login') {
+    const email = rest.join(' ').trim();
+    if (!email) throw new Error('Usage: d2q login <purchase-email>');
+    return login(email, rl, json);
+  }
+  if (command === 'logout') {
+    const removed = await logout();
+    return print(json ? { success: true, removed } : (removed ? 'Signed out.' : 'No local Desk2Quant session was present.'), json);
+  }
+  if (command === 'whoami') {
+    const cfg = await loadConfig();
+    if (!cfg) throw new Error('Not signed in. Run `d2q login <purchase-email>`.');
+    const info = { email: cfg.email, tier: cfg.tier, expiresAt: cfg.expiresAt, baseUrl: cfg.baseUrl };
+    return print(json ? info : `${cfg.email} (${cfg.tier})\nSession expires: ${new Date(Number(cfg.expiresAt)).toLocaleString()}`, json);
+  }
+  if (command === 'progress') {
+    const result = await getProgress();
+    return print(json ? result : formatProgress(result.progress), json);
+  }
+  if (command === 'skills') {
+    const result = await getSkills();
+    return print(json ? result : `${formatSkills(result.skills)}\n\n${result.note || ''}`.trim(), json);
+  }
+  if (command === 'assess') {
+    const result = await startAssessment(rest.join(' ').trim());
+    if (json) return print(result, true);
+    console.log(`Assessment ID: ${result.assessmentId}`);
+    console.log(`Skill: ${result.skill} | difficulty b=${Number(result.difficulty).toFixed(2)} | current theta=${Number(result.currentTheta).toFixed(2)}`);
+    console.log(`\n${formatTerminalMath(result.question)}`);
+    console.log(`\nSubmit with:\n  d2q submit ${result.assessmentId} "your answer"`);
+    return;
+  }
+  if (command === 'submit') {
+    const assessmentId = rest.shift();
+    const answer = rest.join(' ').trim();
+    const result = await submitAssessment(assessmentId, answer);
+    if (json) return print(result, true);
+    console.log(`Score: ${(Number(result.score) * 100).toFixed(1)}%`);
+    console.log(`Theta: ${Number(result.thetaBefore).toFixed(2)} -> ${Number(result.thetaAfter).toFixed(2)}`);
+    console.log(`Attempts: ${result.attempts}`);
+    console.log(`\n${formatTerminalMath(result.feedback)}`);
+    console.log(`\n${formatTerminalMath(result.abilityNote)}`);
+    return;
+  }
+  if (COMMANDS.has(command)) {
+    const query = rest.join(' ').trim();
+    const result = await runCommand(command, query);
+    return print(result, json);
+  }
+  throw new Error(`Unknown command "${command}". Run d2q --help.`);
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.includes('--help') || rawArgs.includes('-h')) return console.log(HELP);
+  if (rawArgs.includes('--version') || rawArgs.includes('-v')) return console.log(`Desk2Quant Quant Agent CLI ${VERSION}`);
+  const json = hasFlag(rawArgs, '--json');
+  const args = withoutFlags(rawArgs);
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    if (args.length) return await execute(args[0].toLowerCase(), args.slice(1), rl, json);
+
+    console.log(`Desk2Quant Quant Agent CLI ${VERSION}`);
+    const cfg = await loadConfig();
+    console.log(cfg ? `Signed in: ${cfg.email}` : 'Not signed in. Type: login <purchase-email>');
+    console.log('Type help for commands, or exit.');
+
+    while (true) {
+      const line = (await rl.question('d2q > ')).trim();
+      if (!line) continue;
+      if (['exit', 'quit'].includes(line.toLowerCase())) break;
+      const parts = line.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+      const clean = parts.map(p => p.replace(/^"|"$/g, ''));
+      const command = String(clean.shift() || '').toLowerCase();
+      try { await execute(command, clean, rl, false); }
+      catch (err) { console.error(`Error: ${err.message}`); }
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(`Desk2Quant CLI: ${err.message}`);
+  process.exitCode = 1;
+});

package/engine.mjs

@@ -0,0 +1,298 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const COMMANDS = new Set(['learn','solve','practice','interview','project']);
+export const ASSESSMENT_SKILLS = ['probability','linear_algebra','statistics','stochastic_calculus','derivatives','fixed_income','numerical_methods','programming','risk','quant_research'];
+export const BASE_URL = process.env.D2Q_BASE_URL || 'https://desk2quant.com';
+export const HELP = `Desk2Quant Quant Agent CLI
+
+Authentication:
+  d2q login <purchase-email>   Email a Desk2Quant magic link, then paste it
+  d2q logout                   Remove the local agent session
+  d2q whoami                   Show the signed-in account and tier
+  d2q progress                 Show activity and today's usage
+
+Quant Agent:
+  d2q learn <topic>
+  d2q solve <problem>
+  d2q practice <topic>
+  d2q interview <role/topic>
+  d2q project <topic>
+
+Adaptive Assessment:
+  d2q assess <skill>           Start one calibrated assessment question
+  d2q submit <id> <answer>     Grade the answer and update latent skill theta
+  d2q skills                   Show calibrated skill estimates
+
+Skills:
+  ${ASSESSMENT_SKILLS.join(', ')}
+
+Options:
+  --json                      Print machine-readable JSON
+  --help, -h                  Show help
+  --version, -v               Show version
+
+Security:
+  The CLI never stores or receives Desk2Quant's model/API secrets.
+  Its local session file is created with owner-only permissions.`;
+
+function configDir(env = process.env) {
+  return env.D2Q_CONFIG_DIR || path.join(os.homedir(), '.desk2quant');
+}
+
+export function configPath(env = process.env) {
+  return path.join(configDir(env), 'config.json');
+}
+
+export function normalizeCommand(command='') {
+  const c = String(command).trim().toLowerCase();
+  if (COMMANDS.has(c)) return c;
+  throw new Error(`Unknown command "${command}". Use: ${[...COMMANDS].join(', ')}`);
+}
+
+export function parseMagicLink(value='') {
+  const raw = String(value).trim();
+  if (!raw) throw new Error('Magic link is required.');
+  let url;
+  try { url = new URL(raw); }
+  catch { throw new Error('Paste the complete Desk2Quant sign-in link from your email.'); }
+  const email = String(url.searchParams.get('email') || '').trim().toLowerCase();
+  const token = String(url.searchParams.get('tk') || '').trim();
+  if (!email || !email.includes('@') || !token) {
+    throw new Error('That link does not contain a valid Desk2Quant email/token pair.');
+  }
+  const host = url.hostname.toLowerCase();
+  const allowed = host === 'desk2quant.com' || host.endsWith('.vercel.app') || host === 'localhost' || host === '127.0.0.1';
+  if (!allowed) throw new Error('Refusing a sign-in link from an untrusted host.');
+  return { email, accessToken: token };
+}
+
+function terminalMathSegment(value='') {
+  let text = String(value);
+
+  // Strip display/inline LaTeX wrappers and layout-only commands that terminals
+  // cannot typeset. Keep the mathematical content itself.
+  text = text
+    .replace(/\\\[/g, '\n')
+    .replace(/\\\]/g, '\n')
+    .replace(/\\\(/g, '')
+    .replace(/\\\)/g, '')
+    .replace(/\\begin\{(?:aligned|align\*?|equation\*?|gather\*?)\}/g, '')
+    .replace(/\\end\{(?:aligned|align\*?|equation\*?|gather\*?)\}/g, '')
+    .replace(/\\(?:left|right|bigl|bigr|Bigl|Bigr|big|Big)\b/g, '')
+    .replace(/\\!/g, '')
+    .replace(/\\[,;:]/g, ' ')
+    .replace(/\\qquad\b/g, '    ')
+    .replace(/\\quad\b/g, '  ')
+    .replace(/\\\\/g, '\n');
+
+  // Fractions are intentionally rendered as explicit parenthesized division.
+  // Repeat to handle simple nested fractions without adding a parser dependency.
+  for (let i = 0; i < 8; i += 1) {
+    const next = text.replace(/\\(?:d|t)?frac\s*\{([^{}]+)\}\s*\{([^{}]+)\}/g, '($1)/($2)');
+    if (next === text) break;
+    text = next;
+  }
+
+  text = text
+    .replace(/\\sqrt\s*\{([^{}]+)\}/g, '√($1)')
+    .replace(/\\mathbb\{Q\}/g, 'ℚ')
+    .replace(/\\mathbb\{R\}/g, 'ℝ')
+    .replace(/\\mathbb\{P\}/g, 'ℙ')
+    .replace(/\\text\{([^{}]*)\}/g, '$1')
+    .replace(/\\operatorname\{([^{}]*)\}/g, '$1')
+    .replace(/\\boxed\{([^{}]*)\}/g, '$1');
+
+  const symbols = {
+    theta: 'θ', sigma: 'σ', mu: 'μ', alpha: 'α', beta: 'β', gamma: 'γ',
+    delta: 'δ', rho: 'ρ', lambda: 'λ', kappa: 'κ', phi: 'φ',
+    Delta: 'Δ', Gamma: 'Γ', Theta: 'Θ', Lambda: 'Λ',
+    partial: '∂', nabla: '∇', int: '∫', sum: 'Σ', prod: 'Π', infinity: '∞', infty: '∞',
+    approx: '≈', neq: '≠', leq: '≤', geq: '≥', le: '≤', ge: '≥',
+    times: '×', cdot: '·', pm: '±', to: '→', rightarrow: '→', leftarrow: '←'
+  };
+  for (const [command, symbol] of Object.entries(symbols)) {
+    text = text.replace(new RegExp(`\\\\${command}\\b`, 'g'), symbol);
+  }
+
+  text = text
+    .replace(/\\exp\b/g, 'exp')
+    .replace(/\\ln\b/g, 'ln')
+    .replace(/\\log\b/g, 'log')
+    .replace(/\\sin\b/g, 'sin')
+    .replace(/\\cos\b/g, 'cos')
+    .replace(/\\min\b/g, 'min')
+    .replace(/\\max\b/g, 'max')
+    .replace(/_\{([^{}]+)\}/g, '_$1')
+    .replace(/\^\{([^{}]+)\}/g, '^($1)')
+    .replace(/\^2\b/g, '²')
+    .replace(/\^3\b/g, '³')
+    .replace(/\^\(-1\)/g, '⁻¹')
+    .replace(/(?<!\\)\$([^$\n]+)\$/g, '$1')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n');
+
+  return text;
+}
+
+export function formatTerminalMath(value='') {
+  const text = String(value ?? '').replace(/\r\n/g, '\n');
+  if (!text) return text;
+
+  // Never rewrite code examples. Only human-readable prose/math segments are
+  // normalized, so Python/R/SQL snippets remain byte-for-byte intact.
+  return text
+    .split(/(```[\s\S]*?```|`[^`\n]+`)/g)
+    .map(part => part.startsWith('`') ? part : terminalMathSegment(part))
+    .join('')
+    .trim();
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  let data;
+  try { data = text ? JSON.parse(text) : {}; }
+  catch { throw new Error(`Desk2Quant returned an invalid response (${response.status}).`); }
+  if (!response.ok) {
+    const err = new Error(data.error || `Desk2Quant request failed (${response.status}).`);
+    err.status = response.status;
+    err.data = data;
+    throw err;
+  }
+  return data;
+}
+
+export async function apiPost(route, payload, { baseUrl = BASE_URL, fetchImpl = fetch } = {}) {
+  const response = await fetchImpl(`${String(baseUrl).replace(/\/$/, '')}${route}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'User-Agent': 'Desk2Quant-CLI/1.1' },
+    body: JSON.stringify(payload)
+  });
+  return readJson(response);
+}
+
+export async function requestLogin(email, options = {}) {
+  const normalized = String(email || '').trim().toLowerCase();
+  if (!normalized || !normalized.includes('@')) throw new Error('A valid purchase email is required.');
+  return apiPost('/api/interview', { action: 'access-login', email: normalized }, options);
+}
+
+export async function exchangeMagicLink(link, options = {}) {
+  const parsed = parseMagicLink(link);
+  const data = await apiPost('/api/products', {
+    action: 'agent-auth',
+    email: parsed.email,
+    accessToken: parsed.accessToken
+  }, options);
+  const config = {
+    version: 1,
+    email: parsed.email,
+    tier: data.tier || 'pro',
+    agentToken: data.agentToken,
+    expiresAt: data.expiresAt,
+    baseUrl: options.baseUrl || BASE_URL
+  };
+  if (!config.agentToken) throw new Error('Desk2Quant did not return an agent session.');
+  await saveConfig(config, options.env || process.env);
+  return { ...data, config };
+}
+
+export async function saveConfig(config, env = process.env) {
+  const dir = configDir(env);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const file = configPath(env);
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+  await fs.rename(tmp, file);
+  try { await fs.chmod(file, 0o600); } catch (_) {}
+}
+
+export async function loadConfig(env = process.env) {
+  try {
+    const raw = await fs.readFile(configPath(env), 'utf8');
+    const cfg = JSON.parse(raw);
+    if (!cfg?.email || !cfg?.agentToken) return null;
+    return cfg;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw new Error('Could not read ~/.desk2quant/config.json. Run `d2q logout` and sign in again.');
+  }
+}
+
+export async function logout(env = process.env) {
+  try { await fs.unlink(configPath(env)); return true; }
+  catch (err) { if (err?.code === 'ENOENT') return false; throw err; }
+}
+
+function assertSession(config) {
+  if (!config) throw new Error('Not signed in. Run `d2q login <purchase-email>`.');
+  if (config.expiresAt && Date.now() >= Number(config.expiresAt)) {
+    throw new Error('Your Desk2Quant agent session expired. Run `d2q login <purchase-email>` again.');
+  }
+}
+
+async function sessionPost(action, extra = {}, options = {}) {
+  const config = options.config || await loadConfig(options.env || process.env);
+  assertSession(config);
+  return apiPost('/api/products', {
+    action,
+    email: config.email,
+    agentToken: config.agentToken,
+    ...extra
+  }, {
+    baseUrl: options.baseUrl || config.baseUrl || BASE_URL,
+    fetchImpl: options.fetchImpl || fetch
+  });
+}
+
+export async function runCommand(command, query='', options = {}) {
+  const c = normalizeCommand(command);
+  const q = String(query).trim();
+  if (!q) throw new Error(`${c} requires a topic/problem.`);
+  return sessionPost('agent-run', { command: c, query: q }, options);
+}
+
+export async function getProgress(options = {}) {
+  return sessionPost('agent-progress', {}, options);
+}
+
+export async function startAssessment(skill, options = {}) {
+  const s = String(skill || '').trim();
+  if (!s) throw new Error('Usage: d2q assess <skill>');
+  return sessionPost('agent-assess-start', { skill: s }, options);
+}
+
+export async function submitAssessment(assessmentId, answer, options = {}) {
+  const id = String(assessmentId || '').trim();
+  const response = String(answer || '').trim();
+  if (!id || !response) throw new Error('Usage: d2q submit <assessment-id> <answer>');
+  return sessionPost('agent-assess-submit', { assessmentId: id, answer: response }, options);
+}
+
+export async function getSkills(options = {}) {
+  return sessionPost('agent-skills', {}, options);
+}
+
+export function formatProgress(progress = {}) {
+  const lines = [
+    `Total sessions: ${Number(progress.totalSessions) || 0}`,
+    `Today: ${Number(progress.usedToday) || 0}/${Number(progress.dailyLimit) || 0} used (${Number(progress.remainingToday) || 0} remaining)`
+  ];
+  if (progress.lastCommand) lines.push(`Last: ${progress.lastCommand} — ${progress.lastTopic || 'general quant'}`);
+  if (Array.isArray(progress.topTopics) && progress.topTopics.length) {
+    lines.push('Top topics:');
+    for (const item of progress.topTopics) lines.push(`  ${item.topic}: ${item.sessions}`);
+  }
+  if (progress.note) lines.push(`\n${progress.note}`);
+  return lines.join('\n');
+}
+
+export function formatSkills(skills = []) {
+  if (!Array.isArray(skills) || !skills.length) return 'No graded skill assessments yet. Run `d2q assess <skill>`.';
+  return skills.map(s => {
+    const theta = Number(s.theta) || 0;
+    const score = Math.round((Number(s.mean_score) || 0) * 100);
+    return `${s.skill_key}: theta=${theta.toFixed(2)} | attempts=${Number(s.attempts)||0} | mean score=${score}%`;
+  }).join('\n');
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@desk2quant/cli",
+  "version": "1.1.0",
+  "description": "Desk2Quant Quant Agent CLI for aspiring quants",
+  "type": "module",
+  "bin": {
+    "d2q": "d2q.mjs"
+  },
+  "files": [
+    "d2q.mjs",
+    "engine.mjs",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIM-IT4/desk2quant.git",
+    "directory": "cli"
+  },
+  "homepage": "https://desk2quant.com",
+  "bugs": {
+    "url": "https://github.com/AIM-IT4/desk2quant/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "quant",
+    "quantitative-finance",
+    "interview",
+    "desk2quant",
+    "cli"
+  ]
+}