rhachet-roles-bhrowser 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Uladzimir Kasacheuski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/contract/sdk/index.d.ts

@@ -0,0 +1,3 @@
+export { getRoleRegistry } from '../../domain.roles/getRoleRegistry';
+export { ROLE_INSPECTOR } from '../../domain.roles/inspector/getInspectorRole';
+export { ROLE_PLAYWRIGHT } from '../../domain.roles/playwright/getPlaywrightRole';

package/dist/contract/sdk/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_PLAYWRIGHT = exports.ROLE_INSPECTOR = exports.getRoleRegistry = void 0;
+var getRoleRegistry_1 = require("../../domain.roles/getRoleRegistry");
+Object.defineProperty(exports, "getRoleRegistry", { enumerable: true, get: function () { return getRoleRegistry_1.getRoleRegistry; } });
+var getInspectorRole_1 = require("../../domain.roles/inspector/getInspectorRole");
+Object.defineProperty(exports, "ROLE_INSPECTOR", { enumerable: true, get: function () { return getInspectorRole_1.ROLE_INSPECTOR; } });
+var getPlaywrightRole_1 = require("../../domain.roles/playwright/getPlaywrightRole");
+Object.defineProperty(exports, "ROLE_PLAYWRIGHT", { enumerable: true, get: function () { return getPlaywrightRole_1.ROLE_PLAYWRIGHT; } });
+//# sourceMappingURL=index.js.map

package/dist/contract/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/sdk/index.ts"],"names":[],"mappings":";;;AAAA,sEAAqE;AAA5D,kHAAA,eAAe,OAAA;AACxB,kFAA+E;AAAtE,kHAAA,cAAc,OAAA;AACvB,qFAAkF;AAAzE,oHAAA,eAAe,OAAA"}

package/dist/domain.roles/getRoleRegistry.d.ts

@@ -0,0 +1,6 @@
+import { RoleRegistry } from 'rhachet';
+/**
+ * .what = returns the bhrowser registry of predefined roles
+ * .why = enables rhachet to discover and enroll bhrowser roles
+ */
+export declare const getRoleRegistry: () => RoleRegistry;

package/dist/domain.roles/getRoleRegistry.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRoleRegistry = void 0;
+const rhachet_1 = require("rhachet");
+const getInspectorRole_1 = require("./inspector/getInspectorRole");
+const getPlaywrightRole_1 = require("./playwright/getPlaywrightRole");
+/**
+ * .what = returns the bhrowser registry of predefined roles
+ * .why = enables rhachet to discover and enroll bhrowser roles
+ */
+const getRoleRegistry = () => rhachet_1.RoleRegistry.build({
+    slug: 'bhrowser',
+    readme: { uri: `${__dirname}/readme.md` },
+    roles: [getPlaywrightRole_1.ROLE_PLAYWRIGHT, getInspectorRole_1.ROLE_INSPECTOR],
+});
+exports.getRoleRegistry = getRoleRegistry;
+//# sourceMappingURL=getRoleRegistry.js.map

package/dist/domain.roles/getRoleRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRoleRegistry.js","sourceRoot":"","sources":["../../src/domain.roles/getRoleRegistry.ts"],"names":[],"mappings":";;;AAAA,qCAAuC;AAEvC,mEAA8D;AAC9D,sEAAiE;AAEjE;;;GAGG;AACI,MAAM,eAAe,GAAG,GAAiB,EAAE,CAChD,sBAAY,CAAC,KAAK,CAAC;IACjB,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,YAAY,EAAE;IACzC,KAAK,EAAE,CAAC,mCAAe,EAAE,iCAAc,CAAC;CACzC,CAAC,CAAC;AALQ,QAAA,eAAe,mBAKvB"}

package/dist/domain.roles/inspector/boot.yml

@@ -0,0 +1,4 @@
+always:
+  briefs:
+    say: []
+    ref: []

package/dist/domain.roles/inspector/getInspectorRole.d.ts

@@ -0,0 +1,6 @@
+import { Role } from 'rhachet';
+/**
+ * .what = returns the inspector role definition
+ * .why = enables rhachet to enroll brains with inspector capabilities
+ */
+export declare const ROLE_INSPECTOR: Role;

