pilothub 0.0.1

package/src/components/SoulDetailPage.tsx

@@ -0,0 +1,263 @@
+import { useAction, useMutation, useQuery } from 'convex/react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import { api } from '../../convex/_generated/api'
+import type { Doc } from '../../convex/_generated/dataModel'
+import type { PublicSoul, PublicUser } from '../lib/publicUser'
+import { isModerator } from '../lib/roles'
+import { useAuthStatus } from '../lib/useAuthStatus'
+
+type SoulDetailPageProps = {
+  slug: string
+}
+
+type SoulBySlugResult = {
+  soul: PublicSoul
+  latestVersion: Doc<'soulVersions'> | null
+  owner: PublicUser | null
+} | null
+
+export function SoulDetailPage({ slug }: SoulDetailPageProps) {
+  const { isAuthenticated, me } = useAuthStatus()
+  const result = useQuery(api.souls.getBySlug, { slug }) as SoulBySlugResult | undefined
+  const toggleStar = useMutation(api.soulStars.toggle)
+  const addComment = useMutation(api.soulComments.add)
+  const removeComment = useMutation(api.soulComments.remove)
+  const getReadme = useAction(api.souls.getReadme)
+  const ensureSoulSeeds = useAction(api.seed.ensureSoulSeeds)
+  const seedEnsuredRef = useRef(false)
+  const [readme, setReadme] = useState<string | null>(null)
+  const [readmeError, setReadmeError] = useState<string | null>(null)
+  const [comment, setComment] = useState('')
+
+  const isLoadingSoul = result === undefined
+  const soul = result?.soul
+  const owner = result?.owner
+  const latestVersion = result?.latestVersion
+  const versions = useQuery(
+    api.souls.listVersions,
+    soul ? { soulId: soul._id, limit: 50 } : 'skip',
+  ) as Doc<'soulVersions'>[] | undefined
+
+  const isStarred = useQuery(
+    api.soulStars.isStarred,
+    isAuthenticated && soul ? { soulId: soul._id } : 'skip',
+  )
+
+  const comments = useQuery(
+    api.soulComments.listBySoul,
+    soul ? { soulId: soul._id, limit: 50 } : 'skip',
+  ) as Array<{ comment: Doc<'soulComments'>; user: PublicUser | null }> | undefined
+
+  const readmeContent = useMemo(() => {
+    if (!readme) return null
+    return stripFrontmatter(readme)
+  }, [readme])
+
+  useEffect(() => {
+    if (seedEnsuredRef.current) return
+    seedEnsuredRef.current = true
+    void ensureSoulSeeds({})
+  }, [ensureSoulSeeds])
+
+  useEffect(() => {
+    if (!latestVersion) return
+    setReadme(null)
+    setReadmeError(null)
+    let cancelled = false
+    void getReadme({ versionId: latestVersion._id })
+      .then((data) => {
+        if (cancelled) return
+        setReadme(data.text)
+      })
+      .catch((error) => {
+        if (cancelled) return
+        setReadmeError(error instanceof Error ? error.message : 'Failed to load SOUL.md')
+        setReadme(null)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [latestVersion, getReadme])
+
+  if (isLoadingSoul) {
+    return (
+      <main className="section">
+        <div className="card">
+          <div className="loading-indicator">Loading soul…</div>
+        </div>
+      </main>
+    )
+  }
+
+  if (result === null || !soul) {
+    return (
+      <main className="section">
+        <div className="card">Soul not found.</div>
+      </main>
+    )
+  }
+
+  const ownerHandle = owner?.handle ?? owner?.name ?? null
+  const downloadBase = `${import.meta.env.VITE_CONVEX_SITE_URL}/api/v1/souls/${soul.slug}/file`
+
+  return (
+    <main className="section">
+      <div className="skill-detail-stack">
+        <div className="card skill-hero">
+          <div className="skill-hero-header">
+            <div className="skill-hero-title">
+              <h1 className="section-title" style={{ margin: 0 }}>
+                {soul.displayName}
+              </h1>
+              <p className="section-subtitle">{soul.summary ?? 'No summary provided.'}</p>
+              <div className="stat">
+                ⭐ {soul.stats.stars} · ⤓ {soul.stats.downloads} · {soul.stats.versions} versions
+              </div>
+              {ownerHandle ? (
+                <div className="stat">
+                  by <a href={`/u/${ownerHandle}`}>@{ownerHandle}</a>
+                </div>
+              ) : null}
+              <div className="skill-actions">
+                {isAuthenticated ? (
+                  <button
+                    className={`star-toggle${isStarred ? ' is-active' : ''}`}
+                    type="button"
+                    onClick={() => void toggleStar({ soulId: soul._id })}
+                    aria-label={isStarred ? 'Unstar soul' : 'Star soul'}
+                  >
+                    <span aria-hidden="true">★</span>
+                  </button>
+                ) : null}
+              </div>
+            </div>
+            <div className="skill-hero-cta">
+              <div className="skill-version-pill">
+                <span className="skill-version-label">Current version</span>
+                <strong>v{latestVersion?.version ?? '—'}</strong>
+              </div>
+              <a
+                className="btn btn-primary"
+                href={`${downloadBase}?path=SOUL.md`}
+                aria-label="Download SOUL.md"
+              >
+                Download SOUL.md
+              </a>
+            </div>
+          </div>
+        </div>
+
+        <div className="card">
+          <div className="skill-readme markdown">
+            {readmeContent ? (
+              <ReactMarkdown remarkPlugins={[remarkGfm]}>{readmeContent}</ReactMarkdown>
+            ) : readmeError ? (
+              <div className="stat">Failed to load SOUL.md: {readmeError}</div>
+            ) : (
+              <div className="loading-indicator">Loading SOUL.md…</div>
+            )}
+          </div>
+        </div>
+
+        <div className="card">
+          <h2 className="section-title" style={{ fontSize: '1.2rem', marginBottom: 8 }}>
+            Versions
+          </h2>
+          <div className="version-scroll">
+            <div className="version-list">
+              {(versions ?? []).map((version) => (
+                <div key={version._id} className="version-row">
+                  <div className="version-info">
+                    <div>
+                      v{version.version} · {new Date(version.createdAt).toLocaleDateString()}
+                      {version.changelogSource === 'auto' ? (
+                        <span style={{ color: 'var(--ink-soft)' }}> · auto</span>
+                      ) : null}
+                    </div>
+                    <div style={{ color: '#5c554e', whiteSpace: 'pre-wrap' }}>
+                      {version.changelog}
+                    </div>
+                  </div>
+                  <div className="version-actions">
+                    <a
+                      className="btn version-zip"
+                      href={`${downloadBase}?path=SOUL.md&version=${encodeURIComponent(
+                        version.version,
+                      )}`}
+                    >
+                      SOUL.md
+                    </a>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+
+        <div className="card">
+          <h2 className="section-title" style={{ fontSize: '1.2rem', margin: 0 }}>
+            Comments
+          </h2>
+          {isAuthenticated ? (
+            <form
+              onSubmit={(event) => {
+                event.preventDefault()
+                if (!comment.trim()) return
+                void addComment({ soulId: soul._id, body: comment.trim() }).then(() =>
+                  setComment(''),
+                )
+              }}
+              className="comment-form"
+            >
+              <textarea
+                className="comment-input"
+                rows={4}
+                value={comment}
+                onChange={(event) => setComment(event.target.value)}
+                placeholder="Leave a note…"
+              />
+              <button className="btn comment-submit" type="submit">
+                Post comment
+              </button>
+            </form>
+          ) : (
+            <p className="section-subtitle">Sign in to comment.</p>
+          )}
+          <div style={{ display: 'grid', gap: 12, marginTop: 16 }}>
+            {(comments ?? []).length === 0 ? (
+              <div className="stat">No comments yet.</div>
+            ) : (
+              (comments ?? []).map((entry) => (
+                <div key={entry.comment._id} className="stat" style={{ alignItems: 'flex-start' }}>
+                  <div>
+                    <strong>@{entry.user?.handle ?? entry.user?.name ?? 'user'}</strong>
+                    <div style={{ color: '#5c554e' }}>{entry.comment.body}</div>
+                  </div>
+                  {isAuthenticated && me && (me._id === entry.comment.userId || isModerator(me)) ? (
+                    <button
+                      className="btn"
+                      type="button"
+                      onClick={() => void removeComment({ commentId: entry.comment._id })}
+                    >
+                      Delete
+                    </button>
+                  ) : null}
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+      </div>
+    </main>
+  )
+}
+
+function stripFrontmatter(content: string) {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  if (!normalized.startsWith('---')) return content
+  const endIndex = normalized.indexOf('\n---', 3)
+  if (endIndex === -1) return content
+  return normalized.slice(endIndex + 4).replace(/^\n+/, '')
+}

package/src/components/UserBootstrap.tsx

@@ -0,0 +1,18 @@
+import { useMutation } from 'convex/react'
+import { useEffect, useRef } from 'react'
+import { api } from '../../convex/_generated/api'
+import { useAuthStatus } from '../lib/useAuthStatus'
+
+export function UserBootstrap() {
+  const { isAuthenticated, isLoading } = useAuthStatus()
+  const ensureUser = useMutation(api.users.ensure)
+  const didRun = useRef(false)
+
+  useEffect(() => {
+    if (isLoading || !isAuthenticated || didRun.current) return
+    didRun.current = true
+    void ensureUser()
+  }, [isAuthenticated, isLoading, ensureUser])
+
+  return null
+}

package/src/components/ui/dropdown-menu.tsx

@@ -0,0 +1,67 @@
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+const DropdownMenu = DropdownMenuPrimitive.Root
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
+const DropdownMenuGroup = DropdownMenuPrimitive.Group
+const DropdownMenuPortal = DropdownMenuPrimitive.Portal
+const DropdownMenuSub = DropdownMenuPrimitive.Sub
+const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className, sideOffset = 8, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 min-w-[180px] rounded-xl border border-[color:var(--line)] bg-[color:var(--surface)] p-2 text-[color:var(--ink)] shadow-[var(--shadow)]',
+        className,
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+))
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
+
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      'flex cursor-pointer select-none items-center gap-2 rounded-lg px-3 py-2 text-sm font-semibold text-[color:var(--ink)] outline-none transition-colors focus:bg-[color:rgba(255,107,74,0.12)] data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className,
+    )}
+    {...props}
+  />
+))
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName
+
+const DropdownMenuSeparator = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.Separator
+    ref={ref}
+    className={cn('my-1 h-px bg-[color:var(--line)]', className)}
+    {...props}
+  />
+))
+DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuRadioGroup,
+}

package/src/components/ui/toggle-group.tsx

@@ -0,0 +1,35 @@
+import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+const ToggleGroup = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <ToggleGroupPrimitive.Root
+    ref={ref}
+    className={cn(
+      'inline-flex items-center gap-1 rounded-full border border-[color:var(--line)] bg-[color:var(--surface)] p-1',
+      className,
+    )}
+    {...props}
+  />
+))
+ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName
+
+const ToggleGroupItem = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <ToggleGroupPrimitive.Item
+    ref={ref}
+    className={cn(
+      'inline-flex h-9 w-9 items-center justify-center rounded-full text-[color:var(--ink-soft)] transition-colors hover:text-[color:var(--ink)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:rgba(255,107,74,0.4)] data-[state=on]:bg-[color:var(--accent)] data-[state=on]:text-white',
+      className,
+    )}
+    {...props}
+  />
+))
+ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName
+
+export { ToggleGroup, ToggleGroupItem }

