pilothub 0.0.1

package/convex/tokens.ts

@@ -0,0 +1,88 @@
+import { v } from 'convex/values'
+import type { Doc } from './_generated/dataModel'
+import { internalMutation, internalQuery, mutation, query } from './_generated/server'
+import { requireUser } from './lib/access'
+import { generateToken, hashToken } from './lib/tokens'
+
+export const listMine = query({
+  args: {},
+  handler: async (ctx) => {
+    const { userId } = await requireUser(ctx)
+    const tokens = await ctx.db
+      .query('apiTokens')
+      .withIndex('by_user', (q) => q.eq('userId', userId))
+      .order('desc')
+      .take(100)
+    return tokens.map((token) => ({
+      _id: token._id,
+      label: token.label,
+      prefix: token.prefix,
+      createdAt: token.createdAt,
+      lastUsedAt: token.lastUsedAt,
+      revokedAt: token.revokedAt,
+    }))
+  },
+})
+
+export const create = mutation({
+  args: { label: v.string() },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx)
+    const label = args.label.trim() || 'CLI token'
+    const { token, prefix } = generateToken()
+    const tokenHash = await hashToken(token)
+
+    const now = Date.now()
+    const tokenId = await ctx.db.insert('apiTokens', {
+      userId,
+      label,
+      prefix,
+      tokenHash,
+      createdAt: now,
+      lastUsedAt: undefined,
+      revokedAt: undefined,
+    })
+
+    return { token, tokenId, label, prefix, createdAt: now }
+  },
+})
+
+export const revoke = mutation({
+  args: { tokenId: v.id('apiTokens') },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx)
+    const token = await ctx.db.get(args.tokenId)
+    if (!token) throw new Error('Token not found')
+    if (token.userId !== userId) throw new Error('Forbidden')
+    if (token.revokedAt) return
+    await ctx.db.patch(token._id, { revokedAt: Date.now() })
+  },
+})
+
+export const getByHashInternal = internalQuery({
+  args: { tokenHash: v.string() },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query('apiTokens')
+      .withIndex('by_hash', (q) => q.eq('tokenHash', args.tokenHash))
+      .unique()
+  },
+})
+
+export const touchInternal = internalMutation({
+  args: { tokenId: v.id('apiTokens') },
+  handler: async (ctx, args) => {
+    const token = await ctx.db.get(args.tokenId)
+    if (!token || token.revokedAt) return
+    await ctx.db.patch(token._id, { lastUsedAt: Date.now() })
+  },
+})
+
+export const getUserForTokenInternal = internalQuery({
+  args: { tokenId: v.id('apiTokens') },
+  handler: async (ctx, args): Promise<Doc<'users'> | null> => {
+    const token = await ctx.db.get(args.tokenId)
+    if (!token || token.revokedAt) return null
+    return ctx.db.get(token.userId)
+  },
+})

package/convex/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "Bundler",
+    "skipLibCheck": true
+  }
+}

package/convex/uploads.ts

@@ -0,0 +1,20 @@
+import { v } from 'convex/values'
+import { internalMutation, mutation } from './_generated/server'
+import { requireUser } from './lib/access'
+
+export const generateUploadUrl = mutation({
+  args: {},
+  handler: async (ctx) => {
+    await requireUser(ctx)
+    return ctx.storage.generateUploadUrl()
+  },
+})
+
+export const generateUploadUrlForUserInternal = internalMutation({
+  args: { userId: v.id('users') },
+  handler: async (ctx, args) => {
+    const user = await ctx.db.get(args.userId)
+    if (!user || user.deletedAt) throw new Error('User not found')
+    return ctx.storage.generateUploadUrl()
+  },
+})

package/convex/users.ts

