pilothub 0.0.1 → 0.0.2

package/docs/skill-format.md

@@ -1,58 +0,0 @@
----
-summary: 'Skill folder format, required files, allowed file types, limits.'
-read_when:
-  - Publishing skills
-  - Debugging publish/sync failures
----
-
-# Skill format
-
-## On disk
-
-A skill is a folder.
-
-Required:
-
-- `SKILL.md` (or `skill.md`)
-
-Optional:
-
-- any supporting *text-based* files (see “Allowed files”)
-- `.pilothubignore` (ignore patterns for publish/sync)
-- `.gitignore` (also honored)
-
-Local install metadata (written by the CLI):
-
-- `<skill>/.pilothub/origin.json`
-
-Workdir install state (written by the CLI):
-
-- `<workdir>/.pilothub/lock.json`
-
-## `SKILL.md`
-
-- Markdown with optional YAML frontmatter.
-- The server extracts metadata from frontmatter during publish.
-- `description` is used as the skill summary in the UI/search.
-
-## Allowed files
-
-Only “text-based” files are accepted by publish.
-
-- Extension allowlist is in `packages/schema/src/textFiles.ts` (`TEXT_FILE_EXTENSIONS`).
-- Content types starting with `text/` are treated as text; plus a small allowlist (JSON/YAML/TOML/JS/TS/Markdown/SVG).
-
-Limits (server-side):
-
-- Total bundle size: 50MB.
-- Embedding text includes `SKILL.md` + up to ~40 non-`.md` files (best-effort cap).
-
-## Slugs
-
-- Derived from folder name by default.
-- Must be lowercase and URL-safe: `^[a-z0-9][a-z0-9-]*$`.
-
-## Versioning + tags
-
-- Each publish creates a new version (semver).
-- Tags are string pointers to a version; `latest` is commonly used.

package/docs/soul-format.md

@@ -1,37 +0,0 @@
----
-summary: 'Soul bundle format, required files, limits.'
-read_when:
-  - Publishing souls
-  - Debugging soul publish failures
----
-
-# Soul format
-
-## On disk
-
-A soul is a single file:
-
-- `SOUL.md` (or `soul.md`)
-
-For now, onlycrabs.ai rejects any extra files.
-
-## `SOUL.md`
-
-- Markdown with optional YAML frontmatter.
-- The server extracts metadata from frontmatter during publish.
-- `description` is used as the soul summary in the UI/search.
-
-## Limits
-
-- Total bundle size: 50MB.
-- Embedding text includes `SOUL.md` only.
-
-## Slugs
-
-- Derived from folder name by default.
-- Must be lowercase and URL-safe: `^[a-z0-9][a-z0-9-]*$`.
-
-## Versioning + tags
-
-- Each publish creates a new version (semver).
-- Tags are string pointers to a version; `latest` is commonly used.

package/docs/spec.md