package/src/convex/client.ts

@@ -0,0 +1,3 @@
+import { ConvexReactClient } from 'convex/react'
+
+export const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)

package/src/lib/badges.ts

@@ -0,0 +1,29 @@
+import type { Doc, Id } from '../../convex/_generated/dataModel'
+
+type BadgeKind = Doc<'skillBadges'>['kind']
+
+type SkillBadgeMap = Partial<Record<BadgeKind, { byUserId: Id<'users'>; at: number }>>
+
+type SkillLike = { badges?: SkillBadgeMap | null }
+
+type BadgeLabel = 'Deprecated' | 'Official' | 'Highlighted'
+
+export function isSkillHighlighted(skill: SkillLike) {
+  return Boolean(skill.badges?.highlighted)
+}
+
+export function isSkillOfficial(skill: SkillLike) {
+  return Boolean(skill.badges?.official)
+}
+
+export function isSkillDeprecated(skill: SkillLike) {
+  return Boolean(skill.badges?.deprecated)
+}
+
+export function getSkillBadges(skill: SkillLike): BadgeLabel[] {
+  const badges: BadgeLabel[] = []
+  if (isSkillDeprecated(skill)) badges.push('Deprecated')
+  if (isSkillOfficial(skill)) badges.push('Official')
+  if (isSkillHighlighted(skill)) badges.push('Highlighted')
+  return badges
+}

