@monoes/monobrowse 1.0.11 → 1.0.13

package/src/cli/output.ts

@@ -17,20 +17,20 @@ class OutputFormatter {
   }
 
   printSuccess(message: string): void {
-    console.log(this.c('green', '✓') + ' ' + message);
+    console.log(`${this.c('green', '✓')} ${message}`);
   }
 
   printError(message: string, details?: string): void {
-    console.error(this.c('red', '✗') + ' ' + message);
-    if (details) console.error(this.c('red', '  ' + details));
+    console.error(`${this.c('red', '✗')} ${message}`);
+    if (details) console.error(this.c('red', `  ${details}`));
   }
 
   printWarning(message: string): void {
-    console.warn(this.c('yellow', '⚠') + ' ' + message);
+    console.warn(`${this.c('yellow', '⚠')} ${message}`);
   }
 
   printInfo(message: string): void {
-    console.log(this.c('cyan', 'ℹ') + ' ' + message);
+    console.log(`${this.c('cyan', 'ℹ')} ${message}`);
   }
 }
 

package/src/cli/platform.ts

@@ -3,22 +3,22 @@
  * Sessions stored as JSON at ~/.monomind/sessions.json
  */
 
-import { Command } from 'commander';
-import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
 import { getAdapter } from '../index.js';
 
