pilothub 0.0.1

package/packages/pilothub/src/cli.ts

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { stat } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { Command } from 'commander'
+import { getCliBuildLabel, getCliVersion } from './cli/buildInfo.js'
+import { cmdLoginFlow, cmdLogout, cmdWhoami } from './cli/commands/auth.js'
+import { cmdDeleteSkill, cmdUndeleteSkill } from './cli/commands/delete.js'
+import { cmdPublish } from './cli/commands/publish.js'
+import { cmdExplore, cmdInstall, cmdList, cmdSearch, cmdUpdate } from './cli/commands/skills.js'
+import { cmdStarSkill } from './cli/commands/star.js'
+import { cmdSync } from './cli/commands/sync.js'
+import { cmdUnstarSkill } from './cli/commands/unstar.js'
+import { configureCommanderHelp, styleEnvBlock, styleTitle } from './cli/helpStyle.js'
+import { resolvePilotbotDefaultWorkspace } from './cli/pilotbotConfig.js'
+import { DEFAULT_REGISTRY, DEFAULT_SITE } from './cli/registry.js'
+import type { GlobalOpts } from './cli/types.js'
+import { fail } from './cli/ui.js'
+import { readGlobalConfig } from './config.js'
+
+const program = new Command()
+  .name('pilothub')
+  .description(
+    `${styleTitle(`PilotHub CLI ${getCliBuildLabel()}`)}\n${styleEnvBlock(
+      'install, update, search, and publish agent skills.',
+    )}`,
+  )
+  .version(getCliVersion(), '-V, --cli-version', 'Show CLI version')
+  .option('--workdir <dir>', 'Working directory (default: cwd)')
+  .option('--dir <dir>', 'Skills directory (relative to workdir, default: skills)')
+  .option('--site <url>', 'Site base URL (for browser login)')
+  .option('--registry <url>', 'Registry API base URL')
+  .option('--no-input', 'Disable prompts')
+  .showHelpAfterError()
+  .showSuggestionAfterError()
+  .addHelpText(
+    'after',
+    styleEnvBlock('\nEnv:\n  PILOTHUB_SITE\n  PILOTHUB_REGISTRY\n  PILOTHUB_WORKDIR\n'),
+  )
+
+configureCommanderHelp(program)
+
+async function resolveGlobalOpts(): Promise<GlobalOpts> {
+  const raw = program.opts<{ workdir?: string; dir?: string; site?: string; registry?: string }>()
+  const workdir = await resolveWorkdir(raw.workdir)
+  const dir = resolve(workdir, raw.dir ?? 'skills')
+  const site = raw.site ?? process.env.PILOTHUB_SITE ?? DEFAULT_SITE
+  const registrySource = raw.registry ? 'cli' : process.env.PILOTHUB_REGISTRY ? 'env' : 'default'
+  const registry = raw.registry ?? process.env.PILOTHUB_REGISTRY ?? DEFAULT_REGISTRY
+  return { workdir, dir, site, registry, registrySource }
+}
+
+function isInputAllowed() {
+  const globalFlags = program.opts<{ input?: boolean }>()
+  return globalFlags.input !== false
+}
+
+async function resolveWorkdir(explicit?: string) {
+  if (explicit?.trim()) return resolve(explicit.trim())
+  const envWorkdir = process.env.PILOTHUB_WORKDIR?.trim()
+  if (envWorkdir) return resolve(envWorkdir)
+
+  const cwd = resolve(process.cwd())
+  const hasMarker = await hasPilothubMarker(cwd)
+  if (hasMarker) return cwd
+
+  const pilotbotWorkspace = await resolvePilotbotDefaultWorkspace()
+  return pilotbotWorkspace ? resolve(pilotbotWorkspace) : cwd
+}
+
+async function hasPilothubMarker(workdir: string) {
+  const lockfile = join(workdir, '.pilothub', 'lock.json')
+  if (await pathExists(lockfile)) return true
+  const markerDir = join(workdir, '.pilothub')
+  return pathExists(markerDir)
+}
+
+async function pathExists(path: string) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+program
+  .command('login')
+  .description('Log in (opens browser or stores token)')
+  .option('--token <token>', 'API token')
+  .option('--label <label>', 'Token label (browser flow only)', 'CLI token')
+  .option('--no-browser', 'Do not open browser (requires --token)')
+  .action(async (options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdLoginFlow(opts, options, isInputAllowed())
+  })
+
+program
+  .command('logout')
+  .description('Remove stored token')
+  .action(async () => {
+    const opts = await resolveGlobalOpts()
+    await cmdLogout(opts)
+  })
+
+program
+  .command('whoami')
+  .description('Validate token')
+  .action(async () => {
+    const opts = await resolveGlobalOpts()
+    await cmdWhoami(opts)
+  })
+
+const auth = program
+  .command('auth')
+  .description('Authentication commands')
+  .showHelpAfterError()
+  .showSuggestionAfterError()
+
+auth
+  .command('login')
+  .description('Log in (opens browser or stores token)')
+  .option('--token <token>', 'API token')
+  .option('--label <label>', 'Token label (browser flow only)', 'CLI token')
+  .option('--no-browser', 'Do not open browser (requires --token)')
+  .action(async (options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdLoginFlow(opts, options, isInputAllowed())
+  })
+
+auth
+  .command('logout')
+  .description('Remove stored token')
+  .action(async () => {
+    const opts = await resolveGlobalOpts()
+    await cmdLogout(opts)
+  })
+
+auth
+  .command('whoami')
+  .description('Validate token')
+  .action(async () => {
+    const opts = await resolveGlobalOpts()
+    await cmdWhoami(opts)
+  })
+
+program
+  .command('search')
+  .description('Vector search skills')
+  .argument('<query...>', 'Query string')
+  .option('--limit <n>', 'Max results', (value) => Number.parseInt(value, 10))
+  .action(async (queryParts, options) => {
+    const opts = await resolveGlobalOpts()
+    const query = queryParts.join(' ').trim()
+    await cmdSearch(opts, query, options.limit)
+  })
+
+program
+  .command('install')
+  .description('Install into <dir>/<slug>')
+  .argument('<slug>', 'Skill slug')
+  .option('--version <version>', 'Version to install')
+  .option('--force', 'Overwrite existing folder')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdInstall(opts, slug, options.version, options.force)
+  })
+
+program
+  .command('update')
+  .description('Update installed skills')
+  .argument('[slug]', 'Skill slug')
+  .option('--all', 'Update all installed skills')
+  .option('--version <version>', 'Update to specific version (single slug only)')
+  .option('--force', 'Overwrite when local files do not match any version')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdUpdate(opts, slug, options, isInputAllowed())
+  })
+
+program
+  .command('list')
+  .description('List installed skills (from lockfile)')
+  .action(async () => {
+    const opts = await resolveGlobalOpts()
+    await cmdList(opts)
+  })
+
+program
+  .command('explore')
+  .description('Browse latest updated skills from the registry')
+  .option(
+    '--limit <n>',
+    'Number of skills to show (max 200)',
+    (value) => Number.parseInt(value, 10),
+    25,
+  )
+  .option(
+    '--sort <order>',
+    'Sort by newest, downloads, rating, installs, installsAllTime, or trending',
+    'newest',
+  )
+  .option('--json', 'Output JSON')
+  .action(async (options) => {
+    const opts = await resolveGlobalOpts()
+    const limit =
+      typeof options.limit === 'number' && Number.isFinite(options.limit) ? options.limit : 25
+    await cmdExplore(opts, { limit, sort: options.sort, json: options.json })
+  })
+
+program
+  .command('publish')
+  .description('Publish skill from folder')
+  .argument('<path>', 'Skill folder path')
+  .option('--slug <slug>', 'Skill slug')
+  .option('--name <name>', 'Display name')
+  .option('--version <version>', 'Version (semver)')
+  .option('--fork-of <slug[@version]>', 'Mark as a fork of an existing skill')
+  .option('--changelog <text>', 'Changelog text')
+  .option('--tags <tags>', 'Comma-separated tags', 'latest')
+  .action(async (folder, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdPublish(opts, folder, options)
+  })
+
+program
+  .command('delete')
+  .description('Soft-delete a skill (owner/admin only)')
+  .argument('<slug>', 'Skill slug')
+  .option('--yes', 'Skip confirmation')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdDeleteSkill(opts, slug, options, isInputAllowed())
+  })
+
+program
+  .command('undelete')
+  .description('Restore a soft-deleted skill (owner/admin only)')
+  .argument('<slug>', 'Skill slug')
+  .option('--yes', 'Skip confirmation')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdUndeleteSkill(opts, slug, options, isInputAllowed())
+  })
+
+program
+  .command('star')
+  .description('Add a skill to your highlights')
+  .argument('<slug>', 'Skill slug')
+  .option('--yes', 'Skip confirmation')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdStarSkill(opts, slug, options, isInputAllowed())
+  })
+
+program
+  .command('unstar')
+  .description('Remove a skill from your highlights')
+  .argument('<slug>', 'Skill slug')
+  .option('--yes', 'Skip confirmation')
+  .action(async (slug, options) => {
+    const opts = await resolveGlobalOpts()
+    await cmdUnstarSkill(opts, slug, options, isInputAllowed())
+  })
+
+program
+  .command('sync')
+  .description('Scan local skills and publish new/updated ones')
+  .option('--root <dir...>', 'Extra scan roots (one or more)')
+  .option('--all', 'Upload all new/updated skills without prompting')
+  .option('--dry-run', 'Show what would be uploaded')
+  .option('--bump <type>', 'Version bump for updates (patch|minor|major)', 'patch')
+  .option('--changelog <text>', 'Changelog to use for updates (non-interactive)')
+  .option('--tags <tags>', 'Comma-separated tags', 'latest')
+  .option('--concurrency <n>', 'Concurrent registry checks (default: 4)', '4')
+  .action(async (options) => {
+    const opts = await resolveGlobalOpts()
+    const bump = String(options.bump ?? 'patch') as 'patch' | 'minor' | 'major'
+    if (!['patch', 'minor', 'major'].includes(bump)) fail('--bump must be patch|minor|major')
+    const concurrencyRaw = Number(options.concurrency ?? 4)
+    const concurrency = Number.isFinite(concurrencyRaw) ? Math.round(concurrencyRaw) : 4
+    if (concurrency < 1 || concurrency > 32) fail('--concurrency must be between 1 and 32')
+    await cmdSync(
+      opts,
+      {
+        root: options.root,
+        all: options.all,
+        dryRun: options.dryRun,
+        bump,
+        changelog: options.changelog,
+        tags: options.tags,
+        concurrency,
+      },
+      isInputAllowed(),
+    )
+  })
+
+program.action(async () => {
+  const opts = await resolveGlobalOpts()
+  const cfg = await readGlobalConfig()
+  if (cfg?.token) {
+    await cmdSync(opts, {}, isInputAllowed())
+    return
+  }
+  program.outputHelp()
+  process.exitCode = 0
+})
+
+void program.parseAsync(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  fail(message)
+})

