@quantbrasil/cli 0.1.0-beta.0

package/dist/cli/terminal.js

@@ -0,0 +1,43 @@
+const ANSI_RESET = "\u001B[0m";
+const ANSI_BOLD = "\u001B[1m";
+const ANSI_DIM = "\u001B[2m";
+const QB_ACCENT_RGB = [73, 206, 139];
+const QB_WARNING_RGB = [212, 158, 22];
+const QB_DANGER_RGB = [225, 82, 65];
+const QB_INFO_RGB = [18, 144, 248];
+export function createTerminalTheme(writer, env = process.env) {
+    const enabled = isColorEnabled(writer, env);
+    return {
+        enabled,
+        accent: text => applyRgb(text, QB_ACCENT_RGB, enabled),
+        bold: text => applyCodes(text, [ANSI_BOLD], enabled),
+        dim: text => applyCodes(text, [ANSI_DIM], enabled),
+        success: text => applyRgb(text, QB_ACCENT_RGB, enabled),
+        warning: text => applyRgb(text, QB_WARNING_RGB, enabled),
+        danger: text => applyRgb(text, QB_DANGER_RGB, enabled),
+        info: text => applyRgb(text, QB_INFO_RGB, enabled),
+        label: text => applyRgb(applyCodes(text, [ANSI_BOLD], enabled), QB_ACCENT_RGB, enabled),
+    };
+}
+export function styleErrorMessage(message, writer, env = process.env) {
+    const theme = createTerminalTheme(writer, env);
+    return theme.enabled ? `${theme.danger("Error:")} ${message}` : message;
+}
+function isColorEnabled(writer, env) {
+    if (env.NO_COLOR !== undefined) {
+        return false;
+    }
+    if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") {
+        return true;
+    }
+    return writer.isTTY === true;
+}
+function applyRgb(text, rgb, enabled) {
+    return applyCodes(text, [`\u001B[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`], enabled);
+}
+function applyCodes(text, codes, enabled) {
+    if (!enabled || !text) {
+        return text;
+    }
+    return `${codes.join("")}${text}${ANSI_RESET}`;
+}

package/dist/commands/analytics.d.ts

