Add dynamic CLI download cards with build-time version fetching

kylemclaren · claude · kylemclaren · commit ff2e647ef5b0 · 2026-01-19T11:07:33.000+02:00
- Create DownloadCards React component with platform selection cards
- Create CliDownloads Astro component that renders proper code blocks
- Add cli-releases utility to fetch latest RC version from S3 bucket
- Platform cards show macOS/Linux/Windows with download buttons
- Selecting a platform shows installation instructions with proper
  Starlight code blocks (copy button, syntax highlighting)
- Version is fetched at build time, no hardcoded URLs

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/src/components/CliDownloads.astro b/src/components/CliDownloads.astro
@@ -0,0 +1,160 @@
+---
+import { Code } from '@astrojs/starlight/components';
+import { DownloadCards } from '@/components/react';
+import { getLatestRcRelease } from '@/lib/cli-releases';
+
+const release = await getLatestRcRelease();
+
+// Get specific binaries for examples
+const darwinArm64 = release.binaries.find(b => b.filename.includes('darwin-arm64'))!;
+const linuxAmd64 = release.binaries.find(b => b.filename.includes('linux-amd64'))!;
+const windowsAmd64 = release.binaries.find(b => b.filename.includes('windows-amd64'))!;
+
+const instructions = [
+  {
+    platform: 'macOS',
+    steps: [
+      {
+        label: 'Download the binary',
+        code: `curl -LO ${darwinArm64.url}`,
+      },
+      {
+        label: 'Verify checksum (recommended)',
+        code: `curl -LO ${darwinArm64.checksumUrl}
+shasum -a 256 -c ${darwinArm64.filename}.sha256`,
+      },
+      {
+        label: 'Extract and install',
+        code: `tar xzf ${darwinArm64.filename}
+sudo mv sprite /usr/local/bin/`,
+      },
+    ],
+    note: 'For Intel Macs, replace "arm64" with "amd64" in the URLs above.',
+  },
+  {
+    platform: 'Linux',
+    steps: [
+      {
+        label: 'Download the binary',
+        code: `curl -LO ${linuxAmd64.url}`,
+      },
+      {
+        label: 'Verify checksum (recommended)',
+        code: `curl -LO ${linuxAmd64.checksumUrl}
+sha256sum -c ${linuxAmd64.filename}.sha256`,
+      },
+      {
+        label: 'Extract and install',
+        code: `tar xzf ${linuxAmd64.filename}
+sudo mv sprite /usr/local/bin/`,
+      },
+    ],
+    note: 'For ARM64, replace "amd64" with "arm64" in the URLs above.',
+  },
+  {
+    platform: 'Windows',
+    steps: [
+      {
+        label: 'Download the binary',
+        code: `Invoke-WebRequest -Uri "${windowsAmd64.url}" -OutFile "${windowsAmd64.filename}"`,
+      },
+      {
+        label: 'Extract to your bin directory',
+        code: `Expand-Archive ${windowsAmd64.filename} -DestinationPath $env:USERPROFILE\\bin`,
+      },
+      {
+        label: 'Add to PATH (run as Administrator)',
+        code: `[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\\bin", "User")`,
+      },
+    ],
+    note: 'For ARM64 Windows, replace "amd64" with "arm64" in the URL above.',
+  },
+];
+---
+
+<div class="cli-downloads" data-default-platform="macOS">
+  <DownloadCards
+    client:load
+    binaries={release.binaries}
+    version={release.version}
+  />
+
+  {instructions.map((instruction) => (
+    <div class="platform-instructions" data-platform={instruction.platform}>
+      {instruction.steps.map((step) => (
+        <div class="instruction-step">
+          <p class="step-label">{step.label}</p>
+          <Code code={step.code} lang={instruction.platform === 'Windows' ? 'powershell' : 'bash'} />
+        </div>
+      ))}
+      {instruction.note && (
+        <p class="step-note">{instruction.note}</p>
+      )}
+    </div>
+  ))}
+</div>
+
+<style>
+  .platform-instructions {
+    display: none;
+    margin-top: 2rem;
+  }
+
+  .platform-instructions.active {
+    display: block;
+  }
+
+  .instruction-step {
+    margin-bottom: 1.25rem;
+  }
+
+  .step-label {
+    font-size: 0.875rem;
+    font-weight: 500;
+    margin-bottom: 0.5rem;
+  }
+
+  .step-note {
+    font-size: 0.875rem;
+    color: var(--sl-color-gray-3);
+    font-style: italic;
+    margin-top: 0.5rem;
+  }
+</style>
+
+<script is:inline>
+  (function() {
+    function initCliDownloads() {
+      document.querySelectorAll('.cli-downloads').forEach(function(container) {
+        var defaultPlatform = container.getAttribute('data-default-platform') || 'macOS';
+
+        // Show default platform instructions
+        var defaultInstructions = container.querySelector('[data-platform="' + defaultPlatform + '"]');
+        if (defaultInstructions) {
+          defaultInstructions.classList.add('active');
+        }
+      });
+    }
+
+    // Listen for platform changes from DownloadCards
+    document.addEventListener('cli-platform-changed', function(event) {
+      var platform = event.detail.platform;
+
+      document.querySelectorAll('.cli-downloads').forEach(function(container) {
+        // Hide all instructions
+        container.querySelectorAll('.platform-instructions').forEach(function(el) {
+          el.classList.remove('active');
+        });
+
+        // Show selected platform
+        var selected = container.querySelector('[data-platform="' + platform + '"]');
+        if (selected) {
+          selected.classList.add('active');
+        }
+      });
+    });
+
+    // Run on page load
+    initCliDownloads();
+  })();
+</script>
diff --git a/src/components/react/DownloadCards.tsx b/src/components/react/DownloadCards.tsx
@@ -0,0 +1,135 @@
+import { Download } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { Item, ItemContent, ItemMedia, ItemTitle } from '@/components/ui/item';
+import { cn } from '@/lib/utils';
+
+function AppleIcon(): React.ReactElement {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-8">
+      <path d="M18.71 19.5c-.83 1.24-1.71 2.45-3.05 2.47-1.34.03-1.77-.79-3.29-.79-1.53 0-2 .77-3.27.82-1.31.05-2.3-1.32-3.14-2.53C4.25 17 2.94 12.45 4.7 9.39c.87-1.52 2.43-2.48 4.12-2.51 1.28-.02 2.5.87 3.29.87.78 0 2.26-1.07 3.81-.91.65.03 2.47.26 3.64 1.98-.09.06-2.17 1.28-2.15 3.81.03 3.02 2.65 4.03 2.68 4.04-.03.07-.42 1.44-1.38 2.83M13 3.5c.73-.83 1.94-1.46 2.94-1.5.13 1.17-.34 2.35-1.04 3.19-.69.85-1.83 1.51-2.95 1.42-.15-1.15.41-2.35 1.05-3.11z" />
+    </svg>
+  );
+}
+
+function LinuxIcon(): React.ReactElement {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-8">
+      <path d="M12.504 0c-.155 0-.315.008-.48.021-4.226.333-3.105 4.807-3.17 6.298-.076 1.092-.3 1.953-1.05 3.02-.885 1.051-2.127 2.75-2.716 4.521-.278.832-.41 1.684-.287 2.489a.424.424 0 00-.11.135c-.26.268-.45.6-.663.839-.199.199-.485.267-.797.4-.313.136-.658.269-.864.68-.09.189-.136.394-.132.602 0 .199.027.4.055.536.058.399.116.728.04.97-.249.68-.28 1.145-.106 1.484.174.334.535.47.94.601.81.2 1.91.135 2.774.6.926.466 1.866.67 2.616.47.526-.116.97-.464 1.208-.946.587-.003 1.23-.269 2.26-.334.699-.058 1.574.267 2.577.2.025.134.063.198.114.333l.003.003c.391.778 1.113 1.132 1.884 1.071.771-.06 1.592-.536 2.257-1.306.631-.765 1.683-1.084 2.378-1.503.348-.199.629-.469.649-.853.023-.4-.2-.811-.714-1.376v-.097l-.003-.003c-.17-.2-.25-.535-.338-.926-.085-.401-.182-.786-.492-1.046h-.003c-.059-.054-.123-.067-.188-.135a.357.357 0 00-.19-.064c.431-1.278.264-2.55-.173-3.694-.533-1.41-1.465-2.638-2.175-3.483-.796-1.005-1.576-1.957-1.56-3.368.026-2.152.236-6.133-3.544-6.139zm.529 3.405h.013c.213 0 .396.062.584.198.19.135.33.332.438.533.105.259.158.459.166.724 0-.02.006-.04.006-.06v.105a.086.086 0 01-.004-.021l-.004-.024a1.807 1.807 0 01-.15.706.953.953 0 01-.213.335.71.71 0 00-.088-.042c-.104-.045-.198-.064-.284-.133a1.312 1.312 0 00-.22-.066c.05-.06.146-.133.183-.198.053-.128.082-.264.088-.402v-.02a1.21 1.21 0 00-.061-.4c-.045-.134-.101-.2-.183-.333-.084-.066-.167-.132-.267-.132h-.016c-.093 0-.176.03-.262.132a.8.8 0 00-.205.334 1.18 1.18 0 00-.09.4v.019c.002.089.008.179.02.267-.193-.067-.438-.135-.607-.202a1.635 1.635 0 01-.018-.2v-.02a1.772 1.772 0 01.15-.768c.082-.22.232-.406.43-.533a.985.985 0 01.594-.2zm-2.962.059h.036c.142 0 .27.048.399.135.146.129.264.288.344.465.09.199.14.4.153.667v.004c.007.134.006.2-.002.266v.08c-.03.007-.056.018-.083.024-.152.055-.274.135-.393.2.012-.09.013-.18.003-.267v-.015c-.012-.133-.04-.2-.082-.333a.613.613 0 00-.166-.267.248.248 0 00-.183-.064h-.021c-.071.006-.13.04-.186.132a.552.552 0 00-.12.27.944.944 0 00-.023.33v.015c.012.135.037.2.08.334.046.134.098.2.166.268.01.009.02.018.034.024-.07.057-.117.07-.176.136a.304.304 0 01-.131.068 2.62 2.62 0 01-.275-.402 1.772 1.772 0 01-.155-.667 1.759 1.759 0 01.08-.668 1.43 1.43 0 01.283-.535c.128-.133.26-.2.418-.2zm1.37 1.706c.332 0 .733.065 1.216.399.293.2.523.269 1.052.468h.003c.255.136.405.266.478.399v-.131a.571.571 0 01.016.47c-.123.31-.516.643-1.063.842v.002c-.268.135-.501.333-.775.465-.276.135-.588.292-1.012.267a1.139 1.139 0 01-.448-.067 3.566 3.566 0 01-.322-.198c-.195-.135-.363-.332-.612-.465v-.005h-.005c-.4-.246-.616-.512-.686-.71-.07-.268-.005-.47.193-.6.224-.135.38-.271.483-.336.104-.074.143-.102.176-.131h.002v-.003c.169-.202.436-.47.839-.601.139-.036.294-.065.466-.065zm2.8 2.142c.358 1.417 1.196 3.475 1.735 4.473.286.534.855 1.659 1.102 3.024.156-.005.33.018.513.064.646-1.671-.546-3.467-1.089-3.966-.22-.2-.232-.335-.123-.335.59.534 1.365 1.572 1.646 2.757.13.535.16 1.104.021 1.67.067.028.135.06.205.067 1.032.534 1.413.938 1.23 1.537v-.025c-.06-.003-.12 0-.18 0h-.016c.151-.467-.182-.825-1.065-1.224-.915-.4-1.646-.336-1.77.465-.008.043-.013.066-.018.135-.068.023-.139.053-.209.064-.43.268-.662.669-.793 1.187-.13.533-.17 1.156-.205 1.869v.003c-.02.334-.17.838-.319 1.35-1.5 1.072-3.58 1.538-5.348.334a2.645 2.645 0 00-.402-.533 1.45 1.45 0 00-.275-.333c.182 0 .338-.03.465-.067a.615.615 0 00.314-.334c.108-.267 0-.697-.345-1.163-.345-.467-.931-.995-1.788-1.521-.63-.4-.986-.87-1.15-1.396-.165-.534-.143-1.085-.015-1.645.245-1.07.873-2.11 1.274-2.763.107-.065.037.135-.408.974-.396.751-1.14 2.497-.122 3.854a8.123 8.123 0 01.647-2.876c.564-1.278 1.743-3.504 1.836-5.268.048.036.217.135.289.202.218.133.38.333.59.465.21.201.477.335.876.335.039.003.075.006.11.006.412 0 .73-.134.997-.268.29-.134.52-.334.74-.4h.005c.467-.135.835-.402 1.044-.7zm2.185 8.958c.037.6.343 1.245.882 1.377.588.134 1.434-.333 1.791-.765l.211-.01c.315-.007.577.01.847.268l.003.003c.208.199.305.53.391.876.085.4.154.78.409 1.066.486.527.645.906.636 1.14l.003-.007v.018l-.003-.012c-.015.262-.185.396-.498.595-.63.401-1.746.712-2.457 1.57-.618.737-1.37 1.14-2.036 1.191-.664.053-1.237-.2-1.574-.898l-.005-.003c-.21-.4-.12-1.025.056-1.69.176-.668.428-1.344.463-1.897.037-.714.076-1.335.195-1.814.117-.468.31-.774.64-.934a1.22 1.22 0 01.187-.06c-.015.06-.039.12-.062.18-.08.334.104.7.263.85z" />
+    </svg>
+  );
+}
+
+function WindowsIcon(): React.ReactElement {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-8">
+      <path d="M0 3.449L9.75 2.1v9.451H0m10.949-9.602L24 0v11.4H10.949M0 12.6h9.75v9.451L0 20.699M10.949 12.6H24V24l-12.9-1.801" />
+    </svg>
+  );
+}
+
+const PLATFORM_ICONS: Record<string, () => React.ReactElement> = {
+  macOS: AppleIcon,
+  Linux: LinuxIcon,
+  Windows: WindowsIcon,
+};
+
+interface Binary {
+  platform: string;
+  arch: string;
+  filename: string;
+  url: string;
+}
+
+interface DownloadCardsProps {
+  binaries: Binary[];
+  version: string;
+}
+
+function groupByPlatform(binaries: Binary[]): Record<string, Binary[]> {
+  const grouped: Record<string, Binary[]> = {};
+  for (const binary of binaries) {
+    if (!grouped[binary.platform]) {
+      grouped[binary.platform] = [];
+    }
+    grouped[binary.platform].push(binary);
+  }
+  return grouped;
+}
+
+function DownloadCards({
+  binaries,
+  version,
+}: DownloadCardsProps): React.ReactElement {
+  const [selectedPlatform, setSelectedPlatform] = useState('macOS');
+
+  useEffect(() => {
+    const event = new CustomEvent('cli-platform-changed', {
+      detail: { platform: selectedPlatform },
+    });
+    document.dispatchEvent(event);
+  }, [selectedPlatform]);
+
+  const grouped = groupByPlatform(binaries);
+
+  return (
+    <div className="not-content">
+      <p className="text-sm text-muted-foreground mb-4">
+        Latest release: <strong className="text-foreground">{version}</strong>
+      </p>
+      <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+        {Object.entries(grouped).map(([platform, platformBinaries]) => {
+          const IconComponent = PLATFORM_ICONS[platform];
+          const isSelected = platform === selectedPlatform;
+          return (
+            <Item
+              key={platform}
+              variant="outline"
+              className={cn(
+                'flex-col items-center text-center px-4 py-3 rounded-lg cursor-pointer transition-colors',
+                isSelected
+                  ? 'border-primary bg-primary/5'
+                  : 'hover:border-muted-foreground/50',
+              )}
+              onClick={() => setSelectedPlatform(platform)}
+            >
+              <ItemMedia
+                className={cn(
+                  'mb-1 transition-colors',
+                  isSelected ? 'text-primary' : 'text-muted-foreground',
+                )}
+              >
+                {IconComponent && <IconComponent />}
+              </ItemMedia>
+              <ItemContent className="items-center gap-2">
+                <ItemTitle className="text-sm">{platform}</ItemTitle>
+                <div className="flex gap-1">
+                  {platformBinaries.map((binary) => (
+                    <Button
+                      key={binary.filename}
+                      variant="ghost"
+                      size="sm"
+                      asChild
+                      className="h-7 px-2 text-xs"
+                    >
+                      <a
+                        href={binary.url}
+                        className="no-underline"
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        <Download size={12} />
+                        {binary.arch}
+                      </a>
+                    </Button>
+                  ))}
+                </div>
+              </ItemContent>
+            </Item>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export default DownloadCards;
diff --git a/src/components/react/index.ts b/src/components/react/index.ts
@@ -26,6 +26,7 @@ export { default as CardGrid } from './CardGrid';
 export { CodeTabs, Snippet } from './CodeTabs';
 export { CopyPageButton } from './CopyPageButton';
 export { DotPattern } from './DotPattern';
+export { default as DownloadCards } from './DownloadCards';
 export { LifecycleDiagram } from './LifecycleDiagram';
 export { default as LinkCard } from './LinkCard';
 export { Pagination } from './Pagination';
diff --git a/src/content/docs/cli/installation.mdx b/src/content/docs/cli/installation.mdx
@@ -4,6 +4,7 @@ description: Install the Sprites CLI on macOS, Linux, or Windows
 ---
 
 import { Callout, LinkCard, CardGrid } from '@/components/react';
+import CliDownloads from '@/components/CliDownloads.astro';
 
 The Sprites CLI (`sprite`) is available for macOS, Linux, and Windows.
 
@@ -27,25 +28,7 @@ After installation, you may need to add `~/.local/bin` to your PATH if it's not
 
 ## Manual Installation
 
-For specific versions or manual installation, download binaries from [GitHub Releases](https://github.com/superfly/sprite-env/releases).
-
-### macOS / Linux
-
-```bash
-# Download and extract the appropriate binary for your platform
-tar xzf sprite-<platform>-<arch>.tar.gz
-sudo mv sprite /usr/local/bin/
-```
-
-### Windows
-
-```powershell
-# Download and extract
-Expand-Archive sprite-windows-amd64.zip -DestinationPath $env:USERPROFILE\bin
-
-# Add to PATH (run in PowerShell as Administrator)
-[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")
-```
+<CliDownloads />
 
 ## Verify Installation
 
diff --git a/src/lib/cli-releases.ts b/src/lib/cli-releases.ts
