@ai-digital-factory/lmt-web-cli 0.1.3 → 0.1.5

package/README.md

@@ -25,14 +25,15 @@ separately from `lmt-cli` and does not use profiles:
 npx --yes @ai-digital-factory/lmt-web-cli@latest credential provision --env dev --credential-stdin
 ```
 
-Start a fresh desktop session against Dev and keep the returned `sessionId` for every
+Start or restore a desktop session against Dev and keep the returned `sessionId` for every
 later command:
 
 ```sh
 npx --yes @ai-digital-factory/lmt-web-cli@latest start --env dev --device desktop
 ```
 
-The session starts on the Home Page. Use the same session to log into the Operator;
+A new session starts on the Home Page; a restored session follows Web’s existing
+authentication state. Use the same session to log into the Operator when required;
 if a Zerodha login is required, start that flow and submit the current OTP through
 standard input only, using the `attemptId` returned by `zerodha-login`:
 
@@ -42,7 +43,8 @@ npx --yes @ai-digital-factory/lmt-web-cli@latest zerodha-login --session SESSION
 npx --yes @ai-digital-factory/lmt-web-cli@latest zerodha-otp --session SESSION_ID --attempt ATTEMPT_ID --stdin
 ```
 
-The user supplies the OTP for the active attempt. Never put it in a command-line
+`zerodha-cancel --session SESSION_ID` cancels a waiting attempt through the page's
+**Cancel login** control. The user supplies the OTP for the active attempt. Never put it in a command-line
 argument or ask the CLI to retrieve it. Inspect the latest JSON result after each
 command. Control references are short-lived: every new observation or action returns
 fresh references, so use only references from the most recent result.
@@ -66,9 +68,34 @@ Broker activity. The CLI also supports `inspect`, `click`, `fill`, `select`, and
 `navigate`; run `npx --yes @ai-digital-factory/lmt-web-cli@latest --help` for the
 complete command list.
 
+## Interactive Zerodha login (human)
+
+Agents cannot receive the Zerodha OTP, so a human logs the saved Web CLI session
+into Zerodha once and agents then restore it with `start`. Run `lmt-web` with no
+arguments (or `lmt-web interactive`) in a terminal:
+
+```sh
+npx --yes @ai-digital-factory/lmt-web-cli@latest
+```
+
+Use ↑/↓ and Enter to choose **Login to Zerodha** or **Logout from Zerodha**; press
+`q` to quit. Logout asks for `y` to confirm, then uses Web's Logout Zerodha control;
+the Operator stays logged in, so the next login needs only the OTP. Interactive
+mode targets `--env dev --device desktop` by default; pass `--env local` or
+`--device mobile` to log in to another saved session. It restores or reuses that
+saved headless browser, logs in to the Operator with the provisioned SMS credential
+when required, starts the Zerodha Login Attempt, and asks for the OTP as a masked
+six-digit field. An attempt left waiting from earlier (for example by an agent) is
+cancelled first, so every run issues a fresh challenge. A rejected OTP can be
+retried on the same attempt; Esc cancels without submitting. An uncertain submission is never replayed—check the page with
+`inspect` first. On exit, a browser started by interactive mode is stopped (its
+login stays saved); a browser that was already running stays open.
+
+Interactive mode requires a terminal; without one it exits with status 2.
+
 ## Install
 
-Requires Node.js 22 or later, Chromium, and a macOS or Linux session owner.
+Requires Node.js 22.13 or later, Chromium, and a macOS or Linux session owner.
 Install the CLI and its browser:
 
 ```sh
@@ -106,7 +133,8 @@ 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`.
+visibility is selected by `start`. Mobile and desktop keep independent saved sessions.
+To change visibility for an already-live device, close its browser first or use `--fresh`.
 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.
@@ -133,18 +161,70 @@ the page or taking a final screenshot. It also works after the browser window ha
 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.
