Starship v2 Brain-dump

braindump.md

Setup

starship setup

• Automated font installer
• Automated terminal configuration
• Automated shell config updates
• Shell detection via parent process id: eval(starship init)
• Preset selection: emoji, nerdfonts, text, etc.

Troubleshooting

starship doctor

• Show various symbols to check if they appear correctly
• Present troubleshooting steps from within the CLI, with links to long-form guides, help, and GitHub Issues

Functionality

Module Detection

• Show modules within an entire project, not just in src directories
  • Identify project root using VCS or with a project root heuristic (e.g. package.json = node)

Configuration

• A config file is automatically generated, containing all default configuration, a description for each property, and a list of available format variables
  • Similar config file output as npx typescript --init or npx jest --init
  • If the config file is untouched, it gets updated along with Starship

Custom Modules

• A plugin system, allowing users to install community-made modules right from the CLI: starship install spotify
  • Similar to Espanso Packages: https://hub.espanso.org/
• Plugins consume a Starship plugin library for easy development
• Plugins can optionally be written with other runtimes, like xbar: https://github.com/matryer/xbar

Architecture

High-Level

• Developed as two packages – a library with the core logic, and a CLI consuming it
  • All logic used to check the state of the system can be used in isolation by other prompts
• "Headless Starship" – Another CLI that outputs the state the system/directory in a structured format for use by tools looking to create a custom formatted output

Internals

• VCS-agnostic
• As much work is done lazily as possible, and is reused across modules
• Module logic, configuration, and tests are all co-located
• Per-shell formatting is done separately from module logic, right before rendering
• Data retreived from the system is cached on disk

Maintainance

Benchmarking

• Have benchmarks for all modules, individually and together
• Performance goal of 16ms per module (refresh rate of 60Hz monitor)
• Prompt should always render within 100ms, no matter what.

  [0 to 100 ms...] Respond to user actions within this time window and users feel like the result is immediate. Any longer, and the connection between action and reaction is broken. RAIL Model

Testing

• Coverage tracking for codebase and coverage diffs per PR
• Unit tests covering complex logic
• Integration tests mocking external commands for each module
• End-to-end tests for the most commonly used modules, as well as the full prompt
• End-to-end matrix tests for shell ↔ OS combination setups
• Nightly contract testing of the output of the tools we interface with

Release

• Automated SemVer release pipeline
  • https://github.com/googleapis/release-please
  • https://github.com/semantic-release/semantic-release

Documentation

• Per OS, per shell installation instructions
  • Pictures and/or videos walking through the process
• Step-by-step Starship configuration guide