@ai-digital-factory/lmt-cli 0.1.1 → 0.1.3

package/README.md

@@ -20,6 +20,16 @@ npm list --global @ai-digital-factory/lmt-cli --depth=0
 
 The package includes the non-secret Origins, Gate scopes, and SMS endpoint. Choose `--env dev` for the deployed dev service, or `--env local` for a running local stack. Only `local` and `dev` are supported; `prod` is rejected. Installing the CLI does not start services or provision credentials.
 
+## Candle Export for Runner
+
+With a saved Operator Session, request one instrument and optional IST date:
+
+```sh
+lmt candle-export NSE:IDEA --date 2026-10-23 --env dev --profile runner --timeout 2m
+```
+
+Omitting `--date` asks Broker for the exchange's latest completed trading session, accounting for holidays and Finalization Grace. The stdout JSON `candleExport` contains the immutable Hosted URL, filename, resolved identity/date, source availability, reference-fetch metadata, and comparison counts. Missing data or Zerodha authentication is explained in the workbook. Export does not start Zerodha login or token recovery. Local/dev only; see `lmt --help` for exit conventions.
+
 ## Quick start: interactive dev login
 
 1. Obtain your Operator Login username and password. For headless login and Operator Session validation, also obtain an SMS read credential authorized to read `live-market-terminal-operator-directory` in the selected Gate scope from your administrator.
@@ -37,7 +47,7 @@ The package includes the non-secret Origins, Gate scopes, and SMS endpoint. Choo
    ```
 
    Enter your Operator Login username and password when prompted. This interactive login uses the credentials you enter; it does not require reading them from SMS. A valid saved session resumes automatically.
-4. Use the menu to **Login with Zerodha**, **Check Operator Session**, **Validate Operator Session**, or **Logout Operator Session**. Zerodha login prompts for the current six-digit OTP. Validation requires the provisioned SMS credential.
+4. Use the menu to **Login with Zerodha**, **Check Operator Session**, **Validate Operator Session**, **Validate Zerodha Session**, **Resume Zerodha Validation**, or **Logout Operator Session**. Zerodha login prompts for the current six-digit OTP. Validation requires the provisioned SMS credential.
 
 Press Enter to submit each prompt. At the Operator password prompt, Escape returns to the username; Ctrl+U clears either field. Passwords remain masked. Press Ctrl+C to exit the terminal; use the logout command or menu action when you want to revoke the Operator Session.
 
@@ -72,37 +82,48 @@ Replace the path with an owner-readable credential file supplied by your secret-
 
 ## Headless Zerodha login
 
-First establish an Operator Session with `lmt login` or interactive login using the same environment and profile. Zerodha credentials stay on Broker. Submit the current six-digit OTP:
+First establish the Operator Session with `login`. Zerodha credentials stay on Broker. Headless Zerodha login uses one two-step flow, matching Web: start login first, then obtain the OTP from Kite and submit it to that exact attempt.
 
-```sh
-lmt zerodha login --env dev --profile my-dev-session --otp CURRENT_OTP
-lmt zerodha status --env dev --profile my-dev-session
-```
+1. Start the Zerodha Login Attempt:
 
-Replace `CURRENT_OTP` with the actual six-digit code. `zerodha login` starts or resumes the profile's login attempt and verifies the resulting Zerodha Session through Gate. The OTP is not stored or included in JSON results or diagnostics; it is passed as a command argument. `--otp-stdin` is unsupported.
+   ```sh
+   lmt zerodha login --env dev --profile my-dev-session
+   ```
 
-To start the challenge before obtaining the OTP:
+   When Zerodha requests the OTP, the command returns `outcome: "blocked"`, `reason: "awaiting_otp"`, exit code `4`, and `zerodha.attemptId`. This is the expected handoff to obtain the OTP from Kite.
 
-```sh
-lmt zerodha login --env dev --profile my-dev-session
-```
+2. Copy that attempt ID and submit the current six-digit OTP:
+
+   ```sh
+   # Bash: mask entry, disable tracing, and send through the builtin printf pipe.
+   set +x
+   IFS= read -r -s -p 'Kite OTP: ' otp_value
+   printf '\n' >&2
+   printf '%s\n' "$otp_value" | lmt zerodha otp --env dev --profile my-dev-session --attempt ATTEMPT_ID --otp-stdin
+   unset otp_value
+   ```
+
+   Replace `ATTEMPT_ID` with `zerodha.attemptId` from step 1 and enter the code obtained after the challenge at the masked prompt. Use the same environment and profile in both steps. Success requires verification of the resulting Zerodha Session through Gate. OTPs are excluded from JSON results and diagnostics and never stored.
 
-When human input is needed, this returns `outcome: "blocked"`, `reason: "awaiting_otp"`, and exit code `4`. Repeat `zerodha login` with `--otp CURRENT_OTP` once the code is available. Attempt IDs are remembered automatically for the selected profile and target.
+From the monorepo root, use `pnpm -s cli:headless` in place of `lmt`. Both `local` and `dev` are supported.
 
-Additional commands for an existing attempt:
+To inspect the attempt or verify the session:
 
 ```sh