+`start` automatically restores saved authentication for the selected environment,
+Web Origin, and device, or reuses that device's live browser and returns its session
+ID. Every later command needs that ID. Reusing a live browser preserves its current
+page; concurrent commands run in order. Separate mobile and desktop sessions each
+need their own initial login and restore independently thereafter.
+
+Closing, stopping, losing the owner process, or restarting the machine preserves
+saved authentication. A subsequent `start` creates a new browser owner and restores
+the same Operator Session cookies when still valid. Gate's expiry, daily-visit
+renewal, revocation, and per-Operator-Session Zerodha authentication remain authoritative.
+Restoration never submits credentials or starts an OTP Challenge. Results include
+`authentication.status` when a recognized Web surface is visible: `operator_login_required`,
+`zerodha_login_required`, or `authenticated`. Follow that state before logging in.
+
+Use `start --env dev --device desktop --fresh` for temporary, isolated login-flow
+testing. It neither reads nor overwrites the normal saved session, and its own
+login is not retained after closure. Closing a browser does not log out, revoke an
+Operator Session, or stop Broker activity. Explicit Zerodha logout is retained;
+Operator logout removes that browser's saved Operator Session. Neither logs out
+another device.
+
+The CLI saves only cookies applicable to the configured Web Origin, during the
+live session and before successful commands return. It does not persist page
+content, passwords, OTPs, localStorage, or third-party Kite cookies, and never imports
+`lmt` authentication. Saved cookies are replayable authentication stored in private
+SQLite files under `~/.lmt-web/sessions` (directory mode 0700, files 0600). Anyone
+acting as the same OS user can reuse them; keychain encryption is not required.
+`LMT_WEB_STATE_DIRECTORY` overrides the private parent directory for isolated setups.
+Unsafe ownership/permissions, symlinks, or corrupt state fail explicitly with
+`saved_session_unavailable`; there is no silent fallback that overwrites bad state.
+Cookies already committed before a process failure can be restored; a failure between
+a server change and its local checkpoint can still require login. Server-side logout
+or revocation cannot be reversed by an older saved cookie.
+
+Results distinguish action completion from the browser's authentication state.
+For example, a successful `operator-login` can return:
+
+```json
+{"outcome":"success","authentication":{"status":"zerodha_login_required","nextAction":"zerodha-login"}}
+```
+
+`authentication.status` is `operator_login_required`, `zerodha_login_required`,
+`zerodha_session_restoring`, `authenticated`, or `unknown`. It observes the
+rendered session surface, including Settings, rather than inferring admission
+from a URL or saved token presence.
+Unrecognized, conflicting, or unavailable page observations return `unknown`;
+a generic loading screen that exceeds the command deadline also returns
+`unknown` alongside the existing action error. `stop` has no page observation
+and returns `unknown`.
+
+When present, `authentication.nextAction` names `operator-login`, `zerodha-login`,
+or `zerodha-otp`. The OTP action includes `authentication.attemptId` for the active
+challenge, also available through `inspect`. It is omitted while an attempt is
+submitting or is no longer accepting OTPs; inspect the page and its error before
+deciding to retry. Supply the OTP through `--stdin` with that attempt ID in the
+same browser session. No login or OTP submission is performed by inspection.
+After successful OTP submission, `authentication.status` is `authenticated`.
+Keep that session alive for Market Watch and pairing QA; `lmt` authentication
+does not transfer to a new `lmt-web` session.
 
 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
+controls, `authentication`, emulated device and actual viewport, and screenshot
+outcome. Images
 are written to unique absolute paths in an owner-only temporary directory;
 screenshots solid-mask only Zerodha access-token value fields marked with
 `data-lmt-sensitive="zerodha-access-token"`; other controls and metadata stay visible.
@@ -155,8 +235,11 @@ session-loading or busy indicators, fonts, visible images, and finite animations
 to finish. The page must render text, controls, or visual content; an empty app
 root is not ready. Pages that remain empty reach the command deadline without a
 captured screenshot. 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.
+screenshot, from `1ms` through `10m`. A recoverable action timeout stops pending loading, waits for the operation to
+settle, and retains a responsive browser. Unsettled work, an unresponsive renderer,
+or an overall inspection/capture deadline can close the owner; use `start` to
+restore saved authentication. Submitted actions remain uncertain and are never
+automatically replayed. Action failures return nonzero; invalid commands and targets return exit code 2.
 The JSON `error.code` is machine-readable:
 
 | Code | Exit | Meaning |
