pilothub 0.0.1

package/convex/lib/webhooks.ts

@@ -0,0 +1,112 @@
+export type WebhookEvent = 'skill.publish' | 'skill.highlighted'
+
+export type WebhookSkillPayload = {
+  slug: string
+  displayName: string
+  summary?: string
+  version?: string
+  ownerHandle?: string
+  highlighted?: boolean
+  tags?: string[]
+}
+
+export type WebhookConfig = {
+  url: string | null
+  highlightedOnly: boolean
+  siteUrl: string
+}
+
+const DEFAULT_SITE_URL = 'https://pilothub.com'
+
+export function getWebhookConfig(env: NodeJS.ProcessEnv = process.env): WebhookConfig {
+  const url = env.DISCORD_WEBHOOK_URL?.trim() || null
+  const highlightedOnly = parseBoolean(env.DISCORD_WEBHOOK_HIGHLIGHTED_ONLY)
+  const siteUrl = env.SITE_URL?.trim() || DEFAULT_SITE_URL
+  return { url, highlightedOnly, siteUrl }
+}
+
+export function shouldSendWebhook(
+  event: WebhookEvent,
+  skill: WebhookSkillPayload,
+  config: WebhookConfig,
+) {
+  if (!config.url) return false
+  if (!config.highlightedOnly) return true
+  if (event === 'skill.highlighted') return true
+  return Boolean(skill.highlighted)
+}
+
+export function buildDiscordPayload(
+  event: WebhookEvent,
+  skill: WebhookSkillPayload,
+  config: WebhookConfig,
+) {
+  const titleBase = skill.displayName || skill.slug
+  const title = event === 'skill.highlighted' ? `Highlighted: ${titleBase}` : titleBase
+  const description = buildDescription(event, skill)
+  const url = buildSkillUrl(skill, config.siteUrl)
+  const tags = formatTags(skill.tags)
+
+  return {
+    embeds: [
+      {
+        title,
+        description,
+        url,
+        color: event === 'skill.highlighted' ? 0xff6b4a : 0x2f76ff,
+        fields: [
+          {
+            name: 'Version',
+            value: skill.version ? `v${skill.version}` : '—',
+            inline: true,
+          },
+          {
+            name: 'Owner',
+            value: skill.ownerHandle ? `@${skill.ownerHandle}` : '—',
+            inline: true,
+          },
+          {
+            name: 'Tags',
+            value: tags,
+            inline: false,
+          },
+        ],
+        footer: {
+          text: 'PilotHub',
+        },
+        timestamp: new Date().toISOString(),
+      },
+    ],
+  }
+}
+
+export function buildSkillUrl(skill: WebhookSkillPayload, siteUrl: string) {
+  const owner = skill.ownerHandle?.trim()
+  if (owner) return `${siteUrl}/${owner}/${skill.slug}`
+  return `${siteUrl}/skills/${skill.slug}`
+}
+
+function buildDescription(event: WebhookEvent, skill: WebhookSkillPayload) {
+  const summary = (skill.summary ?? '').trim()
+  if (summary) return truncate(summary, 200)
+  if (event === 'skill.highlighted') return 'Newly highlighted skill on PilotHub.'
+  if (skill.version) return `New version v${skill.version} published on PilotHub.`
+  return 'New skill published on PilotHub.'
+}
+
+function parseBoolean(value?: string) {
+  if (!value) return false
+  const normalized = value.trim().toLowerCase()
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on'
+}
+
+function formatTags(tags?: string[] | null) {
+  const cleaned = (tags ?? []).map((tag) => tag.trim()).filter(Boolean)
+  if (cleaned.length === 0) return '—'
+  return cleaned.slice(0, 8).join(', ')
+}
+
+function truncate(value: string, max: number) {
+  if (value.length <= max) return value
+  return `${value.slice(0, max - 1).trim()}…`
+}

package/convex/maintenance.test.ts

