@ai-digital-factory/lmt-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# Live Market Terminal CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use the published [`@ai-digital-factory/lmt-cli`](https://www.npmjs.com/package/@ai-digital-factory/lmt-cli) package to log in to Live Market Terminal, manage Operator Sessions, and complete Zerodha login from your terminal. The executable is `lmt`; `live-market-terminal` is an alias with the same commands.
+
+## Install or update
+
+Requires **Node.js 22 or later**, with npm and npx available on your PATH. No source checkout, pnpm, build step, or local configuration file is needed for the published package.
+
+```sh
+node --version
+npm install --global @ai-digital-factory/lmt-cli@latest
+lmt --help
+```
+
+Run the same install command to update to the latest published version. To check your installed version:
+
+```sh
+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.
+
+## 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.
+2. If using those SMS-backed commands, provision the credential once using the masked prompt:
+
+   ```sh
+   lmt interactive credential provision --env dev
+   ```
+
+   Paste the SMS read credential and press Enter. After `SMS credential saved.` appears, press Ctrl+C to leave the provisioning screen. The credential is shared across profiles.
+3. Open the interactive terminal:
+
+   ```sh
+   lmt interactive --env dev --profile my-dev-session
+   ```
+
+   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.
+
+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.
+
+Interactive mode defaults to `--env local --profile default` when these options are omitted. Keep the same environment and profile across commands to reuse a session:
+
+```sh
+lmt status --env dev --profile my-dev-session
+```
+
+## Headless Operator login and sessions
+
+Headless commands require **both `--env` and `--profile`**. They never prompt for input. Provision the SMS credential using the masked interactive command above, then run:
+
+```sh
+lmt login --env dev --profile my-dev-session
+lmt status --env dev --profile my-dev-session
+lmt validate operator-session --env dev --profile my-dev-session
+lmt logout --env dev --profile my-dev-session
+```
+
+`login` reads the configured Operator's username and password from the selected Gate scope's SMS Operator Directory and authenticates through Gate. SMS reads invoke `@ai-digital-factory/sms-cli@0.1.2` through npx, so npm registry access is needed when it is not cached. `status` verifies the saved Operator Session with Gate and the Broker-backed operators route; it does not confirm Zerodha login. Validation exercises login and session behavior using a temporary profile, logs out its temporary sessions, and removes only its temporary records.
+
+`logout` revokes the Operator Session through Gate and clears its saved cookies and pending Zerodha attempt. If Gate cannot confirm logout, the command fails and retains cookies for retry. Other profiles, the shared SMS credential, and Broker-owned SMS access tokens remain intact.
+
+For automated credential provisioning, pipe one non-empty credential line through protected stdin:
+
+```sh
+lmt credential provision --env dev --profile my-dev-session --credential-stdin < /path/to/protected-sms-credential-file
+```
+
+Replace the path with an owner-readable credential file supplied by your secret-management process. Keep SMS credentials, passwords, and cookies out of command arguments. Provisioning saves the credential locally; it does not verify SMS access.
+
+## 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:
+
+```sh
+lmt zerodha login --env dev --profile my-dev-session --otp CURRENT_OTP
+lmt zerodha status --env dev --profile my-dev-session
+```
+
+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.
+
+To start the challenge before obtaining the OTP:
+
+```sh
+lmt zerodha login --env dev --profile my-dev-session
+```
+
+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.
+
+Additional commands for an existing attempt:
+
+```sh
+lmt zerodha observe --env dev --profile my-dev-session
+lmt zerodha otp --env dev --profile my-dev-session --otp CURRENT_OTP
+```
+
+`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.
+
+## 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.
+
+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.
+
+```sh
+lmt interactive --env local --profile my-local-session
+lmt status --env local --profile my-local-session
+```
+
+## Output, deadlines, and troubleshooting
+
+Headless commands write one versioned JSON object per line to stdout; diagnostics go to stderr. Inspect `outcome`, `reason`, and, on failure, `error`. Use the process exit code for automation:
+
+| Exit code | Meaning | Next step |
+| --- | --- | --- |
+| `0` | Success or validation pass | Continue. |
+| `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. |
+
+Actions default to 30 seconds; validation defaults to 2 minutes. Headless actions and validation accept a finite deadline between 1 millisecond and 10 minutes:
+
+```sh
+lmt status --env dev --profile my-dev-session --timeout 45s
+lmt validate operator-session --env dev --profile my-dev-session --timeout 2m
+```
+
+- **`lmt: command not found`:** confirm the global installation with `npm list --global @ai-digital-factory/lmt-cli --depth=0` and add npm's global executable directory to PATH (`npm prefix --global`, then `bin/` on macOS/Linux).
+- **Missing SMS credential:** run `lmt interactive credential provision --env dev` and retry. The credential is shared, but it needs access to the scope used by your chosen environment.
+- **SMS unavailable or invalid Operator Directory:** check the credential's read access and the selected Gate scope's Operator Directory with your administrator.
+- **Session expired or rejected:** the CLI clears rejected session cookies. Log in again explicitly using the same profile and environment.
+- **Origin or Broker unavailable:** check the selected deployment. For local use, keep the full stack running at the canonical Origin. `status` requires Broker to be available even when Gate still accepts the session.
+
+## Run from a source checkout
+
+For contributors, from `live-market-terminal/`:
+
+```sh
+pnpm cli --env dev --profile my-dev-session
+pnpm -s cli:headless status --env dev --profile my-dev-session
+pnpm --filter @ai-digital-factory/lmt-cli interactive credential provision --env dev
+```
+
+These repository scripts rebuild the CLI. The published commands above run directly from the installed package. The CLI sets `NODE_USE_ENV_PROXY=0` on startup so local Gate requests are not sent through `HTTP(S)_PROXY`.
+
+## Maintain the npm package
+
+The **Release LMT CLI** GitHub Action is dispatched manually on `main`. It builds
+current `main`, tests the CLI, builds a standalone package with bundled private
+contracts, selects the next npm patch, and tests a clean installation of the exact
+tarball it publishes publicly under `latest`. Node 22 and pnpm 10.33.3 match CI.
+
+Only `SMS_CREDENTIAL` is configured as a GitHub Actions secret for this workflow.
+It must be able to read `NPM_TOKEN` from SMS scope `infra`, at Vault
+`secret/data/infra/NPM_TOKEN` with field `value`. The endpoint and scope are
+non-secret repository configuration. The existing npm token needs publishing
+permission for `@ai-digital-factory/lmt-cli`; it is masked and passed only to the
+publishing step. No credential values are included in the package.
+
+First publication uses `0.1.0`; later runs increment the highest published stable
+version's patch. Registry/authentication failures stop the release. Versions change
+only in the temporary publishing artifact, with no bump commit, git tag, GitHub
+Release, Origin Version, or deployment. A retry after successful npm publication
+selects another patch, since published npm versions are immutable. npm can accept
+an upload before public registry processing finishes; the action polls for visibility
+for five minutes. If confirmation times out after a successful upload, check npm
+before rerunning the release to avoid publishing an unnecessary patch.
+
+To reproduce the packaging checks from the repository root:
+
+```sh
+(cd live-market-terminal && pnpm --filter @ai-digital-factory/lmt-cli package:build)
+tarball=$(bash .github/scripts/pack-lmt-cli.sh /tmp/lmt-cli-package)
+node .github/scripts/test-lmt-cli-package.mjs "$tarball"
+```