@qontinui/ui-bridge-wrapper 0.2.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,3 +50,92 @@ await transport.close();
50
50
 
51
51
  Phase 3 of the wrapper plan adds a scaffold CLI on top of this package;
52
52
  Phase 4 ships reference wrappers that exercise all four transports.
53
+
54
+ ## CLI bins
55
+
56
+ The package ships three executables. Each resolves the engine bundle
57
+ (`@qontinui/ui-bridge/injected/bundle.global.js`) from the wrapper package's
58
+ own module tree via the injected transport's `createRequire(import.meta.url)`,
59
+ so **they run from any directory once installed** — there is no "must run from
60
+ the ui-bridge repo root" coupling. Run via `npx @qontinui/ui-bridge-wrapper`
61
+ or a global/dev install:
62
+
63
+ | Bin | What it does |
64
+ | --- | --- |
65
+ | `ui-bridge-inject` | Drive the injected transport against a UI-Bridge-free page (exec one-shot actions, or register as a relay tab). |
66
+ | `ui-bridge-login-web` | Automated web login via the injected transport — drives the full Cognito OAuth redirect chain in one headless tab. Optionally asserts on-page text (`--expect-text`) and screenshots the authed landing (`--screenshot`/`--scroll-to`). Prints one JSON result line; exit 0 = login confirmed AND all expected text present. |
67
+ | `ui-bridge-capture-specs` | Log in (same flow) then `goto` + snapshot a set of authed pages, writing one `<slug>.snapshot.json` per page. |
68
+
69
+ Each bin supports `--help`.
70
+
71
+ ### Prerequisites for the browser-driving bins
72
+
73
+ `ui-bridge-login-web` and `ui-bridge-capture-specs` launch Chromium via the
74
+ injected transport, which dynamically imports `@qontinui/ui-bridge-headless`
75
+ (it carries `playwright` as a real dependency). When installing the wrapper
76
+ standalone you must therefore also:
77
+
78
+ 1. Install the optional `@qontinui/ui-bridge-headless` peer alongside it, and
79
+ 2. Run `npx playwright install chromium` once (or point `PLAYWRIGHT_BROWSERS_PATH`
80
+ at an existing Chromium download).
81
+
82
+ > **A bare `npx @qontinui/ui-bridge-wrapper …` does NOT install peers** — it
83
+ > fetches only the wrapper, so the dynamic `import('@qontinui/ui-bridge-headless')`
84
+ > dies with `ERR_MODULE_NOT_FOUND`. For a zero-install one-off, name every package
85
+ > with `-p` so npx stages them together:
86
+ >
87
+ > ```bash
88
+ > npx -y \
89
+ > -p @qontinui/ui-bridge-wrapper \
90
+ > -p @qontinui/ui-bridge \
91
+ > -p @qontinui/ui-bridge-headless \
92
+ > -p playwright \
93
+ > ui-bridge-login-web \
94
+ > --url "https://qontinui.io/login?next=%2Fbuild%2Fworkflows" \
95
+ > --success /build/workflows
96
+ > ```
97
+ >
98
+ > (Still run `npx playwright install chromium` once for the browser binary.) The
99
+ > bare-bin examples below assume a local/global/dev install where the peer is
100
+ > already on the module path.
101
+
102
+ Credentials for the login/capture bins come from `--email`/`--password` or the
103
+ env vars `UIB_LOGIN_EMAIL` / `UIB_LOGIN_PASSWORD`. Git Bash callers should
104
+ prefix `MSYS_NO_PATHCONV=1` so a leading-slash `--success` / path value is not
105
+ rewritten into a Windows path before the bin sees it.
106
+
107
+ ```bash
108
+ # log in and confirm the authed landing is /build/workflows
109
+ ui-bridge-login-web \
110
+ --url "https://qontinui.io/login?next=%2Fbuild%2Fworkflows" \
111
+ --success /build/workflows
112
+
113
+ # log in, land on /operations, assert the gates panel rendered, screenshot it
114
+ ui-bridge-login-web \
115
+ --url "https://qontinui.io/login?next=%2Foperations" \
116
+ --success /operations \
117
+ --expect-text "option2-actions-outage-drill,metric_threshold" \
118
+ --screenshot out.png
119
+
120
+ # capture the default admin coord pages
121
+ ui-bridge-capture-specs --out ./spec-capture
122
+ ```
123
+
124
+ #### Sourcing credentials from SSM (qontinui operators)
125
+
126
+ The bins read credentials from env / flags only — they intentionally do **not**
127
+ embed any SSM lookup, since `@qontinui/ui-bridge-wrapper` is a general-purpose
128
+ package. Operators with access to the operator parameters can populate the env
129
+ vars before invoking a bin. On this fleet `aws` resolves under PowerShell (the
130
+ git-bash profile diverges), so prefer the PowerShell form:
131
+
132
+ ```powershell
133
+ $env:UIB_LOGIN_EMAIL = (aws ssm get-parameter --name /qontinui/operator/email --with-decryption --region eu-central-1 --query Parameter.Value --output text)
134
+ $env:UIB_LOGIN_PASSWORD = (aws ssm get-parameter --name /qontinui/operator/password --with-decryption --region eu-central-1 --query Parameter.Value --output text)
135
+ ```
136
+
137
+ ```bash
138
+ # bash equivalent (only where `aws` is on PATH for this shell)
139
+ export UIB_LOGIN_EMAIL="$(aws ssm get-parameter --name /qontinui/operator/email --with-decryption --region eu-central-1 --query Parameter.Value --output text)"
140
+ export UIB_LOGIN_PASSWORD="$(aws ssm get-parameter --name /qontinui/operator/password --with-decryption --region eu-central-1 --query Parameter.Value --output text)"
141
+ ```