@ai-digital-factory/lmt-web-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+# Live Market Terminal Web 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.
+`@ai-digital-factory/lmt-web-cli` provides the separate `lmt-web` executable for
+browser interaction with the configured local or dev Live Market Terminal Web URL. It
+keeps browser dependencies and session lifetime out of the browser-free `lmt`
+HTTP CLI.
+
+## Install
+
+Requires Node.js 22 or later, Chromium, and a macOS or Linux session owner.
+Install the CLI and its browser:
+
+```sh
+npm install --global @ai-digital-factory/lmt-web-cli@latest
+lmt-web install-browser
+lmt-web --help
+```
+
+`install-browser` uses the Playwright dependency installed with this CLI; a global
+`playwright` executable is not required. On Linux machines missing browser system
+libraries, use `lmt-web install-browser --with-deps` (the system package installer
+may request elevated privileges). `--dry-run` lists the selected Chromium build
+and installation path without downloading it. Setup writes one JSON result to
+stdout and installer diagnostics to stderr; a failed installer returns nonzero.
+If `start` reports `browser_unavailable`, rerun `lmt-web install-browser` before
+starting a fresh session.
+
+For local development, start the configured Live Market Terminal services from
+`live-market-terminal/` with `pnpm dev:local`. The Web CLI never starts services.
+
+## Start, inspect, close
+
+Browser command options may appear before or after the command. For example,
+`lmt-web --env local --device desktop --headed start` is equivalent to
+`lmt-web start --env local --device desktop --headed`.
+
+Choose `local` or `dev` explicitly when starting a session. Mobile emulation and
+headless mode are the defaults. The `iPhone 13` preset uses a 390 × 844 CSS
+viewport, touch input, a device scale factor of 3, and this user agent:
+
+```text
+Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.5 Mobile/15E148 Safari/604.1
+```
+Use `--device desktop` for the 1440 × 900 desktop preset or `--headed` to show
+the browser window. Desktop uses scale 1, no touch emulation, and the installed
+Chromium runtime's desktop user agent. Results report the actual preset,
+viewport, scale, touch support, and user agent. Changing device or browser
+visibility requires a new session; these options are accepted only by `start`.
+A visible browser requires an active desktop display. All automated browser tests
+run headlessly, including mobile and desktop acceptance. `pnpm test` requires no
+desktop display or Xvfb.
+
+Quitting the browser from its Dock menu or closing its session window also ends
+the browser session and its local owner. This does not log out the Operator or
+stop Broker activity. A later `inspect` reports `session_not_found`.
+
+```sh
+lmt-web start --env dev
+lmt-web inspect --session SESSION_ID
+lmt-web inspect --session SESSION_ID --full-page
+lmt-web close --session SESSION_ID --full-page
+lmt-web stop --session SESSION_ID
+```
+
+`stop` terminates that session's browser process and local owner without inspecting
+the page or taking a final screenshot. It also works after the browser window has
+been closed manually. Supply the session ID returned by `start`; other sessions
+remain running. Like `close`, it does not log out or stop Broker activity.
+
+`start` opens the Home Page and returns a session ID. Every later command needs
+that ID and talks to the same local browser process without reloading the page.
+Concurrent commands within a session run in order. Different session IDs have
+separate in-memory browser contexts and storage. A session is owned by the local
+user who started it; closing it, losing its owner process, or restarting the
+machine requires a new session. The Web CLI does not import `lmt` cookies or
+save browser authentication. Closing a browser does not log out, revoke an
+Operator Session, or stop Broker activity.
+
+Each command writes one versioned JSON result to stdout and diagnostics to
+stderr. Results contain the action outcome, current URL, visible page text and
+controls, emulated device and actual viewport, and screenshot outcome. Images
+are written to unique absolute paths in an owner-only temporary directory;
+screenshots preserve the rendered page without added blur or masking. Field values
+are omitted from JSON observations. Captures wait for document loading, visible
+session-loading or busy indicators, fonts, visible images, and finite animations
+to finish. Infinite animations do not block capture. `--timeout` sets one deadline for the command's browser action and
+screenshot, from `1ms` through `10m`. If an operation exceeds it, the session is
+closed. Action failures return nonzero; invalid commands and targets return exit code 2.
+The JSON `error.code` is machine-readable:
+
+| Code | Exit | Meaning |
+| --- | ---: | --- |
+| `invalid_invocation`, `invalid_target`, `invalid_session_id` | 2 | Fix the command or select a configured `local`/`dev` target. |
+| `browser_unavailable` | 1 | Install Chromium with `lmt-web install-browser`, then retry. |
+| `browser_start_failed` | 1 | The local browser owner exited before its session became ready. |
+| `service_unavailable` | 1 | The selected Web URL could not be reached; start/check that service. |
+| `session_not_found`, `session_unavailable` | 1 | The browser owner ended; start a fresh session. |
+| `deadline_exceeded`, `action_failed` | 1 | The action failed or exceeded its finite deadline. |
+
+Screenshots cover the viewport by default. `inspect --full-page` and
+`close --full-page` explicitly capture the complete document, including
+fields below the viewport. Password inputs retain the browser's normal rendering;
+revealed values and echoed text remain visible in screenshots.
+The screenshot metadata records `fullPage`; full-page mode applies only to that
+command and does not change the next capture's default.
+
+Screenshot failure is reported separately in `screenshot.outcome`; it does not
+change an otherwise completed browser action's `outcome`.
+
+Only configured `local` and `dev` Web URLs are supported. `prod`, implicit
+targets, and target fallback are rejected. Configure those URLs in
+`lmt.config.json` when running from a source checkout; the published package
+contains the non-secret `local` and `dev` Web URL values.
+
+## Build and test the standalone package
+
+From `live-market-terminal/`:
+
+```sh
+pnpm --filter @ai-digital-factory/lmt-web-cli build
+pnpm --filter @ai-digital-factory/lmt-web-cli typecheck
+pnpm --filter @ai-digital-factory/lmt-web-cli test
+pnpm --filter @ai-digital-factory/lmt-web-cli package:build
+```
+
+Generic interaction uses controls returned by the latest observation:
+
+```sh
+lmt-web inspect --session SESSION
+lmt-web fill --session SESSION --ref REFERENCE --value "draft text"
+lmt-web click --session SESSION --ref REFERENCE
+lmt-web select --session SESSION --ref REFERENCE --value NSE
+lmt-web scroll --session SESSION --y 500
+lmt-web navigate --session SESSION --url /operator
+```
+
+Every action returns an updated observation and screenshot. References expire with
+the next observation and never identify replacement elements. Use the references
+in each result for the next command. Missing, stale, and duplicate references fail
+explicitly. Navigation accepts a path or URL within the session's configured Origin;
+rendered links can follow the website's own handoff flow. Scroll offsets are pixels;
+`--ref` optionally scrolls a returned control instead of the page. Generic actions
+also accept `--timeout` and `--full-page`.
+
+Credential fields are detected from their type, labels, and attributes. Use
+`fill --secret` for sensitive values in other fields. Entered secrets remain in the
+live session's redaction registry, including when echoed into text or revealed in
+an input. JSON observations omit field values and redact secret text. Screenshots
+show the rendered page without additional masking.
+A click whose completion cannot be confirmed returns `outcome: "uncertain"` and a
+nonzero exit status. Pending browser loading is stopped to retain evidence, but the
+submitted server operation may still complete. Inspect before deciding what to do
+next; the CLI never repeats the click automatically. Screenshot capture has its
+own outcome even when the click is uncertain.
+
+Guided Operator login uses its own protected SMS read credential in `~/.lmt-web/secrets.pem`.
+Provision it through `lmt-web credential provision --env local --credential-stdin` using a secure input
+source (one line). The HTTP CLI uses `~/.lmt/secrets.pem` independently. Neither
+CLI copies or falls back to the other's credential. Provision Web separately,
+even if an HTTP CLI credential already exists. Updating either credential leaves
+the other CLI's credentials and saved sessions unchanged.
+
+Use `--env dev` for Dev Deployment. Web CLI does not support profiles. The
+environment validates the selected deployment; the SMS read credential is owned
+by this CLI and is not stored per environment. The former `--stdin` invocation
+remains available for compatibility.
+The Web CLI reads the selected environment's Gate Operator Directory and fills
+and submits the rendered Home Page form:
+
+```sh
+lmt-web operator-login --session ID
+lmt-web operator-logout --session ID
+```
+
+Login credentials stay in the live owner process. HTTP CLI authentication cookies
+are never imported. Operator logout activates Web controls and confirms Home;
+`close` only closes the browser. Both commands return page observations and a
+screenshot, including credential rejection or SMS lookup failure. A rejected
+login is reported as `incorrect_credentials`; missing provisioning is
+`sms_credential_missing`. Check the credential and selected Gate scope before
+starting another login.
+
+From the Zerodha Login Page, start the existing Web login flow explicitly:
+
+```sh
+lmt-web zerodha-login --session ID
+lmt-web zerodha-otp --session ID --attempt ATTEMPT_ID --stdin
+lmt-web zerodha-logout --session ID
+```
+
+`zerodha-login` returns `loginAttempt.attemptId` and `status: awaiting_otp` when
+Web offers an OTP Challenge. Supply a fresh six-digit OTP on standard input to
+`zerodha-otp`, using that exact attempt ID and browser session. The tool never
+retrieves an OTP or starts a replacement during OTP submission. An explicit retry
+is permitted after `otp_rejected` while the same attempt remains active.
+`attempt_replaced` and `attempt_unavailable` require inspecting the current page;
+neither starts another attempt. Success observes Market Watch.
+
+`zerodha-logout` activates the Authenticated Operator logout control and returns
+the Zerodha Login Page; `operator-logout` continues through Web to Home. These
+controls preserve the product's Broker-owned shared state semantics.
+An action reported as `uncertain` may have been submitted: inspect its screenshot
+and current page before deciding what to do. No mutation is automatically replayed.
+Revealed credential or OTP values remain visible in screenshots, as they do in Web.
+
+
+## Validate a fresh dev OTP Challenge
+
+Controlled package tests cover accepted and rejected credentials and OTPs on mobile
+and desktop. Live dev validation requires an authorized Operator and an OTP from
+the current challenge. Do this explicitly; an OTP from a previous attempt cannot
+validate a new session.
+
+1. Provision the SMS read credential through `credential provision --stdin` from a
+   secure input source, then run `lmt-web start --env dev`. Record `sessionId`, the
+   reported device, viewport, action outcome, and screenshot path.
+2. Run `lmt-web operator-login --session ID` and inspect the Zerodha Login Page
+   screenshot. Run `lmt-web zerodha-login --session ID` once. Record the returned
+   `loginAttempt.attemptId` only when its status is `awaiting_otp`.
+3. Obtain a fresh six-digit OTP for that active challenge from the authorized
+   person. Supply it on standard input to `lmt-web zerodha-otp --session ID
+   --attempt ATTEMPT_ID --stdin`. Do not put the OTP in command arguments, logs,
+   screenshots, or recorded acceptance notes. The command does not retrieve OTPs.
+4. Confirm success, Market Watch in the resulting observation, and a readable
+   viewport image. Run `lmt-web inspect --session ID --full-page` and inspect
+   its separate image and metadata. If the action is `uncertain`, inspect before
+   deciding anything further; do not automatically repeat the submission. If the
+   OTP is rejected, obtain another current OTP only while that attempt is active.
+5. To exercise explicit application logout, run `zerodha-logout` and then
+   `operator-logout` with that session ID, confirming their resulting pages. Run
+   `lmt-web close --session ID` to release the browser. Confirm a later `inspect`
+   reports the session is no longer live.
+6. Repeat with a new `start --env dev --device desktop` session and its own fresh
+   challenge and OTP. Add `--headed` when a visible browser is useful. Record the
+   validation date, device, non-secret outcomes, and local artifact paths. Keep
+   local evidence protected; this workflow does not upload it.
+
+Closing the browser alone does not perform application logout. Separate browser
+sessions still share the Operator's Broker-owned business state.
+
+## Clean-install acceptance
+
+The manual **Release LMT Web CLI** GitHub Action publishes this package from
+`main`. It selects the next npm patch version (or `0.1.0` for the first release),
+verifies the packed tarball with headless browser acceptance, reads the npm token
+through the existing CI SMS credential, and confirms public registry visibility.
+It does not deploy the application or modify the HTTP CLI's npm release.
+
+After `package:build`, run this from `live-market-terminal/`:
+
+```sh
+node ../.github/scripts/test-lmt-web-cli-package.mjs apps/web-cli/dist/npm
+```
+
+The script runs browser tests headlessly, packs and installs into a temporary
+directory, executes the installed bin,
+sets up its own Chromium runtime, verifies packaged runtime modules/configuration,
+and reuses all browser acceptance tests. Installed commands and their live owners
+run outside the checkout. Test-only fixture servers provide repeatable responses;
+this check performs no npm publication or live dev login.