package/dist/domain.roles/inspector/getInspectorRole.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_INSPECTOR = void 0;
+const rhachet_1 = require("rhachet");
+/**
+ * .what = returns the inspector role definition
+ * .why = enables rhachet to enroll brains with inspector capabilities
+ */
+exports.ROLE_INSPECTOR = rhachet_1.Role.build({
+    slug: 'inspector',
+    name: 'Inspector',
+    purpose: 'inspect browser renders for performance, precision, and aesthetics',
+    traits: [],
+    readme: { uri: `${__dirname}/readme.md` },
+    boot: { uri: `${__dirname}/boot.yml` },
+    briefs: {
+        dirs: [{ uri: `${__dirname}/briefs` }],
+    },
+    skills: {
+        dirs: [{ uri: `${__dirname}/skills` }],
+        refs: [],
+    },
+    hooks: {
+        onBrain: {
+            onBoot: [
+                {
+                    command: './node_modules/.bin/rhachet roles boot --repo bhrowser --role inspector',
+                    timeout: 'PT60S',
+                },
+            ],
+        },
+    },
+});
+//# sourceMappingURL=getInspectorRole.js.map

package/dist/domain.roles/inspector/getInspectorRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInspectorRole.js","sourceRoot":"","sources":["../../../src/domain.roles/inspector/getInspectorRole.ts"],"names":[],"mappings":";;;AAAA,qCAA+B;AAE/B;;;GAGG;AACU,QAAA,cAAc,GAAS,cAAI,CAAC,KAAK,CAAC;IAC7C,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,oEAAoE;IAC7E,MAAM,EAAE,EAAE;IACV,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,YAAY,EAAE;IACzC,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,WAAW,EAAE;IACtC,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,SAAS,EAAE,CAAC;KACvC;IACD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,SAAS,EAAE,CAAC;QACtC,IAAI,EAAE,EAAE;KACT;IACD,KAAK,EAAE;QACL,OAAO,EAAE;YACP,MAAM,EAAE;gBACN;oBACE,OAAO,EACL,yEAAyE;oBAC3E,OAAO,EAAE,OAAO;iBACjB;aACF;SACF;KACF;CACF,CAAC,CAAC"}

package/dist/domain.roles/inspector/readme.md

@@ -0,0 +1,7 @@
+## 📐 inspector
+
+- **scale**: visual-level, design assessment
+- **focus**: inspect performance, precision, and aesthetics — screenshots, diffs, regressions
+- **maximizes**: visual accuracy and design coherence
+
+used to assess browser renders, spot visual regressions, and ensure design consistency.

package/dist/domain.roles/playwright/boot.yml

@@ -0,0 +1,37 @@
+always:
+  briefs:
+    say:
+      # core rules - loaded in full
+      - briefs/diagnosis/rule.require.snapshot-before-assume.md
+      - briefs/diagnosis/rule.require.snapshot-before-debug.md
+      - briefs/verification/rule.require.action-verification.md
+      - briefs/spa/rule.require.wait-for-target-element.md
+    ref:
+      # diagnosis
+      - briefs/diagnosis/howto.browser-diagnosis.md
+      - briefs/diagnosis/rule.require.snapshot-latest-tab.md
+      - briefs/diagnosis/rule.require.grep-html-before-selector-guess.md
+      # verification
+      - briefs/verification/rule.forbid.unverified-actions.md
+      # spa
+      - briefs/spa/rule.require.spa-navigation-fail-fast.md
+      - briefs/spa/rule.require.wait-for-content-not-shell.md
+      - briefs/spa/rule.require.wait-for-react-render.md
+      # auth
+      - briefs/auth/howto.cross-session-auth.md
+      # stealth
+      - briefs/stealth/ref.antibot-escalation.md
+      # reliability
+      - briefs/reliability/ref.cdp-reconnection-patterns.md
+      - briefs/reliability/rule.require.bounded-timeouts-and-bisection.md
+      # debug
+      - briefs/debug/howto.debug-movie-frames.md
+      - briefs/debug/howto.capture-state-on-error.md
+      # skills
+      - briefs/skills/howto.browser-action-playbooks.md
+      - briefs/skills/howto.browser-byhand-work.md
+      # test
+      - briefs/test/howto.test-via-browser.md
+      - briefs/test/rule.forbid.test-goto.md
+      - briefs/test/rule.forbid.afterall-state-mutation.md
+      - briefs/test/rule.require.fast-tests.md

package/dist/domain.roles/playwright/briefs/auth/howto.cross-session-auth.md

