pilothub 0.0.1

package/packages/pilothub/README.md

@@ -0,0 +1,57 @@
+# `pilothub`
+
+PilotHub CLI — install, update, search, and publish agent skills as folders.
+
+## Install
+
+```bash
+# From this repo (shortcut script at repo root)
+bun pilothub --help
+
+# Once published to npm
+# npm i -g pilothub
+```
+
+## Auth (publish)
+
+```bash
+pilothub login
+# or
+pilothub auth login
+
+# Headless / token paste
+# or (token paste / headless)
+pilothub login --token clh_...
+```
+
+Notes:
+
+- Browser login opens `https://pilothub.com/cli/auth` and completes via a loopback callback.
+- Token stored in `~/Library/Application Support/pilothub/config.json` on macOS (override via `PILOTHUB_CONFIG_PATH`).
+
+## Examples
+
+```bash
+pilothub search "postgres backups"
+pilothub install my-skill-pack
+pilothub update --all
+pilothub update --all --no-input --force
+pilothub publish ./my-skill-pack --slug my-skill-pack --name "My Skill Pack" --version 1.2.0 --changelog "Fixes + docs"
+```
+
+## Sync (upload local skills)
+
+```bash
+# Start anywhere; scans workdir first, then legacy Pilotbot/Pilot locations.
+pilothub sync
+
+# Explicit roots + non-interactive dry-run
+pilothub sync --root ../pilotbot/skills --all --dry-run
+```
+
+## Defaults
+
+- Site: `https://pilothub.com` (override via `--site` or `PILOTHUB_SITE`)
+- Registry: discovered from `/.well-known/pilothub.json` on the site (override via `--registry` or `PILOTHUB_REGISTRY`)
+- Workdir: current directory (falls back to Pilotbot workspace if configured; override via `--workdir` or `PILOTHUB_WORKDIR`)
+- Install dir: `./skills` under workdir (override via `--dir`)

package/packages/pilothub/bin/pilothub.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.js')

package/packages/pilothub/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pilothub",
+  "version": "0.3.0",
+  "description": "PilotHub CLI \\u2014 install, update, search, and publish agent skills.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pilothub": "bin/pilothub.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --enable-source-maps dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "arktype": "^2.1.29",
+    "commander": "^14.0.2",
+    "fflate": "^0.8.2",
+    "ignore": "^7.0.5",
+    "json5": "^2.2.3",
+    "mime": "^4.1.0",
+    "ora": "^9.0.0",
+    "p-retry": "^7.1.1",
+    "semver": "^7.7.3",
+    "undici": "^7.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/packages/pilothub/src/browserAuth.test.ts

