@quantbrasil/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/commands/portfolios.js

@@ -2,65 +2,156 @@ import { invokeCliCapability } from "../cli/client.js";
 import { createCliMutationFailedError, createCliValidationError, } from "../cli/errors.js";
 import { createTerminalTheme } from "../cli/terminal.js";
 export function registerPortfoliosCommands(program, context = {}) {
-    const portfoliosCommand = program
-        .command("portfolios")
-        .description("Manage saved portfolios");
-    portfoliosCommand
+    const watchlistsCommand = program
+        .command("watchlists")
+        .description("Manage watchlists for tracking ideas and filters");
+    watchlistsCommand
         .command("list")
-        .description("List saved portfolios for authenticated user")
+        .description("List watchlists for authenticated user")
         .option("--json", "Show JSON output")
         .action(async (options) => {
-        await runPortfolioListCommand(options, context);
+        await runWatchlistListCommand(options, context);
     });
-    portfoliosCommand
+    watchlistsCommand
         .command("get")
-        .description("Get one saved portfolio by id")
-        .argument("<portfolio-id>", "Saved portfolio id", parsePortfolioIdArgument)
+        .description("Get one watchlist by id")
+        .argument("<watchlist-id>", "Watchlist id", parsePortfolioIdArgument)
         .option("--json", "Show JSON output")
         .action(async (portfolioId, options) => {
-        await runPortfolioGetCommand(portfolioId, options, context);
+        await runWatchlistGetCommand(portfolioId, options, context);
     });
-    portfoliosCommand
+    watchlistsCommand
         .command("create")
-        .description("Create a new portfolio")
-        .argument("<name>", "Portfolio name")
+        .description("Create a new watchlist")
+        .argument("<name>", "Watchlist name")
         .option("--json", "Show JSON output")
         .action(async (name, options) => {
-        await runPortfolioCreateCommand(name, options, context);
+        await runWatchlistCreateCommand(name, options, context);
     });
-    portfoliosCommand
+    watchlistsCommand
         .command("rename")
-        .description("Rename an existing portfolio")
-        .argument("<portfolio-id>", "Saved portfolio id", parsePortfolioIdArgument)
-        .argument("<name>", "New portfolio name")
+        .description("Rename an existing watchlist")
+        .argument("<watchlist-id>", "Watchlist id", parsePortfolioIdArgument)
+        .argument("<name>", "New watchlist name")
         .option("--json", "Show JSON output")
         .action(async (portfolioId, name, options) => {
-        await runPortfolioRenameCommand(portfolioId, name, options, context);
+        await runWatchlistRenameCommand(portfolioId, name, options, context);
     });
-    portfoliosCommand
+    watchlistsCommand
         .command("add-assets")
-        .description("Add one or more monitored tickers to a portfolio")
-        .argument("<portfolio-id>", "Saved portfolio id", parsePortfolioIdArgument)
+        .description("Add one or more monitored tickers to a watchlist")
+        .argument("<watchlist-id>", "Watchlist id", parsePortfolioIdArgument)
         .argument("<ticker...>", "One or more tickers to add")
         .option("--json", "Show JSON output")
         .action(async (portfolioId, symbols, options) => {
-        await runPortfolioAddAssetsCommand(portfolioId, symbols, options, context);
+        await runWatchlistAddAssetsCommand(portfolioId, symbols, options, context);
     });
-    portfoliosCommand
+    watchlistsCommand
         .command("remove-assets")
-        .description("Remove one or more monitored tickers from a portfolio")
-        .argument("<portfolio-id>", "Saved portfolio id", parsePortfolioIdArgument)
+        .description("Remove one or more monitored tickers from a watchlist")
+        .argument("<watchlist-id>", "Watchlist id", parsePortfolioIdArgument)
         .argument("<ticker...>", "One or more tickers to remove")
         .option("--json", "Show JSON output")
         .action(async (portfolioId, symbols, options) => {
-        await runPortfolioRemoveAssetsCommand(portfolioId, symbols, options, context);
+        await runWatchlistRemoveAssetsCommand(portfolioId, symbols, options, context);
     });
+    const holdingsCommand = program
+        .command("holdings")
+        .description("Manage holdings for investable metrics");
+    holdingsCommand
+        .command("list")
+        .description("List holdings for authenticated user")
+        .option("--json", "Show JSON output")
+        .action(async (options) => {
+        await runHoldingListCommand(options, context);
+    });
+    holdingsCommand
+        .command("get")
+        .description("Get one holding by id")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, options) => {
+        await runHoldingGetCommand(portfolioId, options, context);
+    });
+    holdingsCommand
+        .command("create")
+        .description("Create a new holding")
+        .argument("<name>", "Holding name")
+        .option("--mode <mode>", "Initial mode: target or position", "target")
+        .option("--target <target>", "Initial target weight in TICKER:WEIGHT_PCT form", collectStringOption, [])
+        .option("--json", "Show JSON output")
+        .action(async (name, options) => {
+        await runHoldingCreateCommand(name, options, context);
+    });
+    holdingsCommand
+        .command("rename")
+        .description("Rename an existing holding")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .argument("<name>", "New holding name")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, name, options) => {
+        await runHoldingRenameCommand(portfolioId, name, options, context);
+    });
+    holdingsCommand
+        .command("set-targets")
+        .description("Set target weights for a holding")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .argument("<target...>", "One or more target weights in TICKER:WEIGHT_PCT form")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, targets, options) => {
+        await runHoldingSetTargetsCommand(portfolioId, targets, options, context);
+    });
+    holdingsCommand
+        .command("set-positions")
+        .description("Set position quantities for a holding")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .argument("<position...>", "One or more position quantities in TICKER:QUANTITY form")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, positions, options) => {
+        await runHoldingSetPositionsCommand(portfolioId, positions, options, context);
+    });
+    holdingsCommand
+        .command("historical-return")
+        .description("Calculate historical return for a saved holding")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .option("--from <date>", "Inclusive start date in ISO format")
+        .option("--to <date>", "Inclusive end date in ISO format")
+        .option("--period <period>", "Lookback period such as 1y, 3y, 5y, or 6m")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, options) => {
+        await runHoldingHistoricalReturnCommand(portfolioId, options, context);
+    });
+    holdingsCommand
+        .command("beta")
+        .description("Calculate holding beta against IBOV")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .option("--years <years>", "Lookback window in years", "1")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, options) => {
+        await runHoldingBetaCommand(portfolioId, options, context);
+    });
+    holdingsCommand
+        .command("var")
+        .description("Calculate one-day Value-at-Risk for a holding")
+        .argument("<holding-id>", "Holding id", parsePortfolioIdArgument)
+        .option("--years <years>", "Lookback window in years", "1")
+        .option("--confidence <confidence>", "Confidence level in percent", "95")
+        .option("--json", "Show JSON output")
+        .action(async (portfolioId, options) => {
+        await runHoldingVarCommand(portfolioId, options, context);
+    });
+}
+export async function runWatchlistListCommand(options, context = {}) {
+    await runPortfolioListLikeCommand("watchlists.list", "Watchlists", options, context);
 }
