Skip to content

CLAUDE.md

Latest commit

 

History

History
69 lines (47 loc) · 4.09 KB

CLAUDE.md

File metadata and controls

69 lines (47 loc) · 4.09 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run dev      # Start dev server with hot reload
npm run build    # Production build → dist/
npm run preview  # Preview dist/ locally

There are no lint or test commands configured.

The json/ directory (gitignored) is required at build time. It is fetched from aaronparker/apptracker in CI. For local builds, you need to provide app JSON files in json/.

Tech Stack

  • Framework: Astro (Static Site Generation with Islands architecture)
  • UI Library: React (interactive islands)
  • Language: TypeScript
  • Build Tool: Vite
  • Icons: @fluentui/react-icons
  • Styling: CSS custom properties (no Tailwind, no CSS-in-JS)

Architecture

Evergreen Workbench is a static-generated PWA for browsing application version data tracked by the Evergreen PowerShell module. It deploys to GitHub Pages at https://eucpilots.com/workbench/.

Data Flow

At build time, src/lib/appData.ts globs json/*.json (each file = one app's version data), runs git log against those files to get lastUpdated timestamps, and compiles everything into appdata.json (a static API endpoint generated by src/pages/appdata.json.ts). The client fetches this JSON on load — there is no runtime server.

In CI, the JSON files are sparse-cloned from aaronparker/apptracker with full git history preserved (for accurate lastUpdated dates). The JSON_GIT_DIR env var points git log at that external repo's history.

App Structure

  • src/pages/index.astro — Shell page; mounts <AppsPage client:load /> (the entire SPA is a React island)
  • src/layouts/Layout.astro — HTML shell with Inter font, theme initialization script, PWA registration
  • src/components/AppsPage.tsx — Root SPA component; owns all state (selected app, tab, favorites, search, mobile/sidebar state); fetches appdata.json on mount
  • src/components/AppsSidebar.tsx — App list with favorites pinned, search, and "recent" badges
  • src/components/AppDetails.tsx — Version table with sortable columns, architecture/type filters, copy-URI on click, and PowerShell snippet generation
  • src/components/DashboardPage.tsx — Stats cards and CSS bar charts (no charting library)
  • src/components/GlobalSearch.tsx — Ctrl+K overlay rendered via React Portal; searches app names and version fields
  • src/components/ThemeToggle.tsx — Light/dark mode switcher; persists preference to localStorage
  • src/styles/global.css — All styling via CSS custom properties for light/dark theming (no Tailwind, no CSS-in-JS)

Routing & State

Routing is hash-based (#AppName). AppsPage.tsx is the single state owner — tab (apps/dashboard/about), selected app, favorites (persisted to localStorage), search query (debounced 150ms), and mobile sidebar state. There is no external state library.

Keyboard Shortcuts

/ focuses sidebar search, ↑↓ navigates the app list, f toggles favorite, ? shows shortcuts modal, Ctrl+K opens global search, Escape closes overlays.

Key Features

  • Global Search (Ctrl+K): Overlay search across all apps and version data via React Portal with background blur
  • Two-Panel UI: Sidebar + detail panel split view
  • Theme Support: Light/dark mode with Evergreen brand palette, persisted to localStorage
  • Developer Utilities: One-click "Copy URI" and auto-generated Get-EvergreenApp PowerShell snippets
  • PWA: Service worker with auto-update; installable as a desktop/mobile app

Deployment

  • Hosting: GitHub Pages; base path /workbench/ is configured in astro.config.mjs
  • CI: .github/workflows/astro-gh-pages.yml — triggers daily at 13:00 UTC, on push to main (src/** changes), or manually
  • Post-deploy: Cloudflare cache purge for /workbench/appdata.json (requires CF_ZONE_ID + CF_API_TOKEN secrets)
  • PWA: Vite PWA plugin generates service worker with auto-update; manifest configured with Evergreen brand colors (#009485)