package/packages/pilothub/src/config.ts

@@ -0,0 +1,36 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { type GlobalConfig, GlobalConfigSchema, parseArk } from './schema/index.js'
+
+export function getGlobalConfigPath() {
+  const override = process.env.PILOTHUB_CONFIG_PATH?.trim()
+  if (override) return resolve(override)
+  const home = homedir()
+  if (process.platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'pilothub', 'config.json')
+  }
+  const xdg = process.env.XDG_CONFIG_HOME
+  if (xdg) return join(xdg, 'pilothub', 'config.json')
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA
+    if (appData) return join(appData, 'pilothub', 'config.json')
+  }
+  return join(home, '.config', 'pilothub', 'config.json')
+}
+
+export async function readGlobalConfig(): Promise<GlobalConfig | null> {
+  try {
+    const raw = await readFile(getGlobalConfigPath(), 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    return parseArk(GlobalConfigSchema, parsed, 'Global config')
+  } catch {
+    return null
+  }
+}
+
+export async function writeGlobalConfig(config: GlobalConfig) {
+  const path = getGlobalConfigPath()
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+}

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

@@ -0,0 +1,75 @@
+/* @vitest-environment node */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { discoverRegistryFromSite } from './discovery'
+
+describe('discovery', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('returns null on non-ok response', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('nope', { status: 404 })) as unknown as typeof fetch,
+    )
+    await expect(discoverRegistryFromSite('https://example.com')).resolves.toBeNull()
+  })
+
+  it('parses registry config', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ registry: 'https://example.convex.site' }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+      ) as unknown as typeof fetch,
+    )
+    await expect(discoverRegistryFromSite('https://example.com')).resolves.toEqual({
+      apiBase: 'https://example.convex.site',
+      authBase: undefined,
+      minCliVersion: undefined,
+    })
+  })
+
+  it('parses apiBase config', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(
+            JSON.stringify({
+              apiBase: 'https://api.example.com',
+              authBase: 'https://auth.example.com',
+              minCliVersion: '1.2.3',
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          ),
+      ) as unknown as typeof fetch,
+    )
+    await expect(discoverRegistryFromSite('https://example.com')).resolves.toEqual({
+      apiBase: 'https://api.example.com',
+      authBase: 'https://auth.example.com',
+      minCliVersion: '1.2.3',
+    })
+  })
+
+  it('returns null when apiBase is empty', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ apiBase: '' }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+      ) as unknown as typeof fetch,
+    )
+    await expect(discoverRegistryFromSite('https://example.com')).resolves.toBeNull()
+  })
+})