@@ -0,0 +1,131 @@
+import { Command } from "commander";
+import type { JsonValue } from "../vendor/core/index.js";
+import { type CliInvokeContext } from "../cli/client.js";
+import { type TerminalWriter } from "../cli/terminal.js";
+export interface AnalyticsCommandIO {
+    stdout: TerminalWriter;
+}
+export interface AnalyticsCommandContext extends CliInvokeContext {
+    io?: AnalyticsCommandIO;
+}
+export interface HistoricalReturnCommandOptions {
+    portfolio?: number;
+    asset?: string[];
+    from: string;
+    to: string;
+    json?: boolean;
+}
+export interface BetaCommandOptions {
+    portfolio?: number;
+    asset?: string[];
+    years?: string;
+    json?: boolean;
+}
+export interface VarCommandOptions {
+    portfolio?: number;
+    asset?: string[];
+    years?: string;
+    confidence?: string;
+    json?: boolean;
+}
+export interface HistoricalReturnHolding {
+    [key: string]: JsonValue;
+    ticker: string;
+    weight_pct: number;
+    total_return: number;
+    contribution: number;
+}
+export interface HistoricalReturnResponse {
+    [key: string]: JsonValue;
+    source_type: "saved_portfolio" | "ad_hoc";
+    portfolio_id: number | null;
+    portfolio_name: string | null;
+    requested_start_date: string;
+    requested_end_date: string;
+    effective_start_date: string;
+    effective_end_date: string;
+    total_return: number;
+    annualized_return: number;
+    max_drawdown: number;
+    daily_volatility: number;
+    annualized_volatility: number;
+    sharpe_ratio: number;
+    ibov_return: number;
+    cdi_return: number;
+    ipca_return: number;
+    holdings: HistoricalReturnHolding[];
+    summary_markdown: string;
+    assumptions: string[];
+    warnings: string[];
+}
+export interface BetaHolding {
+    [key: string]: JsonValue;
+    ticker: string;
+    weight_pct: number;
+    beta: number | null;
+    weighted_beta: number | null;
+    correlation: number | null;
+    asset_daily_volatility: number | null;
+    benchmark_daily_volatility: number | null;
+    last_updated: string | null;
+}
+export interface BetaResponse {
+    [key: string]: JsonValue;
+    source_type: "saved_portfolio" | "ad_hoc";
+    portfolio_id: number | null;
+    portfolio_name: string | null;
+    benchmark: "IBOV";
+    lookback_years: number;
+    beta: number;
+    correlation: number;
+    daily_volatility: number;
+    annualized_volatility: number;
+    long_exposure_pct: number;
+    short_exposure_pct: number;
+    total_weight_pct: number;
+    holdings: BetaHolding[];
+    summary_markdown: string;
+    assumptions: string[];
+    warnings: string[];
+}
+export interface VarHolding {
+    [key: string]: JsonValue;
+    ticker: string;
+    weight_pct: number;
+}
+export interface VarResponse {
+    [key: string]: JsonValue;
+    source_type: "saved_portfolio" | "ad_hoc";
+    portfolio_id: number | null;
+    portfolio_name: string | null;
+    lookback_years: number;
+    confidence_pct: number;
+    time_horizon: "1d";
+    var: number;
+    long_exposure_pct: number;
+    short_exposure_pct: number;
+    total_weight_pct: number;
+    holdings: VarHolding[];
+    histogram_data: JsonValue[];
+    summary_markdown: string;
+    assumptions: string[];
+    warnings: string[];
+}
+interface ParsedAssetInput {
+    [key: string]: JsonValue;
+    ticker: string;
+    weight_pct: number | null;
+}
+export declare function registerAnalyticsCommands(program: Command, context?: AnalyticsCommandContext): void;
+export declare function runHistoricalReturnCommand(options: HistoricalReturnCommandOptions, context?: AnalyticsCommandContext): Promise<void>;
+export declare function runBetaCommand(options: BetaCommandOptions, context?: AnalyticsCommandContext): Promise<void>;
+export declare function runVarCommand(options: VarCommandOptions, context?: AnalyticsCommandContext): Promise<void>;
+export declare function buildHistoricalReturnInput(options: HistoricalReturnCommandOptions): JsonValue;
+export declare function buildBetaInput(options: BetaCommandOptions): JsonValue;
+export declare function buildVarInput(options: VarCommandOptions): JsonValue;
+export declare function formatHistoricalReturnHuman(data: HistoricalReturnResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
+export declare function formatBetaHuman(data: BetaResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
+export declare function formatVarHuman(data: VarResponse, theme?: import("../cli/terminal.js").TerminalTheme): string;
+export declare function parseAssetSpec(rawAsset: string): ParsedAssetInput;
+export {};
+//# sourceMappingURL=analytics.d.ts.map

package/dist/commands/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/commands/analytics.ts"],"names":[],"mappings":"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"}

package/dist/commands/analytics.js

@@ -0,0 +1,291 @@
+import { invokeCliCapability } from "../cli/client.js";
+import { createCliValidationError } from "../cli/errors.js";
+import { createTerminalTheme } from "../cli/terminal.js";
+export function registerAnalyticsCommands(program, context = {}) {
+    const analyticsCommand = program
+        .command("analytics")
+        .description("Read portfolio analytics operations");
+    analyticsCommand
+        .command("historical-return")
+        .description("Calculate historical return for a saved portfolio or basket")
+        .option("--portfolio <id>", "Saved portfolio id", parsePositiveIntegerOption)
+        .option("--asset <asset>", "Repeatable asset input in TICKER[:WEIGHT_PCT] form", collectStringOption, [])
+        .requiredOption("--from <date>", "Inclusive start date in ISO format")
+        .requiredOption("--to <date>", "Inclusive end date in ISO format")
+        .option("--json", "Show JSON output")
+        .action(async (options) => {
+        await runHistoricalReturnCommand(options, context);
+    });
+    analyticsCommand
+        .command("beta")
+        .description("Calculate portfolio beta against IBOV")
+        .option("--portfolio <id>", "Saved portfolio id", parsePositiveIntegerOption)
+        .option("--asset <asset>", "Repeatable asset input in TICKER[:WEIGHT_PCT] form", collectStringOption, [])
+        .option("--years <years>", "Lookback window in years", "1")
+        .option("--json", "Show JSON output")
+        .action(async (options) => {
+        await runBetaCommand(options, context);
+    });
+    analyticsCommand
+        .command("var")
+        .description("Calculate one-day Value-at-Risk for a portfolio or basket")
+        .option("--portfolio <id>", "Saved portfolio id", parsePositiveIntegerOption)
+        .option("--asset <asset>", "Repeatable asset input in TICKER[:WEIGHT_PCT] form", collectStringOption, [])
+        .option("--years <years>", "Lookback window in years", "1")
+        .option("--confidence <confidence>", "Confidence level in percent", "95")
+        .option("--json", "Show JSON output")
+        .action(async (options) => {
+        await runVarCommand(options, context);
+    });
+}
+export async function runHistoricalReturnCommand(options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "analytics.historical-return",
+        input: buildHistoricalReturnInput(options),
+        env: context.env,
+        fetch: context.fetch,
+    });
+    if (options.json) {
+        stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
+        return;
+    }
+    stdout.write(`${formatHistoricalReturnHuman(response.data, theme)}\n`);
+}
+export async function runBetaCommand(options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "analytics.beta",
+        input: buildBetaInput(options),
+        env: context.env,
+        fetch: context.fetch,
+    });
+    if (options.json) {
+        stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
+        return;
+    }
+    stdout.write(`${formatBetaHuman(response.data, theme)}\n`);
+}
+export async function runVarCommand(options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "analytics.var",
+        input: buildVarInput(options),
+        env: context.env,
+        fetch: context.fetch,
+    });
+    if (options.json) {
+        stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
+        return;
+    }
+    stdout.write(`${formatVarHuman(response.data, theme)}\n`);
+}
+export function buildHistoricalReturnInput(options) {
+    const source = resolveAnalyticsSource(options.portfolio, options.asset ?? []);
+    return {
+        ...source,
+        start_date: options.from,
+        end_date: options.to,
+    };
+}
+export function buildBetaInput(options) {
+    const source = resolveAnalyticsSource(options.portfolio, options.asset ?? []);
+    return {
+        ...source,
+        years: parseYearsOption(options.years ?? "1"),
+    };
+}
+export function buildVarInput(options) {
+    const source = resolveAnalyticsSource(options.portfolio, options.asset ?? []);
+    return {
+        ...source,
+        years: parsePositiveIntegerOption(options.years ?? "1"),
+        confidence_pct: parseNumberOption(options.confidence ?? "95", "confidence"),
+    };
+}
+export function formatHistoricalReturnHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const lines = [
+        theme.label("Historical return"),
+        "",
+        formatSourceLabel(data, theme),
+        `${theme.label("Period:")} ${data.effective_start_date} → ${data.effective_end_date}`,
+        `${theme.label("Requested:")} ${data.requested_start_date} → ${data.requested_end_date}`,
+        "",
+        `${theme.label("Portfolio return:")} ${formatPercentValue(data.total_return)}`,
+        `${theme.label("Annualized return:")} ${formatPercentValue(data.annualized_return)}`,
+        `${theme.label("Max drawdown:")} ${formatPercentValue(data.max_drawdown)}`,
+        `${theme.label("Daily volatility:")} ${formatPercentValue(data.daily_volatility)}`,
+        `${theme.label("Annualized volatility:")} ${formatPercentValue(data.annualized_volatility)}`,
+        `${theme.label("Sharpe ratio:")} ${formatNumber(data.sharpe_ratio)}`,
+        "",
+        theme.label("Benchmarks"),
+        `  IBOV: ${formatPercentValue(data.ibov_return)}`,
+        `  CDI: ${formatPercentValue(data.cdi_return)}`,
+        `  IPCA: ${formatPercentValue(data.ipca_return)}`,
+        "",
+        theme.label("Holdings"),
+        ...data.holdings.map(item => `  - ${item.ticker}: weight=${formatPercentDirect(item.weight_pct)}, return=${formatPercentValue(item.total_return)}, contribution=${formatPercentValue(item.contribution)}`),
+    ];
+    pushNotes(lines, "Assumptions", data.assumptions, theme);
+    pushNotes(lines, "Warnings", data.warnings, theme);
+    return lines.join("\n");
+}
+export function formatBetaHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const lines = [
+        theme.label("Portfolio beta"),
+        "",
+        formatSourceLabel(data, theme),
+        `${theme.label("Benchmark:")} ${data.benchmark}`,
+        `${theme.label("Lookback:")} ${data.lookback_years}Y`,
+        "",
+        `${theme.label("Beta:")} ${formatNumber(data.beta)}`,
+        `${theme.label("Correlation:")} ${formatNumber(data.correlation)}`,
+        `${theme.label("Daily volatility:")} ${formatPercentValue(data.daily_volatility)}`,
+        `${theme.label("Annualized volatility:")} ${formatPercentValue(data.annualized_volatility)}`,
+        `${theme.label("Long exposure:")} ${formatPercentDirect(data.long_exposure_pct)}`,
+        `${theme.label("Short exposure:")} ${formatPercentDirect(data.short_exposure_pct)}`,
+        `${theme.label("Net exposure:")} ${formatPercentDirect(data.total_weight_pct)}`,
+        "",
+        theme.label("Holdings"),
+        ...data.holdings.map(item => `  - ${item.ticker}: weight=${formatPercentDirect(item.weight_pct)}, beta=${formatNullableNumber(item.beta)}, weighted=${formatNullableNumber(item.weighted_beta)}, corr=${formatNullableNumber(item.correlation)}`),
+    ];
+    pushNotes(lines, "Assumptions", data.assumptions, theme);
+    pushNotes(lines, "Warnings", data.warnings, theme);
+    return lines.join("\n");
+}
+export function formatVarHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const lines = [
+        theme.label("Portfolio VaR"),
+        "",
+        formatSourceLabel(data, theme),
+        `${theme.label("Lookback:")} ${data.lookback_years}Y`,
+        `${theme.label("Confidence:")} ${formatPercentDirect(data.confidence_pct)}`,
+        `${theme.label("Horizon:")} ${data.time_horizon}`,
+        "",
+        `${theme.label("VaR:")} ${formatPercentValue(data.var)}`,
+        `${theme.label("Long exposure:")} ${formatPercentDirect(data.long_exposure_pct)}`,
+        `${theme.label("Short exposure:")} ${formatPercentDirect(data.short_exposure_pct)}`,
+        `${theme.label("Net exposure:")} ${formatPercentDirect(data.total_weight_pct)}`,
+        "",
+        theme.label("Holdings"),
+        ...data.holdings.map(item => `  - ${item.ticker}: weight=${formatPercentDirect(item.weight_pct)}`),
+        "",
+        `${theme.label("Histogram bins:")} ${formatInteger(data.histogram_data.length)}`,
+    ];
+    pushNotes(lines, "Assumptions", data.assumptions, theme);
+    pushNotes(lines, "Warnings", data.warnings, theme);
+    return lines.join("\n");
+}
+export function parseAssetSpec(rawAsset) {
+    const normalized = rawAsset.trim();
+    if (!normalized) {
+        throw createCliValidationError("Asset input cannot be empty.");
+    }
+    const parts = normalized.split(":");
+    if (parts.length > 2) {
+        throw createCliValidationError(`Invalid asset input "${rawAsset}". Use TICKER[:WEIGHT_PCT].`);
+    }
+    const [rawTicker, rawWeight] = parts;
+    const ticker = rawTicker?.trim().toUpperCase();
+    if (!ticker) {
+        throw createCliValidationError(`Invalid asset input "${rawAsset}". Use TICKER[:WEIGHT_PCT].`);
+    }
+    if (rawWeight === undefined) {
+        return { ticker, weight_pct: null };
+    }
+    const weight_pct = Number(rawWeight.trim());
+    if (!Number.isFinite(weight_pct)) {
+        throw createCliValidationError(`Invalid asset weight in "${rawAsset}". Use TICKER[:WEIGHT_PCT].`);
+    }
+    return { ticker, weight_pct };
+}
+function resolveAnalyticsSource(portfolioId, assets) {
+    const hasPortfolio = portfolioId !== undefined;
+    const hasAssets = assets.length > 0;
+    if (hasPortfolio === hasAssets) {
+        throw createCliValidationError("Use exactly one source: --portfolio <id> or one or more --asset TICKER[:WEIGHT_PCT].");
+    }
+    if (hasPortfolio) {
+        return { portfolio_id: portfolioId };
+    }
+    return {
+        assets: assets.map(parseAssetSpec),
+    };
+}
+function collectStringOption(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function parsePositiveIntegerOption(value) {
+    const normalized = value.trim();
+    if (!/^\d+$/.test(normalized)) {
+        throw createCliValidationError("Value must be a positive integer.");
+    }
+    const parsed = Number(normalized);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw createCliValidationError("Value must be a positive integer.");
+    }
+    return parsed;
+}
+function parseYearsOption(value) {
+    const parsed = parsePositiveIntegerOption(value);
+    if (![1, 3, 5].includes(parsed)) {
+        throw createCliValidationError("Years must be one of: 1, 3, 5.");
+    }
+    return parsed;
+}
+function parseNumberOption(value, fieldName) {
+    const parsed = Number(value.trim());
+    if (!Number.isFinite(parsed)) {
+        throw createCliValidationError(`${fieldName} must be a number.`);
+    }
+    return parsed;
+}
+function formatSourceLabel(data, theme) {
+    if (data.source_type === "saved_portfolio" && data.portfolio_id !== null) {
+        const name = data.portfolio_name ? ` · ${data.portfolio_name}` : "";
+        return `${theme.bold(String(data.portfolio_id))}${theme.dim(name)}`;
+    }
+    return theme.bold("Ad-hoc basket");
+}
+function pushNotes(lines, title, items, theme) {
+    if (items.length === 0) {
+        return;
+    }
+    lines.push("");
+    lines.push(theme.label(title));
+    for (const item of items) {
+        lines.push(`  - ${item}`);
+    }
+}
+function formatNumber(value) {
+    return new Intl.NumberFormat("en-US", {
+        maximumFractionDigits: 4,
+    }).format(value);
+}
+function formatInteger(value) {
+    return new Intl.NumberFormat("en-US", {
+        maximumFractionDigits: 0,
+    }).format(value);
+}
+function formatNullableNumber(value) {
+    if (value === null) {
+        return "n/a";
+    }
+    return formatNumber(value);
+}
+function formatPercentValue(value) {
+    return `${new Intl.NumberFormat("en-US", {
+        maximumFractionDigits: 2,
+        minimumFractionDigits: 2,
+    }).format(value * 100)}%`;
+}
+function formatPercentDirect(value) {
+    return `${new Intl.NumberFormat("en-US", {
+        maximumFractionDigits: 2,
+        minimumFractionDigits: 2,
+    }).format(value)}%`;
+}

