Skip to content

Commit f977ccb

Browse files
FrederickEngelhardtFrederickEngelhardt
committed
Cleanup repo and make installs more verbose
1 parent 3091171 commit f977ccb

8 files changed

Lines changed: 584 additions & 65 deletions

‎README.md‎

Lines changed: 158 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,26 @@ OSA is a shell-first, interactive CLI tool that automates the tedious setup of d
1717
- 🔐 **Extensible**: Keep secrets and machine-specific configs out of git via constructors
1818
- 📦 **Modern Tooling**: Built-in support for mise (replaces nvm/rbenv/pyenv/jenv)
1919

20+
### Why OSA When Mise Exists?
21+
22+
**Mise is great for runtime management, but OSA solves the whole setup problem:**
23+
24+
Mise only handles runtime versions (Node, Python, Ruby, etc.). OSA handles **everything**:
25+
26+
| Task | Mise | OSA |
27+
|------|------|-----|
28+
| **Runtime versions** (Node, Python, Ruby) | ✅ Yes | ✅ Yes (via mise) |
29+
| **Homebrew packages** (git, ripgrep, etc.) | ❌ No | ✅ Yes |
30+
| **Oh My Zsh + plugins** | ❌ No | ✅ Yes |
31+
| **Shell configuration** | ❌ No | ✅ Yes |
32+
| **Git config** (user, aliases, ignores) | ❌ No | ✅ Yes |
33+
| **IDE settings** (VS Code, PhpStorm) | ❌ No | ✅ Yes |
34+
| **Mobile dev tools** (CocoaPods, Android SDK) | ❌ No | ✅ Yes |
35+
| **Security model** (secrets isolation) | ❌ No | ✅ Yes |
36+
| **Team consistency** (shared configs) | ❌ No | ✅ Yes |
37+
38+
**TL;DR:** Mise is one tool. OSA is an orchestrator that brings together mise + shell + package manager + IDE + security best practices into one unified setup experience.
39+
2040
## Tested Platforms
2141

2242
<ul>
@@ -28,50 +48,117 @@ OSA is a shell-first, interactive CLI tool that automates the tedious setup of d
2848

2949
## Quick Start
3050

31-
**Two ways to get started:**
32-
33-
### Option 1: Clone from GitHub (For Development)
51+
**Clone and run:**
3452

3553
```bash
3654
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
3755
cd ~/osa
3856
zsh ./osa-cli.zsh --interactive
3957
```
4058

41-
### Option 2: Install via Homebrew (Recommended)
59+
**Note:** If you get "permission denied", try: `chmod +x ./osa-cli.zsh && zsh ./osa-cli.zsh --interactive`
4260

61+
After setup completes, the `osa` command will be available globally from any directory:
4362
```bash
44-
brew tap VirtualizeLLC/homebrew-osa
45-
brew install osa
46-
osa --interactive
63+
osa --interactive # Works from anywhere
64+
osa --help # Try it out
4765
```
4866

4967
That's it. The CLI will guide you through the rest.
5068