-lmt zerodha observe --env dev --profile my-dev-session
-lmt zerodha otp --env dev --profile my-dev-session --otp CURRENT_OTP
+lmt zerodha observe --env dev --profile my-dev-session --attempt ATTEMPT_ID
+lmt zerodha status --env dev --profile my-dev-session
 ```
 
-`observe` and `otp` optionally accept `--attempt ID` to override the remembered attempt. Invalid OTPs report Broker's rejection message and retry count. Successful login, Operator logout, and Operator Session replacement or rejection clear the remembered attempt.
+`--attempt ID` is required for `zerodha otp` and `zerodha observe`. The CLI does not remember attempt IDs. Existing saved attempt IDs are ignored and removed on the next profile-store write; saved cookies and the SMS credential remain usable. Argument-based `--otp CODE` and `--otp=CODE` are rejected before credential or network access. Migrate scripts to explicitly selected `--otp-stdin`; provide one six-digit line through a protected pipe and close it. Terminal input, extra lines, more than eight bytes, and unfinished input past `--timeout` are rejected. There is no single-pass login or automatic resume. See [protected OTP migration and local/dev smoke steps](docs/protected-otp.md).
+
+An expired, canceled, replaced, or failed attempt fails without starting a new login or submitting the OTP to another attempt. Explicitly run `zerodha login` again, obtain the new challenge's OTP, and submit it using the new attempt ID. A rejected OTP that leaves the attempt active returns `awaiting_otp` with Broker's rejection message and retry count; retry `zerodha otp` with a fresh code and the same ID. Every command remains noninteractive and honors `--timeout`.
+
 
 ## Profiles and local use
 
 Profiles save Client Identity and Operator Session cookies across invocations. Sessions are isolated by profile, environment, canonical Origin, and configured Operator. Profile names must be 1–64 letters, digits, dots, underscores, or hyphens, starting with a letter or digit.
 
-Storage is `~/.lmt/secrets.pem`: a protected JSON file containing the shared SMS credential, per-profile cookies, and pending Zerodha attempt IDs. The CLI enforces owner-only permissions and migrates legacy storage automatically. Do not share this file or include it in logs or version control.
+Storage is `~/.lmt/secrets.pem`: a protected JSON file containing the shared SMS credential and per-profile cookies. The CLI enforces owner-only permissions and migrates legacy storage automatically. Do not share this file or include it in logs or version control.
 
 For local use, first start Web, Gate, and Broker from a configured source checkout with `pnpm dev:local` in `live-market-terminal/`. The installed CLI uses the bundled canonical local Origin (`http://127.0.0.1:5173`) through Web's `/api` proxy; it does not fall back to a different port. The CLI's SMS read credential is separate from the service credential used by Gate and Broker.
 
@@ -121,7 +142,7 @@ Headless commands write one versioned JSON object per line to stdout; diagnostic
 | `1` | Action failure | Read the diagnostic; check SMS permissions or service reachability. |
 | `2` | Invalid invocation or target | Check `lmt --help`; supply `local` or `dev` and a valid profile. |
 | `3` | Operator Login required | Run `login` or interactive login with the same environment and profile. |
-| `4` | Validation blocked or Zerodha awaiting OTP | Read `reason`; for `awaiting_otp`, repeat Zerodha login with the current OTP. |
+| `4` | Validation blocked or Zerodha awaiting OTP | Read `reason`; for `awaiting_otp`, obtain the Kite OTP and run `zerodha otp --attempt ID --otp-stdin`. |
 
 Actions default to 30 seconds; validation defaults to 2 minutes. Headless actions and validation accept a finite deadline between 1 millisecond and 10 minutes:
 
@@ -178,3 +199,9 @@ To reproduce the packaging checks from the repository root:
 tarball=$(bash .github/scripts/pack-lmt-cli.sh /tmp/lmt-cli-package)
 node .github/scripts/test-lmt-cli-package.mjs "$tarball"
 ```
+
+### Zerodha validation
+
+`lmt validate zerodha-session --env local --profile NAME` starts a new Broker-owned attempt and returns an attributed blocked report when a human OTP is needed. Resume with the same profile and explicit `--attempt ID`; add `--otp-stdin` to submit the protected human code. Without that flag, the supplied attempt is only observed. A pass requires authoritative attempt state followed by a hard session check; status alone does not pass the scenario. The resulting session stays available on the caller profile.
+
+Interactive **Validate Zerodha Session** runs the same scenario with masked OTP input and a visible report. **Resume Zerodha Validation** asks for an explicit attempt ID. Fresh validation can replace the Operator's active Broker attempt and successful login can refresh its shared token. CLI profile isolation does not isolate that shared state. See [local/dev validation smoke steps and recorded prerequisites](ZERODHA-SMOKE.md).