test: mock connector for e2e/browser/local dev (#258)

CONTRIBUTING.md

···
   - [Available commands](#available-commands)
   - [Project structure](#project-structure)
   - [Local connector CLI](#local-connector-cli)
+  - [Mock connector (for local development)](#mock-connector-for-local-development)
 - [Code style](#code-style)
   - [TypeScript](#typescript)
   - [Server API patterns](#server-api-patterns)
···
 pnpm build            # Production build
 pnpm preview          # Preview production build
 
+# Connector
+pnpm npmx-connector   # Start the real connector (requires npm login)
+pnpm mock-connector   # Start the mock connector (no npm login needed)
+
 # Code Quality
 pnpm lint             # Run linter (oxlint + oxfmt)
 pnpm lint:fix         # Auto-fix lint issues
···
 ```
 
 The connector will check your npm authentication, generate a connection token, and listen for requests from npmx.dev.
+
+### Mock connector (for local development)
+
+If you're working on admin features (org management, package access controls, operations queue) and don't want to use your real npm account, you can run the mock connector instead:
+
+```bash
+pnpm mock-connector
+```
+
+This starts a mock connector server pre-populated with sample data (orgs, teams, members, packages). No npm login is required — operations succeed immediately without making real npm CLI calls.
+
+The mock connector prints a connection URL to the terminal, just like the real connector. Click it (or paste the token manually) to connect the UI.
+
+**Options:**
+
+```bash
+pnpm mock-connector                # default: port 31415, user "mock-user", sample data
+pnpm mock-connector --port 9999    # custom port
+pnpm mock-connector --user alice   # custom username
+pnpm mock-connector --empty        # start with no pre-populated data
+```
+
+**Default sample data:**
+
+- **@nuxt**: 4 members (mock-user, danielroe, pi0, antfu), 3 teams (core, docs, triage)
+- **@unjs**: 2 members (mock-user, pi0), 1 team (maintainers)
+- **Packages**: @nuxt/kit, @nuxt/schema, @unjs/nitro with team-based access controls
+
+> [!TIP]
+> Run `pnpm dev` in a separate terminal to start the Nuxt dev server, then click the connection URL from the mock connector to connect.
 
 ## Code style
 
···
 
 1. Add a fixture file for that package/endpoint
 2. Update the mock handlers in `test/fixtures/mock-routes.cjs` (client) or `modules/runtime/server/cache.ts` (server)
+
+### Testing connector features
+
+Features that require authentication through the local connector (org management, package collaborators, operations queue) are tested using a mock connector server.
+
+#### Architecture
+
+The mock connector infrastructure is shared between the CLI, E2E tests, and Vitest component tests:
+
+```
+cli/src/
+├── types.ts           # ConnectorEndpoints contract (shared by real + mock)
+├── mock-state.ts      # MockConnectorStateManager (canonical source)
+├── mock-app.ts        # H3 mock app + MockConnectorServer class
+└── mock-server.ts     # CLI entry point (pnpm mock-connector)
+
+test/test-utils/       # Re-exports from cli/src/ for test convenience
+test/e2e/helpers/      # E2E-specific wrappers (fixtures, global setup)
+```
+
+Both the real server (`cli/src/server.ts`) and the mock server (`cli/src/mock-app.ts`) conform to the `ConnectorEndpoints` interface defined in `cli/src/types.ts`. This ensures the API contract is enforced by TypeScript. When adding a new endpoint, update `ConnectorEndpoints` first, then implement it in both servers.
+
+#### Vitest component tests (`test/nuxt/`)
+
+- Mock the `useConnector` composable with reactive state
+- Use `document.body` queries for components using Teleport
+- See `test/nuxt/components/HeaderConnectorModal.spec.ts` for an example
+
+```typescript
+// Create mock state
+const mockState = ref({ connected: false, npmUser: null, ... })
+
+// Mock the composable
+vi.mock('~/composables/useConnector', () => ({
+  useConnector: () => ({
+    isConnected: computed(() => mockState.value.connected),
+    // ... other properties
+  }),
+}))
+```
+
+#### Playwright E2E tests (`test/e2e/`)
+
+- A mock HTTP server starts automatically via Playwright's global setup
+- Use the `mockConnector` fixture to set up test data and the `gotoConnected` helper to navigate with authentication
+
+```typescript
+test('shows org members', async ({ page, gotoConnected, mockConnector }) => {
+  // Set up test data
+  await mockConnector.setOrgData('@testorg', {
+    users: { testuser: 'owner', member1: 'admin' },
+  })
+
+  // Navigate with connector authentication
+  await gotoConnected('/@testorg')
+
+  // Test assertions
+  await expect(page.getByRole('link', { name: '@testuser' })).toBeVisible()
+})
+```
+
+The mock connector supports test endpoints for state manipulation:
+
+- `/__test__/reset` - Reset all mock state
+- `/__test__/org` - Set org users, teams, and team members
+- `/__test__/user-orgs` - Set user's organizations
+- `/__test__/user-packages` - Set user's packages
+- `/__test__/package` - Set package collaborators
 
 ## Submitting changes
 

app/composables/useConnector.ts

···
-import type { PendingOperation, OperationStatus, OperationType } from '../../cli/src/types'
+import type { PendingOperation, OperationStatus, OperationType } from '#cli/types'
 import { $fetch } from 'ofetch'
 
 export interface NewOperation {

cli/package.json

···
     "npmx-connector": "./dist/cli.mjs"
   },
   "exports": {
-    ".": {
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.mts"
-    }
+    ".": "./dist/index.mjs"
   },
   "files": [
     "dist"
···
     "build": "tsdown",
     "dev": "NPMX_CLI_DEV=true node src/cli.ts",
     "dev:debug": "DEBUG=npmx-connector NPMX_CLI_DEV=true node src/cli.ts",
+    "dev:mock": "NPMX_CLI_DEV=true node src/mock-server.ts",
     "test:types": "tsc --noEmit"
   },
   "dependencies": {

cli/src/mock-app.ts

···
+/**
+ * Mock connector H3 application. Same API as the real server (server.ts)
+ * but backed by in-memory state. Used by the mock CLI and E2E tests.
+ */
+
+import { H3, HTTPError, handleCors, type H3Event } from 'h3-next'
+import type { CorsOptions } from 'h3-next'
+import { serve, type Server } from 'srvx'
+import type {
+  OperationType,
+  ApiResponse,
+  ConnectorEndpoints,
+  AssertEndpointsImplemented,
+} from './types.ts'
+import type { MockConnectorStateManager } from './mock-state.ts'
+
+// Endpoint completeness check — errors if this list diverges from ConnectorEndpoints.
+// oxlint-disable-next-line no-unused-vars
+const _endpointCheck: AssertEndpointsImplemented<
+  | 'POST /connect'
+  | 'GET /state'
+  | 'POST /operations'
+  | 'POST /operations/batch'
+  | 'DELETE /operations'
+  | 'DELETE /operations/all'
+  | 'POST /approve'
+  | 'POST /approve-all'
+  | 'POST /retry'
+  | 'POST /execute'
+  | 'GET /org/:org/users'
+  | 'GET /org/:org/teams'
+  | 'GET /team/:scopeTeam/users'
+  | 'GET /package/:pkg/collaborators'
+  | 'GET /user/packages'
+  | 'GET /user/orgs'
+> = true
+void _endpointCheck
+
+const corsOptions: CorsOptions = {
+  origin: '*',
+  methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+  allowHeaders: ['Content-Type', 'Authorization'],
+}
+
+function createMockConnectorApp(stateManager: MockConnectorStateManager) {
+  const app = new H3()
+
+  app.use((event: H3Event) => {
+    const corsResult = handleCors(event, corsOptions)
+    if (corsResult !== false) {
+      return corsResult
+    }
+  })
+
+  function requireAuth(event: H3Event): void {
+    const authHeader = event.req.headers.get('authorization')
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      throw new HTTPError({ statusCode: 401, message: 'Authorization required' })
+    }
+    const token = authHeader.slice(7)
+    if (token !== stateManager.token) {
+      throw new HTTPError({ statusCode: 401, message: 'Invalid token' })
+    }
+    if (!stateManager.isConnected()) {
+      throw new HTTPError({ statusCode: 401, message: 'Not connected' })
+    }
+  }
+
+  // POST /connect
+  app.post('/connect', async (event: H3Event) => {
+    const body = (await event.req.json()) as { token?: string }
+    const token = body?.token
+
+    if (!token || token !== stateManager.token) {
+      throw new HTTPError({ statusCode: 401, message: 'Invalid token' })
+    }
+
+    stateManager.connect(token)
+
+    return {
+      success: true,
+      data: {
+        npmUser: stateManager.config.npmUser,
+        avatar: stateManager.config.avatar ?? null,
+        connectedAt: stateManager.state.connectedAt ?? Date.now(),
+      },
+    } satisfies ApiResponse<ConnectorEndpoints['POST /connect']['data']>
+  })
+
+  // GET /state
+  app.get('/state', (event: H3Event) => {
+    requireAuth(event)
+
+    return {
+      success: true,
+      data: {
+        npmUser: stateManager.config.npmUser,
+        avatar: stateManager.config.avatar ?? null,
+        operations: stateManager.getOperations(),
+      },
+    } satisfies ApiResponse<ConnectorEndpoints['GET /state']['data']>
+  })
+
+  // POST /operations
+  app.post('/operations', async (event: H3Event) => {
+    requireAuth(event)
+
+    const body = (await event.req.json()) as {
+      type?: string
+      params?: Record<string, string>
+      description?: string
+      command?: string
+      dependsOn?: string
+    }
+    if (!body?.type || !body.description || !body.command) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing required fields' })
+    }
+
+    const operation = stateManager.addOperation({
+      type: body.type as OperationType,
+      params: body.params ?? {},
+      description: body.description,
+      command: body.command,
+      dependsOn: body.dependsOn,
+    })
+
+    return {
+      success: true,
+      data: operation,
+    } satisfies ApiResponse<ConnectorEndpoints['POST /operations']['data']>
+  })
+
+  // POST /operations/batch
+  app.post('/operations/batch', async (event: H3Event) => {
+    requireAuth(event)
+
+    const body = await event.req.json()
+    if (!Array.isArray(body)) {
+      throw new HTTPError({ statusCode: 400, message: 'Expected array of operations' })
+    }
+
+    const operations = stateManager.addOperations(body)
+    return {
+      success: true,
+      data: operations,
+    } satisfies ApiResponse<ConnectorEndpoints['POST /operations/batch']['data']>
+  })
+
+  // DELETE /operations?id=<id>
+  app.delete('/operations', (event: H3Event) => {
+    requireAuth(event)
+
+    const id = new URL(event.req.url).searchParams.get('id')
+    if (!id) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing operation id' })
+    }
+
+    const removed = stateManager.removeOperation(id)
+    if (!removed) {
+      throw new HTTPError({ statusCode: 404, message: 'Operation not found or cannot be removed' })
+    }
+
+    return { success: true } satisfies ApiResponse<ConnectorEndpoints['DELETE /operations']['data']>
+  })
+
+  // DELETE /operations/all
+  app.delete('/operations/all', (event: H3Event) => {
+    requireAuth(event)
+
+    const removed = stateManager.clearOperations()
+    return {
+      success: true,
+      data: { removed },
+    } satisfies ApiResponse<ConnectorEndpoints['DELETE /operations/all']['data']>
+  })
+
+  // POST /approve?id=<id>
+  app.post('/approve', (event: H3Event) => {
+    requireAuth(event)
+
+    const id = new URL(event.req.url).searchParams.get('id')
+    if (!id) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing operation id' })
+    }
+
+    const operation = stateManager.approveOperation(id)
+    if (!operation) {
+      throw new HTTPError({ statusCode: 404, message: 'Operation not found or not pending' })
+    }
+
+    return {
+      success: true,
+      data: operation,
+    } satisfies ApiResponse<ConnectorEndpoints['POST /approve']['data']>
+  })
+
+  // POST /approve-all
+  app.post('/approve-all', (event: H3Event) => {
+    requireAuth(event)
+
+    const approved = stateManager.approveAll()
+    return {
+      success: true,
+      data: { approved },
+    } satisfies ApiResponse<ConnectorEndpoints['POST /approve-all']['data']>
+  })
+
+  // POST /retry?id=<id>
+  app.post('/retry', (event: H3Event) => {
+    requireAuth(event)
+
+    const id = new URL(event.req.url).searchParams.get('id')
+    if (!id) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing operation id' })
+    }
+
+    const operation = stateManager.retryOperation(id)
+    if (!operation) {
+      throw new HTTPError({ statusCode: 404, message: 'Operation not found or not failed' })
+    }
+
+    return {
+      success: true,
+      data: operation,
+    } satisfies ApiResponse<ConnectorEndpoints['POST /retry']['data']>
+  })
+
+  // POST /execute
+  app.post('/execute', async (event: H3Event) => {
+    requireAuth(event)
+
+    const body = await event.req.json().catch(() => ({}))
+    const otp = (body as { otp?: string })?.otp
+
+    const { results, otpRequired } = stateManager.executeOperations({ otp })
+
+    return {
+      success: true,
+      data: { results, otpRequired },
+    } satisfies ApiResponse<ConnectorEndpoints['POST /execute']['data']>
+  })
+
+  // GET /org/:org/users
+  app.get('/org/:org/users', (event: H3Event) => {
+    requireAuth(event)
+
+    const org = event.context.params?.org
+    if (!org) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing org parameter' })
+    }
+
+    const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+    const users = stateManager.getOrgUsers(normalizedOrg)
+    if (users === null) {
+      return { success: true, data: {} } satisfies ApiResponse<
+        ConnectorEndpoints['GET /org/:org/users']['data']
+      >
+    }
+
+    return { success: true, data: users } satisfies ApiResponse<
+      ConnectorEndpoints['GET /org/:org/users']['data']
+    >
+  })
+
+  // GET /org/:org/teams
+  app.get('/org/:org/teams', (event: H3Event) => {
+    requireAuth(event)
+
+    const org = event.context.params?.org
+    if (!org) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing org parameter' })
+    }
+
+    const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+    const orgName = normalizedOrg.slice(1)
+
+    const teams = stateManager.getOrgTeams(normalizedOrg)
+    const formattedTeams = teams ? teams.map(t => `${orgName}:${t}`) : []
+    return { success: true, data: formattedTeams } satisfies ApiResponse<
+      ConnectorEndpoints['GET /org/:org/teams']['data']
+    >
+  })
+
+  // GET /team/:scopeTeam/users
+  app.get('/team/:scopeTeam/users', (event: H3Event) => {
+    requireAuth(event)
+
+    const scopeTeam = event.context.params?.scopeTeam
+    if (!scopeTeam) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing scopeTeam parameter' })
+    }
+
+    if (!scopeTeam.startsWith('@') || !scopeTeam.includes(':')) {
+      throw new HTTPError({
+        statusCode: 400,
+        message: 'Invalid scope:team format (expected @scope:team)',
+      })
+    }
+
+    const [scope, team] = scopeTeam.split(':')
+    if (!scope || !team) {
+      throw new HTTPError({ statusCode: 400, message: 'Invalid scope:team format' })
+    }
+
+    const users = stateManager.getTeamUsers(scope, team)
+    return { success: true, data: users ?? [] } satisfies ApiResponse<
+      ConnectorEndpoints['GET /team/:scopeTeam/users']['data']
+    >
+  })
+
+  // GET /package/:pkg/collaborators
+  app.get('/package/:pkg/collaborators', (event: H3Event) => {
+    requireAuth(event)
+
+    const pkg = event.context.params?.pkg
+    if (!pkg) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing package parameter' })
+    }
+
+    const collaborators = stateManager.getPackageCollaborators(decodeURIComponent(pkg))
+    return { success: true, data: collaborators ?? {} } satisfies ApiResponse<
+      ConnectorEndpoints['GET /package/:pkg/collaborators']['data']
+    >
+  })
+
+  // GET /user/packages
+  app.get('/user/packages', (event: H3Event) => {
+    requireAuth(event)
+
+    const packages = stateManager.getUserPackages()
+    return { success: true, data: packages } satisfies ApiResponse<
+      ConnectorEndpoints['GET /user/packages']['data']
+    >
+  })
+
+  // GET /user/orgs
+  app.get('/user/orgs', (event: H3Event) => {
+    requireAuth(event)
+
+    const orgs = stateManager.getUserOrgs()
+    return { success: true, data: orgs } satisfies ApiResponse<
+      ConnectorEndpoints['GET /user/orgs']['data']
+    >
+  })
+
+  // -- Test-only endpoints --
+
+  // POST /__test__/reset
+  app.post('/__test__/reset', () => {
+    stateManager.reset()
+    return { success: true }
+  })
+
+  // POST /__test__/org
+  app.post('/__test__/org', async (event: H3Event) => {
+    const body = (await event.req.json()) as {
+      org?: string
+      users?: Record<string, 'developer' | 'admin' | 'owner'>
+      teams?: string[]
+      teamMembers?: Record<string, string[]>
+    }
+    if (!body?.org) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing org parameter' })
+    }
+
+    stateManager.setOrgData(body.org, {
+      users: body.users,
+      teams: body.teams,
+      teamMembers: body.teamMembers,
+    })
+
+    return { success: true }
+  })
+
+  // POST /__test__/user-orgs
+  app.post('/__test__/user-orgs', async (event: H3Event) => {
+    const body = (await event.req.json()) as { orgs?: string[] }
+    if (!body?.orgs) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing orgs parameter' })
+    }
+
+    stateManager.setUserOrgs(body.orgs)
+    return { success: true }
+  })
+
+  // POST /__test__/user-packages
+  app.post('/__test__/user-packages', async (event: H3Event) => {
+    const body = (await event.req.json()) as {
+      packages?: Record<string, 'read-only' | 'read-write'>
+    }
+    if (!body?.packages) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing packages parameter' })
+    }
+
+    stateManager.setUserPackages(body.packages)
+    return { success: true }
+  })
+
+  // POST /__test__/package
+  app.post('/__test__/package', async (event: H3Event) => {
+    const body = (await event.req.json()) as {
+      package?: string
+      collaborators?: Record<string, 'read-only' | 'read-write'>
+    }
+    if (!body?.package) {
+      throw new HTTPError({ statusCode: 400, message: 'Missing package parameter' })
+    }
+
+    stateManager.setPackageData(body.package, {
+      collaborators: body.collaborators ?? {},
+    })
+
+    return { success: true }
+  })
+
+  return app
+}
+
+/** Wraps the mock H3 app in an HTTP server via srvx. */
+export class MockConnectorServer {
+  private server: Server | null = null
+  private stateManager: MockConnectorStateManager
+
+  constructor(stateManager: MockConnectorStateManager) {
+    this.stateManager = stateManager
+  }
+
+  async start(): Promise<void> {
+    if (this.server) {
+      throw new Error('Mock connector server is already running')
+    }
+
+    const app = createMockConnectorApp(this.stateManager)
+
+    this.server = serve({
+      port: this.stateManager.port,
+      hostname: '127.0.0.1',
+      fetch: app.fetch,
+    })
+
+    await this.server.ready()
+    console.log(`[Mock Connector] Started on http://127.0.0.1:${this.stateManager.port}`)
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return
+    await this.server.close()
+    console.log('[Mock Connector] Stopped')
+    this.server = null
+  }
+
+  get state(): MockConnectorStateManager {
+    return this.stateManager
+  }
+
+  get port(): number {
+    return this.stateManager.port
+  }
+
+  get token(): string {
+    return this.stateManager.token
+  }
+
+  reset(): void {
+    this.stateManager.reset()
+  }
+}

cli/src/mock-server.ts

···
+#!/usr/bin/env node
+/**
+ * Mock connector CLI — starts a pre-populated mock server for developing
+ * authenticated features without a real npm account.
+ */
+
+import process from 'node:process'
+import crypto from 'node:crypto'
+import { styleText } from 'node:util'
+import * as p from '@clack/prompts'
+import { defineCommand, runMain } from 'citty'
+import {
+  MockConnectorStateManager,
+  createMockConnectorState,
+  type MockConnectorConfig,
+} from './mock-state.ts'
+import { MockConnectorServer } from './mock-app.ts'
+
+const DEFAULT_PORT = 31415
+const DEV_FRONTEND_URL = 'http://127.0.0.1:3000/'
+const PROD_FRONTEND_URL = 'https://npmx.dev/'
+
+function generateToken(): string {
+  return crypto.randomBytes(16).toString('hex')
+}
+
+/**
+ * Pre-populate with sample data using real npm orgs so the registry
+ * API calls don't 404. Members/teams are fictional.
+ */
+function populateDefaultData(stateManager: MockConnectorStateManager): void {
+  const npmUser = stateManager.config.npmUser
+
+  stateManager.setOrgData('@nuxt', {
+    users: {
+      [npmUser]: 'owner',
+      danielroe: 'owner',
+      pi0: 'admin',
+      antfu: 'developer',
+    },
+    teams: ['core', 'docs', 'triage'],
+    teamMembers: {
+      core: [npmUser, 'danielroe', 'pi0'],
+      docs: ['antfu'],
+      triage: ['pi0', 'antfu'],
+    },
+  })
+
+  stateManager.setOrgData('@unjs', {
+    users: {
+      [npmUser]: 'admin',
+      pi0: 'owner',
+    },
+    teams: ['maintainers'],
+    teamMembers: {
+      maintainers: [npmUser, 'pi0'],
+    },
+  })
+
+  stateManager.setUserOrgs(['nuxt', 'unjs'])
+
+  stateManager.setPackageData('@nuxt/kit', {
+    collaborators: {
+      [npmUser]: 'read-write',
+      'danielroe': 'read-write',
+      'nuxt:core': 'read-write',
+      'nuxt:docs': 'read-only',
+    },
+  })
+  stateManager.setPackageData('@nuxt/schema', {
+    collaborators: {
+      [npmUser]: 'read-write',
+      'nuxt:core': 'read-write',
+    },
+  })
+  stateManager.setPackageData('@unjs/nitro', {
+    collaborators: {
+      [npmUser]: 'read-write',
+      'pi0': 'read-write',
+      'unjs:maintainers': 'read-write',
+    },
+  })
+
+  stateManager.setUserPackages({
+    '@nuxt/kit': 'read-write',
+    '@nuxt/schema': 'read-write',
+    '@unjs/nitro': 'read-write',
+  })
+}
+
+const main = defineCommand({
+  meta: {
+    name: 'npmx-connector-mock',
+    version: '0.0.1',
+    description: 'Mock connector for npmx.dev development and testing',
+  },
+  args: {
+    port: {
+      type: 'string',
+      description: 'Port to listen on',
+      default: String(DEFAULT_PORT),
+    },
+    user: {
+      type: 'string',
+      description: 'Simulated npm username',
+      default: 'mock-user',
+    },
+    empty: {
+      type: 'boolean',
+      description: 'Start with empty state (no pre-populated data)',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const port = Number.parseInt(args.port as string, 10) || DEFAULT_PORT
+    const npmUser = args.user as string
+    const empty = args.empty as boolean
+    const frontendUrl = process.env.NPMX_CLI_DEV === 'true' ? DEV_FRONTEND_URL : PROD_FRONTEND_URL
+
+    p.intro(styleText(['bgMagenta', 'white'], ' npmx mock connector '))
+
+    const token = generateToken()
+    const config: MockConnectorConfig = {
+      token,
+      npmUser,
+      avatar: null,
+      port,
+    }
+    const stateManager = new MockConnectorStateManager(createMockConnectorState(config))
+
+    if (!empty) {
+      populateDefaultData(stateManager)
+      p.log.info(`Pre-populated with sample data for ${styleText('cyan', npmUser)}`)
+      p.log.info(styleText('dim', `  Orgs: @nuxt (4 members, 3 teams), @unjs (2 members, 1 team)`))
+      p.log.info(styleText('dim', `  Packages: @nuxt/kit, @nuxt/schema, @unjs/nitro`))
+    } else {
+      p.log.info('Starting with empty state')
+    }
+
+    stateManager.connect(token)
+    const server = new MockConnectorServer(stateManager)
+
+    try {
+      await server.start()
+    } catch (error) {
+      p.log.error(error instanceof Error ? error.message : 'Failed to start mock connector server')
+      process.exit(1)
+    }
+
+    const connectUrl = `${frontendUrl}?token=${token}&port=${port}`
+
+    p.note(
+      [
+        `Open: ${styleText(['bold', 'underline', 'cyan'], connectUrl)}`,
+        '',
+        styleText('dim', `Or paste token manually: ${token}`),
+        '',
+        styleText('dim', `User: ${npmUser} | Port: ${port}`),
+        styleText('dim', 'Operations will succeed immediately (no real npm calls)'),
+      ].join('\n'),
+      'Click to connect',
+    )
+
+    p.log.info('Waiting for connection... (Press Ctrl+C to stop)')
+  },
+})
+
+runMain(main)

cli/src/mock-state.ts

···
+/**
+ * Mock connector state management. Canonical source used by the mock server,
+ * E2E tests, and Vitest composable mocks.
+ */
+
+import type {
+  PendingOperation,
+  OperationType,
+  OperationResult,
+  OrgRole,
+  AccessPermission,
+} from './types.ts'
+
+export interface MockConnectorConfig {
+  token: string
+  npmUser: string
+  avatar?: string | null
+  port?: number
+}
+
+export interface MockOrgData {
+  users: Record<string, OrgRole>
+  teams: string[]
+  /** team name -> member usernames */
+  teamMembers: Record<string, string[]>
+}
+
+export interface MockPackageData {
+  collaborators: Record<string, AccessPermission>
+}
+
+export interface MockConnectorStateData {
+  config: MockConnectorConfig
+  connected: boolean
+  connectedAt: number | null
+  orgs: Record<string, MockOrgData>
+  packages: Record<string, MockPackageData>
+  userPackages: Record<string, AccessPermission>
+  userOrgs: string[]
+  operations: PendingOperation[]
+  operationIdCounter: number
+}
+
+export interface NewOperationInput {
+  type: OperationType
+  params: Record<string, string>
+  description: string
+  command: string
+  dependsOn?: string
+}
+
+export interface ExecuteOptions {
+  otp?: string
+  /** Per-operation results for testing failures. */
+  results?: Record<string, Partial<OperationResult>>
+}
+
+export interface ExecuteResult {
+  results: Array<{ id: string; result: OperationResult }>
+  otpRequired?: boolean
+}
+
+export function createMockConnectorState(config: MockConnectorConfig): MockConnectorStateData {
+  return {
+    config: {
+      port: 31415,
+      avatar: null,
+      ...config,
+    },
+    connected: false,
+    connectedAt: null,
+    orgs: {},
+    packages: {},
+    userPackages: {},
+    userOrgs: [],
+    operations: [],
+    operationIdCounter: 0,
+  }
+}
+
+/**
+ * Mock connector state, shared between the HTTP server and composable mock.
+ */
+export class MockConnectorStateManager {
+  public state: MockConnectorStateData
+
+  constructor(initialState: MockConnectorStateData) {
+    this.state = initialState
+  }
+
+  // -- Configuration --
+
+  get config(): MockConnectorConfig {
+    return this.state.config
+  }
+
+  get token(): string {
+    return this.state.config.token
+  }
+
+  get port(): number {
+    return this.state.config.port ?? 31415
+  }
+
+  // -- Connection --
+
+  connect(token: string): boolean {
+    if (token !== this.state.config.token) {
+      return false
+    }
+    this.state.connected = true
+    this.state.connectedAt = Date.now()
+    return true
+  }
+
+  disconnect(): void {
+    this.state.connected = false
+    this.state.connectedAt = null
+    this.state.operations = []
+  }
+
+  isConnected(): boolean {
+    return this.state.connected
+  }
+
+  // -- Org data --
+
+  setOrgData(org: string, data: Partial<MockOrgData>): void {
+    const existing = this.state.orgs[org] ?? { users: {}, teams: [], teamMembers: {} }
+    this.state.orgs[org] = {
+      users: { ...existing.users, ...data.users },
+      teams: data.teams ?? existing.teams,
+      teamMembers: { ...existing.teamMembers, ...data.teamMembers },
+    }
+  }
+
+  getOrgUsers(org: string): Record<string, OrgRole> | null {
+    const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+    return this.state.orgs[normalizedOrg]?.users ?? null
+  }
+
+  getOrgTeams(org: string): string[] | null {
+    const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+    return this.state.orgs[normalizedOrg]?.teams ?? null
+  }
+
+  getTeamUsers(scope: string, team: string): string[] | null {
+    const normalizedScope = scope.startsWith('@') ? scope : `@${scope}`
+    const org = this.state.orgs[normalizedScope]
+    if (!org) return null
+    return org.teamMembers[team] ?? null
+  }
+
+  // -- Package data --
+
+  setPackageData(pkg: string, data: MockPackageData): void {
+    this.state.packages[pkg] = data
+  }
+
+  getPackageCollaborators(pkg: string): Record<string, AccessPermission> | null {
+    return this.state.packages[pkg]?.collaborators ?? null
+  }
+
+  // -- User data --
+
+  setUserPackages(packages: Record<string, AccessPermission>): void {
+    this.state.userPackages = packages
+  }
+
+  setUserOrgs(orgs: string[]): void {
+    this.state.userOrgs = orgs
+  }
+
+  getUserPackages(): Record<string, AccessPermission> {
+    return this.state.userPackages
+  }
+
+  getUserOrgs(): string[] {
+    return this.state.userOrgs
+  }
+
+  // -- Operations queue --
+
+  addOperation(operation: NewOperationInput): PendingOperation {
+    const id = `op-${++this.state.operationIdCounter}`
+    const newOp: PendingOperation = {
+      id,
+      type: operation.type,
+      params: operation.params,
+      description: operation.description,
+      command: operation.command,
+      status: 'pending',
+      createdAt: Date.now(),
+      dependsOn: operation.dependsOn,
+    }
+    this.state.operations.push(newOp)
+    return newOp
+  }
+
+  addOperations(operations: NewOperationInput[]): PendingOperation[] {
+    return operations.map(op => this.addOperation(op))
+  }
+
+  getOperation(id: string): PendingOperation | undefined {
+    return this.state.operations.find(op => op.id === id)
+  }
+
+  getOperations(): PendingOperation[] {
+    return this.state.operations
+  }
+
+  removeOperation(id: string): boolean {
+    const index = this.state.operations.findIndex(op => op.id === id)
+    if (index === -1) return false
+    const op = this.state.operations[index]
+    // Can't remove running operations
+    if (op?.status === 'running') return false
+    this.state.operations.splice(index, 1)
+    return true
+  }
+
+  clearOperations(): number {
+    const removable = this.state.operations.filter(op => op.status !== 'running')
+    const count = removable.length
+    this.state.operations = this.state.operations.filter(op => op.status === 'running')
+    return count
+  }
+
+  approveOperation(id: string): PendingOperation | null {
+    const op = this.state.operations.find(op => op.id === id)
+    if (!op || op.status !== 'pending') return null
+    op.status = 'approved'
+    return op
+  }
+
+  approveAll(): number {
+    let count = 0
+    for (const op of this.state.operations) {
+      if (op.status === 'pending') {
+        op.status = 'approved'
+        count++
+      }
+    }
+    return count
+  }
+
+  retryOperation(id: string): PendingOperation | null {
+    const op = this.state.operations.find(op => op.id === id)
+    if (!op || op.status !== 'failed') return null
+    op.status = 'approved'
+    op.result = undefined
+    return op
+  }
+
+  /** Execute all approved operations (mock: instant success unless configured otherwise). */
+  executeOperations(options?: ExecuteOptions): ExecuteResult {
+    const results: Array<{ id: string; result: OperationResult }> = []
+    const approved = this.state.operations.filter(op => op.status === 'approved')
+
+    // Sort by dependencies
+    const sorted = this.sortByDependencies(approved)
+
+    for (const op of sorted) {
+      // Check if dependent operation completed successfully
+      if (op.dependsOn) {
+        const dep = this.state.operations.find(d => d.id === op.dependsOn)
+        if (!dep || dep.status !== 'completed') {
+          // Skip - dependency not met
+          continue
+        }
+      }
+
+      op.status = 'running'
+
+      // Check for configured result
+      const configuredResult = options?.results?.[op.id]
+      if (configuredResult) {
+        const result: OperationResult = {
+          stdout: configuredResult.stdout ?? '',
+          stderr: configuredResult.stderr ?? '',
+          exitCode: configuredResult.exitCode ?? 1,
+          requiresOtp: configuredResult.requiresOtp,
+          authFailure: configuredResult.authFailure,
+        }
+        op.result = result
+        op.status = result.exitCode === 0 ? 'completed' : 'failed'
+        results.push({ id: op.id, result })
+
+        if (result.requiresOtp && !options?.otp) {
+          return { results, otpRequired: true }
+        }
+      } else {
+        // Default: success
+        const result: OperationResult = {
+          stdout: `Mock: ${op.command}`,
+          stderr: '',
+          exitCode: 0,
+        }
+        op.result = result
+        op.status = 'completed'
+        results.push({ id: op.id, result })
+
+        // Apply the operation's effects to mock state
+        this.applyOperationEffect(op)
+      }
+    }
+
+    return { results }
+  }
+
+  /** Apply side effects of a completed operation. Param keys match schemas.ts. */
+  private applyOperationEffect(op: PendingOperation): void {
+    const { type, params } = op
+
+    switch (type) {
+      case 'org:add-user': {
+        // Params: { org, user, role } — OrgAddUserParamsSchema
+        const org = params['org']
+        const user = params['user']
+        const role = (params['role'] as OrgRole) ?? 'developer'
+        if (org && user) {
+          const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+          if (!this.state.orgs[normalizedOrg]) {
+            this.state.orgs[normalizedOrg] = { users: {}, teams: [], teamMembers: {} }
+          }
+          this.state.orgs[normalizedOrg].users[user] = role
+        }
+        break
+      }
+      case 'org:rm-user': {
+        // Params: { org, user } — OrgRemoveUserParamsSchema
+        const org = params['org']
+        const user = params['user']
+        if (org && user) {
+          const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+          if (this.state.orgs[normalizedOrg]) {
+            delete this.state.orgs[normalizedOrg].users[user]
+          }
+        }
+        break
+      }
+      case 'org:set-role': {
+        // Params: { org, user, role } — reuses OrgAddUserParamsSchema
+        const org = params['org']
+        const user = params['user']
+        const role = params['role'] as OrgRole
+        if (org && user && role) {
+          const normalizedOrg = org.startsWith('@') ? org : `@${org}`
+          if (this.state.orgs[normalizedOrg]) {
+            this.state.orgs[normalizedOrg].users[user] = role
+          }
+        }
+        break
+      }
+      case 'team:create': {
+        // Params: { scopeTeam } — TeamCreateParamsSchema
+        const scopeTeam = params['scopeTeam']
+        if (scopeTeam) {
+          const [scope, team] = scopeTeam.split(':')
+          if (scope && team) {
+            const normalizedScope = scope.startsWith('@') ? scope : `@${scope}`
+            if (!this.state.orgs[normalizedScope]) {
+              this.state.orgs[normalizedScope] = { users: {}, teams: [], teamMembers: {} }
+            }
+            if (!this.state.orgs[normalizedScope].teams.includes(team)) {
+              this.state.orgs[normalizedScope].teams.push(team)
+            }
+            this.state.orgs[normalizedScope].teamMembers[team] = []
+          }
+        }
+        break
+      }
+      case 'team:destroy': {
+        // Params: { scopeTeam } — TeamDestroyParamsSchema
+        const scopeTeam = params['scopeTeam']
+        if (scopeTeam) {
+          const [scope, team] = scopeTeam.split(':')
+          if (scope && team) {
+            const normalizedScope = scope.startsWith('@') ? scope : `@${scope}`
+            if (this.state.orgs[normalizedScope]) {
+              this.state.orgs[normalizedScope].teams = this.state.orgs[
+                normalizedScope
+              ].teams.filter(t => t !== team)
+              delete this.state.orgs[normalizedScope].teamMembers[team]
+            }
+          }
+        }
+        break
+      }
+      case 'team:add-user': {
+        // Params: { scopeTeam, user } — TeamAddUserParamsSchema
+        const scopeTeam = params['scopeTeam']
+        const user = params['user']
+        if (scopeTeam && user) {
+          const [scope, team] = scopeTeam.split(':')
+          if (scope && team) {
+            const normalizedScope = scope.startsWith('@') ? scope : `@${scope}`
+            if (this.state.orgs[normalizedScope]) {
+              const members = this.state.orgs[normalizedScope].teamMembers[team] ?? []
+              if (!members.includes(user)) {
+                members.push(user)
+              }
+              this.state.orgs[normalizedScope].teamMembers[team] = members
+            }
+          }
+        }
+        break
+      }
+      case 'team:rm-user': {
+        // Params: { scopeTeam, user } — TeamRemoveUserParamsSchema
+        const scopeTeam = params['scopeTeam']
+        const user = params['user']
+        if (scopeTeam && user) {
+          const [scope, team] = scopeTeam.split(':')
+          if (scope && team) {
+            const normalizedScope = scope.startsWith('@') ? scope : `@${scope}`
+            if (this.state.orgs[normalizedScope]) {
+              const members = this.state.orgs[normalizedScope].teamMembers[team]
+              if (members) {
+                this.state.orgs[normalizedScope].teamMembers[team] = members.filter(u => u !== user)
+              }
+            }
+          }
+        }
+        break
+      }
+      case 'access:grant': {
+        // Params: { permission, scopeTeam, pkg } — AccessGrantParamsSchema
+        const pkg = params['pkg']
+        const scopeTeam = params['scopeTeam']
+        const permission = (params['permission'] as AccessPermission) ?? 'read-write'
+        if (pkg && scopeTeam) {
+          if (!this.state.packages[pkg]) {
+            this.state.packages[pkg] = { collaborators: {} }
+          }
+          this.state.packages[pkg].collaborators[scopeTeam] = permission
+        }
+        break
+      }
+      case 'access:revoke': {
+        // Params: { scopeTeam, pkg } — AccessRevokeParamsSchema
+        const pkg = params['pkg']
+        const scopeTeam = params['scopeTeam']
+        if (pkg && scopeTeam && this.state.packages[pkg]) {
+          delete this.state.packages[pkg].collaborators[scopeTeam]
+        }
+        break
+      }
+      case 'owner:add': {
+        // Params: { user, pkg } — OwnerAddParamsSchema
+        const pkg = params['pkg']
+        const user = params['user']
+        if (pkg && user) {
+          if (!this.state.packages[pkg]) {
+            this.state.packages[pkg] = { collaborators: {} }
+          }
+          this.state.packages[pkg].collaborators[user] = 'read-write'
+        }
+        break
+      }
+      case 'owner:rm': {
+        // Params: { user, pkg } — OwnerRemoveParamsSchema
+        const pkg = params['pkg']
+        const user = params['user']
+        if (pkg && user && this.state.packages[pkg]) {
+          delete this.state.packages[pkg].collaborators[user]
+        }
+        break
+      }
+      case 'package:init': {
+        // Params: { name, author? } — PackageInitParamsSchema
+        const name = params['name']
+        if (name) {
+          this.state.packages[name] = {
+            collaborators: { [this.state.config.npmUser]: 'read-write' },
+          }
+          this.state.userPackages[name] = 'read-write'
+        }
+        break
+      }
+    }
+  }
+
+  /** Topological sort by dependsOn. */
+  private sortByDependencies(operations: PendingOperation[]): PendingOperation[] {
+    const result: PendingOperation[] = []
+    const visited = new Set<string>()
+
+    const visit = (op: PendingOperation) => {
+      if (visited.has(op.id)) return
+      visited.add(op.id)
+
+      if (op.dependsOn) {
+        const dep = operations.find(d => d.id === op.dependsOn)
+        if (dep) visit(dep)
+      }
+
+      result.push(op)
+    }
+
+    for (const op of operations) {
+      visit(op)
+    }
+
+    return result
+  }
+
+  reset(): void {
+    this.state.connected = false
+    this.state.connectedAt = null
+    this.state.orgs = {}
+    this.state.packages = {}
+    this.state.userPackages = {}
+    this.state.userOrgs = []
+    this.state.operations = []
+    this.state.operationIdCounter = 0
+  }
+}
+
+/** @internal */
+export const DEFAULT_MOCK_CONFIG: MockConnectorConfig = {
+  token: 'test-token-e2e-12345',
+  npmUser: 'testuser',
+  avatar: null,
+  port: 31415,
+}

cli/src/server.ts

···
 import type { CorsOptions } from 'h3-next'
 import * as v from 'valibot'
 
-import type { ConnectorState, PendingOperation, ApiResponse } from './types.ts'
+import type {
+  ConnectorState,
+  PendingOperation,
+  ApiResponse,
+  ConnectorEndpoints,
+  AssertEndpointsImplemented,
+} from './types.ts'
+
+// Endpoint completeness check — errors if this list diverges from ConnectorEndpoints.
+const _endpointCheck: AssertEndpointsImplemented<
+  | 'POST /connect'
+  | 'GET /state'
+  | 'POST /operations'
+  | 'POST /operations/batch'
+  | 'DELETE /operations'
+  | 'DELETE /operations/all'
+  | 'POST /approve'
+  | 'POST /approve-all'
+  | 'POST /retry'
+  | 'POST /execute'
+  | 'GET /org/:org/users'
+  | 'GET /org/:org/teams'
+  | 'GET /team/:scopeTeam/users'
+  | 'GET /package/:pkg/collaborators'
+  | 'GET /user/packages'
+  | 'GET /user/orgs'
+> = true
+void _endpointCheck
 import { logDebug, logError } from './logger.ts'
 import {
   getNpmUser,
···
         avatar,
         connectedAt: state.session.connectedAt,
       },
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /connect']['data']>
   })
 
   app.get('/state', event => {
···
         avatar: state.session.avatar,
         operations: state.operations,
       },
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['GET /state']['data']>
   })
 
   app.post('/operations', async event => {
···
     return {
       success: true,
       data: operation,
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /operations']['data']>
   })
 
   app.post('/operations/batch', async event => {
···
     return {
       success: true,
       data: created,
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /operations/batch']['data']>
   })
 
   app.post('/approve', event => {
···
     return {
       success: true,
       data: operation,
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /approve']['data']>
   })
 
   app.post('/approve-all', event => {
···
     return {
       success: true,
       data: { approved: pendingOps.length },
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /approve-all']['data']>
   })
 
   app.post('/retry', event => {
···
     return {
       success: true,
       data: operation,
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /retry']['data']>
   })
 
   app.post('/execute', async event => {
···
         otpRequired,
         authFailure,
       },
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['POST /execute']['data']>
   })
 
   app.delete('/operations', event => {
···
 
     state.operations.splice(index, 1)
 
-    return { success: true } as ApiResponse
+    return { success: true } satisfies ApiResponse<ConnectorEndpoints['DELETE /operations']['data']>
   })
 
   app.delete('/operations/all', event => {
···
     return {
       success: true,
       data: { removed },
-    } as ApiResponse
+    } satisfies ApiResponse<ConnectorEndpoints['DELETE /operations/all']['data']>
   })
 
   // List endpoints (read-only data fetching)
···
       return {
         success: true,
         data: users,
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /org/:org/users']['data']>
     } catch {
       return {
         success: false,
···
       return {
         success: true,
         data: teams,
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /org/:org/teams']['data']>
     } catch {
       return {
         success: false,
···
       return {
         success: true,
         data: users,
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /team/:scopeTeam/users']['data']>
     } catch {
       return {
         success: false,
···
       return {
         success: true,
         data: collaborators,
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /package/:pkg/collaborators']['data']>
     } catch {
       return {
         success: false,
···
       return {
         success: true,
         data: packages,
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /user/packages']['data']>
     } catch {
       return {
         success: false,
···
       return {
         success: true,
         data: Array.from(orgs).sort(),
-      } as ApiResponse
+      } satisfies ApiResponse<ConnectorEndpoints['GET /user/orgs']['data']>
     } catch {
       return {
         success: false,

cli/src/types.ts

···
   data?: T
   error?: string
 }
+
+// -- Connector API contract (shared by real + mock server) -------------------
+
+export type OrgRole = 'developer' | 'admin' | 'owner'
+
+export type AccessPermission = 'read-only' | 'read-write'
+
+/** POST /connect response data */
+export interface ConnectResponseData {
+  npmUser: string | null
+  avatar: string | null
+  connectedAt: number
+}
+
+/** GET /state response data */
+export interface StateResponseData {
+  npmUser: string | null
+  avatar: string | null
+  operations: PendingOperation[]
+}
+
+/** POST /execute response data */
+export interface ExecuteResponseData {
+  results: Array<{ id: string; result: OperationResult }>
+  otpRequired?: boolean
+  authFailure?: boolean
+}
+
+/** POST /approve-all response data */
+export interface ApproveAllResponseData {
+  approved: number
+}
+
+/** DELETE /operations/all response data */
+export interface ClearOperationsResponseData {
+  removed: number
+}
+
+/** Request body for POST /operations */
+export interface CreateOperationBody {
+  type: OperationType
+  params: Record<string, string>
+  description: string
+  command: string
+  dependsOn?: string
+}
+
+/**
+ * Connector API endpoint contract. Both server.ts and mock-app.ts must
+ * conform to these shapes, enforced via `satisfies` and `AssertEndpointsImplemented`.
+ */
+export interface ConnectorEndpoints {
+  'POST /connect': { body: { token: string }; data: ConnectResponseData }
+  'GET /state': { body: never; data: StateResponseData }
+  'POST /operations': { body: CreateOperationBody; data: PendingOperation }
+  'POST /operations/batch': { body: CreateOperationBody[]; data: PendingOperation[] }
+  'DELETE /operations': { body: never; data: void }
+  'DELETE /operations/all': { body: never; data: ClearOperationsResponseData }
+  'POST /approve': { body: never; data: PendingOperation }
+  'POST /approve-all': { body: never; data: ApproveAllResponseData }
+  'POST /retry': { body: never; data: PendingOperation }
+  'POST /execute': { body: { otp?: string }; data: ExecuteResponseData }
+  'GET /org/:org/users': { body: never; data: Record<string, OrgRole> }
+  'GET /org/:org/teams': { body: never; data: string[] }
+  'GET /team/:scopeTeam/users': { body: never; data: string[] }
+  'GET /package/:pkg/collaborators': { body: never; data: Record<string, AccessPermission> }
+  'GET /user/packages': { body: never; data: Record<string, AccessPermission> }
+  'GET /user/orgs': { body: never; data: string[] }
+}
+
+/** Compile-time check that a server implements exactly the ConnectorEndpoints keys. */
+type IsExact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+export type AssertEndpointsImplemented<Implemented extends string> =
+  IsExact<Implemented, keyof ConnectorEndpoints> extends true
+    ? true
+    : {
+        error: 'Endpoint mismatch'
+        missing: Exclude<keyof ConnectorEndpoints, Implemented>
+        extra: Exclude<Implemented, keyof ConnectorEndpoints>
+      }

cli/tsconfig.json

···
     "noEmit": true,
     "allowImportingTsExtensions": true,
     "declaration": true,
+    "types": ["node"],
     "declarationMap": true
   },
   "include": ["src/**/*.ts"],

knip.ts

···
         'uno-preset-rtl.ts!',
         'scripts/**/*.ts',
       ],
-      project: ['**/*.{ts,vue,cjs,mjs}', '!test/fixtures/**'],
+      project: [
+        '**/*.{ts,vue,cjs,mjs}',
+        '!test/fixtures/**',
+        '!test/test-utils/**',
+        '!test/e2e/helpers/**',
+        '!cli/src/**',
+      ],
       ignoreDependencies: [
         '@iconify-json/*',
         '@voidzero-dev/vite-plus-core',
···
         /** Oxlint plugins don't get picked up yet */
         '@e18e/eslint-plugin',
         'eslint-plugin-regexp',
+
+        /** Used in test/e2e/helpers/ which is excluded from knip project scope */
+        'h3-next',
       ],
       ignoreUnresolved: ['#components', '#oauth/config'],
     },
     'cli': {
-      project: ['src/**/*.ts!'],
+      project: ['src/**/*.ts!', '!src/mock-*.ts'],
     },
     'docs': {
       entry: ['app/**/*.{ts,vue}'],

nuxt.config.ts

···
       compilerOptions: {
         noUnusedLocals: true,
         allowImportingTsExtensions: true,
+        paths: {
+          '#cli/*': ['../cli/src/*'],
+        },
       },
       include: ['../test/unit/app/**/*.ts'],
     },
···
     nodeTsConfig: {
       compilerOptions: {
         allowImportingTsExtensions: true,
+        paths: {
+          '#cli/*': ['../cli/src/*'],
+          '#server/*': ['../server/*'],
+          '#shared/*': ['../shared/*'],
+        },
       },
-      include: ['../*.ts'],
+      include: ['../*.ts', '../test/e2e/**/*.ts'],
     },
   },
 

package.json

···
     "lint:css": "node scripts/unocss-checker.ts",
     "generate": "nuxt generate",
     "npmx-connector": "pnpm --filter npmx-connector dev",
+    "mock-connector": "pnpm --filter npmx-connector dev:mock",
     "generate-pwa-icons": "pwa-assets-generator",
     "preview": "nuxt preview",
     "postinstall": "pnpm rebuild @resvg/resvg-js && pnpm generate:lexicons && pnpm generate:sprite && nuxt prepare && simple-git-hooks",
···
     "eslint-plugin-regexp": "3.0.0",
     "fast-check": "4.5.3",
     "h3": "1.15.5",
+    "h3-next": "npm:h3@2.0.1-rc.11",
     "knip": "5.83.0",
     "lint-staged": "16.2.7",
     "oxfmt": "0.27.0",

playwright.config.ts

···
     reuseExistingServer: false,
     timeout: 60_000,
   },
+  // Start/stop mock connector server before/after all tests (teardown via returned closure)
+  globalSetup: fileURLToPath(new URL('./test/e2e/global-setup.ts', import.meta.url)),
   // We currently only test on one browser on one platform
   snapshotPathTemplate: '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{ext}',
   use: {

pnpm-lock.yaml

···
       h3:
         specifier: 1.15.5
         version: 1.15.5
+      h3-next:
+        specifier: npm:h3@2.0.1-rc.11
+        version: h3@2.0.1-rc.11
       knip:
         specifier: 5.83.0
         version: 5.83.0(@types/node@24.10.9)(typescript@5.9.3)

test/e2e/connector.spec.ts

···
+/**
+ * E2E tests for connector-authenticated features.
+ *
+ * These tests use a mock connector server (started in global setup)
+ * to test features that require being logged in via the connector.
+ *
+ * All tests run serially because they share a single mock connector server
+ * whose state is reset before each test via `mockConnector.reset()`.
+ */
+
+import type { Page } from '@playwright/test'
+import { test, expect } from './helpers/fixtures'
+
+test.describe.configure({ mode: 'serial' })
+
+/**
+ * When connected, the header shows "packages" and "orgs" links scoped to the user.
+ * This helper waits for the packages link to appear as proof of successful connection.
+ */
+async function expectConnected(page: Page, username = 'testuser') {
+  await expect(page.locator(`a[href="/~${username}"]`, { hasText: 'packages' })).toBeVisible({
+    timeout: 10_000,
+  })
+}
+
+/**
+ * Open the connector modal by clicking the account menu button, then clicking
+ * the npm CLI menu item inside the dropdown.
+ */
+async function openConnectorModal(page: Page) {
+  // The AccountMenu button has aria-haspopup="true"
+  await page.locator('button[aria-haspopup="true"]').click()
+
+  // In the dropdown menu, click the npm CLI item (menuitem containing ~testuser)
+  await page
+    .getByRole('menuitem')
+    .filter({ hasText: /~testuser/ })
+    .click()
+
+  // Wait for the dialog to appear
+  await expect(page.getByRole('dialog')).toBeVisible()
+}
+
+test.describe('Connector Connection', () => {
+  test('connects via URL params and shows connected state', async ({
+    page,
+    gotoConnected,
+    mockConnector,
+  }) => {
+    await mockConnector.setUserOrgs(['@testorg'])
+    await gotoConnected('/')
+
+    // Header should show "packages" link for the connected user
+    await expectConnected(page)
+  })
+
+  test('opens connector modal and shows connected user', async ({ page, gotoConnected }) => {
+    await gotoConnected('/')
+    await expectConnected(page)
+
+    await openConnectorModal(page)
+
+    // The modal should show the connected user
+    await expect(page.getByRole('dialog')).toContainText('testuser')
+  })
+
+  test('can disconnect from the connector', async ({ page, gotoConnected }) => {
+    await gotoConnected('/')
+    await expectConnected(page)
+
+    await openConnectorModal(page)
+
+    const modal = page.getByRole('dialog')
+
+    // Click disconnect button
+    await modal.getByRole('button', { name: /disconnect/i }).click()
+
+    // Close the modal
+    await modal.getByRole('button', { name: /close/i }).click()
+
+    // The "packages" link should disappear since we're disconnected
+    await expect(page.locator('a[href="/~testuser"]', { hasText: 'packages' })).not.toBeVisible({
+      timeout: 5000,
+    })
+
+    // The account menu button should now show "connect" text (the main button, not dropdown items)
+    await expect(page.getByRole('button', { name: 'connect', exact: true })).toBeVisible()
+  })
+})
+
+test.describe('Organization Management', () => {
+  test.beforeEach(async ({ mockConnector }) => {
+    await mockConnector.setOrgData('@testorg', {
+      users: {
+        testuser: 'owner',
+        member1: 'admin',
+        member2: 'developer',
+      },
+      teams: ['core', 'docs'],
+      teamMembers: {
+        core: ['testuser', 'member1'],
+        docs: ['member2'],
+      },
+    })
+    await mockConnector.setUserOrgs(['@testorg'])
+  })
+
+  test('shows org members when connected', async ({ page, gotoConnected }) => {
+    await gotoConnected('/@testorg')
+
+    // The org management region contains the members panel
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    // Should show the members list
+    const membersList = page.getByRole('list', { name: /organization members/i })
+    await expect(membersList).toBeVisible({ timeout: 10_000 })
+
+    // Members are shown as ~username links
+    await expect(membersList.getByRole('link', { name: '~testuser' })).toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~member1' })).toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~member2' })).toBeVisible()
+  })
+
+  test('can filter members by role', async ({ page, gotoConnected }) => {
+    await gotoConnected('/@testorg')
+
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    const membersList = page.getByRole('list', { name: /organization members/i })
+    await expect(membersList).toBeVisible({ timeout: 10_000 })
+
+    // Click the "admin" filter button (inside "Filter by role" group)
+    await orgManagement
+      .getByRole('group', { name: /filter by role/i })
+      .getByRole('button', { name: /admin/i })
+      .click()
+
+    // Should only show admin member
+    await expect(membersList.getByRole('link', { name: '~member1' })).toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~testuser' })).not.toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~member2' })).not.toBeVisible()
+  })
+
+  test('can search members by name', async ({ page, gotoConnected }) => {
+    await gotoConnected('/@testorg')
+
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    const membersList = page.getByRole('list', { name: /organization members/i })
+    await expect(membersList).toBeVisible({ timeout: 10_000 })
+
+    const searchInput = orgManagement.getByRole('searchbox', { name: /filter members/i })
+    await searchInput.fill('member1')
+
+    // Should only show matching member
+    await expect(membersList.getByRole('link', { name: '~member1' })).toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~testuser' })).not.toBeVisible()
+    await expect(membersList.getByRole('link', { name: '~member2' })).not.toBeVisible()
+  })
+
+  test('can add a new member operation', async ({ page, gotoConnected, mockConnector }) => {
+    await gotoConnected('/@testorg')
+
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    // Click "Add member" button
+    await orgManagement.getByRole('button', { name: /add member/i }).click()
+
+    // Wait for the add-member form to appear
+    const usernameInput = orgManagement.locator('#new-member-username')
+    await expect(usernameInput).toBeVisible({ timeout: 5000 })
+
+    // Fill in the form
+    await usernameInput.fill('newuser')
+
+    // Select role (SelectField renders id on the <select>, not name)
+    await orgManagement.locator('#new-member-role').selectOption('admin')
+
+    // Submit
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations') && resp.ok()),
+      orgManagement.getByRole('button', { name: /^add$/i }).click(),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(1)
+    expect(operations[0]?.type).toBe('org:add-user')
+    expect(operations[0]?.params.user).toBe('newuser')
+    expect(operations[0]?.params.role).toBe('admin')
+  })
+
+  test('can remove a member (adds operation)', async ({ page, gotoConnected, mockConnector }) => {
+    await gotoConnected('/@testorg')
+
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations') && resp.ok()),
+      orgManagement.getByRole('button', { name: /remove member2/i }).click(),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(1)
+    expect(operations[0]?.type).toBe('org:rm-user')
+    expect(operations[0]?.params.user).toBe('member2')
+  })
+
+  test('can change member role (adds operation)', async ({
+    page,
+    gotoConnected,
+    mockConnector,
+  }) => {
+    await gotoConnected('/@testorg')
+
+    const orgManagement = page.getByRole('region', { name: /organization management/i })
+    await expect(orgManagement).toBeVisible({ timeout: 10_000 })
+
+    const roleSelect = orgManagement.locator('#role-member2')
+    await expect(roleSelect).toBeVisible({ timeout: 5000 })
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations') && resp.ok()),
+      roleSelect.selectOption('admin'),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(1)
+    expect(operations[0]?.type).toBe('org:add-user')
+    expect(operations[0]?.params.user).toBe('member2')
+    expect(operations[0]?.params.role).toBe('admin')
+  })
+})
+
+test.describe('Package Access Controls', () => {
+  test.beforeEach(async ({ mockConnector }) => {
+    await mockConnector.setOrgData('@nuxt', {
+      users: { testuser: 'owner' },
+      teams: ['core', 'docs', 'triage'],
+    })
+    await mockConnector.setUserOrgs(['@nuxt'])
+    await mockConnector.setPackageData('@nuxt/kit', {
+      collaborators: {
+        'nuxt:core': 'read-write',
+        'nuxt:docs': 'read-only',
+      },
+    })
+  })
+
+  /**
+   * Helper: connect on home page then navigate to the package page.
+   * Verifies connection is established before navigating.
+   */
+  async function goToPackageConnected(page: Page, gotoConnected: (path: string) => Promise<void>) {
+    await gotoConnected('/')
+    await expectConnected(page)
+    await page.goto('/package/@nuxt/kit')
+    await expect(page.locator('h1')).toContainText('kit', { timeout: 30_000 })
+  }
+
+  test('shows team access section on scoped package when connected', async ({
+    page,
+    gotoConnected,
+  }) => {
+    await goToPackageConnected(page, gotoConnected)
+
+    await expect(accessSection(page)).toBeVisible({ timeout: 15_000 })
+    await expect(page.getByRole('heading', { name: /team access/i })).toBeVisible()
+  })
+
+  test('displays collaborators with correct permissions', async ({ page, gotoConnected }) => {
+    await goToPackageConnected(page, gotoConnected)
+
+    await expect(accessSection(page)).toBeVisible({ timeout: 15_000 })
+
+    const teamList = page.getByRole('list', { name: /team access list/i })
+    await expect(teamList).toBeVisible({ timeout: 10_000 })
+
+    await expect(teamList.getByText('core')).toBeVisible()
+    await expect(teamList.locator('span', { hasText: 'rw' })).toBeVisible()
+    await expect(teamList.getByText('docs')).toBeVisible()
+    await expect(teamList.locator('span', { hasText: 'ro' })).toBeVisible()
+  })
+
+  test('can grant team access (creates operation)', async ({
+    page,
+    gotoConnected,
+    mockConnector,
+  }) => {
+    await goToPackageConnected(page, gotoConnected)
+
+    const section = accessSection(page)
+    await expect(section).toBeVisible({ timeout: 15_000 })
+
+    await section.getByRole('button', { name: /grant team access/i }).click()
+
+    const teamSelect = section.locator('#grant-team-select')
+    await expect(teamSelect).toBeVisible()
+    await expect(teamSelect.locator('option')).toHaveCount(4, { timeout: 10_000 })
+    await teamSelect.selectOption({ label: 'nuxt:triage' })
+
+    await section.locator('#grant-permission-select').selectOption('read-write')
+
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations') && resp.ok()),
+      section.getByRole('button', { name: /^grant$/i }).click(),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(1)
+    expect(operations[0]?.type).toBe('access:grant')
+    expect(operations[0]?.params.scopeTeam).toBe('@nuxt:triage')
+    expect(operations[0]?.params.pkg).toBe('@nuxt/kit')
+    expect(operations[0]?.params.permission).toBe('read-write')
+  })
+
+  test('can revoke team access (creates operation)', async ({
+    page,
+    gotoConnected,
+    mockConnector,
+  }) => {
+    await goToPackageConnected(page, gotoConnected)
+
+    const section = accessSection(page)
+    await expect(section).toBeVisible({ timeout: 15_000 })
+
+    const teamList = page.getByRole('list', { name: /team access list/i })
+    await expect(teamList).toBeVisible({ timeout: 10_000 })
+
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations') && resp.ok()),
+      section.getByRole('button', { name: /revoke docs access/i }).click(),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(1)
+    expect(operations[0]?.type).toBe('access:revoke')
+    expect(operations[0]?.params.scopeTeam).toBe('nuxt:docs')
+    expect(operations[0]?.params.pkg).toBe('@nuxt/kit')
+  })
+
+  test('can cancel grant access form', async ({ page, gotoConnected }) => {
+    await goToPackageConnected(page, gotoConnected)
+
+    const section = accessSection(page)
+    await expect(section).toBeVisible({ timeout: 15_000 })
+
+    await section.getByRole('button', { name: /grant team access/i }).click()
+    const teamSelect = section.locator('#grant-team-select')
+    await expect(teamSelect).toBeVisible()
+
+    await section.getByRole('button', { name: /cancel granting access/i }).click()
+    await expect(teamSelect).not.toBeVisible()
+    await expect(section.getByRole('button', { name: /grant team access/i })).toBeVisible()
+  })
+})
+
+test.describe('Operations Queue', () => {
+  test('shows operations in connector modal', async ({ page, gotoConnected, mockConnector }) => {
+    await mockConnector.addOperation({
+      type: 'org:add-user',
+      params: { org: '@testorg', user: 'newuser', role: 'developer' },
+      description: 'Add @newuser to @testorg as developer',
+      command: 'npm org set @testorg newuser developer',
+    })
+    await mockConnector.addOperation({
+      type: 'org:rm-user',
+      params: { org: '@testorg', user: 'olduser' },
+      description: 'Remove @olduser from @testorg',
+      command: 'npm org rm @testorg olduser',
+    })
+
+    await gotoConnected('/')
+    await expectConnected(page)
+
+    await openConnectorModal(page)
+
+    const modal = page.getByRole('dialog')
+    await expect(modal).toContainText('Add @newuser')
+    await expect(modal).toContainText('Remove @olduser')
+  })
+
+  test('can approve and execute operations', async ({ page, gotoConnected, mockConnector }) => {
+    await mockConnector.addOperation({
+      type: 'org:add-user',
+      params: { org: '@testorg', user: 'newuser', role: 'developer' },
+      description: 'Add @newuser to @testorg',
+      command: 'npm org set @testorg newuser developer',
+    })
+
+    await gotoConnected('/')
+    await expectConnected(page)
+
+    await openConnectorModal(page)
+
+    const modal = page.getByRole('dialog')
+
+    // Approve all
+    const approveAllBtn = modal.getByRole('button', { name: /approve all/i })
+    await expect(approveAllBtn).toBeVisible({ timeout: 5000 })
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/approve-all') && resp.ok()),
+      approveAllBtn.click(),
+    ])
+
+    let operations = await mockConnector.getOperations()
+    expect(operations[0]?.status).toBe('approved')
+
+    // Execute
+    const executeBtn = modal.getByRole('button', { name: /execute/i })
+    await expect(executeBtn).toBeVisible({ timeout: 5000 })
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/execute') && resp.ok()),
+      executeBtn.click(),
+    ])
+
+    operations = await mockConnector.getOperations()
+    expect(operations[0]?.status).toBe('completed')
+  })
+
+  test('can clear pending operations', async ({ page, gotoConnected, mockConnector }) => {
+    await mockConnector.addOperation({
+      type: 'org:add-user',
+      params: { org: '@testorg', user: 'newuser', role: 'developer' },
+      description: 'Add @newuser to @testorg',
+      command: 'npm org set @testorg newuser developer',
+    })
+
+    await gotoConnected('/')
+    await expectConnected(page)
+
+    await openConnectorModal(page)
+
+    const modal = page.getByRole('dialog')
+    await Promise.all([
+      page.waitForResponse(resp => resp.url().includes('/operations/all') && resp.ok()),
+      modal.getByRole('button', { name: /clear/i }).click(),
+    ])
+
+    const operations = await mockConnector.getOperations()
+    expect(operations).toHaveLength(0)
+  })
+})
+
+/** The access section is identified by the "Team Access" heading */
+function accessSection(page: Page) {
+  return page.locator('section:has(#access-heading)')
+}

test/e2e/global-setup.ts

···
+/**
+ * Playwright global setup - starts the mock connector server before all tests.
+ *
+ * Returns an async teardown function (Playwright's recommended pattern for
+ * sharing state between setup and teardown via closure).
+ */
+
+// eslint-disable no-console
+
+import { MockConnectorServer, DEFAULT_MOCK_CONFIG } from './helpers/mock-connector'
+
+export default async function globalSetup() {
+  console.log('[Global Setup] Starting mock connector server...')
+
+  const mockServer = new MockConnectorServer(DEFAULT_MOCK_CONFIG)
+
+  try {
+    await mockServer.start()
+    console.log(`[Global Setup] Mock connector ready at http://127.0.0.1:${mockServer.port}`)
+    console.log(`[Global Setup] Test token: ${mockServer.token}`)
+  } catch (error) {
+    console.error('[Global Setup] Failed to start mock connector:', error)
+    throw error
+  }
+
+  // Return teardown function — Playwright calls this after all tests complete
+  return async () => {
+    console.log('[Global Teardown] Stopping mock connector server...')
+    try {
+      await mockServer.stop()
+    } catch (error) {
+      console.error('[Global Teardown] Error stopping mock connector:', error)
+    }
+  }
+}

test/e2e/helpers/fixtures.ts

···
+/**
+ * Playwright fixtures for connector E2E tests. Extends test-utils.ts
+ * (which includes external API mocking) with connector-specific helpers.
+ */
+
+import { test as base } from '../test-utils'
+import { DEFAULT_MOCK_CONFIG } from './mock-connector'
+
+const TEST_TOKEN = DEFAULT_MOCK_CONFIG.token
+const TEST_PORT = DEFAULT_MOCK_CONFIG.port ?? 31415
+
+/**
+ * Helper to make requests to the mock connector server.
+ * This allows tests to set up state before running.
+ */
+export class MockConnectorClient {
+  private token: string
+  private baseUrl: string
+
+  constructor(token: string, port: number) {
+    this.token = token
+    this.baseUrl = `http://127.0.0.1:${port}`
+  }
+
+  private async request<T>(path: string, options?: RequestInit): Promise<T> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.token}`,
+        ...options?.headers,
+      },
+    })
+    if (!response.ok) {
+      throw new Error(
+        `Mock connector request failed: ${response.status} ${response.statusText} (${path})`,
+      )
+    }
+    return response.json() as Promise<T>
+  }
+
+  private async testEndpoint(path: string, body: unknown): Promise<void> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (!response.ok) {
+      throw new Error(
+        `Mock connector test endpoint failed: ${response.status} ${response.statusText} (${path})`,
+      )
+    }
+  }
+
+  async reset(): Promise<void> {
+    await this.testEndpoint('/__test__/reset', {})
+    await this.testEndpoint('/connect', { token: this.token })
+  }
+
+  async setOrgData(
+    org: string,
+    data: {
+      users?: Record<string, 'developer' | 'admin' | 'owner'>
+      teams?: string[]
+      teamMembers?: Record<string, string[]>
+    },
+  ): Promise<void> {
+    await this.testEndpoint('/__test__/org', { org, ...data })
+  }
+
+  async setUserOrgs(orgs: string[]): Promise<void> {
+    await this.testEndpoint('/__test__/user-orgs', { orgs })
+  }
+
+  async setUserPackages(packages: Record<string, 'read-only' | 'read-write'>): Promise<void> {
+    await this.testEndpoint('/__test__/user-packages', { packages })
+  }
+
+  async setPackageData(
+    pkg: string,
+    data: { collaborators?: Record<string, 'read-only' | 'read-write'> },
+  ): Promise<void> {
+    await this.testEndpoint('/__test__/package', { package: pkg, ...data })
+  }
+
+  async addOperation(operation: {
+    type: string
+    params: Record<string, string>
+    description: string
+    command: string
+    dependsOn?: string
+  }): Promise<{ id: string; status: string }> {
+    const result = await this.request<{ success: boolean; data: { id: string; status: string } }>(
+      '/operations',
+      {
+        method: 'POST',
+        body: JSON.stringify(operation),
+      },
+    )
+    return result.data
+  }
+
+  async getOperations(): Promise<
+    Array<{ id: string; type: string; status: string; params: Record<string, string> }>
+  > {
+    const result = await this.request<{
+      success: boolean
+      data: {
+        operations: Array<{
+          id: string
+          type: string
+          status: string
+          params: Record<string, string>
+        }>
+      }
+    }>('/state')
+    return result.data.operations
+  }
+}
+
+export interface ConnectorFixtures {
+  mockConnector: MockConnectorClient
+  testToken: string
+  connectorPort: number
+  /** Navigate to a page pre-authenticated with connector credentials. */
+  gotoConnected: (path: string) => Promise<void>
+}
+
+export const test = base.extend<ConnectorFixtures>({
+  mockConnector: async ({ page: _ }, use) => {
+    const client = new MockConnectorClient(TEST_TOKEN, TEST_PORT)
+    await client.reset()
+    await use(client)
+  },
+
+  testToken: TEST_TOKEN,
+
+  connectorPort: TEST_PORT,
+
+  gotoConnected: async ({ goto, testToken, connectorPort }, use) => {
+    const navigateConnected = async (path: string) => {
+      const cleanPath = path.startsWith('/') ? path : `/${path}`
+      const separator = cleanPath.includes('?') ? '&' : '?'
+      const urlWithParams = `${cleanPath}${separator}token=${testToken}&port=${connectorPort}`
+      await goto(urlWithParams, { waitUntil: 'networkidle' })
+    }
+    await use(navigateConnected)
+  },
+})
+
+export { expect } from '@nuxt/test-utils/playwright'

test/e2e/helpers/mock-connector-state.ts

···
+/** Singleton state management for E2E tests. */
+
+import {
+  MockConnectorStateManager,
+  createMockConnectorState,
+  DEFAULT_MOCK_CONFIG,
+  type MockConnectorConfig,
+} from '../../../cli/src/mock-state.ts'
+
+export { MockConnectorStateManager, createMockConnectorState, DEFAULT_MOCK_CONFIG }
+export type { MockConnectorConfig }
+
+let globalStateManager: MockConnectorStateManager | null = null
+
+export function initGlobalMockState(config: MockConnectorConfig): MockConnectorStateManager {
+  globalStateManager = new MockConnectorStateManager(createMockConnectorState(config))
+  return globalStateManager
+}
+
+export function getGlobalMockState(): MockConnectorStateManager {
+  if (!globalStateManager) {
+    throw new Error('Mock connector state not initialized. Call initGlobalMockState() first.')
+  }
+  return globalStateManager
+}
+
+export function resetGlobalMockState(): void {
+  globalStateManager?.reset()
+}

test/e2e/helpers/mock-connector.ts

···
+/**
+ * E2E mock connector server. Wraps the base server from cli/src/mock-app.ts
+ * with global singleton state for Playwright test isolation.
+ */
+
+import { MockConnectorServer as BaseMockConnectorServer } from '../../../cli/src/mock-app.ts'
+import { type MockConnectorConfig, initGlobalMockState } from './mock-connector-state'
+
+export class MockConnectorServer {
+  private baseServer: BaseMockConnectorServer
+
+  constructor(config: MockConnectorConfig) {
+    const stateManager = initGlobalMockState(config)
+    this.baseServer = new BaseMockConnectorServer(stateManager)
+  }
+
+  async start(): Promise<void> {
+    return this.baseServer.start()
+  }
+
+  async stop(): Promise<void> {
+    return this.baseServer.stop()
+  }
+
+  get state() {
+    return this.baseServer.state
+  }
+
+  get port(): number {
+    return this.baseServer.port
+  }
+
+  get token(): string {
+    return this.baseServer.token
+  }
+
+  reset(): void {
+    this.baseServer.reset()
+  }
+}
+
+export {
+  getGlobalMockState,
+  resetGlobalMockState,
+  DEFAULT_MOCK_CONFIG,
+} from './mock-connector-state'

test/fixtures/npm-registry/orgs/testorg.json

···
+{
+  "@testorg/package-a": "write",
+  "@testorg/package-b": "write"
+}

test/nuxt/components/HeaderConnectorModal.spec.ts

···
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import { ref, computed, readonly, nextTick } from 'vue'
+import type { VueWrapper } from '@vue/test-utils'
+import type { PendingOperation } from '../../../cli/src/types'
+import { HeaderConnectorModal } from '#components'
+
+// Mock state that will be controlled by tests
+const mockState = ref({
+  connected: false,
+  connecting: false,
+  npmUser: null as string | null,
+  avatar: null as string | null,
+  operations: [] as PendingOperation[],
+  error: null as string | null,
+  lastExecutionTime: null as number | null,
+})
+
+// Create the mock composable function
+function createMockUseConnector() {
+  return {
+    state: readonly(mockState),
+    isConnected: computed(() => mockState.value.connected),
+    isConnecting: computed(() => mockState.value.connecting),
+    npmUser: computed(() => mockState.value.npmUser),
+    avatar: computed(() => mockState.value.avatar),
+    error: computed(() => mockState.value.error),
+    lastExecutionTime: computed(() => mockState.value.lastExecutionTime),
+    operations: computed(() => mockState.value.operations),
+    pendingOperations: computed(() =>
+      mockState.value.operations.filter(op => op.status === 'pending'),
+    ),
+    approvedOperations: computed(() =>
+      mockState.value.operations.filter(op => op.status === 'approved'),
+    ),
+    completedOperations: computed(() =>
+      mockState.value.operations.filter(
+        op => op.status === 'completed' || (op.status === 'failed' && !op.result?.requiresOtp),
+      ),
+    ),
+    activeOperations: computed(() =>
+      mockState.value.operations.filter(
+        op =>
+          op.status === 'pending' ||
+          op.status === 'approved' ||
+          op.status === 'running' ||
+          (op.status === 'failed' && op.result?.requiresOtp),
+      ),
+    ),
+    hasOperations: computed(() => mockState.value.operations.length > 0),
+    hasPendingOperations: computed(() =>
+      mockState.value.operations.some(op => op.status === 'pending'),
+    ),
+    hasApprovedOperations: computed(() =>
+      mockState.value.operations.some(op => op.status === 'approved'),
+    ),
+    hasActiveOperations: computed(() =>
+      mockState.value.operations.some(
+        op =>
+          op.status === 'pending' ||
+          op.status === 'approved' ||
+          op.status === 'running' ||
+          (op.status === 'failed' && op.result?.requiresOtp),
+      ),
+    ),
+    hasCompletedOperations: computed(() =>
+      mockState.value.operations.some(
+        op => op.status === 'completed' || (op.status === 'failed' && !op.result?.requiresOtp),
+      ),
+    ),
+    connect: vi.fn().mockResolvedValue(true),
+    reconnect: vi.fn().mockResolvedValue(true),
+    disconnect: vi.fn(),
+    refreshState: vi.fn().mockResolvedValue(undefined),
+    addOperation: vi.fn().mockResolvedValue(null),
+    addOperations: vi.fn().mockResolvedValue([]),
+    removeOperation: vi.fn().mockResolvedValue(true),
+    clearOperations: vi.fn().mockResolvedValue(0),
+    approveOperation: vi.fn().mockResolvedValue(true),
+    retryOperation: vi.fn().mockResolvedValue(true),
+    approveAll: vi.fn().mockResolvedValue(0),
+    executeOperations: vi.fn().mockResolvedValue({ success: true }),
+    listOrgUsers: vi.fn().mockResolvedValue(null),
+    listOrgTeams: vi.fn().mockResolvedValue(null),
+    listTeamUsers: vi.fn().mockResolvedValue(null),
+    listPackageCollaborators: vi.fn().mockResolvedValue(null),
+    listUserPackages: vi.fn().mockResolvedValue(null),
+    listUserOrgs: vi.fn().mockResolvedValue(null),
+  }
+}
+
+function resetMockState() {
+  mockState.value = {
+    connected: false,
+    connecting: false,
+    npmUser: null,
+    avatar: null,
+    operations: [],
+    error: null,
+    lastExecutionTime: null,
+  }
+}
+
+function simulateConnect() {
+  mockState.value.connected = true
+  mockState.value.npmUser = 'testuser'
+  mockState.value.avatar = 'https://example.com/avatar.png'
+}
+
+// Mock the composables at module level (vi.mock is hoisted)
+vi.mock('~/composables/useConnector', () => ({
+  useConnector: createMockUseConnector,
+}))
+
+vi.mock('~/composables/useSelectedPackageManager', () => ({
+  useSelectedPackageManager: () => ref('npm'),
+}))
+
+vi.mock('~/utils/npm', () => ({
+  getExecuteCommand: () => 'npx npmx-connector',
+}))
+
+// Mock clipboard
+const mockWriteText = vi.fn().mockResolvedValue(undefined)
+vi.stubGlobal('navigator', {
+  ...navigator,
+  clipboard: {
+    writeText: mockWriteText,
+    readText: vi.fn().mockResolvedValue(''),
+  },
+})
+
+// Track current wrapper for cleanup
+let currentWrapper: VueWrapper | null = null
+
+/**
+ * Get the modal dialog element from the document body (where Teleport sends it).
+ */
+function getModalDialog(): HTMLDialogElement | null {
+  return document.body.querySelector('dialog#connector-modal')
+}
+
+/**
+ * Mount the component and open the dialog via showModal().
+ */
+async function mountAndOpen(state?: 'connected' | 'error') {
+  if (state === 'connected') simulateConnect()
+  if (state === 'error') {
+    mockState.value.error = 'Could not reach connector. Is it running?'
+  }
+
+  currentWrapper = await mountSuspended(HeaderConnectorModal, {
+    attachTo: document.body,
+  })
+  await nextTick()
+
+  const dialog = getModalDialog()
+  dialog?.showModal()
+  await nextTick()
+
+  return dialog
+}
+
+// Reset state before each test
+beforeEach(() => {
+  resetMockState()
+  mockWriteText.mockClear()
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+  if (currentWrapper) {
+    currentWrapper.unmount()
+    currentWrapper = null
+  }
+})
+
+describe('HeaderConnectorModal', () => {
+  describe('Disconnected state', () => {
+    it('shows connection form when not connected', async () => {
+      const dialog = await mountAndOpen()
+      expect(dialog).not.toBeNull()
+
+      // Should show the form (disconnected state)
+      const form = dialog?.querySelector('form')
+      expect(form).not.toBeNull()
+
+      // Should show token input
+      const tokenInput = dialog?.querySelector('input[name="connector-token"]')
+      expect(tokenInput).not.toBeNull()
+
+      // Should show connect button
+      const connectButton = dialog?.querySelector('button[type="submit"]')
+      expect(connectButton).not.toBeNull()
+    })
+
+    it('shows the CLI command to run', async () => {
+      const dialog = await mountAndOpen()
+      // The command is now "pnpm npmx-connector"
+      expect(dialog?.textContent).toContain('npmx-connector')
+    })
+
+    it('has a copy button for the command', async () => {
+      const dialog = await mountAndOpen()
+      // The copy button is inside the command block (dir="ltr" div)
+      const commandBlock = dialog?.querySelector('div[dir="ltr"]')
+      const copyBtn = commandBlock?.querySelector('button') as HTMLButtonElement
+      expect(copyBtn).toBeTruthy()
+      // The button should have a copy-related aria-label
+      expect(copyBtn?.getAttribute('aria-label')).toBeTruthy()
+    })
+
+    it('disables connect button when token is empty', async () => {
+      const dialog = await mountAndOpen()
+      const connectButton = dialog?.querySelector('button[type="submit"]') as HTMLButtonElement
+      expect(connectButton?.disabled).toBe(true)
+    })
+
+    it('enables connect button when token is entered', async () => {
+      const dialog = await mountAndOpen()
+      const tokenInput = dialog?.querySelector('input[name="connector-token"]') as HTMLInputElement
+      expect(tokenInput).not.toBeNull()
+
+      // Set value and dispatch input event to trigger v-model
+      tokenInput.value = 'my-test-token'
+      tokenInput.dispatchEvent(new Event('input', { bubbles: true }))
+      await nextTick()
+
+      const connectButton = dialog?.querySelector('button[type="submit"]') as HTMLButtonElement
+      expect(connectButton?.disabled).toBe(false)
+    })
+
+    it('shows error message when connection fails', async () => {
+      const dialog = await mountAndOpen('error')
+      // Error needs hasAttemptedConnect=true to show. Simulate a connect attempt first.
+      const tokenInput = dialog?.querySelector('input[name="connector-token"]') as HTMLInputElement
+      tokenInput.value = 'bad-token'
+      tokenInput.dispatchEvent(new Event('input', { bubbles: true }))
+      await nextTick()
+
+      const form = dialog?.querySelector('form')
+      form?.dispatchEvent(new Event('submit', { bubbles: true }))
+      await nextTick()
+
+      const alerts = dialog?.querySelectorAll('[role="alert"]')
+      const errorAlert = Array.from(alerts || []).find(el =>
+        el.textContent?.includes('Could not reach connector'),
+      )
+      expect(errorAlert).not.toBeUndefined()
+    })
+  })
+
+  describe('Connected state', () => {
+    it('shows connected status', async () => {
+      const dialog = await mountAndOpen('connected')
+      expect(dialog?.textContent).toContain('Connected')
+    })
+
+    it('shows logged in username', async () => {
+      const dialog = await mountAndOpen('connected')
+      expect(dialog?.textContent).toContain('testuser')
+    })
+
+    it('shows disconnect button', async () => {
+      const dialog = await mountAndOpen('connected')
+      const buttons = dialog?.querySelectorAll('button')
+      const disconnectBtn = Array.from(buttons || []).find(b =>
+        b.textContent?.toLowerCase().includes('disconnect'),
+      )
+      expect(disconnectBtn).not.toBeUndefined()
+    })
+
+    it('hides connection form when connected', async () => {
+      const dialog = await mountAndOpen('connected')
+      const form = dialog?.querySelector('form')
+      expect(form).toBeNull()
+    })
+  })
+
+  describe('Modal behavior', () => {
+    it('closes modal when close button is clicked', async () => {
+      const dialog = await mountAndOpen()
+
+      // Find the close button (ButtonBase with close icon) in the dialog header
+      const closeBtn = Array.from(dialog?.querySelectorAll('button') ?? []).find(
+        b =>
+          b.querySelector('[class*="close"]') ||
+          b.getAttribute('aria-label')?.toLowerCase().includes('close'),
+      ) as HTMLButtonElement
+      expect(closeBtn).toBeTruthy()
+
+      closeBtn?.click()
+      await nextTick()
+
+      // Dialog should be closed (open attribute removed)
+      expect(dialog?.open).toBe(false)
+    })
+
+    it('does not render dialog content when not opened', async () => {
+      currentWrapper = await mountSuspended(HeaderConnectorModal, {
+        attachTo: document.body,
+      })
+      await nextTick()
+
+      const dialog = getModalDialog()
+      // Dialog exists in DOM but should not be open
+      expect(dialog?.open).toBeFalsy()
+    })
+  })
+})