formalconf 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +167 -207
- package/dist/formalconf.js +575 -151
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,280 +1,240 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# ⚙️ FormalConf
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### A macOS dotfiles management TUI built with React & Ink
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[](https://github.com/vadimdemedes/ink)
|
|
8
|
+
[](https://reactjs.org/)
|
|
9
|
+
[](https://www.typescriptlang.org/)
|
|
10
|
+
[](https://bun.sh/)
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
- **🔄 Package Synchronization**: Intelligent Homebrew package management with purge capabilities
|
|
11
|
-
- **🎨 Theme System**: Easy switching between visual themes across all applications
|
|
12
|
-
- **🖥️ Interactive TUI**: Beautiful terminal interface for easy management
|
|
13
|
-
- **⚡ Smart Adoption**: Import existing configurations seamlessly
|
|
12
|
+
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Development](#development) • [Tech Stack](#tech-stack) • [Contributing](#contributing)
|
|
14
13
|
|
|
15
|
-
|
|
14
|
+
</div>
|
|
16
15
|
|
|
17
|
-
|
|
18
|
-
```bash
|
|
19
|
-
git clone <your-repo-url> ~/.dotfiles
|
|
20
|
-
cd ~/.dotfiles
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
2. **Install Dependencies**
|
|
24
|
-
```bash
|
|
25
|
-
brew install stow jq mas
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
3. **Launch FormalConf**
|
|
29
|
-
```bash
|
|
30
|
-
./formalconf.sh
|
|
31
|
-
```
|
|
16
|
+
---
|
|
32
17
|
|
|
33
|
-
##
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
### **Configuration Management**
|
|
21
|
+
- **GNU Stow integration** for symlink-based dotfile management
|
|
22
|
+
- **Stow, unstow, restow** operations for individual or all configs
|
|
23
|
+
- **Status checking** to verify symlink integrity
|
|
24
|
+
- Maintains clean home directory structure
|
|
25
|
+
|
|
26
|
+
### **Package Synchronization**
|
|
27
|
+
- **Homebrew formulas & casks** sync from a single JSON config
|
|
28
|
+
- **Mac App Store apps** via `mas` CLI integration
|
|
29
|
+
- **Purge mode** to remove unlisted packages
|
|
30
|
+
- **Lockfile support** for reproducible package installations
|
|
31
|
+
- Smart dependency detection prevents removal of system-critical apps
|
|
32
|
+
|
|
33
|
+
### **Theme System**
|
|
34
|
+
- **Omarchy-compatible themes** with symlink-based switching
|
|
35
|
+
- Application-specific theme configs (Ghostty, Btop, Neovim, etc.)
|
|
36
|
+
- Theme discovery with metadata parsing (author, colors, light/dark mode)
|
|
37
|
+
- Background support as part of themes
|
|
38
|
+
|
|
39
|
+
### **Interactive TUI**
|
|
40
|
+
- **Beautiful React-based interface** powered by Ink
|
|
41
|
+
- **Vim-style navigation** (hjkl, Enter, Esc)
|
|
42
|
+
- Breadcrumb navigation showing current context
|
|
43
|
+
- Real-time status indicators for theme and config state
|
|
44
|
+
- Responsive grid-based theme selector
|
|
34
45
|
|
|
35
|
-
|
|
36
|
-
formalconf/
|
|
37
|
-
├── formalconf.sh # Main TUI interface
|
|
38
|
-
├── config-manager.sh # Dotfile management with GNU Stow
|
|
39
|
-
├── pkg-sync.sh # Package synchronization engine
|
|
40
|
-
├── set-theme.sh # Theme switching utility
|
|
41
|
-
├── pkg-config.json # Package configuration
|
|
42
|
-
├── configs/ # Dotfile packages
|
|
43
|
-
│ ├── aerospace/ # Window manager config
|
|
44
|
-
│ ├── btop/ # System monitor config
|
|
45
|
-
│ ├── fish/ # Shell configuration
|
|
46
|
-
│ ├── ghostty/ # Terminal emulator config
|
|
47
|
-
│ ├── neovim/ # Editor configuration
|
|
48
|
-
│ └── tmux/ # Terminal multiplexer config
|
|
49
|
-
└── themes/ # Visual themes
|
|
50
|
-
├── tokyo-night/ # Dark theme
|
|
51
|
-
└── matte-black/ # Black theme
|
|
52
|
-
```
|
|
46
|
+
---
|
|
53
47
|
|
|
54
|
-
##
|
|
48
|
+
## Installation
|
|
55
49
|
|
|
56
|
-
###
|
|
50
|
+
### Prerequisites
|
|
57
51
|
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
./formalconf.sh
|
|
61
|
-
```
|
|
52
|
+
The following tools must be installed on your system:
|
|
62
53
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
54
|
+
| Tool | Purpose | Install |
|
|
55
|
+
|------|---------|---------|
|
|
56
|
+
| **Bun** | JavaScript runtime | [bun.sh](https://bun.sh/) |
|
|
57
|
+
| **GNU Stow** | Symlink manager | `brew install stow` |
|
|
58
|
+
| **Homebrew** | Package manager | [brew.sh](https://brew.sh/) |
|
|
59
|
+
| **mas** | Mac App Store CLI | `brew install mas` |
|
|
60
|
+
| **jq** | JSON processor | `brew install jq` |
|
|
67
61
|
|
|
68
|
-
###
|
|
62
|
+
### Quick Start
|
|
69
63
|
|
|
70
|
-
#### Configuration Management
|
|
71
64
|
```bash
|
|
72
|
-
#
|
|
73
|
-
|
|
65
|
+
# Run directly with bunx (recommended)
|
|
66
|
+
bunx formalconf
|
|
74
67
|
|
|
75
|
-
#
|
|
76
|
-
|
|
68
|
+
# Or with npx
|
|
69
|
+
npx formalconf
|
|
70
|
+
```
|
|
77
71
|
|
|
78
|
-
|
|
79
|
-
./config-manager.sh unstow-all
|
|
72
|
+
[](https://www.npmjs.com/package/formalconf)
|
|
80
73
|
|
|
81
|
-
|
|
82
|
-
./config-manager.sh status
|
|
74
|
+
---
|
|
83
75
|
|
|
84
|
-
|
|
85
|
-
./config-manager.sh list
|
|
76
|
+
## Usage
|
|
86
77
|
|
|
87
|
-
|
|
88
|
-
./config-manager.sh adopt fish
|
|
89
|
-
```
|
|
78
|
+
### Configuration Directory
|
|
90
79
|
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
# Sync packages from config
|
|
94
|
-
./pkg-sync.sh pkg-config.json
|
|
80
|
+
FormalConf expects your configuration files in `~/.config/formalconf/`:
|
|
95
81
|
|
|
96
|
-
|
|
97
|
-
|
|
82
|
+
```
|
|
83
|
+
~/.config/formalconf/
|
|
84
|
+
├── configs/ # Your dotfile packages (stow directories)
|
|
85
|
+
│ ├── nvim/ # Example: Neovim config
|
|
86
|
+
│ ├── tmux/ # Example: tmux config
|
|
87
|
+
│ └── ...
|
|
88
|
+
├── themes/ # Omarchy-compatible themes
|
|
89
|
+
├── pkg-config.json # Package sync configuration
|
|
90
|
+
└── pkg-lock.json # Package version lockfile
|
|
98
91
|
```
|
|
99
92
|
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
# Apply theme
|
|
103
|
-
./set-theme.sh tokyo-night
|
|
93
|
+
### Dotfile Configs
|
|
104
94
|
|
|
105
|
-
|
|
106
|
-
|
|
95
|
+
Place your dotfile packages in `~/.config/formalconf/configs/`. Each subdirectory is a "stow package" that mirrors your home directory structure:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
configs/
|
|
99
|
+
└── nvim/
|
|
100
|
+
└── .config/
|
|
101
|
+
└── nvim/
|
|
102
|
+
└── init.lua
|
|
107
103
|
```
|
|
108
104
|
|
|
109
|
-
|
|
105
|
+
When stowed, this creates: `~/.config/nvim/init.lua`
|
|
110
106
|
|
|
111
|
-
### Package
|
|
107
|
+
### Package Config
|
|
112
108
|
|
|
113
|
-
Define your
|
|
109
|
+
Define your packages in `pkg-config.json`:
|
|
114
110
|
|
|
115
111
|
```json
|
|
116
112
|
{
|
|
117
113
|
"config": {
|
|
118
|
-
"purge":
|
|
119
|
-
"autoUpdate": true
|
|
114
|
+
"purge": false,
|
|
115
|
+
"autoUpdate": true
|
|
120
116
|
},
|
|
121
|
-
"taps": [
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
"neovim",
|
|
127
|
-
"tmux",
|
|
128
|
-
"fish"
|
|
129
|
-
],
|
|
130
|
-
"casks": [ // GUI applications
|
|
131
|
-
"ghostty",
|
|
132
|
-
"raycast",
|
|
133
|
-
"aerospace"
|
|
134
|
-
],
|
|
135
|
-
"mas": { // Mac App Store apps
|
|
136
|
-
"Xcode": 497799835,
|
|
137
|
-
"WhatsApp": 310633997
|
|
117
|
+
"taps": ["oven-sh/bun"],
|
|
118
|
+
"packages": ["neovim", "tmux", "ripgrep"],
|
|
119
|
+
"casks": ["ghostty", "raycast"],
|
|
120
|
+
"mas": {
|
|
121
|
+
"Xcode": 497799835
|
|
138
122
|
}
|
|
139
123
|
}
|
|
140
124
|
```
|
|
141
125
|
|
|
142
|
-
###
|
|
126
|
+
### Theme Compatibility
|
|
143
127
|
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
mkdir -p configs/myapp/.config/myapp
|
|
147
|
-
```
|
|
128
|
+
FormalConf supports [Omarchy themes](https://learn.omacom.io/2/the-omarchy-manual/52/themes). Place themes in `~/.config/formalconf/themes/` following the Omarchy theme structure.
|
|
148
129
|
|
|
149
|
-
|
|
150
|
-
```bash
|
|
151
|
-
# Place your config files maintaining home directory structure
|
|
152
|
-
configs/myapp/.config/myapp/config.toml
|
|
153
|
-
```
|
|
130
|
+
---
|
|
154
131
|
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
./config-manager.sh stow myapp
|
|
158
|
-
```
|
|
132
|
+
## Development
|
|
159
133
|
|
|
160
|
-
###
|
|
134
|
+
### Commands
|
|
161
135
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
136
|
+
```bash
|
|
137
|
+
bun run formalconf # Launch interactive TUI
|
|
138
|
+
bun run config <cmd> # Config management (stow, unstow, status, list, stow-all, unstow-all)
|
|
139
|
+
bun run pkg-sync # Sync packages from pkg-config.json
|
|
140
|
+
bun run pkg-sync --purge # Sync and remove unlisted packages
|
|
141
|
+
bun run theme <name> # Apply a theme
|
|
142
|
+
bun run typecheck # Run TypeScript type checking
|
|
143
|
+
```
|
|
166
144
|
|
|
167
|
-
|
|
168
|
-
```bash
|
|
169
|
-
# Add configuration files for each app
|
|
170
|
-
themes/my-theme/ghostty.conf
|
|
171
|
-
themes/my-theme/btop.theme
|
|
172
|
-
themes/my-theme/neovim.lua
|
|
173
|
-
```
|
|
145
|
+
### Project Structure
|
|
174
146
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
147
|
+
```
|
|
148
|
+
src/
|
|
149
|
+
├── cli/ # Entry points (run directly with bun)
|
|
150
|
+
│ ├── formalconf.tsx # Main TUI app
|
|
151
|
+
│ ├── config-manager.ts # Stow operations
|
|
152
|
+
│ ├── pkg-sync.ts # Homebrew/MAS sync
|
|
153
|
+
│ └── set-theme.ts # Theme switching
|
|
154
|
+
├── components/ # Ink React components
|
|
155
|
+
│ ├── layout/ # Layout primitives (Panel, Breadcrumb, Footer)
|
|
156
|
+
│ └── ui/ # UI elements (StatusIndicator, Divider)
|
|
157
|
+
├── hooks/ # React hooks (useTerminalSize, useSystemStatus)
|
|
158
|
+
├── lib/ # Shared utilities
|
|
159
|
+
│ ├── paths.ts # Path constants (CONFIG_DIR, THEMES_DIR)
|
|
160
|
+
│ ├── shell.ts # Command execution helpers
|
|
161
|
+
│ ├── config.ts # Config loading
|
|
162
|
+
│ └── theme.ts # Theme colors
|
|
163
|
+
└── types/ # TypeScript type definitions
|
|
164
|
+
```
|
|
179
165
|
|
|
180
|
-
|
|
166
|
+
---
|
|
181
167
|
|
|
182
|
-
|
|
168
|
+
## Architecture
|
|
183
169
|
|
|
184
|
-
|
|
185
|
-
- **Aerospace**: Tiling window manager
|
|
186
|
-
- **Btop**: System resource monitor
|
|
187
|
-
- **FastFetch**: System information tool
|
|
188
|
-
- **Fish**: Friendly shell
|
|
189
|
-
- **Ghostty**: Fast terminal emulator
|
|
190
|
-
- **Git**: Version control system
|
|
191
|
-
- **Neovim**: Modern Vim-based editor
|
|
192
|
-
- **Tmux**: Terminal multiplexer
|
|
170
|
+
FormalConf combines three systems into a unified TUI:
|
|
193
171
|
|
|
194
|
-
|
|
172
|
+
1. **Configuration Manager** - Wraps GNU Stow for symlink-based dotfile management
|
|
173
|
+
2. **Package Sync** - Orchestrates Homebrew and Mac App Store package synchronization
|
|
174
|
+
3. **Theme Switcher** - Manages Omarchy-compatible themes via symlinks
|
|
195
175
|
|
|
196
|
-
|
|
197
|
-
2. **Add theme variants** in `themes/*/`
|
|
198
|
-
3. **Update package lists** in `pkg-config.json`
|
|
176
|
+
### Key Concepts
|
|
199
177
|
|
|
200
|
-
|
|
178
|
+
- **Stow Packages** - Each config directory mirrors your home directory structure
|
|
179
|
+
- **Session Isolation** - Package configs are separate from dotfile configs
|
|
180
|
+
- **Theme Metadata** - Themes include author, description, and color information
|
|
181
|
+
- **Lockfiles** - Enable reproducible package installations across machines
|
|
201
182
|
|
|
202
|
-
|
|
183
|
+
---
|
|
203
184
|
|
|
204
|
-
|
|
205
|
-
# This will move your existing config into the repo
|
|
206
|
-
./config-manager.sh adopt fish
|
|
207
|
-
```
|
|
185
|
+
## Tech Stack
|
|
208
186
|
|
|
209
|
-
|
|
187
|
+
<div align="center">
|
|
210
188
|
|
|
211
|
-
|
|
189
|
+
| Category | Technologies |
|
|
190
|
+
|----------|-------------|
|
|
191
|
+
| **Runtime** | Bun |
|
|
192
|
+
| **UI Framework** | Ink, React |
|
|
193
|
+
| **Language** | TypeScript |
|
|
194
|
+
| **Config Management** | GNU Stow |
|
|
195
|
+
| **Package Management** | Homebrew, mas |
|
|
196
|
+
| **Theme Format** | Omarchy-compatible |
|
|
212
197
|
|
|
213
|
-
|
|
214
|
-
- **System App Protection**: Prevents removal of essential macOS apps
|
|
215
|
-
- **Failure Handling**: Continues operation even if individual packages fail
|
|
216
|
-
- **Cleanup**: Automatically removes orphaned dependencies
|
|
198
|
+
</div>
|
|
217
199
|
|
|
218
|
-
|
|
200
|
+
---
|
|
219
201
|
|
|
220
|
-
|
|
221
|
-
- **Application-specific**: Each app can have its own theme configuration
|
|
222
|
-
- **Extensible**: Easy to add new applications and themes
|
|
202
|
+
## Contributing
|
|
223
203
|
|
|
224
|
-
|
|
204
|
+
Contributions are welcome! Here's how you can help:
|
|
225
205
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
-
|
|
229
|
-
|
|
206
|
+
1. **Fork the repository**
|
|
207
|
+
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
|
|
208
|
+
3. **Commit your changes** (`git commit -m 'Add amazing feature'`)
|
|
209
|
+
4. **Push to the branch** (`git push origin feature/amazing-feature`)
|
|
210
|
+
5. **Open a Pull Request**
|
|
230
211
|
|
|
231
|
-
|
|
212
|
+
### Development Guidelines
|
|
232
213
|
|
|
233
|
-
|
|
214
|
+
- Run `bun run typecheck` before committing
|
|
215
|
+
- Keep commits focused and descriptive
|
|
216
|
+
- Follow existing code patterns
|
|
234
217
|
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
# Remove conflicting files first
|
|
238
|
-
./config-manager.sh unstow-all
|
|
239
|
-
# Then restow
|
|
240
|
-
./config-manager.sh stow-all
|
|
241
|
-
```
|
|
218
|
+
---
|
|
242
219
|
|
|
243
|
-
|
|
244
|
-
```bash
|
|
245
|
-
# Update Homebrew
|
|
246
|
-
brew update && brew doctor
|
|
247
|
-
# Retry sync
|
|
248
|
-
./pkg-sync.sh pkg-config.json
|
|
249
|
-
```
|
|
220
|
+
## License
|
|
250
221
|
|
|
251
|
-
|
|
252
|
-
```bash
|
|
253
|
-
# Check if theme directory exists
|
|
254
|
-
ls themes/
|
|
255
|
-
# Verify theme files
|
|
256
|
-
ls themes/your-theme/
|
|
257
|
-
```
|
|
222
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
258
223
|
|
|
259
|
-
|
|
224
|
+
---
|
|
260
225
|
|
|
261
|
-
|
|
262
|
-
- **GNU Stow**: Configuration management
|
|
263
|
-
- **jq**: JSON processing
|
|
264
|
-
- **Homebrew**: Package management
|
|
265
|
-
- **mas**: Mac App Store CLI
|
|
226
|
+
## Acknowledgments
|
|
266
227
|
|
|
267
|
-
|
|
228
|
+
- Symlink management powered by [GNU Stow](https://www.gnu.org/software/stow/)
|
|
229
|
+
- Terminal UI built with [Ink](https://github.com/vadimdemedes/ink)
|
|
230
|
+
- Theme format compatible with [Omarchy](https://learn.omacom.io/2/the-omarchy-manual/52/themes)
|
|
268
231
|
|
|
269
|
-
|
|
232
|
+
---
|
|
270
233
|
|
|
271
|
-
|
|
234
|
+
<div align="center">
|
|
272
235
|
|
|
273
|
-
|
|
274
|
-
2. Create your feature branch
|
|
275
|
-
3. Add your configurations/themes
|
|
276
|
-
4. Submit a pull request
|
|
236
|
+
**Made with ❤️ by [formalsnake.dev](https://formalsnake.dev)**
|
|
277
237
|
|
|
278
|
-
|
|
238
|
+
⭐ Star this repo if you find it useful!
|
|
279
239
|
|
|
280
|
-
|
|
240
|
+
</div>
|