pilothub 0.0.1

package/src/lib/site.ts

@@ -0,0 +1,84 @@
+export type SiteMode = 'skills' | 'souls'
+
+const DEFAULT_PILOTHUB_SITE_URL = 'https://pilothub.com'
+const DEFAULT_ONLYCRABS_SITE_URL = 'https://onlycrabs.ai'
+const DEFAULT_ONLYCRABS_HOST = 'onlycrabs.ai'
+
+export function getPilotHubSiteUrl() {
+  return import.meta.env.VITE_SITE_URL ?? DEFAULT_PILOTHUB_SITE_URL
+}
+
+export function getOnlyCrabsSiteUrl() {
+  const explicit = import.meta.env.VITE_SOULHUB_SITE_URL
+  if (explicit) return explicit
+
+  const siteUrl = import.meta.env.VITE_SITE_URL
+  if (siteUrl) {
+    try {
+      const url = new URL(siteUrl)
+      if (
+        url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '0.0.0.0'
+      ) {
+        return url.origin
+      }
+    } catch {
+      // ignore invalid URLs, fall through to default
+    }
+  }
+
+  return DEFAULT_ONLYCRABS_SITE_URL
+}
+
+export function getOnlyCrabsHost() {
+  return import.meta.env.VITE_SOULHUB_HOST ?? DEFAULT_ONLYCRABS_HOST
+}
+
+export function detectSiteMode(host?: string | null): SiteMode {
+  if (!host) return 'skills'
+  const onlyCrabsHost = getOnlyCrabsHost().toLowerCase()
+  const lower = host.toLowerCase()
+  if (lower === onlyCrabsHost || lower.endsWith(`.${onlyCrabsHost}`)) return 'souls'
+  return 'skills'
+}
+
+export function detectSiteModeFromUrl(value?: string | null): SiteMode {
+  if (!value) return 'skills'
+  try {
+    const host = new URL(value).hostname
+    return detectSiteMode(host)
+  } catch {
+    return detectSiteMode(value)
+  }
+}
+
+export function getSiteMode(): SiteMode {
+  if (typeof window !== 'undefined') {
+    return detectSiteMode(window.location.hostname)
+  }
+  const forced = import.meta.env.VITE_SITE_MODE
+  if (forced === 'souls' || forced === 'skills') return forced
+
+  const onlyCrabsSite = import.meta.env.VITE_SOULHUB_SITE_URL
+  if (onlyCrabsSite) return detectSiteModeFromUrl(onlyCrabsSite)
+
+  const siteUrl = import.meta.env.VITE_SITE_URL ?? process.env.SITE_URL
+  if (siteUrl) return detectSiteModeFromUrl(siteUrl)
+
+  return 'skills'
+}
+
+export function getSiteName(mode: SiteMode = getSiteMode()) {
+  return mode === 'souls' ? 'SoulHub' : 'PilotHub'
+}
+
+export function getSiteDescription(mode: SiteMode = getSiteMode()) {
+  return mode === 'souls'
+    ? 'SoulHub — the home for SOUL.md bundles and personal system lore.'
+    : 'PilotHub — a fast skill registry for agents, with vector search.'
+}
+
+export function getSiteUrlForMode(mode: SiteMode = getSiteMode()) {
+  return mode === 'souls' ? getOnlyCrabsSiteUrl() : getPilotHubSiteUrl()
+}

