@pungoyal/kite-cli 0.1.0

package/dist/commands/portfolio.js

@@ -0,0 +1,286 @@
+import { PRODUCTS } from '../core/api.js';
+import { UsageError } from '../core/errors.js';
+import { money, percent, quantity, rupees, signedRupees } from '../output/format.js';
+import { heading, printTable, renderKeyValue } from '../output/table.js';
+import { confirmAction } from '../safety.js';
+export const portfolioCommands = (program, run) => {
+    program
+        .command('holdings')
+        .description('Show your long-term holdings')
+        .option('--sort <field>', 'Sort by: symbol, value, pnl, day', 'value')
+        .action(run(holdings));
+    program
+        .command('positions')
+        .description('Show your open positions')
+        .option('--day', 'Show intraday positions instead of net')
+        .action(run(positions));
+    program
+        .command('funds')
+        .description('Show available margin and funds')
+        .option('--segment <segment>', 'equity or commodity')
+        .action(run(funds));
+    program
+        .command('authorise')
+        .alias('authorize')
+        .description('Authorise holdings at the depository so they can be sold (recovers from HTTP 428)')
+        .argument('[isins...]', 'Specific ISINs to authorise. Omit to authorise the whole demat account.')
+        .action(run(authoriseHoldings));
+    const convert = program
+        .command('convert')
+        .description('Convert a position between products (e.g. MIS to CNC)')
+        .argument('<instrument>', 'Instrument as EXCHANGE:SYMBOL, e.g. NSE:INFY')
+        .requiredOption('--quantity <n>', 'Quantity to convert')
+        .requiredOption('--from <product>', `Current product (${PRODUCTS.join(', ')})`)
+        .requiredOption('--to <product>', `Target product (${PRODUCTS.join(', ')})`)
+        .option('--transaction-type <type>', 'BUY or SELL', 'BUY')
+        .option('--position-type <type>', 'overnight or day', 'day')
+        .action(run(convertPosition));
+    void convert;
+};
+async function holdings(ctx, opts) {
+    ctx.requireSession();
+    const rows = await ctx.api.getHoldings(ctx.signal);
+    const sorted = [...rows].sort(sorter(opts.sort ?? 'value'));
+    const totalInvested = sorted.reduce((sum, h) => sum + h.average_price * h.quantity, 0);
+    const totalCurrent = sorted.reduce((sum, h) => sum + h.last_price * h.quantity, 0);
+    const totalPnl = totalCurrent - totalInvested;
+    const totalDayChange = sorted.reduce((sum, h) => sum + h.day_change * h.quantity, 0);
+    const columns = [
+        { header: 'Symbol', value: (h, io) => io.bold(h.tradingsymbol) },
+        { header: 'Exch', value: (h) => h.exchange },
+        {
+            header: 'Qty',
+            value: (h) => quantity(h.quantity + h.t1_quantity),
+            align: 'right',
+        },
+        { header: 'Avg', value: (h) => money(h.average_price), align: 'right' },
+        { header: 'LTP', value: (h) => money(h.last_price), align: 'right' },
+        {
+            header: 'Value',
+            value: (h) => money(h.last_price * h.quantity),
+            align: 'right',
+        },
+        {
+            header: 'P&L',
+            value: (h, io) => io.signed(h.pnl, signedRupees(h.pnl)),
+            align: 'right',
+        },
+        {
+            header: 'P&L %',
+            value: (h, io) => {
+                const invested = h.average_price * h.quantity;
+                const pct = invested === 0 ? 0 : (h.pnl / invested) * 100;
+                return io.signed(pct, percent(pct));
+            },
+            align: 'right',
+        },
+        {
+            header: 'Day',
+            value: (h, io) => io.signed(h.day_change_percentage, percent(h.day_change_percentage)),
+            align: 'right',
+        },
+    ];
+    printTable(ctx.io, sorted, columns, rows, {
+        compact: ctx.config.output.compact,
+        empty: 'No holdings.',
+    });
+    if (ctx.io.json)
+        return;
+    const { io } = ctx;
+    io.line(renderKeyValue(io, [
+        ['Invested', rupees(totalInvested)],
+        ['Current', rupees(totalCurrent)],
+        [
+            'P&L',
+            io.signed(totalPnl, `${signedRupees(totalPnl)}  ${percent(totalInvested === 0 ? 0 : (totalPnl / totalInvested) * 100)}`),
+        ],
+        ["Day's change", io.signed(totalDayChange, signedRupees(totalDayChange))],
+    ]));
+}
+function sorter(field) {
+    switch (field) {
+        case 'symbol':
+            return (a, b) => a.tradingsymbol.localeCompare(b.tradingsymbol);
+        case 'pnl':
+            return (a, b) => b.pnl - a.pnl;
+        case 'day':
+            return (a, b) => b.day_change_percentage - a.day_change_percentage;
+        case 'value':
+            return (a, b) => b.last_price * b.quantity - a.last_price * a.quantity;
+        default:
+            throw new UsageError(`Unknown sort field "${field}".`, 'Valid fields: symbol, value, pnl, day.');
+    }
+}
+async function positions(ctx, opts) {
+    ctx.requireSession();
+    const result = await ctx.api.getPositions(ctx.signal);
+    const rows = opts.day ? result.day : result.net;
+    const columns = [
+        { header: 'Symbol', value: (p, io) => io.bold(p.tradingsymbol) },
+        { header: 'Exch', value: (p) => p.exchange },
+        { header: 'Product', value: (p) => p.product ?? '—' },
+        {
+            header: 'Qty',
+            value: (p, io) => io.signed(p.quantity, quantity(p.quantity)),
+            align: 'right',
+        },
+        { header: 'Avg', value: (p) => money(p.average_price), align: 'right' },
+        { header: 'LTP', value: (p) => money(p.last_price), align: 'right' },
+        {
+            header: 'P&L',
+            value: (p, io) => io.signed(p.pnl, signedRupees(p.pnl)),
+            align: 'right',
+        },
+        {
+            header: 'M2M',
+            value: (p, io) => io.signed(p.m2m, signedRupees(p.m2m)),
+            align: 'right',
+        },
+    ];
+    // The JSON payload is always the array of positions being displayed. Emitting
+    // the whole {net, day} envelope for one flag and a bare array for the other
+    // would force every consumer to branch on the flag they passed.
+    printTable(ctx.io, rows, columns, rows, {
+        compact: ctx.config.output.compact,
+        empty: opts.day ? 'No intraday positions.' : 'No open positions.',
+    });
+    if (ctx.io.json)
+        return;
+    const totalPnl = rows.reduce((sum, p) => sum + p.pnl, 0);
+    const { io } = ctx;
+    io.line(renderKeyValue(io, [['Total P&L', io.signed(totalPnl, signedRupees(totalPnl))]]));
+    const open = rows.filter((p) => p.quantity !== 0);
+    if (open.length > 0 && !opts.day) {
+        io.note('');
+        io.info('To exit a position, place an opposite order with the SAME product — otherwise it opens a new position.');
+    }
+}
+async function funds(ctx, opts) {
+    ctx.requireSession();
+    const margins = await ctx.api.getMargins(ctx.signal);
+    if (ctx.io.json) {
+        ctx.io.writeJson(margins);
+        return;
+    }
+    const { io } = ctx;
+    const segments = [
+        ['Equity', margins.equity],
+        ['Commodity', margins.commodity],
+    ];
+    for (const [name, segment] of segments) {
+        if (!segment)
+            continue;
+        if (opts.segment && opts.segment.toLowerCase() !== name.toLowerCase())
+            continue;
+        io.line(heading(io, name));
+        io.line(renderKeyValue(io, [
+            ['Available', rupees(segment.net)],
+            ['Cash', rupees(segment.available?.cash)],
+            ['Opening balance', rupees(segment.available?.opening_balance)],
+            ['Collateral', rupees(segment.available?.collateral)],
+            ['Used', rupees(segment.utilised?.debits)],
+            ['SPAN', rupees(segment.utilised?.span)],
+            ['Exposure', rupees(segment.utilised?.exposure)],
+            ['Option premium', rupees(segment.utilised?.option_premium)],
+            ['Realised P&L', io.signed(segment.utilised?.m2m_realised ?? 0, signedRupees(segment.utilised?.m2m_realised))],
+            [
+                'Unrealised P&L',
+                io.signed(segment.utilised?.m2m_unrealised ?? 0, signedRupees(segment.utilised?.m2m_unrealised)),
+            ],
+        ]));
+    }
+}
+/**
+ * Recover from HTTP 428 — "N quantity needs authorisation at depository".
+ *
+ * Selling shares held in demat requires a CDSL authorisation the user must
+ * complete in a browser. We request an id, then hand them the URL. The
+ * authorisation is valid until 5:30 PM the same day.
+ */
+async function authoriseHoldings(ctx, _opts, command) {
+    ctx.requireSession();
+    const isins = command.args.map((isin) => isin.trim().toUpperCase()).filter(Boolean);
+    const result = await ctx.api.authoriseHoldings(isins, ctx.signal);
+    const url = ctx.api.authorisationUrl(result.request_id);
+    if (ctx.io.json) {
+        ctx.io.writeJson({ request_id: result.request_id, url, isins });
+        return;
+    }
+    const { io } = ctx;
+    io.note('');
+    io.info(isins.length > 0
+        ? `Authorising ${isins.length} instrument(s): ${isins.join(', ')}`
+        : 'Authorising your entire demat account.');
+    io.note('');
+    io.note(`  ${io.bold(url)}`);
+    io.note('');
+    io.info('Open that URL to complete the authorisation with CDSL.');
+    io.info('It stays valid until 5:30 PM IST today.');
+    const { openBrowser } = await import('../core/auth.js');
+    if (await openBrowser(url)) {
+        io.success('Opened your browser.');
+    }
+}
+async function convertPosition(ctx, opts, command) {
+    ctx.requireSession();
+    const instrument = command.args[0] ?? '';
+    const { parseInstrumentKey } = await import('../core/instruments.js');
+    const parsed = parseInstrumentKey(instrument);
+    const qty = Number(opts.quantity);
+    if (!Number.isInteger(qty) || qty <= 0) {
+        throw new UsageError('--quantity must be a positive whole number.');
+    }
+    const from = normaliseProduct(opts.from);
+    const to = normaliseProduct(opts.to);
+    if (from === to) {
+        throw new UsageError('--from and --to are the same product; nothing to convert.');
+    }
+    const transactionType = (opts.transactionType ?? 'BUY').toUpperCase();
+    if (transactionType !== 'BUY' && transactionType !== 'SELL') {
+        throw new UsageError('--transaction-type must be BUY or SELL.');
+    }
+    const positionType = (opts.positionType ?? 'day').toLowerCase();
+    if (positionType !== 'day' && positionType !== 'overnight') {
+        throw new UsageError('--position-type must be day or overnight.');
+    }
+    await confirmAction(ctx, {
+        action: `Convert ${qty} ${parsed.tradingsymbol} from ${from} to ${to}`,
+        mutatesOrders: true,
+        details: [
+            ['Instrument', `${parsed.exchange}:${parsed.tradingsymbol}`],
+            ['Quantity', quantity(qty)],
+            ['From product', from],
+            ['To product', to],
+            ['Transaction', transactionType],
+            ['Position type', positionType],
+        ].map(([label, value]) => ({ label: label, value: value })),
+    });
+    if (ctx.options.dryRun)
+        return;
+    await ctx.api.convertPosition({
+        tradingsymbol: parsed.tradingsymbol,
+        exchange: parsed.exchange,
+        transaction_type: transactionType,
+        position_type: positionType,
+        quantity: qty,
+        old_product: from,
+        new_product: to,
+    }, ctx.signal);
+    if (ctx.io.json) {
+        ctx.io.writeJson({
+            converted: true,
+            tradingsymbol: parsed.tradingsymbol,
+            from,
+            to,
+            quantity: qty,
+        });
+        return;
+    }
+    ctx.io.success(`Converted ${qty} ${parsed.tradingsymbol} from ${from} to ${to}.`);
+}
+function normaliseProduct(value) {
+    const upper = value.toUpperCase();
+    if (PRODUCTS.includes(upper))
+        return upper;
+    throw new UsageError(`Unknown product "${value}".`, `Valid products: ${PRODUCTS.join(', ')}.`);
+}