@@ -1,177 +0,0 @@
----
-summary: "PilotHub spec: skills registry, versioning, vector search, moderation"
-read_when:
-  - Bootstrapping PilotHub
-  - Implementing schema/auth/search/versioning
-  - Reviewing API and upload/download flows
----
-
-# PilotHub — product + implementation spec (v1)
-
-## Goals
-- onlycrabs.ai mode for sharing `SOUL.md` bundles (host-based entry point).
-- Minimal, fast SPA for browsing and publishing agent skills.
-- Skills stored in Convex (files + metadata + versions + stats).
-- GitHub OAuth login; GitHub App backs up skills to `pilotbot/skills`.
-- Vector-based search over skill text + metadata.
-- Versioning, tags (`latest` + user tags), changelog, rollback (tag movement).
-- Public read access; upload requires auth.
-- Moderation: badges + comment delete; audit everything.
-
-## Non-goals (v1)
-- Paid features, private skills, or binary assets.
-- GitHub App sync beyond backups (future phase).
-
-## Core objects
-
-### User
-- `authId` (from Convex Auth provider)
-- `handle` (GitHub login)
-- `name`, `bio`
-- `avatarUrl` (GitHub, fallback gravatar)
-- `role`: `admin | moderator | user` (moderators can soft-delete and flag; admins can hard-delete + change owners)
-- `createdAt`, `updatedAt`
-
-### Skill
-- `slug` (unique)
-- `displayName`
-- `ownerUserId`
-- `summary` (from SKILL.md frontmatter `description`)
-- `latestVersionId`
-- `latestTagVersionId` (for `latest` tag)
-- `tags` map: `{ tag -> versionId }`
-- `badges`: `{ redactionApproved?: { byUserId, at }, highlighted?: { byUserId, at }, official?: { byUserId, at }, deprecated?: { byUserId, at } }`
-  - `official` marks admin-verified/official skills.
-  - `deprecated` marks skills that should not be used for new integrations.
-- `moderationStatus`: `active | hidden | removed`
-- `moderationFlags`: `string[]` (automatic detection)
-- `moderationNotes`, `moderationReason`
-- `hiddenAt`, `hiddenBy`, `lastReviewedAt`, `reportCount`
-- `stats`: `{ downloads, stars, versions, comments }`
-- `createdAt`, `updatedAt`
-
-### SkillVersion
-- `skillId`
-- `version` (semver string)
-- `tag` (string, optional; `latest` always maintained separately)
-- `changelog` (required)
-- `files`: list of file metadata
-  - `path`, `size`, `storageId`, `sha256`
-- `parsed` (metadata extracted from SKILL.md)
-- `vectorDocId` (if using RAG component) OR `embeddingId`
-- `createdBy`, `createdAt`
-- `softDeletedAt` (nullable)
-
-### Parsed Skill Metadata
-From SKILL.md frontmatter + AgentSkills + Pilotbot extensions:
-- `name`, `description`, `homepage`, `website`, `url`, `emoji`
-- `metadata.pilotbot`: `always`, `skillKey`, `primaryEnv`, `emoji`, `homepage`, `os`,
-  `requires` (`bins`, `anyBins`, `env`, `config`), `install[]`, `nix` (`plugin`, `systems`),
-  `config` (`requiredEnv`, `stateDirs`, `example`), `cliHelp` (string; `cli --help` output)
-- `metadata.pilotbot`: alias of `metadata.pilotbot` (preferred for nix-pilotbot plugin pointers)
-  - Nix plugins are different from regular skills; they bundle the skill pack, the CLI binary, and config flags/requirements together.
-  - `metadata` in frontmatter is YAML (object) preferred; legacy JSON-string accepted.
-
-
-
-### Soul
-- `slug` (unique)
-- `displayName`
-- `ownerUserId`
-- `summary` (from SOUL.md frontmatter `description`)
-- `latestVersionId`
-- `tags` map: `{ tag -> versionId }`
-- `stats`: `{ downloads, stars, versions, comments }`
-- `status`: `active` only (soft-delete on version/comment only)
-- `createdAt`, `updatedAt`
-
-### SoulVersion
-- `soulId`
-- `version` (semver string)
-- `tag` (string, optional; `latest` always maintained separately)
-- `changelog` (required)
-- `files`: list of file metadata (SOUL.md only)
-  - `path`, `size`, `storageId`, `sha256`
-- `parsed` (metadata extracted from SOUL.md)
-- `vectorDocId` (if using RAG component) OR `embeddingId`
-- `createdBy`, `createdAt`
-- `softDeletedAt` (nullable)
-
-### SoulComment
-- `soulId`, `userId`, `body`
-- `softDeletedAt`, `deletedBy`
-- `createdAt`
-
-### SoulStar
-- `soulId`, `userId`, `createdAt`
-
-### Comment
-- `skillId`, `userId`, `body`
-- `softDeletedAt`, `deletedBy`
-- `createdAt`
-
-### Star
-- `skillId`, `userId`, `createdAt`
-
-### AuditLog
-- `actorUserId`
-- `action` (enum: `badge.set`, `badge.unset`, `comment.delete`, `role.change`)
-- `targetType` / `targetId`
-- `metadata` (json)
-- `createdAt`
-
-## Auth + roles
-- Convex Auth with GitHub OAuth App.
-- Default role `user`; bootstrap `steipete` to `admin` on first login.
-- Management console: moderators can hide/restore skills + mark duplicates; admins can change owners, approve badges, and hard-delete.
-- Role changes are admin-only and audited.
-
-## Upload flow (50MB per version)
-1) Client requests upload session.
-2) Client uploads each file via Convex upload URLs (no binaries, text only).
-3) Client submits metadata + file list + changelog + version + tags.
-4) Server validates:
-   - total size ≤ 50MB
-   - file extensions/text content
-   - SKILL.md exists and frontmatter parseable
-   - version uniqueness
-5) Server stores files + metadata, sets `latest` tag, updates stats.
-
-Soul upload flow: same as skills, but only `SOUL.md` is allowed in the bundle.
-Seed data lives in `convex/seed.ts` for local dev.
-
-## Versioning + tags
-- Each upload is a new `SkillVersion`.
-- `latest` tag always points to most recent version unless user re-tags.
-- Rollback: move `latest` (and optionally other tags) to an older version.
-- Changelog is optional.
-
-## Search
-- Vector search over: SKILL.md + other text files + metadata summary (souls index SOUL.md).
-- Convex embeddings + vector index.
-- Filters: tag, owner, `redactionApproved` only, min stars, updatedAt.
-
-## Download API
-- JSON API for skill metadata + versions.
-- Download endpoint returns zip of a version (HTTP action).
-- Soft-delete versions; downloads remain for non-deleted versions only.
-
-## UI (SPA)
-- Home: search + filters + trending/featured + “Highlighted” badge.
-- Skill detail: README render, files list, version history, tags, stats, badges.
-- Upload/edit: file picker + version + tag + changelog.
-- Account settings: name + delete account (soft delete).
-- Admin: user role management + badge approvals + audit log.
-
-## Testing + quality
-- Vitest 4 with >=70% global coverage.
-- Lint: Biome + Oxlint (type-aware).
-
-## Vercel
-- Env vars: Convex deployment URLs + GitHub OAuth client + OpenAI key (if used) + GitHub App backup credentials.
-- SPA feel: client-side transitions, prefetching, optimistic UI.
-
-## Open questions (carry forward)
-- Embeddings provider key + rate limits.
-- Zip generation memory limits (optimize with streaming if needed).
-- GitHub App repo sync (phase 2).

package/docs/telemetry.md

@@ -1,91 +0,0 @@
----
-summary: 'Install telemetry collected via `pilothub sync` + opt-out.'
-read_when:
-  - Working on telemetry / privacy controls
-  - Questions about what data is collected
----
-
-# Telemetry
-
-PilotHub uses **minimal telemetry** to compute **install counts** (what’s actually in use) and to power better sorting/filtering.
-This is based on the CLI `pilothub sync` command.
-
-## When telemetry is collected
-
-Telemetry is only sent when:
-
-- You are **logged in** in the CLI (we already require auth for sync/publish flows).
-- You run `pilothub sync`.
-- Telemetry is **not disabled** (see “How to disable” below).
-
-If you are not logged in, nothing is reported.
-
-## What we collect
-
-On each `pilothub sync`, the CLI reports a **full snapshot** of what it found, grouped by scan root (“folder/root”).
-
-For each root we store:
-
-- `rootId`: a **SHA-256 hash** of the canonical root path (server never sees the raw path).
-- `label`: a human-readable label derived from the last two path segments (home paths are shown with `~`).
-- `firstSeenAt`, `lastSeenAt`, optional `expiredAt`.
-
-For each skill found under a root we store:
-
-- `skillId` (resolved by slug; only skills that exist in the registry are tracked).
-- `firstSeenAt`, `lastSeenAt`.
-- `lastVersion` (best-effort; currently the registry-matched version if known).
-- optional `removedAt` when a previously-reported install disappears from a root.
-
-### What we do *not* collect
-
-- No raw absolute folder paths (only hashed `rootId` + a short display label).
-- No file contents.
-- No per-run logs, prompts, or other CLI output.
-- No tracking for skills that aren’t uploaded to the registry (unknown slugs are ignored).
-
-## Install counts
-
-We maintain two counters per skill:
-
-- `installsCurrent`: unique users who currently have the skill installed in at least one active root.
-- `installsAllTime`: unique users who have ever reported the skill installed.
-
-### Multiple roots
-
-If you sync from multiple folders, we treat each scan root independently. A skill is “currently installed” if it exists in **any** active root.
-
-### Uninstall detection
-
-Because `sync` reports the full set per root:
-
-- If a skill disappears from a root on the next sync, we mark it removed for that root.
-- If the skill is removed from all of your roots, it no longer counts toward `installsCurrent`.
-- `installsAllTime` never decreases unless you delete telemetry (see below).
-
-### Staleness (120 days)
-
-Roots that don’t report telemetry for **120 days** are marked stale and their installs stop counting toward `installsCurrent`.
-This is evaluated lazily (on the next telemetry report) to avoid background jobs.
-
-## Transparency + user controls
-
-PilotHub provides a private “Installed” tab on your own profile:
-
-- Shows the exact roots + installed skills we store.
-- Includes a **JSON export** view.
-- Includes a **Delete telemetry** action to remove all stored telemetry for your account.
-
-Everyone else only sees **aggregated install counters**; no one else can see your roots/folders.
-
-Deleting your account also deletes your telemetry data.
-
-## How to disable telemetry
-
-Set the environment variable:
-
-```bash
-export PILOTHUB_DISABLE_TELEMETRY=1
-```
-
-With this set, the CLI will not send telemetry during `pilothub sync`.