-export async function runPortfolioListCommand(options, context = {}) {
+export async function runHoldingListCommand(options, context = {}) {
+    await runPortfolioListLikeCommand("holdings.list", "Holdings", options, context);
+}
+async function runPortfolioListLikeCommand(capability, title, options, context) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
     const response = await invokeCliCapability({
-        capability: "portfolios.list",
+        capability,
         env: context.env,
         fetch: context.fetch,
     });
@@ -68,13 +159,19 @@ export async function runPortfolioListCommand(options, context = {}) {
         stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
         return;
     }
-    stdout.write(`${formatPortfolioListHuman(response.data, theme)}\n`);
+    stdout.write(`${formatPortfolioListHuman(response.data, theme, title)}\n`);
+}
+export async function runWatchlistGetCommand(portfolioId, options, context = {}) {
+    await runPortfolioGetLikeCommand("watchlists.get", "Watchlist", portfolioId, options, context);
+}
+export async function runHoldingGetCommand(portfolioId, options, context = {}) {
+    await runPortfolioGetLikeCommand("holdings.get", "Holding", portfolioId, options, context);
 }
-export async function runPortfolioGetCommand(portfolioId, options, context = {}) {
+async function runPortfolioGetLikeCommand(capability, title, portfolioId, options, context) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
     const response = await invokeCliCapability({
-        capability: "portfolios.get",
+        capability,
         input: {
             portfolio_id: portfolioId,
         },
@@ -85,26 +182,74 @@ export async function runPortfolioGetCommand(portfolioId, options, context = {})
         stdout.write(`${JSON.stringify(response.data, null, 2)}\n`);
         return;
     }
-    stdout.write(`${formatPortfolioGetHuman(response.data, theme)}\n`);
+    stdout.write(`${formatPortfolioGetHuman(response.data, theme, title)}\n`);
+}
+export async function runWatchlistCreateCommand(name, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "watchlists.create",
+        input: {
+            name: parsePortfolioNameArgument(name),
+        },
+        env: context.env,
+        fetch: context.fetch,
+    });
+    writeMutationResponse(response.data, options.json, stdout, theme);
 }