@@ -165,7 +248,8 @@ The JSON `error.code` is machine-readable:
 | `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. |
+| `session_not_found`, `session_unavailable` | 1 | The browser owner ended; use `start` to restore it. |
+| `saved_session_unavailable` | 1 | Check ownership, private permissions, and integrity of saved-session storage. |
 | `deadline_exceeded`, `action_failed` | 1 | The action failed or exceeded its finite deadline. |
 
 Screenshots cover the viewport by default. `inspect --full-page` and
@@ -216,8 +300,9 @@ 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.
+an input. General JSON observations omit field values and redact secret text; explicit
+reads follow the ordinary-value/secret-metadata contract below. Screenshots mask secret
+values and their learned echoes.
 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
@@ -335,6 +420,7 @@ this check performs no npm publication or live dev login.
 ```sh
 lmt-web read --session ID --ref FIELD
 lmt-web clipboard --session ID
+lmt-web paste --session ID --ref FIELD
 lmt-web check --session ID --ref FIELD --stdin < /path/to/protected-expectation
 lmt-web clipboard-check --session ID --ref FIELD
 lmt-web scroll --session ID --ref FIELD
@@ -342,19 +428,49 @@ lmt-web scroll --session ID --y 600
 lmt-web inspect --session ID --full-page
 ```
 
-read returns an ordinary field value. clipboard returns content only when it matches
-a verified ordinary field on the current page; unknown or secret content is refused.
+`read` returns `value` for an ordinary field, including Settings User ID. A protected
+field returns only `secret: {present, length, fingerprint}`. `fingerprint` is the
+12-hex SHA-256 prefix used in Broker token logs, or null for an empty value.
+`clipboard` returns an ordinary value only when it matches a verified ordinary field;
+otherwise it returns the same safe secret metadata. Reveal the saved token before
+reading it: hidden/capture-safe placeholders report `value_unreadable`, never metadata
+for the placeholder. Copy still permits safe clipboard metadata in capture-safe mode.
 check compares the field with one stdin-supplied expectation (an optional final newline
 is removed). clipboard-check compares clipboard and field inside the browser session.
 Comparisons return only matches: true or matches: false. An unreadable field/clipboard
 or an expired reference is an error without a matches result. Inspect/action observations
 continue to redact secrets, including revealed fields.
 
+`paste` reads the clipboard and updates a protected input or textarea entirely inside
+the browser. It returns secret metadata and `matches: true` only after the field retains
+the value. It does not submit the form. Read-only, ordinary, missing or rejecting fields
+and unreadable clipboards fail explicitly. A failed paste has no equality result.
+
+For current-token verification, use the existing saved browser session: navigate to
+Settings, click Copy access token, inspect clipboard metadata, click Replace access token,
+then `paste --ref` the Replacement access token input. Use fresh references from each
+result. `clipboard-check` can prove the pasted field matches. Explicitly click Validate
+and replace and inspect the resulting verification or refusal message. All actions use
+the rendered controls; no HTTP Runner profile or direct API probing is required.
+
+Screenshots mask protected field values and learned secret echoes while keeping ordinary
+fields and labels readable. Every result still includes its independent screenshot outcome.
+Same-origin browser requests carry `x-lmt-client-kind: cli` and
+`x-lmt-client-profile: web-cli-desktop|web-cli-mobile`. Control actions also send a
+`journey_step` audit through the browser to Gate's existing `/api/journey-records` ingest:
+step `Web CLI <action>`, browser session correlation, CLI attribution, action outcome and
+screenshot outcome only. No field/clipboard value, reference label or payload is logged.
+`audit.outcome` reports `recorded` only for HTTP 202; `failed`/`unavailable` means logging
+has not been established and does not reverse an already completed browser action.
+In OpenObserve, discover the current `journey_step` fields and filter by step, browser
+session and the bounded run window; join API traces using the attributed request rows.
+
 Referenced scrolling brings the control into view through its ancestors. Pixel scrolling
 targets the largest scrolling content area. Results include before/after positions and
 moved, already_visible, or at_boundary. Each observation expires older references.
+A referenced control still outside the clipped visible area reports `target_unreachable`.
 
 Full-page capture temporarily expands inner scrolling content and restores its styles
 and positions afterward. A screenshot with unexpanded clipped content reports failed;
-browser-action and screenshot outcomes remain separate. Screenshots retain the existing
-rendered-page confidentiality behavior: protect their files as you would the visible UI.
+browser-action and screenshot outcomes remain separate. Protect screenshot files as
+evidence even though their secret values are masked.