@esimplicitylabs/katalyst-xspec 0.7.1 → 0.8.0

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  apiLoginAsRole,
   assertMasked,
   clearFetchIntercept,
   defaultBearerConfig,
@@ -33,8 +34,9 @@ import {
   setupBearerAuth,
   setupBypassAuth,
   setupFetchIntercept,
-  tryParseJson
-} from "./chunk-UTTKW2SR.js";
+  tryParseJson,
+  uiLoginAsRole
+} from "./chunk-VHVH476W.js";
 
 // src/fixtures.ts
 import { test as base } from "playwright-bdd";
@@ -69,6 +71,110 @@ function resolveApiRequestTarget(baseURL, env = process.env) {
   return { baseURL: rewritten, extraHTTPHeaders: { Host: host } };
 }
 
+// src/targets.ts
+var DEFAULT_URL = "http://localhost:3000";
+function resolveTargets(env = process.env) {
+  const frontend = env.FRONTEND_URL ? { frontendUrl: env.FRONTEND_URL, frontendSource: "FRONTEND_URL" } : env.BASE_URL ? { frontendUrl: env.BASE_URL, frontendSource: "BASE_URL" } : { frontendUrl: DEFAULT_URL, frontendSource: "default" };
+  const api = env.API_BASE_URL ? { apiBaseUrl: env.API_BASE_URL, apiSource: "API_BASE_URL" } : env.TARGET_BASE_URL ? { apiBaseUrl: env.TARGET_BASE_URL, apiSource: "TARGET_BASE_URL" } : env.TARGET_PORT ? { apiBaseUrl: `http://localhost:${env.TARGET_PORT}`, apiSource: "TARGET_PORT" } : frontend.frontendSource !== "default" ? { apiBaseUrl: frontend.frontendUrl, apiSource: "FRONTEND_URL" } : { apiBaseUrl: DEFAULT_URL, apiSource: "default" };
+  return { ...frontend, ...api };
+}
+function resolveApiBaseUrl({
+  env = process.env,
+  projectName = "",
+  projectBaseURL
+}) {
+  return env.API_BASE_URL || env.TARGET_BASE_URL || (projectName.includes("api") ? projectBaseURL : void 0) || (env.TARGET_PORT ? `http://localhost:${env.TARGET_PORT}` : void 0) || projectBaseURL || DEFAULT_URL;
+}
+function formatTargets(t) {
+  return `katalyst-xspec targets: UI ${t.frontendUrl} (${t.frontendSource}) | API ${t.apiBaseUrl} (${t.apiSource})`;
+}
+function shouldLogTargets(env = process.env, argv = process.argv) {
+  const quiet = env.KATALYST_XSPEC_QUIET?.trim().toLowerCase();
+  if (quiet && quiet !== "false" && quiet !== "0") return false;
+  if (env.TEST_WORKER_INDEX !== void 0) return false;
+  if (argv.some((a) => /bddgen/.test(a))) return false;
+  return true;
+}
+function logTargets(targets = resolveTargets()) {
+  if (shouldLogTargets()) console.log(formatTargets(targets));
+  return targets;
+}
+
+// src/auth/credentials.ts
+var MissingCredentialsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingCredentialsError";
+  }
+};
+function roleEnvKeys(role) {
+  const key = role.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_|_$/g, "");
+  return { username: `AUTH_${key}_USERNAME`, password: `AUTH_${key}_PASSWORD` };
+}
+var LEGACY_KEYS = {
+  admin: { username: ["DEFAULT_ADMIN_USERNAME", "DEFAULT_ADMIN_EMAIL"], password: ["DEFAULT_ADMIN_PASSWORD"] },
+  user: { username: ["DEFAULT_USER_USERNAME", "NON_ADMIN_USERNAME"], password: ["DEFAULT_USER_PASSWORD", "NON_ADMIN_PASSWORD"] }
+};
+function resolveCredentials(role, { env = process.env, roles } = {}) {
+  const fromCode = roles && Object.entries(roles).find(([name]) => name.toLowerCase() === role.toLowerCase())?.[1];
+  const keys = roleEnvKeys(role);
+  const legacy = LEGACY_KEYS[role.toLowerCase()];
+  const pick = (primary, fallbacks = []) => [primary, ...fallbacks].map((k) => env[k]).find(Boolean);
+  const username = fromCode?.username || pick(keys.username, legacy?.username);
+  const password = fromCode?.password || pick(keys.password, legacy?.password);
+  if (username && password) return { username, password };
+  const missing = !username ? "username" : "password";
+  const alsoAccepted = legacy?.[missing]?.length ? ` (${legacy[missing].join(" or ")} also work)` : "";
+  throw new MissingCredentialsError(
+    `No ${missing} for role "${role}". Set ${keys[missing]} in .env${alsoAccepted}, or pass roles: { '${role}': { username, password } } to UniversalAuthAdapter.`
+  );
+}
+
+// src/auth/api-login.ts
+var DEFAULT_TOKEN_PATHS = ["access_token", "token", "accessToken", "data.access_token", "data.token", "data.accessToken"];
+function buildApiLoginRequest(creds, env = process.env) {
+  const body = (env.API_AUTH_BODY || "form").trim().toLowerCase();
+  if (body !== "form" && body !== "json") {
+    throw new Error(`API_AUTH_BODY must be "form" or "json" (got "${env.API_AUTH_BODY}")`);
+  }
+  return {
+    path: env.API_AUTH_LOGIN_PATH || "/auth/login",
+    body,
+    fields: {
+      [env.API_AUTH_USERNAME_FIELD || "username"]: creds.username,
+      [env.API_AUTH_PASSWORD_FIELD || "password"]: creds.password
+    }
+  };
+}
+function extractToken(json, env = process.env) {
+  const paths = env.API_AUTH_TOKEN_PATH ? [env.API_AUTH_TOKEN_PATH] : DEFAULT_TOKEN_PATHS;
+  for (const p of paths) {
+    let value;
+    try {
+      value = selectPath(json, p);
+    } catch {
+      continue;
+    }
+    if (typeof value === "string" && value) return value;
+  }
+  return void 0;
+}
+function apiLoginErrorMessage({
+  role,
+  path,
+  status,
+  text,
+  noToken = false
+}) {
+  const keys = roleEnvKeys(role);
+  const body = text.length > 300 ? `${text.slice(0, 300)}\u2026` : text;
+  const head = noToken ? `API login as "${role}" failed: POST ${path} returned ${status} but no token found and no session cookie was set.` : `API login as "${role}" failed: POST ${path} returned ${status}.`;
+  const hint = noToken ? "Set API_AUTH_TOKEN_PATH to where the token is in the response (e.g. data.jwt)." : `Check ${keys.username} / ${keys.password}, API_AUTH_LOGIN_PATH, and API_AUTH_BODY (form|json) / API_AUTH_USERNAME_FIELD / API_AUTH_PASSWORD_FIELD.`;
+  return `${head}
+Response: ${body || "(empty)"}
+${hint}`;
+}
+
 // src/adapters/api/playwright-api.adapter.ts
 var PlaywrightApiAdapter = class {
   constructor(request) {
@@ -284,6 +390,64 @@ var PlaywrightUiAdapter = class {
       }
     }
   }
