pilothub 0.0.1 → 0.0.2

package/docs/diffing.md

@@ -1,84 +0,0 @@
----
-summary: "Skill version diffing mode (Monaco-backed)"
-read_when:
-  - Implementing skill diff UI
-  - Adding version comparisons
----
-
-# Diffing mode
-
-## Goals
-- Compare any file between two versions.
-- Default compare: `latest` vs `previous` (SemVer precedence).
-- UX feels native to PilotHub (theme + typography + motion).
-- Inline or side-by-side toggle.
-- Public access.
-
-## UX
-- Diff card on skill detail page.
-- Two selectors: Left/Right.
-  - Items: version strings, plus tags (e.g. `latest`), plus `previous`.
-  - Default: Left = `previous`, Right = `latest`.
-- File list with status: added / removed / changed / same.
-  - Default file: `SKILL.md` if present; else first changed file.
-- Toggle: Inline vs Side-by-side.
-- Show size guard message when file > 200KB.
-
-## SemVer ordering
-- Use SemVer precedence to sort versions.
-- `previous` = immediate predecessor of `latest` by SemVer.
-- If `latest` missing or only one version:
-  - Disable `previous` and show empty-state copy.
-
-## Data sources
-- Versions: `api.skills.listVersions` (all, not just latest 10).
-- Tags: `skill.tags` map.
-- File list: `version.files` with `path`, `sha256`, `size`.
-
-## API
-Add action:
-- `skills.getFileText({ versionId, path }) -> { text, size, sha256 }`
-  - Validate version exists + file path exists in version.
-  - Enforce size <= 200KB (both in action and client).
-  - Use `fetchText` from `convex/lib/skillPublish.ts`.
-
-Optional helper action:
-- `skills.getVersionFiles({ versionId }) -> files[]`
-  - If we want lightweight fetch without full version object.
-
-## Client flow
-1. Fetch versions + tags.
-2. Resolve default compare pair:
-   - Right = tag `latest` if present else highest SemVer.
-   - Left = `previous` (SemVer predecessor).
-3. Build file union by path.
-4. For selected file:
-   - Fetch left/right text (guard by size).
-   - Feed into Monaco diff editor.
-
-## Monaco theming
-- Define `pilothub-light` / `pilothub-dark` via `monaco.editor.defineTheme`.
-- Derive colors from CSS variables on `document.documentElement`:
-  - `--surface`, `--surface-muted`, `--ink`, `--ink-soft`, `--line`, `--accent`.
-- Apply theme on load + when theme changes (`data-theme`).
-- Match font: `var(--font-mono)`.
-- Set diff options:
-  - `renderSideBySide` toggle
-  - `diffAlgorithm: 'advanced'`
-  - `renderSideBySideInlineBreakpoint` for mobile
-  - `wordWrap: 'on'`
-
-## Edge cases
-- File removed/added: show empty buffer on missing side + label.
-- Non-text file should not exist (upload rejects), but still guard.
-- Large file: show size warning + disable fetch.
-- Missing version: show error state.
-
-## Perf
-- Cache file text per version+path in client state.
-- Debounce selector changes (100-200ms).
-- Limit concurrent fetches to 2.
-
-## Tests
-- Unit: SemVer ordering + `previous` selection.
-- Component: default selectors, tag inclusion, size guard.

package/docs/github-import.md

