kmcom-nuxt-layers 2.3.2 → 2.5.0

package/README.md

@@ -29,6 +29,8 @@ export default defineNuxtConfig({
 | **motion** | Animations — GSAP, Locomotive Scroll |
 | **shader** | 3D / WebGPU — Three.js, TresJS |
 | **forms** | Validation — Zod-based form system |
+| **database** | Storage — Drizzle ORM + Neon Postgres |
+| **auth** | Authentication — nuxt-auth-utils + GitHub OAuth |
 | **theme** | Theming — color mode, accent colors |
 | **content** | CMS — @nuxt/content, Nuxt Studio |
 

package/docs/ARCHITECTURE.md

@@ -15,6 +15,8 @@ nuxt-layers/
 │   ├── motion/              # GSAP + Locomotive Scroll animations
 │   ├── shader/              # Three.js / TresJS WebGPU shaders
 │   ├── forms/               # Zod-based form validation
+│   ├── database/            # Drizzle + Neon Postgres connection
+│   ├── auth/                # nuxt-auth-utils + GitHub OAuth
 │   ├── theme/               # Color mode, accent colors, accessibility
 │   └── content/             # @nuxt/content integration, Nuxt Studio
 ├── packages/                # Shared utilities (placeholder)
@@ -192,5 +194,7 @@ Some layers (ui, content) support standalone mode via environment variables (`UI
 | **motion** | Animation layer. GSAP with ScrollTrigger, Locomotive Scroll (Lenis) smooth scrolling, motion composables. Transpiles GSAP for SSR. |
 | **shader** | WebGPU/WebGL layer. Three.js + TresJS integration, TSL shader support, post-processing. Includes custom shader utilities and auto-imported shader modules. |
 | **forms** | Form validation layer. Zod schema-based validation, form composables, typed form components. |
+| **database** | Database infrastructure. Drizzle ORM + Neon Postgres via HTTP driver. Exposes `useSql()` and `useDrizzle(schema)` server utilities. App-owned schema and migrations; env: `NUXT_DATABASE_LAYER_URL`. |
+| **auth** | Authentication layer. nuxt-auth-utils + GitHub OAuth handler, sealed-cookie sessions. Opt-in `auth` route middleware; no user table (app's responsibility). Env: `NUXT_SESSION_PASSWORD`, `NUXT_OAUTH_GITHUB_CLIENT_ID/SECRET`. |
 | **theme** | Theming layer. Color mode switching, accent color palette, theme plugin, CSS custom properties for dynamic theming. |
 | **content** | Content management layer. @nuxt/content integration, better-sqlite3 for local content DB, optional Nuxt Studio support. |

package/layers/auth/app/middleware/auth.ts

@@ -0,0 +1,4 @@
+export default defineNuxtRouteMiddleware(() => {
+  const { loggedIn } = useUserSession()
+  if (!loggedIn.value) return navigateTo('/auth/github')
+})

package/layers/auth/nuxt.config.ts

@@ -0,0 +1,31 @@
+export default defineNuxtConfig({
+  $meta: {
+    name: 'auth',
+  },
+
+  extends: ['../core'],
+
+  modules: ['nuxt-auth-utils'],
+
+  alias: {
+    '#layers/auth': import.meta.dirname,
+  },
+
+  compatibilityDate: '2026-06-28',
+
+  runtimeConfig: {
+    // nuxt-auth-utils reads these env vars automatically:
+    session: { password: '' }, // env: NUXT_SESSION_PASSWORD
+    oauth: {
+      github: {
+        clientId: '', // env: NUXT_OAUTH_GITHUB_CLIENT_ID
+        clientSecret: '', // env: NUXT_OAUTH_GITHUB_CLIENT_SECRET
+      },
+    },
+  },
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})

package/layers/auth/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "kmcom-layer-auth",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev": "nuxi dev",
+    "dev:playground": "PLAYGROUND_LAYERS=core,auth pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "nuxt-auth-utils": "catalog:"
+  }
+}

package/layers/auth/server/routes/auth/github.get.ts

@@ -0,0 +1,13 @@
+export default defineOAuthGitHubEventHandler({
+  async onSuccess(event, { user }) {
+    await setUserSession(event, {
+      user: {
+        provider: 'github',
+        providerId: user.id,
+        username: user.login,
+        avatarUrl: user.avatar_url,
+      },
+    })
+    return sendRedirect(event, '/')
+  },
+})

package/layers/auth/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/baseline/app/components/BaselineStatus.vue

@@ -0,0 +1,17 @@
+<script lang="ts">
+import { defineComponent, h } from 'vue'
+
+export default defineComponent({
+  name: 'BaselineStatus',
+  props: {
+    featureId: {
+      type: String,
+      required: true,
+    },
+  },
+  setup(props) {
+    if (import.meta.server) return () => null
+    return () => h('baseline-status', { featureId: props.featureId })
+  },
+})
+</script>

package/layers/baseline/app/plugins/baseline-status.client.ts

@@ -0,0 +1,3 @@
+import 'baseline-status'
+
+export default defineNuxtPlugin(() => {})

package/layers/baseline/nuxt.config.ts

@@ -0,0 +1,24 @@
+export default defineNuxtConfig({
+  $meta: {
+    name: 'baseline',
+  },
+
+  extends: ['../core'],
+
+  alias: {
+    '#layers/baseline': import.meta.dirname,
+  },
+
+  compatibilityDate: '2026-06-06',
+
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === 'baseline-status' || tag === 'baseline-icon',
+    },
+  },
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})

package/layers/baseline/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "kmcom-layer-baseline",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev:playground": "PLAYGROUND_LAYERS=core,baseline pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "baseline-status": "catalog:"
+  }
+}

package/layers/baseline/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/database/nuxt.config.ts

@@ -0,0 +1,30 @@
+export default defineNuxtConfig({
+  $meta: {
+    name: 'database',
+  },
+
+  extends: ['../core'],
+
+  alias: {
+    '#layers/database': import.meta.dirname,
+  },
+
+  compatibilityDate: '2026-06-28',
+
+  runtimeConfig: {
+    databaseLayer: {
+      url: '', // env: NUXT_DATABASE_LAYER_URL  (Neon connection string)
+    },
+  },
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})
+
+declare module '@nuxt/schema' {
+  interface RuntimeConfig {
+    databaseLayer?: { url: string }
+  }
+}

package/layers/database/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "kmcom-layer-database",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev": "nuxi dev",
+    "dev:playground": "PLAYGROUND_LAYERS=core,database pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@neondatabase/serverless": "catalog:",
+    "drizzle-orm": "catalog:"
+  }
+}

package/layers/database/server/utils/drizzle.ts

@@ -0,0 +1,5 @@
+import { drizzle } from 'drizzle-orm/neon-http'
+
+export function useDrizzle<TSchema extends Record<string, unknown>>(schema: TSchema) {
+  return drizzle(useSql(), { schema })
+}

package/layers/database/server/utils/sql.ts

@@ -0,0 +1,7 @@
+import { neon } from '@neondatabase/serverless'
+
+export function useSql() {
+  const { databaseLayer } = useRuntimeConfig()
+  if (!databaseLayer?.url) throw createError('Database URL not configured')
+  return neon(databaseLayer.url)
+}

package/layers/database/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/metadata/app/composables/useMetadataItem.ts

@@ -0,0 +1,11 @@
+import type { MetadataProviderId, MetadataRecord } from '#layers/metadata/shared/types'
+
+export function useMetadataItem(provider: MetadataProviderId, providerId: string, resourceType?: string) {
+  return useAsyncData(
+    `metadata-item:${provider}:${providerId}`,
+    () =>
+      $fetch('/api/metadata/lookup', {
+        query: { provider, providerId, resourceType },
+      }) as Promise<MetadataRecord>,
+  )
+}

package/layers/metadata/app/composables/useMetadataSearch.ts

@@ -0,0 +1,25 @@
+import type { MetadataMediaType, MetadataProviderId, MetadataSearchResult } from '#layers/metadata/shared/types'
+
+type UseMetadataSearchOptions = {
+  mediaType?: MetadataMediaType
+  providers?: MetadataProviderId[]
+  limit?: number
+}
+
+export function useMetadataSearch(query: MaybeRef<string>, options: UseMetadataSearchOptions = {}) {
+  const q = computed(() => toValue(query).trim())
+
+  return useAsyncData(
+    () => `metadata-search:${q.value}`,
+    () =>
+      $fetch('/api/metadata/search', {
+        query: {
+          q: q.value,
+          mediaType: options.mediaType,
+          providers: options.providers?.join(','),
+          limit: options.limit,
+        },
+      }) as Promise<MetadataSearchResult[]>,
+    { watch: [q], immediate: false },
+  )
+}

package/layers/metadata/nuxt.config.ts

@@ -0,0 +1,27 @@
+export default defineNuxtConfig({
+  $meta: {
+    name: 'metadata',
+  },
+
+  extends: ['../core'],
+
+  alias: {
+    '#layers/metadata': import.meta.dirname,
+    '#layers/metadata/shared': `${import.meta.dirname}/shared`,
+  },
+
+  compatibilityDate: '2026-06-30',
+
+  nitro: {
+    storage: {
+      metadata: {
+        driver: 'memory',
+      },
+    },
+  },
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})

package/layers/metadata/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "kmcom-layer-metadata",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev": "nuxi dev",
+    "dev:playground": "PLAYGROUND_LAYERS=core,metadata pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
+  }
+}

package/layers/metadata/server/api/metadata/lookup.get.ts

@@ -0,0 +1,40 @@
+import type { MetadataProviderId } from '#layers/metadata/shared/types'
+
+// fallow-ignore-next-line complexity
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+
+  const providerId = String(query.providerId ?? '').trim()
+  const providerName = String(query.provider ?? '').trim() as MetadataProviderId
+  const resourceType = query.resourceType ? String(query.resourceType) : undefined
+
+  if (!providerName || !providerId) {
+    throw createError({ statusCode: 400, message: 'provider and providerId are required' })
+  }
+
+  const provider = getProvider(providerName)
+  if (!provider) throw createError({ statusCode: 404, message: `Provider '${providerName}' not registered` })
+
+  const cacheKey = makeCacheKey('metadata', providerName, resourceType ?? 'item', providerId)
+  const cached = await getCacheRecord(cacheKey)
+  if (cached) return cached.normalised
+
+  const result = await provider.lookup({ provider: providerName, providerId, resourceType })
+  if (!result) throw createError({ statusCode: 404, message: 'Not found' })
+
+  const now = new Date().toISOString()
+  await setCacheRecord(cacheKey, {
+    id: result.id,
+    provider: providerName,
+    providerId,
+    resourceType: resourceType ?? 'item',
+    mediaType: result.mediaType,
+    normalised: result,
+    raw: result.raw ?? null,
+    createdAt: now,
+    updatedAt: now,
+    lastSyncedAt: now,
+  })
+
+  return result
+})

package/layers/metadata/server/api/metadata/providers.get.ts

@@ -0,0 +1,7 @@
+export default defineEventHandler(() => {
+  return getProviders().map((p) => ({
+    id: p.id,
+    label: p.label,
+    mediaTypes: p.mediaTypes,
+  }))
+})

package/layers/metadata/server/api/metadata/search.get.ts

@@ -0,0 +1,17 @@
+import type { MetadataMediaType, MetadataProviderId } from '#layers/metadata/shared/types'
+
+// fallow-ignore-next-line complexity
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+
+  const q = String(query.q ?? '').trim()
+  if (!q) throw createError({ statusCode: 400, message: 'q is required' })
+
+  const mediaType = query.mediaType as MetadataMediaType | undefined
+  const providers = query.providers
+    ? String(query.providers).split(',').filter(Boolean) as MetadataProviderId[]
+    : undefined
+  const limit = query.limit ? Number(query.limit) : 10
+
+  return searchMetadata({ query: q, mediaType, providers, limit })
+})

package/layers/metadata/server/api/metadata/sync.post.ts

@@ -0,0 +1,40 @@
+import type { MetadataSyncInput, MetadataProviderId } from '#layers/metadata/shared/types'
+
+// fallow-ignore-next-line complexity
+export default defineEventHandler(async (event) => {
+  const body = await readBody<MetadataSyncInput>(event)
+
+  const { provider: providerName, providerId, resourceType, force } = body ?? {}
+  if (!providerName || !providerId) {
+    throw createError({ statusCode: 400, message: 'provider and providerId are required' })
+  }
+
+  const provider = getProvider(providerName as MetadataProviderId)
+  if (!provider) throw createError({ statusCode: 404, message: `Provider '${providerName}' not registered` })
+  if (!provider.sync) throw createError({ statusCode: 400, message: `Provider '${providerName}' does not support sync` })
+
+  const cacheKey = makeCacheKey('metadata', providerName, resourceType ?? 'item', providerId)
+
+  if (!force) {
+    const cached = await getCacheRecord(cacheKey)
+    if (cached) return { synced: false, record: cached.normalised }
+  }
+
+  const result = await provider.sync({ provider: providerName as MetadataProviderId, providerId, resourceType, force })
+  const now = new Date().toISOString()
+
+  await setCacheRecord(cacheKey, {
+    id: result.id,
+    provider: providerName as MetadataProviderId,
+    providerId,
+    resourceType: resourceType ?? 'item',
+    mediaType: result.mediaType,
+    normalised: result,
+    raw: result.raw ?? null,
+    createdAt: now,
+    updatedAt: now,
+    lastSyncedAt: now,
+  })
+
+  return { synced: true, record: result }
+})

package/layers/metadata/server/utils/metadata/cache.ts

@@ -0,0 +1,36 @@
+import type { MetadataCacheRecord } from '#layers/metadata/shared/types'
+
+// Cache keys: metadata:{provider}:{resourceType}:{providerId}
+//             metadata-search:{provider}:{mediaType}:{queryHash}
+
+export function makeCacheKey(...parts: string[]): string {
+  return parts.join(':')
+}
+
+export async function getCacheRecord(key: string): Promise<MetadataCacheRecord | null> {
+  const storage = useStorage('metadata')
+  return (await storage.getItem<MetadataCacheRecord>(key)) ?? null
+}
+
+export async function setCacheRecord(key: string, record: MetadataCacheRecord, ttl?: number): Promise<void> {
+  const storage = useStorage('metadata')
+  await storage.setItem(key, record, ttl ? { ttl } : undefined)
+}
+
+export async function getSearchCache<T>(key: string): Promise<T | null> {
+  const storage = useStorage('metadata')
+  return (await storage.getItem<T>(key)) ?? null
+}
+
+export async function setSearchCache<T>(key: string, value: T, ttl = 3600): Promise<void> {
+  const storage = useStorage('metadata')
+  await storage.setItem(key, value, { ttl })
+}
+
+export function hashQuery(query: string): string {
+  let h = 0
+  for (let i = 0; i < query.length; i++) {
+    h = (Math.imul(31, h) + query.charCodeAt(i)) | 0
+  }
+  return Math.abs(h).toString(36)
+}

package/layers/metadata/server/utils/metadata/errors.ts

@@ -0,0 +1,24 @@
+export class MetadataProviderError extends Error {
+  constructor(
+    public readonly provider: string,
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(`[metadata:${provider}] ${message}`)
+    this.name = 'MetadataProviderError'
+  }
+}
+
+export class MetadataNotFoundError extends Error {
+  constructor(provider: string, id: string) {
+    super(`[metadata:${provider}] Not found: ${id}`)
+    this.name = 'MetadataNotFoundError'
+  }
+}
+
+export class MetadataRateLimitError extends Error {
+  constructor(provider: string) {
+    super(`[metadata:${provider}] Rate limit exceeded`)
+    this.name = 'MetadataRateLimitError'
+  }
+}

package/layers/metadata/server/utils/metadata/provider-registry.ts

@@ -0,0 +1,15 @@
+import type { MetadataProvider, MetadataProviderId } from '#layers/metadata/shared/types'
+
+const _registry = new Map<MetadataProviderId, MetadataProvider>()
+
+export function registerProvider(provider: MetadataProvider) {
+  _registry.set(provider.id, provider)
+}
+
+export function getProvider(id: MetadataProviderId): MetadataProvider | null {
+  return _registry.get(id) ?? null
+}
+
+export function getProviders(): MetadataProvider[] {
+  return [..._registry.values()]
+}

package/layers/metadata/server/utils/metadata/search.ts

@@ -0,0 +1,42 @@
+import type { MetadataSearchInput, MetadataSearchResult } from '#layers/metadata/shared/types'
+
+// fallow-ignore-next-line complexity
+export async function searchMetadata(input: MetadataSearchInput): Promise<MetadataSearchResult[]> {
+  const all = getProviders()
+  const targets = input.providers?.length
+    ? all.filter((p) => input.providers!.includes(p.id))
+    : all.filter((p) => !input.mediaType || p.mediaTypes.includes(input.mediaType))
+
+  if (!targets.length) return []
+
+  const cacheKey = makeCacheKey(
+    'metadata-search',
+    targets.map((p) => p.id).join('+'),
+    input.mediaType ?? 'any',
+    hashQuery(`${input.query}:${input.limit ?? 10}`),
+  )
+
+  const cached = await getSearchCache<MetadataSearchResult[]>(cacheKey)
+  if (cached) return cached
+
+  const settled = await Promise.allSettled(targets.map((p) => p.search(input)))
+
+  const results: MetadataSearchResult[] = []
+  for (const outcome of settled) {
+    if (outcome.status === 'fulfilled') results.push(...outcome.value)
+  }
+
+  const deduped = deduplicateResults(results)
+  await setSearchCache(cacheKey, deduped)
+  return deduped
+}
+
+function deduplicateResults(results: MetadataSearchResult[]): MetadataSearchResult[] {
+  const seen = new Set<string>()
+  return results.filter((r) => {
+    const key = `${r.title.toLowerCase()}:${r.publishedAt?.slice(0, 4) ?? ''}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}

package/layers/metadata/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/metadata-comicvine/nuxt.config.ts

@@ -0,0 +1,36 @@
+export default defineNuxtConfig({
+  $meta: {
+    name: 'metadata-comicvine',
+  },
+
+  extends: ['../metadata'],
+
+  alias: {
+    '#layers/metadata-comicvine': import.meta.dirname,
+  },
+
+  compatibilityDate: '2026-06-30',
+
+  runtimeConfig: {
+    metadataComicvine: {
+      apiKey: '', // env: NUXT_METADATA_COMICVINE_API_KEY
+      baseUrl: 'https://comicvine.gamespot.com/api',
+      cacheTtl: 60 * 60 * 24 * 30,
+    },
+  },
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})
+
+declare module '@nuxt/schema' {
+  interface RuntimeConfig {
+    metadataComicvine: {
+      apiKey: string
+      baseUrl: string
+      cacheTtl: number
+    }
+  }
+}

package/layers/metadata-comicvine/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "kmcom-layer-metadata-comicvine",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev": "nuxi dev",
+    "dev:playground": "PLAYGROUND_LAYERS=core,metadata,metadata-comicvine pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
+  }
+}

package/layers/metadata-comicvine/server/plugins/comicvine-register.ts

@@ -0,0 +1,3 @@
+export default defineNitroPlugin(() => {
+  registerProvider(comicVineProvider)
+})