@pungoyal/kite-cli 0.1.0

package/dist/safety.d.ts

@@ -0,0 +1,93 @@
+import type { Context } from './context.js';
+/**
+ * Guard rails for money-moving commands.
+ *
+ * Layered, cheapest first:
+ *
+ *   1. Kill switch    — config `trading.enabled: false` refuses before any network call
+ *   2. Value cap      — config `trading.maxOrderValue` refuses oversized orders
+ *   3. --dry-run      — renders the resolved action and exits 0 without calling the API
+ *   4. Confirmation   — y/N, escalating to type-the-symbol above a threshold
+ *
+ * Two rules that are easy to get wrong and important to get right:
+ *
+ *   - No TTY and no `--yes` means REFUSE, exit non-zero. Never silently proceed
+ *     just because stdin is not interactive.
+ *   - The prompt renders the RESOLVED action — the actual instrument token,
+ *     the computed value — not an echo of the flags. A flag echo cannot catch
+ *     "I typed the wrong symbol and it resolved to a different contract",
+ *     which is precisely the expensive mistake.
+ */
+export interface ConfirmationDetail {
+    label: string;
+    value: string;
+}
+export interface ConfirmOptions {
+    /** Short imperative summary, e.g. "Place BUY order". */
+    action: string;
+    /** The resolved facts shown to the user before they commit. */
+    details: ConfirmationDetail[];
+    /** Notional value in rupees, used for the cap and escalation checks. */
+    notionalValue?: number | undefined;
+    /**
+     * Does this action create or increase market exposure?
+     *
+     * Only these are subject to `trading.maxOrderValue`, and only these fail
+     * closed on an unknown value. Cancelling an order or converting a position
+     * REDUCES or merely reshapes risk — blocking those because a cap could not
+     * be evaluated would be exactly backwards, and would leave a user unable to
+     * cancel their way out of a position.
+     */
+    increasesExposure?: boolean;
+    /**
+     * When escalation triggers, the user must type this string exactly.
+     * Usually the trading symbol.
+     */
+    challengeToken?: string | undefined;
+    /** Set for actions that place, modify or cancel orders. */
+    mutatesOrders?: boolean;
+}
+/** Refuse early if the local kill switch is off. */
+export declare function assertTradingEnabled(ctx: Context): void;
+/**
+ * Refuse orders above the configured notional cap.
+ *
+ * Fails CLOSED when the value cannot be determined. An unknown notional is the
+ * normal outcome of a failed quote lookup (the quote bucket is 1 req/sec, so a
+ * 429 is easy to hit), and treating "unknown" as "within the cap" would mean
+ * the one guard the user explicitly configured silently stops applying exactly
+ * when the CLI is least sure what it is about to do.
+ */
+export declare function assertWithinValueCap(ctx: Context, notionalValue: number | undefined): void;
+/**
+ * Render the resolved action and obtain consent.
+ *
+ * Returns true to proceed. Throws rather than returning false, so a caller can
+ * never accidentally treat a declined confirmation as approval.
+ */
+export declare function confirmAction(ctx: Context, opts: ConfirmOptions): Promise<void>;
+/**
+ * Generate a unique order tag.
+ *
+ * This is the cornerstone of safe order placement. Kite has NO idempotency
+ * key — the `guid` in the response is server-assigned — so a timed-out POST
+ * /orders may or may not have executed. The only safe recovery is to search the
+ * orderbook for a tag we chose ourselves.
+ *
+ * Kite caps `tag` at 20 alphanumeric characters.
+ */
+export declare function generateOrderTag(prefix?: string): string;
+/**
+ * Build the tag actually sent to Kite, guaranteeing uniqueness even when the
+ * user supplied their own.
+ *
+ * A user tag is a label; the reconciliation key must be unique or the recovery
+ * path actively lies. With a reused tag, a failed placement would find the
+ * EARLIER order carrying that tag and report "it was placed, do not retry" —
+ * when in fact nothing was placed. So the user's tag is kept as a prefix for
+ * their own filtering, and a random suffix makes it unique.
+ *
+ * Kite caps `tag` at 20 alphanumeric characters, so the user prefix is
+ * truncated to leave room for the suffix.
+ */
+export declare function buildOrderTag(userTag?: string): string;

package/dist/safety.js

