@quantbrasil/cli 0.1.0-beta.1 → 0.1.0-beta.11

package/skills/quantbrasil/references/workflows.md

@@ -1,15 +1,28 @@
 # Workflows
 
+## Choose command from user intent
+
+- asset price, quote, or daily move → `market price`
+- supported assets, tickers, or market universe → `market assets`
+- asset performance, technicals, risk, fundamentals, or ranking → `assets overview`
+- current ordered asset lists such as Magic Formula, momentum, Low Risk, or user rankings → `rankings list`, then `rankings current`
+- watchlist details or changes → `watchlists ...`
+- holding details or changes → `holdings ...`
+- holding return, beta, risk, VaR, or comparison → `holdings historical-return|beta|var`
+- indicator screening over saved asset sets → `screening universes`, `screening indicators` when needed, then `screening run`
+- cointegration or Long & Short between two explicit assets → `cointegration pair`
+
 ## Find supported ticker, then get price
 
 Use this when user gives company theme, partial name, or market universe question.
 
 ```bash
-quantbrasil market assets --type B3
+quantbrasil market assets --search PETR
 quantbrasil market price PETR4
 ```
 
 If exact ticker already known, skip discovery and go straight to `market price`.
+Use `--type` when the user asks for a whole supported universe.
 
 ## Get price on specific date
 
@@ -26,6 +39,9 @@ Use absolute ISO dates.
 - need richer analysis for one asset → `assets overview`
 
 Do not jump to `assets overview` if price-only answer is enough.
+Do not use generic web or finance search for QuantBrasil-supported market data
+unless the CLI is unavailable, the requested data is outside the supported
+surface, or the user explicitly asks for an external source.
 
 ## Cost-aware `assets overview` section choice
 
@@ -48,52 +64,130 @@ Guidance:
 
 Avoid asking for every section unless user clearly wants full report.
 
-## Analyze saved portfolio
+## Get current ranked assets
 
-1. Discover portfolio id.
-2. Inspect holdings if needed.
-3. Run analytics.
+Use this when the user asks for an ordered list such as top Magic Formula,
+momentum leaders, dividend-yield leaders, Low Risk, Momentum Double, or a saved
+user ranking.
 
 ```bash
-quantbrasil portfolios list
-quantbrasil portfolios get 93
-quantbrasil analytics historical-return --portfolio 93 --from 2025-01-01 --to 2026-01-01
-quantbrasil analytics beta --portfolio 93 --years 1
-quantbrasil analytics var --portfolio 93 --years 1 --confidence 95
+quantbrasil rankings list
+quantbrasil rankings current --system momentum-90d --top 20
+quantbrasil rankings current --system magic-formula --top 10
+quantbrasil rankings current --system low-risk --top 30
+quantbrasil rankings current --id 123 --top 20
 ```
 
-## Analyze ad-hoc basket
+Rules:
+
+- rankings answer order-first questions
+- system rankings use their slug from `rankings list`
+- user rankings use their numeric id from `rankings list`
+- use exactly one selector: `--system <slug>` or `--id <id>`
+- do not call user rankings "factor:" in command syntax; ranking fatorial is a saved user ranking
+- use `--json` if another step needs to parse tickers, ranks, or ordering metrics
+- do not route ranking-first questions through screening unless the user asks for indicator conditions
+
+## Analyze saved holding
+
+1. Discover holding id.
+2. Inspect the holding if needed.
+3. Run the holding metric.
+
+```bash
+quantbrasil holdings list
+quantbrasil holdings get 93
+quantbrasil holdings historical-return 93 --period 1y
+quantbrasil holdings beta 93 --years 1
+quantbrasil holdings var 93 --years 1 --confidence 95
+```
+
+## Run indicator screening
+
+1. Discover available universes.
+2. Discover available indicators when the filter JSON is not already known.
+3. Pick exactly one system portfolio, watchlist, or holding.
+4. Run screening with a full `ScreenerRequest` JSON file.
+
+```bash
+quantbrasil screening universes
+quantbrasil screening indicators
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening.json
+quantbrasil screening run --watchlist 93 --query-file ./screening.json --limit 25
+quantbrasil screening run --holding 182 --query-file ./screening.json --sort ticker
+```
+
+Rules:
+
+- screening universes are portfolio-backed only: system portfolios, watchlists, or holdings
+- a holding used as a screening universe contributes only its asset set
+- do not invent ad-hoc ticker-list screening commands
+- load `references/screening.md` for IFR/RSI examples and full JSON payloads
+- use `--json` when the result will be parsed by an agent or script
+
+## Run pair cointegration / Long & Short
+
+Use this when the user asks to run cointegração, cointegration, Long & Short,
+long and short, long-short, pair trading statistics, z-score, p-value, or
+half-life for two explicit assets.
+
+```bash
+quantbrasil cointegration pair PETR4 VALE3
+quantbrasil cointegration pair PETR4 VALE3 --window 120
+quantbrasil cointegration pair PETR4 VALE3 --json
+```
+
+Rules:
+
+- require two explicit tickers
+- frame Long & Short phrasing as pair analysis, not order execution or a guaranteed trade recommendation
+- use `market assets --search` first only if a ticker is ambiguous
+- do not invent a universe scan command for "quais pares cointegrados"; the public CLI currently supports explicit pairs
+- use `--json` if the z-score or beta series will feed another calculation
+
+## Analyze a theoretical composition
 