-export async function runPortfolioCreateCommand(name, options, context = {}) {
+export async function runHoldingCreateCommand(name, options, context = {}) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const defaultAllocationInput = parseHoldingModeOption(options.mode ?? "target");
+    const targets = parseTargetArguments(options.target ?? []);
+    if (targets.length > 0 && defaultAllocationInput === "POSITION") {
+        throw createCliValidationError("Initial targets require target mode.");
+    }
     const response = await invokeCliCapability({
-        capability: "portfolios.create",
+        capability: "holdings.create",
         input: {
             name: parsePortfolioNameArgument(name),
+            default_allocation_input: defaultAllocationInput,
+            ...(targets.length > 0 ? { targets } : {}),
         },
         env: context.env,
         fetch: context.fetch,
     });
     writeMutationResponse(response.data, options.json, stdout, theme);
 }
-export async function runPortfolioRenameCommand(portfolioId, name, options, context = {}) {
+export async function runHoldingSetTargetsCommand(portfolioId, targets, options, context = {}) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
     const response = await invokeCliCapability({
-        capability: "portfolios.rename",
+        capability: "holdings.set-targets",
+        input: {
+            portfolio_id: portfolioId,
+            targets: parseTargetArguments(targets),
+        },
+        env: context.env,
+        fetch: context.fetch,
+    });
+    writeMutationResponse(response.data, options.json, stdout, theme);
+}
+export async function runHoldingSetPositionsCommand(portfolioId, positions, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "holdings.set-positions",
+        input: {
+            portfolio_id: portfolioId,
+            positions: parsePositionArguments(positions),
+        },
+        env: context.env,
+        fetch: context.fetch,
+    });
+    writeMutationResponse(response.data, options.json, stdout, theme);
+}
+export async function runWatchlistRenameCommand(portfolioId, name, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "watchlists.rename",
         input: {
             portfolio_id: portfolioId,
             name: parsePortfolioNameArgument(name),
@@ -114,11 +259,25 @@ export async function runPortfolioRenameCommand(portfolioId, name, options, cont
     });
     writeMutationResponse(response.data, options.json, stdout, theme);
 }
-export async function runPortfolioAddAssetsCommand(portfolioId, symbols, options, context = {}) {
+export async function runHoldingRenameCommand(portfolioId, name, options, context = {}) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
     const response = await invokeCliCapability({
-        capability: "portfolios.add-assets",
+        capability: "holdings.rename",
+        input: {
+            portfolio_id: portfolioId,
+            name: parsePortfolioNameArgument(name),
+        },
+        env: context.env,
+        fetch: context.fetch,
+    });
+    writeMutationResponse(response.data, options.json, stdout, theme);
+}
+export async function runWatchlistAddAssetsCommand(portfolioId, symbols, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "watchlists.add-assets",
         input: {
             portfolio_id: portfolioId,
             symbols: parseSymbolArguments(symbols),
@@ -128,11 +287,11 @@ export async function runPortfolioAddAssetsCommand(portfolioId, symbols, options
     });
     writeMutationResponse(response.data, options.json, stdout, theme);
 }