package/dist/commands/assets.d.ts

@@ -0,0 +1,69 @@
+import { Command } from "commander";
+import type { JsonValue } from "../vendor/core/index.js";
+import { assetOverviewSections } from "../vendor/core/capabilities/index.js";
+import { type CliInvokeContext } from "../cli/client.js";
+import { type TerminalWriter } from "../cli/terminal.js";
+export interface AssetsCommandIO {
+    stdout: TerminalWriter;
+}
+export interface AssetOverviewCommandOptions {
+    sections: string;
+    json?: boolean;
+}
+export interface AssetOverviewResponse {
+    asset: AssetOverviewAssetInfo | null;
+    as_of: AssetOverviewAsOfInfo | null;
+    price: AssetOverviewPrice | null;
+    performance: AssetOverviewValueItem[] | null;
+    momentum: AssetOverviewMomentumItem[] | null;
+    technicals: Record<string, JsonValue> | null;
+    risk: Record<string, JsonValue> | null;
+    fundamentals: Record<string, JsonValue> | null;
+    rankings: AssetOverviewRankingItem[] | null;
+    candles: JsonValue[] | null;
+}
+interface AssetOverviewAssetInfo {
+    symbol: string;
+    name?: string | null;
+    type?: string | null;
+}
+interface AssetOverviewAsOfInfo {
+    price_date: string;
+    last_updated: string;
+}
+interface AssetOverviewPrice {
+    close: number;
+    open: number;
+    high: number;
+    low: number;
+    volume: number | null;
+    prev_close?: number | null;
+    change_pct?: number | null;
+}
+interface AssetOverviewValueItem {
+    id: string;
+    label: string;
+    value?: number | null;
+}
+interface AssetOverviewMomentumItem {
+    id: string;
+    label: string;
+    regression_type: string;
+    momentum?: number | null;
+    r_squared?: number | null;
+}
+interface AssetOverviewRankingItem {
+    id: string;
+    label: string;
+    position?: number | null;
+    total?: number | null;
+}
+export interface AssetsCommandContext extends CliInvokeContext {
+    io?: AssetsCommandIO;
+}
+export declare function registerAssetsCommands(program: Command, context?: AssetsCommandContext): void;
+export declare function runAssetOverviewCommand(ticker: string, options: AssetOverviewCommandOptions, context?: AssetsCommandContext): Promise<void>;
+export declare function parseAssetOverviewSections(rawSections: string): (typeof assetOverviewSections)[number][];
+export declare function formatAssetOverviewHuman(data: AssetOverviewResponse, sections: readonly (typeof assetOverviewSections)[number][], theme?: import("../cli/terminal.js").TerminalTheme): string;
+export {};
+//# sourceMappingURL=assets.d.ts.map

package/dist/commands/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/commands/assets.ts"],"names":[],"mappings":"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"}