package/src/lib/theme-transition.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it, vi } from 'vitest'
+import { startThemeTransition } from './theme-transition'
+
+describe('startThemeTransition', () => {
+  it('no-ops when theme does not change', () => {
+    const setTheme = vi.fn()
+    startThemeTransition({
+      currentTheme: 'dark',
+      nextTheme: 'dark',
+      setTheme,
+    })
+    expect(setTheme).not.toHaveBeenCalled()
+  })
+
+  it('applies theme without document (SSR)', () => {
+    const original = Object.getOwnPropertyDescriptor(globalThis, 'document')
+    Object.defineProperty(globalThis, 'document', { value: undefined, configurable: true })
+
+    try {
+      const calls: string[] = []
+      const setTheme = vi.fn()
+      startThemeTransition({
+        currentTheme: 'light',
+        nextTheme: 'dark',
+        setTheme,
+        onBeforeThemeChange: () => calls.push('before'),
+        onAfterThemeChange: () => calls.push('after'),
+      })
+      expect(calls).toEqual(['before', 'after'])
+      expect(setTheme).toHaveBeenCalledWith('dark')
+    } finally {
+      if (original) Object.defineProperty(globalThis, 'document', original)
+      else delete (globalThis as unknown as { document?: unknown }).document
+    }
+  })
+
+  it('skips view-transition when prefers reduced motion', () => {
+    const setTheme = vi.fn()
+    const root = document.documentElement
+
+    window.matchMedia = vi.fn(() => ({ matches: true }) as unknown as MediaQueryList)
+    ;(document as unknown as { startViewTransition?: unknown }).startViewTransition = vi.fn()
+
+    startThemeTransition({
+      currentTheme: 'light',
+      nextTheme: 'dark',
+      setTheme,
+      context: { pointerClientX: 10, pointerClientY: 10 },
+    })
+
+    expect(setTheme).toHaveBeenCalledWith('dark')
+    expect(root.classList.contains('theme-transition')).toBe(false)
+    expect(
+      (document as unknown as { startViewTransition?: unknown }).startViewTransition,
+    ).not.toHaveBeenCalled()
+  })
+
+  it('uses view-transition when available', async () => {
+    const setTheme = vi.fn()
+    const root = document.documentElement
+
+    window.matchMedia = vi.fn(() => ({ matches: false }) as unknown as MediaQueryList)
+
+    ;(
+      document as unknown as {
+        startViewTransition?: (callback: () => void) => { finished: Promise<void> }
+      }
+    ).startViewTransition = (callback) => {
+      callback()
+      return { finished: Promise.resolve() }
+    }
+
+    startThemeTransition({
+      currentTheme: 'light',
+      nextTheme: 'dark',
+      setTheme,
+      context: { pointerClientX: 10, pointerClientY: 20 },
+    })
+
+    expect(setTheme).toHaveBeenCalledWith('dark')
+    expect(root.classList.contains('theme-transition')).toBe(true)
+
+    await new Promise((r) => setTimeout(r, 0))
+    expect(root.classList.contains('theme-transition')).toBe(false)
+    expect(root.style.getPropertyValue('--theme-switch-x')).toBe('')
+    expect(root.style.getPropertyValue('--theme-switch-y')).toBe('')
+  })
+
+  it('cleans up when view-transition does not provide finished', () => {
+    const setTheme = vi.fn()
+    const root = document.documentElement
+
+    window.matchMedia = vi.fn(() => ({ matches: false }) as unknown as MediaQueryList)
+    ;(
+      document as unknown as { startViewTransition?: (callback: () => void) => unknown }
+    ).startViewTransition = (callback) => {
+      callback()
+      return {}
+    }
+
+    startThemeTransition({
+      currentTheme: 'light',
+      nextTheme: 'dark',
+      setTheme,
+      context: { element: document.body },
+    })
+
+    expect(setTheme).toHaveBeenCalledWith('dark')
+    expect(root.classList.contains('theme-transition')).toBe(false)
+  })
+
+  it('falls back when view-transition throws', () => {
+    const setTheme = vi.fn()
+    const root = document.documentElement
+
+    window.matchMedia = vi.fn(() => ({ matches: false }) as unknown as MediaQueryList)
+    ;(document as unknown as { startViewTransition?: () => never }).startViewTransition = () => {
+      throw new Error('nope')
+    }
+
+    const element = document.createElement('button')
+    element.getBoundingClientRect = () => ({ left: 10, top: 10, width: 10, height: 10 }) as DOMRect
+
+    startThemeTransition({
+      currentTheme: 'light',
+      nextTheme: 'dark',
+      setTheme,
+      context: { element },
+    })
+
+    expect(setTheme).toHaveBeenCalledWith('dark')
+    expect(root.classList.contains('theme-transition')).toBe(false)
+  })
+})