package/docs/troubleshooting.md

@@ -1,49 +0,0 @@
----
-summary: 'Common setup/runtime issues (CLI + backend) and fixes.'
-read_when:
-  - Something is broken and you need a fix-fast checklist
----
-
-# Troubleshooting
-
-## `pilothub login` opens browser but never completes
-
-- Ensure your browser can reach `http://127.0.0.1:<port>/callback` (local firewalls/VPNs can interfere).
-- Use headless mode:
-  - create a token in the web UI (Settings → API tokens)
-  - `pilothub login --token clh_...`
-
-## `whoami` / `publish` returns `Unauthorized` (401)
-
-- Token missing or revoked: check your config file (`PILOTHUB_CONFIG_PATH` override?).
-- Ensure requests include `Authorization: Bearer ...` (CLI does this automatically).
-
-## `publish` fails with `OPENAI_API_KEY is not configured`
-
-- Set `OPENAI_API_KEY` in the Convex environment (not only locally).
-- Re-run `bunx convex dev` / `bunx convex deploy` after setting env.
-
-## `sync` says “No skills found”
-
-- `sync` looks for folders containing `SKILL.md` (or `skill.md`).
-- It scans:
-  - workdir first
-  - then fallback roots (legacy `~/pilotbot/skills`, `~/pilotbot/skills`, etc.)
-- Provide explicit roots:
-
-```bash
-pilothub sync --root /path/to/skills
-```
-
-## `update` refuses due to “local changes (no match)”
-
-- Your local files don’t match any published fingerprint.
-- Options:
-  - keep local edits; skip updating
-  - overwrite: `pilothub update <slug> --force`
-  - publish as fork: copy to new folder/slug then `pilothub publish ... --fork-of upstream@version`
-
-## `GET /api/*` works locally but not on Vercel
-
-- Check `vercel.json` rewrite destination points at your Convex site URL.
-- Ensure `VITE_CONVEX_SITE_URL` and `CONVEX_SITE_URL` match your deployment.

