Merge branch 'main' into main

Author: rshigg

CONTRIBUTING.md

@@ -110,6 +110,59 @@ The connector will check your npm authentication, generate a connection token, a
 - We care about good types – never cast things to `any` 💪
 - Validate rather than just assert
 
+### Server API patterns
+
+#### Input validation with Valibot
+
+Use Valibot schemas from `#shared/schemas/` to validate API inputs. This ensures type safety and provides consistent error messages:
+
+```typescript
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+
+// In your handler:
+const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+  packageName: rawPackageName,
+  version: rawVersion,
+})
+```
+
+#### Error handling with `handleApiError`
+
+Use the `handleApiError` utility for consistent error handling in API routes. It re-throws H3 errors (like 404s) and wraps other errors with a fallback message:
+
+```typescript
+import { ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+
+try {
+  // API logic...
+} catch (error: unknown) {
+  handleApiError(error, {
+    statusCode: 502,
+    message: ERROR_NPM_FETCH_FAILED,
+  })
+}
+```
+
+#### URL parameter parsing with `parsePackageParams`
+
+Use `parsePackageParams` to extract package name and version from URL segments:
+
+```typescript
+const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
+```
+
+This handles patterns like `/pkg`, `/pkg/v/1.0.0`, `/@scope/pkg`, and `/@scope/pkg/v/1.0.0`.
+
+#### Constants
+
+Define error messages and other string constants in `#shared/utils/constants.ts` to ensure consistency across the codebase:
+
+```typescript
+export const ERROR_NPM_FETCH_FAILED = 'Failed to fetch package from npm registry.'
+```
+
 ### Import order
 
 1. Type imports first (`import type { ... }`)

app/composables/useRepoMeta.ts

@@ -466,6 +466,56 @@ const sourcehutAdapter: ProviderAdapter = {
   },
 }
 