@@ -0,0 +1,96 @@
+/* @vitest-environment node */
+
+import { describe, expect, it } from 'vitest'
+import {
+  buildCliAuthUrl,
+  isAllowedLoopbackRedirectUri,
+  startLoopbackAuthServer,
+} from './browserAuth'
+
+describe('browserAuth', () => {
+  it('builds auth url', () => {
+    const url = buildCliAuthUrl({
+      siteUrl: 'https://example.com',
+      redirectUri: 'http://127.0.0.1:1234/callback',
+      label: 'CLI token',
+      state: 'state123',
+    })
+    expect(url).toContain('https://example.com/cli/auth?')
+    expect(url).toContain('redirect_uri=')
+    expect(url).toContain('label_b64=')
+    expect(url).toContain('state=')
+  })
+
+  it('builds auth url without label', () => {
+    const url = buildCliAuthUrl({
+      siteUrl: 'https://example.com',
+      redirectUri: 'http://127.0.0.1:1234/callback',
+      state: 'state123',
+    })
+    expect(url).toContain('https://example.com/cli/auth?')
+    expect(url).not.toContain('label_b64=')
+  })
+
+  it('accepts only loopback http redirect uris', () => {
+    expect(isAllowedLoopbackRedirectUri('http://127.0.0.1:1234/callback')).toBe(true)
+    expect(isAllowedLoopbackRedirectUri('http://localhost:1234/callback')).toBe(true)
+    expect(isAllowedLoopbackRedirectUri('http://[::1]:1234/callback')).toBe(true)
+    expect(isAllowedLoopbackRedirectUri('https://127.0.0.1:1234/callback')).toBe(false)
+    expect(isAllowedLoopbackRedirectUri('http://evil.com/callback')).toBe(false)
+    expect(isAllowedLoopbackRedirectUri('not a url')).toBe(false)
+  })
+
+  it('receives token via loopback server', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 2000 })
+    const payload = {
+      token: 'clh_test',
+      registry: 'https://example.convex.site',
+      state: server.state,
+    }
+    await fetch(server.redirectUri.replace('/callback', '/token'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    await expect(server.waitForResult()).resolves.toEqual(payload)
+  })
+
+  it('serves callback html', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 2000 })
+    const response = await fetch(server.redirectUri)
+    expect(response.status).toBe(200)
+    const text = await response.text()
+    expect(text).toContain('PilotHub CLI Login')
+    server.close()
+  })
+
+  it('returns 404 for unknown routes', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 2000 })
+    const response = await fetch(server.redirectUri.replace('/callback', '/nope'))
+    expect(response.status).toBe(404)
+    server.close()
+  })
+
+  it('rejects invalid json payloads', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 2000 })
+    const tokenUrl = server.redirectUri.replace('/callback', '/token')
+    const response = await fetch(tokenUrl, { method: 'POST', body: '{' })
+    expect(response.status).toBe(400)
+    await expect(server.waitForResult()).rejects.toThrow()
+  })
+
+  it('rejects state mismatches', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 2000 })
+    await fetch(server.redirectUri.replace('/callback', '/token'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token: 'clh_test', registry: 'https://example.com', state: 'nope' }),
+    })
+    await expect(server.waitForResult()).rejects.toThrow(/state mismatch/i)
+  })
+
+  it('times out waiting for login', async () => {
+    const server = await startLoopbackAuthServer({ timeoutMs: 25 })
+    await expect(server.waitForResult()).rejects.toThrow(/timed out waiting for browser login/i)
+  })
+})

package/packages/pilothub/src/browserAuth.ts