@@ -0,0 +1,122 @@
+import { getAuthUserId } from '@convex-dev/auth/server'
+import { v } from 'convex/values'
+import { internal } from './_generated/api'
+import { internalQuery, mutation, query } from './_generated/server'
+import { assertAdmin, requireUser } from './lib/access'
+import { toPublicUser } from './lib/public'
+
+const DEFAULT_ROLE = 'user'
+const ADMIN_HANDLE = 'steipete'
+
+export const getById = query({
+  args: { userId: v.id('users') },
+  handler: async (ctx, args) => toPublicUser(await ctx.db.get(args.userId)),
+})
+
+export const getByIdInternal = internalQuery({
+  args: { userId: v.id('users') },
+  handler: async (ctx, args) => ctx.db.get(args.userId),
+})
+
+export const me = query({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await getAuthUserId(ctx)
+    if (!userId) return null
+    const user = await ctx.db.get(userId)
+    if (!user || user.deletedAt) return null
+    return user
+  },
+})
+
+export const ensure = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const { userId, user } = await requireUser(ctx)
+    const now = Date.now()
+    const updates: Record<string, unknown> = {}
+
+    const handle = user.handle ?? user.name ?? user.email?.split('@')[0]
+    if (!user.handle && handle) updates.handle = handle
+    if (!user.displayName) updates.displayName = handle
+    if (!user.role) {
+      updates.role = handle === ADMIN_HANDLE ? 'admin' : DEFAULT_ROLE
+    }
+    if (!user.createdAt) updates.createdAt = user._creationTime
+    updates.updatedAt = now
+
+    if (Object.keys(updates).length > 0) {
+      await ctx.db.patch(userId, updates)
+    }
+
+    return ctx.db.get(userId)
+  },
+})
+
+export const updateProfile = mutation({
+  args: {
+    displayName: v.string(),
+    bio: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx)
+    await ctx.db.patch(userId, {
+      displayName: args.displayName.trim(),
+      bio: args.bio?.trim(),
+      updatedAt: Date.now(),
+    })
+  },
+})
+
+export const deleteAccount = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const { userId } = await requireUser(ctx)
+    await ctx.db.patch(userId, {
+      deletedAt: Date.now(),
+      updatedAt: Date.now(),
+    })
+    await ctx.runMutation(internal.telemetry.clearUserTelemetryInternal, { userId })
+  },
+})
+
+export const list = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUser(ctx)
+    assertAdmin(user)
+    const limit = args.limit ?? 50
+    return ctx.db.query('users').order('desc').take(limit)
+  },
+})
+
+export const getByHandle = query({
+  args: { handle: v.string() },
+  handler: async (ctx, args) => {
+    const user = await ctx.db
+      .query('users')
+      .withIndex('handle', (q) => q.eq('handle', args.handle))
+      .unique()
+    return toPublicUser(user)
+  },
+})
+
+export const setRole = mutation({
+  args: {
+    userId: v.id('users'),
+    role: v.union(v.literal('admin'), v.literal('moderator'), v.literal('user')),
+  },
+  handler: async (ctx, args) => {
+    const { user } = await requireUser(ctx)
+    assertAdmin(user)
+    await ctx.db.patch(args.userId, { role: args.role, updatedAt: Date.now() })
+    await ctx.db.insert('auditLogs', {
+      actorUserId: user._id,
+      action: 'role.change',
+      targetType: 'user',
+      targetId: args.userId,
+      metadata: { role: args.role },
+      createdAt: Date.now(),
+    })
+  },
+})

package/convex/webhooks.ts