@@ -1,171 +0,0 @@
----
-summary: 'Feature spec: import a skill from a public GitHub URL (auto-detect SKILL.md, selective file upload, provenance).'
-read_when:
-  - Adding GitHub import (web + API)
-  - Reviewing safety limits (SSRF/zip-bombs)
-  - Implementing provenance + canonical-claim flows
----
-
-# GitHub import (public repos)
-
-Goal: paste a GitHub URL → auto-detect skill → preview files → publish (selective) → persist provenance.
-
-Non-goal (v1): private repos (no OAuth/PAT support).
-
-Related:
-- `docs/skill-format.md` (what counts as a skill; text-only limits)
-- `docs/api.md` / `docs/http-api.md` (REST patterns + auth)
-
-## UX
-
-Upload page: “Import from GitHub” mode.
-
-Flow:
-1) URL input
-2) Detect skill candidates (SKILL.md)
-3) If multiple candidates: choose one
-4) File picker: check/uncheck; smart-select referenced files
-5) Confirm slug/name/version/tags
-6) Import → publish
-
-## Accepted URLs
-
-Allowlist: `https://github.com/...` only.
-
-Supported shapes:
-- Repo root: `https://github.com/<owner>/<repo>`
-- Tree path: `https://github.com/<owner>/<repo>/tree/<ref>/<path>`
-- Blob path (file): `https://github.com/<owner>/<repo>/blob/<ref>/<path>`
-
-Normalization:
-- Strip query/hash for fetch.
-- From `blob/.../SKILL.md` derive `path` as parent folder.
-- If `ref` missing: use `HEAD`.
-
-Reject:
-- Non-GitHub hosts.
-- Unknown URL patterns.
-- Paths containing `..` after normalization.
-
-## Fetch strategy (public)
-
-Download archive:
-- `https://github.com/<owner>/<repo>/archive/<ref>.zip`
-- Follow redirects. Final redirect usually pins a commit via `codeload.github.com/.../zip/<sha-or-branch>`.
-
-Unzip server-side (Node or Convex node action). Scan for skill candidates.
-
-Skill candidate definition:
-- Any folder containing `SKILL.md` or `skill.md` (also accept `skills.md` for compatibility).
-- Treat repo root as a folder too.
-
-Multiple skills:
-- Return candidate list: `{ path, frontmatter.name, frontmatter.description }`.
-- User chooses one.
-
-## Smart file selection
-
-Defaults:
-- Always select `SKILL.md` (or chosen readme file).
-- Prefer selecting only within chosen skill folder; allow “include out-of-folder refs” if explicitly toggled.
-
-Referenced file expansion:
-- Parse Markdown links/images from selected `.md` files:
-  - `[](<rel>)`, `![](<rel>)`, `<rel>` only when relative.
-  - Ignore `http(s):`, `mailto:`, `#anchors`.
-  - Strip query/hash from relative targets.
-- Resolve against the current file’s directory.
-- Normalize, reject escapes (`..`).
-- Add referenced file if present in archive and is text-allowed.
-- Recurse for newly added `.md` files.
-
-Hard caps:
-- Max recursion depth (e.g. 4).
-- Max referenced additions (e.g. 200).
-
-UI affordances:
-- “Select referenced”
-- “Select all text”
-- “Clear”
-- Search/filter by path
-
-## Publish behavior
-
-Server publishes using existing pipeline:
-- Text-only enforced (see `docs/skill-format.md`).
-- Total ≤ 50MB (selected set).
-- Must include `SKILL.md` (or accepted variant).
-
-Suggested defaults (UI):
-- `displayName`: frontmatter `name` else folder basename → title case.
-- `slug`: sanitize folder basename; if collision, suffix (`-2`, `-3`, …).
-- `version`: if new skill → `0.1.0`; if updating own existing skill → bump patch.
-- `tags`: default `latest`.
-
-## Provenance (persist source)
-
-Persist on each published version (server-side injection; no mutation of imported files):
-- Store in `skillVersions.parsed.metadata.source`:
-
-Example:
-```json
-{
-  "kind": "github",
-  "url": "https://github.com/visionik/ouracli",
-  "repo": "visionik/ouracli",
-  "ref": "HEAD",
-  "commit": "66ac8fb266b7c5ff6519431862be6a375bbfb883",
-  "path": "",
-  "importedAt": 1767930000000
-}
-```
-
-Why `parsed.metadata`:
-- Already optional and stored with each version.
-- No schema churn for v1.
-
-Future: canonical-claim
-- “claim canonical” can key off `{ kind:'github', repo, path }`.
-- Prefer commit-pinned provenance for auditability; allow UI to show “Imported from …”.
-
-## API sketch (internal actions)
-
-Two-step (recommended):
-- `previewGitHubImport(url)` → `{ commit, candidates:[...], files:[...], defaults:{...} }`
-- `importGitHubSkill({ url, commit, candidatePath, selectedPaths, slug, displayName, version, tags })`
-
-Notes:
-- `importGitHubSkill` should re-fetch by pinned `commit` (not floating branch), to avoid TOCTOU.
-- Validate `selectedPaths` subset of fetched archive manifest.
-
-## Security / abuse controls
-
-SSRF:
-- Only `github.com` (+ `codeload.github.com` during redirect follow).
-- No arbitrary redirects to other hosts.
-
-Zip safety:
-- Max compressed bytes (from `Content-Length` if present; else streaming cap).
-- Max uncompressed total bytes.
-- Max file count.
-- Max single file size.
-- Reject symlinks; reject absolute paths; reject `..` segments.
-
-Rate limits:
-- Tie to existing write limits (import == publish).
-- Cache preview results briefly (e.g. 60s) keyed by `{repo, commit}`.
-
-Error UX:
-- “No SKILL.md found.”
-- “Multiple skills found; pick one.”
-- “Repo too large / too many files.”
-- “Selected files exceed 50MB.”
-
-## Manual test checklist
-
-- Repo root skill (`SKILL.md` at root).
-- Nested skill (`skills/foo/SKILL.md`).
-- Multi-skill repo (two SKILL.md).
-- SKILL.md references `docs/usage.md` + images; smart-select picks `.md` and referenced text files; ignores external links.
-- Huge repo → clean “too large” error.
-- Redirect pinning → import stores commit sha in provenance.