+const tangledAdapter: ProviderAdapter = {
+  id: 'tangled',
+
+  parse(url) {
+    const host = url.hostname.toLowerCase()
+    if (
+      host !== 'tangled.sh' &&
+      host !== 'www.tangled.sh' &&
+      host !== 'tangled.org' &&
+      host !== 'www.tangled.org'
+    ) {
+      return null
+    }
+
+    const parts = url.pathname.split('/').filter(Boolean)
+    if (parts.length < 2) return null
+
+    // Tangled uses owner/repo format (owner is a domain-like identifier)
+    const owner = decodeURIComponent(parts[0] ?? '').trim()
+    const repo = decodeURIComponent(parts[1] ?? '')
+      .trim()
+      .replace(/\.git$/i, '')
+
+    if (!owner || !repo) return null
+
+    return { provider: 'tangled', owner, repo }
+  },
+
+  links(ref) {
+    const base = `https://tangled.sh/${ref.owner}/${ref.repo}`
+    return {
+      repo: base,
+      stars: base, // Tangled shows stars on the repo page
+      forks: `${base}/fork`,
+    }
+  },
+
+  async fetchMeta(_ref, links) {
+    // Tangled doesn't have a public API for repo stats yet
+    // Just return basic info without fetching
+    return {
+      provider: 'tangled',
+      url: links.repo,
+      stars: 0,
+      forks: 0,
+      links,
+    }
+  },
+}
+
 // Order matters: more specific adapters should come before generic ones
 const providers: readonly ProviderAdapter[] = [
   githubAdapter,
@@ -474,6 +524,7 @@ const providers: readonly ProviderAdapter[] = [
   codebergAdapter,
   giteeAdapter,
   sourcehutAdapter,
+  tangledAdapter,
   giteaAdapter, // Generic Gitea adapter last as fallback for self-hosted instances
 ] as const
 

app/pages/[...package].vue

@@ -164,6 +164,7 @@ const PROVIDER_ICONS: Record<string, string> = {
   gitea: 'i-simple-icons-gitea',
   gitee: 'i-simple-icons-gitee',
   sourcehut: 'i-simple-icons-sourcehut',
+  tangled: 'i-custom-tangled',
 }
 
 const repoProviderIcon = computed(() => {
@@ -451,6 +452,7 @@ defineOgImageComponent('Package', {
                   class="i-solar-eye-scan-outline w-3.5 h-3.5 inline-block"
                   aria-hidden="true"
                 />
+                <span class="sr-only">Inspect dependency tree</span>
               </a>
             </dd>
           </div>
@@ -568,7 +570,7 @@ defineOgImageComponent('Package', {
                 jsr
               </a>
             </li>
-            <li class="flex-grow">
+            <li class="sm:flex-grow">
               <a
                 :href="`https://socket.dev/npm/package/${pkg.name}/overview/${displayVersion?.version ?? 'latest'}`"
                 target="_blank"
@@ -670,6 +672,7 @@ defineOgImageComponent('Package', {
             </div>
           </div>
           <button
+            type="button"
             class="absolute top-3 right-3 px-2 py-1 font-mono text-xs text-fg-muted bg-bg-subtle/80 border border-border rounded transition-colors duration-200 hover:(text-fg border-border-hover) active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50"
             @click="copyInstallCommand"
           >

nuxt.config.ts

@@ -111,7 +111,13 @@ export default defineNuxtConfig({
 
   vite: {
     optimizeDeps: {
-      include: ['@vueuse/core', 'vue-data-ui/vue-ui-sparkline', 'virtua/vue'],
+      include: [
+        '@vueuse/core',
+        'vue-data-ui/vue-ui-sparkline',
+        'virtua/vue',
+        'semver',
+        'validate-npm-package-name',
+      ],
     },
   },
 })

package.json

@@ -44,6 +44,7 @@
     "shiki": "^3.21.0",
     "ufo": "^1.6.3",
     "unplugin-vue-router": "^0.19.2",
+    "valibot": "^1.2.0",
     "validate-npm-package-name": "^7.0.2",
     "virtua": "^0.48.3",
     "vue": "3.5.27",

pnpm-lock.yaml

@@ -1,3 +1,6 @@
+import * as v from 'valibot'
+import { PackageNameSchema } from '#shared/schemas/package'
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_JSR_FETCH_FAILED } from '#shared/utils/constants'
 import type { JsrPackageInfo } from '#shared/types/jsr'
 
 /**
@@ -11,17 +14,25 @@ import type { JsrPackageInfo } from '#shared/types/jsr'
 export default defineCachedEventHandler<Promise<JsrPackageInfo>>(
   async event => {
     const pkgPath = getRouterParam(event, 'pkg')
-    if (!pkgPath) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
-    assertValidPackageName(pkgPath)
 
-    return await fetchJsrPackageInfo(pkgPath)
+    try {
+      const packageName = v.parse(PackageNameSchema, pkgPath)
+
+      return await fetchJsrPackageInfo(packageName)
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_JSR_FETCH_FAILED,
+      })
+    }
   },
   {
-    maxAge: 60 * 60, // 1 hour
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
     swr: true,
     name: 'api-jsr-package',
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `jsr:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )

server/api/jsr/[...pkg].get.ts

@@ -1,24 +1,28 @@
+import * as v from 'valibot'
+import { PackageNameSchema } from '#shared/schemas/package'
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+
 export default defineCachedEventHandler(
   async event => {
-    const pkg = getRouterParam(event, 'pkg')
-    if (!pkg) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
+    try {
+      const pkg = getRouterParam(event, 'pkg')
 
-    assertValidPackageName(pkg)
+      const packageName = v.parse(PackageNameSchema, pkg)
 
-    try {
-      return await fetchNpmPackage(pkg)
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({ statusCode: 502, message: 'Failed to fetch package from npm registry' })
+      return await fetchNpmPackage(packageName)
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_NPM_FETCH_FAILED,
+      })
     }
   },
   {
-    maxAge: 60 * 60, // 1 hour
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
     swr: true,
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `packument:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )

server/api/registry/[...pkg].get.ts

@@ -1,34 +1,31 @@
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
 import type { PackageAnalysis, ExtendedPackageJson } from '#shared/utils/package-analysis'
 import {
   analyzePackage,
   getTypesPackageName,
   hasBuiltInTypes,
 } from '#shared/utils/package-analysis'
-
-const NPM_REGISTRY = 'https://registry.npmjs.org'
+import {
+  NPM_REGISTRY,
+  CACHE_MAX_AGE_ONE_DAY,
+  ERROR_PACKAGE_ANALYSIS_FAILED,
+} from '#shared/utils/constants'
 
 export default defineCachedEventHandler(
   async event => {
-    const pkgParam = getRouterParam(event, 'pkg')
-    if (!pkgParam) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
-
     // Parse package name and optional version from path
     // e.g., "vue" or "vue/v/3.4.0" or "@nuxt/kit" or "@nuxt/kit/v/1.0.0"
-    const segments = pkgParam.split('/')
-    let packageName: string
-    let version: string | undefined
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
 
-    const vIndex = segments.indexOf('v')
-    if (vIndex !== -1 && vIndex < segments.length - 1) {
-      packageName = segments.slice(0, vIndex).join('/')
-      version = segments.slice(vIndex + 1).join('/')
-    } else {
-      packageName = segments.join('/')
-    }
+    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
 
     try {
+      const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+        packageName: rawPackageName,
+        version: rawVersion,
+      })
+
       // Fetch package data
       const encodedName = encodePackageName(packageName)
       const versionSuffix = version ? `/${version}` : '/latest'
@@ -39,8 +36,8 @@ export default defineCachedEventHandler(
       // Only check for @types package if the package doesn't ship its own types
       let typesPackageExists = false
       if (!hasBuiltInTypes(pkg)) {
-        const typesPackageName = getTypesPackageName(packageName)
-        typesPackageExists = await checkPackageExists(typesPackageName)
+        const typesPkgName = getTypesPackageName(packageName)
+        typesPackageExists = await checkPackageExists(typesPkgName)
       }
 
       const analysis = analyzePackage(pkg, { typesPackageExists })
@@ -50,20 +47,20 @@ export default defineCachedEventHandler(
         version: pkg.version ?? version ?? 'latest',
         ...analysis,
       } satisfies PackageAnalysisResponse
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({
+    } catch (error: unknown) {
+      handleApiError(error, {
         statusCode: 502,
-        message: 'Failed to analyze package',
+        message: ERROR_PACKAGE_ANALYSIS_FAILED,
       })
     }
   },
   {
-    maxAge: 60 * 60 * 24, // 24 hours - analysis rarely changes
+    maxAge: CACHE_MAX_AGE_ONE_DAY, // 24 hours - analysis rarely changes
     swr: true,
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `analysis:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )