pilothub 0.0.1

package/packages/schema/src/index.ts

@@ -0,0 +1,5 @@
+export type { ArkValidator } from './ark.js'
+export { formatArkErrors, parseArk } from './ark.js'
+export { ApiRoutes, LegacyApiRoutes } from './routes.js'
+export * from './schemas.js'
+export * from './textFiles.js'

package/packages/schema/src/routes.ts

@@ -0,0 +1,22 @@
+export const LegacyApiRoutes = {
+  download: '/api/download',
+  search: '/api/search',
+  skill: '/api/skill',
+  skillResolve: '/api/skill/resolve',
+  cliWhoami: '/api/cli/whoami',
+  cliUploadUrl: '/api/cli/upload-url',
+  cliPublish: '/api/cli/publish',
+  cliTelemetrySync: '/api/cli/telemetry/sync',
+  cliSkillDelete: '/api/cli/skill/delete',
+  cliSkillUndelete: '/api/cli/skill/undelete',
+} as const
+
+export const ApiRoutes = {
+  search: '/api/v1/search',
+  resolve: '/api/v1/resolve',
+  download: '/api/v1/download',
+  skills: '/api/v1/skills',
+  stars: '/api/v1/stars',
+  souls: '/api/v1/souls',
+  whoami: '/api/v1/whoami',
+} as const

package/packages/schema/src/schemas.test.ts

@@ -0,0 +1,123 @@
+/* @vitest-environment node */
+
+import { describe, expect, it } from 'vitest'
+import { parseArk } from './ark'
+import {
+  ApiSearchResponseSchema,
+  CliPublishRequestSchema,
+  CliSkillDeleteRequestSchema,
+  LockfileSchema,
+  WellKnownConfigSchema,
+} from './schemas'
+
+describe('pilothub-schema', () => {
+  it('parses lockfile records', () => {
+    const lock = parseArk(
+      LockfileSchema,
+      { version: 1, skills: { demo: { version: '1.0.0', installedAt: 123 } } },
+      'Lockfile',
+    )
+    expect(lock.skills.demo?.version).toBe('1.0.0')
+  })
+
+  it('allows publish payload without tags', () => {
+    const payload = parseArk(
+      CliPublishRequestSchema,
+      {
+        slug: 'demo',
+        displayName: 'Demo',
+        version: '1.0.0',
+        changelog: '',
+        files: [{ path: 'SKILL.md', size: 1, storageId: 's', sha256: 'x' }],
+      },
+      'Publish payload',
+    )
+    expect(payload.tags).toBeUndefined()
+    expect(payload.files[0]?.path).toBe('SKILL.md')
+  })
+
+  it('accepts publish payload with github source', () => {
+    const payload = parseArk(
+      CliPublishRequestSchema,
+      {
+        slug: 'demo',
+        displayName: 'Demo',
+        version: '1.0.0',
+        changelog: '',
+        source: {
+          kind: 'github',
+          url: 'https://github.com/example/demo',
+          repo: 'example/demo',
+          ref: 'main',
+          commit: 'abc123',
+          path: '.',
+          importedAt: 123,
+        },
+        files: [{ path: 'SKILL.md', size: 1, storageId: 's', sha256: 'x' }],
+      },
+      'Publish payload',
+    )
+    expect(payload.source?.repo).toBe('example/demo')
+  })
+
+  it('parses well-known config', () => {
+    expect(
+      parseArk(WellKnownConfigSchema, { registry: 'https://example.convex.site' }, 'WellKnown'),
+    ).toEqual({ registry: 'https://example.convex.site' })
+
+    expect(
+      parseArk(
+        WellKnownConfigSchema,
+        { registry: 'https://example.convex.site', authBase: 'https://pilothub.com' },
+        'WellKnown',
+      ),
+    ).toEqual({ registry: 'https://example.convex.site', authBase: 'https://pilothub.com' })
+
+    expect(
+      parseArk(
+        WellKnownConfigSchema,
+        { apiBase: 'https://example.convex.site', minCliVersion: '0.1.0' },
+        'WellKnown',
+      ),
+    ).toEqual({ apiBase: 'https://example.convex.site', minCliVersion: '0.1.0' })
+
+    const combined = parseArk(
+      WellKnownConfigSchema,
+      {
+        apiBase: 'https://pilothub.com',
+        registry: 'https://pilothub.com',
+        authBase: 'https://pilothub.com',
+      },
+      'WellKnown',
+    ) as unknown as Record<string, unknown>
+    expect(combined.apiBase).toBe('https://pilothub.com')
+    expect(combined.registry).toBe('https://pilothub.com')
+  })
+
+  it('throws labeled errors', () => {
+    expect(() => parseArk(LockfileSchema, null, 'Lockfile')).toThrow(/Lockfile:/)
+  })
+
+  it('parses search results arrays', () => {
+    expect(parseArk(ApiSearchResponseSchema, { results: [] }, 'Search')).toEqual({ results: [] })
+
+    const parsed = parseArk(
+      ApiSearchResponseSchema,
+      {
+        results: [
+          { slug: 'a', displayName: 'A', version: '1.0.0', score: 0.9 },
+          { slug: 'b', displayName: 'B', version: null, score: 0.1 },
+        ],
+      },
+      'Search',
+    )
+    expect(parsed.results).toHaveLength(2)
+    expect(parsed.results[0]?.slug).toBe('a')
+  })
+
+  it('parses delete request payload', () => {
+    expect(parseArk(CliSkillDeleteRequestSchema, { slug: 'demo' }, 'Delete')).toEqual({
+      slug: 'demo',
+    })
+  })
+})