package/docs/http-api.md

@@ -1,187 +0,0 @@
----
-summary: 'HTTP API reference (public + CLI endpoints + auth).'
-read_when:
-  - Adding/changing endpoints
-  - Debugging CLI ↔ registry requests
----
-
-# HTTP API
-
-Base URL: `https://pilothub.com` (default).
-
-All v1 paths are under `/api/v1/...` and implemented by Convex HTTP routes (`convex/http.ts`).
-Legacy `/api/...` and `/api/cli/...` remain for compatibility (see `DEPRECATIONS.md`).
-OpenAPI: `/api/v1/openapi.json`.
-
-## Rate limits
-
-Enforced 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` (when limited)
-
-## Public endpoints (no auth)
-
-### `GET /api/v1/search`
-
-Query params:
-
-- `q` (required): query string
-- `limit` (optional): integer
-- `highlightedOnly` (optional): `true` to filter to highlighted skills
-
-Response:
-
-```json
-{ "results": [{ "score": 0.123, "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "version": "1.2.3", "updatedAt": 1730000000000 }] }
-```
-
-### `GET /api/v1/skills`
-
-Query params:
-
-- `limit` (optional): integer (1–200)
-- `cursor` (optional): pagination cursor (only for `sort=updated`)
-- `sort` (optional): `updated` (default), `downloads`, `stars` (alias: `rating`), `installsCurrent` (alias: `installs`), `installsAllTime`, `trending`
-
-Notes:
-
-- `trending` ranks by installs in the last 7 days (telemetry-based).
-
-Response:
-
-```json
-{ "items": [{ "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "tags": { "latest": "1.2.3" }, "stats": {}, "createdAt": 0, "updatedAt": 0, "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" } }], "nextCursor": null }
-```
-
-### `GET /api/v1/skills/{slug}`
-
-Response:
-
-```json
-{ "skill": { "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "tags": { "latest": "1.2.3" }, "stats": {}, "createdAt": 0, "updatedAt": 0 }, "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" }, "owner": { "handle": "steipete", "displayName": "Peter", "image": null } }
-```
-
-### `GET /api/v1/skills/{slug}/versions`
-
-Query params:
-
-- `limit` (optional): integer
-- `cursor` (optional): pagination cursor
-
-### `GET /api/v1/skills/{slug}/versions/{version}`
-
-Returns version metadata + files list.
-
-### `GET /api/v1/skills/{slug}/file`
-
-Returns raw text content.
-
-Query params:
-
-- `path` (required)
-- `version` (optional)
-- `tag` (optional)
-
-Notes:
-
-- Defaults to latest version.
-- File size limit: 200KB.
-
-### `GET /api/v1/resolve`
-
-Used by the CLI to map a local fingerprint to a known version.
-
-Query params:
-
-- `slug` (required)
-- `hash` (required): 64-char hex sha256 of the bundle fingerprint
-
-Response:
-
-```json
-{ "slug": "gifgrep", "match": { "version": "1.2.2" }, "latestVersion": { "version": "1.2.3" } }
-```
-
-### `GET /api/v1/download`
-
-Downloads a zip of a skill version.
-
-Query params:
-
-- `slug` (required)
-- `version` (optional): semver string
-- `tag` (optional): tag name (e.g. `latest`)
-
-Notes:
-
-- If neither `version` nor `tag` is provided, the latest version is used.
-- Soft-deleted versions return `410`.
-
-## Auth endpoints (Bearer token)
-
-All endpoints require:
-
-```
-Authorization: Bearer clh_...
-```
-
-### `GET /api/v1/whoami`
-
-Validates token and returns the user handle.
-
-### `POST /api/v1/skills`
-
-Publishes a new version.
-
-- Preferred: `multipart/form-data` with `payload` JSON + `files[]` blobs.
-- JSON body with `files` (storageId-based) is also accepted.
-
-### `DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete`
-
-Soft-delete / restore a skill (owner/admin only).
-
-### `POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}`
-
-Add/remove a star (highlights). Both endpoints are idempotent.
-
-Responses:
-
-```json
-{ "ok": true, "starred": true, "alreadyStarred": false }
-```
-
-```json
-{ "ok": true, "unstarred": true, "alreadyUnstarred": false }
-```
-
-## Legacy CLI endpoints (deprecated)
-
-Still supported for older CLI versions:
-
-- `GET /api/cli/whoami`
-- `POST /api/cli/upload-url`
-- `POST /api/cli/publish`
-- `POST /api/cli/telemetry/sync`
-- `POST /api/cli/skill/delete`
-- `POST /api/cli/skill/undelete`
-
-See `DEPRECATIONS.md` for removal plan.
-
-## Registry discovery (`/.well-known/pilothub.json`)
-
-The CLI can discover registry/auth settings from the site:
-
-- `/.well-known/pilothub.json` (JSON)
-
-Schema:
-
-```json
-{ "apiBase": "https://pilothub.com", "authBase": "https://pilothub.com", "minCliVersion": "0.0.5" }
-```
-
-If you self-host, serve this file (or set `PILOTHUB_REGISTRY` explicitly).

package/docs/manual-testing.md

@@ -1,64 +0,0 @@
----
-summary: 'Copy/paste CLI smoke checklist for local verification.'
-read_when:
-  - Pre-merge validation
-  - Reproducing a reported CLI bug
----
-
-# Manual testing (CLI)
-
-## Setup
-- Ensure logged in: `bun pilothub whoami` (or `bun pilothub login`).
-- Optional: set env
-  - `PILOTHUB_SITE=https://pilothub.com`
-  - `PILOTHUB_REGISTRY=https://pilothub.com`
-
-## Smoke
-- `bun pilothub --help`
-- `bun pilothub --cli-version`
-- `bun pilothub whoami`
-
-## Search
-- `bun pilothub search gif --limit 5`
-
-## Install / list / update
-- `mkdir -p /tmp/pilothub-manual && cd /tmp/pilothub-manual`
-- `bunx pilothub@beta install gifgrep --force`
-- `bunx pilothub@beta list`
-- `bunx pilothub@beta update gifgrep --force`
-
-## Publish (changelog optional)
-- `mkdir -p /tmp/pilothub-skill-demo/SKILL && cd /tmp/pilothub-skill-demo`
-- Create files:
-  - `SKILL.md`
-  - `notes.md`
-- Publish:
-  - `bun pilothub publish . --slug pilothub-manual-<ts> --name "Manual <ts>" --version 1.0.0 --tags latest`
-- Publish update with empty changelog:
-  - `bun pilothub publish . --slug pilothub-manual-<ts> --name "Manual <ts>" --version 1.0.1 --tags latest`
-
-## Delete / undelete (owner/admin)
-- `bun pilothub delete pilothub-manual-<ts> --yes`
-- Verify hidden:
-- `curl -i "https://pilothub.com/api/v1/skills/pilothub-manual-<ts>"`
-- Restore:
-  - `bun pilothub undelete pilothub-manual-<ts> --yes`
-- Cleanup:
-  - `bun pilothub delete pilothub-manual-<ts> --yes`
-
-## Sync
-- `bun pilothub sync --dry-run --all`
-
-## Playwright (menu smoke)
-
-Run against prod:
-
-```
-PLAYWRIGHT_BASE_URL=https://pilothub.com bun run test:pw
-```
-
-Run against a local preview server:
-
-```
-bun run test:e2e:local
-```

package/docs/mintlify.md

@@ -1,43 +0,0 @@
----
-summary: 'Mintlify setup notes for publishing docs/.'
-read_when:
-  - Setting up docs site
----
-
-# Mintlify
-
-Goal: publish `docs/` as a browsable docs site (nice UX for OSS users).
-
-This repo does **not** include Mintlify config yet (`mint.json` missing).
-
-## Minimal setup
-
-1) Install Mintlify CLI (per Mintlify docs).
-
-2) Add a `mint.json` at repo root that points to `docs/` pages.
-
-Example (starter):
-
-```json
-{
-  "name": "PilotHub",
-  "logo": "public/logo.svg",
-  "navigation": [
-    { "group": "Start", "pages": ["docs/README", "docs/quickstart"] },
-    { "group": "Concepts", "pages": ["docs/architecture", "docs/skill-format", "docs/telemetry"] },
-    { "group": "Reference", "pages": ["docs/cli", "docs/http-api", "docs/auth", "docs/deploy"] }
-  ]
-}
-```
-
-Notes:
-
-- Mintlify usually wants page paths without extension; keep files as `.md`.
-- If you prefer Mintlify conventions, rename to `.mdx` later (optional).
-
-## Recommended “docs UX” additions
-
-- Add an “Overview” page (use `docs/README.md`).
-- Keep “Quickstart” copy/paste friendly.
-- Provide CLI + HTTP API reference pages (done here).
-- Add a Troubleshooting page for common setup failures.

package/docs/quickstart.md

@@ -1,120 +0,0 @@
----
-summary: 'Local setup + CLI smoke: login, search, install, publish, sync.'
-read_when:
-  - First run / local dev setup
-  - Verifying end-to-end flows
----
-
-# Quickstart
-
-## 0) Prereqs
-
-- Bun
-- Convex CLI (`bunx convex ...`)
-- GitHub OAuth App (for login)
-- OpenAI key (for embeddings/search)
-
-## 1) Local dev (web + Convex)
-
-```bash
-bun install
-cp .env.local.example .env.local
-
-# terminal A
-bun run dev
-
-# terminal B
-bunx convex dev
-```
-
-## 2) Auth setup (GitHub OAuth + Convex Auth keys)
-
-Fill in `.env.local`:
-
-- `AUTH_GITHUB_ID`
-- `AUTH_GITHUB_SECRET`
-- `VITE_CONVEX_URL`
-- `VITE_CONVEX_SITE_URL`
-- `CONVEX_SITE_URL` (same as `VITE_CONVEX_SITE_URL`)
-- `OPENAI_API_KEY`
-
-Generate Convex Auth keys for your deployment:
-
-```bash
-bunx auth --deployment-name <deployment> --web-server-url http://localhost:3000
-```
-
-Then paste the printed `JWT_PRIVATE_KEY` + `JWKS` into `.env.local` (and ensure the deployment got them too).
-
-## 3) CLI: login + basic commands
-
-From this repo:
-
-```bash
-bun pilothub --help
-bun pilothub login
-bun pilothub whoami
-bun pilothub search gif --limit 5
-```
-
-Install a skill into `./skills/<slug>` (if Pilotbot is configured, installs into that workspace instead):
-
-```bash
-bun pilothub install <slug>
-bun pilothub list
-```
-
-You can also install into any folder:
-
-```bash
-bun pilothub install <slug> --workdir /tmp/pilothub-demo --dir skills
-```
-
-Update:
-
-```bash
-bun pilothub update --all
-```
-
-## 4) Publish a skill
-
-Create a folder containing `SKILL.md` (required) plus any supporting text files:
-
-```bash
-mkdir -p /tmp/pilothub-skill-demo && cd /tmp/pilothub-skill-demo
-cat > SKILL.md <<'EOF'
----
-name: Demo Skill
-description: Demo skill for local testing
----
-
-# Demo Skill
-
-Hello.
-EOF
-```
-
-Publish:
-
-```bash
-bun pilothub publish . \
-  --slug pilothub-demo-$(date +%s) \
-  --name "Demo $(date +%s)" \
-  --version 1.0.0 \
-  --tags latest \
-  --changelog "Initial release"
-```
-
-## 5) Sync local skills (auto-publish new/changed)
-
-`sync` scans for local skill folders and publishes the ones that aren’t “synced” yet.
-
-```bash
-bun pilothub sync
-```
-
-Dry run + non-interactive:
-
-```bash
-bun pilothub sync --all --dry-run --no-input
-```