@@ -0,0 +1,270 @@
+/* @vitest-environment node */
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('./_generated/api', () => ({
+  internal: {
+    maintenance: {
+      getSkillBackfillPageInternal: Symbol('getSkillBackfillPageInternal'),
+      applySkillBackfillPatchInternal: Symbol('applySkillBackfillPatchInternal'),
+      backfillSkillSummariesInternal: Symbol('backfillSkillSummariesInternal'),
+      getSkillFingerprintBackfillPageInternal: Symbol('getSkillFingerprintBackfillPageInternal'),
+      applySkillFingerprintBackfillPatchInternal: Symbol(
+        'applySkillFingerprintBackfillPatchInternal',
+      ),
+      backfillSkillFingerprintsInternal: Symbol('backfillSkillFingerprintsInternal'),
+    },
+  },
+}))
+
+const { backfillSkillFingerprintsInternalHandler, backfillSkillSummariesInternalHandler } =
+  await import('./maintenance')
+
+function makeBlob(text: string) {
+  return { text: () => Promise.resolve(text) } as unknown as Blob
+}
+
+describe('maintenance backfill', () => {
+  it('repairs summary + parsed by reparsing SKILL.md', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          kind: 'ok',
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          skillSummary: '>',
+          versionParsed: { frontmatter: { description: '>' } },
+          readmeStorageId: 'storage:1',
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+    const storageGet = vi
+      .fn()
+      .mockResolvedValue(makeBlob(`---\ndescription: >\n  Hello\n  world.\n---\nBody`))
+
+    const result = await backfillSkillSummariesInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.skillsScanned).toBe(1)
+    expect(result.stats.skillsPatched).toBe(1)
+    expect(result.stats.versionsPatched).toBe(1)
+    expect(runMutation).toHaveBeenCalledTimes(1)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      skillId: 'skills:1',
+      versionId: 'skillVersions:1',
+      summary: 'Hello world.',
+      parsed: {
+        frontmatter: { description: 'Hello world.' },
+        metadata: undefined,
+        pilotbot: undefined,
+      },
+    })
+  })
+
+  it('dryRun does not patch', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          kind: 'ok',
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          skillSummary: '>',
+          versionParsed: { frontmatter: { description: '>' } },
+          readmeStorageId: 'storage:1',
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn()
+    const storageGet = vi.fn().mockResolvedValue(makeBlob(`---\ndescription: Hello\n---\nBody`))
+
+    const result = await backfillSkillSummariesInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: true, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.skillsPatched).toBe(1)
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('counts missing storage blob', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          kind: 'ok',
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          skillSummary: null,
+          versionParsed: { frontmatter: {} },
+          readmeStorageId: 'storage:missing',
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn()
+    const storageGet = vi.fn().mockResolvedValue(null)
+
+    const result = await backfillSkillSummariesInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.stats.missingStorageBlob).toBe(1)
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+})
+
+describe('maintenance fingerprint backfill', () => {
+  it('backfills fingerprint field and inserts index entry', async () => {
+    const { hashSkillFiles } = await import('./lib/skills')
+    const expected = await hashSkillFiles([{ path: 'SKILL.md', sha256: 'abc' }])
+
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          versionFingerprint: undefined,
+          files: [{ path: 'SKILL.md', sha256: 'abc' }],
+          existingEntries: [],
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+
+    const result = await backfillSkillFingerprintsInternalHandler(
+      { runQuery, runMutation } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.versionsScanned).toBe(1)
+    expect(result.stats.versionsPatched).toBe(1)
+    expect(result.stats.fingerprintsInserted).toBe(1)
+    expect(result.stats.fingerprintMismatches).toBe(0)
+    expect(runMutation).toHaveBeenCalledTimes(1)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      versionId: 'skillVersions:1',
+      fingerprint: expected,
+      patchVersion: true,
+      replaceEntries: true,
+      existingEntryIds: [],
+    })
+  })
+
+  it('dryRun does not patch', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          versionFingerprint: undefined,
+          files: [{ path: 'SKILL.md', sha256: 'abc' }],
+          existingEntries: [],
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn()
+
+    const result = await backfillSkillFingerprintsInternalHandler(
+      { runQuery, runMutation } as never,
+      { dryRun: true, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.versionsPatched).toBe(1)
+    expect(result.stats.fingerprintsInserted).toBe(1)
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('patches missing version fingerprint without touching correct entries', async () => {
+    const { hashSkillFiles } = await import('./lib/skills')
+    const expected = await hashSkillFiles([{ path: 'SKILL.md', sha256: 'abc' }])
+
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          versionFingerprint: undefined,
+          files: [{ path: 'SKILL.md', sha256: 'abc' }],
+          existingEntries: [{ id: 'skillVersionFingerprints:1', fingerprint: expected }],
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+
+    const result = await backfillSkillFingerprintsInternalHandler(
+      { runQuery, runMutation } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.versionsPatched).toBe(1)
+    expect(result.stats.fingerprintsInserted).toBe(0)
+    expect(result.stats.fingerprintMismatches).toBe(0)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      versionId: 'skillVersions:1',
+      fingerprint: expected,
+      patchVersion: true,
+      replaceEntries: false,
+      existingEntryIds: [],
+    })
+  })
+
+  it('replaces mismatched fingerprint entries', async () => {
+    const { hashSkillFiles } = await import('./lib/skills')
+    const expected = await hashSkillFiles([{ path: 'SKILL.md', sha256: 'abc' }])
+
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          skillId: 'skills:1',
+          versionId: 'skillVersions:1',
+          versionFingerprint: 'wrong',
+          files: [{ path: 'SKILL.md', sha256: 'abc' }],
+          existingEntries: [{ id: 'skillVersionFingerprints:1', fingerprint: 'wrong' }],
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+
+    const result = await backfillSkillFingerprintsInternalHandler(
+      { runQuery, runMutation } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.fingerprintMismatches).toBe(1)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      versionId: 'skillVersions:1',
+      fingerprint: expected,
+      patchVersion: true,
+      replaceEntries: true,
+      existingEntryIds: ['skillVersionFingerprints:1'],
+    })
+  })
+})