package/src/lib/theme-transition.ts

@@ -0,0 +1,134 @@
+import { flushSync } from 'react-dom'
+
+export type ThemeValue = 'light' | 'dark' | 'system' | (string & {})
+
+export type ThemeTransitionContext = {
+  element?: HTMLElement | null
+  pointerClientX?: number
+  pointerClientY?: number
+}
+
+export type ThemeTransitionOptions = {
+  nextTheme: ThemeValue
+  setTheme: (theme: ThemeValue) => void
+  context?: ThemeTransitionContext | undefined
+  onBeforeThemeChange?: () => void
+  onAfterThemeChange?: () => void
+  currentTheme?: ThemeValue | null
+}
+
+type DocumentWithViewTransition = Document & {
+  startViewTransition?: (callback: () => void) => {
+    finished: Promise<void>
+  }
+}
+
+type WindowWithMatchMedia = Window & {
+  matchMedia: (query: string) => MediaQueryList
+}
+
+const clamp01 = (value: number) => {
+  if (Number.isNaN(value)) return 0.5
+  if (value <= 0) return 0
+  if (value >= 1) return 1
+  return value
+}
+
+const resolveWindow = (): WindowWithMatchMedia | undefined =>
+  globalThis.window as WindowWithMatchMedia | undefined
+
+const hasReducedMotionPreference = (): boolean => {
+  const currentWindow = resolveWindow()
+  if (!currentWindow || typeof currentWindow.matchMedia !== 'function') return false
+  return currentWindow.matchMedia('(prefers-reduced-motion: reduce)').matches ?? false
+}
+
+const cleanupThemeTransition = (root: HTMLElement) => {
+  root.classList.remove('theme-transition')
+  root.style.removeProperty('--theme-switch-x')
+  root.style.removeProperty('--theme-switch-y')
+}
+
+export const startThemeTransition = ({
+  nextTheme,
+  setTheme,
+  context,
+  onBeforeThemeChange,
+  onAfterThemeChange,
+  currentTheme,
+}: ThemeTransitionOptions) => {
+  if (currentTheme === nextTheme) return
+
+  const documentReference = globalThis.document ?? null
+  if (!documentReference) {
+    onBeforeThemeChange?.()
+    setTheme(nextTheme)
+    onAfterThemeChange?.()
+    return
+  }
+
+  const root = documentReference.documentElement
+  const document_ = documentReference as DocumentWithViewTransition
+  const prefersReducedMotion = hasReducedMotionPreference()
+
+  const applyTheme = () => {
+    onBeforeThemeChange?.()
+    flushSync(() => {
+      setTheme(nextTheme)
+    })
+    onAfterThemeChange?.()
+  }
+
+  const canUseViewTransition = Boolean(document_.startViewTransition) && !prefersReducedMotion
+  if (canUseViewTransition) {
+    let xPercent = 0.5
+    let yPercent = 0.5
+
+    const currentWindow = resolveWindow()
+    if (
+      context?.pointerClientX !== undefined &&
+      context?.pointerClientY !== undefined &&
+      currentWindow
+    ) {
+      xPercent = clamp01(context.pointerClientX / currentWindow.innerWidth)
+      yPercent = clamp01(context.pointerClientY / currentWindow.innerHeight)
+    } else if (context?.element) {
+      const rect = context.element.getBoundingClientRect()
+      if (rect.width > 0 && rect.height > 0 && currentWindow) {
+        xPercent = clamp01((rect.left + rect.width / 2) / currentWindow.innerWidth)
+        yPercent = clamp01((rect.top + rect.height / 2) / currentWindow.innerHeight)
+      }
+    }
+
+    root.style.setProperty('--theme-switch-x', `${xPercent * 100}%`)
+    root.style.setProperty('--theme-switch-y', `${yPercent * 100}%`)
+    root.classList.add('theme-transition')
+
+    try {
+      const transition = document_.startViewTransition?.(() => {
+        applyTheme()
+      })
+      if (transition?.finished === undefined) {
+        cleanupThemeTransition(root)
+      } else {
+        const handleTransitionFinish = async () => {
+          try {
+            await transition.finished
+          } catch {
+            // swallow transition cancellation errors
+          } finally {
+            cleanupThemeTransition(root)
+          }
+        }
+        void handleTransitionFinish()
+      }
+    } catch {
+      cleanupThemeTransition(root)
+      applyTheme()
+    }
+    return
+  }
+
+  applyTheme()
+  cleanupThemeTransition(root)
+}