package/src/lib/diffing.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildFileDiffList,
+  getDefaultDiffSelection,
+  resolveLatestVersionId,
+  resolvePreviousVersionId,
+  selectDefaultFilePath,
+  sortVersionsBySemver,
+} from './diffing'
+
+describe('diffing', () => {
+  it('sorts versions by semver descending', () => {
+    const ordered = sortVersionsBySemver([
+      { id: 'a', version: '1.0.0' },
+      { id: 'b', version: '2.0.0' },
+      { id: 'c', version: '1.5.0' },
+    ])
+    expect(ordered.map((entry) => entry.version)).toEqual(['2.0.0', '1.5.0', '1.0.0'])
+  })
+
+  it('sorts valid semver ahead of invalid entries', () => {
+    const ordered = sortVersionsBySemver([
+      { id: 'a', version: 'not-a-version' },
+      { id: 'b', version: '1.0.0' },
+      { id: 'c', version: '2.0.0' },
+    ])
+    expect(ordered.map((entry) => entry.version)).toEqual(['2.0.0', '1.0.0', 'not-a-version'])
+  })
+
+  it('sorts when only one entry is valid', () => {
+    const ordered = sortVersionsBySemver([
+      { id: 'a', version: 'nope' },
+      { id: 'b', version: '1.0.0' },
+    ])
+    expect(ordered.map((entry) => entry.version)).toEqual(['1.0.0', 'nope'])
+  })
+
+  it('sorts invalid entries lexicographically', () => {
+    const ordered = sortVersionsBySemver([
+      { id: 'a', version: 'beta' },
+      { id: 'b', version: 'alpha' },
+    ])
+    expect(ordered.map((entry) => entry.version)).toEqual(['alpha', 'beta'])
+  })
+
+  it('resolves latest from tag when present', () => {
+    const latestId = resolveLatestVersionId(
+      [
+        { id: 'a', version: '1.0.0' },
+        { id: 'b', version: '2.0.0' },
+      ],
+      { latest: 'a' },
+    )
+    expect(latestId).toBe('a')
+  })
+
+  it('returns null when no versions exist', () => {
+    const latestId = resolveLatestVersionId([], undefined)
+    expect(latestId).toBeNull()
+  })
+
+  it('resolves previous via semver predecessor', () => {
+    const latestId = 'b'
+    const previousId = resolvePreviousVersionId(
+      [
+        { id: 'a', version: '1.0.0' },
+        { id: 'b', version: '2.0.0' },
+        { id: 'c', version: '1.5.0' },
+      ],
+      latestId,
+    )
+    expect(previousId).toBe('c')
+  })
+
+  it('falls back to second entry when latest missing', () => {
+    const previousId = resolvePreviousVersionId(
+      [
+        { id: 'a', version: '2.0.0' },
+        { id: 'b', version: '1.0.0' },
+        { id: 'c', version: '0.5.0' },
+      ],
+      'missing',
+    )
+    expect(previousId).toBe('b')
+  })
+
+  it('returns default selection previous vs latest', () => {
+    const selection = getDefaultDiffSelection(
+      [
+        { id: 'a', version: '1.0.0' },
+        { id: 'b', version: '2.0.0' },
+      ],
+      { latest: 'b' },
+    )
+    expect(selection).toEqual({ leftId: 'a', rightId: 'b' })
+  })
+
+  it('builds file diff list with statuses', () => {
+    const diff = buildFileDiffList(
+      [
+        { path: 'SKILL.md', sha256: 'aaa', size: 10 },
+        { path: 'a.ts', sha256: 'bbb', size: 10 },
+      ],
+      [
+        { path: 'SKILL.md', sha256: 'aaa', size: 10 },
+        { path: 'b.ts', sha256: 'ccc', size: 10 },
+        { path: 'a.ts', sha256: 'ddd', size: 10 },
+      ],
+    )
+    const statusByPath = Object.fromEntries(diff.map((item) => [item.path, item.status]))
+    expect(statusByPath['SKILL.md']).toBe('same')
+    expect(statusByPath['a.ts']).toBe('changed')
+    expect(statusByPath['b.ts']).toBe('added')
+  })
+
+  it('orders file diff list by change status then path', () => {
+    const diff = buildFileDiffList(
+      [
+        { path: 'c.txt', sha256: 'aaa', size: 1 },
+        { path: 'a.txt', sha256: 'bbb', size: 1 },
+      ],
+      [
+        { path: 'a.txt', sha256: 'ccc', size: 1 },
+        { path: 'b.txt', sha256: 'ddd', size: 1 },
+      ],
+    )
+    expect(diff.map((item) => item.path)).toEqual(['a.txt', 'b.txt', 'c.txt'])
+  })
+
+  it('orders file diff list alphabetically for same status', () => {
+    const diff = buildFileDiffList(
+      [
+        { path: 'b.txt', sha256: 'aaa', size: 1 },
+        { path: 'a.txt', sha256: 'bbb', size: 1 },
+      ],
+      [
+        { path: 'b.txt', sha256: 'aaa', size: 1 },
+        { path: 'a.txt', sha256: 'bbb', size: 1 },
+      ],
+    )
+    expect(diff.map((item) => item.path)).toEqual(['a.txt', 'b.txt'])
+  })
+
+  it('selects SKILL.md as default file when present', () => {
+    const path = selectDefaultFilePath([
+      { path: 'notes.md', status: 'changed' },
+      { path: 'SKILL.md', status: 'same' },
+    ])
+    expect(path).toBe('SKILL.md')
+  })
+
+  it('falls back to first changed file when SKILL.md missing', () => {
+    const path = selectDefaultFilePath([
+      { path: 'alpha.txt', status: 'same' },
+      { path: 'beta.txt', status: 'changed' },
+    ])
+    expect(path).toBe('beta.txt')
+  })
+
+  it('returns null when no file entries exist', () => {
+    expect(selectDefaultFilePath([])).toBeNull()
+  })
+})