+  async fillField(name, value, options = {}) {
+    const candidates = [
+      this.page.getByLabel(name, { exact: true }),
+      this.page.getByPlaceholder(name, { exact: true }),
+      this.page.getByLabel(name),
+      this.page.getByPlaceholder(name),
+      this.page.locator(`[name="${name.replace(/"/g, '\\"')}"]`)
+    ];
+    const any = candidates.reduce((acc, loc) => acc.or(loc));
+    try {
+      await any.first().waitFor({ state: "visible", timeout: options.timeoutMs ?? 1e4 });
+    } catch {
+      return false;
+    }
+    for (const loc of candidates) {
+      if (await loc.count() > 0) {
+        await loc.first().fill(value);
+        return true;
+      }
+    }
+    return false;
+  }
+  async waitForUrl(predicate, timeoutMs) {
+    try {
+      await this.page.waitForURL((u) => predicate(u.toString()), { timeout: timeoutMs });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async waitForText(text, timeoutMs) {
+    try {
+      await this.page.getByText(text).first().waitFor({ state: "visible", timeout: timeoutMs });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async saveSession() {
+    return await this.page.context().storageState();
+  }
+  async restoreSession(state) {
+    const context = this.page.context();
+    if (state.cookies.length) await context.addCookies(state.cookies);
+    if (state.origins.some((o) => o.localStorage.length)) {
+      await context.addInitScript((origins) => {
+        try {
+          if (sessionStorage.getItem("__katalyst_xspec_session_restored")) return;
+          for (const o of origins) {
+            if (o.origin !== location.origin) continue;
+            for (const { name, value } of o.localStorage) localStorage.setItem(name, value);
+          }
+          sessionStorage.setItem("__katalyst_xspec_session_restored", "1");
+        } catch {
+        }
+      }, state.origins);
+    }
+  }
   async performClick(locator, clickMode) {
     if (clickMode === "dispatch click") {
       await locator.dispatchEvent("click");
@@ -356,72 +520,121 @@ var PlaywrightUiAdapter = class {
 };
 
 // src/adapters/auth/universal-auth.adapter.ts
+var uiSessions = /* @__PURE__ */ new Map();
+function clearUiSessions() {
+  uiSessions.clear();
+}
 var UniversalAuthAdapter = class {
-  constructor(deps) {
-    this.deps = deps;
+  constructor(options) {
+    this.api = options.api;
+    this.ui = options.ui;
+    this.roles = options.roles;
+    this.env = options.env ?? process.env;
+  }
+  /** Credentials for a role; throws MissingCredentialsError with the variables to set. */
+  credentialsFor(role) {
+    return resolveCredentials(role, { env: this.env, roles: this.roles });
   }
   apiSetBearer(world, token) {
     world.headers = { ...world.headers || {}, Authorization: `Bearer ${token}` };
   }
-  async apiLoginAsAdmin(world) {
-    const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
-    const password = process.env.DEFAULT_ADMIN_PASSWORD;
-    if (!username || !password) {
-      console.warn("apiLoginAsAdmin skipped: DEFAULT_ADMIN_USERNAME and DEFAULT_ADMIN_PASSWORD are not set");
-      return;
+  async apiLoginAs(world, role) {
+    await this.apiLogin(world, role, this.credentialsFor(role));
+  }
+  async uiLoginAs(world, role, options = {}) {
+    const creds = this.credentialsFor(role);
+    const reuse = options.reuseSession && this.sessionReuseEnabled();
+    const key = `${role.toLowerCase()}\0${creds.username}\0${this.env.UI_LOGIN_PATH || "/login"}`;
+    if (reuse && this.ui.restoreSession) {
+      const saved = uiSessions.get(key);
+      if (saved) {
+        await this.ui.restoreSession(saved);
+        return;
+      }
     }
-    await this.apiLogin(world, username, password);
+    await this.uiLogin(world, role, creds);
+    if (reuse && this.ui.saveSession) uiSessions.set(key, await this.ui.saveSession());
   }
-  async apiLoginAsUser(world) {
-    const username = process.env.DEFAULT_USER_USERNAME || process.env.NON_ADMIN_USERNAME;
-    const password = process.env.DEFAULT_USER_PASSWORD || process.env.NON_ADMIN_PASSWORD;
-    if (!username || !password) {
-      console.warn("apiLoginAsUser skipped: DEFAULT_USER_USERNAME and DEFAULT_USER_PASSWORD are not set");
-      return;
-    }
-    await this.apiLogin(world, username, password);
+  apiLoginAsAdmin(world) {
+    return this.apiLoginAs(world, "admin");
   }
-  async apiLogin(world, username, password) {
-    const loginPath = process.env.API_AUTH_LOGIN_PATH || "/auth/login";
-    const result = await this.deps.api.sendForm("POST", loginPath, { username, password });
+  apiLoginAsUser(world) {
+    return this.apiLoginAs(world, "user");
+  }
+  uiLoginAsAdmin(world) {
+    return this.uiLoginAs(world, "admin");
+  }
+  uiLoginAsUser(world) {
+    return this.uiLoginAs(world, "user");
+  }
+  /** POST credentials to the login endpoint; keep the bearer token or session cookie. */
+  async apiLogin(world, role, creds) {
+    const req = buildApiLoginRequest(creds, this.env);
+    const result = req.body === "json" ? await this.api.sendJson("POST", req.path, req.fields) : await this.api.sendForm("POST", req.path, req.fields);
     world.lastStatus = result.status;
     world.lastText = result.text;
     world.lastJson = result.json;
     world.lastHeaders = result.headers;
-    const json = result.json || {};
-    const token = json?.access_token;
-    if (typeof token !== "string" || !token) {
-      throw new Error(`API login failed for ${username}: ${result.status} ${result.text}`);
-    }
-    this.apiSetBearer(world, token);
-  }
-  async uiLoginAsAdmin(world) {
-    const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
-    const password = process.env.DEFAULT_ADMIN_PASSWORD;
-    if (!username || !password) {
-      console.warn("uiLoginAsAdmin skipped: DEFAULT_ADMIN_USERNAME and DEFAULT_ADMIN_PASSWORD are not set");
+    const ok = result.status >= 200 && result.status < 300;
+    if (!ok) throw new Error(apiLoginErrorMessage({ role, path: req.path, status: result.status, text: result.text }));
+    const token = extractToken(result.json, this.env);
+    if (token) {
+      this.apiSetBearer(world, token);
       return;
     }
-    await this.uiLogin(world, username, password);
+    const setsCookie = Object.keys(result.headers || {}).some((h) => h.toLowerCase() === "set-cookie");
+    if (!setsCookie) {
+      throw new Error(apiLoginErrorMessage({ role, path: req.path, status: result.status, text: result.text, noToken: true }));
+    }
   }
-  async uiLoginAsUser(world) {
-    const username = process.env.DEFAULT_USER_USERNAME || process.env.NON_ADMIN_USERNAME;
-    const password = process.env.DEFAULT_USER_PASSWORD || process.env.NON_ADMIN_PASSWORD;
-    if (!username || !password) {
-      console.warn("uiLoginAsUser skipped: DEFAULT_USER_USERNAME and DEFAULT_USER_PASSWORD are not set");
-      return;
+  /** Fill and submit the login form, then confirm the login worked. */
+  async uiLogin(_world, role, creds) {
+    const loginPath = this.env.UI_LOGIN_PATH || "/login";
+    const usernameField = this.env.UI_USERNAME_FIELD || "Username";
+    const passwordField = this.env.UI_PASSWORD_FIELD || "Password";
+    const button = this.env.UI_LOGIN_BUTTON || "Login";
+    const timeoutMs = Number(this.env.UI_LOGIN_TIMEOUT) || 1e4;
+    const keys = roleEnvKeys(role);
+    await this.ui.goto(loginPath);
+    const loginUrl = await this.ui.getCurrentUrl();
+    if (this.ui.fillField) {
+      for (const [kind, field, value, setting] of [
+        ["username", usernameField, creds.username, "UI_USERNAME_FIELD"],
+        ["password", passwordField, creds.password, "UI_PASSWORD_FIELD"]
+      ]) {
+        if (!await this.ui.fillField(field, value, { timeoutMs })) {
+          throw new Error(
+            `UI login as "${role}": No ${kind} field "${field}" on ${loginPath} (looked for a label, placeholder or name). Set ${setting} to the field's label or placeholder, or UI_LOGIN_PATH to the login page.`
+          );
+        }
+      }
+    } else {
+      await this.ui.fillPlaceholder(usernameField, creds.username);
+      await this.ui.fillPlaceholder(passwordField, creds.password);
+    }
+    await this.ui.clickButton(button);
+    const successUrl = this.env.UI_LOGIN_SUCCESS_URL;
+    const successText = this.env.UI_LOGIN_SUCCESS_TEXT;
+    let ok;
+    if (successText && this.ui.waitForText) {
+      ok = await this.ui.waitForText(successText, timeoutMs);
+    } else if (this.ui.waitForUrl) {
+      const loginPathname = new URL(loginUrl).pathname;
+      ok = await this.ui.waitForUrl(
+        (u) => successUrl ? u.includes(successUrl) : new URL(u).pathname !== loginPathname,
+        timeoutMs
+      );
+    }
+    if (ok === false) {
+      const expected = successText ? `for "${successText}" to appear` : successUrl ? `for a URL containing "${successUrl}"` : "to leave the login page";
+      throw new Error(
+        `UI login as "${role}" stayed on ${new URL(loginUrl).pathname} (waited ${timeoutMs}ms ${expected}). Check ${keys.username} / ${keys.password}. If your app doesn't navigate after login, set UI_LOGIN_SUCCESS_TEXT (text shown once logged in) or UI_LOGIN_SUCCESS_URL.`
+      );
     }
-    await this.uiLogin(world, username, password);
-  }
-  async uiLogin(_world, username, password) {
-    const loginPath = process.env.UI_LOGIN_PATH || "/login";
-    const usernameField = process.env.UI_USERNAME_FIELD || "Username";
-    const passwordField = process.env.UI_PASSWORD_FIELD || "Password";
-    const loginButton = process.env.UI_LOGIN_BUTTON || "Login";
-    await this.deps.ui.goto(loginPath);
-    await this.deps.ui.fillPlaceholder(usernameField, username);
-    await this.deps.ui.fillPlaceholder(passwordField, password);
-    await this.deps.ui.clickButton(loginButton);
+  }
+  sessionReuseEnabled() {
+    const v = this.env.UI_SESSION_REUSE?.trim().toLowerCase();
+    return v !== "false" && v !== "0";
   }
 };
 
@@ -497,32 +710,50 @@ async function defaultGetAdminHeaders(request) {
     cachedAdminToken = staticToken;
     return { Authorization: `Bearer ${staticToken}` };
   }
-  const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
-  const password = process.env.DEFAULT_ADMIN_PASSWORD;
+  const username = process.env.AUTH_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
+  const password = process.env.AUTH_ADMIN_PASSWORD || process.env.DEFAULT_ADMIN_PASSWORD;
   if (!username || !password) {
     return {};
   }
-  const loginPath = process.env.API_AUTH_LOGIN_PATH || "/auth/login";
-  const body = new URLSearchParams({ username, password }).toString();
-  const resp = await request.post(loginPath, {
-    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
-    data: body
+  const req = buildApiLoginRequest({ username, password });
+  const resp = await request.post(req.path, {
+    headers: { Accept: "application/json" },
+    ...req.body === "json" ? { data: req.fields } : { form: req.fields }
   });
   if (!resp.ok()) {
     console.warn(`cleanup auth failed: ${resp.status()} ${resp.statusText()}`);
     cachedAdminToken = void 0;
     return {};
   }
-  const json = await resp.json();
-  const token = json?.access_token;
-  if (typeof token === "string" && token) {
+  const json = await resp.json().catch(() => void 0);
+  const token = extractToken(json);
+  if (token) {
     cachedAdminToken = token;
     return { Authorization: `Bearer ${token}` };
   }
-  console.warn("cleanup auth: no access_token in response");
+  if (resp.headers()["set-cookie"]) return {};
+  console.warn("cleanup auth: no token in login response (set API_AUTH_TOKEN_PATH)");
   cachedAdminToken = void 0;
   return {};
 }
+function lazyUi(binding) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      const ui = binding.current;
+      if (!ui) {
+        if (prop === "then") return void 0;
+        throw new Error(
+          "UI login needs the browser: add `ui` to the step's fixtures, e.g. When('...', async ({ auth, ui, world }) => auth.uiLoginAs(world, 'admin'))."
+        );
+      }
+      const value = ui[prop];
+      return typeof value === "function" ? value.bind(ui) : value;
+    },
+    has(_target, prop) {
+      return binding.current ? prop in binding.current : false;
+    }
+  });
+}
 function createBddTest(options = {}) {
   const {
     createApi = ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
@@ -534,6 +765,11 @@ function createBddTest(options = {}) {
     worldFactory = initWorld
   } = options;
   const test = base.extend({
+    // Lets `auth` reach the UI adapter without depending on `page`, so API-only
+    // scenarios that log in never start a browser.
+    uiBinding: async ({}, use) => {
+      await use({});
+    },
     world: async ({ apiRequest }, use) => {
       const w = worldFactory();
       await use(w);
@@ -566,9 +802,10 @@ function createBddTest(options = {}) {
       }
     },
     apiRequest: async ({ playwright }, use, testInfo) => {
-      const projectName = String(testInfo.project.name || "");
-      const baseURLFromProject = testInfo.project.use?.baseURL;
-      const baseURL = process.env.API_BASE_URL || process.env.TARGET_BASE_URL || (projectName.includes("api") ? baseURLFromProject : void 0) || (process.env.TARGET_PORT ? `http://localhost:${process.env.TARGET_PORT}` : void 0) || "http://localhost:3000";
+      const baseURL = resolveApiBaseUrl({
+        projectName: String(testInfo.project.name || ""),
+        projectBaseURL: testInfo.project.use?.baseURL
+      });
       const ctx = await playwright.request.newContext(resolveApiRequestTarget(baseURL));
       try {
         await use(ctx);
@@ -582,11 +819,13 @@ function createBddTest(options = {}) {
     cleanup: async ({ apiRequest }, use) => {
       await use(createCleanup({ apiRequest }));
     },
-    ui: async ({ page }, use) => {
-      await use(createUi({ page }));
+    ui: async ({ page, uiBinding }, use) => {
+      const ui = createUi({ page });
+      uiBinding.current = ui;
+      await use(ui);
     },
-    auth: async ({ api, ui }, use) => {
-      await use(createAuth({ api, ui }));
+    auth: async ({ api, apiRequest, uiBinding }, use) => {
+      await use(createAuth({ api, apiRequest, ui: lazyUi(uiBinding) }));
     },
     /**
      * TUI fixture for terminal user interface testing.
@@ -1035,21 +1274,28 @@ function resolveBddPaths(options = {}) {
 }
 export {
   DefaultCleanupAdapter,
+  MissingCredentialsError,
   PlaywrightApiAdapter,
   PlaywrightUiAdapter,
   TuiTesterAdapter,
   UniversalAuthAdapter,
+  apiLoginAsRole,
   assertMasked,
   base as baseTest,
+  buildApiLoginRequest,
   clearFetchIntercept,
+  clearUiSessions,
   createBddTest,
   createOidcCleanupAuth,
   defaultBearerConfig,
   defaultBypassConfig,
+  extractToken,
+  formatTargets,
   getCpuCount,
   initWorld,
   interpolate,
   isFlagEnabled,
+  logTargets,
   parseExpected,
   registerAllSteps,
   registerApiAssertionSteps,
@@ -1074,17 +1320,23 @@ export {
   registerUiSteps,
   registerWizardSteps,
   resetOidcCleanupAuth,
+  resolveApiBaseUrl,
   resolveApiRequestTarget,
   resolveBddPaths,
+  resolveCredentials,
   resolveExtraTags,
   resolveFeatures,
   resolveSteps,
+  resolveTargets,
   resolveWorkers,
+  roleEnvKeys,
   selectPath,
   setFlag,
   setupBearerAuth,
   setupBypassAuth,
   setupFetchIntercept,
+  shouldLogTargets,
   tagsForProject,
-  tryParseJson
+  tryParseJson,
+  uiLoginAsRole
 };

package/dist/steps/index.js

@@ -22,7 +22,7 @@ import {
   registerUiSteps,
   registerWizardSteps,
   setFlag
-} from "../chunk-UTTKW2SR.js";
+} from "../chunk-VHVH476W.js";
 export {
   isFlagEnabled,
   registerAllSteps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esimplicitylabs/katalyst-xspec",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/katalyst-bdd-architecture/SKILL.md

@@ -304,52 +304,37 @@ class AxiosApiAdapter implements ApiPort {
 
 ### Custom Auth Adapter
 
+Usually not needed: the default `UniversalAuthAdapter` logs in by role using `AUTH_<ROLE>_*` credentials and `API_AUTH_*` / `UI_*` settings (see docs/guides/authentication.md). Constructor: `new UniversalAuthAdapter({ api, ui, roles?, env? })`, where `roles` is `{ pm: { username, password } }` and overrides env vars.
+
+When only the login request or page differs, **subclass** and override `apiLogin` / `uiLogin`. Credentials, the role steps, and UI session reuse keep working:
+
 ```typescript
-import { AuthPort, World, ApiPort, UiPort } from '@esimplicitylabs/katalyst-xspec';
+import { UniversalAuthAdapter, type Credentials, type World } from '@esimplicitylabs/katalyst-xspec';
 
-class CustomAuthAdapter implements AuthPort {
-  constructor(private deps: { api: ApiPort; ui: UiPort }) {}
-  
-  async apiLoginAsAdmin(world: World): Promise<void> {
-    const result = await this.deps.api.sendJson('POST', '/auth/admin', {
-      apiKey: process.env.ADMIN_API_KEY,
-    });
-    
-    if (result.json?.token) {
-      world.headers['Authorization'] = `Bearer ${result.json.token}`;
-    }
-  }
-  
-  async apiLoginAsUser(world: World): Promise<void> {
-    const result = await this.deps.api.sendJson('POST', '/auth/login', {
-      email: process.env.DEFAULT_USER_USERNAME,
-      password: process.env.DEFAULT_USER_PASSWORD,
+class CustomAuthAdapter extends UniversalAuthAdapter {
+  protected async apiLogin(world: World, role: string, creds: Credentials): Promise<void> {
+    const result = await this.api.sendJson('POST', '/auth/login', {
+      email: creds.username,
+      password: creds.password,
     });
-    
-    if (result.json?.token) {
-      world.headers['Authorization'] = `Bearer ${result.json.token}`;
-    }
+    if (result.status !== 200) throw new Error(`login as ${role} failed: ${result.status}`);
+    this.apiSetBearer(world, (result.json as any).token);
   }
-  
-  async uiLoginAsAdmin(world: World): Promise<void> {
-    await this.deps.ui.goto('/admin/login');
-    await this.deps.ui.fillLabel('Admin Key', process.env.ADMIN_KEY!);
-    await this.deps.ui.clickButton('Login');
-  }
-  
-  async uiLoginAsUser(world: World): Promise<void> {
-    await this.deps.ui.goto('/login');
-    await this.deps.ui.fillLabel('Email', process.env.DEFAULT_USER_USERNAME!);
-    await this.deps.ui.fillLabel('Password', process.env.DEFAULT_USER_PASSWORD!);
-    await this.deps.ui.clickButton('Sign In');
-  }
-  
-  apiSetBearer(world: World, token: string): void {
-    world.headers['Authorization'] = `Bearer ${token}`;
+
+  protected async uiLogin(world: World, role: string, creds: Credentials): Promise<void> {
+    await this.ui.goto('/login');
+    await this.ui.fillLabel('Email', creds.username);
+    await this.ui.fillLabel('Password', creds.password);
+    await this.ui.clickButton('Sign In');
+    await this.ui.expectUrlContains('/dashboard');
   }
 }
 ```
 
+Writing an `AuthPort` from scratch: implement `apiLoginAsAdmin`, `apiLoginAsUser`, `uiLoginAsAdmin`, `uiLoginAsUser`, `apiSetBearer`, plus the optional `apiLoginAs(world, role)` and `uiLoginAs(world, role, { reuseSession })` so the role steps work for any role.
+
+The `ui` passed to `createAuth` only works after a step requests the `ui` fixture (API login never starts a browser). Custom steps calling `auth.uiLoginAs` must include `ui`: `async ({ auth, ui, world }) => ...`.
+
 ### Using Custom Adapters
 
 ```typescript