pilothub 0.0.1 → 0.0.2

package/convex/tokens.ts

@@ -1,88 +0,0 @@
-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

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

package/convex/uploads.ts

@@ -1,20 +0,0 @@
-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

@@ -1,122 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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

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

package/docs/README.md

@@ -1,32 +0,0 @@
----
-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

@@ -1,51 +0,0 @@
----
-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

@@ -1,61 +0,0 @@
----
-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

@@ -1,54 +0,0 @@
----
-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

@@ -1,117 +0,0 @@
----
-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

@@ -1,78 +0,0 @@
----
-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
-```