How github/gh-skyline works
Purpose and entry points
gh-skyline is a Go GitHub CLI extension that converts a GitHub user’s contribution calendar into a 3D-printable binary STL, with an optional terminal ASCII preview. Process startup is main.go; command wiring and flag handling are rooted in cmd/root.go and cmd/skyline/skyline.go.
CLI orchestration
The skyline command resolves flags for user, year/range, full history, output, web-only, art-only, and debug behavior. It is the application coordinator: validate/select the requested time span, obtain contribution data, render preview, and conditionally write STL output. Paths: cmd/skyline/skyline.go, cmd/root.go, internal/types/types.go.
GitHub boundary and authentication
GitHub access is isolated behind the internal client layer. It relies on the installed/authenticated gh CLI rather than implementing independent credential management. This boundary fetches the authenticated or explicitly requested user and contribution graph data, likely including join-date information needed by --full; it also supports profile-opening behavior. Paths: internal/github/client.go, internal/github/init.go, internal/types/types.go.
Shared contribution model
A common type layer carries contribution-calendar data between API retrieval and both renderers, keeping GitHub transport logic separate from visualization and geometry. Domain-specific failures are centralized for command-level reporting. Paths: internal/types/types.go, internal/errors/errors.go.
ASCII loading-preview pipeline
The ASCII generator maps contribution levels and future/empty dates into terminal blocks, rearranging each week vertically into the skyline/building effect. This is a presentation-only path for loading feedback and becomes the terminal result when --art-only is selected. Paths: internal/ascii/generator.go, internal/ascii/block.go, internal/ascii/text.go.
STL model-generation pipeline
The STL generator transforms the same calendar into a 3D model: contribution cells become geometric structures, with geometry utilities defining shapes, transforms, vectors, and text. Bundled geometry assets support model lettering/branding. The STL layer serializes the assembled mesh as binary STL to the selected or default output file. Paths: internal/stl/generator.go, internal/stl/stl.go, internal/stl/geometry/geometry.go, internal/stl/geometry/shapes.go, internal/stl/geometry/assets.go.
Runtime, dependencies, and delivery
The runtime is a compiled Go executable invoked by GitHub CLI as gh skyline. Material external dependencies are GitHub CLI/authentication, GitHub’s user/contribution APIs, and golang/freetype plus bundled Mona Sans assets for 3D text. GitHub Actions provides build, lint, and release automation. Paths: go.mod, internal/stl/geometry/text.go, internal/stl/geometry/assets, .github/workflows/release.yml.
Main entry points: skyline.go Skyline command · client.go GitHub client · generator.go STL generator · types.go Contribution model
Components 18
CLI
- Process entry
main.go - Root command
cmd/root.go - Skyline command · Resolves flags, selects time spans, and chooses preview or STL output.
cmd/skyline/skyline.go
GitHub access
- GitHub CLI · Invokes the extension and supplies authentication.
- GitHub client · Retrieves users, contribution graphs, and join-date data through gh authentication.
internal/github/client.go - GitHub client setup
internal/github/init.go - GitHub user APIs
Rendering
- ASCII generator · Rearranges weekly contribution levels into a skyline preview.
internal/ascii/generator.go - ASCII blocks and text
internal/ascii/block.go - STL generator · Converts contribution cells into a printable mesh.
internal/stl/generator.go - Geometry toolkit · Defines shapes, transforms, vectors, and model assets.
internal/stl/geometry/geometry.go - 3D text and assets · Uses Freetype and bundled Mona Sans assets for model lettering.
internal/stl/geometry/text.go - Binary STL writer · Writes the selected or default STL file.
internal/stl/stl.go
Build & delivery
- Go module
go.mod - Release workflow · Builds, lints, and releases the extension.
.github/workflows/release.yml
Other components
- Contribution model · Carries calendar data between retrieval and renderers.
internal/types/types.go - Domain errors
internal/errors/errors.go - STL output file
Connections 21
- GitHub CLI → Process entry: runs gh skyline
- Process entry → Root command: starts
- Root command → Skyline command: registers
- Skyline command → GitHub client setup: initializes
- GitHub client setup → GitHub client: configures
- GitHub client → GitHub CLI: uses auth
- GitHub client → GitHub user APIs: queries
- GitHub client → Contribution model: returns calendar
- GitHub client → Domain errors: reports failures
- Skyline command → Contribution model: selects range
- Skyline command → ASCII generator: renders preview
- Contribution model → ASCII generator: calendar data
- ASCII generator → ASCII blocks and text: uses
- Skyline command → STL generator: when not art-only
- Contribution model → STL generator: calendar data
- STL generator → Geometry toolkit: builds mesh
- STL generator → 3D text and assets: adds lettering
- STL generator → Binary STL writer: serializes
- Binary STL writer → STL output file: writes binary STL
- Go module → Process entry: builds executable
- Release workflow → Go module: builds and releases