package/dist/commands/types.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import type { Context } from '../context.js';
+/**
+ * A command handler receives a fully-built context plus its own parsed options.
+ *
+ * Commander types `.opts<T>()` as a caller-supplied cast rather than inferring
+ * from the `.option()` calls, so nothing verifies that `Options` matches what
+ * was declared. Commands that take non-trivial input therefore re-validate
+ * through a zod schema at the top of the handler, which converts a silent type
+ * lie into a runtime guarantee.
+ */
+export type Handler<Options = Record<string, unknown>> = (ctx: Context, options: Options, command: Command) => Promise<void> | void;
+/** Wraps a handler so it is given a context and has its errors reported. */
+export type Runner = <Options>(handler: Handler<Options>) => (...args: unknown[]) => Promise<void>;
+/** Registers a group of related commands on the root program. */
+export type CommandFactory = (program: Command, run: Runner) => void;

package/dist/commands/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/watch.d.ts

@@ -0,0 +1,18 @@
+import type { CommandFactory } from './types.js';
+/**
+ * Live streaming quotes.
+ *
+ * Two design choices worth stating, both about not melting the terminal:
+ *
+ *  1. **Tick rate is decoupled from render rate.** Kite pushes far faster than
+ *     a human can read. Ticks accumulate into a map and we repaint on a fixed
+ *     interval (default 4/sec). Rendering per tick would burn CPU and produce
+ *     an unreadable blur.
+ *
+ *  2. **The visible row count is capped below the terminal height.** When a
+ *     live-updating region grows taller than the terminal, the renderer is
+ *     forced into full-screen repaints and flicker becomes very hard to
+ *     eliminate. Staying under the fold avoids the problem entirely rather
+ *     than fighting it.
+ */
+export declare const watchCommands: CommandFactory;

