How ahmedalbarghouti/soluna works
Soluna is a single-process Visual Studio Code extension. Its runtime boundary is the VS Code extension host: it does not appear to ship a separate backend, service, or local daemon. All behavior is driven by VS Code commands, status bar actions, and extension configuration.
1. Core purpose
The extension automates theme switching between a user-selected light theme and dark theme, either manually or on a schedule. The main user-facing outputs are theme changes in VS Code and a status bar entry that exposes the controls.
2. Main entrypoint and lifecycle
src/extension.ts is the extension activation point. This is where the extension would register commands, initialize state, create the status bar UI, and start or stop any automatic switching logic when the extension is enabled or disabled.
3. Command-driven control plane
The repo is organized around named commands exposed to VS Code, such as switching to light/dark themes, setting preferred themes, enabling/disabling automatic switching, and setting switch times. These commands form the primary control plane for both manual operation and configuration.
4. Automatic switching subsystem
Automatic theme switching is governed by user-defined times for day and night. The README describes a 24-hour split into two periods, so the architecture likely centers on comparing the current time with configured thresholds and applying the corresponding theme when the schedule changes.
5. Theme state and configuration
src/configUtils.ts is the configuration boundary. This module likely reads and writes extension settings such as:
• preferred light theme
• preferred dark theme
• automatic switching enabled/disabled
• light switch time
• dark switch time
This is the persistence layer for user preferences, probably backed by VS Code settings.
6. Time and schedule logic
src/timeUtils.ts isolates time calculations. This is the natural place for parsing times like 08:00 and 20:00, comparing times, and deciding whether the current moment is in the light or dark period. This separation keeps scheduling logic independent from UI and settings access.
7. User interface surface
The extension has a compact UI surface: a status bar item and a commands menu. The status bar button is the quick access path for switching themes or opening the command list, while the command palette exposes the full set of actions.
8. Asset boundary
src/assets/soluna-demo.gif is documentation-only media used in the README. It is not part of the runtime architecture, but it supports user-facing documentation and onboarding.
9. Test boundary
src/test/suite/extension.test.ts indicates integration-style extension tests using the VS Code test harness. This suggests the repository validates extension activation and command behavior in a VS Code-like environment rather than through isolated unit tests alone.
10. Tooling and development environment
The project is TypeScript-based and uses standard VS Code extension tooling: tsconfig.json for compilation, ESLint/Prettier for code quality, and vscode-test.mjs / .vscode-test.mjs for test execution. These tools shape development and validation, but they do not add runtime dependencies.
11. External dependency surface
The only external platform dependency that materially affects architecture is the VS Code API itself. Theme switching likely works by invoking VS Code’s configuration/theme APIs, and the extension’s lifecycle, commands, status bar, and settings are all mediated by VS Code.
12. Overall data flow
User action or timer event → extension command/activation logic → config/time helpers determine target theme → VS Code theme setting is updated → UI reflects the new mode. The key architectural boundary is between user preferences stored in VS Code configuration and the logic that decides when and what to switch.
In short, Soluna is a small, command-centric VS Code extension with three main subsystems: extension activation/UI, configuration persistence, and time-based theme selection.
Main entry points: extension.ts Extension entry · README.md README · configUtils.ts Config utils · timeUtils.ts Time utils
Components 15
Runtime
VS Code extension host behavior and theme switching flow
- Package manifest · Declares activation, commands, and extension metadata
package.json - Extension entry · Activates the extension, wires commands, UI, and switching lifecycle
src/extension.ts - Commands · Manual theme switching and preference commands exposed to VS Code
- Status bar · Quick-access entry point for switching and opening controls
- Auto switcher · Coordinates scheduled light/dark theme changes
- Theme apply · Updates the active VS Code theme
- Config utils · Reads and writes stored preferences and scheduling settings
src/configUtils.ts - Time utils · Parses times and decides whether the current period is light or dark
src/timeUtils.ts - VS Code API · Host APIs for commands, configuration, status bar, and theme control
Validation
Tests and harness used to exercise the extension
- Test suite · Exercises extension activation and command behavior in the VS Code test host
src/test/suite/extension.test.ts - Test host · Runs the extension inside a VS Code-like test environment
Tooling
Build and development support files
- TS config · TypeScript compilation settings
tsconfig.json - Test runners · Local and VS Code test execution entry points
vscode-test.mjs
Docs
User-facing documentation and demo assets
- README · Explains features, usage, and theme-switching workflow
README.md - Demo GIF · Animated demo used in the documentation
Connections 22
- Package manifest → Extension entry: activates · Defines when and how the extension loads
- Package manifest → Commands: contributes · Publishes commands and extension metadata
- Extension entry → VS Code API: uses · Registers commands, status bar items, and configuration access
- Extension entry → Commands: implements · Binds command handlers to extension behavior
- Extension entry → Status bar: creates · Initializes the quick-access UI entry
- Extension entry → Auto switcher: starts · Turns scheduled switching on and off with extension lifecycle
- Extension entry → Config utils: reads/writes · Loads user preferences and persists updates
- Extension entry → Time utils: evaluates · Uses schedule logic to decide the active theme period
- Commands → Theme apply: triggers · Manual commands request theme changes
- Commands → Config utils: updates · Preference commands store selected themes and times
- Auto switcher → Time utils: checks · Compares the current time against configured thresholds
- Auto switcher → Theme apply: applies · Switches to light or dark theme when the schedule changes
- Config utils → VS Code API: persists via · Uses VS Code settings as the storage boundary
- Time utils → VS Code API: supports · Relies on runtime time source and extension context only indirectly
- Status bar → Commands: routes to · Offers quick access to the command-driven control plane
- Test suite → Test host: runs in · Executes inside the VS Code extension test harness
- Test suite → Extension entry: verifies · Covers activation and command behavior
- Test runners → Test host: launches · Starts the VS Code-based test environment
- TS config → Extension entry: compiles · Configures TypeScript build output
- README → Demo GIF: shows · Uses the GIF as a usage illustration
- README → Commands: describes · Documents the available controls and switching flow
- README → Auto switcher: explains · Describes scheduled day/night switching behavior