@qontinui/ui-bridge-wrapper 0.4.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
@@ -63,7 +63,7 @@ or a global/dev install:
63
63
  | Bin | What it does |
64
64
  | --- | --- |
65
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. Prints one JSON result line; exit 0 = login confirmed. |
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
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
68
 
69
69
  Each bin supports `--help`.
@@ -79,6 +79,26 @@ standalone you must therefore also:
79
79
  2. Run `npx playwright install chromium` once (or point `PLAYWRIGHT_BROWSERS_PATH`
80
80
  at an existing Chromium download).
81
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
+
82
102
  Credentials for the login/capture bins come from `--email`/`--password` or the
83
103
  env vars `UIB_LOGIN_EMAIL` / `UIB_LOGIN_PASSWORD`. Git Bash callers should
84
104
  prefix `MSYS_NO_PATHCONV=1` so a leading-slash `--success` / path value is not
@@ -90,6 +110,32 @@ ui-bridge-login-web \
90
110
  --url "https://qontinui.io/login?next=%2Fbuild%2Fworkflows" \
91
111
  --success /build/workflows
92
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
+
93
120
  # capture the default admin coord pages
94
121
  ui-bridge-capture-specs --out ./spec-capture
95
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
+ ```
@@ -234,7 +234,20 @@ var HeadlessTransport = class extends BaseTransport {
234
234
  };
235
235
  }
236
236
  async onReady() {
237
- const { launchHeadlessTab } = await import('@qontinui/ui-bridge-headless');
237
+ let launchHeadlessTab;
238
+ try {
239
+ ({ launchHeadlessTab } = await import('@qontinui/ui-bridge-headless'));
240
+ } catch (err) {
241
+ const cause = err instanceof Error ? err.message : String(err);
242
+ throw new WrapperTransportError(
243
+ "INVALID_CONFIG",
244
+ `Transport kind '${this.kind}' needs the optional '@qontinui/ui-bridge-headless' peer, which is not installed. Install it and the Chromium browser:
245
+ npm i @qontinui/ui-bridge-headless && npx playwright install chromium
246
+ (bare \`npx @qontinui/ui-bridge-wrapper \u2026\` does NOT install peers \u2014 pass each peer with \`-p\`, e.g.
247
+ npx -y -p @qontinui/ui-bridge-wrapper -p @qontinui/ui-bridge -p @qontinui/ui-bridge-headless -p playwright ui-bridge-login-web \u2026)
248
+ Underlying import error: ${cause}`
249
+ );
250
+ }
238
251
  const initScripts = await this.buildInitScripts();