package/src/lib/theme.test.tsx

@@ -0,0 +1,88 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { applyTheme, getStoredTheme, useThemeMode } from './theme'
+
+describe('theme', () => {
+  let store: Record<string, string>
+
+  function Harness() {
+    const { mode, setMode } = useThemeMode()
+    return (
+      <div>
+        <div data-testid="mode">{mode}</div>
+        <button type="button" onClick={() => setMode('dark')}>
+          dark
+        </button>
+      </div>
+    )
+  }
+
+  beforeEach(() => {
+    store = {}
+    Object.defineProperty(window, 'localStorage', {
+      value: {
+        getItem: (key: string) => (key in store ? store[key] : null),
+        setItem: (key: string, value: string) => {
+          store[key] = String(value)
+        },
+        removeItem: (key: string) => {
+          delete store[key]
+        },
+        clear: () => {
+          store = {}
+        },
+      },
+      configurable: true,
+    })
+  })
+
+  afterEach(() => {
+    document.documentElement.classList.remove('dark')
+    delete document.documentElement.dataset.theme
+    window.localStorage.clear()
+    vi.unstubAllGlobals()
+  })
+
+  it('reads stored theme with fallback', () => {
+    expect(getStoredTheme()).toBe('system')
+    window.localStorage.setItem('pilothub-theme', 'dark')
+    expect(getStoredTheme()).toBe('dark')
+    window.localStorage.setItem('pilothub-theme', 'nope')
+    expect(getStoredTheme()).toBe('system')
+  })
+
+  it('applies theme and toggles dark class', () => {
+    applyTheme('dark')
+    expect(document.documentElement.dataset.theme).toBe('dark')
+    expect(document.documentElement.classList.contains('dark')).toBe(true)
+
+    applyTheme('light')
+    expect(document.documentElement.dataset.theme).toBe('light')
+    expect(document.documentElement.classList.contains('dark')).toBe(false)
+  })
+
+  it('resolves system theme via matchMedia', () => {
+    vi.stubGlobal('matchMedia', () => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }))
+    applyTheme('system')
+    expect(document.documentElement.dataset.theme).toBe('dark')
+  })
+
+  it('useThemeMode persists and applies mode', async () => {
+    vi.stubGlobal('matchMedia', () => ({
+      matches: false,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }))
+    render(<Harness />)
+    expect(screen.getByTestId('mode').textContent).toBe('system')
+    fireEvent.click(screen.getByRole('button', { name: 'dark' }))
+    await waitFor(() => {
+      expect(document.documentElement.dataset.theme).toBe('dark')
+    })
+    expect(window.localStorage.getItem('pilothub-theme')).toBe('dark')
+  })
+})