package/dist/commands/watch.js

@@ -0,0 +1,285 @@
+import logUpdate from 'log-update';
+import { getSecret } from '../core/credentials.js';
+import { ExitCode, KiteCliError, UsageError } from '../core/errors.js';
+import { formatInstrumentKey, parseInstrumentKey } from '../core/instruments.js';
+import { MAX_INSTRUMENTS_PER_CONNECTION, Ticker } from '../core/ticker.js';
+import { compactNumber, money, percent, timeOnly } from '../output/format.js';
+import { renderTable } from '../output/table.js';
+/**
+ * Live streaming quotes.
+ *
+ * Two design choices worth stating, both about not melting the terminal:
+ *
+ *  1. **Tick rate is decoupled from render rate.** Kite pushes far faster than
+ *     a human can read. Ticks accumulate into a map and we repaint on a fixed
+ *     interval (default 4/sec). Rendering per tick would burn CPU and produce
+ *     an unreadable blur.
+ *
+ *  2. **The visible row count is capped below the terminal height.** When a
+ *     live-updating region grows taller than the terminal, the renderer is
+ *     forced into full-screen repaints and flicker becomes very hard to
+ *     eliminate. Staying under the fold avoids the problem entirely rather
+ *     than fighting it.
+ */
+export const watchCommands = (program, run) => {
+    program
+        .command('watch')
+        .description('Stream live quotes in a self-updating table')
+        .argument('[instruments...]', 'Instruments to watch, e.g. NSE:INFY NSE:TCS')
+        .option('--holdings', 'Watch everything in your holdings')
+        .option('--positions', 'Watch your open positions')
+        .option('-m, --mode <mode>', 'Streaming mode: ltp, quote, or full', 'quote')
+        .option('--fps <n>', 'Screen repaints per second', '4')
+        .option('--orders', 'Also print live order updates')
+        .action(run(watch));
+};
+async function watch(ctx, opts, command) {
+    ctx.requireSession();
+    const mode = (opts.mode ?? 'quote').toLowerCase();
+    if (mode !== 'ltp' && mode !== 'quote' && mode !== 'full') {
+        throw new UsageError('--mode must be ltp, quote, or full.');
+    }
+    // --- resolve the watchlist ---------------------------------------------
+    const keys = new Set();
+    for (const arg of command.args) {
+        const parsed = parseInstrumentKey(arg);
+        keys.add(formatInstrumentKey(parsed.exchange, parsed.tradingsymbol));
+    }
+    if (opts.holdings) {
+        for (const holding of await ctx.api.getHoldings(ctx.signal)) {
+            keys.add(formatInstrumentKey(holding.exchange, holding.tradingsymbol));
+        }
+    }
+    if (opts.positions) {
+        const positions = await ctx.api.getPositions(ctx.signal);
+        for (const position of positions.net) {
+            if (position.quantity !== 0) {
+                keys.add(formatInstrumentKey(position.exchange, position.tradingsymbol));
+            }
+        }
+    }
+    if (keys.size === 0) {
+        throw new UsageError('Nothing to watch.', 'Pass instruments (e.g. `kite watch NSE:INFY`), or use --holdings / --positions.');
+    }
+    if (keys.size > MAX_INSTRUMENTS_PER_CONNECTION) {
+        throw new UsageError(`Kite allows at most ${MAX_INSTRUMENTS_PER_CONNECTION} instruments per connection; you asked for ${keys.size}.`);
+    }
+    // The WebSocket accepts ONLY numeric instrument tokens, never symbols.
+    await ctx.instruments.load({ signal: ctx.signal });
+    const watchlist = [];
+    for (const key of keys) {
+        watchlist.push({ key, token: ctx.instruments.requireToken(key) });
+    }
+    const tokenToKey = new Map(watchlist.map((entry) => [entry.token, entry.key]));
+    // --- credentials for the socket ----------------------------------------
+    const stored = await getSecret('access_token', { env: ctx.env });
+    if (!stored) {
+        throw new KiteCliError('No access token available for streaming.', ExitCode.Auth, 'Run `kite login`.');
+    }
+    const ticker = new Ticker({
+        apiKey: ctx.client.apiKey,
+        accessToken: stored.value,
+        endpoints: ctx.endpoints,
+        // The sandbox socket will not authenticate without a user_id, which the
+        // official SDKs do not send.
+        userId: ctx.env === 'sandbox' ? ctx.session?.userId : undefined,
+    });
+    // --- JSON mode: stream NDJSON, no dashboard ----------------------------
+    if (ctx.io.json || !ctx.io.interactive) {
+        await streamJson(ctx, ticker, watchlist, tokenToKey, mode, opts.orders ?? false);
+        return;
+    }
+    await streamDashboard(ctx, ticker, watchlist, tokenToKey, mode, opts);
+}
+/** Non-TTY / --json: one JSON object per line, suitable for piping. */
+async function streamJson(ctx, ticker, watchlist, tokenToKey, mode, showOrders) {
+    ticker.on('ticks', (ticks) => {
+        for (const tick of ticks) {
+            ctx.io.writeJson({
+                ...tick,
+                instrument: tokenToKey.get(tick.instrumentToken),
+            });
+        }
+    });
+    if (showOrders) {
+        ticker.on('orderUpdate', (order) => ctx.io.writeJson({ type: 'order', data: order }));
+    }
+    ticker.on('connect', () => ticker.subscribe(watchlist.map((w) => w.token), mode));
+    // An EventEmitter with no 'error' listener RETHROWS the error, which here
+    // would escape the socket callback and take the process down mid-stream.
+    // Errors are recoverable — the ticker reconnects — so report and continue.
+    ticker.on('error', (err) => ctx.io.warn(err.message));
+    ticker.on('reconnect', ({ attempt, delayMs }) => ctx.io.warn(`Disconnected; reconnecting (attempt ${attempt}, ${Math.round(delayMs / 1000)}s)…`));
+    // Without this the reconnect budget can be exhausted while the command sits
+    // waiting on a signal that will never arrive, hanging a pipeline forever.
+    const exhausted = new Promise((resolve) => {
+        ticker.once('noreconnect', () => {
+            ctx.io.error('Gave up reconnecting to the Kite ticker.');
+            process.exitCode = ExitCode.Upstream;
+            resolve();
+        });
+    });
+    ticker.connect();
+    await Promise.race([waitForSignal(ctx.signal), exhausted]);
+    ticker.close();
+}
+async function streamDashboard(ctx, ticker, watchlist, _tokenToKey, mode, opts) {
+    const { io } = ctx;
+    const fps = clamp(Number(opts.fps ?? 4) || 4, 1, 20);
+    const latest = new Map();
+    const previousPrice = new Map();
+    const flashUntil = new Map();
+    const orderLog = [];
+    let status = 'connecting…';
+    let lastUpdate;
+    ticker.on('connect', () => {
+        status = 'live';
+        ticker.subscribe(watchlist.map((w) => w.token), mode);
+    });
+    ticker.on('reconnect', ({ attempt, delayMs }) => {
+        status = `reconnecting (attempt ${attempt}, ${Math.round(delayMs / 1000)}s)`;
+    });
+    ticker.on('close', () => {
+        if (status === 'live')
+            status = 'disconnected';
+    });
+    ticker.on('noreconnect', () => {
+        status = 'gave up reconnecting';
+    });
+    ticker.on('error', (err) => {
+        status = `error: ${err.message}`;
+    });
+    ticker.on('ticks', (ticks) => {
+        // Buffer only — the render loop decides when to paint.
+        for (const tick of ticks) {
+            const previous = latest.get(tick.instrumentToken);
+            if (previous && previous.lastPrice !== tick.lastPrice) {
+                previousPrice.set(tick.instrumentToken, previous.lastPrice);
+                flashUntil.set(tick.instrumentToken, {
+                    direction: tick.lastPrice > previous.lastPrice ? 1 : -1,
+                    at: Date.now(),
+                });
+            }
+            latest.set(tick.instrumentToken, tick);
+        }
+        lastUpdate = new Date();
+    });
+    if (opts.orders) {
+        ticker.on('orderUpdate', (payload) => {
+            const order = payload;
+            orderLog.unshift(`${timeOnly(new Date())}  ${order.tradingsymbol ?? '?'}  ${order.status ?? '?'}  ${order.filled_quantity ?? 0} filled`);
+            orderLog.length = Math.min(orderLog.length, 5);
+        });
+    }
+    // Cap rows so the live region never exceeds the terminal height — this is
+    // what keeps the repaint incremental instead of full-screen.
+    const chromeRows = 6 + (opts.orders ? 7 : 0);
+    const maxRows = Math.max(3, io.rows - chromeRows);
+    const visible = watchlist.slice(0, maxRows);
+    const hidden = watchlist.length - visible.length;
+    const render = () => {
+        const now = Date.now();
+        const rows = visible.map((entry) => ({
+            key: entry.key,
+            tick: latest.get(entry.token),
+            flash: flashUntil.get(entry.token),
+        }));
+        const columns = [
+            { header: 'Instrument', value: (r, io) => io.bold(r.key) },
+            {
+                header: 'LTP',
+                value: (r, io) => {
+                    if (!r.tick)
+                        return io.dim('—');
+                    const text = money(r.tick.lastPrice);
+                    // Flash the cell briefly on a price change so movement is visible
+                    // even when the number barely shifts.
+                    if (r.flash && now - r.flash.at < 400) {
+                        return r.flash.direction === 1 ? io.green(text) : io.red(text);
+                    }
+                    return text;
+                },
+                align: 'right',
+            },
+            {
+                header: 'Change',
+                value: (r, io) => r.tick?.change === undefined ? io.dim('—') : io.signed(r.tick.change, percent(r.tick.change)),
+                align: 'right',
+            },
+            {
+                header: 'Open',
+                value: (r) => money(r.tick?.ohlc?.open),
+                align: 'right',
+            },
+            {
+                header: 'High',
+                value: (r) => money(r.tick?.ohlc?.high),
+                align: 'right',
+            },
+            { header: 'Low', value: (r) => money(r.tick?.ohlc?.low), align: 'right' },
+            {
+                header: 'Close',
+                value: (r) => money(r.tick?.ohlc?.close),
+                align: 'right',
+            },
+            ...(mode !== 'ltp'
+                ? [
+                    {
+                        header: 'Volume',
+                        value: (r) => compactNumber(r.tick?.volume),
+                        align: 'right',
+                    },
+                ]
+                : []),
+        ];
+        const statusColour = status === 'live'
+            ? io.green('● live')
+            : status.startsWith('error')
+                ? io.red(`● ${status}`)
+                : io.yellow(`● ${status}`);
+        const parts = [
+            `${statusColour}  ${io.dim(`${watchlist.length} instruments · ${mode} mode · ${lastUpdate ? timeOnly(lastUpdate) : 'waiting for data'}`)}`,
+            renderTable(io, rows, columns, { compact: ctx.config.output.compact }),
+        ];
+        if (hidden > 0) {
+            parts.push(io.dim(`  …and ${hidden} more (terminal too short to show them all)`));
+        }
+        if (opts.orders && orderLog.length > 0) {
+            parts.push(`\n${io.bold('Order updates')}\n${orderLog.map((line) => `  ${io.dim(line)}`).join('\n')}`);
+        }
+        parts.push(io.dim('\n  Ctrl-C to stop'));
+        logUpdate(parts.join('\n'));
+    };
+    // The dashboard already listens for 'error', so the emitter never rethrows.
+    // It still needs to stop waiting once reconnection is abandoned.
+    const exhausted = new Promise((resolve) => {
+        ticker.once('noreconnect', () => {
+            process.exitCode = ExitCode.Upstream;
+            resolve();
+        });
+    });
+    ticker.connect();
+    const timer = setInterval(render, Math.round(1000 / fps));
+    render();
+    try {
+        await Promise.race([waitForSignal(ctx.signal), exhausted]);
+    }
+    finally {
+        clearInterval(timer);
+        ticker.close();
+        // Leave the final frame on screen rather than erasing it.
+        logUpdate.done();
+    }
+}
+function waitForSignal(signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}