@@ -0,0 +1,174 @@
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+
+export type LoopbackAuthResult = {
+  token: string
+  registry?: string
+  state?: string
+}
+
+export function buildCliAuthUrl(params: {
+  siteUrl: string
+  redirectUri: string
+  label?: string
+  state: string
+}) {
+  const url = new URL('/cli/auth', params.siteUrl)
+  url.searchParams.set('redirect_uri', params.redirectUri)
+  if (params.label) url.searchParams.set('label_b64', encodeBase64Url(params.label))
+  url.searchParams.set('state', params.state)
+  return url.toString()
+}
+
+export function isAllowedLoopbackRedirectUri(value: string) {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return false
+  }
+  if (url.protocol !== 'http:') return false
+  const host = url.hostname.toLowerCase()
+  if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1' && host !== '[::1]') {
+    return false
+  }
+  return true
+}
+
+export async function startLoopbackAuthServer(params?: { timeoutMs?: number }) {
+  const timeoutMs = params?.timeoutMs ?? 5 * 60_000
+  const expectedState = generateState()
+
+  let resolveToken: ((value: LoopbackAuthResult) => void) | null = null
+  let rejectToken: ((error: Error) => void) | null = null
+  const tokenPromise = new Promise<LoopbackAuthResult>((resolve, reject) => {
+    resolveToken = resolve
+    rejectToken = reject
+  })
+
+  const server = createServer((req, res) => {
+    const method = req.method ?? 'GET'
+    const url = req.url ?? '/'
+
+    if (method === 'GET' && (url === '/' || url.startsWith('/callback'))) {
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'text/html; charset=utf-8')
+      res.end(CALLBACK_HTML)
+      return
+    }
+
+    if (method === 'POST' && url === '/token') {
+      const chunks: Uint8Array[] = []
+      req.on('data', (chunk) => chunks.push(chunk as Uint8Array))
+      req.on('end', () => {
+        try {
+          const raw = Buffer.concat(chunks).toString('utf8')
+          const parsed = JSON.parse(raw) as unknown
+          if (!parsed || typeof parsed !== 'object') throw new Error('invalid payload')
+          const token = (parsed as { token?: unknown }).token
+          const registry = (parsed as { registry?: unknown }).registry
+          const state = (parsed as { state?: unknown }).state
+          if (typeof token !== 'string' || !token.trim()) throw new Error('token required')
+          if (typeof state !== 'string' || state !== expectedState) {
+            throw new Error('state mismatch')
+          }
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'application/json')
+          res.end(JSON.stringify({ ok: true }))
+          resolveToken?.({
+            token: token.trim(),
+            registry: typeof registry === 'string' ? registry : undefined,
+            state,
+          })
+        } catch (error) {
+          res.statusCode = 400
+          res.setHeader('Content-Type', 'application/json')
+          res.end(JSON.stringify({ ok: false }))
+          const message = error instanceof Error ? error.message : 'invalid payload'
+          rejectToken?.(new Error(message))
+        } finally {
+          server.close()
+        }
+      })
+      return
+    }
+
+    res.statusCode = 404
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+    res.end('Not found')
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => resolve())
+  })
+  const address = server.address() as AddressInfo | null
+  if (!address) {
+    server.close()
+    throw new Error('Failed to bind loopback server')
+  }
+  const redirectUri = `http://127.0.0.1:${address.port}/callback`
+
+  const timeout = setTimeout(() => {
+    server.close()
+    rejectToken?.(new Error('Timed out waiting for browser login'))
+  }, timeoutMs)
+  tokenPromise.finally(() => clearTimeout(timeout)).catch(() => {})
+
+  return {
+    redirectUri,
+    state: expectedState,
+    waitForResult: () => tokenPromise,
+    close: () => server.close(),
+  }
+}
+
+const CALLBACK_HTML = `<!doctype html>
+<html lang="en">
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>PilotHub CLI Login</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif; padding: 24px; }
+    .card { max-width: 560px; margin: 40px auto; padding: 18px 16px; border: 1px solid rgba(127,127,127,.35); border-radius: 12px; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  </style>
+  <body>
+    <div class="card">
+      <h1 style="margin: 0 0 10px; font-size: 18px;">Completing login…</h1>
+      <p id="status" style="margin: 0; opacity: .8;">Waiting for token.</p>
+    </div>
+    <script>
+      const statusEl = document.getElementById('status')
+      const params = new URLSearchParams(location.hash.replace(/^#/, ''))
+      const token = params.get('token')
+      const registry = params.get('registry')
+      const state = params.get('state')
+      if (!token) {
+        statusEl.textContent = 'Missing token in URL. You can close this tab and try again.'
+      } else if (!state) {
+        statusEl.textContent = 'Missing state in URL. You can close this tab and try again.'
+      } else {
+        fetch('/token', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token, registry, state }),
+        }).then(() => {
+          statusEl.textContent = 'Logged in. You can close this tab.'
+          setTimeout(() => window.close(), 250)
+        }).catch(() => {
+          statusEl.textContent = 'Failed to send token to CLI. You can close this tab and try again.'
+        })
+      }
+    </script>
+  </body>
+</html>`
+
+function encodeBase64Url(value: string) {
+  return Buffer.from(value, 'utf8').toString('base64url')
+}
+
+function generateState() {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString('hex')
+}