package/packages/schema/src/schemas.ts

@@ -0,0 +1,287 @@
+import { type inferred, type } from 'arktype'
+
+export const GlobalConfigSchema = type({
+  registry: 'string',
+  token: 'string?',
+})
+export type GlobalConfig = (typeof GlobalConfigSchema)[inferred]
+
+export const WellKnownConfigSchema = type({
+  apiBase: 'string',
+  authBase: 'string?',
+  minCliVersion: 'string?',
+}).or({
+  registry: 'string',
+  authBase: 'string?',
+  minCliVersion: 'string?',
+})
+export type WellKnownConfig = (typeof WellKnownConfigSchema)[inferred]
+
+export const LockfileSchema = type({
+  version: '1',
+  skills: {
+    '[string]': {
+      version: 'string|null',
+      installedAt: 'number',
+    },
+  },
+})
+export type Lockfile = (typeof LockfileSchema)[inferred]
+
+export const ApiCliWhoamiResponseSchema = type({
+  user: {
+    handle: 'string|null',
+  },
+})
+
+export const ApiSearchResponseSchema = type({
+  results: type({
+    slug: 'string?',
+    displayName: 'string?',
+    version: 'string|null?',
+    score: 'number',
+  }).array(),
+})
+
+export const ApiSkillMetaResponseSchema = type({
+  latestVersion: type({
+    version: 'string',
+  }).optional(),
+  skill: 'unknown|null?',
+})
+
+export const ApiCliUploadUrlResponseSchema = type({
+  uploadUrl: 'string',
+})
+
+export const ApiUploadFileResponseSchema = type({
+  storageId: 'string',
+})
+
+export const CliPublishFileSchema = type({
+  path: 'string',
+  size: 'number',
+  storageId: 'string',
+  sha256: 'string',
+  contentType: 'string?',
+})
+export type CliPublishFile = (typeof CliPublishFileSchema)[inferred]
+
+export const PublishSourceSchema = type({
+  kind: '"github"',
+  url: 'string',
+  repo: 'string',
+  ref: 'string',
+  commit: 'string',
+  path: 'string',
+  importedAt: 'number',
+})
+
+export const CliPublishRequestSchema = type({
+  slug: 'string',
+  displayName: 'string',
+  version: 'string',
+  changelog: 'string',
+  tags: 'string[]?',
+  source: PublishSourceSchema.optional(),
+  forkOf: type({
+    slug: 'string',
+    version: 'string?',
+  }).optional(),
+  files: CliPublishFileSchema.array(),
+})
+export type CliPublishRequest = (typeof CliPublishRequestSchema)[inferred]
+
+export const ApiCliPublishResponseSchema = type({
+  ok: 'true',
+  skillId: 'string',
+  versionId: 'string',
+})
+
+export const CliSkillDeleteRequestSchema = type({
+  slug: 'string',
+})
+export type CliSkillDeleteRequest = (typeof CliSkillDeleteRequestSchema)[inferred]
+
+export const ApiCliSkillDeleteResponseSchema = type({
+  ok: 'true',
+})
+
+export const ApiSkillResolveResponseSchema = type({
+  match: type({ version: 'string' }).or('null'),
+  latestVersion: type({ version: 'string' }).or('null'),
+})
+
+export const CliTelemetrySyncRequestSchema = type({
+  roots: type({
+    rootId: 'string',
+    label: 'string',
+    skills: type({
+      slug: 'string',
+      version: 'string|null?',
+    }).array(),
+  }).array(),
+})
+export type CliTelemetrySyncRequest = (typeof CliTelemetrySyncRequestSchema)[inferred]
+
+export const ApiCliTelemetrySyncResponseSchema = type({
+  ok: 'true',
+})
+
+export const ApiV1WhoamiResponseSchema = type({
+  user: {
+    handle: 'string|null',
+    displayName: 'string|null?',
+    image: 'string|null?',
+  },
+})
+
+export const ApiV1SearchResponseSchema = type({
+  results: type({
+    slug: 'string?',
+    displayName: 'string?',
+    summary: 'string|null?',
+    version: 'string|null?',
+    score: 'number',
+    updatedAt: 'number?',
+  }).array(),
+})
+
+export const ApiV1SkillListResponseSchema = type({
+  items: type({
+    slug: 'string',
+    displayName: 'string',
+    summary: 'string|null?',
+    tags: 'unknown',
+    stats: 'unknown',
+    createdAt: 'number',
+    updatedAt: 'number',
+    latestVersion: type({
+      version: 'string',
+      createdAt: 'number',
+      changelog: 'string',
+    }).optional(),
+  }).array(),
+  nextCursor: 'string|null',
+})
+
+export const ApiV1SkillResponseSchema = type({
+  skill: type({
+    slug: 'string',
+    displayName: 'string',
+    summary: 'string|null?',
+    tags: 'unknown',
+    stats: 'unknown',
+    createdAt: 'number',
+    updatedAt: 'number',
+  }).or('null'),
+  latestVersion: type({
+    version: 'string',
+    createdAt: 'number',
+    changelog: 'string',
+  }).or('null'),
+  owner: type({
+    handle: 'string|null',
+    displayName: 'string|null?',
+    image: 'string|null?',
+  }).or('null'),
+})
+
+export const ApiV1SkillVersionListResponseSchema = type({
+  items: type({
+    version: 'string',
+    createdAt: 'number',
+    changelog: 'string',
+    changelogSource: '"auto"|"user"|null?',
+  }).array(),
+  nextCursor: 'string|null',
+})
+
+export const ApiV1SkillVersionResponseSchema = type({
+  version: type({
+    version: 'string',
+    createdAt: 'number',
+    changelog: 'string',
+    changelogSource: '"auto"|"user"|null?',
+    files: 'unknown?',
+  }).or('null'),
+  skill: type({
+    slug: 'string',
+    displayName: 'string',
+  }).or('null'),
+})
+
+export const ApiV1SkillResolveResponseSchema = type({
+  match: type({ version: 'string' }).or('null'),
+  latestVersion: type({ version: 'string' }).or('null'),
+})
+
+export const ApiV1PublishResponseSchema = type({
+  ok: 'true',
+  skillId: 'string',
+  versionId: 'string',
+})
+
+export const ApiV1DeleteResponseSchema = type({
+  ok: 'true',
+})
+
+export const ApiV1StarResponseSchema = type({
+  ok: 'true',
+  starred: 'boolean',
+  alreadyStarred: 'boolean',
+})
+
+export const ApiV1UnstarResponseSchema = type({
+  ok: 'true',
+  unstarred: 'boolean',
+  alreadyUnstarred: 'boolean',
+})
+
+export const SkillInstallSpecSchema = type({
+  id: 'string?',
+  kind: '"brew"|"node"|"go"|"uv"',
+  label: 'string?',
+  bins: 'string[]?',
+  formula: 'string?',
+  tap: 'string?',
+  package: 'string?',
+  module: 'string?',
+})
+export type SkillInstallSpec = (typeof SkillInstallSpecSchema)[inferred]
+
+export const NixPluginSpecSchema = type({
+  plugin: 'string',
+  systems: 'string[]?',
+})
+export type NixPluginSpec = (typeof NixPluginSpecSchema)[inferred]
+
+export const PilotbotConfigSpecSchema = type({
+  requiredEnv: 'string[]?',
+  stateDirs: 'string[]?',
+  example: 'string?',
+})
+export type PilotbotConfigSpec = (typeof PilotbotConfigSpecSchema)[inferred]
+
+export const PilotbotRequiresSchema = type({
+  bins: 'string[]?',
+  anyBins: 'string[]?',
+  env: 'string[]?',
+  config: 'string[]?',
+})
+export type PilotbotRequires = (typeof PilotbotRequiresSchema)[inferred]
+
+export const PilotbotSkillMetadataSchema = type({
+  always: 'boolean?',
+  skillKey: 'string?',
+  primaryEnv: 'string?',
+  emoji: 'string?',
+  homepage: 'string?',
+  os: 'string[]?',
+  cliHelp: 'string?',
+  requires: PilotbotRequiresSchema.optional(),
+  install: SkillInstallSpecSchema.array().optional(),
+  nix: NixPluginSpecSchema.optional(),
+  config: PilotbotConfigSpecSchema.optional(),
+})
+export type PilotbotSkillMetadata = (typeof PilotbotSkillMetadataSchema)[inferred]

