feat(auth): add aggregate status command (#1879)

Author: jackwener

clis/_shared/site-auth.js

@@ -29,6 +29,14 @@ function commandColumns(config) {
   return ['logged_in', 'site', ...identityColumns];
 }
 
+function normalizeQuickCheck(result) {
+  if (typeof result === 'boolean') return { logged_in: result };
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    return { logged_in: !!result.logged_in, ...result };
+  }
+  return { logged_in: false };
+}
+
 export function registerSiteAuthCommands(config) {
   if (!config?.site || !config?.domain || !config?.loginUrl || typeof config.verify !== 'function') {
     throw new Error('registerSiteAuthCommands requires site, domain, loginUrl, and verify(page)');
@@ -45,6 +53,9 @@ export function registerSiteAuthCommands(config) {
     navigateBefore: false,
     args: [],
     columns: commandColumns(config),
+    authStatus: typeof config.quickCheck === 'function'
+      ? { quickCheck: async (page) => normalizeQuickCheck(await config.quickCheck(page)) }
+      : undefined,
     func: async (page) => tryProbe(config, page, 'identity'),
   });
 

src/cli.test.ts

@@ -66,13 +66,47 @@ describe('createProgram root help descriptions', () => {
     expect(descriptionFor(program, 'browser')).toContain('type');
     expect(descriptionFor(program, 'browser')).toContain('verify');
     expect(descriptionFor(program, 'browser')).not.toContain('Browser control');
+    expect(descriptionFor(program, 'auth')).toBe('status');
     expect(descriptionFor(program, 'plugin')).toBe('create, install, list, uninstall, update');
     expect(descriptionFor(program, 'adapter')).toBe('eject, reset, status');
     expect(descriptionFor(program, 'profile')).toBe('list, rename, use');
     expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop');
     expect(descriptionFor(program, 'external')).toBe('install, list, register');
   });
 
+  it('renders auth namespace structured help', () => {
+    const argv = process.argv;
+    try {
+      const program = createProgram('', '');
+      const auth = program.commands.find(cmd => cmd.name() === 'auth')!;
+      expect(auth).toBeTruthy();
+
+      process.argv = ['node', 'opencli', 'auth', '--help', '-f', 'yaml'];
+      const data = yaml.load(auth.helpInformation()) as any;
+
+      expect(data).toMatchObject({
+        namespace: 'auth',
+        description: 'Inspect website login status',
+        command_count: 1,
+      });
+      expect(data.commands.map((cmd: any) => cmd.name)).toEqual(['status']);
+      const status = auth.commands.find(cmd => cmd.name() === 'status')!;
+      process.argv = ['node', 'opencli', 'auth', 'status', '--help', '-f', 'yaml'];
+      const statusData = yaml.load(status.helpInformation()) as any;
+      expect(statusData.command).toBe('opencli auth status');
+      expect(statusData.command_options.map((option: any) => option.name)).toEqual(expect.arrayContaining([
+        'site',
+        'full',
+        'concurrency',
+        'timeout',
+        'only',
+        'format',
+      ]));
+    } finally {
+      process.argv = argv;
+    }
+  });
+
   it('keeps leaf command descriptions unchanged', () => {
     const program = createProgram('', '');
 

src/cli.ts

@@ -30,6 +30,7 @@ import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
 import { buildHtmlTreeJs, type HtmlTreeResult } from './browser/html-tree.js';
 import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
 import { analyzeSite, type PageSignals } from './browser/analyze.js';
+import { registerAuthCommands } from './commands/auth.js';
 import { daemonRestart, daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 import { bindTab, BrowserCommandError, fetchDaemonStatus, sendCommand } from './browser/daemon-client.js';
@@ -796,6 +797,8 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command
       process.exitCode = r.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
     });
 
+  const authCmd = registerAuthCommands(program);
+
   program
     .command('convention-audit')
     .description('Scan adapters for agent-native convention violations')
@@ -3470,6 +3473,7 @@ cli({
   const adapterGroups: RootAdapterGroups = { external: externalHelpEntries, apps, sites };
   const adapterNameSet = new Set<string>([...externalNames, ...siteNames]);
   installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
+  installCommanderNamespaceStructuredHelp(authCmd, { globalCommand: program, description: 'Inspect website login status' });
   installCommanderNamespaceStructuredHelp(daemonCmd, { globalCommand: program, description: originalDaemonDescription });
   installCommanderNamespaceStructuredHelp(pluginCmd, { globalCommand: program, description: originalPluginDescription });
   installCommanderNamespaceStructuredHelp(adapterCmd, { globalCommand: program, description: originalAdapterDescription });

src/commands/auth.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { BrowserCliCommand } from '../registry.js';
+
+const executeCommandMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../execution.js', () => ({
+  executeCommand: executeCommandMock,
+}));
+
+import { collectAuthStatus } from './auth.js';
+import { AuthRequiredError } from '../errors.js';
+import { cli, getRegistry, Strategy } from '../registry.js';
+
+function registerWhoami(site: string, opts: {
+  quick?: boolean;
+  quickLoggedIn?: boolean;
+  identity?: Record<string, unknown>;
+} = {}): void {
+  cli({
+    site,
+    name: 'whoami',
+    access: 'read',
+    description: `${site} whoami`,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    domain: `${site}.example.com`,
+    navigateBefore: false,
+    args: [],
+    columns: ['logged_in', 'site', 'username'],
+    authStatus: opts.quick
+      ? { quickCheck: async () => ({ logged_in: opts.quickLoggedIn ?? false }) }
+      : undefined,
+    func: async () => opts.identity ?? { logged_in: true, site, username: site },
+  });
+}
+
+beforeEach(() => {
+  getRegistry().clear();
+  executeCommandMock.mockReset();
+  executeCommandMock.mockImplementation(async (cmd: BrowserCliCommand, kwargs: Record<string, unknown>) => {
+    if (!cmd.func) return {};
+    return cmd.func({} as never, kwargs);
+  });
+});
+
+describe('auth status collection', () => {
+  it('uses quickCheck by default and does not run full whoami', async () => {
+    registerWhoami('alpha', { quick: true, quickLoggedIn: true, identity: { username: 'full-alpha' } });
+
+    const rows = await collectAuthStatus({ sites: 'alpha' });
+
+    expect(rows).toEqual([
+      { site: 'alpha', status: 'logged_in', logged_in: true, identity: '', checked: 'quick', error: '' },
+    ]);
+    expect(executeCommandMock).toHaveBeenCalledTimes(1);
+    expect(executeCommandMock.mock.calls[0]?.[0]).toMatchObject({
+      site: 'alpha',
+      name: 'whoami',
+      navigateBefore: false,
+      siteSession: 'ephemeral',
+      defaultWindowMode: 'background',
+    });
+  });
+
+  it('marks sites without quickCheck as unknown unless --full is used', async () => {
+    registerWhoami('beta');
+
+    const rows = await collectAuthStatus({ sites: 'beta' });
+
+    expect(rows).toEqual([
+      {
+        site: 'beta',
+        status: 'unknown',
+        logged_in: '',
+        identity: '',
+        checked: 'skipped',
+        error: 'quickCheck not implemented; use --full to run whoami',
+      },
+    ]);
+    expect(executeCommandMock).not.toHaveBeenCalled();
+  });
+
+  it('runs full whoami with --full and returns a safe identity summary', async () => {
+    registerWhoami('gamma', {
+      identity: {
+        logged_in: true,
+        site: 'gamma',
+        email: 'hidden@example.com',
+        username: 'public-handle',
+      },
+    });
+
+    const rows = await collectAuthStatus({ sites: 'gamma', full: true });
+
+    expect(rows).toEqual([
+      { site: 'gamma', status: 'logged_in', logged_in: true, identity: 'public-handle', checked: 'full', error: '' },
+    ]);
+  });
+
+  it('converts AuthRequiredError into not_logged_in rows', async () => {
+    registerWhoami('delta', { quick: true });
+    executeCommandMock.mockRejectedValueOnce(new AuthRequiredError('delta.example.com'));
+
+    const rows = await collectAuthStatus({ sites: 'delta' });
+
+    expect(rows).toEqual([
+      { site: 'delta', status: 'not_logged_in', logged_in: false, identity: '', checked: 'quick', error: '' },
+    ]);
+  });
+});