@@ -0,0 +1,50 @@
+import { v } from 'convex/values'
+import { internalAction } from './_generated/server'
+import { buildDiscordPayload, getWebhookConfig, shouldSendWebhook } from './lib/webhooks'
+
+export const sendDiscordWebhook = internalAction({
+  args: {
+    event: v.union(v.literal('skill.publish'), v.literal('skill.highlighted')),
+    skill: v.object({
+      slug: v.string(),
+      displayName: v.string(),
+      summary: v.optional(v.string()),
+      version: v.optional(v.string()),
+      ownerHandle: v.optional(v.string()),
+      highlighted: v.optional(v.boolean()),
+      tags: v.optional(v.array(v.string())),
+    }),
+  },
+  handler: async (_ctx, args) => {
+    const config = getWebhookConfig()
+    const logMeta = {
+      event: args.event,
+      slug: args.skill.slug,
+      version: args.skill.version ?? null,
+      highlighted: args.skill.highlighted ?? false,
+      highlightedOnly: config.highlightedOnly,
+    }
+    if (!shouldSendWebhook(args.event, args.skill, config)) {
+      console.info('[webhook] skipped', logMeta)
+      return { ok: false, skipped: true }
+    }
+
+    const payload = buildDiscordPayload(args.event, args.skill, config)
+    const response = await fetch(config.url as string, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    if (!response.ok) {
+      const message = await response.text()
+      console.error('[webhook] failed', {
+        ...logMeta,
+        status: response.status,
+        body: message.slice(0, 300),
+      })
+      throw new Error(`Discord webhook failed: ${response.status} ${message}`)
+    }
+    console.info('[webhook] sent', { ...logMeta, status: response.status })
+    return { ok: true }
+  },
+})

package/convex.json

@@ -0,0 +1,3 @@
+{
+  "functions": "convex"
+}

package/docs/README.md

@@ -0,0 +1,32 @@
+---
+summary: 'Documentation index + reading order.'
+read_when:
+  - New contributor onboarding
+  - Looking for the right doc
+---
+
+# Docs
+
+Reading order (new contributor):
+
+1. `README.md` (repo root): run locally.
+2. `docs/quickstart.md`: end-to-end: search → install → publish → sync.
+3. `docs/architecture.md`: how the pieces fit (TanStack Start + Convex + CLI).
+4. `docs/skill-format.md`: what a “skill” is on disk + on the registry.
+5. `docs/cli.md`: CLI reference (flags, config, lockfiles, sync rules).
+6. `docs/http-api.md`: HTTP endpoints used by the CLI + public API.
+7. `docs/auth.md`: GitHub OAuth + API tokens + CLI loopback login.
+8. `docs/deploy.md`: Convex + Vercel deployment + rewrites.
+9. `docs/troubleshooting.md`: common failure modes.
+
+Feature/ops docs (already present):
+
+- `docs/spec.md`: product + implementation spec (data model + flows).
+- `docs/telemetry.md`: what `pilothub sync` reports; opt-out.
+- `docs/webhook.md`: Discord webhook events/payload.
+- `docs/diffing.md`: version-to-version diff UI spec.
+- `docs/manual-testing.md`: CLI smoke scripts.
+
+Docs tooling:
+
+- `docs/mintlify.md`: publish these docs with Mintlify.

package/docs/api.md

@@ -0,0 +1,51 @@
+---
+summary: 'Public REST API (v1) overview and conventions.'
+read_when:
+  - Building API clients
+  - Adding endpoints or schemas
+---
+
+# API v1
+
+Base: `https://pilothub.com`
+
+OpenAPI: `/api/v1/openapi.json`
+
+## Auth
+
+- Public read: no token required.
+- Write + account: `Authorization: Bearer clh_...`.
+
+## Rate limits
+
+Per IP + per API key:
+
+- Read: 120/min per IP, 600/min per key
+- Write: 30/min per IP, 120/min per key
+
+Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (on 429).
+
+## Endpoints
+
+Public read:
+
+- `GET /api/v1/search?q=...`
+- `GET /api/v1/skills?limit=&cursor=&sort=`
+  - `sort`: `updated` (default), `downloads`, `stars` (`rating`), `installsCurrent` (`installs`), `installsAllTime`, `trending`
+- `GET /api/v1/skills/{slug}`
+- `GET /api/v1/skills/{slug}/versions?limit=&cursor=`
+- `GET /api/v1/skills/{slug}/versions/{version}`
+- `GET /api/v1/skills/{slug}/file?path=&version=&tag=`
+- `GET /api/v1/resolve?slug=&hash=`
+- `GET /api/v1/download?slug=&version=&tag=`
+
+Auth required:
+
+- `POST /api/v1/skills` (publish, multipart preferred)
+- `DELETE /api/v1/skills/{slug}`
+- `POST /api/v1/skills/{slug}/undelete`
+- `GET /api/v1/whoami`
+
+## Legacy
+
+Legacy `/api/*` and `/api/cli/*` still available. See `DEPRECATIONS.md`.

package/docs/architecture.md

@@ -0,0 +1,61 @@
+---
+summary: 'System overview: web app + Convex backend + CLI + shared schema.'
+read_when:
+  - Orienting in codebase
+  - Tracing a user flow across layers
+---
+
+# Architecture
+
+## Pieces
+
+- Web app: TanStack Start (React) under `src/`.
+- Backend: Convex under `convex/` (DB, storage, actions, HTTP routes).
+- CLI: `packages/pilothub/` (published as `pilothub`).
+- Shared schemas/routes: `packages/schema/` (`pilothub-schema`).
+
+## Data + storage
+
+- Skill “bundle” = versioned set of text files stored in Convex `_storage`.
+- Metadata extracted from `SKILL.md` frontmatter.
+- Stats stored on `skills` (downloads, installs, stars, comments, …).
+
+## Main flows
+
+### Browse (web)
+
+- UI reads skill metadata + latest version from Convex queries/actions.
+- `SKILL.md` rendered as Markdown.
+
+### Search (HTTP)
+
+- `/api/v1/search?q=...` routes to Convex action for vector search.
+- Embeddings currently generated during publish.
+
+### Install (CLI)
+
+- Resolve latest version via `/api/v1/skills/<slug>`.
+- Download zip via `/api/v1/download?slug=...&version=...`.
+- Extract into `./skills/<slug>` (default).
+- Persist install state:
+  - `./.pilothub/lock.json` (per workdir)
+  - `./skills/<slug>/.pilothub/origin.json` (per skill folder)
+
+### Update (CLI)
+
+- Hash local files, call `/api/v1/resolve?slug=...&hash=<sha256>`.
+- If local matches a known version → use that for “current”.
+- If local doesn’t match:
+  - refuse by default
+  - or overwrite with `--force`
+
+### Publish (CLI)
+
+- Publish via `POST /api/v1/skills` (multipart; requires Bearer token).
+
+### Sync (CLI)
+
+- Scan roots for skill folders (contain `SKILL.md`).
+- Compute fingerprint; compare to registry state.
+- Optionally reports telemetry (see `docs/telemetry.md`).
+- Publishes new/changed skills (skips modified installed skills inside install root).

package/docs/auth.md

@@ -0,0 +1,54 @@
+---
+summary: 'Auth overview: GitHub OAuth (web) + API tokens (CLI).'
+read_when:
+  - Working on login/token flows
+  - Debugging 401s
+---
+
+# Auth
+
+## Web auth (GitHub OAuth)
+
+- Convex Auth + GitHub OAuth App.
+- Env vars:
+  - `AUTH_GITHUB_ID`
+  - `AUTH_GITHUB_SECRET`
+  - `CONVEX_SITE_URL` (used by auth config)
+
+Local setup steps are in the repo root `README.md`.
+
+## API tokens (CLI)
+
+The CLI uses a long-lived API token (Bearer token) for publish/sync/delete.
+
+### Browser flow (default)
+
+`pilothub login` does:
+
+1. Starts a loopback HTTP server on `127.0.0.1` (random port).
+2. Opens `<site>/cli/auth?redirect_uri=http://127.0.0.1:<port>/callback&state=...`.
+3. Web UI requires GitHub login, then creates a token and redirects back to the loopback server.
+4. CLI stores the token in the global config file.
+
+### Headless flow
+
+Create a token in the web UI (Settings → API tokens) and paste it:
+
+```bash
+pilothub login --token clh_...
+```
+
+### Token storage
+
+Default global config path:
+
+- macOS: `~/Library/Application Support/pilothub/config.json`
+
+Override:
+
+- `PILOTHUB_CONFIG_PATH=/path/to/config.json`
+
+### Revocation
+
+- Tokens can be revoked in the web UI.
+- Revoked tokens return `401 Unauthorized` on CLI endpoints.

package/docs/cli.md

@@ -0,0 +1,117 @@
+---
+summary: 'CLI reference: commands, flags, config, lockfile, sync behavior.'
+read_when:
+  - Working on CLI behavior
+  - Debugging install/update/sync
+---
+
+# CLI
+
+CLI package: `packages/pilothub/` (bin: `pilothub`).
+
+From this repo you can run it via the wrapper script:
+
+```bash
+bun pilothub --help
+```
+
+## Global flags
+
+- `--workdir <dir>`: working directory (default: cwd; falls back to Pilotbot workspace if configured)
+- `--dir <dir>`: install dir under workdir (default: `skills`)
+- `--site <url>`: base URL for browser login (default: `https://pilothub.com`)
+- `--registry <url>`: API base URL (default: discovered, else `https://pilothub.com`)
+- `--no-input`: disable prompts
+
+Env equivalents:
+
+- `PILOTHUB_SITE`
+- `PILOTHUB_REGISTRY`
+- `PILOTHUB_WORKDIR`
+
+## Config file
+
+Stores your API token + cached registry URL.
+
+- macOS: `~/Library/Application Support/pilothub/config.json`
+- override: `PILOTHUB_CONFIG_PATH`
+
+## Commands
+
+### `login` / `auth login`
+
+- Default: opens browser to `<site>/cli/auth` and completes via loopback callback.
+- Headless: `pilothub login --token clh_...`
+
+### `whoami`
+
+- Verifies the stored token via `/api/v1/whoami`.
+
+### `star <slug>` / `unstar <slug>`
+
+- Adds/removes a skill from your highlights.
+- Calls `POST /api/v1/stars/<slug>` and `DELETE /api/v1/stars/<slug>`.
+- `--yes` skips confirmation.
+
+### `search <query...>`
+
+- Calls `/api/v1/search?q=...`.
+
+### `explore`
+
+- Lists latest updated skills via `/api/v1/skills?limit=...` (sorted by `updatedAt` desc).
+- Flags:
+  - `--limit <n>` (1–200, default: 25)
+  - `--sort newest|downloads|rating|installs|installsAllTime|trending` (default: newest)
+  - `--json` (machine-readable output)
+- Output: `<slug>  v<version>  <age>  <summary>` (summary truncated to 50 chars).
+
+### `install <slug>`
+
+- Resolves latest version via `/api/v1/skills/<slug>`.
+- Downloads zip via `/api/v1/download`.
+- Extracts into `<workdir>/<dir>/<slug>`.
+- Writes:
+  - `<workdir>/.pilothub/lock.json`
+  - `<skill>/.pilothub/origin.json`
+
+### `list`
+
+- Reads `<workdir>/.pilothub/lock.json`.
+
+### `update [slug]` / `update --all`
+
+- Computes fingerprint from local files.
+- If fingerprint matches a known version: no prompt.
+- If fingerprint does not match:
+  - refuses by default
+  - overwrites with `--force` (or prompt, if interactive)
+
+### `publish <path>`
+
+- Publishes via `POST /api/v1/skills` (multipart).
+- Requires semver: `--version 1.2.3`.
+
+### `sync`
+
+- Scans for local skill folders and publishes new/changed ones.
+- Roots can be any folder: a skills directory or a single skill folder with `SKILL.md`.
+- Auto-adds Pilotbot skill roots when `~/.pilotbot/pilotbot.json` is present:
+  - `agent.workspace/skills` (main agent)
+  - `routing.agents.*.workspace/skills` (per-agent)
+  - `~/.pilotbot/skills` (shared)
+  - `skills.load.extraDirs` (shared packs)
+- Respects `PILOTBOT_CONFIG_PATH` and `PILOTBOT_STATE_DIR`.
+- Flags:
+  - `--root <dir...>` extra scan roots
+  - `--all` upload without prompting
+  - `--dry-run` show plan only
+  - `--bump patch|minor|major` (default: patch)
+  - `--changelog <text>` (non-interactive)
+  - `--tags a,b,c` (default: latest)
+  - `--concurrency <n>` (default: 4)
+
+Telemetry:
+
+- Sent during `sync` when logged in, unless `PILOTHUB_DISABLE_TELEMETRY=1`.
+- Details: `docs/telemetry.md`.

package/docs/deploy.md

@@ -0,0 +1,78 @@
+---
+summary: 'Deploy checklist: Convex backend + Vercel web app + /api rewrites.'
+read_when:
+  - Shipping to production
+  - Debugging /api routing
+---
+
+# Deploy
+
+PilotHub is two deployables:
+
+- Web app (TanStack Start) → typically Vercel.
+- Convex backend → Convex deployment (serves `/api/...` routes).
+
+## 1) Deploy Convex
+
+From your local machine:
+
+```bash
+bunx convex deploy
+```
+
+Ensure Convex env is set (auth + embeddings):
+
+- `AUTH_GITHUB_ID`
+- `AUTH_GITHUB_SECRET`
+- `CONVEX_SITE_URL`
+- `JWT_PRIVATE_KEY`
+- `JWKS`
+- `OPENAI_API_KEY`
+- `SITE_URL` (your web app URL)
+- Optional webhook env (see `docs/webhook.md`)
+
+## 2) Deploy web app (Vercel)
+
+Set env vars:
+
+- `VITE_CONVEX_URL`
+- `VITE_CONVEX_SITE_URL` (Convex “site” URL)
+- `CONVEX_SITE_URL` (same value; used by auth provider config)
+- `SITE_URL` (web app URL)
+
+## 3) Route `/api/*` to Convex
+
+This repo currently uses `vercel.json` rewrites:
+
+- `source: /api/:path*`
+- `destination: https://<deployment>.convex.site/api/:path*`
+
+For self-host:
+
+- update `vercel.json` to your deployment’s Convex site URL.
+
+## 4) Registry discovery
+
+The CLI can discover the API base from:
+
+- `/.well-known/pilothub.json`
+
+If you don’t serve that file, users must set:
+
+```bash
+export PILOTHUB_REGISTRY=https://your-site.example
+```
+
+## 5) Post-deploy checks
+
+```bash
+curl -i "https://<site>/api/v1/search?q=test"
+curl -i "https://<site>/api/v1/skills/gifgrep"
+```
+
+Then:
+
+```bash
+pilothub login --site https://<site>
+pilothub whoami
+```