@pungoyal/kite-cli 0.2.1 → 0.4.0

package/dist/commands/completion.js

@@ -0,0 +1,240 @@
+import { Command } from 'commander';
+import { UsageError } from '../core/errors.js';
+/**
+ * Shell completion scripts, generated from the live command tree.
+ *
+ * Rather than hand-maintain a completion file per shell — the exact docs-rot
+ * trap a CLI that places real orders cannot afford — this walks the same
+ * registration path run() uses (with a no-op runner) and emits command names,
+ * subcommand names, and long flags straight from it. A new command or flag is
+ * completable as soon as it is added; the only user step is to regenerate after
+ * upgrading, the same contract gh, rustup, and kubectl ship.
+ *
+ * Depth is intentionally capped at command → subcommand + flags, which covers
+ * every path this CLI has (`config set`, `margins order`, `orders place`).
+ */
+const SHELLS = ['bash', 'zsh', 'fish'];
+export const completionCommands = (program, run) => {
+    program
+        .command('completion')
+        .summary('Print a shell completion script')
+        .description('Print a shell completion script for bash, zsh, or fish.\n\n' +
+        'The shell is auto-detected from $SHELL when omitted. Install with, e.g.:\n' +
+        '  bash   kite completion bash >> ~/.bash_completion\n' +
+        '  zsh    kite completion zsh  > ~/.zfunc/_kite   (with ~/.zfunc on your fpath)\n' +
+        '  fish   kite completion fish > ~/.config/fish/completions/kite.fish')
+        .argument('[shell]', 'Target shell: bash, zsh, or fish')
+        .action(run(completion));
+};
+async function completion(ctx, _opts, command) {
+    const requested = (command.args[0] ?? detectShell())?.toLowerCase();
+    if (!requested) {
+        throw new UsageError('Could not detect your shell from $SHELL.', `Name it explicitly: kite completion <${SHELLS.join('|')}>.`);
+    }
+    if (!isShell(requested)) {
+        throw new UsageError(`Unsupported shell "${requested}".`, `Supported shells: ${SHELLS.join(', ')}.`);
+    }
+    const model = await buildModel();
+    // The script is data: it goes to stdout so `kite completion bash > file`
+    // captures exactly the script and nothing else.
+    ctx.io.line(renderScript(requested, model));
+}
+/**
+ * Build the completion model by registering the real command tree onto a
+ * throwaway program. The runner is a no-op: completion needs each command's
+ * name, options, and subcommands, never its behaviour.
+ */
+export async function buildModel() {
+    const { applyGlobalOptions, registerCommands } = await import('./register.js');
+    const program = new Command('kite');
+    applyGlobalOptions(program);
+    const noop = () => async () => { };
+    await registerCommands(program, noop);
+    const descriptions = {};
+    const subcommands = {};
+    const commands = [];
+    for (const cmd of realCommands(program)) {
+        commands.push(cmd.name());
+        descriptions[cmd.name()] = summaryOf(cmd);
+        const subs = realCommands(cmd);
+        if (subs.length > 0) {
+            subcommands[cmd.name()] = subs.map((s) => s.name());
+            for (const sub of subs)
+                descriptions[`${cmd.name()} ${sub.name()}`] = summaryOf(sub);
+        }
+    }
+    return { commands, subcommands, globalFlags: longFlags(program), descriptions };
+}
+/** Child commands, minus commander's auto-generated `help` command. */
+function realCommands(cmd) {
+    return cmd.commands.filter((c) => c.name() !== 'help');
+}
+function longFlags(cmd) {
+    return cmd.options.map((o) => o.long).filter((long) => Boolean(long));
+}
+function summaryOf(cmd) {
+    // summary() is the short one-liner; description() may be a multi-line block.
+    const text = cmd.summary() || cmd.description().split('\n')[0] || '';
+    return sanitize(text);
+}
+/**
+ * Strip characters that would break a quoted description in a shell script.
+ * Backslash is included: fish treats it as an escape inside single quotes, so a
+ * description ending in `\` would escape the closing quote and corrupt the line.
+ */
+function sanitize(text) {
+    return text
+        .replace(/['\\\n\r]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// --- rendering -------------------------------------------------------------
+export function renderScript(shell, model) {
+    // Sanitise at the rendering boundary, not only in buildModel(), so renderScript
+    // can never emit a script broken by a stray quote or backslash regardless of
+    // how its model was built.
+    const safe = {
+        ...model,
+        descriptions: Object.fromEntries(Object.entries(model.descriptions).map(([key, value]) => [key, sanitize(value)])),
+    };
+    switch (shell) {
+        case 'bash':
+            return renderBash(safe);
+        case 'zsh':
+            return renderZsh(safe);
+        case 'fish':
+            return renderFish(safe);
+    }
+}
+function renderBash(model) {
+    // A `case` for subcommands rather than an associative array, so this works on
+    // the bash 3.2 that macOS still ships (declare -A is bash 4+).
+    const subCases = Object.entries(model.subcommands)
+        .map(([cmd, subs]) => `    ${cmd}) echo "${subs.join(' ')}" ;;`)
+        .join('\n');
+    return `# kite bash completion. Source it, or install with:
+#   kite completion bash >> ~/.bash_completion
+_kite_subcommands() {
+  case "$1" in
+${subCases}
+  esac
+}
+
+_kite() {
+  local cur cmd sub i w
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  # First two non-flag words after "kite" are the command and its subcommand.
+  cmd=""; sub=""
+  for (( i=1; i < COMP_CWORD; i++ )); do
+    w="\${COMP_WORDS[i]}"
+    [[ "$w" == -* ]] && continue
+    if [[ -z "$cmd" ]]; then cmd="$w"; else sub="$w"; break; fi
+  done
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "${model.globalFlags.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${model.commands.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  if [[ -z "$sub" ]]; then
+    local subs
+    subs="$(_kite_subcommands "$cmd")"
+    [[ -n "$subs" ]] && COMPREPLY=( $(compgen -W "$subs" -- "$cur") )
+  fi
+}
+complete -F _kite kite
+`;
+}
+function renderZsh(model) {
+    const topDescribe = model.commands.map((name) => `    '${name}:${model.descriptions[name] ?? ''}'`).join('\n');
+    // Build the sub arrays inline per command so descriptions survive.
+    const subBlocks = Object.entries(model.subcommands)
+        .map(([cmd, subs]) => {
+        const described = subs.map((s) => `'${s}:${model.descriptions[`${cmd} ${s}`] ?? ''}'`).join(' ');
+        return `    ${cmd}) local -a subs=(${described}); _describe 'subcommand' subs ;;`;
+    })
+        .join('\n');
+    return `#compdef kite
+# kite zsh completion. Install with:
+#   kite completion zsh > "\${fpath[1]}/_kite"
+_kite() {
+  local -a commands
+  commands=(
+${topDescribe}
+  )
+
+  # Flags complete anywhere the current word starts with a dash. \`compadd --\`
+  # is required: a bare \`compadd --json\` makes zsh parse the flags as its own
+  # options instead of as candidates.
+  if [[ \${words[CURRENT]} == -* ]]; then
+    compadd -- ${model.globalFlags.join(' ')}
+    return
+  fi
+
+  # Top-level command name.
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+
+  # Subcommands only at the subcommand position; deeper positions offer nothing,
+  # which caps depth at command -> subcommand as documented.
+  if (( CURRENT == 3 )); then
+    case \${words[2]} in
+${subBlocks}
+    esac
+  fi
+}
+compdef _kite kite
+`;
+}
+function renderFish(model) {
+    const lines = [
+        '# kite fish completion. Install with:',
+        '#   kite completion fish > ~/.config/fish/completions/kite.fish',
+        '',
+        '# No file completion by default; kite takes symbols and subcommands, not paths.',
+        'complete -c kite -f',
+        '',
+        '# Top-level commands (only before a subcommand is typed).',
+    ];
+    for (const name of model.commands) {
+        lines.push(`complete -c kite -n __fish_use_subcommand -a ${name} -d '${model.descriptions[name] ?? ''}'`);
+    }
+    lines.push('', '# Subcommands (only until one is chosen, capping depth at command → subcommand).');
+    for (const [cmd, subs] of Object.entries(model.subcommands)) {
+        // __fish_seen_subcommand_from is true anywhere the token appears on the
+        // line, so without the `and not …` guard `kite config set <TAB>` would keep
+        // re-offering config's subcommands. Excluding the subcommands themselves
+        // stops that once one has been typed.
+        const guard = `__fish_seen_subcommand_from ${cmd}; and not __fish_seen_subcommand_from ${subs.join(' ')}`;
+        for (const sub of subs) {
+            const desc = model.descriptions[`${cmd} ${sub}`] ?? '';
+            lines.push(`complete -c kite -n '${guard}' -a ${sub} -d '${desc}'`);
+        }
+    }
+    lines.push('', '# Global flags.');
+    for (const flag of model.globalFlags) {
+        lines.push(`complete -c kite -l ${flag.replace(/^--/, '')}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+// --- helpers ---------------------------------------------------------------
+function isShell(value) {
+    return SHELLS.includes(value);
+}
+/** Best-effort shell detection from $SHELL, e.g. "/usr/bin/fish" -> "fish". */
+function detectShell() {
+    const shell = process.env['SHELL'];
+    if (!shell)
+        return undefined;
+    const base = shell.split('/').pop();
+    return base && isShell(base) ? base : undefined;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,4 @@
+import type { CommandFactory } from './types.js';
+export declare const doctorCommands: CommandFactory;
+/** True when `current` is >= `floor`, comparing major.minor.patch numerically. */
+export declare function meetsFloor(current: string, floor: string): boolean;

package/dist/commands/doctor.js

@@ -0,0 +1,190 @@
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { getSecret, keyringAvailable } from '../core/credentials.js';
+import { ExitCode } from '../core/errors.js';
+import { configFile } from '../core/paths.js';
+import { isExpired, timeUntilExpiry } from '../core/session.js';
+import { renderKeyValue } from '../output/table.js';
+export const doctorCommands = (program, run) => {
+    program
+        .command('doctor')
+        .description('Run offline health checks on your configuration, credentials, and session')
+        .action(run(doctor));
+};
+async function doctor(ctx) {
+    const checks = [
+        checkNode(),
+        await checkConfigFile(),
+        await checkKeyring(),
+        await checkCredentials(ctx),
+        checkSession(ctx),
+        await checkCallbackPort(ctx),
+    ];
+    const worst = checks.some((c) => c.status === 'fail')
+        ? 'fail'
+        : checks.some((c) => c.status === 'warn')
+            ? 'warn'
+            : 'ok';
+    if (ctx.io.json) {
+        ctx.io.writeJson({
+            ok: worst !== 'fail',
+            profile: ctx.profile.name,
+            env: ctx.env,
+            checks: checks.map((c) => ({
+                name: c.name,
+                status: c.status,
+                detail: c.detail,
+                ...(c.hint ? { hint: c.hint } : {}),
+            })),
+        });
+        if (worst === 'fail')
+            process.exitCode = ExitCode.Failure;
+        return;
+    }
+    const { io } = ctx;
+    const rows = [];
+    for (const check of checks) {
+        rows.push([`${icon(io, check.status)} ${check.name}`, check.detail]);
+        if (check.hint)
+            rows.push(['', io.dim(check.hint)]);
+    }
+    io.line(renderKeyValue(io, rows));
+    io.note('');
+    if (worst === 'fail') {
+        io.error('Some checks failed. See the hints above.');
+        process.exitCode = ExitCode.Failure;
+    }
+    else if (worst === 'warn') {
+        io.warn('All essential checks passed, with warnings.');
+        io.info('Run `kite whoami` to confirm the session is live on Kite (doctor is offline).');
+    }
+    else {
+        io.success('Everything looks healthy.');
+        io.info('Run `kite whoami` to confirm the session against Kite (doctor is offline).');
+    }
+}
+// --- individual checks -----------------------------------------------------
+/** Node must meet the floor declared in package.json `engines`. */
+function checkNode() {
+    const current = process.versions.node;
+    const floor = '22.12.0';
+    return meetsFloor(current, floor)
+        ? { name: 'Node runtime', status: 'ok', detail: `v${current}` }
+        : {
+            name: 'Node runtime',
+            status: 'fail',
+            detail: `v${current} is below the required v${floor}`,
+            hint: `Upgrade to Node ${floor} or newer.`,
+        };
+}
+async function checkConfigFile() {
+    const path = configFile();
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // No file is fine — defaults apply until the first `config set`.
+            return { name: 'Config file', status: 'ok', detail: 'none yet (using built-in defaults)' };
+        }
+        return { name: 'Config file', status: 'fail', detail: `cannot read ${path}`, hint: err.message };
+    }
+    // Windows models permissions through ACLs, not the POSIX mode bits, so the
+    // 0600 assertion only makes sense off Windows.
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        const mode = (info.mode & 0o777).toString(8).padStart(3, '0');
+        return {
+            name: 'Config file',
+            status: 'warn',
+            detail: `${path} is mode ${mode} (world- or group-readable)`,
+            hint: `Tighten it: chmod 600 ${path}`,
+        };
+    }
+    return { name: 'Config file', status: 'ok', detail: path };
+}
+async function checkKeyring() {
+    return (await keyringAvailable())
+        ? { name: 'Credential store', status: 'ok', detail: 'OS keyring available' }
+        : {
+            name: 'Credential store',
+            status: 'warn',
+            detail: 'no OS keyring — falling back to an encrypted file',
+            hint: 'Set KITE_CREDENTIALS_PASSPHRASE to enable the encrypted file store on this machine.',
+        };
+}
+async function checkCredentials(ctx) {
+    if (ctx.env === 'sandbox') {
+        return { name: 'API secret', status: 'ok', detail: 'using the public sandbox credentials' };
+    }
+    const secret = await getSecret('api_secret', { scope: ctx.credentialScope });
+    return secret
+        ? { name: 'API secret', status: 'ok', detail: `stored (${secret.backend})` }
+        : {
+            name: 'API secret',
+            status: 'warn',
+            detail: 'not stored',
+            hint: 'Run `kite login` (or set KITE_API_SECRET) so re-login and signing work.',
+        };
+}
+/** Cached session metadata only — liveness against Kite is `kite whoami`'s job. */
+function checkSession(ctx) {
+    const loginHint = ctx.profile.name === 'default' ? 'Run `kite login`.' : `Run \`kite --profile ${ctx.profile.name} login\`.`;
+    if (!ctx.session) {
+        return { name: 'Session', status: 'warn', detail: 'not logged in', hint: loginHint };
+    }
+    if (isExpired(ctx.session)) {
+        return {
+            name: 'Session',
+            status: 'warn',
+            detail: 'expired (Kite invalidates tokens at 06:00 IST daily)',
+            hint: loginHint,
+        };
+    }
+    const who = ctx.session.userName ?? ctx.session.userId;
+    return { name: 'Session', status: 'ok', detail: `${who}, expires in ${timeUntilExpiry(ctx.session)}` };
+}
+async function checkCallbackPort(ctx) {
+    const port = ctx.config.redirectPort;
+    const free = await portIsFree(port);
+    return free
+        ? { name: 'Login callback port', status: 'ok', detail: `127.0.0.1:${port} is free` }
+        : {
+            name: 'Login callback port',
+            status: 'warn',
+            detail: `127.0.0.1:${port} is in use`,
+            hint: 'Another process holds the callback port; `kite login` may fail until it frees, or change redirectPort.',
+        };
+}
+// --- helpers ---------------------------------------------------------------
+function icon(io, status) {
+    switch (status) {
+        case 'ok':
+            return io.green('✓');
+        case 'warn':
+            return io.yellow('!');
+        case 'fail':
+            return io.red('✗');
+    }
+}
+/** True when `current` is >= `floor`, comparing major.minor.patch numerically. */
+export function meetsFloor(current, floor) {
+    const c = current.split('.').map((n) => Number.parseInt(n, 10));
+    const f = floor.split('.').map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const a = c[i] ?? 0;
+        const b = f[i] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/** Bind-and-release probe: can `kite login` open its loopback callback server? */
+function portIsFree(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}

package/dist/commands/margins.d.ts

@@ -0,0 +1,34 @@
+import { type OrderType, type Product, type TransactionType, type Variety } from '../core/api.js';
+import type { CommandFactory } from './types.js';
+/**
+ * Margin and charge calculators — read-only.
+ *
+ * These POST a hypothetical set of orders to Kite and return what they would
+ * cost: `order` gives the per-order required margin (no netting), `basket` the
+ * net margin for the set (with spread/hedge benefit), and `charges` the
+ * itemised brokerage/tax breakdown (a "virtual contract note"). Nothing is
+ * placed, so none of the trading safety layer applies.
+ */
+export declare const marginCommands: CommandFactory;
+/** A hypothetical order, resolved from a spec, ready to serialise per endpoint. */
+export interface OrderSpec {
+    exchange: string;
+    tradingsymbol: string;
+    transactionType: TransactionType;
+    quantity: number;
+    orderType: OrderType;
+    product: Product;
+    variety: Variety;
+    price: number | undefined;
+    triggerPrice: number | undefined;
+}
+/**
+ * Parse one `EXCHANGE:SYMBOL:SIDE:QTY[:attrs...]` spec.
+ *
+ * Attributes after QTY are classified by content — an order type, a product, a
+ * variety, a bare number (the price), or `trigger=<n>`. Fails closed: an
+ * unrecognised token, a duplicated field, or an empty field rejects the whole
+ * spec rather than silently defaulting, since a mis-parsed order yields a
+ * silently wrong margin or charge.
+ */
+export declare function parseOrderSpec(spec: string): OrderSpec;