@@ -0,0 +1,134 @@
+# howto.cross-session-auth
+
+## .what
+
+persist authentication across browser sessions via playwright's `storageState`.
+
+## .why
+
+- human solves captcha once, robot reuses auth indefinitely
+- login flows run once per credential lifetime
+- headful ↔ headless handoff without re-authentication
+
+## .pattern
+
+### save session after authentication
+
+```typescript
+// after login completes
+const storageState = await context.storageState();
+await fs.writeFile('./auth-state.json', JSON.stringify(storageState, null, 2));
+```
+
+### restore session in new browser
+
+```typescript
+// new browser instance, same auth
+const context = await browser.newContext({
+  storageState: './auth-state.json',
+});
+// all cookies, localStorage, sessionStorage restored
+```
+
+## .storage state contents
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123...",
+      "domain": ".example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "authToken", "value": "xyz789..." }
+      ]
+    }
+  ]
+}
+```
+
+## .workflow: captcha handoff
+
+```bash
+# 1. human session (headful)
+browser.start --session human --mode HEADFUL
+# human navigates to login, solves captcha, authenticates
+
+# 2. export auth state
+browser.session get --session human --into ./auth-state.json
+
+# 3. stop human session
+browser.stop --session human
+
+# 4. robot session (headless)
+browser.start --session robot --mode HEADLESS
+browser.session set --session robot --from ./auth-state.json
+
+# 5. robot works with human's auth
+browser.action --session robot --play ./scrape-data.play.ts
+```
+
+## .credential lifetime
+
+| credential type | typical lifetime | refresh strategy |
+|-----------------|------------------|------------------|
+| session cookie | hours to days | re-login on expiry |
+| jwt token | 15 min to 1 hour | refresh token flow |
+| oauth token | varies | refresh endpoint |
+| remember-me | weeks to months | periodic re-auth |
+
+## .best practices
+
+### secure storage
+
+```bash
+# encrypt at rest
+gpg -c ./auth-state.json
+
+# restrict permissions
+chmod 600 ./auth-state.json
+```
+
+### session isolation
+
+```bash
+# different sessions for different accounts
+browser.session set --session account-a --from ./auth-a.json
+browser.session set --session account-b --from ./auth-b.json
+```
+
+### expiry detection
+
+```typescript
+import { BadRequestError } from 'helpful-errors';
+
+// in playbook, detect session expiry
+export const action = async (input: { page: Page }) => {
+  await input.page.goto('https://example.com/dashboard');
+
+  // check if redirected to login
+  if (input.page.url().includes('/login')) {
+    throw new BadRequestError('session expired', {
+      url: input.page.url(),
+      hint: 're-authenticate via browser.session set --from @storage',
+    });
+  }
+
+  // continue with authenticated work
+};
+```
+
+## .see also
+
+- `stealth/ref.antibot-escalation.md` — when auth alone fails
+- `browser.session.sh` — session management skill

package/dist/domain.roles/playwright/briefs/debug/howto.capture-state-on-error.md

@@ -0,0 +1,253 @@
+# howto.capture-state-on-error
+
+## .what
+
+automatically capture browser state when errors occur.
+
+## .why
+
+errors are transient:
+- page state changes after error
+- console messages scroll away
+- network requests complete
+- element disappears
+
+capture immediately preserves evidence.
+
+## .pattern
+
+```typescript
+import { HelpfulError } from 'helpful-errors';
+
+/**
+ * .what = get current timestamp in milliseconds
+ * .why = isolates Date.now() call from orchestrator
+ */
+const asTimestamp = (): number => Date.now();
+
+/**
+ * .what = get current time as ISO string
+ * .why = isolates Date conversion from orchestrator
+ */
+const asIsoTimestamp = (): string => new Date().toJSON();
+
+/**
+ * .what = get capture directory path with fallback to timestamp
+ * .why = isolates nullable coalesce + path construction
+ */
+const asCaptureDir = (input: { captureId: string | null }): string =>
+  `.cache/errors/${input.captureId ?? String(asTimestamp())}`;
+
+/**
+ * .what = wrap browser action with automatic error state capture
+ * .why = preserves evidence when errors occur for post-mortem analysis
+ */
+export const action = async (
+  input: Record<string, never>,
+  context: { page: Page; browser: Browser },
+) => {
+  return HelpfulError.wrap(
+    async () => {
+      await riskyOperation(context.page);
+      return { success: true };
+    },
+    {
+      message: 'browser action failed',
+      metadata: { url: context.page.url() },
+      onError: async (error) => {
+        // capture state before it changes
+        await setErrorSnapshot({ error, captureId: null }, { page: context.page });
+      },
+    },
+  )();
+};
+
+/**
+ * .what = persist browser state snapshot when error occurs
+ * .why = preserves screenshot, html, and error details for diagnosis
+ */
+const setErrorSnapshot = async (
+  // captureId nullable: caller may not have identifier; defaults to timestamp
+  input: { error: Error; captureId: string | null },
+  context: { page: Page },
+) => {
+  // derive artifact path via named transformer
+  const dirError = asCaptureDir({ captureId: input.captureId });
+  await fs.mkdir(dirError, { recursive: true });
+
+  // screenshot
+  await context.page.screenshot({
+    path: `${dirError}/screenshot.png`,
+    fullPage: true,
+  });
+
+  // html
+  await fs.writeFile(`${dirError}/page.html`, await context.page.content());
+
+  // console logs (captured earlier via event handler - not available in error handler)
+  // .note = console messages should be captured proactively, not in error handler
+
+  // error details
+  await fs.writeFile(`${dirError}/error.json`, JSON.stringify({
+    message: input.error.message,
+    stack: input.error.stack,
+    url: context.page.url(),
+    title: await context.page.title(),
+    time: asIsoTimestamp(),
+  }, null, 2));
+};
+```
+
+## .wrapper pattern
+
+```typescript
+import { HelpfulError } from 'helpful-errors';
+
+/**
+ * .what = higher-order function that wraps playbooks with error snapshot
+ * .why = enables consistent error state capture across all playbooks
+ */
+const withErrorSnapshot = <I, R>(
+  action: (input: I, context: { page: Page }) => Promise<R>
+) => {
+  return async (input: I, context: { page: Page }): Promise<R> => {
+    return HelpfulError.wrap(
+      async () => action(input, context),
+      {
+        message: 'browser action failed',
+        metadata: { url: context.page.url() },
+        onError: async (error) => {
+          // capture state before re-throw
+          await setErrorSnapshot({ error, captureId: null }, { page: context.page });
+        },
+      },
+    )();
+  };
+};
+
+// usage: define _action then wrap
+/**
+ * .what = submit form and wait for success
+ * .why = demonstrates error capture wrapper pattern
+ */
+const _action = async (
+  input: Record<string, never>,
+  context: { page: Page },
+) => {
+  await context.page.click('#submit');
+  await context.page.waitForURL('**/success');
+  return { success: true };
+};
+
+export const action = withErrorSnapshot(_action);
+```
+
+## .captured artifacts
+
+| artifact | content | use |
+|----------|---------|-----|
+| screenshot.png | visual state | see what user would see |
+| page.html | dom snapshot | search for elements |
+| console.log | browser console | errors, warnings |
+| network.json | request/response | endpoint failures |
+| storage.json | cookies, localStorage | auth state |
+| error.json | error details | stack trace, context |
+
+## .network capture
+
+```typescript
+interface NetworkEntry {
+  url: string;
+  method?: string;
+  status?: number;
+  headers: Record<string, string>;
+  time: string;
+}
+
+/**
+ * .what = create network entry from playwright request
+ * .why = pure transformer for request data extraction
+ */
+const asNetworkEntryFromRequest = (input: { req: Request }): NetworkEntry => ({
+  url: input.req.url(),
+  method: input.req.method(),
+  headers: input.req.headers(),
+  time: asIsoTimestamp(),
+});
+
+/**
+ * .what = create network entry from playwright response
+ * .why = pure transformer for response data extraction
+ */
+const asNetworkEntryFromResponse = (input: { res: Response }): NetworkEntry => ({
+  url: input.res.url(),
+  status: input.res.status(),
+  headers: input.res.headers(),
+  time: asIsoTimestamp(),
+});
+
+/**
+ * .what = append entry to accumulator array
+ * .why = named transformer makes append intent clear without decode
+ */
+const appendToAccumulator = <T>(accumulator: T[], entry: T): void => {
+  accumulator.push(entry);
+};
+
+/**
+ * .what = set up network snapshot capture and return flush function
+ * .why = enables capture of request/response data for error diagnosis
+ */
+const setNetworkSnapshotCapture = (input: { page: Page; dir: string }) => {
+  // accumulator for network entries - playwright events append via callback
+  const entriesAccumulator: NetworkEntry[] = [];
+
+  // capture request data when fired
+  input.page.on('request', (req) => {
+    const entry = asNetworkEntryFromRequest({ req });
+    appendToAccumulator(entriesAccumulator, entry);
+  });
+
+  // capture response data when fired
+  input.page.on('response', (res) => {
+    const entry = asNetworkEntryFromResponse({ res });
+    appendToAccumulator(entriesAccumulator, entry);
+  });
+
+  // return flush function to persist captured data
+  return async () => {
+    // snapshot entries at flush time (immutable copy)
+    const entriesSnapshot = [...entriesAccumulator];
+    await fs.writeFile(`${input.dir}/network.json`, JSON.stringify(entriesSnapshot, null, 2));
+  };
+};
+```
+
+## .test integration
+
+```typescript
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+// in test setup - capture state on failure for diagnosis
+afterEach(async () => {
+  if (testInfo.status !== 'passed') {
+    // .note = capture state for post-mortem; original error already propagated via testInfo
+    await setErrorSnapshot(
+      {
+        error: new UnexpectedCodePathError('test failed', {
+          testTitle: testInfo.title,
+          testFile: testInfo.file,
+          originalError: testInfo.error?.message,
+        }),
+        captureId: null,
+      },
+      { page },
+    );
+  }
+});
+```
+
+## .see also
+
+- `howto.debug-movie-frames.md` — sequential capture
+- `howto.browser-diagnosis.md` — diagnosis workflow