-export async function runPortfolioRemoveAssetsCommand(portfolioId, symbols, options, context = {}) {
+export async function runWatchlistRemoveAssetsCommand(portfolioId, symbols, options, context = {}) {
     const stdout = context.io?.stdout ?? process.stdout;
     const theme = createTerminalTheme(stdout, context.env ?? process.env);
     const response = await invokeCliCapability({
-        capability: "portfolios.remove-assets",
+        capability: "watchlists.remove-assets",
         input: {
             portfolio_id: portfolioId,
             symbols: parseSymbolArguments(symbols),
@@ -142,15 +301,72 @@ export async function runPortfolioRemoveAssetsCommand(portfolioId, symbols, opti
     });
     writeMutationResponse(response.data, options.json, stdout, theme);
 }
-export function formatPortfolioListHuman(data, theme = createTerminalTheme(process.stdout)) {
+export async function runHoldingHistoricalReturnCommand(portfolioId, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const dateRange = resolveHistoricalReturnDateRange(options, context.now ?? new Date());
+    const response = await invokeCliCapability({
+        capability: "holdings.historical-return",
+        input: {
+            portfolio_id: portfolioId,
+            start_date: dateRange.start_date,
+            end_date: dateRange.end_date,
+        },
+        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 runHoldingBetaCommand(portfolioId, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "holdings.beta",
+        input: {
+            portfolio_id: portfolioId,
+            years: parseYearsOption(options.years ?? "1"),
+        },
+        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 runHoldingVarCommand(portfolioId, options, context = {}) {
+    const stdout = context.io?.stdout ?? process.stdout;
+    const theme = createTerminalTheme(stdout, context.env ?? process.env);
+    const response = await invokeCliCapability({
+        capability: "holdings.var",
+        input: {
+            portfolio_id: portfolioId,
+            years: parsePositiveIntegerOption(options.years ?? "1"),
+            confidence_pct: parseNumberOption(options.confidence ?? "95", "confidence"),
+        },
+        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 formatPortfolioListHuman(data, theme = createTerminalTheme(process.stdout), title = "Saved items") {
     const lines = [
-        theme.label("Portfolios"),
+        theme.label(title),
         "",
         `${theme.label("Total:")} ${formatInteger(data.total)}`,
     ];
     if (data.portfolios.length === 0) {
         lines.push("");
-        lines.push("No saved portfolios.");
+        lines.push(`No ${title.toLowerCase()} saved.`);
         return lines.join("\n");
     }
     for (const portfolio of data.portfolios) {
@@ -163,17 +379,17 @@ export function formatPortfolioListHuman(data, theme = createTerminalTheme(proce
     }
     return lines.join("\n");
 }
-export function formatPortfolioGetHuman(data, theme = createTerminalTheme(process.stdout)) {
+export function formatPortfolioGetHuman(data, theme = createTerminalTheme(process.stdout), title = "Saved item") {
     const { portfolio } = data;
     const lines = [
-        theme.label("Portfolio"),
+        theme.label(title),
         "",
         `${theme.bold(String(portfolio.id))} ${theme.dim("·")} ${portfolio.name}`,
         `${theme.label("Assets:")} ${formatInteger(portfolio.symbols.length)}`,
     ];
     if (portfolio.symbols.length === 0) {
         lines.push("");
-        lines.push("No assets in this portfolio.");
+        lines.push("No assets saved.");
         return lines.join("\n");
     }
     lines.push("");
@@ -193,21 +409,24 @@ export function formatPortfolioGetHuman(data, theme = createTerminalTheme(proces
     return lines.join("\n");
 }
 export function formatPortfolioMutationHuman(data, theme = createTerminalTheme(process.stdout)) {
+    const label = formatPortfolioKind(data.portfolio);
     const lines = [
         data.ok
-            ? theme.success(theme.bold("Portfolio"))
-            : theme.danger(theme.bold("Portfolio mutation failed")),
+            ? theme.success(theme.bold(label))
+            : theme.danger(theme.bold("Mutation failed")),
         "",
         data.summary_markdown,
         "",
-        `${theme.bold(String(data.portfolio.id))} ${theme.dim("·")} ${data.portfolio.name || "Portfolio"}`,
+        `${theme.bold(String(data.portfolio.id))} ${theme.dim("·")} ${data.portfolio.name || label}`,
         `${theme.label("Assets:")} ${formatInteger(data.portfolio.symbols.length)}`,
     ];
     if (data.portfolio.symbols.length > 0) {
         lines.push("");
         lines.push(theme.label("Holdings"));
         for (const symbol of data.portfolio.symbols) {
-            lines.push(`  - ${symbol}`);
+            const weight = data.portfolio.weights?.[symbol];
+            const suffix = weight === undefined ? "" : `: ${formatNumber(weight)}%`;
+            lines.push(`  - ${symbol}${suffix}`);
         }
     }
     return lines.join("\n");
@@ -215,24 +434,113 @@ export function formatPortfolioMutationHuman(data, theme = createTerminalTheme(p
 function parsePortfolioIdArgument(value) {
     const normalized = value.trim();
     if (!/^\d+$/.test(normalized)) {
-        throw createCliValidationError("Portfolio id must be a positive integer.");
+        throw createCliValidationError("Id must be a positive integer.");
     }
     const portfolioId = Number(normalized);
     if (!Number.isSafeInteger(portfolioId) || portfolioId <= 0) {
-        throw createCliValidationError("Portfolio id must be a positive integer.");
+        throw createCliValidationError("Id must be a positive integer.");
     }
     return portfolioId;
 }
 function parsePortfolioNameArgument(value) {
     const normalized = value.trim();
     if (!normalized) {
-        throw createCliValidationError("Portfolio name cannot be empty.");
+        throw createCliValidationError("Name cannot be empty.");
     }
     if (normalized.length > 100) {
-        throw createCliValidationError("Portfolio name cannot exceed 100 characters.");
+        throw createCliValidationError("Name cannot exceed 100 characters.");
     }
     return normalized;
 }
+function parseHoldingModeOption(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "target" || normalized === "target-weight") {
+        return "TARGET_WEIGHT";
+    }
+    if (normalized === "position" || normalized === "positions") {
+        return "POSITION";
+    }
+    throw createCliValidationError("Holding mode must be target or position.");
+}
+function collectStringOption(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function parseTargetArguments(values) {
+    if (values.length === 0) {
+        return [];
+    }
+    const targets = values.map(parseTargetArgument);
+    const tickers = targets.map(target => target.ticker);
+    if (new Set(tickers).size !== tickers.length) {
+        throw createCliValidationError("Do not send duplicated tickers.");
+    }
+    return targets;
+}
+function parseTargetArgument(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw createCliValidationError("Target input cannot be empty.");
+    }
+    const parts = normalized.split(":");
+    if (parts.length !== 2) {
+        throw createCliValidationError(`Invalid target input "${value}". Use TICKER:WEIGHT_PCT.`);
+    }
+    const [rawTicker, rawWeight] = parts;
+    const ticker = rawTicker?.trim().toUpperCase();
+    if (!ticker) {
+        throw createCliValidationError(`Invalid target input "${value}". Use TICKER:WEIGHT_PCT.`);
+    }
+    const weight_pct = Number(rawWeight?.trim());
+    if (!Number.isFinite(weight_pct) || weight_pct < 0 || weight_pct > 100) {
+        throw createCliValidationError(`Invalid target weight in "${value}". Use a number from 0 to 100.`);
+    }
+    return { ticker, weight_pct };
+}
+function parsePositionArguments(values) {
+    if (values.length === 0) {
+        return [];
+    }
+    const positions = values.map(parsePositionArgument);
+    const tickers = positions.map(position => position.ticker);
+    if (new Set(tickers).size !== tickers.length) {
+        throw createCliValidationError("Do not send duplicated tickers.");
+    }
+    return positions;
+}
+function parsePositionArgument(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw createCliValidationError("Position input cannot be empty.");
+    }
+    const parts = normalized.split(":");
+    if (parts.length !== 2 && parts.length !== 3) {
+        throw createCliValidationError(`Invalid position input "${value}". Use TICKER:QUANTITY.`);
+    }
+    const rawTicker = parts[0];
+    const rawQuantity = parts.length === 2
+        ? parts[1]
+        : parsePositionMode(value, parts[1], parts[2]);
+    const ticker = rawTicker?.trim().toUpperCase();
+    if (!ticker) {
+        throw createCliValidationError(`Invalid position input "${value}". Use TICKER:QUANTITY.`);
+    }
+    const quantity = Number(rawQuantity?.trim());
+    if (!Number.isFinite(quantity) || quantity <= 0) {
+        throw createCliValidationError(`Invalid position quantity in "${value}". Use a number greater than 0.`);
+    }
+    return { ticker, quantity };
+}
+function parsePositionMode(originalValue, rawMode, rawQuantity) {
+    const mode = rawMode?.trim().toLowerCase();
+    if (mode === "qty" || mode === "quantity") {
+        return rawQuantity;
+    }
+    if (mode === "value" || mode === "amount") {
+        throw createCliValidationError("Position values are not supported in the public CLI. Use TICKER:QUANTITY.");
+    }
+    throw createCliValidationError(`Invalid position input "${originalValue}". Use TICKER:QUANTITY.`);
+}
 function parseSymbolArguments(values) {
     const symbols = values.map(symbol => symbol.trim().toUpperCase());
     if (symbols.length === 0 || symbols.some(symbol => symbol.length === 0)) {
@@ -252,6 +560,85 @@ function dedupeSymbols(symbols) {
     }
     return deduped;
 }
+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;
+}
+export function resolveHistoricalReturnDateRange(options, now = new Date()) {
+    const from = options.from?.trim();
+    const to = options.to?.trim();
+    const period = options.period?.trim().toLowerCase();
+    const hasExplicitRange = Boolean(from || to);
+    if (period && hasExplicitRange) {
+        throw createCliValidationError("Use either --period or both --from and --to, not both.");
+    }
+    if (period) {
+        return resolvePeriodDateRange(period, now);
+    }
+    if (from && to) {
+        return {
+            start_date: from,
+            end_date: to,
+        };
+    }
+    throw createCliValidationError("Use --period, or provide both --from and --to.");
+}
+function resolvePeriodDateRange(period, now) {
+    const match = /^(\d+)([my])$/.exec(period);
+    if (!match) {
+        throw createCliValidationError("Period must use the form <number>m or <number>y, for example 6m or 1y.");
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    if (!Number.isSafeInteger(amount) || amount <= 0) {
+        throw createCliValidationError("Period amount must be a positive integer.");
+    }
+    const endDate = toLocalCalendarDate(now);
+    const startDate = subtractUtcCalendarPeriod(endDate, amount, unit);
+    return {
+        start_date: formatIsoDate(startDate),
+        end_date: formatIsoDate(endDate),
+    };
+}
+function subtractUtcCalendarPeriod(endDate, amount, unit) {
+    const targetYear = unit === "y" ? endDate.getUTCFullYear() - amount : endDate.getUTCFullYear();
+    const targetMonth = unit === "m" ? endDate.getUTCMonth() - amount : endDate.getUTCMonth();
+    return createClampedUtcDate(targetYear, targetMonth, endDate.getUTCDate());
+}
+function createClampedUtcDate(year, monthIndex, day) {
+    const firstOfTargetMonth = new Date(Date.UTC(year, monthIndex, 1));
+    const normalizedYear = firstOfTargetMonth.getUTCFullYear();
+    const normalizedMonth = firstOfTargetMonth.getUTCMonth();
+    const lastDayOfTargetMonth = new Date(Date.UTC(normalizedYear, normalizedMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(normalizedYear, normalizedMonth, Math.min(day, lastDayOfTargetMonth)));
+}
+function toLocalCalendarDate(value) {
+    return new Date(Date.UTC(value.getFullYear(), value.getMonth(), value.getDate()));
+}
+function formatIsoDate(value) {
+    return value.toISOString().slice(0, 10);
+}
+function parseNumberOption(value, fieldName) {
+    const parsed = Number(value.trim());
+    if (!Number.isFinite(parsed)) {
+        throw createCliValidationError(`${fieldName} must be a number.`);
+    }
+    return parsed;
+}
 function writeMutationResponse(data, json, stdout, theme) {
     if (!data.ok) {
         if (!json) {
@@ -283,9 +670,124 @@ function formatWeightsInline(portfolio) {
     })
         .join(", ");
 }
+function formatPortfolioKind(portfolio) {
+    if (portfolio.kind === "WATCHLIST") {
+        return "Watchlist";
+    }
+    if (portfolio.kind === "HOLDING") {
+        return "Holding";
+    }
+    return "Saved item";
+}
 function createCountSuffix(count) {
     return count === 1 ? "(1 asset)" : `(${count} assets)`;
 }
+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("Holding 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("Holding 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("Holding 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");
+}
+function formatSourceLabel(data, theme) {
+    const id = data.portfolio_id === null ? "n/a" : String(data.portfolio_id);
+    const name = data.portfolio_name ? ` · ${data.portfolio_name}` : "";
+    return `${theme.bold(id)}${theme.dim(name)}`;
+}
+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 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)}%`;
+}
 function formatInteger(value) {
     return new Intl.NumberFormat("en-US", {
         maximumFractionDigits: 0,