51-
### First-Time Setup Steps
69+
### Setup Instructions by Platform
70+
71+
<table>
72+
<thead>
73+
<tr>
74+
<th>Platform</th>
75+
<th>Setup Command</th>
76+
<th>Dependencies</th>
77+
<th>Status</th>
78+
</tr>
79+
</thead>
80+
<tbody>
81+
<tr>
82+
<td><strong>macOS</strong></td>
83+
<td>
84+
<code>git clone https://github.com/VirtualizeLLC/osa.git ~/osa && cd ~/osa && brew bundle && zsh ./osa-cli.zsh --interactive</code>
85+
</td>
86+
<td>Git, Zsh, Homebrew</td>
87+
<td>✅ Fully Tested</td>
88+
</tr>
89+
<tr>
90+
<td><strong>Linux (Ubuntu/Debian)</strong></td>
91+
<td>
92+
<code>git clone https://github.com/VirtualizeLLC/osa.git ~/osa && cd ~/osa && sudo apt-get install -y git zsh jq && zsh ./osa-cli.zsh --interactive</code>
93+
</td>
94+
<td>Git, Zsh, jq</td>
95+
<td>✅ Supported</td>
96+
</tr>
97+
<tr>
98+
<td><strong>WSL 2 (Windows)</strong></td>
99+
<td>
100+
<code>git clone https://github.com/VirtualizeLLC/osa.git ~/osa && cd ~/osa && sudo apt-get install -y git zsh jq && zsh ./osa-cli.zsh --interactive</code>
101+
</td>
102+
<td>Git, Zsh, jq</td>
103+
<td>✅ Supported</td>
104+
</tr>
105+
<tr>
106+
<td><strong>Android (Termux)</strong></td>
107+
<td>
108+
<code>pkg install git zsh openssh && git clone https://github.com/VirtualizeLLC/osa.git ~/osa && cd ~/osa && zsh ./osa-cli.zsh --interactive</code>
109+
</td>
110+
<td>Git, Zsh, OpenSSH</td>
111+
<td>⚠️ Experimental</td>
112+
</tr>
113+
<tr>
114+
<td><strong>Windows (Native)</strong></td>
115+
<td>Use <strong>WSL 2</strong> (recommended) or see <a href="#windows-native-setup">manual setup</a></td>
116+
<td>WSL 2 or manual config</td>
117+
<td>⚠️ Limited</td>
118+
</tr>
119+
</tbody>
120+
</table>
121+
122+
### Detailed Setup by Platform
123+
124+
#### macOS
125+
```bash
126+
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
127+
cd ~/osa
128+
brew bundle # Install dependencies (optional but recommended)
129+
zsh ./osa-cli.zsh --interactive
130+
```
52131

53-
1. **Clone this repo**:
54-
```bash
55-
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
56-
cd ~/osa
57-
```
132+
#### Linux (Ubuntu/Debian)
133+
```bash
134+
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
135+
cd ~/osa
136+
sudo apt-get install -y git zsh jq # Install dependencies
137+
zsh ./osa-cli.zsh --interactive
138+
```
58139

59-
2. **Install dependencies** (optional but recommended):
60-
```bash
61-
brew bundle # Installs jq, git, zsh, and optional tools
62-
```
140+
#### WSL 2 (Windows Subsystem for Linux)
141+
```bash
142+
# In WSL terminal
143+
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
144+
cd ~/osa
145+
sudo apt-get install -y git zsh jq # Install dependencies
146+
zsh ./osa-cli.zsh --interactive
147+
```
63148

64-
3. **Make zsh your login shell** (if not already):
65-
```bash
66-
chsh -s $(which zsh)
67-
```
149+
#### Android (Termux)
150+
```bash
151+
# In Termux terminal
152+
pkg install git zsh openssh
153+
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
154+
cd ~/osa
155+
zsh ./osa-cli.zsh --interactive
156+
```
68157

69-
4. **Run the interactive setup**:
70-
```bash
71-
zsh ./osa-cli.zsh --interactive
72-
```
158+
#### Windows (Native)
159+
Use **WSL 2** for best experience (see WSL 2 section above).
73160