package/packages/pilothub/src/discovery.ts

@@ -0,0 +1,19 @@
+import { parseArk, WellKnownConfigSchema } from './schema/index.js'
+
+export async function discoverRegistryFromSite(siteUrl: string) {
+  const url = new URL('/.well-known/pilothub.json', siteUrl)
+  const response = await fetch(url.toString(), {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+  })
+  if (!response.ok) return null
+  const raw = (await response.json()) as unknown
+  const parsed = parseArk(WellKnownConfigSchema, raw, 'WellKnown config')
+  const apiBase = 'apiBase' in parsed ? parsed.apiBase : parsed.registry
+  if (!apiBase) return null
+  return {
+    apiBase,
+    authBase: parsed.authBase,
+    minCliVersion: parsed.minCliVersion,
+  }
+}

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

@@ -0,0 +1,156 @@
+/* @vitest-environment node */
+
+import { describe, expect, it, vi } from 'vitest'
+import { apiRequest, apiRequestForm, downloadZip } from './http.js'
+import { ApiV1WhoamiResponseSchema } from './schema/index.js'
+
+describe('apiRequest', () => {
+  it('adds bearer token and parses json', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ user: { handle: null } }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    const result = await apiRequest(
+      'https://example.com',
+      { method: 'GET', path: '/x', token: 'clh_token' },
+      ApiV1WhoamiResponseSchema,
+    )
+    expect(result.user.handle).toBeNull()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer clh_token')
+    vi.unstubAllGlobals()
+  })
+
+  it('posts json body', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ ok: true }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await apiRequest('https://example.com', {
+      method: 'POST',
+      path: '/x',
+      body: { a: 1 },
+    })
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('https://example.com/x')
+    expect(init.body).toBe(JSON.stringify({ a: 1 }))
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe('application/json')
+    vi.unstubAllGlobals()
+  })
+
+  it('throws text body on non-200', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      text: async () => 'bad',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(apiRequest('https://example.com', { method: 'GET', path: '/x' })).rejects.toThrow(
+      'bad',
+    )
+    vi.unstubAllGlobals()
+  })
+
+  it('falls back to HTTP status when body is empty', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: async () => '',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(
+      apiRequest('https://example.com', { method: 'GET', url: 'https://example.com/x' }),
+    ).rejects.toThrow('HTTP 500')
+    vi.unstubAllGlobals()
+  })
+
+  it('downloads zip bytes', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    const bytes = await downloadZip('https://example.com', { slug: 'demo', version: '1.0.0' })
+    expect(Array.from(bytes)).toEqual([1, 2, 3])
+    const [url] = fetchMock.mock.calls[0] as [string]
+    expect(url).toContain('slug=demo')
+    expect(url).toContain('version=1.0.0')
+    vi.unstubAllGlobals()
+  })
+
+  it('does not retry on non-retryable errors', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      text: async () => 'nope',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(downloadZip('https://example.com', { slug: 'demo' })).rejects.toThrow('nope')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    vi.unstubAllGlobals()
+  })
+})
+
+describe('apiRequestForm', () => {
+  it('posts form data and returns json', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ ok: true }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    const form = new FormData()
+    form.append('x', '1')
+    const result = await apiRequestForm('https://example.com', {
+      method: 'POST',
+      path: '/upload',
+      token: 'clh_token',
+      form,
+    })
+    expect(result).toEqual({ ok: true })
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.body).toBe(form)
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer clh_token')
+    vi.unstubAllGlobals()
+  })
+
+  it('retries on 429', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 429,
+      text: async () => 'rate limited',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(
+      apiRequestForm('https://example.com', {
+        method: 'POST',
+        path: '/upload',
+        form: new FormData(),
+      }),
+    ).rejects.toThrow('rate limited')
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    vi.unstubAllGlobals()
+  })
+
+  it('falls back to HTTP status when body cannot be read', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      text: async () => {
+        throw new Error('boom')
+      },
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(
+      apiRequestForm('https://example.com', {
+        method: 'POST',
+        path: '/upload',
+        form: new FormData(),
+      }),
+    ).rejects.toThrow('HTTP 400')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    vi.unstubAllGlobals()
+  })
+})