@ai-digital-factory/lmt-cli 0.1.2 → 0.1.4

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.
 
@@ -85,10 +95,15 @@ First establish the Operator Session with `login`. Zerodha credentials stay on B
 2. Copy that attempt ID and submit the current six-digit OTP:
 
    ```sh
-   lmt zerodha otp --env dev --profile my-dev-session --attempt ATTEMPT_ID --otp CURRENT_OTP
+   # 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 `CURRENT_OTP` with the code obtained after the challenge. 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.
+   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.
 
 From the monorepo root, use `pnpm -s cli:headless` in place of `lmt`. Both `local` and `dev` are supported.
 
@@ -99,7 +114,7 @@ lmt zerodha observe --env dev --profile my-dev-session --attempt ATTEMPT_ID
 lmt zerodha status --env dev --profile my-dev-session
 ```
 
-`--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. `zerodha login --otp` is rejected before network access; there is no single-pass login or automatic resume. `--otp-stdin` remains unsupported.
+`--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`.
 
@@ -127,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`, obtain the Kite OTP and run `zerodha otp --attempt ID --otp CODE`. |
+| `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:
 
@@ -184,3 +199,51 @@ 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).
+
+## Settings and token commands for Runner
+
+Read ordinary Settings and their durable Settings Version with:
+
+```sh
+lmt settings read --env dev --profile runner
+```
+
+Save one intent by piping a single JSON object to protected stdin. Supply the version
+you reviewed and only the settings you intend to change. For example:
+
+```sh
+printf '%s\n' '{"expectedSettingsVersion":7,"entryCategories":[]}' |
+  lmt settings save --stdin --env dev --profile runner
+```
+
+An empty list disables all Entry Categories; omitted fields keep their saved values.
+Replacing credentials requires all four fields (userId, password, apiKey, apiSecret)
+inside a credentials object supplied through protected stdin. Keep secrets in an
+owner-readable input file or a protected pipe, never in command arguments or shell history.
+One changed save advances one Settings Version; a current unchanged save returns
+unchanged without a write. Every ordinary API write, including standalone credential
+saves, requires expectedSettingsVersion. Stale saves return settings_conflict; read
+Settings again and review the intended changes before submitting. A transport timeout
+after submission or an unconfirmed Broker save returns uncertain with exit code 1.
+Commands never retry a save. An ambiguous SMS write blocks authoritative Settings
+reads and further Operator-record writes until Broker restarts and reloads its durable
+record. The existing Market Watch resize recovery limitation still applies across stores.
+
+Access-token operations use a separate version and endpoint:
+
+```sh
+lmt token read --env dev --profile runner
+lmt token replace --stdin --env dev --profile runner < /path/to/protected-token-request.json
+```
+
+The token request contains accessToken, expected (the metadata returned by token read),
+and optionally continueReplacement: true after reviewing an active-trading confirmation.
+A same-token submission verifies the submitter without reinstalling the token. Ordinary
+Settings Save never replaces access tokens. Token values and saved credentials do not
+appear in command results.