@@ -0,0 +1,154 @@
+import { randomBytes } from 'node:crypto';
+import { confirm, isCancel, text } from '@clack/prompts';
+import { AbortedError, ExitCode, KiteCliError } from './core/errors.js';
+import { rupees } from './output/format.js';
+/** Refuse early if the local kill switch is off. */
+export function assertTradingEnabled(ctx) {
+    if (!ctx.config.trading.enabled) {
+        throw new KiteCliError('Trading is disabled by the local kill switch.', ExitCode.TradingDisabled, 'Re-enable it with `kite config set trading.enabled true`.');
+    }
+}
+/**
+ * Refuse orders above the configured notional cap.
+ *
+ * Fails CLOSED when the value cannot be determined. An unknown notional is the
+ * normal outcome of a failed quote lookup (the quote bucket is 1 req/sec, so a
+ * 429 is easy to hit), and treating "unknown" as "within the cap" would mean
+ * the one guard the user explicitly configured silently stops applying exactly
+ * when the CLI is least sure what it is about to do.
+ */
+export function assertWithinValueCap(ctx, notionalValue) {
+    const cap = ctx.config.trading.maxOrderValue;
+    if (cap === undefined)
+        return;
+    if (notionalValue === undefined) {
+        throw new KiteCliError(`Cannot verify this order against your configured cap of ${rupees(cap)} — its value is unknown.`, ExitCode.TradingDisabled, 'Specify an explicit --price so the value can be computed, or unset the cap with `kite config unset trading.maxOrderValue`.');
+    }
+    if (notionalValue > cap) {
+        throw new KiteCliError(`Order value ${rupees(notionalValue)} exceeds your configured cap of ${rupees(cap)}.`, ExitCode.TradingDisabled, 'Raise it with `kite config set trading.maxOrderValue <amount>`, or unset it to remove the cap.');
+    }
+}
+/**
+ * Render the resolved action and obtain consent.
+ *
+ * Returns true to proceed. Throws rather than returning false, so a caller can
+ * never accidentally treat a declined confirmation as approval.
+ */
+export async function confirmAction(ctx, opts) {
+    if (opts.mutatesOrders) {
+        assertTradingEnabled(ctx);
+    }
+    // The cap is about how much exposure you can take on, not about whether you
+    // may unwind it.
+    if (opts.increasesExposure) {
+        assertWithinValueCap(ctx, opts.notionalValue);
+    }
+    const { io } = ctx;
+    // Whether we will actually stop and ask. Computed up front because it
+    // decides whether the preview may be suppressed.
+    const willPrompt = !ctx.options.dryRun && !ctx.options.yes && (ctx.config.trading.confirm || opts.mutatesOrders === true);
+    // Always show what is about to happen, even with --yes, so the record exists
+    // in the terminal scrollback.
+    //
+    // `force` when we are about to prompt: --quiet and --json normally suppress
+    // the preview, but asking someone to approve an order while showing them
+    // none of the resolved facts is worse than printing in a mode they asked to
+    // be quiet. A prompt without its preview is not informed consent.
+    renderPreview(ctx, opts, willPrompt);
+    if (ctx.options.dryRun) {
+        io.note('');
+        io.note(io.cyan('Dry run — nothing was sent to Kite.'));
+        return;
+    }
+    // --yes is a call-site-only bypass. It is deliberately not readable from the
+    // config file: disabling safety must be an explicit act every time.
+    if (ctx.options.yes)
+        return;
+    if (!ctx.config.trading.confirm && opts.mutatesOrders !== true)
+        return;
+    if (!process.stdin.isTTY || !io.stderrIsTty) {
+        throw new KiteCliError(`${opts.action} requires confirmation, but this is not an interactive terminal.`, ExitCode.ConfirmationRequired, 'Pass --yes to confirm non-interactively, or --dry-run to preview without sending.');
+    }
+    const threshold = ctx.config.trading.strictConfirmAbove;
+    // An unknown value escalates rather than de-escalates. If we could not price
+    // the order, we cannot claim it is small — and a mispriced market order is
+    // precisely the case where typing the symbol is worth the friction.
+    // Unknown value only escalates for exposure-increasing actions; demanding a
+    // typed confirmation to unwind a position would be friction in the wrong
+    // direction.
+    const valueUnknown = opts.notionalValue === undefined && opts.increasesExposure === true;
+    const needsChallenge = opts.challengeToken !== undefined &&
+        (valueUnknown || (opts.notionalValue !== undefined && opts.notionalValue >= threshold));
+    if (needsChallenge) {
+        // Above the threshold a keystroke is too easy to fire by accident, so we
+        // require the symbol to be typed out.
+        const reason = valueUnknown
+            ? 'This order value could not be determined'
+            : `This is a large order (${rupees(opts.notionalValue)})`;
+        const answer = await text({
+            message: `${reason}. Type ${opts.challengeToken} to confirm:`,
+            validate: (value) => value === opts.challengeToken ? undefined : `Type "${opts.challengeToken}" exactly, or press Ctrl-C to abort.`,
+        });
+        if (isCancel(answer) || answer !== opts.challengeToken) {
+            throw new AbortedError('Aborted — confirmation did not match.');
+        }
+        return;
+    }
+    const answer = await confirm({
+        message: `${opts.action}?`,
+        initialValue: false,
+    });
+    if (isCancel(answer) || answer !== true) {
+        throw new AbortedError();
+    }
+}
+function renderPreview(ctx, opts, force = false) {
+    const { io } = ctx;
+    if ((io.json || io.quiet) && !force)
+        return;
+    const width = Math.max(...opts.details.map((d) => d.label.length));
+    const emit = force ? (text) => io.forceNote(text) : (text) => io.note(text);
+    emit('');
+    emit(io.bold(opts.action));
+    for (const detail of opts.details) {
+        emit(`  ${io.dim(detail.label.padEnd(width))}  ${detail.value}`);
+    }
+    if (ctx.env === 'sandbox') {
+        emit(`  ${io.cyan('sandbox — no real money involved')}`);
+    }
+}
+/**
+ * Generate a unique order tag.
+ *
+ * This is the cornerstone of safe order placement. Kite has NO idempotency
+ * key — the `guid` in the response is server-assigned — so a timed-out POST
+ * /orders may or may not have executed. The only safe recovery is to search the
+ * orderbook for a tag we chose ourselves.
+ *
+ * Kite caps `tag` at 20 alphanumeric characters.
+ */
+export function generateOrderTag(prefix = 'kc') {
+    const random = randomBytes(6).toString('hex');
+    const stamp = Date.now().toString(36);
+    return `${prefix}${stamp}${random}`.slice(0, 20);
+}
+/**
+ * Build the tag actually sent to Kite, guaranteeing uniqueness even when the
+ * user supplied their own.
+ *
+ * A user tag is a label; the reconciliation key must be unique or the recovery
+ * path actively lies. With a reused tag, a failed placement would find the
+ * EARLIER order carrying that tag and report "it was placed, do not retry" —
+ * when in fact nothing was placed. So the user's tag is kept as a prefix for
+ * their own filtering, and a random suffix makes it unique.
+ *
+ * Kite caps `tag` at 20 alphanumeric characters, so the user prefix is
+ * truncated to leave room for the suffix.
+ */
+export function buildOrderTag(userTag) {
+    if (!userTag)
+        return generateOrderTag();
+    const suffix = randomBytes(4).toString('hex'); // 8 chars
+    const prefix = userTag.slice(0, 20 - suffix.length);
+    return `${prefix}${suffix}`;
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@pungoyal/kite-cli",
+  "version": "0.1.0",
+  "description": "Unofficial command-line interface for the Zerodha Kite Connect API — not affiliated with or endorsed by Zerodha",
+  "keywords": [
+    "zerodha",
+    "kite",
+    "kiteconnect",
+    "trading",
+    "stocks",
+    "cli",
+    "nse",
+    "bse"
+  ],
+  "license": "MIT",
+  "author": "Puneet Goyal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pungoyal/kite-cli.git"
+  },
+  "homepage": "https://github.com/pungoyal/kite-cli#readme",
+  "bugs": {
+    "url": "https://github.com/pungoyal/kite-cli/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "kite": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "node --experimental-strip-types src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "hooks:install": "git config core.hooksPath .githooks",
+    "check:deps": "node scripts/check-deps.mjs",
+    "lint:publish": "publint && attw --pack . --profile esm-only",
+    "check:dist": "node -e \"const{existsSync,readFileSync}=require('node:fs');if(!existsSync('dist/cli.js'))throw new Error('dist/ is missing — run npm run build before publishing');if(!readFileSync('dist/cli.js','utf8').startsWith('#!/usr/bin/env node'))throw new Error('dist/cli.js lost its shebang')\"",
+    "prepublishOnly": "npm run build && npm run check:dist"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@napi-rs/keyring": "^1.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
+    "log-update": "^8.0.0",
+    "picocolors": "^1.1.1",
+    "undici": "^8.7.0",
+    "ws": "^8.21.1",
+    "yocto-spinner": "^1.2.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
+    "@biomejs/biome": "^2.5.4",
+    "@types/node": "^22.15.0",
+    "@types/ws": "^8.18.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "execa": "^10.0.0",
+    "msw": "^2.15.0",
+    "publint": "^0.3.0",
+    "strip-ansi": "^7.1.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.10"
+  }
+}