package/dist/context.d.ts

@@ -0,0 +1,40 @@
+import { KiteApi } from './core/api.js';
+import { KiteClient } from './core/client.js';
+import { type Config, type Endpoints, type Environment } from './core/config.js';
+import { InstrumentStore } from './core/instruments.js';
+import { type SessionMeta } from './core/session.js';
+import { Io, type IoStreams } from './output/io.js';
+/**
+ * Everything a command needs, assembled once per invocation.
+ *
+ * Construction is deliberately lazy about authentication: `kite login`,
+ * `kite config` and `kite --help` must work with no session at all, so the
+ * client is built without a token and commands call `requireSession()` when
+ * they actually need one.
+ */
+export interface GlobalOptions {
+    json?: boolean;
+    color?: 'auto' | 'always' | 'never';
+    quiet?: boolean;
+    debug?: boolean;
+    env?: string;
+    yes?: boolean;
+    dryRun?: boolean;
+}
+export interface Context {
+    io: Io;
+    config: Config;
+    env: Environment;
+    endpoints: Endpoints;
+    client: KiteClient;
+    api: KiteApi;
+    instruments: InstrumentStore;
+    session: SessionMeta | null;
+    options: GlobalOptions;
+    signal: AbortSignal;
+    /** Throw unless there is a live session. */
+    requireSession: () => SessionMeta;
+    /** Resolve the API secret, for flows that need to sign (login only). */
+    requireApiSecret: () => Promise<string>;
+}
+export declare function createContext(options: GlobalOptions, signal: AbortSignal, streams?: IoStreams): Promise<Context>;