package/packages/pilothub/src/cli/buildInfo.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+type PackageJson = { version?: string }
+
+function readPackageVersion() {
+  try {
+    const path = join(dirname(fileURLToPath(import.meta.url)), '../../package.json')
+    const raw = readFileSync(path, 'utf8')
+    const pkg = JSON.parse(raw) as PackageJson
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+function shortCommit(value: string) {
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  if (trimmed.length <= 8) return trimmed
+  return trimmed.slice(0, 8)
+}
+
+export function getCliCommit() {
+  const candidates = [
+    process.env.PILOTHUB_COMMIT,
+    process.env.VERCEL_GIT_COMMIT_SHA,
+    process.env.GITHUB_SHA,
+    process.env.COMMIT_SHA,
+  ]
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    const short = shortCommit(candidate)
+    if (short) return short
+  }
+  return readGitCommitFromCwd()
+}
+
+export function getCliVersion() {
+  return readPackageVersion()
+}
+
+export function getCliBuildLabel() {
+  const version = getCliVersion()
+  const commit = getCliCommit()
+  return commit ? `v${version} (${commit})` : `v${version}`
+}
+
+function readGitCommitFromCwd() {
+  try {
+    const gitDir = findGitDir(process.cwd())
+    if (!gitDir) return null
+    const headPath = join(gitDir, 'HEAD')
+    if (!existsSync(headPath)) return null
+    const head = readFileSync(headPath, 'utf8').trim()
+    if (!head) return null
+    if (!head.startsWith('ref:')) return shortCommit(head)
+    const ref = head.replace(/^ref:\s*/, '').trim()
+    if (!ref) return null
+    const refPath = join(gitDir, ref)
+    if (!existsSync(refPath)) return null
+    const sha = readFileSync(refPath, 'utf8').trim()
+    return shortCommit(sha)
+  } catch {
+    return null
+  }
+}
+
+function findGitDir(start: string) {
+  let current = resolve(start)
+  for (;;) {
+    const dotGit = join(current, '.git')
+    if (existsSync(dotGit)) {
+      try {
+        const stat = statSync(dotGit)
+        if (stat.isDirectory()) return dotGit
+      } catch {
+        // ignore
+      }
+      try {
+        const content = readFileSync(dotGit, 'utf8').trim()
+        const match = content.match(/^gitdir:\s*(.+)$/)
+        if (match?.[1]) return resolve(current, match[1])
+      } catch {
+        return dotGit
+      }
+      return dotGit
+    }
+    const parent = resolve(current, '..')
+    if (parent === current) return null
+    current = parent
+  }
+}

package/packages/pilothub/src/cli/commands/auth.ts

@@ -0,0 +1,97 @@
+import { buildCliAuthUrl, startLoopbackAuthServer } from '../../browserAuth.js'
+import { readGlobalConfig, writeGlobalConfig } from '../../config.js'
+import { discoverRegistryFromSite } from '../../discovery.js'
+import { apiRequest } from '../../http.js'
+import { ApiRoutes, ApiV1WhoamiResponseSchema } from '../../schema/index.js'
+import { getRegistry } from '../registry.js'
+import type { GlobalOpts } from '../types.js'
+import { createSpinner, fail, formatError, openInBrowser, promptHidden } from '../ui.js'
+
+export async function cmdLoginFlow(
+  opts: GlobalOpts,
+  options: { token?: string; label?: string; browser?: boolean },
+  inputAllowed: boolean,
+) {
+  if (options.token) {
+    await cmdLogin(opts, options.token, inputAllowed)
+    return
+  }
+
+  if (options.browser === false) {
+    fail('Token required (use --token or remove --no-browser)')
+  }
+
+  const label = String(options.label ?? 'CLI token').trim() || 'CLI token'
+  const receiver = await startLoopbackAuthServer()
+  const discovery = await discoverRegistryFromSite(opts.site).catch(() => null)
+  const authBase = discovery?.authBase?.trim() || opts.site
+  const authUrl = buildCliAuthUrl({
+    siteUrl: authBase,
+    redirectUri: receiver.redirectUri,
+    label,
+    state: receiver.state,
+  })
+
+  console.log(`Opening browser: ${authUrl}`)
+  openInBrowser(authUrl)
+
+  const result = await receiver.waitForResult()
+  const registry = result.registry?.trim() || opts.registry
+  await cmdLogin({ ...opts, registry }, result.token, inputAllowed)
+}
+
+export async function cmdLogin(
+  opts: GlobalOpts,
+  tokenFlag: string | undefined,
+  inputAllowed: boolean,
+) {
+  if (!tokenFlag && !inputAllowed) fail('Token required (use --token or remove --no-input)')
+
+  const token = tokenFlag || (await promptHidden('PilotHub token: '))
+  if (!token) fail('Token required')
+
+  const registry = await getRegistry(opts, { cache: true })
+  const spinner = createSpinner('Verifying token')
+  try {
+    const whoami = await apiRequest(
+      registry,
+      { method: 'GET', path: ApiRoutes.whoami, token },
+      ApiV1WhoamiResponseSchema,
+    )
+    if (!whoami.user) fail('Login failed')
+
+    await writeGlobalConfig({ registry, token })
+    const handle = whoami.user.handle ? `@${whoami.user.handle}` : 'unknown user'
+    spinner.succeed(`OK. Logged in as ${handle}.`)
+  } catch (error) {
+    spinner.fail(formatError(error))
+    throw error
+  }
+}
+
+export async function cmdLogout(opts: GlobalOpts) {
+  const cfg = await readGlobalConfig()
+  const registry = cfg?.registry || (await getRegistry(opts, { cache: true }))
+  await writeGlobalConfig({ registry, token: undefined })
+  console.log('OK. Logged out.')
+}
+
+export async function cmdWhoami(opts: GlobalOpts) {
+  const cfg = await readGlobalConfig()
+  const token = cfg?.token
+  if (!token) fail('Not logged in. Run: pilothub login')
+  const registry = await getRegistry(opts, { cache: true })
+
+  const spinner = createSpinner('Checking token')
+  try {
+    const whoami = await apiRequest(
+      registry,
+      { method: 'GET', path: ApiRoutes.whoami, token },
+      ApiV1WhoamiResponseSchema,
+    )
+    spinner.succeed(whoami.user.handle ?? 'unknown')
+  } catch (error) {
+    spinner.fail(formatError(error))
+    throw error
+  }
+}

package/packages/pilothub/src/cli/commands/delete.test.ts

@@ -0,0 +1,73 @@
+/* @vitest-environment node */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { GlobalOpts } from '../types'
+
+vi.mock('../../config.js', () => ({
+  readGlobalConfig: vi.fn(async () => ({ registry: 'https://pilothub.com', token: 'tkn' })),
+}))
+
+vi.mock('../registry.js', () => ({
+  getRegistry: vi.fn(async () => 'https://pilothub.com'),
+}))
+
+const mockApiRequest = vi.fn()
+vi.mock('../../http.js', () => ({
+  apiRequest: (registry: unknown, args: unknown, schema?: unknown) =>
+    mockApiRequest(registry, args, schema),
+}))
+
+const mockFail = vi.fn((message: string) => {
+  throw new Error(message)
+})
+
+vi.mock('../ui.js', () => ({
+  createSpinner: vi.fn(() => ({ succeed: vi.fn(), fail: vi.fn() })),
+  fail: (message: string) => mockFail(message),
+  formatError: (error: unknown) => (error instanceof Error ? error.message : String(error)),
+  isInteractive: () => false,
+  promptConfirm: vi.fn(async () => true),
+}))
+
+const { cmdDeleteSkill, cmdUndeleteSkill } = await import('./delete')
+
+function makeOpts(): GlobalOpts {
+  return {
+    workdir: '/work',
+    dir: '/work/skills',
+    site: 'https://pilothub.com',
+    registry: 'https://pilothub.com',
+    registrySource: 'default',
+  }
+}
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('delete/undelete', () => {
+  it('requires --yes when input is disabled', async () => {
+    await expect(cmdDeleteSkill(makeOpts(), 'demo', {}, false)).rejects.toThrow(/--yes/i)
+    await expect(cmdUndeleteSkill(makeOpts(), 'demo', {}, false)).rejects.toThrow(/--yes/i)
+  })
+
+  it('calls delete endpoint with --yes', async () => {
+    mockApiRequest.mockResolvedValueOnce({ ok: true })
+    await cmdDeleteSkill(makeOpts(), 'demo', { yes: true }, false)
+    expect(mockApiRequest).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ method: 'DELETE', path: '/api/v1/skills/demo' }),
+      expect.anything(),
+    )
+  })
+
+  it('calls undelete endpoint with --yes', async () => {
+    mockApiRequest.mockResolvedValueOnce({ ok: true })
+    await cmdUndeleteSkill(makeOpts(), 'demo', { yes: true }, false)
+    expect(mockApiRequest).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ method: 'POST', path: '/api/v1/skills/demo/undelete' }),
+      expect.anything(),
+    )
+  })
+})