-Use repeated `--asset TICKER[:WEIGHT_PCT]`.
+Create a holding with target weights, then run holding metrics on its id.
 
 Rules:
 
-- if weights omitted, backend may assume equal weights
-- negative weights allowed for hedge / short exposure
+- `holdings create` returns the holding id
+- use `holdings set-targets` to replace target weights later
+- use `holdings set-positions` for actual share/unit/coin quantities
 - `beta` only accepts `--years 1|3|5`
 - `var --confidence` takes percent like `95` or `99`
 
 Example:
 
 ```bash
-quantbrasil analytics historical-return --asset VALE3:50 --asset PRIO3:50 --from 2025-01-01 --to 2026-01-01
-quantbrasil analytics beta --asset VALE3:120 --asset WINFUT:-20 --years 1
-quantbrasil analytics var --asset VALE3:120 --asset WINFUT:-20 --years 1 --confidence 99
+quantbrasil holdings create "Teórica energia" --target VALE3:50 --target PRIO3:50
+quantbrasil holdings historical-return 93 --from 2025-01-01 --to 2026-01-01
+quantbrasil holdings beta 93 --years 1
+quantbrasil holdings var 93 --years 1 --confidence 99
 ```
 
-## Modify saved portfolio
+## Modify watchlists and holdings
 
 Use explicit mutation commands. Do not retry failed mutations automatically.
 
 ```bash
-quantbrasil portfolios create "Dividendos"
-quantbrasil portfolios rename 93 "Longo Prazo"
-quantbrasil portfolios add-assets 93 PETR4 VALE3
-quantbrasil portfolios remove-assets 93 PETR4
+quantbrasil watchlists create "Dividendos"
+quantbrasil watchlists rename 93 "Longo Prazo"
+quantbrasil watchlists add-assets 93 PETR4 VALE3
+quantbrasil watchlists remove-assets 93 PETR4
+
+quantbrasil holdings create "Longo Prazo"
+quantbrasil holdings create "Longo Prazo" --target PETR4:50 --target VALE3:50
+quantbrasil holdings create "Carteira Real" --mode position
+quantbrasil holdings rename 182 "Carteira Real"
+quantbrasil holdings set-targets 182 PETR4:50 VALE3:50
+quantbrasil holdings set-positions 182 PRIO3:1600 BTC-USD:0.25 QQQ:10
 ```
 
 Rules:
 
-- use `portfolios list` first if user names a portfolio instead of giving id
+- use `watchlists list` or `holdings list` first if the user names a saved object instead of giving id
 - confirm destructive intent before removing assets when user request is ambiguous
+- positions are quantity-only in the public CLI; do not pass monetary values as positions
+- target weights and positions are independent; updating positions does not clear target weights
 - use `--json` only when structured output is needed

package/dist/commands/analytics.d.ts

@@ -1,131 +0,0 @@
-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

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

package/dist/commands/analytics.js

@@ -1,291 +0,0 @@
-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)}%`;
-}