package/docs/webhook.md

@@ -1,51 +0,0 @@
----
-summary: 'Discord webhook events/payloads for skill publish + highlight.'
-read_when:
-  - Working on webhooks/integrations
----
-
-# Webhooks (Discord)
-
-PilotHub can post Discord embeds when skills are published or highlighted.
-
-## Setup
-
-Set the webhook URL in the Convex environment:
-
-- `DISCORD_WEBHOOK_URL` (required): Discord webhook URL.
-- `DISCORD_WEBHOOK_HIGHLIGHTED_ONLY` (optional): `true` to only send for highlighted skills.
-- `SITE_URL` (optional): Base site URL for links (default `https://pilothub.com`).
-
-## Events
-
-- `skill.publish`: fires on every publish (new or updated version).
-- `skill.highlighted`: fires when a skill is newly highlighted.
-
-### Highlight-only filter
-
-When `DISCORD_WEBHOOK_HIGHLIGHTED_ONLY=true`:
-
-- `skill.publish` only sends if the skill is highlighted.
-- `skill.highlighted` always sends.
-
-## Payload (Discord)
-
-Discord receives a JSON payload with a single embed:
-
-```json
-{
-  "embeds": [
-    {
-      "title": "Demo Skill",
-      "description": "Nice skill",
-      "url": "https://pilothub.com/owner/demo-skill",
-      "fields": [
-        { "name": "Version", "value": "v1.2.3", "inline": true },
-        { "name": "Owner", "value": "@owner", "inline": true },
-        { "name": "Tags", "value": "latest, discord", "inline": false }
-      ],
-      "footer": { "text": "PilotHub" }
-    }
-  ]
-}
-```

package/e2e/menu-smoke.pw.test.ts

@@ -1,49 +0,0 @@
-import { expect, test } from '@playwright/test'
-
-const navLabels = ['Skills', 'Upload', 'Import', 'Search']
-
-test('skills loads without error', async ({ page }) => {
-  await page.goto('/skills', { waitUntil: 'domcontentloaded' })
-  await expect(page.locator('text=Something went wrong!')).toHaveCount(0)
-  await expect(page.locator('h1', { hasText: 'Skills' })).toBeVisible()
-})
-
-test('souls loads without error', async ({ page }) => {
-  await page.goto('/souls', { waitUntil: 'domcontentloaded' })
-  await expect(page.locator('text=Something went wrong!')).toHaveCount(0)
-  await expect(page.locator('h1', { hasText: 'Souls' })).toBeVisible()
-})
-
-test('header menu routes render', async ({ page }) => {
-  await page.goto('/', { waitUntil: 'domcontentloaded' })
-
-  for (const label of navLabels) {
-    const link = page.getByRole('link', { name: label }).first()
-    await expect(link).toBeVisible()
-    await link.click()
-
-    if (label === 'Skills') {
-      await expect(page).toHaveURL(/\/skills/)
-      await expect(page.locator('h1', { hasText: 'Skills' })).toBeVisible()
-    }
-
-    if (label === 'Upload') {
-      await expect(page).toHaveURL(/\/upload/)
-      const heading = page.locator('h1.section-title', { hasText: /^Publish a /i })
-      const signInCard = page.locator('text=Sign in to upload')
-      await expect(heading.or(signInCard)).toBeVisible()
-    }
-
-    if (label === 'Import') {
-      await expect(page).toHaveURL(/\/import/)
-      const heading = page.getByRole('heading', { name: 'Import from GitHub' })
-      const signInCard = page.locator('text=Sign in to import and publish skills.')
-      await expect(heading.or(signInCard)).toBeVisible()
-    }
-
-    if (label === 'Search') {
-      await expect(page).toHaveURL(/\/?(\?|$)/)
-      await expect(page.locator('h1', { hasText: 'PilotHub' })).toBeVisible()
-    }
-  }
-})