pilothub 0.0.1

package/scripts/docs-list.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DOCS_DIR = resolveDocsDir()
+
+const EXCLUDED_DIRS = new Set(['archive', 'research'])
+
+function resolveDocsDir() {
+  const env = process.env.DOCS_DIR?.trim()
+  if (env) return env
+
+  const fromCwd = join(process.cwd(), 'docs')
+  if (existsSync(fromCwd)) return fromCwd
+
+  const docsListFile = fileURLToPath(import.meta.url)
+  const docsListDir = dirname(docsListFile)
+  return join(docsListDir, '..', 'docs')
+}
+
+function compactStrings(values: unknown[]): string[] {
+  const result: string[] = []
+  for (const value of values) {
+    if (value === null || value === undefined) continue
+    const normalized = String(value).trim()
+    if (normalized.length > 0) result.push(normalized)
+  }
+  return result
+}
+
+function walkMarkdownFiles(dir: string, base: string = dir): string[] {
+  const entries = readdirSync(dir, { withFileTypes: true })
+  const files: string[] = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue
+    const fullPath = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue
+      files.push(...walkMarkdownFiles(fullPath, base))
+      continue
+    }
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(relative(base, fullPath))
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b))
+}
+
+function extractMetadata(fullPath: string): {
+  summary: string | null
+  readWhen: string[]
+  error?: string
+} {
+  const content = readFileSync(fullPath, 'utf8')
+
+  if (!content.startsWith('---')) {
+    return { summary: null, readWhen: [], error: 'missing front matter' }
+  }
+
+  const endIndex = content.indexOf('\n---', 3)
+  if (endIndex === -1) {
+    return { summary: null, readWhen: [], error: 'unterminated front matter' }
+  }
+
+  const frontMatter = content.slice(3, endIndex).trim()
+  const lines = frontMatter.split('\n')
+
+  let summaryLine: string | null = null
+  const readWhen: string[] = []
+  let collectingField: 'read_when' | null = null
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+
+    if (line.startsWith('summary:')) {
+      summaryLine = line
+      collectingField = null
+      continue
+    }
+
+    if (line.startsWith('read_when:')) {
+      collectingField = 'read_when'
+      const inline = line.slice('read_when:'.length).trim()
+      if (inline.startsWith('[') && inline.endsWith(']')) {
+        try {
+          const parsed = JSON.parse(inline.replace(/'/g, '"')) as unknown
+          if (Array.isArray(parsed)) {
+            readWhen.push(...compactStrings(parsed))
+          }
+        } catch {
+          // ignore malformed inline arrays
+        }
+      }
+      continue
+    }
+
+    if (collectingField === 'read_when') {
+      if (line.startsWith('- ')) {
+        const hint = line.slice(2).trim()
+        if (hint) readWhen.push(hint)
+      } else if (line === '') {
+        // ignore
+      } else {
+        collectingField = null
+      }
+    }
+  }
+
+  if (!summaryLine) {
+    return { summary: null, readWhen, error: 'summary key missing' }
+  }
+
+  const summaryValue = summaryLine.slice('summary:'.length).trim()
+  const normalized = summaryValue
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  if (!normalized) {
+    return { summary: null, readWhen, error: 'summary is empty' }
+  }
+
+  return { summary: normalized, readWhen }
+}
+
+console.log('Listing all markdown files in docs folder:')
+
+const markdownFiles = walkMarkdownFiles(DOCS_DIR)
+
+for (const relativePath of markdownFiles) {
+  const fullPath = join(DOCS_DIR, relativePath)
+  const { summary, readWhen, error } = extractMetadata(fullPath)
+  if (summary) {
+    console.log(`${relativePath} - ${summary}`)
+    if (readWhen.length > 0) {
+      console.log(`  Read when: ${readWhen.join('; ')}`)
+    }
+  } else {
+    const reason = error ? ` - [${error}]` : ''
+    console.log(`${relativePath}${reason}`)
+  }
+}
+
+console.log(
+  '\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above, read that doc before coding, and suggest new coverage when it is missing.',
+)

package/scripts/run-playwright-local.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PORT="${PLAYWRIGHT_PORT:-4173}"
+
+if [[ -n "${PLAYWRIGHT_BASE_URL:-}" ]]; then
+  echo "Running against $PLAYWRIGHT_BASE_URL"
+  bun run test:pw
+  exit 0
+fi
+
+echo "Running against local preview server on http://127.0.0.1:$PORT"
+bun run build
+PLAYWRIGHT_PORT="$PORT" bun run test:pw

package/server/og/fetchSkillOgMeta.ts

@@ -0,0 +1,27 @@
+export type SkillOgMeta = {
+  displayName: string | null
+  summary: string | null
+  owner: string | null
+  version: string | null
+}
+
+export async function fetchSkillOgMeta(slug: string, apiBase: string): Promise<SkillOgMeta | null> {
+  try {
+    const url = new URL(`/api/v1/skills/${encodeURIComponent(slug)}`, apiBase)
+    const response = await fetch(url.toString(), { headers: { Accept: 'application/json' } })
+    if (!response.ok) return null
+    const payload = (await response.json()) as {
+      skill?: { displayName?: string; summary?: string | null } | null
+      owner?: { handle?: string | null } | null
+      latestVersion?: { version?: string | null } | null
+    }
+    return {
+      displayName: payload.skill?.displayName ?? null,
+      summary: payload.skill?.summary ?? null,
+      owner: payload.owner?.handle ?? null,
+      version: payload.latestVersion?.version ?? null,
+    }
+  } catch {
+    return null
+  }
+}

package/server/og/fetchSoulOgMeta.ts

@@ -0,0 +1,27 @@
+export type SoulOgMeta = {
+  displayName: string | null
+  summary: string | null
+  owner: string | null
+  version: string | null
+}
+
+export async function fetchSoulOgMeta(slug: string, apiBase: string): Promise<SoulOgMeta | null> {
+  try {
+    const url = new URL(`/api/v1/souls/${encodeURIComponent(slug)}`, apiBase)
+    const response = await fetch(url.toString(), { headers: { Accept: 'application/json' } })
+    if (!response.ok) return null
+    const payload = (await response.json()) as {
+      soul?: { displayName?: string; summary?: string | null } | null
+      owner?: { handle?: string | null } | null
+      latestVersion?: { version?: string | null } | null
+    }
+    return {
+      displayName: payload.soul?.displayName ?? null,
+      summary: payload.soul?.summary ?? null,
+      owner: payload.owner?.handle ?? null,
+      version: payload.latestVersion?.version ?? null,
+    }
+  } catch {
+    return null
+  }
+}

package/server/og/ogAssets.ts

@@ -0,0 +1,80 @@
+import { readFile } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+
+export const FONT_SANS = 'Bricolage Grotesque'
+export const FONT_MONO = 'IBM Plex Mono'
+
+type GlobalNitroMain = {
+  __nitro_main__?: unknown
+}
+
+let markDataUrlPromise: Promise<string> | null = null
+let resvgWasmPromise: Promise<Uint8Array> | null = null
+let fontBuffersPromise: Promise<Uint8Array[]> | null = null
+
+function getServerRootUrl() {
+  const nitroMain = (globalThis as unknown as GlobalNitroMain).__nitro_main__
+  if (typeof nitroMain === 'string') {
+    try {
+      return new URL('./', nitroMain)
+    } catch {
+      // fall through
+    }
+  }
+  return pathToFileURL(`${process.cwd()}/`)
+}
+
+function getServerUrl(pathname: string) {
+  return new URL(pathname.replace(/^\//, ''), getServerRootUrl())
+}
+
+export async function getMarkDataUrl() {
+  if (!markDataUrlPromise) {
+    markDataUrlPromise = (async () => {
+      const candidates = [getServerUrl('pilot-mark.png'), getServerUrl('public/pilot-mark.png')]
+      let lastError: unknown = null
+      for (const url of candidates) {
+        try {
+          const buffer = await readFile(url)
+          return `data:image/png;base64,${buffer.toString('base64')}`
+        } catch (error) {
+          lastError = error
+        }
+      }
+      throw lastError
+    })()
+  }
+  return markDataUrlPromise
+}
+
+export async function getResvgWasm() {
+  if (!resvgWasmPromise) {
+    resvgWasmPromise = readFile(getServerUrl('node_modules/@resvg/resvg-wasm/index_bg.wasm')).then(
+      (buffer) => new Uint8Array(buffer),
+    )
+  }
+  return resvgWasmPromise
+}
+
+export async function getFontBuffers() {
+  if (!fontBuffersPromise) {
+    fontBuffersPromise = Promise.all([
+      readFile(
+        getServerUrl(
+          'node_modules/@fontsource/bricolage-grotesque/files/bricolage-grotesque-latin-800-normal.woff2',
+        ),
+      ),
+      readFile(
+        getServerUrl(
+          'node_modules/@fontsource/bricolage-grotesque/files/bricolage-grotesque-latin-500-normal.woff2',
+        ),
+      ),
+      readFile(
+        getServerUrl(
+          'node_modules/@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-500-normal.woff2',
+        ),
+      ),
+    ]).then((buffers) => buffers.map((buffer) => new Uint8Array(buffer)))
+  }
+  return fontBuffersPromise
+}

package/server/og/skillOgSvg.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { buildSkillOgSvg } from './skillOgSvg'
+
+describe('skill OG SVG', () => {
+  it('includes title, description, and labels', () => {
+    const svg = buildSkillOgSvg({
+      markDataUrl: 'data:image/png;base64,AAA=',
+      title: 'Discord Doctor',
+      description: 'Quick diagnosis and repair for Discord bot.',
+      ownerLabel: '@jhillock',
+      versionLabel: 'v1.2.3',
+      footer: 'pilothub.com/jhillock/discord-doctor',
+    })
+
+    expect(svg).toContain('Discord Doctor')
+    expect(svg).toContain('Quick diagnosis and repair')
+    expect(svg).toContain('@jhillock')
+    expect(svg).toContain('v1.2.3')
+    expect(svg).toContain('pilothub.com/jhillock/discord-doctor')
+  })
+
+  it('wraps long titles to avoid clipping', () => {
+    const svg = buildSkillOgSvg({
+      markDataUrl: 'data:image/png;base64,AAA=',
+      title: 'Excalidraw Flowchart',
+      description: 'Create Excalidraw flowcharts from descriptions.',
+      ownerLabel: '@swiftlysisngh',
+      versionLabel: 'v1.0.2',
+      footer: 'pilothub.com/swiftlysisngh/excalidraw-flowchart',
+    })
+
+    const titleBlock = svg.match(/<text[^>]*font-weight="800"[\s\S]*?<\/text>/)?.[0] ?? ''
+    const titleTspans = titleBlock.match(/<tspan /g) ?? []
+    expect(titleTspans.length).toBe(2)
+    expect(svg).toContain('Excalidraw')
+    expect(svg).toContain('Flowchart')
+  })
+
+  it('clips and wraps long descriptions', () => {
+    const longWord = 'a'.repeat(200)
+    const svg = buildSkillOgSvg({
+      markDataUrl: 'data:image/png;base64,AAA=',
+      title: 'Gurkerlcli',
+      description: `Prefix ${longWord} suffix`,
+      ownerLabel: '@pasogott',
+      versionLabel: 'v0.1.0',
+      footer: 'pilothub.com/pasogott/gurkerlcli',
+    })
+
+    expect(svg).toContain('<clipPath id="cardClip">')
+    expect(svg).toContain('clip-path="url(#cardClip)"')
+    expect(svg).not.toContain(longWord)
+    expect(svg).toContain('…')
+
+    const descBlock = svg.match(/<text[^>]*font-size="26"[\s\S]*?<\/text>/)?.[0] ?? ''
+    const descTspans = descBlock.match(/<tspan /g) ?? []
+    expect(descTspans.length).toBeLessThanOrEqual(3)
+  })
+})

package/server/og/skillOgSvg.ts

@@ -0,0 +1,258 @@
+import { FONT_MONO, FONT_SANS } from './ogAssets'
+
+export type SkillOgSvgParams = {
+  markDataUrl: string
+  title: string
+  description: string
+  ownerLabel: string
+  versionLabel: string
+  footer: string
+}
+
+function escapeXml(value: string) {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function glyphWidthFactor(char: string) {
+  if (char === ' ') return 0.28
+  if (char === '…') return 0.62
+  if (/[ilI.,:;|!'"`]/.test(char)) return 0.28
+  if (/[mwMW@%&]/.test(char)) return 0.9
+  if (/[A-Z]/.test(char)) return 0.68
+  if (/[0-9]/.test(char)) return 0.6
+  return 0.56
+}
+
+function estimateTextWidth(value: string, fontSize: number) {
+  let width = 0
+  for (const char of value) width += glyphWidthFactor(char) * fontSize
+  return width
+}
+
+function truncateToWidth(value: string, maxWidth: number, fontSize: number) {
+  const trimmed = value.trim()
+  if (!trimmed) return ''
+  if (estimateTextWidth(trimmed, fontSize) <= maxWidth) return trimmed
+
+  const ellipsis = '…'
+  const ellipsisWidth = estimateTextWidth(ellipsis, fontSize)
+  let out = ''
+  for (const char of trimmed) {
+    const next = out + char
+    if (estimateTextWidth(next, fontSize) + ellipsisWidth > maxWidth) break
+    out = next
+  }
+  return `${out.replace(/\s+$/g, '').replace(/[.。,;:!?]+$/g, '')}${ellipsis}`
+}
+
+function wrapText(value: string, maxWidth: number, fontSize: number, maxLines: number) {
+  const words = value.trim().split(/\s+/).filter(Boolean)
+  const lines: string[] = []
+  let current = ''
+
+  function pushLine(line: string) {
+    if (!line) return
+    lines.push(line)
+  }
+
+  function splitLongWord(word: string) {
+    if (estimateTextWidth(word, fontSize) <= maxWidth) return [word]
+    const parts: string[] = []
+    let remaining = word
+    while (remaining && estimateTextWidth(remaining, fontSize) > maxWidth) {
+      let chunk = ''
+      for (const char of remaining) {
+        const next = chunk + char
+        if (estimateTextWidth(`${next}…`, fontSize) > maxWidth) break
+        chunk = next
+      }
+      if (!chunk) break
+      parts.push(`${chunk}…`)
+      remaining = remaining.slice(chunk.length)
+    }
+    if (remaining) parts.push(remaining)
+    return parts
+  }
+
+  for (const word of words) {
+    if (estimateTextWidth(word, fontSize) > maxWidth) {
+      if (current) {
+        pushLine(current)
+        current = ''
+        if (lines.length >= maxLines - 1) break
+      }
+      const parts = splitLongWord(word)
+      for (const part of parts) {
+        pushLine(part)
+        if (lines.length >= maxLines) break
+      }
+      current = ''
+      if (lines.length >= maxLines - 1) break
+      continue
+    }
+
+    const next = current ? `${current} ${word}` : word
+    if (estimateTextWidth(next, fontSize) <= maxWidth) {
+      current = next
+      continue
+    }
+    pushLine(current)
+    current = word
+    if (lines.length >= maxLines - 1) break
+  }
+  if (lines.length < maxLines && current) pushLine(current)
+  if (lines.length > maxLines) lines.length = maxLines
+
+  const usedWords = lines.join(' ').split(/\s+/).filter(Boolean).length
+  if (usedWords < words.length) {
+    lines[lines.length - 1] = truncateToWidth(lines.at(-1) ?? '', maxWidth, fontSize)
+  }
+  return lines
+}
+
+export function buildSkillOgSvg(params: SkillOgSvgParams) {
+  const rawTitle = params.title.trim() || 'PilotHub Skill'
+  const rawDescription = params.description.trim() || 'Published on PilotHub.'
+
+  const cardX = 72
+  const cardY = 96
+  const cardW = 640
+  const cardH = 456
+  const cardR = 34
+
+  const contentX = 114
+  const contentRightPadding = 28
+  const contentMaxWidth = cardX + cardW - contentX - contentRightPadding
+
+  const titleMaxLines = 2
+  const descMaxLines = 3
+
+  const titleProbeLines = wrapText(rawTitle, contentMaxWidth, 80, titleMaxLines)
+  const titleFontSize = titleProbeLines.length > 1 ? 72 : 80
+  const titleLines = wrapText(rawTitle, contentMaxWidth, titleFontSize, titleMaxLines)
+
+  const descLines = wrapText(rawDescription, contentMaxWidth, 26, descMaxLines)
+  const titleY = titleLines.length > 1 ? 258 : 280
+  const titleLineHeight = 84
+
+  const descY = titleLines.length > 1 ? 395 : 380
+  const descLineHeight = 34
+
+  const pillText = `${params.ownerLabel} • ${params.versionLabel}`
+  const underlineY = cardY + cardH - 80
+  const footerY = cardY + cardH - 18
+
+  const titleTspans = titleLines
+    .map((line, index) => {
+      const dy = index === 0 ? 0 : titleLineHeight
+      return `<tspan x="114" dy="${dy}">${escapeXml(line)}</tspan>`
+    })
+    .join('')
+
+  const descTspans = descLines
+    .map((line, index) => {
+      const dy = index === 0 ? 0 : descLineHeight
+      return `<tspan x="114" dy="${dy}">${escapeXml(line)}</tspan>`
+    })
+    .join('')
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg width="1200" height="630" viewBox="0 0 1200 630" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="630" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#14110F"/>
+      <stop offset="0.55" stop-color="#1A1512"/>
+      <stop offset="1" stop-color="#14110F"/>
+    </linearGradient>
+
+    <radialGradient id="glowOrange" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(260 60) rotate(120) scale(520 420)">
+      <stop stop-color="#E86A47" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#E86A47" stop-opacity="0"/>
+    </radialGradient>
+
+    <radialGradient id="glowSea" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(1050 120) rotate(140) scale(520 420)">
+      <stop stop-color="#4AD8B7" stop-opacity="0.35"/>
+      <stop offset="1" stop-color="#4AD8B7" stop-opacity="0"/>
+    </radialGradient>
+
+    <filter id="softBlur" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="24"/>
+    </filter>
+
+    <filter id="cardShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="18" stdDeviation="26" flood-color="#000000" flood-opacity="0.6"/>
+    </filter>
+
+    <linearGradient id="pill" x1="0" y1="0" x2="520" y2="0" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#E86A47" stop-opacity="0.22"/>
+      <stop offset="1" stop-color="#E86A47" stop-opacity="0.08"/>
+    </linearGradient>
+
+    <linearGradient id="stroke" x1="0" y1="0" x2="0" y2="1">
+      <stop stop-color="#FFFFFF" stop-opacity="0.16"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0.06"/>
+    </linearGradient>
+
+    <clipPath id="cardClip">
+      <rect x="${cardX}" y="${cardY}" width="${cardW}" height="${cardH}" rx="${cardR}"/>
+    </clipPath>
+  </defs>
+
+  <rect width="1200" height="630" fill="url(#bg)"/>
+  <circle cx="260" cy="60" r="520" fill="url(#glowOrange)" filter="url(#softBlur)"/>
+  <circle cx="1050" cy="120" r="520" fill="url(#glowSea)" filter="url(#softBlur)"/>
+
+  <g opacity="0.08">
+    <path d="M0 84 C160 120 340 40 520 86 C700 132 820 210 1200 160" stroke="#FFFFFF" stroke-opacity="0.10" stroke-width="2"/>
+    <path d="M0 188 C220 240 360 160 560 204 C760 248 900 330 1200 300" stroke="#FFFFFF" stroke-opacity="0.08" stroke-width="2"/>
+    <path d="M0 440 C240 380 420 520 620 470 C820 420 960 500 1200 460" stroke="#FFFFFF" stroke-opacity="0.06" stroke-width="2"/>
+  </g>
+
+  <g opacity="0.22" filter="url(#softBlur)">
+    <image href="${params.markDataUrl}" x="740" y="70" width="560" height="560" preserveAspectRatio="xMidYMid meet"/>
+  </g>
+
+  <g filter="url(#cardShadow)">
+    <rect x="${cardX}" y="${cardY}" width="${cardW}" height="${cardH}" rx="${cardR}" fill="#201B18" fill-opacity="0.92" stroke="url(#stroke)"/>
+  </g>
+
+  <g clip-path="url(#cardClip)">
+    <image href="${params.markDataUrl}" x="108" y="134" width="46" height="46" preserveAspectRatio="xMidYMid meet"/>
+
+    <g>
+      <rect x="166" y="136" width="520" height="42" rx="21" fill="url(#pill)" stroke="#E86A47" stroke-opacity="0.28"/>
+      <text x="186" y="163"
+        fill="#F6EFE4"
+        font-size="18"
+        font-weight="600"
+        font-family="${FONT_SANS}, sans-serif"
+        opacity="0.92">${escapeXml(pillText)}</text>
+    </g>
+
+    <text x="114" y="${titleY}"
+      fill="#F6EFE4"
+      font-size="${titleFontSize}"
+      font-weight="800"
+      font-family="${FONT_SANS}, sans-serif">${titleTspans}</text>
+
+    <text x="114" y="${descY}"
+      fill="#C6B8A8"
+      font-size="26"
+      font-weight="500"
+      font-family="${FONT_SANS}, sans-serif">${descTspans}</text>
+
+    <rect x="114" y="${underlineY}" width="110" height="6" rx="3" fill="#E86A47"/>
+    <text x="114" y="${footerY}"
+      fill="#F6EFE4"
+      font-size="20"
+      font-weight="500"
+      opacity="0.90"
+      font-family="${FONT_MONO}, monospace">${escapeXml(params.footer)}</text>
+  </g>
+</svg>`
+}