-const CDP_PORT = Number(process.env['MONOMIND_CDP_PORT'] ?? 9222);
+const CDP_PORT = Number(process.env.MONOMIND_CDP_PORT ?? 9222);
 
 const SESSIONS_FILE = join(homedir(), '.monomind', 'sessions.json');
 
 interface Session {
-  id: string;          // "platform:username"
+  id: string; // "platform:username"
   platform: string;
   username: string;
-  cookies: string;     // JSON-serialized
+  cookies: string; // JSON-serialized
   userAgent: string;
   createdAt: number;
   lastUsedAt: number;
@@ -46,7 +46,9 @@ export function createPlatformCommand(): Command {
 
   cmd
     .command('connect <platform>')
-    .description('Connect a platform account via browser — opens Chrome, waits for login, saves session')
+    .description(
+      'Connect a platform account via browser — opens Chrome, waits for login, saves session',
+    )
     .option('--port <number>', 'CDP port of running Chrome instance', String(CDP_PORT))
     .option('--timeout <seconds>', 'Login timeout in seconds', '300')
     .action(async (platform: string, opts: { port: string; timeout: string }) => {
@@ -57,7 +59,9 @@ export function createPlatformCommand(): Command {
       }
 
       let adapter: ReturnType<typeof getAdapter>;
-      try { adapter = getAdapter(platform); } catch (err) {
+      try {
+        adapter = getAdapter(platform);
+      } catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
       }
@@ -67,7 +71,9 @@ export function createPlatformCommand(): Command {
 
       // Lazy-load browser module
       let browser: typeof import('@monoes/monobrowse');
-      try { browser = await import('@monoes/monobrowse'); } catch (err) {
+      try {
+        browser = await import('@monoes/monobrowse');
+      } catch (err) {
         console.error('Browser module unavailable:', err);
         process.exit(1);
       }
@@ -91,16 +97,18 @@ export function createPlatformCommand(): Command {
       const { client, sessionId: sid } = conn;
 
       try {
-        const refs = new Map();
+        const _refs = new Map();
 
         // Restore any existing cookies first so the user might already be logged in
         const sessions = await loadSessions();
-        const existingSession = sessions.find(s => s.platform === platform);
+        const existingSession = sessions.find((s) => s.platform === platform);
         if (existingSession?.cookies) {
           try {
             const cookies = JSON.parse(existingSession.cookies);
             if (cookies.length > 0) await browser.setCookies(client, sid, cookies);
-          } catch { /* ignore */ }
+          } catch {
+            /* ignore */
+          }
         }
 
         // Navigate to login URL
@@ -120,25 +128,31 @@ export function createPlatformCommand(): Command {
           console.log(`│  Please sign in to ${platform.padEnd(34)}│`);
           console.log('│                                                      │');
           console.log('│  Complete the login in the browser window.           │');
-          console.log(`│  Waiting up to ${Math.round(timeoutMs / 60000)} minutes for login…           │`);
+          console.log(
+            `│  Waiting up to ${Math.round(timeoutMs / 60000)} minutes for login…           │`,
+          );
           console.log('└──────────────────────────────────────────────────────┘');
           console.log('');
 
           const deadline = Date.now() + timeoutMs;
           while (Date.now() < deadline) {
-            await new Promise(r => setTimeout(r, 2000));
+            await new Promise((r) => setTimeout(r, 2000));
             isLoggedIn = await adapter.isLoggedIn(pageIface).catch(() => false);
             if (isLoggedIn) break;
             // Navigate to app URL if user manually browsed away from login
             const currentUrl = await browser.getCurrentUrl(client, sid).catch(() => '');
-            if (!currentUrl.includes(new URL(adapter.loginURL()).hostname) &&
-                !currentUrl.includes(new URL(adapter.baseURL).hostname)) {
+            if (
+              !currentUrl.includes(new URL(adapter.loginURL()).hostname) &&
+              !currentUrl.includes(new URL(adapter.baseURL).hostname)
+            ) {
               await browser.openUrl(client, sid, adapter.loginURL());
             }
           }
 
           if (!isLoggedIn) {
-            console.error(`\nLogin timeout after ${Math.round(timeoutMs / 1000)}s. Session not saved.`);
+            console.error(
+              `\nLogin timeout after ${Math.round(timeoutMs / 1000)}s. Session not saved.`,
+            );
             process.exit(1);
           }
         }
@@ -147,7 +161,9 @@ export function createPlatformCommand(): Command {
 
         // Capture cookies and user agent
         const liveCookies = await browser.getCookies(client, sid).catch(() => []);
-        const userAgent = await browser.evaluateJs(client, sid, 'navigator.userAgent').catch(() => 'unknown') as string;
+        const userAgent = (await browser
+          .evaluateJs(client, sid, 'navigator.userAgent')
+          .catch(() => 'unknown')) as string;
         const username = await adapter.extractUsername(pageIface).catch(() => `${platform}-user`);
 
         // Save to sessions file
@@ -160,8 +176,9 @@ export function createPlatformCommand(): Command {
           createdAt: existingSession?.createdAt ?? Date.now(),
           lastUsedAt: Date.now(),
         };
-        const idx = sessions.findIndex(s => s.platform === platform);
-        if (idx >= 0) sessions[idx] = sessionEntry; else sessions.push(sessionEntry);
+        const idx = sessions.findIndex((s) => s.platform === platform);
+        if (idx >= 0) sessions[idx] = sessionEntry;
+        else sessions.push(sessionEntry);
         await saveSessions(sessions);
 
         console.log(`\n✓ Session saved: ${sessionEntry.id}`);
@@ -183,11 +200,15 @@ export function createPlatformCommand(): Command {
         console.log('No connected accounts. Run: browse platform connect <platform>');
         return;
       }
-      console.log(`\n${'ID'.padEnd(40)} ${'PLATFORM'.padEnd(12)} ${'USERNAME'.padEnd(30)} LAST USED`);
+      console.log(
+        `\n${'ID'.padEnd(40)} ${'PLATFORM'.padEnd(12)} ${'USERNAME'.padEnd(30)} LAST USED`,
+      );
       console.log('─'.repeat(95));
       for (const s of sessions) {
         const lastUsed = new Date(s.lastUsedAt).toLocaleString();
-        console.log(`${s.id.padEnd(40)} ${s.platform.padEnd(12)} ${s.username.padEnd(30)} ${lastUsed}`);
+        console.log(
+          `${s.id.padEnd(40)} ${s.platform.padEnd(12)} ${s.username.padEnd(30)} ${lastUsed}`,
+        );
       }
     });
 
@@ -196,7 +217,7 @@ export function createPlatformCommand(): Command {
     .description('Remove a saved platform session')
     .action(async (id: string) => {
       const sessions = await loadSessions();
-      const idx = sessions.findIndex(s => s.id === id);
+      const idx = sessions.findIndex((s) => s.id === id);
       if (idx < 0) {
         console.error(`Session not found: ${id}`);
         console.log('Run "browse platform list" to see available sessions.');

package/src/cli/types.ts

@@ -37,7 +37,7 @@ export interface CommandExample {
   description: string;
 }
 
-export type CommandAction = (ctx: CommandContext) => Promise<CommandResult | void>;
+export type CommandAction = (ctx: CommandContext) => Promise<CommandResult | undefined>;
 
 export interface CommandResult {
   success: boolean;

package/src/cli.ts

@@ -4,10 +4,10 @@
  * Dispatches to the same command tree used by `monomind browse`
  */
 
-import { createRequire } from 'module';
+import { createRequire } from 'node:module';
 import browseCommand from './cli/commands.js';
 import { output } from './cli/output.js';
-import type { Command, CommandContext, CommandOption, ParsedFlags } from './cli/types.js';
+import type { Command, CommandContext, ParsedFlags } from './cli/types.js';
 
 const _require = createRequire(import.meta.url);
 
@@ -16,7 +16,7 @@ const _require = createRequire(import.meta.url);
 // ---------------------------------------------------------------------------
 
 function findSub(name: string, subs: Command[]): Command | undefined {
-  return subs.find(s => s.name === name || s.aliases?.includes(name));
+  return subs.find((s) => s.name === name || s.aliases?.includes(name));
 }
 
 // ---------------------------------------------------------------------------
@@ -33,11 +33,14 @@ function buildShortMap(cmd: Command | undefined): Record<string, string> {
 }
 
 function isBooleanOpt(name: string, cmd: Command | undefined): boolean {
-  const opt = cmd?.options?.find(o => o.name === name);
+  const opt = cmd?.options?.find((o) => o.name === name);
   return opt?.type === 'boolean';
 }
 
-function parseArgv(argv: string[], sub: Command | undefined): { args: string[]; flags: ParsedFlags } {
+function parseArgv(
+  argv: string[],
+  sub: Command | undefined,
+): { args: string[]; flags: ParsedFlags } {
   const shortMap = buildShortMap(sub);
   const flags: ParsedFlags = { _: [] };
   const positional: string[] = [];
@@ -81,7 +84,7 @@ function parseArgv(argv: string[], sub: Command | undefined): { args: string[];
   }
 
   // Coerce number options
-  for (const opt of (sub?.options ?? [])) {
+  for (const opt of sub?.options ?? []) {
     if (opt.type === 'number' && typeof flags[opt.name] === 'string') {
       flags[opt.name] = Number(flags[opt.name]);
     }
@@ -95,11 +98,12 @@ function parseArgv(argv: string[], sub: Command | undefined): { args: string[];
 // ---------------------------------------------------------------------------
 
 function printHelp(cmd: Command, prefix = 'monobrowse'): void {
-  const usage = cmd.name === 'browse'
-    ? `${prefix} <subcommand> [options]`
-    : `${prefix} ${cmd.name} [subcommand] [options]`;
+  const usage =
+    cmd.name === 'browse'
+      ? `${prefix} <subcommand> [options]`
+      : `${prefix} ${cmd.name} [subcommand] [options]`;
   console.log(`\nUsage: ${usage}\n`);
-  console.log(cmd.description + '\n');
+  console.log(`${cmd.description}\n`);
 
   if (cmd.subcommands?.length) {
     console.log('Subcommands:');
@@ -160,7 +164,12 @@ async function dispatch(cmd: Command, argv: string[]): Promise<void> {
     const nested = findSub(rest[0], sub.subcommands);
     if (nested?.action) {
       const { args, flags } = parseArgv(rest.slice(1), nested);
-      const ctx: CommandContext = { args, flags, cwd: process.cwd(), interactive: !!process.stdout.isTTY };
+      const ctx: CommandContext = {
+        args,
+        flags,
+        cwd: process.cwd(),
+        interactive: !!process.stdout.isTTY,
+      };
       const result = await nested.action(ctx);
       if (result && !result.success) process.exitCode = result.exitCode ?? 1;
       return;
@@ -174,7 +183,12 @@ async function dispatch(cmd: Command, argv: string[]): Promise<void> {
   }
 
   const { args, flags } = parseArgv(rest, sub);
-  const ctx: CommandContext = { args, flags, cwd: process.cwd(), interactive: !!process.stdout.isTTY };
+  const ctx: CommandContext = {
+    args,
+    flags,
+    cwd: process.cwd(),
+    interactive: !!process.stdout.isTTY,
+  };
   const result = await sub.action(ctx);
   if (result && !result.success) process.exitCode = result.exitCode ?? 1;
 }
@@ -200,9 +214,11 @@ async function main(): Promise<void> {
   await dispatch(browseCommand, userArgs);
 }
 
-main().then(() => {
-  process.exit(process.exitCode ?? 0);
-}).catch(err => {
-  output.printError(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-});
+main()
+  .then(() => {
+    process.exit(process.exitCode ?? 0);
+  })
+  .catch((err) => {
+    output.printError(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });

package/src/index.ts

@@ -1,5 +1,5 @@
-export * from './browser/index.js';
 export * from './browser/action-builder/analyzer.js';
 export * from './browser/action-builder/types.js';
 export * from './browser/adapters/index.js';
-export { startDashboard, getDashboard } from './browser/dashboard/server.js';
+export { getDashboard, startDashboard } from './browser/dashboard/server.js';
+export * from './browser/index.js';

package/src/report/a11y.ts

@@ -0,0 +1,242 @@
+/**
+ * Accessibility rules computed from the CDP accessibility tree.
+ *
+ * Deliberate scope limit: colour contrast is NOT computed here. Contrast
+ * needs resolved foreground/background pixels or computed styles, and the AX
+ * tree carries neither — guessing it would produce confident nonsense. The
+ * report says so explicitly instead.
+ *
+ * Every rule is a pure function of a node array, so the fixtures in the tests
+ * are just hand-written AX trees.
+ */
+
+import type { A11yFinding, AxNode, FocusCandidate } from './types.js';
+
+/** Roles whose whole purpose is to be activated — a nameless one is unusable. */
+const COMMAND_ROLES = new Set([
+  'button',
+  'link',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'tab',
+  'switch',
+  'treeitem',
+]);
+
+/** Roles that take user input and therefore need a programmatic label. */
+const FORM_FIELD_ROLES = new Set([
+  'textbox',
+  'searchbox',
+  'combobox',
+  'listbox',
+  'checkbox',
+  'radio',
+  'slider',
+  'spinbutton',
+]);
+
+const IMAGE_ROLES = new Set(['image', 'img']);
+
+/** Natively focusable tags — a negative tabindex on these removes them from the tab order. */
+const NATIVELY_FOCUSABLE = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary']);
+
+function strValue(v: unknown): string {
+  return typeof v === 'string' ? v : v == null ? '' : String(v);
+}
+
+function roleOf(node: AxNode): string {
+  return strValue(node.role?.value).toLowerCase();
+}
+
+function nameOf(node: AxNode): string {
+  return strValue(node.name?.value).trim();
+}
+
+function propOf(node: AxNode, name: string): unknown {
+  return node.properties?.find((p) => p.name === name)?.value?.value;
+}
+
+function locatorFor(node: AxNode, locators?: Map<number, string>): string {
+  if (node.backendDOMNodeId !== undefined) {
+    const found = locators?.get(node.backendDOMNodeId);
+    if (found) return found;
+  }
+  return `ax-node:${node.nodeId}`;
+}
+
+/**
+ * Depth-first document order. `Accessibility.getFullAXTree` usually returns
+ * nodes pre-ordered already, but heading-order is the one rule where a
+ * reordered array would silently produce wrong findings, so we walk childIds
+ * ourselves. Nodes unreachable from a root are appended in array order rather
+ * than dropped.
+ */
+export function orderNodes(nodes: AxNode[]): AxNode[] {
+  const byId = new Map<string, AxNode>();
+  for (const n of nodes) byId.set(String(n.nodeId), n);
+
+  const ids = new Set(byId.keys());
+  const roots = nodes.filter((n) => n.parentId === undefined || !ids.has(String(n.parentId)));
+
+  const seen = new Set<string>();
+  const ordered: AxNode[] = [];
+  const visit = (node: AxNode): void => {
+    const id = String(node.nodeId);
+    if (seen.has(id)) return;
+    seen.add(id);
+    ordered.push(node);
+    for (const childId of node.childIds ?? []) {
+      const child = byId.get(String(childId));
+      if (child) visit(child);
+    }
+  };
+  for (const root of roots) visit(root);
+  for (const node of nodes) if (!seen.has(String(node.nodeId))) ordered.push(node);
+  return ordered;
+}
+
+/**
+ * Nameless controls, images without alt text, and unlabelled form fields.
+ *
+ * `ignored` nodes are skipped: that is how `<img alt="">` correctly escapes
+ * the image rule — a deliberately decorative image is dropped from the AX
+ * tree, while `<img>` with no alt attribute at all stays in it with an empty
+ * name, which is the bug we want to report.
+ */
+export function findNamingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const node of nodes) {
+    if (node.ignored) continue;
+    const role = roleOf(node);
+    if (!role) continue;
+    const name = nameOf(node);
+    if (name) continue;
+
+    if (FORM_FIELD_ROLES.has(role)) {
+      findings.push({
+        rule: 'form-field-no-label',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — no <label>, aria-label or aria-labelledby resolves to one`,
+      });
+      continue;
+    }
+
+    if (COMMAND_ROLES.has(role)) {
+      findings.push({
+        rule: 'unlabelled-control',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — a screen reader announces it as just "${role}"`,
+      });
+      continue;
+    }
+
+    if (IMAGE_ROLES.has(role)) {
+      findings.push({
+        rule: 'image-missing-alt',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: 'image has no alt text (use alt="" if it is purely decorative)',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Headings that skip a level (h1 -> h3), plus a document whose first heading
+ * is not h1. Both break the outline screen-reader users navigate by.
+ */
+export function findHeadingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  let previous: number | null = null;
+
+  for (const node of orderNodes(nodes)) {
+    if (node.ignored) continue;
+    if (roleOf(node) !== 'heading') continue;
+    const raw = propOf(node, 'level');
+    const level = typeof raw === 'number' ? raw : Number.parseInt(strValue(raw), 10);
+    if (!Number.isFinite(level) || level < 1) continue;
+
+    const name = nameOf(node);
+    if (previous === null) {
+      if (level > 1) {
+        findings.push({
+          rule: 'heading-order-jump',
+          impact: 'warning',
+          role: 'heading',
+          name: name || null,
+          locator: locatorFor(node, locators),
+          detail: `document outline starts at h${level} — the first heading should be h1`,
+        });
+      }
+    } else if (level > previous + 1) {
+      findings.push({
+        rule: 'heading-order-jump',
+        impact: 'warning',
+        role: 'heading',
+        name: name || null,
+        locator: locatorFor(node, locators),
+        detail: `heading level jumps h${previous} -> h${level}`,
+      });
+    }
+    previous = level;
+  }
+  return findings;
+}
+
+/**
+ * Interactive elements pulled out of the keyboard tab order by a negative
+ * tabindex. They stay clickable with a mouse and stay in the AX tree, so
+ * nothing else in this file can see them — the candidates come from a DOM
+ * sweep in collect.ts.
+ */
+export function findFocusOrderIssues(candidates: FocusCandidate[]): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const c of candidates) {
+    if (c.tabindex >= 0) continue;
+    const interactive = NATIVELY_FOCUSABLE.has(c.tag.toLowerCase()) || c.role !== '';
+    if (!interactive) continue;
+    findings.push({
+      rule: 'negative-tabindex',
+      impact: 'warning',
+      role: c.role || c.tag.toLowerCase(),
+      name: c.name,
+      locator: c.locator,
+      detail: `<${c.tag.toLowerCase()}> has tabindex="${c.tabindex}" — mouse users can reach it, keyboard users cannot`,
+    });
+  }
+  return findings;
+}
+
+export interface A11yInput {
+  nodes: AxNode[];
+  focusCandidates?: FocusCandidate[];
+  locators?: Map<number, string>;
+}
+
+export function runA11yRules({ nodes, focusCandidates = [], locators }: A11yInput): A11yFinding[] {
+  return [
+    ...findNamingIssues(nodes, locators),
+    ...findHeadingIssues(nodes, locators),
+    ...findFocusOrderIssues(focusCandidates),
+  ];
+}
+
+export function countA11y(findings: A11yFinding[]): { errors: number; warnings: number } {
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    if (f.impact === 'error') errors++;
+    else warnings++;
+  }
+  return { errors, warnings };
+}