239
252
  const tab = await launchHeadlessTab({
240
253
  url: this.options.targetUrl,
@@ -692,6 +705,182 @@ function createTransport(config) {
692
705
  }
693
706
  }
694
707
 
708
+ // src/cli-args.ts
709
+ var COMMON_FLAGS = /* @__PURE__ */ new Set(["--help", "-h", "--quiet"]);
710
+ function isFlagShaped(value) {
711
+ return value.startsWith("--");
712
+ }
713
+ var ArgReader = class {
714
+ argv;
715
+ error;
716
+ /**
717
+ * @param argv Already sliced past `node script`.
718
+ * @param known All flags the bin recognizes (union the bin's set with {@link COMMON_FLAGS}).
719
+ * @param error Factory producing the bin's domain error type.
720
+ */
721
+ constructor(argv, known, error) {
722
+ this.argv = argv;
723
+ this.error = error;
724
+ for (const arg of argv) {
725
+ if (isFlagShaped(arg) && !known.has(arg)) {
726
+ throw error(`Unknown flag: ${arg}`);
727
+ }
728
+ }
729
+ }
730
+ /** True if `name` appears as a bare boolean flag. */
731
+ has(name) {
732
+ return this.argv.includes(name);
733
+ }
734
+ /**
735
+ * Value following the value-flag `name`, or `null` when the flag is absent OR
736
+ * has no following token (the caller defaults it). Throws when the following
737
+ * token is flag-shaped — the swallow this kit exists to kill.
738
+ */
739
+ value(name) {
740
+ const i = this.argv.indexOf(name);
741
+ if (i < 0 || i + 1 >= this.argv.length) return null;
742
+ const raw = this.argv[i + 1];
743
+ if (isFlagShaped(raw)) {
744
+ throw this.error(
745
+ `${name} expects a value but got the flag '${raw}' \u2014 did you omit ${name}'s argument?`
746
+ );
747
+ }
748
+ return raw;
749
+ }
750
+ };
751
+ function makeLogger(prefix, quiet) {
752
+ if (quiet) return () => {
753
+ };
754
+ return (m) => process.stderr.write(`${prefix} ${m}
755
+ `) ;
756
+ }
757
+
758
+ // src/login-drive.ts
759
+ var isCognito = (u) => /auth\.qontinui\.io|amazoncognito\.com|\/oauth2\//i.test(u);
760
+ var pathOf = (u) => {
761
+ try {
762
+ return new URL(u).pathname;
763
+ } catch {
764
+ return "";
765
+ }
766
+ };
767
+ var isAppLoginPath = (u) => /\/login(\b|\/|$)/.test(pathOf(u)) && !isCognito(u);
768
+ async function scrapeErrorCard(page) {
769
+ try {
770
+ const alerts = page.locator(
771
+ '[role="alert"], #loginErrorMessage, .error-message, [class*="error" i], [data-testid*="error" i]'
772
+ );
773
+ const an = await alerts.count();
774
+ for (let i = 0; i < an; i++) {
775
+ const el = alerts.nth(i);
776
+ if (await el.isVisible().catch(() => false)) {
777
+ const t = (await el.innerText().catch(() => "")).trim();
778
+ if (t) return t.slice(0, 500);
779
+ }
780
+ }
781
+ } catch {
782
+ }
783
+ return null;
784
+ }
785
+ async function loginDrive(page, { email, password, timeoutMs, log = () => {
786
+ } }) {
787
+ log(`landed ${page.url()}`);
788
+ const emailBtn = page.getByRole("button", { name: /continue with email/i }).or(page.getByText(/continue with email/i));
789
+ await emailBtn.first().waitFor({ state: "visible", timeout: 15e3 });
790
+ await emailBtn.first().click();
791
+ await page.waitForURL(
792
+ (u) => {
793
+ const s = u.toString();
794
+ return isCognito(s) || !isAppLoginPath(s) && !/\/auth\/callback/.test(pathOf(s));
795
+ },
796
+ { timeout: timeoutMs }
797
+ );
798
+ if (isCognito(page.url())) {
799
+ await page.waitForLoadState("domcontentloaded");
800
+ log(`cognito ${page.url()}`);
801
+ const fillFirst = async (sels, val, what) => {
802
+ for (const s of sels) {
803
+ const loc = page.locator(s);
804
+ const n = await loc.count().catch(() => 0);
805
+ for (let i = 0; i < n; i++) {
806
+ const el = loc.nth(i);
807
+ if (await el.isVisible().catch(() => false)) {
808
+ await el.fill(val, { timeout: 1e4 });
809
+ log(`filled ${what} via ${s} [visible #${i}]`);
810
+ return;
811
+ }
812
+ }
813
+ }
814
+ throw new Error(`Cognito ${what} field (visible) not found (selectors: ${sels.join(", ")})`);
815
+ };
816
+ await fillFirst(
817
+ [
818
+ "#signInFormUsername",
819
+ 'input[name="username"]',
820
+ 'input[type="email"]',
821
+ 'input[autocomplete="username"]'
822
+ ],
823
+ email,
824
+ "email"
825
+ );
826
+ await fillFirst(
827
+ [
828
+ "#signInFormPassword",
829
+ 'input[name="password"]',
830
+ 'input[type="password"]',
831
+ 'input[autocomplete="current-password"]'
832
+ ],
833
+ password,
834
+ "password"
835
+ );
836
+ const submitLoc = page.locator(
837
+ 'input[name="signInSubmitButton"], button[type="submit"], input[type="submit"], [name="signInSubmitButton"]'
838
+ );
839
+ let clicked = false;
840
+ const sn = await submitLoc.count().catch(() => 0);
841
+ for (let i = 0; i < sn; i++) {
842
+ const el = submitLoc.nth(i);
843
+ if (await el.isVisible().catch(() => false)) {
844
+ await el.click();
845
+ clicked = true;
846
+ log(`clicked submit [visible #${i}]`);
847
+ break;
848
+ }
849
+ }
850
+ if (!clicked) {
851
+ await page.getByRole("button", { name: /sign in|log in|continue|submit/i }).first().click();
852
+ log("clicked submit [role fallback]");
853
+ }
854
+ try {
855
+ await page.waitForURL(
856
+ (u) => {
857
+ const s = u.toString();
858
+ return !isCognito(s) && !/\/auth\/callback/.test(pathOf(s));
859
+ },
860
+ { timeout: timeoutMs }
861
+ );
862
+ } catch {
863
+ const errorText2 = await scrapeErrorCard(page);
864
+ const finalUrl2 = page.url();
865
+ log(`final ${finalUrl2} (stalled)`);
866
+ return { ok: false, finalUrl: finalUrl2, landingPath: pathOf(finalUrl2), errorText: errorText2 };
867
+ }
868
+ }
869
+ await page.waitForLoadState("networkidle").catch(() => {
870
+ });
871
+ await page.waitForFunction(
872
+ () => window.__uiBridgeInjected?.ready === true,
873
+ { timeout: 15e3 }
874
+ ).catch(() => {
875
+ });
876
+ const finalUrl = page.url();
877
+ log(`final ${finalUrl}`);
878
+ const landingPath = await page.evaluate(() => location.pathname).catch(() => pathOf(finalUrl));
879
+ const ok = !isAppLoginPath(finalUrl) && !isCognito(finalUrl) && !/\/auth\/callback/.test(pathOf(finalUrl));
880
+ const errorText = ok ? null : await scrapeErrorCard(page);
881
+ return { ok, finalUrl, landingPath, errorText };
882
+ }
883
+
695
884
  // src/capture-specs-cli.ts
696
885
  var USAGE = `ui-bridge-capture-specs \u2014 log in and snapshot authed pages via the injected transport
697
886
 
@@ -708,6 +897,8 @@ Options:
708
897
  the two admin coord pages.
709
898
  --device <id> device_id query for the default trees page.
710
899
  --timeout <ms> Per-hop wait budget (default 70000).
900
+ --quiet Suppress human-readable stderr logs (the per-page
901
+ JSON lines still print).
711
902
  --help, -h Print this help and exit.
712
903
 
713
904
  Prerequisites (packaged bin): the optional @qontinui/ui-bridge-headless peer must
@@ -746,15 +937,6 @@ function defaultTargets(origin, device) {
746
937
  { slug: "admin-coord-pull-decisions", url: `${origin}/admin/coord/pull-decisions` }
747
938
  ];
748
939
  }
749
- var isCognito = (u) => /auth\.qontinui\.io|amazoncognito\.com|\/oauth2\//i.test(u);
750
- var pathOf = (u) => {
751
- try {
752
- return new URL(u).pathname;
753
- } catch {
754
- return "";
755
- }
756
- };
757
- var isLoginPath = (u) => /\/login(\b|\/|$)/.test(pathOf(u)) && !isCognito(u);
758
940
  function computeLoginUrl(targets, origin) {
759
941
  let firstNext = null;
760
942
  try {
@@ -766,16 +948,10 @@ function computeLoginUrl(targets, origin) {
766
948
  return { loginUrl, firstNext };
767
949
  }
768
950
  function parseArgs(argv) {
769
- const valueOf = (name) => {
770
- const i = argv.indexOf(name);
771
- return i >= 0 && i + 1 < argv.length ? argv[i + 1] ?? null : null;
772
- };
773
- const has = (name) => argv.includes(name);
774
- for (const arg of argv) {
775
- if (arg.startsWith("--") && !KNOWN_FLAGS.has(arg)) {
776
- throw new CaptureCliArgError(`Unknown flag: ${arg}`);
777
- }
778
- }
951
+ const mkError = (m) => new CaptureCliArgError(m);
952
+ const reader = new ArgReader(argv, KNOWN_FLAGS, mkError);
953
+ const valueOf = (name) => reader.value(name);
954
+ const has = (name) => reader.has(name);
779
955
  const help = has("--help") || has("-h");
780
956
  const origin = valueOf("--origin") ?? DEFAULT_ORIGIN;
781
957
  const device = valueOf("--device") ?? DEFAULT_DEVICE;
@@ -785,6 +961,15 @@ function parseArgs(argv) {
785
961
  throw new CaptureCliArgError(`--timeout expects a positive integer (got ${timeoutRaw})`);
786
962
  }
787
963
  const pagesSpec = valueOf("--pages");
964
+ let pages = null;
965
+ if (pagesSpec !== null) {
966
+ pages = parsePages(pagesSpec, origin);
967
+ if (pages.length === 0) {
968
+ throw new CaptureCliArgError(
969
+ `--pages was given but parsed to zero targets (got '${pagesSpec}'); omit --pages for the default pages, or pass 'slug=path[,slug=path]'`
970
+ );
971
+ }
972
+ }
788
973
  const args = {
789
974
  email: valueOf("--email") ?? process.env.UIB_LOGIN_EMAIL ?? "",
790
975
  password: valueOf("--password") ?? process.env.UIB_LOGIN_PASSWORD ?? "",
@@ -792,7 +977,8 @@ function parseArgs(argv) {
792
977
  origin,
793
978
  device,
794
979
  timeoutMs,
795
- pages: pagesSpec ? parsePages(pagesSpec, origin) : null,
980
+ pages,
981
+ quiet: has("--quiet"),
796
982
  help
797
983
  };
798
984
  validateArgs(args);
@@ -806,8 +992,7 @@ var KNOWN_FLAGS = /* @__PURE__ */ new Set([
806
992
  "--pages",
807
993
  "--device",
808
994
  "--timeout",
809
- "--help",
810
- "-h"
995
+ ...COMMON_FLAGS
811
996
  ]);
812
997
  function validateArgs(args) {
813
998
  if (args.help) return;
@@ -815,24 +1000,6 @@ function validateArgs(args) {
815
1000
  throw new CaptureCliArgError("need creds (UIB_LOGIN_EMAIL/PASSWORD or --email/--password)");
816
1001
  }
817
1002
  }
818
- function log(m) {
819
- process.stderr.write(`[capture] ${m}
820
- `);
821
- }
822
- async function fillVisible(page, sels, val, what) {
823
- for (const s of sels) {
824
- const loc = page.locator(s);
825
- const n = await loc.count().catch(() => 0);
826
- for (let i = 0; i < n; i++) {
827
- const el = loc.nth(i);
828
- if (await el.isVisible().catch(() => false)) {
829
- await el.fill(val, { timeout: 1e4 });
830
- return;
831
- }
832
- }
833
- }
834
- throw new Error(`Cognito ${what} field not found`);
835
- }
836
1003
  async function main() {
837
1004
  let args;
838
1005
  try {
@@ -851,9 +1018,9 @@ ${USAGE}`);
851
1018
  process.exit(0);