74-
5. **Restart your terminal** and you're done!
161+
For manual setup, see [Windows Native Setup](#windows-native-setup) section.
75162

76163
### Alternative Setup Methods
77164

@@ -116,6 +203,51 @@ zsh ./osa-cli.zsh --all
116203
- Rust (stable)
117204
- Deno, Elixir, Erlang (latest)
118205

206+
## About Mise
207+
208+
**[Mise](https://mise.jdx.dev/)** is a polyglot runtime manager that replaces nvm, rbenv, pyenv, jenv, and similar tools.
209+
210+
### Why Mise?
211+
212+
- ✅ **Single tool** for all languages (no more nvm + rbenv + pyenv juggling)
213+
- ✅ **Fast**: Cached, optimized binaries (much faster than building from source)
214+
- ✅ **Per-project versions**: Automatic switching via `.mise.toml` files
215+
- ✅ **Team consistency**: Everyone uses the same runtime versions
216+
- ✅ **Easy updates**: `mise install` from `.mise.toml`
217+
218+
### Quick Start with Mise
219+
220+
After OSA setup, mise is ready to use:
221+
222+
```bash
223+
# Install runtimes from .mise.toml
224+
mise install
225+
226+
# Check installed versions
227+
mise list
228+
229+
# Switch versions
230+
mise use node@20
231+
232+
# Show what's available
233+
mise list-all node
234+
```
235+
236+
### Per-Project Setup
237+
238+
Create `.mise.toml` in your project:
239+
240+
```toml
241+
[tools]
242+
node = "20.11.0"
243+
python = "3.12"
244+
ruby = "3.3.0"
245+
```
246+
247+
When you `cd` into the directory, mise automatically activates those versions. No more shell aliasing or version switching scripts!
248+
249+
**Learn more:** [Mise Documentation](https://mise.jdx.dev/) | [GitHub](https://github.com/jdx/mise)
250+
119251
## Security Model: Why It Matters
120252

121253
OSA's workspace-based approach is fundamentally different from traditional dotfile management:

‎configs/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,51 @@ A: We use `jq` to parse JSON configs. If it's not installed, run: `brew install
219219
**Q: Can I version control my config?**
220220
A: Absolutely! Commit your custom config to git and share it with your team.
221221

222+
### CocoaPods & Ruby Gem Installation Issues
223+
224+
**Q: Why do I get "readonly" errors when installing CocoaPods?**
225+
A: When `gem install cocoapods` runs, it tries to write to Ruby's gem directory. If you see permission errors:
226+
227+
```
228+
ERROR: While executing gem ... (Gem::FilePermissionError)
229+
You don't have write permissions
230+
```
231+
232+
**Solutions (in order of preference):**
233+
234+
1. **Use user-install mode** (automatic in OSA):
235+
```bash
236+
gem install cocoapods --user-install
237+
```
238+
This installs gems to `~/.gem` which is always writable.
239+
240+
2. **Set GEM_HOME** to a user directory:
241+
```bash
242+
export GEM_HOME="$HOME/.gem"
243+
export PATH="$GEM_HOME/bin:$PATH"
244+
gem install cocoapods
245+
```
246+
247+
3. **Use sudo** (last resort):
248+
```bash
249+
sudo gem install cocoapods
250+
```
251+
⚠️ Only use this if other methods fail. Installing gems as root is not recommended.
252+
253+
**Q: Why does CocoaPods need a specific Ruby version?**
254+
A: CocoaPods has Ruby version requirements:
255+
- **CocoaPods 1.14+**: Requires Ruby 3.0+
256+
- **CocoaPods 1.13**: Requires Ruby 2.7+
257+
- **CocoaPods 1.12**: Requires Ruby 2.7+
258+
259+
OSA handles version compatibility automatically and warns you if there's a mismatch.
260+
261+
**Q: Can I skip CocoaPods installation?**
262+
A: Yes, CocoaPods is optional. During interactive setup, answer "No" when asked. You can install it later manually:
263+
```bash
264+
./osa-cli.zsh --enable cocoapods --auto
265+
```
266+
222267
## Security
223268

224269
### Remote Configuration Security

‎osa-cli.zsh‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -558,6 +558,31 @@ interactive_setup() {
558558
exit 1
559559
fi
560560

561+
# macOS pre-flight check: Xcode Command Line Tools
562+
if [[ "$OSA_IS_MACOS" == "true" ]]; then
563+
if ! command -v xcode-select &>/dev/null || ! xcode-select -p &>/dev/null; then
564+
echo -e "${COLOR_YELLOW}⚠️ Xcode Command Line Tools not found${COLOR_RESET}"
565+
echo ""
566+
echo "Homebrew and many development tools require Xcode CLT."
567+
echo ""
568+
echo "Two ways to install:"
569+
echo ""
570+
echo " Option 1 (Easiest):"
571+
echo " ${COLOR_BOLD}xcode-select --install${COLOR_RESET}"
572+
echo ""
573+
echo " Option 2 (From Apple Developer):"
574+
echo " Visit: https://developer.apple.com/download/more/"
575+
echo " Search for 'Command Line Tools'"
576+
echo " Download and install (Apple login required)"
577+
echo ""
578+
579+
if ! ask_yes_no "Continue anyway?" "n"; then
580+
echo -e "${COLOR_RED}Setup cancelled.${COLOR_RESET}"
581+
return 1
582+
fi
583+
fi
584+
fi
585+
561586
echo -e "${COLOR_BOLD}Select components to install:${COLOR_RESET}\n"
562587

563588
# CRITICAL: Always include required components IN CORRECT ORDER
@@ -762,6 +787,21 @@ automated_setup() {
762787

763788
# Save the configuration for future runs
764789
save_config
790+
791+
# Auto-source the new shell configuration
792+
echo ""
793+
echo -e "${COLOR_CYAN}Sourcing your new shell configuration...${COLOR_RESET}"
794+
if [[ -f "$HOME/.zshrc" ]]; then
795+
source "$HOME/.zshrc"
796+
echo -e "${COLOR_GREEN}✨ Shell updated! You're ready to go.${COLOR_RESET}"
797+
fi
798+
799+
# Show next steps
800+
echo ""
801+
echo -e "${COLOR_BOLD}${COLOR_CYAN}Next steps:${COLOR_RESET}"
802+
echo " 1. Try it out: ${COLOR_BOLD}mise --version${COLOR_RESET}"
803+
echo " 2. Test in a new terminal (recommended): ${COLOR_BOLD}zsh${COLOR_RESET}"
804+
echo " 3. Happy coding! 🚀"
765805
}
766806

767807
# Show help

‎src/setup/install-cocoapods-interactive.zsh‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -199,18 +199,46 @@ install_cocoapods() {
199199
}
200200
}
201201

202-
# Install CocoaPods
202+
# Set up GEM_HOME to user directory to avoid permission issues
203+
# This ensures gem install writes to ~/.gem instead of system directories
204+
export GEM_HOME="$HOME/.gem"
205+
export PATH="$GEM_HOME/bin:$PATH"
206+
207+
# Create gem directories if they don't exist
208+
mkdir -p "$GEM_HOME/bin" "$GEM_HOME/specs" 2>/dev/null || true
209+
210+
# Install CocoaPods with --user-install flag and verbose error handling
203211
echo -e "${COLOR_CYAN}Installing CocoaPods ${COCOAPODS_VERSION}...${COLOR_RESET}"
204212
if [[ "$COCOAPODS_VERSION" == "latest" ]]; then
205-
gem install cocoapods || {
206-
echo -e "${COLOR_RED}✗${COLOR_RESET} Failed to install CocoaPods"
207-
return 1
208-
}
213+
if gem install cocoapods --user-install 2>&1; then
214+
echo -e "${COLOR_GREEN}✓${COLOR_RESET} CocoaPods installed successfully"
215+
else
216+
# Fallback to standard install if user-install fails
217+
echo -e "${COLOR_YELLOW}⚠${COLOR_RESET} Standard gem install attempt..."
218+
if gem install cocoapods 2>&1; then
219+
echo -e "${COLOR_GREEN}✓${COLOR_RESET} CocoaPods installed successfully"
220+
else
221+
echo -e "${COLOR_RED}✗${COLOR_RESET} Failed to install CocoaPods"
222+
echo -e "${COLOR_CYAN}→${COLOR_RESET} This usually means the gem directory doesn't have write permissions"
223+
echo -e "${COLOR_CYAN}→${COLOR_RESET} Try running: sudo gem install cocoapods"
224+
return 1
225+
fi
226+
fi
209227
else
210-
gem install cocoapods --version "${COCOAPODS_VERSION}" || {
211-
echo -e "${COLOR_RED}✗${COLOR_RESET} Failed to install CocoaPods ${COCOAPODS_VERSION}"
212-
return 1
213-
}
228+
if gem install cocoapods --version "${COCOAPODS_VERSION}" --user-install 2>&1; then
229+
echo -e "${COLOR_GREEN}✓${COLOR_RESET} CocoaPods ${COCOAPODS_VERSION} installed successfully"
230+
else
231+
# Fallback to standard install if user-install fails
232+
echo -e "${COLOR_YELLOW}⚠${COLOR_RESET} Standard gem install attempt..."
233+
if gem install cocoapods --version "${COCOAPODS_VERSION}" 2>&1; then
234+
echo -e "${COLOR_GREEN}✓${COLOR_RESET} CocoaPods ${COCOAPODS_VERSION} installed successfully"
235+
else
236+
echo -e "${COLOR_RED}✗${COLOR_RESET} Failed to install CocoaPods ${COCOAPODS_VERSION}"
237+
echo -e "${COLOR_CYAN}→${COLOR_RESET} This usually means the gem directory doesn't have write permissions"
238+
echo -e "${COLOR_CYAN}→${COLOR_RESET} Try running: sudo gem install cocoapods --version ${COCOAPODS_VERSION}"
239+
return 1
240+
fi
241+
fi
214242
fi
215243

216244
# Verify installation

0 commit comments

Comments
 (0)