package/packages/schema/src/textFiles.test.ts

@@ -0,0 +1,23 @@
+/* @vitest-environment node */
+
+import { describe, expect, it } from 'vitest'
+import * as schema from '.'
+import { isTextContentType, TEXT_FILE_EXTENSION_SET } from './textFiles'
+
+describe('pilothub-schema textFiles', () => {
+  it('exports text-file extension set', () => {
+    expect(TEXT_FILE_EXTENSION_SET.has('md')).toBe(true)
+    expect(TEXT_FILE_EXTENSION_SET.has('exe')).toBe(false)
+  })
+
+  it('detects text content types with parameters', () => {
+    expect(isTextContentType('text/plain; charset=utf-8')).toBe(true)
+    expect(isTextContentType('application/json; charset=utf-8')).toBe(true)
+    expect(isTextContentType('application/octet-stream')).toBe(false)
+  })
+
+  it('re-exports helpers from index', () => {
+    expect(typeof schema.isTextContentType).toBe('function')
+    expect(schema.isTextContentType('application/markdown')).toBe(true)
+  })
+})

package/packages/schema/src/textFiles.ts

@@ -0,0 +1,66 @@
+const RAW_TEXT_FILE_EXTENSIONS = [
+  'md',
+  'mdx',
+  'txt',
+  'json',
+  'json5',
+  'yaml',
+  'yml',
+  'toml',
+  'js',
+  'cjs',
+  'mjs',
+  'ts',
+  'tsx',
+  'jsx',
+  'py',
+  'sh',
+  'rb',
+  'go',
+  'rs',
+  'swift',
+  'kt',
+  'java',
+  'cs',
+  'cpp',
+  'c',
+  'h',
+  'hpp',
+  'sql',
+  'csv',
+  'ini',
+  'cfg',
+  'env',
+  'xml',
+  'html',
+  'css',
+  'scss',
+  'sass',
+  'svg',
+] as const
+
+export const TEXT_FILE_EXTENSIONS = RAW_TEXT_FILE_EXTENSIONS
+export const TEXT_FILE_EXTENSION_SET = new Set<string>(TEXT_FILE_EXTENSIONS)
+
+const RAW_TEXT_CONTENT_TYPES = [
+  'application/json',
+  'application/xml',
+  'application/yaml',
+  'application/x-yaml',
+  'application/toml',
+  'application/javascript',
+  'application/typescript',
+  'application/markdown',
+  'image/svg+xml',
+] as const
+
+export const TEXT_CONTENT_TYPES = RAW_TEXT_CONTENT_TYPES
+export const TEXT_CONTENT_TYPE_SET = new Set<string>(TEXT_CONTENT_TYPES)
+
+export function isTextContentType(contentType: string) {
+  if (!contentType) return false
+  const normalized = contentType.split(';', 1)[0]?.trim().toLowerCase() ?? ''
+  if (!normalized) return false
+  if (normalized.startsWith('text/')) return true
+  return TEXT_CONTENT_TYPE_SET.has(normalized)
+}