package/src/lib/diffing.ts

@@ -0,0 +1,106 @@
+import semver from 'semver'
+
+export const MAX_DIFF_FILE_BYTES = 200 * 1024
+
+type TagMap<IdType extends string> = Record<string, IdType>
+
+export type VersionEntry<IdType extends string = string> = {
+  id: IdType
+  version: string
+}
+
+export type FileMeta = {
+  path: string
+  sha256: string
+  size: number
+}
+
+export type FileDiffStatus = 'added' | 'removed' | 'changed' | 'same'
+
+export type FileDiffItem = {
+  path: string
+  status: FileDiffStatus
+  left?: FileMeta
+  right?: FileMeta
+}
+
+export function sortVersionsBySemver<IdType extends string>(versions: VersionEntry<IdType>[]) {
+  return [...versions].sort((a, b) => {
+    const aValid = Boolean(semver.valid(a.version))
+    const bValid = Boolean(semver.valid(b.version))
+    if (aValid && bValid) return semver.rcompare(a.version, b.version)
+    if (aValid) return -1
+    if (bValid) return 1
+    return a.version.localeCompare(b.version)
+  })
+}
+
+export function resolveLatestVersionId<IdType extends string>(
+  versions: VersionEntry<IdType>[],
+  tags?: TagMap<IdType>,
+) {
+  if (tags?.latest) return tags.latest
+  return sortVersionsBySemver(versions)[0]?.id ?? null
+}
+
+export function resolvePreviousVersionId<IdType extends string>(
+  versions: VersionEntry<IdType>[],
+  latestId?: IdType | null,
+) {
+  const ordered = sortVersionsBySemver(versions)
+  if (!latestId) return ordered[1]?.id ?? null
+  const latestIndex = ordered.findIndex((entry) => entry.id === latestId)
+  if (latestIndex === -1) return ordered[1]?.id ?? null
+  return ordered[latestIndex + 1]?.id ?? null
+}
+
+export function getDefaultDiffSelection<IdType extends string>(
+  versions: VersionEntry<IdType>[],
+  tags?: TagMap<IdType>,
+) {
+  const latestId = resolveLatestVersionId(versions, tags)
+  const previousId = resolvePreviousVersionId(versions, latestId)
+  return {
+    leftId: previousId ?? latestId ?? null,
+    rightId: latestId ?? previousId ?? null,
+  }
+}
+
+export function buildFileDiffList(leftFiles: FileMeta[], rightFiles: FileMeta[]) {
+  const entries = new Map<string, { left?: FileMeta; right?: FileMeta }>()
+  for (const file of leftFiles) {
+    entries.set(file.path, { left: file })
+  }
+  for (const file of rightFiles) {
+    const existing = entries.get(file.path) ?? {}
+    entries.set(file.path, { ...existing, right: file })
+  }
+
+  const statusRank: Record<FileDiffStatus, number> = {
+    changed: 0,
+    added: 1,
+    removed: 2,
+    same: 3,
+  }
+
+  return Array.from(entries.entries())
+    .map(([path, info]) => {
+      let status: FileDiffStatus = 'same'
+      if (info.left && !info.right) status = 'removed'
+      else if (!info.left && info.right) status = 'added'
+      else if (info.left?.sha256 !== info.right?.sha256) status = 'changed'
+      return { path, status, left: info.left, right: info.right }
+    })
+    .sort((a, b) => {
+      const statusDiff = statusRank[a.status] - statusRank[b.status]
+      if (statusDiff !== 0) return statusDiff
+      return a.path.localeCompare(b.path)
+    })
+}
+
+export function selectDefaultFilePath(items: FileDiffItem[]) {
+  const readme = items.find((item) => item.path.toLowerCase() === 'skill.md')
+  if (readme) return readme.path
+  const changed = items.find((item) => item.status !== 'same')
+  return changed?.path ?? items[0]?.path ?? null
+}