package/src/lib/theme.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react'
+
+export type ThemeMode = 'system' | 'light' | 'dark'
+
+const THEME_KEY = 'pilothub-theme'
+
+export function getStoredTheme(): ThemeMode {
+  if (typeof window === 'undefined') return 'system'
+  const stored = window.localStorage.getItem(THEME_KEY)
+  if (stored === 'light' || stored === 'dark' || stored === 'system') return stored
+  return 'system'
+}
+
+function resolveTheme(mode: ThemeMode) {
+  if (mode !== 'system') return mode
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+export function applyTheme(mode: ThemeMode) {
+  if (typeof document === 'undefined') return
+  const resolved = resolveTheme(mode)
+  document.documentElement.dataset.theme = resolved
+  document.documentElement.classList.toggle('dark', resolved === 'dark')
+}
+
+export function useThemeMode() {
+  const [mode, setMode] = useState<ThemeMode>(() => getStoredTheme())
+
+  useEffect(() => {
+    applyTheme(mode)
+    if (typeof window !== 'undefined') {
+      window.localStorage.setItem(THEME_KEY, mode)
+    }
+    if (mode !== 'system' || typeof window === 'undefined') return
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    const handler = () => applyTheme(mode)
+    media.addEventListener('change', handler)
+    return () => media.removeEventListener('change', handler)
+  }, [mode])
+
+  return { mode, setMode }
+}

package/src/lib/uploadFiles.jsdom.test.ts

@@ -0,0 +1,33 @@
+import { strToU8, unzipSync, zipSync } from 'fflate'
+import { describe, expect, it } from 'vitest'
+
+import { expandFiles } from './uploadFiles'
+
+function readWithFileReader(blob: Blob) {
+  return new Promise<ArrayBuffer>((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onerror = () => reject(reader.error ?? new Error('Could not read blob.'))
+    reader.onload = () => resolve(reader.result as ArrayBuffer)
+    reader.readAsArrayBuffer(blob)
+  })
+}
+
+describe('expandFiles (jsdom)', () => {
+  it('expands zip archives using FileReader fallback', async () => {
+    const zip = zipSync({
+      'hetzner-cloud-skill/SKILL.md': new Uint8Array(strToU8('hello')),
+      'hetzner-cloud-skill/notes.txt': new Uint8Array(strToU8('notes')),
+    })
+    const zipBytes = Uint8Array.from(zip).buffer
+    const zipFile = new File([zipBytes], 'bundle.zip', { type: 'application/zip' })
+
+    const readerBuffer = await readWithFileReader(zipFile)
+    const entries = unzipSync(new Uint8Array(readerBuffer))
+    expect(Object.keys(entries)).toEqual(
+      expect.arrayContaining(['hetzner-cloud-skill/SKILL.md', 'hetzner-cloud-skill/notes.txt']),
+    )
+
+    const expanded = await expandFiles([zipFile])
+    expect(expanded.map((file) => file.name)).toEqual(['SKILL.md', 'notes.txt'])
+  })
+})

package/src/lib/uploadFiles.test.ts

@@ -0,0 +1,123 @@
+/* @vitest-environment node */
+import { gzipSync, strToU8, zipSync } from 'fflate'
+import { describe, expect, it } from 'vitest'
+import { expandFiles } from './uploadFiles'
+
+if (typeof File === 'undefined') {
+  class NodeFile extends Blob {
+    name: string
+    lastModified: number
+
+    constructor(parts: BlobPart[], name: string, options?: FilePropertyBag) {
+      super(parts, options)
+      this.name = name
+      this.lastModified = options?.lastModified ?? Date.now()
+    }
+  }
+  // @ts-expect-error Node test environment polyfill
+  globalThis.File = NodeFile
+}
+
+function buildTar(entries: Array<{ name: string; content: string }>) {
+  const blocks: Uint8Array[] = []
+  for (const entry of entries) {
+    const content = strToU8(entry.content)
+    const header = new Uint8Array(512)
+    writeString(header, entry.name, 0, 100)
+    writeString(header, '0000777', 100, 8)
+    writeString(header, '0000000', 108, 8)
+    writeString(header, '0000000', 116, 8)
+    writeString(header, content.length.toString(8).padStart(11, '0'), 124, 12)
+    writeString(header, '00000000000', 136, 12)
+    header[156] = '0'.charCodeAt(0)
+    writeString(header, 'ustar', 257, 6)
+    for (let i = 148; i < 156; i += 1) {
+      header[i] = 32
+    }
+    let sum = 0
+    for (const byte of header) sum += byte
+    writeString(header, sum.toString(8).padStart(6, '0'), 148, 6)
+    header[154] = 0
+    header[155] = 32
+    blocks.push(header)
+    blocks.push(content)
+    const pad = (512 - (content.length % 512)) % 512
+    if (pad) blocks.push(new Uint8Array(pad))
+  }
+  blocks.push(new Uint8Array(1024))
+  const total = blocks.reduce((sum, block) => sum + block.length, 0)
+  const buffer = new Uint8Array(total)
+  let offset = 0
+  for (const block of blocks) {
+    buffer.set(block, offset)
+    offset += block.length
+  }
+  return buffer
+}
+
+function writeString(target: Uint8Array, value: string, start: number, length: number) {
+  const bytes = strToU8(value)
+  target.set(bytes.subarray(0, length), start)
+}
+
+describe('expandFiles', () => {
+  it('expands zip archives into files', async () => {
+    const zip = zipSync({
+      'SKILL.md': strToU8('hello'),
+      'docs/readme.txt': strToU8('doc'),
+    })
+    const zipFile = new File([Uint8Array.from(zip).buffer], 'pack.zip', { type: 'application/zip' })
+    const result = await expandFiles([zipFile])
+    expect(result.map((file) => file.name)).toEqual(['SKILL.md', 'docs/readme.txt'])
+  })
+
+  it('unwraps top-level folders in zip archives', async () => {
+    const zip = zipSync({
+      'hetzner-cloud-skill/SKILL.md': strToU8('hello'),
+      'hetzner-cloud-skill/docs/readme.txt': strToU8('doc'),
+      '__MACOSX/._SKILL.md': strToU8('junk'),
+      'hetzner-cloud-skill/.DS_Store': strToU8('junk2'),
+      'hetzner-cloud-skill/screenshot.png': strToU8('not-really-a-png'),
+    })
+    const zipFile = new File([Uint8Array.from(zip).buffer], 'pack.zip', { type: 'application/zip' })
+    const result = await expandFiles([zipFile])
+    expect(result.map((file) => file.name)).toEqual(['SKILL.md', 'docs/readme.txt'])
+    const png = result.find((file) => file.name.endsWith('.png'))
+    expect(png).toBeUndefined()
+  })
+
+  it('expands gzipped tar archives into files', async () => {
+    const tar = buildTar([
+      { name: 'SKILL.md', content: 'hi' },
+      { name: 'notes.txt', content: 'yo' },
+    ])
+    const tgz = gzipSync(tar)
+    const tgzFile = new File([Uint8Array.from(tgz).buffer], 'bundle.tgz', {
+      type: 'application/gzip',
+    })
+    const result = await expandFiles([tgzFile])
+    expect(result.map((file) => file.name)).toEqual(['SKILL.md', 'notes.txt'])
+  })
+
+  it('unwraps top-level folders in tar.gz archives', async () => {
+    const tar = buildTar([
+      { name: 'skill-folder/SKILL.md', content: 'hi' },
+      { name: 'skill-folder/notes.txt', content: 'yo' },
+    ])
+    const tgz = gzipSync(tar)
+    const tgzFile = new File([Uint8Array.from(tgz).buffer], 'bundle.tgz', {
+      type: 'application/gzip',
+    })
+    const result = await expandFiles([tgzFile])
+    expect(result.map((file) => file.name)).toEqual(['SKILL.md', 'notes.txt'])
+  })
+
+  it('expands .gz single files', async () => {
+    const gz = gzipSync(strToU8('content'))
+    const gzFile = new File([Uint8Array.from(gz).buffer], 'skill.md.gz', {
+      type: 'application/gzip',
+    })
+    const result = await expandFiles([gzFile])
+    expect(result.map((file) => file.name)).toEqual(['skill.md'])
+  })
+})