package/packages/schema/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "declaration": true,
+    "sourceMap": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/pilothub

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const distCliUrl = new URL('./packages/pilothub/dist/cli.js', import.meta.url)
+const distCliPath = fileURLToPath(distCliUrl)
+const srcRootPath = fileURLToPath(new URL('./packages/pilothub/src/', import.meta.url))
+
+const shouldBuild = await (async () => {
+  if (!existsSync(distCliPath)) return true
+  try {
+    const dist = await stat(distCliPath)
+    const latestSrcMtime = await getLatestMtime(srcRootPath)
+    return latestSrcMtime > dist.mtimeMs
+  } catch {
+    return true
+  }
+})()
+
+if (shouldBuild) {
+  const proc = Bun.spawn(['bunx', 'tsc', '-p', 'packages/pilothub/tsconfig.json'], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  })
+  const code = await proc.exited
+  if (code !== 0) process.exit(code)
+}
+
+await import(distCliUrl.href)
+
+async function getLatestMtime(root: string) {
+  let latest = 0
+  const glob = new Bun.Glob('**/*.ts')
+  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    const path = `${root}${root.endsWith('/') ? '' : '/'}${rel}`
+    try {
+      const entry = await stat(path)
+      latest = Math.max(latest, entry.mtimeMs)
+    } catch {
+      // ignore
+    }
+  }
+  return latest
+}

package/playwright.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const port = Number(process.env.PLAYWRIGHT_PORT || 4173)
+const baseURL = process.env.PLAYWRIGHT_BASE_URL || `http://127.0.0.1:${port}`
+
+export default defineConfig({
+  testDir: './e2e',
+  testMatch: /.*\.pw\.test\.ts/,
+  timeout: 60_000,
+  expect: { timeout: 10_000 },
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : [['list']],
+  use: {
+    baseURL,
+    trace: 'retain-on-failure',
+  },
+  webServer: process.env.PLAYWRIGHT_BASE_URL
+    ? undefined
+    : {
+        command: 'bun run preview -- --host 127.0.0.1 --port 4173',
+        url: baseURL,
+        reuseExistingServer: !process.env.CI,
+        stdout: 'ignore',
+        stderr: 'pipe',
+      },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+})

package/public/.well-known/pilothub.json

@@ -0,0 +1,6 @@
+{
+  "apiBase": "https://pilothub.com",
+  "authBase": "https://pilothub.com",
+  "minCliVersion": "0.1.0",
+  "registry": "https://pilothub.com"
+}