Merge remote-tracking branch 'origin/main' into feat/npmx-connector-allow-web-auth

Author: danielroe

.github/workflows/mirror-tangled.yml

@@ -13,6 +13,7 @@ permissions:
 jobs:
   mirror:
     name: 🕸️ Mirror to Tangled
+    if: ${{ github.repository == 'npmx-dev/npmx.dev' }}
     runs-on: ubuntu-24.04-arm
 
     steps:

.gitignore

@@ -39,6 +39,7 @@ test-results/
 
 # generated files
 shared/types/lexicons
+file-tree-sprite.svg
 
 **/__screenshots__/**
 

.oxfmtignore

@@ -33,6 +33,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [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)
@@ -104,6 +105,10 @@ pnpm dev              # Start development server
 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
@@ -157,6 +162,36 @@ pnpm npmx-connector
 
 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
 
 When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes.
@@ -752,6 +787,74 @@ You need to either:
 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
 
 ### Before submitting

CONTRIBUTING.md

@@ -116,7 +116,7 @@ npmx.dev supports npm permalinks – just replace `npmjs.com` with `npmx.dev
 | `npmjs.com/org/nuxt`            | [`npmx.dev/org/nuxt`](https://npmx.dev/org/nuxt)                       |
 
 > [!TIP]
-> Want automatic redirects? Try the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) (Chrome only for now).
+> Want automatic redirects? Try the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) (Chrome only for now) or the separate [npmx-redirect extension](https://github.com/iaverages/npmx-redirect) for [Chrome](https://chromewebstore.google.com/detail/lbhjgfgpnlihfmobnohoipeljollhlnb) / [Firefox](https://addons.mozilla.org/en-GB/firefox/addon/npmx-redirect/).
 
 #### Not yet supported
 
@@ -159,6 +159,7 @@ We welcome contributions – please do feel free to explore the project and
 - [nxjt](https://nxjt.netlify.app) – npmx Jump To: Quickly navigate to npmx common webpages.
 - [npmx-weekly](https://npmx-weekly.trueberryless.org/) – A weekly newsletter for the npmx ecosystem. Add your own content via suggestions in the weekly PR on [GitHub](https://github.com/trueberryless-org/npmx-weekly/pulls?q=is%3Aopen+is%3Apr+label%3A%22%F0%9F%95%94+weekly+post%22).
 - [npmx-digest](https://npmx-digest.trueberryless.org/) – An automated news aggregation website that summarizes npmx activity from GitHub and Bluesky every 8 hours.
+- [npmx-redirect](https://github.com/iaverages/npmx-redirect) – Browser extension that automatically redirects npmjs.com URLs to npmx.dev.
 
 If you're building something cool, let us know! 🙏
 

README.md

@@ -180,7 +180,7 @@ onKeyStroke(
     for (const link of desktopLinks.value) {
       if (link.to && link.keyshortcut && isKeyWithoutModifiers(e, link.keyshortcut)) {
         e.preventDefault()
-        navigateTo(link.to.name)
+        navigateTo(link.to)
         break
       }
     }

app/components/AppHeader.vue

@@ -1,14 +1,14 @@
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
 import type { RouteLocationRaw } from 'vue-router'
-import { getFileIcon } from '~/utils/file-icons'
+import type { RouteNamedMap } from 'vue-router/auto-routes'
+import { ADDITIONAL_ICONS, getFileIcon } from '~/utils/file-icons'
 
 const props = defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
-  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
-  basePath: string[]
+  baseRoute: Pick<RouteNamedMap['code'], 'params'>
 }>()
 
 // Get the current directory's contents
@@ -41,13 +41,14 @@ const parentPath = computed(() => {
 
 // Build route object for a path
 function getCodeRoute(nodePath?: string): RouteLocationRaw {
-  if (!nodePath) {
-    return { name: 'code', params: { path: props.basePath as [string, ...string[]] } }
-  }
-  const pathSegments = [...props.basePath, ...nodePath.split('/')]
   return {
     name: 'code',
-    params: { path: pathSegments as [string, ...string[]] },
+    params: {
+      org: props.baseRoute.params.org,
+      packageName: props.baseRoute.params.packageName,
+      version: props.baseRoute.params.version,
+      filePath: nodePath ?? '',
+    },
   }
 }
 
@@ -80,8 +81,15 @@ const bytesFormatter = useBytesFormatter()
               :to="getCodeRoute(parentPath || undefined)"
               class="py-2 px-4 font-mono text-sm w-full"
               no-underline
-              classicon="i-carbon:folder text-yellow-600"
             >
+              <svg
+                class="size-[1em] me-1 shrink-0 text-yellow-600"
+                viewBox="0 0 16 16"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <use :href="`/file-tree-sprite.svg#${ADDITIONAL_ICONS['folder']}`" />
+              </svg>
               <span class="w-full flex justify-self-stretch items-center gap-2"> .. </span>
             </LinkBase>
           </td>
@@ -98,12 +106,18 @@ const bytesFormatter = useBytesFormatter()
               :to="getCodeRoute(node.path)"
               class="py-2 px-4 font-mono text-sm w-full"
               no-underline
-              :classicon="
-                node.type === 'directory'
-                  ? 'i-carbon:folder text-yellow-600'
-                  : getFileIcon(node.name)
-              "
             >
+              <svg
+                class="size-[1em] me-1 shrink-0"
+                viewBox="0 0 16 16"
+                fill="currentColor"
+                :class="node.type === 'directory' ? 'text-yellow-600' : undefined"
+                aria-hidden="true"
+              >
+                <use
+                  :href="`/file-tree-sprite.svg#${node.type === 'directory' ? ADDITIONAL_ICONS['folder'] : getFileIcon(node.name)}`"
+                />
+              </svg>
               <span class="w-full flex justify-self-stretch items-center gap-2">
                 <span class="flex-1">{{ node.name }}</span>
                 <span

app/components/Code/DirectoryListing.vue

@@ -1,14 +1,14 @@
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
 import type { RouteLocationRaw } from 'vue-router'
-import { getFileIcon } from '~/utils/file-icons'
+import type { RouteNamedMap } from 'vue-router/auto-routes'
+import { ADDITIONAL_ICONS, getFileIcon } from '~/utils/file-icons'
 
 const props = defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
-  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
-  basePath: string[]
+  baseRoute: Pick<RouteNamedMap['code'], 'params'>
   depth?: number
 }>()
 
@@ -23,10 +23,14 @@ function isNodeActive(node: PackageFileTree): boolean {
 
 // Build route object for a file path
 function getFileRoute(nodePath: string): RouteLocationRaw {
-  const pathSegments = [...props.basePath, ...nodePath.split('/')]
   return {
     name: 'code',
-    params: { path: pathSegments as [string, ...string[]] },
+    params: {
+      org: props.baseRoute.params.org,
+      packageName: props.baseRoute.params.packageName,
+      version: props.baseRoute.params.version,
+      filePath: nodePath ?? '',
+    },
   }
 }
 
@@ -57,22 +61,25 @@ watch(
           @click="toggleDir(node.path)"
           :classicon="isExpanded(node.path) ? 'i-carbon:chevron-down' : 'i-carbon:chevron-right'"
         >
-          <span
-            class="w-4 h-4 shrink-0"
-            :class="
-              isExpanded(node.path)
-                ? 'i-carbon:folder-open text-yellow-500'
-                : 'i-carbon:folder text-yellow-600'
-            "
-          />
+          <svg
+            class="size-[1em] me-1 shrink-0"
+            :class="isExpanded(node.path) ? 'text-yellow-500' : 'text-yellow-600'"
+            viewBox="0 0 16 16"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <use
+              :href="`/file-tree-sprite.svg#${isExpanded(node.path) ? ADDITIONAL_ICONS['folder-open'] : ADDITIONAL_ICONS['folder']}`"
+            />
+          </svg>
           <span class="truncate">{{ node.name }}</span>
         </ButtonBase>
         <CodeFileTree
           v-if="isExpanded(node.path) && node.children"
           :tree="node.children"
           :current-path="currentPath"
           :base-url="baseUrl"
-          :base-path="basePath"
+          :base-route="baseRoute"
           :depth="depth + 1"
         />
       </template>
@@ -86,8 +93,15 @@ watch(
           class="w-full justify-start! rounded-none! border-none!"
           block
           :style="{ paddingLeft: `${depth * 12 + 32}px` }"
-          :classicon="getFileIcon(node.name)"
         >
+          <svg
+            class="size-[1em] me-1 shrink-0"
+            viewBox="0 0 16 16"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <use :href="`/file-tree-sprite.svg#${getFileIcon(node.name)}`" />
+          </svg>
           <span class="truncate">{{ node.name }}</span>
         </LinkBase>
       </template>

app/components/Code/FileTree.vue

@@ -1,12 +1,12 @@
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
+import type { RouteNamedMap } from 'vue-router/auto-routes'
 
 defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
-  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
-  basePath: string[]
+  baseRoute: Pick<RouteNamedMap['code'], 'params'>
 }>()
 
 const isOpen = shallowRef(false)
@@ -75,7 +75,7 @@ watch(isOpen, open => (isLocked.value = open))
         :tree="tree"
         :current-path="currentPath"
         :base-url="baseUrl"
-        :base-path="basePath"
+        :base-route="baseRoute"
       />
     </aside>
   </Transition>

app/components/Code/MobileTreeDrawer.vue

@@ -26,7 +26,7 @@ onPrehydrate(() => {
   const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
   const collapsed: string[] = settings?.sidebar?.collapsed || []
   for (const id of collapsed) {
-    if (!document.documentElement.dataset.collapsed?.includes(id)) {
+    if (!document.documentElement.dataset.collapsed?.split(' ').includes(id)) {
       document.documentElement.dataset.collapsed = (
         document.documentElement.dataset.collapsed +
         ' ' +
@@ -38,7 +38,9 @@ onPrehydrate(() => {
 
 onMounted(() => {
   if (document?.documentElement) {
-    isOpen.value = !(document.documentElement.dataset.collapsed?.includes(props.id) ?? false)
+    isOpen.value = !(
+      document.documentElement.dataset.collapsed?.split(' ').includes(props.id) ?? false
+    )
   }
 })