852
1019
  }
853
1020
  const { email, password, out, origin, device, timeoutMs } = args;
1021
+ const log = makeLogger("[capture]", args.quiet);
854
1022
  const targets = args.pages ?? defaultTargets(origin, device);
855
- const { loginUrl, firstNext } = computeLoginUrl(targets, origin);
856
- const landedAuthed = (u) => firstNext ? pathOf(u) === pathOf(`${origin}${firstNext}`) : pathOf(u).includes("/dashboard") || pathOf(u).includes("/build");
1023
+ const { loginUrl } = computeLoginUrl(targets, origin);
857
1024
  const transport = createTransport({
858
1025
  kind: "injected",
859
1026
  options: { targetUrl: loginUrl, waitForSettle: false, readyTimeoutMs: 45e3 }
@@ -861,67 +1028,9 @@ ${USAGE}`);
861
1028
  transport.register("run", async (_p, ctx) => {
862
1029
  const page = ctx.page;
863
1030
  log(`login: ${page.url()}`);
864
- await page.getByRole("button", { name: /continue with email/i }).or(page.getByText(/continue with email/i)).first().click({ timeout: 2e4 });
865
- await page.waitForURL((u) => isCognito(u.toString()) || landedAuthed(u.toString()), {
866
- timeout: timeoutMs
867
- });
868
- if (isCognito(page.url())) {
869
- await page.waitForLoadState("domcontentloaded");
870
- await fillVisible(
871
- page,
872
- ["#signInFormUsername", 'input[name="username"]', 'input[type="email"]'],
873
- email,
874
- "email"
875
- );
876
- await fillVisible(
877
- page,
878
- ["#signInFormPassword", 'input[name="password"]', 'input[type="password"]'],
879
- password,
880
- "password"
881
- );
882
- const sub = page.locator(
883
- 'input[name="signInSubmitButton"], button[type="submit"], input[type="submit"]'
884
- );
885
- const sn = await sub.count();
886
- let done = false;
887
- for (let i = 0; i < sn; i++) {
888
- if (await sub.nth(i).isVisible().catch(() => false)) {
889
- await sub.nth(i).click();
890
- done = true;
891
- break;
892
- }
893
- }
894
- if (!done) await page.getByRole("button", { name: /sign in|continue/i }).first().click();
895
- try {
896
- await page.waitForURL(
897
- (u) => !isCognito(u.toString()) && !/^\/auth\/callback/.test(pathOf(u.toString())),
898
- { timeout: timeoutMs }
899
- );
900
- } catch {
901
- let errorText = null;
902
- try {
903
- const alerts = page.locator(
904
- '[role="alert"], #loginErrorMessage, .error-message, [class*="error" i], [data-testid*="error" i]'
905
- );
906
- const an = await alerts.count();
907
- for (let i = 0; i < an && !errorText; i++) {
908
- const el = alerts.nth(i);
909
- if (await el.isVisible().catch(() => false)) {
910
- const t = (await el.innerText().catch(() => "")).trim();
911
- if (t) errorText = t.slice(0, 500);
912
- }
913
- }
914
- } catch {
915
- }
916
- throw new Error(
917
- `login stalled on ${pathOf(page.url())}${errorText ? ` \u2014 ${errorText}` : ""}`
918
- );
919
- }
920
- }
921
- await page.waitForLoadState("networkidle").catch(() => {
922
- });
923
- if (isLoginPath(page.url())) {
924
- throw new Error(`login failed \u2014 bounced back to ${pathOf(page.url())}`);
1031
+ const r = await loginDrive(page, { email, password, timeoutMs, log });
1032
+ if (!r.ok) {
1033
+ throw new Error(`login stalled on ${r.landingPath}${r.errorText ? ` \u2014 ${r.errorText}` : ""}`);
925
1034
  }
926
1035
  log(`authed: ${page.url()}`);
927
1036
  const out2 = [];
@@ -944,7 +1053,7 @@ ${USAGE}`);
944
1053
  err = e instanceof Error ? e.message : String(e);
945
1054
  }
946
1055
  const finalUrl = page.url();
947
- const onLogin = isLoginPath(finalUrl);
1056
+ const onLogin = isAppLoginPath(finalUrl);
948
1057
  out2.push({
949
1058
  slug: t.slug,
950
1059
  requestedUrl: t.url,
@@ -1013,11 +1122,8 @@ exports.CaptureCliArgError = CaptureCliArgError;
1013
1122
  exports.USAGE = USAGE;
1014
1123
  exports.computeLoginUrl = computeLoginUrl;
1015
1124
  exports.defaultTargets = defaultTargets;
1016
- exports.isCognito = isCognito;
1017
- exports.isLoginPath = isLoginPath;
1018
1125
  exports.parseArgs = parseArgs;
1019
1126
  exports.parsePages = parsePages;
1020
- exports.pathOf = pathOf;
1021
1127
  exports.validateArgs = validateArgs;
1022
1128
  //# sourceMappingURL=capture-specs-cli.cjs.map
1023
1129
  //# sourceMappingURL=capture-specs-cli.cjs.map